Mandaire MCP Wire Contract v1.0.17

Owner: Surface layer

Canonical source: ~/openclaw/mandaire_mcp/server.py, auth_provider.py, core/mandaire/a2a/

Protocol version: 1.0.14

Spec URL: https://mandaire.org/spec/v1.0

Produced: 2026-05-20 (Surface first-session deliverable)

Supersedes: v0.1 (2026-05-18)

Revised: 2026-06-30 (v1.0.17: §4.1 + §4.2: context_card family envelope fields documented (card_id, mode, persisted, outcome, allowed_summary, withheld_topics, owner_approval_required, safe_to_send, wire_version); enforce mode behavior noted (shipped #151510). §15 context_card wire gap closed.)

Review dispatch targets:

• Product: semantic correctness of per-kind output shapes
• Inference: compute contract (confidence scoring, expectedness, calibration gaps)
• Judgment: pre-flight hook shape, safety tier gate enforcement

Change log: v1.0.16 → v1.0.17

Change log: v1.0.15 → v1.0.16

Change log: v1.0.14 → v1.0.15

Change log: v1.0.13 → v1.0.14

Change log: v1.0.12 → v1.0.13

Change log: v1.0.11 → v1.0.12

Change log: v1.0.10 → v1.0.11

Change log: v1.0.9 → v1.0.10

Change log: v1.0.8 → v1.0.9

Change log: v1.0.7 → v1.0.8

Change log: v1.0.5 → v1.0.6

Change log: v1.0.4 → v1.0.5

Change log: v1.0.3 → v1.0.4

Change log: v1.0.2 → v1.0.3

Change log: v1.0.1 → v1.0.2

Change log: v1.0 → v1.0.1

Change log: v0.1 → v1.0

1. Transport

2. Registered MCP Tools

8 tools registered (ADR-0021 CRUD split live as of 2026-06-06).

Super-tool watermark: >8 registered MCP tools = regression. PR-time check enforces this.

Grant tier → tool access (enforced at tools/list + server-side dispatch):

Scope (current vs planned):

• CURRENT_SCOPE = "mandaire", shim period. Refresh tokens scoped "mandaire" still work.
• CURRENT_SCOPE = "mandaire-v2", post-shim. Refresh tokens must be re-authorized to get "mandaire-v2". Bumping CURRENT_SCOPE starts the 24h window before the SELECT shim in mandaire() can be retired.

Annotation presets:

• _RO: readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False
• _WRITE_INTERNAL: readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=False

3. Request Envelope, mandaire()

3.1 Full JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "MandaireRequest",
  "type": "object",
  "properties": {
    "verb": {
      "type": "string",
      "enum": ["SELECT", "INSERT", "UPDATE", "DELETE", "READ", "GET", "QUERY", "CREATE", "ADD", "PATCH", "REMOVE"],
      "default": "SELECT",
      "description": "Operation verb. SELECT/READ/GET/QUERY are aliases. INSERT/CREATE/ADD are aliases. UPDATE/PATCH are aliases. DELETE/REMOVE are aliases."
    },
    "from_kind": {
      "type": ["string", "null"],
      "description": "The data domain to query. See §3.2 for full catalog."
    },
    "from_id": {
      "type": ["string", "null"],
      "description": "Canonical ID for direct-lookup path. UUID or integer string depending on from_kind."
    },
    "from_match": {
      "type": ["string", "null"],
      "description": "Free-text match string (SELECT only). Used for fuzzy name/topic matching."
    },
    "fields": {
      "type": ["array", "null"],
      "items": {"type": "string"},
      "description": "Field projections within from_kind. Behavior is from_kind-specific."
    },
    "payload": {
      "oneOf": [
        {"type": "object"},
        {"type": "array"},
        {"type": "null"}
      ],
      "description": "Write payload (INSERT/UPDATE/DELETE). Shape is from_kind-specific. See §5 for ai_observation schema."
    },
    "since": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "ISO 8601 UTC lower bound (inclusive). e.g. '2026-01-01T00:00:00Z'"
    },
    "until": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "ISO 8601 UTC upper bound (exclusive)."
    },
    "sources": {
      "type": ["array", "null"],
      "items": {"type": "string"},
      "description": "Source filter. Restricts which data sources contribute."
    },
    "filters": {
      "type": ["object", "null"],
      "description": "Pre-computation filters (SQL WHERE equivalent). Shape is from_kind-specific."
    },
    "having": {
      "type": ["object", "null"],
      "description": "Post-computation filters (SQL HAVING equivalent)."
    },
    "purpose": {
      "type": ["string", "null"],
      "description": "Intent of the call. Required for SENSITIVE and RESTRICTED from_kinds. Suggested values: preparing_for_meeting | drafting_reply | researching_history | evaluating_relationship | disambiguating | ai_writeback_from_conversation"
    },
    "context_note": {
      "type": ["string", "null"],
      "description": "Working hypothesis for retrieval bias. Steers semantic search."
    },
    "caller": {
      "type": ["object", "null"],
      "properties": {
        "who": {"type": "string"},
        "channel": {"type": "string"},
        "disclosure_mode": {
          "type": "string",
          "enum": ["direct", "relay", "delegated", "federated", "professional_update", "investment_discussion", "casual_chat", "medical_consultation", "legal_proceeding"],
          "description": "Maps to `context` axis of the 5-axis disclosure tuple. Unrecognized values default to hold (no policy match → hold per project_policy_schema_v0_1.md §Evaluation Order)."
        }
      },
      "description": "Caller context. Default: self/mirror mode (David's own room)."
    },
    "depth": {
      "type": "string",
      "enum": ["minimal", "standard", "deep", "exhaustive"],
      "default": "standard",
      "description": "Composition depth. deep/exhaustive on person/household/relationship escalates to SENSITIVE tier."
    },
    "format_hint": {
      "type": "string",
      "enum": ["auto", "prose", "structured", "both", "ui"],
      "default": "auto",
      "description": "Output format preference."
    },
    "max_chars": {
      "type": ["integer", "null"],
      "minimum": 1,
      "description": "Cap on rendered_text length."
    },
    "ask": {
      "type": ["string", "null"],
      "description": "Free-text question. No from_kind → recall fallback."
    }
  },
  "required": []
}

3.2 From_kind Catalog (v1.0.11, 96 catalog entries: 95 in _VALID_FROM_KINDS + ai_observation via alias map)

Identity contract: uuid is the stable entity identity across ER rebuilds. Integer entity_id is NOT invariant, it may rotate when entities are merged. Email/phone aliases are stable across rebuilds and recommended for cross-rebuild durability. Any cross-reference that must survive an ER merge must use uuid, not entity_id.

Status taxonomy: All 91 kinds in this catalog are SHIPPED (confirmed live handlers in mandaire_mcp/server.py). Deprecated kinds are documented in §3.2.2. Gated kinds (namespace reserved, handler pending) are marked with a GATED note in their catalog entry.

Live count note (App H2 #70277): Live _VALID_FROM_KINDS = 95 unique entries (96 in tuple, free duplicated at positions @7372 and @7401; Surface de-dup pending). The 4-kind gap between documented (91) and live (95) is aliases and potential undocumented kinds. SSOT rule: generate the advertised count from len(set(_VALID_FROM_KINDS)) at publish time, not hand-maintained.

Genetic/health data gate: Any from_kind returning genetic, genomic, or familial disease-risk data requires RESTRICTED tier review + explicit purpose declaration before deployment. No such kinds are currently active; this gate applies to future additions.

Core life-graph

Operating profile

Decisions + standing state

Composed surfaces

Communication surfaces

Activity / silence / commitments

Pattern detection

Pipeline / review

Dimension / pipeline graph

Enrichment + graph

Cognitive / input modeling

AI writeback

Free access (bearer secret links)

Health (RESTRICTED tier, audience_tier_max=1)

Finances (RESTRICTED tier, audience_tier_max=1)

Disclosure

Consent management

mandaire.dev namespace (v1.0 SHIPPED; dev_architecture_decision bumped v2.0 per Dev #64082)

Schemas: domains/dev/schemas/dev_.v1.json (dev_architecture_decision: dev_architecture_decision.v2.json). Storage: brain/dev.db. All reversibility_class values use canonical OS.md §5.29 enum (REVERSIBLE\|IRREVERSIBLE\|PARTIAL). dev_tech_debt is the only remaining gated kind (v0.2 wave).

New in v1.0.3

3.2.1 Aliases and Legacy Migration Pointers

These are accepted from_kind values that route to a canonical handler. Callers SHOULD use the canonical form. Aliases are supported indefinitely unless explicitly deprecated with a 90-day window per §14.1.

3.2.2 Deprecated Kinds

Deprecated from_kinds return a migration hint but remain in _VALID_FROM_KINDS until the deprecation window closes per §14.1 (90 days minimum).

4. Response Envelope

All responses use the same envelope. Error responses include the same metadata keys.

4.1 Full JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "MandaireResponse",
  "type": "object",
  "required": ["ok", "verb", "result", "rendered_text", "structured",
               "approval_required", "sources_used", "disclosure_applied",
               "absent_knowledge_caveats", "suggestions", "confidence",
               "signals", "cognitive_mode", "expectedness"],
  "properties": {
    "ok":                      {"type": "boolean"},
    "verb":                    {"type": "string"},
    "result":                  {"oneOf": [{"type": "object"}, {"type": "array"}, {"type": "null"}]},
    "rendered_text":           {"type": "string"},
    "structured":              {"oneOf": [{"type": "object"}, {"type": "array"}, {"type": "null"}]},
    "artifact_id":             {"type": ["string", "null"]},
    "approval_required":       {"type": "boolean"},
    "sources_used":            {"type": "array", "items": {"type": "string"}},
    "disclosure_applied": {
      "oneOf": [
        {
          "type": "array",
          "maxItems": 0,
          "description": "[], engine not engaged: Judgment did not run OR nothing withheld. Reserved meaning; do NOT use for populated results."
        },
        {
          "type": "object",
          "description": "Judgment ran. Object form = full Judgment engine evaluation result. CONVERGENCE NOTE (App M1 #70277): live code produces three shapes, (1) [] via _disclosure_state()-fallback paths, (2) this dict via _disclosure_state() @server.py:1581, (3) list-of-{field,withheld,reason|policy_tuple} via disclosure_demo/compose path @16885. Shapes (2) and (3) must converge to this object form before v0.1 PRODUCTION. Until then, renderers should handle all three gracefully.",
          "required": ["mode", "policy_version", "receiver_kind", "context"],
          "properties": {
            "mode":                {"type": "string", "enum": ["external", "internal", "relay", "direct"]},
            "policy_version":      {"type": "string", "description": "Disclosure policy schema version, e.g. '0.1'"},
            "receiver_kind":       {"type": "string", "enum": ["family", "friend", "manager", "report", "investor", "client", "public", "internal"]},
            "context":             {"type": "string", "description": "Interaction context from caller.disclosure_mode"},
            "gating_reason":       {"type": ["string", "null"]},
            "redacted_fields":     {"type": "array", "items": {"type": "string"}},
            "pii_classes_blocked": {"type": "array", "items": {"type": "string"}},
            "rule_id":             {"type": ["string", "null"]},
            "spillover_risk":      {"type": "number", "minimum": 0.0, "maximum": 1.0}
          }
        }
      ]
    },
    "absent_knowledge_caveats":{"type": "array", "items": {"type": "string"}},
    "suggestions":             {"type": "array"},
    "confidence":              {"type": "number", "minimum": 0.0, "maximum": 1.0},
    "signals":                 {"type": "array", "items": {"type": "string"}},
    "cognitive_mode": {
      "type": "object",
      "required": ["cycle", "tone", "preferred_kinds", "avoid", "hour_pt", "weekday", "iso_pt", "rendering_hint"],
      "properties": {
        "cycle":           {"type": "string"},
        "tone":            {"type": "string"},
        "preferred_kinds": {"type": "array", "items": {"type": "string"}},
        "avoid":           {"type": "array", "items": {"type": "string"}},
        "hour_pt":         {"type": "integer"},
        "weekday":         {"type": "string"},
        "iso_pt":          {"type": "string"},
        "rendering_hint":  {"type": "string"},
        "length":          {"type": "string", "description": "Rendering length policy compiled from briefing_style_by_mode.md (v1.0.1, optional, promoted to required in v1.1)"},
        "structure":       {"type": "string", "description": "Structure policy (prose | bullets | mixed)"},
        "decisions":       {"type": "string", "description": "Decision-surfacing policy for this mode"},
        "max_words":       {"type": "integer", "description": "Hard cap on rendered output word count"},
        "policy_source":   {"type": "string", "description": "Artifact path for the briefing_style_by_mode.md that produced this policy"},
        "user_mode_axes":  {"type": "object", "description": "6-axis input mode (WHAT/WHERE/WHEN/HOW/WHY/HOW_MUCH). WHEN populated from clock; other axes nullable hooks for from_kind=user_mode to fill."}
      }
    },
    "expectedness": {
      "type": "object",
      "required": ["score", "rationale", "surface_recommendation"],
      "properties": {
        "score":                  {"type": "number", "minimum": 0.0, "maximum": 1.0, "description": "Continuous novelty score; lower = more expected/routine"},
        "rationale":              {"type": "string"},
        "surface_recommendation": {"type": "string", "enum": [
          "SUPPRESS",
          "SUPPRESS_OBVIOUS_SURFACE_NOVEL",
          "SURFACE_NOVEL",
          "SURFACE_INTERESTING_IF_TRUE",
          "SURFACE_AS_IS"
        ]},
        "framing_hint":           {"type": "string", "description": "Optional renderer framing suggestion"}
      }
    },
    "_inference_origin":       {"type": "array", "items": {"type": "string"}, "description": "Optional. Field names in result whose value originated from inference.db (vs deterministic count or raw observed). Lets renderers distinguish LLM-derived fields from algorithmic ones. e.g. ['tie_strength', 'tie_trend', 'info_quality']"},
    "_valid_until":            {"type": ["string", "null"], "format": "date-time", "description": "v1.1-planned. For from_kinds returning inference claims: the validity window of the primary claim (from inference.db valid_until). NOT emitted live, _get_inference_claims does not SELECT valid_until. Null until handler ships."},
    "_prior_id":               {"type": ["integer", "null"], "description": "v1.1-planned. For inference SELECT envelopes: the prior_id chain pointer if this claim supersedes a previous one. NOT emitted at envelope level live, prior_id is per-claim only inside claims[]. Non-null enables renderers to display supersession history."},
    "judgment_applied": {
      "type": "object",
      "description": "v1.1-planned. Evidence that Judgment ran (AOR-2 audit trail / GDPR Article 30). NOT emitted live, Judgment integration not yet wired. When absent, disclosure_applied: [] is indistinguishable from Judgment not running; judgment_applied closes that gap.",
      "properties": {
        "version":        {"type": "string"},
        "decision":       {"type": "string", "enum": ["ALLOW", "HOLD", "WARN"]},
        "policy_version": {"type": "string"},
        "rule_id":        {"type": ["string", "null"], "description": "Matched rule_id from policy, or null if default-hold (no rule match)"}
      }
    },
    "error":                   {"type": "string", "description": "Present when ok=false only"},
    "hint":                    {"type": "string", "description": "Present with error, not on success"},
    "is_retrieved_content":    {"type": "boolean", "description": "true when from_kind ∈ {email, message, note, recall, file, image}"},
    "safety_warning":          {"type": "string", "description": "Present when safety.review() returns WARN"},
    "provenance": {
      "type": "object",
      "description": "Article 50 provenance triple",
      "properties": {
        "producer":  {"type": "string"},
        "channel":   {"type": "string"},
        "audience":  {"type": "string"},
        "ts":        {"type": "string", "format": "date-time"}
      }
    },
    "_compression": {
      "type": "object",
      "description": "Present when envelope was compressed by local Qwen 14B (>24,000 chars)",
      "properties": {
        "applied":          {"type": "boolean"},
        "original_chars":   {"type": "integer"},
        "compressed_chars": {"type": "integer"},
        "model":            {"type": "string"},
        "provider_used":    {"type": "string"},
        "fallback_used":    {"type": "boolean"}
      }
    },
    "card_id":                 {"type": ["string", "null"], "description": "context_card family only. Stable card ID; non-null only when from_kind=context_card_create AND persisted."},
    "mode":                    {"type": ["string", "null"], "description": "context_card family only. dry_run | preview | persist."},
    "persisted":               {"type": ["boolean", "null"], "description": "context_card family only. True when card written to context_cards (context_card_create)."},
    "outcome":                 {"type": ["string", "null"], "description": "context_card family only. PERMIT | DENY | WITHHOLD policy verdict."},
    "allowed_summary":         {"type": ["string", "null"], "description": "context_card family only. Prose of what the card would share; null on DENY."},
    "withheld_topics":         {"type": "array", "items": {"type": "string"}, "description": "context_card family only. Topics withheld per per-(R,T,C,S) policy; [] when all allowed."},
    "owner_approval_required": {"type": ["boolean", "null"], "description": "context_card family only. True if safe_to_send=False OR high-regret OR outcome != PERMIT."},
    "safe_to_send":            {"type": ["boolean", "null"], "description": "context_card family only. Fail-closed in enforce mode — any leak-class violation sets safe_version=null, outcome=DENY."},
    "wire_version":            {"type": "string", "description": "context_card family only. Wire protocol version, e.g. 'context_card/v0.2'."}
  }
}

4.2 Field semantics

4.3 Confidence scoring

Additive/subtractive from 0.40 base:

Inner result may carry its own confidence float; envelope takes max(computed, inner).

Two distinct namespaces (v1.0.6): source_kind and provenance are NOT the same field.

• source_kind, inference.db.inferences column. CHECK constraint: exactly {observed, derived_index, llm_inferred, user_authored}. Dominant value: derived_index (92.8% of 503 live rows, personality_v0.1_deterministic, probabilistic_pair_match.v0.1); llm_inferred 4.6%, observed 2.6%, user_authored 0. Values user_confirmed, ai_inference, auto_derived do not appear in inference.db and are blocked by constraint.

• provenance, envelope field emitted by each from_kind handler. The scorer reads result.get("provenance") (server.py:8616). Current handlers (5695, 5739) hardcode "ai_inference" regardless of underlying source_kind. Pending change (Inference #70261): handlers will emit per-source_kind provenance per the intent mapping below. Until that ships, every inference_claim/entity_state read receives −0.15.

Intent mapping (post-handler-fix, Inference + Surface co-ratified):

Dead wire values (user_confirmed, ai_inference, auto_derived): valid in scorer table for non-inference callers; handlers must never emit them for inference.db-sourced reads.

Multi-claim provenance aggregation rule (inference_claim from_kind, shipped commit 187de03):

inference_claim returns N claims, each carrying its own source_kind. The envelope-level provenance is a single value, a coarse trust signal. The handler resolves it by taking the most conservative (weakest) source_kind present across all returned claims:

One llm_inferred claim anywhere in the set pulls the entire envelope to −0.15. Rationale: the envelope confidence must never over-promise, conservative aggregation prevents a mostly-observed result from being reported at +0.20 when it contains a single LLM-derived claim.

Per-claim source_kind is preserved in result.claims[].source_kind for granular per-claim hedging by renderers that need finer resolution.

count=0 → provenance=None → 0.00 delta (neutral; no found=false signal on this handler, so no −0.30).

4.4 Compression

Large envelopes (>24,000 chars) are compressed by local Qwen 14B before returning. Exempt from_kinds (renderer needs IDs for follow-up calls): person, relationship, household, social_graph, entity_state, personality_profile, inference_claim, email, event, decision, compare_options, topic, context, file, outbound_style, user_mode, surfacing_score.

4.5 Provenance (Article 50)

Every envelope carries a provenance triple via attach_provenance() from core.mandaire.transport.provenance. Fail-open: attachment failure never blocks response.

4.6 Safety shim

Every external MCP response runs through safety.review() at _instrumented_call_tool.

S2/S3 HOLD suppression (Judgment integration, v0.1 PRODUCTION): When Judgment's disclosure-policy gate fires a HOLD on S2/S3 sensitivity topics (SENSITIVE/RESTRICTED from_kinds), the external response MUST equal the NO_INFO_RESPONSE template byte-for-byte, identical to a GENUINE_UNKNOWN response. blocked_reason and block_class MUST NOT appear in the external response for S2/S3 HOLD (they go to the audit log only). This preserves the 8-property pooling checklist Property 1: S2/S3 topic existence must be non-distinguishable from the wire.

The existing safety content HOLD (STANDARD/S1 topics, fired by safety.review()) MAY retain blocked_reason in the external response, the suppression requirement applies only to S2/S3 HOLD paths. See §12.4.

5. ai_observation, INSERT Payload Schema

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "AiObservationInsertPayload",
  "type": "object",
  "required": ["claim", "confidence", "trigger_reason"],
  "properties": {
    "claim": {
      "type": "string",
      "description": "The observation text. PII-detected: SSN/payment_card/password/api_key/otp patterns are blocked."
    },
    "confidence": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Confidence in the claim."
    },
    "trigger_reason": {
      "type": "string",
      "enum": ["user_direct_statement", "ai_synthesis", "nil_result_writeback", "user_confirmed_prior"],
      "description": "Why this observation is being written."
    },
    "claim_tier": {
      "type": "string",
      "enum": ["factual", "behavioral", "preference", "preference_negative", "boundary"],
      "description": "Claim classification tier."
    },
    "entity_refs": {
      "type": "array",
      "items": {"type": "object"},
      "description": "Entity references for cross-linking to people.db. Each item: {name?, email?, phone?, uuid?, entity_id?}. If both uuid and entity_id supplied, uuid wins. Integer entity_id is best-effort resolution-time and may rotate across ER rebuilds. Email/phone aliases are stable across rebuilds and recommended for cross-rebuild durability."
    },
    "evidence_refs": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Source references supporting the claim."
    },
    "writeback_slot_id": {
      "type": ["string", "null"],
      "description": "If filling a nil-result slot, the slot ID from open_writeback_slots."
    },
    "property": {
      "type": ["string", "null"],
      "description": "Property name the claim is about (e.g. 'relationship_quality', 'preference_food')."
    },
    "subject_kind": {
      "type": ["string", "null"],
      "description": "Subject type: person | relationship | self | topic"
    },
    "subject_key": {
      "type": ["string", "null"],
      "description": "UUID of the subject entity (for person/relationship subjects)."
    }
  }
}

INSERT response (ai_observation):

{
  "ok": true,
  "verb": "INSERT",
  "result": {
    "id": "<integer inference.db row id>",
    "kind_stored": "AI_OBSERVATION",
    "tier": "high | medium | low",
    "user_visible": "<boolean: confidence >= 0.65>",
    "claim_tier": "<string>",
    "claim_source": "<string>",
    "source_attribution": "<string>",
    "pending_review_until": "<ISO 8601 or null>",
    "entity_resolution_status": "<object>",
    "dedup": "<boolean: true if this is a duplicate of existing active row>",
    "claim_source_source": "<string, classifier that produced claim_source>",
    "claim_type_source": "<string, classifier that produced the claim type/tier>",
    "verification_state": "<string, e.g. 'pending_review' | 'verified' | 'rejected'>",
    "claim_signature": "<string, dedup hash: sha256(claim_text + affects); present on both new and dedup rows>"
  },
  "artifact_id": "<inference.db row id as string>"
}

Constraints:

• purpose required (e.g. ai_writeback_from_conversation). Declared at the request envelope level (mandaire(..., purpose="...")), not inside the INSERT payload, the server reads it from the outer call args.
• Cross-user writeback blocked in v1.0 (single-tenant)
• Double-write guard: same claim_signature + active = dedup, returns existing_id with dedup=true
• classifier_version = mcp_ai_observation_v0.1 stamped automatically

SELECT ai_observation:

mandaire(verb="SELECT", from_kind="ai_observation", from_match="<query>", filters={"limit": 20})

Returns array of inference rows matching the query via recall_search.

6. decision, SELECT Schema (Audit Click-Through)

mandaire(verb="SELECT", from_kind="decision", from_id="<audit_ref_uuid>")

Output:

{
  "ok": true,
  "verb": "SELECT",
  "result": {
    "from_kind": "decision",
    "audit_ref": "<uuid>",
    "found": true,
    "evaluations": [
      {
        "decision": "<text>",
        "recipient": "<name>",
        "decision_date": "<ISO 8601>",
        "confidence": 0.85,
        "source_kind": "user_authored",
        "evidence_refs": []
      }
    ]
  }
}

If from_id not provided, returns recent decisions list (same as from_kind=recent_decisions).

7. situation_brief, SELECT Schema

Required: from_match (or from_id / ask) containing the topic string.

mandaire(
  verb="SELECT",
  from_kind="situation_brief",
  from_match="tesla roof leak",
  filters={"detail": "standard"}
)

filters.detail values:

Output (result field):

{
  "title": "<situation title>",
  "status": "active_unresolved | resolved | not_found | unknown",
  "confidence": 0.85,
  "signals": ["source: analysis_situation_lookup (2026-05-19)"],
  "key_facts": [
    {
      "claim": "<fact text, max 200 chars>",
      "confidence": 0.9,
      "source_kind": "user_authored | observed | ai_inference",
      "source_refs": ["<source identifier>"]
    }
  ],
  "open_items": [
    {"item": "<text>", "priority": "high | medium | low"}
  ],
  "recent_events": [
    {"ts": "<ISO 8601>", "event": "<text, max 100 chars>", "source": "<source>"}
  ],
  "key_people": [
    {"name": "<name>", "role": "<role>", "uuid": "<stable uuid or null>", "entity_id": "<integer, best-effort, may rotate across ER rebuilds>"}
  ],
  "suggested_next_action": "<text>",
  "absent_knowledge_caveats": ["<caveat>"],
  "disclosure_applied": [],
  "_detail_level": "standard",
  "_version": "v0.2"
}

Primary path: Analysis situation_lookup() (situations.db, ~200ms warm). Falls back to pre-built context doc (topic_corpus), then recall_search (may be 8-15s cold if SentenceTransformer not warm).

Sources: analysis_situation_lookup > topic_corpus > recall

Suggestions always included:

[
  {"verb": "SELECT", "from_kind": "situation_brief", "from_match": "<topic>", "filters": {"detail": "full"}},
  {"verb": "SELECT", "from_kind": "context", "from_match": "<topic>"}
]

8. catch_me_up, SELECT Schema

mandaire(verb="SELECT", from_kind="catch_me_up")

Optional filters:

• filters.include_silence=true: include outbound_silence + followup_due (adds ~100-300ms)
• filters.decisions_limit=: cap recent_decisions (default 8)
• filters.event_days=: upcoming_events lookahead in days (default 7)
• filters.threads_limit=: live_threads count (default 15)
• filters.mailing_lists_limit=: live_mailing_lists count (default 10)

Output (result field):

{
  "ok": true,
  "version": "v0.2.2-2026-05-15-commitment-resolution",
  "live_tasks": [
    {"title": "<task>", "status": "<status>", "tags": [], "deadline": "<ISO 8601 or null>"}
  ],
  "filtered_out_stale_tasks": {
    "count": 2,
    "reason": "deadline_passed or likely_resolved (corpus evidence)",
    "items": []
  },
  "recent_drifts": [],
  "active_threads": {},
  "recent_decisions": [],
  "upcoming_events": [],
  "outbound_silence": [],
  "followup_due": [],
  "open_commitments_outbound": [],
  "open_commitments_inbound": [],
  "recently_resolved_commitments": [],
  "live_threads": [
    {
      "entity_id": "<uuid>",
      "name": "<name>",
      "channels": [],
      "decay_score": 0.85,
      "last_contact": "<ISO 8601>"
    }
  ],
  "live_mailing_lists": [],
  "stale_filter_metric": {
    "total_tasks_in_pending": 10,
    "live_count": 8,
    "stale_count": 2
  },
  "cache_hit": false
}

Cache: 5-minute TTL (write-invalidation stamp). cache_hit=true when cache served.

Sources: pending_tasks, comms, topic_corpus, calendar, task_resolution_v0_2, commitments_v0_1, active_threads_decay_v0_2, people_aliases

Note for renderer: Narrate with confidence markers (CONFIRMED / OBSERVED / STALE / GAP).

9. entity_lookup (via from_kind=person), Output Schema

Reached via from_kind=person with from_match=.

Input:

mandaire(verb="SELECT", from_kind="person", from_match="Bala", purpose="researching_history")

Candidate list (within result):

{
  "found": true,
  "candidates": [
    {
      "entity_id": 10522,
      "name": "Balaji T Kuppuswamy",
      "uuid": "<uuid>",
      "type": "person | org",
      "has_profile": true,
      "interactions": 548,
      "sources": ["gmail", "imessage"]
    }
  ],
  "interaction_total": 548
}

Resolution precedence:

1. Exact email match (aliases.alias_type='email')

2. Exact phone match (aliases.alias_type='phone', normalized)

3. Exact name match

4. Multi-token LIKE match

5. Prefix LIKE match (single token ≥3 chars)

6. name_variant alias match

7. Contact-tagged entities win ties at every preceding step, an entity with a contact tag ranks above an untagged entity at the same precedence level.

Merged-entity guard: Rows with name.startswith("[MERGED") or notes containing "merged_into" are excluded from candidates.

Identity contract: uuid is the stable identity; entity_id (integer) is NOT invariant across merges.

10. Auth

10.1 Required headers (MCP/HTTP)

10.2 OAuth 2.1 + PKCE flow

1. Discovery:  GET {issuer}/.well-known/openid-configuration
2. DCR:        POST {issuer}/oauth/register → {client_id, client_secret}
3. Authorize:  GET {issuer}/oauth/authorize?...&code_challenge=...&code_challenge_method=S256
               (Authelia SSO gates this; code prefix: "ac_", TTL: 600s)
4. Exchange:   POST {issuer}/oauth/token (grant_type=authorization_code)
               → {"access_token": "at_...", "expires_in": 86400, "refresh_token": "rt_..."}
5. Refresh:    POST {issuer}/oauth/token (grant_type=refresh_token)
6. Revoke:     POST {issuer}/oauth/revoke

10.3 Token TTLs

10.4 Scope

Valid scopes: mandaire (default, shim period), mandaire-v2 (post-shim). Scope bump triggers re-consent cycle for all existing clients.

Incremental scope consent (ADR-0199): a client presenting a token that is missing the current required scope is rejected with an explicit re-consent error rather than a silent downgrade. The client must re-run the consent flow to acquire the elevated scope; partial-scope tokens never silently grant reduced access.

10.5 Machine token (M2M, ADR-0139 B3)

For headless agents needing a JWT without a user OAuth flow:

POST /auth/machine/token
Content-Type: application/json
{"grant_type": "client_credentials", "client_id": "<id>", "client_secret": "<secret>"}

→ {"access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 3600}

JWT issuer: https://mcp.mandaire.app. Algorithm: ES256. Valid for 1h (not 24h).

10.6 JWKS endpoint (ADR-0139 B1)

Public key for JWT validation:

GET /.well-known/jwks.json
→ {"keys": [{"kty": "EC", "crv": "P-256", "kid": "...", "x": "...", "y": "..."}]}

Callers SHOULD cache the JWKS for the JWT's TTL; re-fetch on kid mismatch.

10.7 SDK endpoint, agent-auth (ADR-0141 S-O5, internal only)

Privileged full-fidelity read endpoint for trusted internal agents (Chief, Briefing, david-cli):

GET  /sdk/v1/select      (port 8765, tailnet-only; NOT exposed externally)
POST /sdk/v1/write       (symmetric with select; same mTLS+CN gate)
POST /sdk/v1/signal      (control-plane signal, ADR-0233 D1)
X-Mandaire-Agent-CN: chief    ← set by nginx mTLS frontend on port 8768

/sdk/v1/signal (ADR-0233): cross-VM control-plane signal channel, from_kind-discriminated. Same mTLS + CN gate; CN allowlist defaults to mnd-app-david (env MANDAIRE_SDK_SIGNAL_CN_ALLOWLIST, or pattern ^mnd-app-[a-z0-9-]+$). Allowed kinds default to diagnostic (env MANDAIRE_SDK_SIGNAL_KINDS). Not a data-read path; carries diagnostic / control signals only.

• CN absent → 403. CN not in {chief, briefing, david-cli} → 403.
• Returns full-fidelity mandaire_read response (disclosure-axis fields stripped before response).
• Port 8768 nginx mTLS frontend: pending Mandaire CA bootstrap (David at terminal on mnd-infra). Per-agent leaf certs required: chief, briefing, david-cli.
• Until port 8768 is live, internal agents may call port 8765 directly with X-Mandaire-Agent-CN set (tailnet-only; no mTLS enforcement until CA is up).

10.8 SDK signal endpoint: control-plane signals (ADR-0233 D1, internal only)

Cross-VM diagnostic and feedback endpoint for mnd-app-side principals (SDK agents):

POST /sdk/v1/signal       (port 8765, tailnet-only; NOT exposed externally)
Content-Type: application/json
X-Mandaire-Agent-CN: mnd-app-david    ← set by nginx mTLS frontend

Body: {"from_kind": "diagnostic", "payload": {...}}

→ {"status": "recorded", "from_kind": "diagnostic"}

CN gate: Must match pattern mnd-app-[a-z0-9][a-z0-9-]* (or explicit MANDAIRE_SDK_SIGNAL_CN_ALLOWLIST env list). CN absent or non-matching → 403.

from_kind discriminator: Only diagnostic permitted by default. Expandable via MANDAIRE_SDK_SIGNAL_KINDS env (comma-separated). Unknown kind → 400.

Rationale (ADR-0233): Separates cross-VM control-plane signals (health probes, telemetry) from the data plane (/sdk/v1/select). Avoids overloading the SELECT endpoint with write/signal semantics. Single endpoint, from_kind-discriminated, so future signal kinds extend without new routes.

10.9 Requester key discovery (SEC-070 D2)

Publicly-discoverable Ed25519 signing key for cross-tenant request authentication (ADR-0224 prerequisite):

GET /.well-known/mandaire-requester-key.json    (no auth, public)

→ HTTP 200 + Cache-Control: public, max-age=3600
{
  "kty": "OKP",
  "crv": "Ed25519",
  "use": "sig",
  "kid": "<key-id>",
  "x": "<base64url-encoded public key>"
}

→ HTTP 404 when no key has been generated yet (OS D1 prerequisite not met)

Purpose: Cross-tenant peers resolve this endpoint to verify that incoming request payloads were signed by this Mandaire instance. Used by the five ADR-0224 cross-user verbs (request_context, offer_context, evaluate_disclosure, claim_context, acknowledge_disclosure); those verbs are not yet implemented (gated on Architecture layer-3 authorization).

Key lifecycle: OS layer generates and rotates key material; Surface reads and serves the current JWK file. kid is derived from a SHA-256 fingerprint of the public key (first 16 hex chars). Cache-Control of 1h prevents stale serving during rotation.

Live: https://mcp.mandaire.com/.well-known/mandaire-requester-key.json and https://mcp.mandaire.app/.well-known/mandaire-requester-key.json

11. Error Codes

11.1 MCP-level errors (HTTP status)

11.2 Application-level errors (ok=false in envelope)

block_class field (Judgment integration, v0.1 PRODUCTION): Error envelopes include block_class (string) when Judgment is wired. Values: "safety_content" | "disclosure_policy" | "safety_tier_gate". For S2/S3 disclosure_policy blocks, block_class goes to audit log only, NOT returned to the external caller.

11.3 A2A error codes

12. Safety Tier Gate (R2)

Applied at mandaire() entry, after verb validation, before any handler runs.

12.1 Tiers

SSOT gate discipline: The gate implementation MUST derive RESTRICTED/SENSITIVE/STANDARD tier from the tier column in §3.2, not from a hardcoded enumeration of the table above. §3.2 is authoritative; §12.1 is a human-readable summary. Any divergence between them is a spec-publishing error, §3.2 wins.

12.2 Depth-conditional escalation

person, household, relationship at depth="deep" or depth="exhaustive" → treated as SENSITIVE regardless of catalog tier.

12.3 Purpose check

Presence-only check. Not validated against an enum. Suggested values: preparing_for_meeting, drafting_reply, researching_history, evaluating_relationship, disambiguating, ai_writeback_from_conversation.

12.4 Judgment disclosure-policy gate (v0.1 PRODUCTION, forward design)

Judgment's gate fires pre-fetch (before any handler runs). This is distinct from the safety.review() shim (§4.6) which fires post-handler. These are different failure modes with different caller remediation paths.

block_class enum, appears in error envelopes when Judgment is wired:

S2/S3 HOLD external response: byte-equal to NO_INFO_RESPONSE template (see §4.6 S2/S3 suppression note). block_class and blocked_reason go to audit log only, NOT returned to the external caller. Existence of S2/S3 content must be non-distinguishable from GENUINE_UNKNOWN on the wire.

Error envelope shape for Judgment-integrated blocks:

Non-S2/S3 blocks (safety_tier_gate + non-sensitive disclosure_policy):

{
  "ok": false,
  "error": "response blocked by disclosure policy",
  "block_class": "disclosure_policy",
  "hint": "Provide additional purpose or authorization context.",
  "disclosure_applied": []
}

S2/S3 disclosure_policy HOLD, block_class and blocked_reason OMITTED from external response (audit log only); caller cannot distinguish from GENUINE_UNKNOWN:

{
  "ok": false,
  "error": "response blocked by disclosure policy",
  "disclosure_applied": []
}

13. A2A Protocol

Endpoint: https://research.mandaire.com/a2a

Version: 0.1.0

Wire owner: Surface (absorbed from Research at activation)

13.1 Endpoints

13.2 Request envelope

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "skill": "research.<skill_id>",
    "message": {"parts": [{"kind": "text", "text": "..."}]},
    "metadata": {"limit": 8, "mode": "both"}
  },
  "id": "<caller-generated id>"
}

Required headers: Authorization: Bearer

Optional: X-A2A-Trace-Id, X-A2A-Parent-Trace, X-A2A-Hop-Count, X-Mandaire-Caller

13.3 Registered skills

13.4 Auth

v0.1 (active): Shared bearer secret at ~/openclaw/Brain/credentials/a2a_research_v01.secret. Sufficient because all live peers are internal fleet agents on the same trust boundary.

v0.4 (condition-gated, not date-scheduled): OAuth 2.1 client_credentials via Authelia (https://auth.mandaire.com/api/oidc/token). Scopes: research:read, research:write (Research-owned); inference:read (Inference-owned). The flip condition is: admit a genuinely external / untrusted peer, OR the disclosure engine reaches ENFORCEMENT for cross-agent callers. When either fires, OAuth enrollment precedes bearer decommission; no silent rotation. Confirmed by Research 2026-06-13.

13.5 Per-Skill Wire Reference

All skills use the §13.2 request envelope. This section documents params.message.parts[].text (the query input) and params.metadata fields per live skill, plus the response shape. Stub skills return {"status": "not_yet_implemented", "skill": "<id>"}.

research.recall_search

• Text: query string (required)
• Metadata: limit int default=8; mode "both"|"fts"|"semantic" default="both"
• Response: {"status", "query", "mode", "limit", "elapsed_s", "output": "<recall output, max 20 000 chars>", "cost_class": "free"}

research.entity_lookup

• Text: name, email, or phone substring to search (required)
• Metadata: none
• Response: {"status", "query", "match_count", "results": [{"id", "name", "type", "company", "title", "current_role", "current_company", "web_bio" (≤300 chars), "updated_at"}], "elapsed_s", "cost_class": "free"}. Returns up to 10 matches ranked by source_count.

research.web_enrich

• Text: entity name (required)
• Metadata: timeout_s int default=180
• Response: {"status", "entity", "elapsed_s", "output": "<enrichment stdout, max 20 000 chars>", "cost_class": "claude_sonnet"}. Writes to web_enrichment.db as a side-effect.

research.inferred_asset_query

• Text: subject/topic filter substring (optional; empty = most-recent across all assets)
• Metadata: asset "web_enrichment"|"observations"|"all" default="all"; limit 1-50 default=10
• Response: {"status", "query", "asset", "web_enrichment": [{entity_name, summary (≤400), current_role, company, confidence, queried_at}], "observations": [{source, severity, topic_key, summary (≤400), created_at}], "elapsed_s", "cost_class": "free"}. Keys present only for requested asset(s).

inference.claim_lookup

• Text: subject_key or substring (e.g. "email:[email protected]", "candidate:<uuid>", "self:...") (required)
• Metadata: limit 1-100 default=20; as_of ISO-ts optional (valid-time replay)
• Response: lookup_claims() output — active (non-superseded, non-evicted) claims for the subject. Shape: {"status", "subject", "claims": [{"id", "subject_key", "property", "value", "confidence", "source", "asserted_at", "valid_from", "evidence_refs"}], "count", "elapsed_s"}.

enrichment.coverage_check

• Text: not used
• Metadata: none
• Response: {"status": "ok", "total", "pct_with_summary", "pct_stale_90d", "pct_no_citations", "pct_with_uuid", "pct_contaminated", "elapsed_s", "cost_class": "free"}. All pct_* fields are 0–100 floats rounded to 1 decimal.

enrichment.enrich_entity

• Text: entity name (required)
• Metadata: force bool default=false (re-enrich even if recently enriched); timeout_s int default=180
• Response: {"status", "entity", "force", "elapsed_s", "output" (max 20 000 chars), "cost_class": "claude_sonnet"}. Writes to web_enrichment.db.

enrichment.freshness_sweep

• Text: not used
• Metadata: limit 1-50 default=10 (max entities to re-enrich); refresh_days int default=90 (staleness threshold); confirm_cost "yes" required when limit > 20
• Response: {"status", "limit", "refresh_days", "elapsed_s", "output" (max 20 000 chars), "cost_class": "claude_sonnet × ≤N"}. When limit>20 and confirm_cost != "yes": {"status": "cost_gate", "error": "...", "cost_class": "..."}.

14. Versioning Policy

14.1 Version bump rules

14.2 Guarantees

• No silent breaking changes. All wire changes require a spec version bump.
• Deprecated from_kinds remain in _VALID_FROM_KINDS for ≥90 days with deprecation notice in server_status output.
• Spec URL always points to the current stable version. Previous versions archived at /spec/v.M/.

14.3 Current spec URL

https://mandaire.org/spec/v1.0 (hosted by nginx; Surface owns keeping it in sync with this doc).

15. Open Items (Forward Design)

Appendix A: Telemetry Schema

Every call recorded to ~/openclaw/brain/mcp_telemetry.db:

tool_calls(
  id                           INTEGER PRIMARY KEY,
  ts_utc                       TEXT,
  request_id                   TEXT,
  client_id                    TEXT,
  principal                    TEXT,
  tool_name                    TEXT,
  args_json                    TEXT,      -- truncated at 2000 chars
  args_size_bytes              INTEGER,
  latency_ms                   INTEGER,
  status                       TEXT,      -- 'ok' | 'error' | 'empty'
  error_class                  TEXT,
  error_message                TEXT,      -- truncated at 500 chars
  result_size_bytes            INTEGER,
  result_summary               TEXT,
  disclosure_applied_populated INTEGER,   -- 1=non-stub, 0=stub, NULL=pre-migration
  safety_review_latency_ms     INTEGER,
  cache_hit                    INTEGER,
  source_kind                  TEXT,
  confidence_score             REAL,
  inference_ids_json           TEXT
)

Safety review SLO: p99 < 10ms.

Spec produced by Surface (Mandaire) 2026-05-20. Dispatch targets: Product (§7 semantic shapes), Inference (§4.3 confidence contract + §15 confidence_breakdown), Judgment (§11 safety tier gate + §12 pre-flight hook shape).