phaedo-mcp 0.2.1 → 0.3.0

package/NOTICE

@@ -0,0 +1,17 @@
+Phaedo
+Copyright 2026 Phaedo Labs, Inc.
+
+This product includes software developed by Phaedo Labs, Inc. (https://phaedo.so),
+licensed under the Apache License, Version 2.0.
+
+"Phaedo" and the Phaedo logo are trademarks of Phaedo Labs, Inc. The Apache License,
+Version 2.0 grants no trademark rights (Apache-2.0 §6); see TRADEMARKS for the brand
+policy and permitted nominative use.
+
+----------------------------------------------------------------------
+Third-party components (not redistributed in this package)
+----------------------------------------------------------------------
+The reference browser extension vendors @mlc-ai/web-llm (Apache-2.0). That bundle
+is NOT included in this npm package or the public repository (it is a gitignored
+build artifact). If/when the extension is distributed, the @mlc-ai/web-llm
+LICENSE and NOTICE travel with it.

package/README.md

@@ -1,9 +1,12 @@
-# Phaedo MCP server — Phase 1 (push injection)
+# Phaedo MCP server (`phaedo-mcp`)
 
-A local [MCP](https://modelcontextprotocol.io) server that exposes your Phaedo
-cognitive-fingerprint **projection** to any MCP client (Claude Desktop, Claude
-Code, Cursor, agent frameworks) — so the assistant responds in your style
-without the Chrome extension. One integration, every MCP client.
+A local [MCP](https://modelcontextprotocol.io) server that brings your Phaedo
+cognitive fingerprint to any MCP client (Claude Desktop, Claude Code, Cursor,
+agent frameworks) — no Chrome extension needed. It injects your fingerprint
+**projection** so the assistant responds in your style, and adds **consultation**
+(decision/risk signals), **real-time escalation** to your paired phone for a live
+approve / deny / modify on a blocking decision, and **act-as-me** learning from
+your outcome marks. One integration, every MCP client.
 
 Implements `docs/protocol/mcp-binding.md` §3.1:
 
@@ -17,12 +20,24 @@ Implements `docs/protocol/mcp-binding.md` §3.1:
 | tool | `phaedo_escalate` | run the consult and, on a blocking signal (`escalate`, or a consequential `clarify`), wake the subject's paired device for a live **approve / deny / modify**; returns a `request_id` (non-blocking). Safe default on no answer: **hold**. |
 | tool | `phaedo_escalation_status` | poll an escalation by `request_id`; on resolution records the subject's live decision as the §10.6 outcome automatically (a real-time approve/deny is the strongest act-as-me signal). |
 | tool | `phaedo_record_outcome` | §10.6 — record what the SUBJECT decided about a consulted action (`approved`/`rejected`/`modified`/`unknown`). A `rejected`/`modified` outcome teaches the **act-as-me** channel (how the user wants delegated work handled). |
+| tool | `phaedo_sign_mandate` | §8.3 — ask the subject to **sign** an AP2 Intent Mandate built from their standing authorizations (a verifiable payment credential). Deposits the request and returns a `request_id` + the unsigned mandate (non-blocking). The subject signs on their phone in the Secure Enclave, or declines. |
+| tool | `phaedo_sign_status` | poll a `phaedo_sign_mandate` request by `request_id` (+ the returned mandate); returns the mandate carrying a **verified** signature once signed, `refused` if declined, or pending/expired. The signature is checked against the subject's published signing key before it is returned. |
 
 The projection is rendered by the **same** `context-block.js` the extension
 injects, so MCP injection is byte-identical to web injection.
 
 ## Status
 
+The phases below track the **fingerprint source** (how the server obtains the
+fingerprint). The consultation, real-time escalation, act-as-me / delegation, and
+receipts-audit surfaces (the tools table above) shipped on top of these across the
+**0.2.x** line, and the §8.3 signing pair in **0.3.0** — see `CHANGELOG.md`.
+
+> **Install 0.3.0 or later.** 0.2.0, 0.2.1 and 0.2.2 were published with three
+> modules missing from the package, so they exit with `ERR_MODULE_NOT_FOUND`
+> instead of starting. 0.3.0 is the first working release since 0.1.1, and
+> `test-package-closure.mjs` now boots the packed tarball in CI.
+
 - **Phase 1a (this cut):** reads the fingerprint from a local JSON file (see
   *Fingerprint source*). Lets injection work in a real client today, no crypto.
 - **Phase 1b-i (done):** the spec-faithful key boundary — authorize → pull
@@ -50,8 +65,10 @@ injects, so MCP injection is byte-identical to web injection.
   `../docs/roadmap/mcp-revocable-approval-plan.md`. Phone-gated unlock stays a
   deferred enterprise mode behind a config flag.
 
-**Injection-only.** MCP never returns the conversation, so there is **no
-capture** here (binding §5) — your fingerprint does not learn from MCP sessions.
+**No conversation capture.** MCP never returns the conversation, so your
+fingerprint does not learn from MCP sessions (binding §5). (Consultation,
+escalation, and `phaedo_record_outcome` shape and record *decisions*, but none
+capture conversation text into the fingerprint.)
 Local **stdio** only; **standard** mode only (enhanced-privacy/Stained-Glass and
 remote HTTP/SSE are out of this cut).
 
@@ -181,6 +198,31 @@ fully automatic depending on the client:
 
   Every chat in that project then injects automatically.
 
+### Capture from Claude Code / Cowork (optional)
+
+`npm run setup:code-hook` also installs a **SessionEnd** hook that reads the just-ended
+transcript locally, derives behavioral signals (deterministic pattern detectors), and
+deposits an encrypted **signal delta** to the owner — so your Claude Code / Cowork usage
+feeds the fingerprint, not just the browser. The transcript is counted and **discarded**
+(nothing but signal names + integers leaves the machine); a paired phone/extension drains
+and merges it.
+
+Optionally enrich the deterministic detectors with a **local model** (opt-in) — it
+classifies the messages the regexes miss, against the same taxonomy, and feeds the same
+counters (so re-fires stay idempotent). Any **Ollama / OpenAI-compatible** endpoint works:
+
+```
+ollama pull llama3.1:8b          # or any local model
+npm run setup:capture-model -- llama3.1:8b     # writes ~/.phaedo-mcp/capture-model.json
+npm run setup:capture-model -- off             # turn it back off
+```
+
+Point it elsewhere with `--capture-url <url>` (default `http://localhost:11434`). It's
+fail-safe: endpoint down/slow/garbage → the hook silently falls back to the deterministic
+detectors, and a model call can never break or stall a session (30s budget, hook always
+exits 0). Prefer the `setup:capture-model` config file over an env var — the file reaches
+Dock-launched Claude Desktop, a shell `export` does not.
+
 ## Consult at decision points (`phaedo_consult`, §10)
 
 Beyond injecting style, an agent can **ask the fingerprint how the user's pattern
@@ -303,7 +345,7 @@ The installer writes exactly this. The minimal **paired** entry needs no `env`
   "mcpServers": {
     "phaedo": {
       "command": "/absolute/path/to/node",
-      "args": ["/Users/galavoxx/phaedo/mcp/server.js"]
+      "args": ["/absolute/path/to/phaedo/mcp/server.js"]
     }
   }
 }
@@ -315,5 +357,5 @@ chat and prepend the returned `projection`.
 
 **Claude Code** — `.mcp.json` in a project, or:
 ```bash
-claude mcp add phaedo -- /absolute/path/to/node /Users/galavoxx/phaedo/mcp/server.js
+claude mcp add phaedo -- /absolute/path/to/node /absolute/path/to/phaedo/mcp/server.js
 ```

package/action-binding.js

@@ -0,0 +1,82 @@
+// §10.2 `action_binding` — tying a consultation to the call it claims to describe.
+//
+// THE PROBLEM. Every field the resolver decides on lives in `action_descriptor`,
+// and every one of them is authored by the agent being gated: domain, magnitude,
+// reversible, amount, summary. A standing authorization like
+//
+//     { match: { domains: ["writing"], magnitude_max: "medium", reversible: true },
+//       effect: "autoproceed" }
+//
+// therefore fires on whatever the agent SAYS it is doing, not on what it is doing.
+// A buggy, prompt-injected, or hostile agent auto-proceeds on anything by
+// describing it as low-magnitude reversible writing. The escalation rail inherits
+// the same assumption: the subject approves the agent's prose summary.
+//
+// This is a known 2026 vulnerability class, not a hypothetical — agents requesting
+// approval on a shown path while operating on the resolved target (CWE-61 symlink
+// following + CWE-451 UI misrepresentation) produced CVE-2026-12958 (Amazon) and
+// CVE-2026-50549 (Cursor), among others.
+//
+// WHAT THIS DOES, AND WHAT IT DOES NOT. A binding does NOT make the descriptor
+// truthful — nothing at this layer can, short of the resolver executing the call
+// itself. What it does:
+//
+//   1. makes a mismatch PROVABLE after the fact (the receipt records the exact
+//      tool and a hash of its arguments, so the agent's own logs can be checked
+//      against what the oracle was told),
+//   2. gives the subject the REAL call on the escalation card, next to the
+//      agent's description of it, and
+//   3. lets an authored authorization demand a binding before it will RELAX
+//      anything (§10.5 `require_binding`), so the blast radius of a fabricated
+//      descriptor is bounded by what the subject explicitly opted into.
+//
+// The hash is over the RFC 8785 canonical form of the arguments, so an agent and
+// an auditor computing it independently agree byte-for-byte. Arguments themselves
+// are NEVER carried — only a digest, plus an optional short human preview that the
+// subject sees on the escalation sheet.
+//
+// PURE: no I/O, no globals, no crypto beyond the hash the caller injects. Shared by
+// the resolver (mcp/consult-core.js), the receipt writer (mcp/receipts.js) and the
+// escalation payload builder (mcp/escalation.js) so the three cannot drift.
+
+import { PhaedoError } from './errors.js';
+
+// A preview is for a human glance on a phone sheet, not a serialization format.
+export const PREVIEW_MAX = 200;
+export const TOOL_NAME_MAX = 120;
+// A hex or base64url digest. Bounded so a malformed field can't bloat the receipt
+// store or the (encrypted) escalation payload.
+const HASH_RE = /^[A-Za-z0-9_-]{16,128}$/;
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const clip = (s, n) => String(s).replace(/\s+/g, ' ').trim().slice(0, n);
+
+// Parse + validate §10.2 `action_binding`. Returns the normalized binding, or null
+// when absent. THROWS `request_malformed` when present but structurally wrong — a
+// half-formed binding is worse than none, because a caller could believe it is
+// bound when the resolver treats it as unbound.
+export function normalizeActionBinding(raw) {
+  if (raw == null) return null;
+  if (!isObj(raw)) throw new PhaedoError('request_malformed', 'action_binding must be an object.');
+
+  const toolName = typeof raw.tool_name === 'string' ? raw.tool_name.trim() : '';
+  if (!toolName) throw new PhaedoError('request_malformed', 'action_binding.tool_name is required and must be a non-empty string.');
+  if (toolName.length > TOOL_NAME_MAX) throw new PhaedoError('request_malformed', `action_binding.tool_name exceeds ${TOOL_NAME_MAX} characters.`);
+
+  const hash = typeof raw.arguments_hash === 'string' ? raw.arguments_hash.trim() : '';
+  if (!hash) throw new PhaedoError('request_malformed', 'action_binding.arguments_hash is required and must be a non-empty string.');
+  if (!HASH_RE.test(hash)) throw new PhaedoError('request_malformed', 'action_binding.arguments_hash must be a hex or base64url digest (16–128 chars).');
+
+  const out = { tool_name: clip(toolName, TOOL_NAME_MAX), arguments_hash: hash };
+  if (typeof raw.arguments_preview === 'string' && raw.arguments_preview.trim()) {
+    out.arguments_preview = clip(raw.arguments_preview, PREVIEW_MAX);
+  }
+  return out;
+}
+
+// Is this request bound to a concrete call? The single predicate every consumer
+// asks, so "bound" means exactly one thing across the resolver, the policy engine,
+// the receipt and the escalation card.
+export function isBound(binding) {
+  return !!(binding && binding.tool_name && binding.arguments_hash);
+}

package/agreement.js

@@ -77,6 +77,44 @@ export function computeAgreement(receipts, { windowDays = DEFAULT_WINDOW_DAYS, n
   };
 }
 
+// ── The transportable summary (receipts digest → phone) ───────────────────────
+// `computeAgreement` is the full local report; this is the bounded slice that rides
+// the `agent_to_phone` receipts digest so the subject can see how well their oracle
+// is tracking them, per domain, without opening a terminal.
+//
+// It is derived ENTIRELY from the subject's own receipts and only ever travels
+// between the subject's own devices (ciphertext over the relay), so it raises no
+// §10.4 question — but it still carries no layer content, no rationale, and no
+// `drivers`: counts and a rate, nothing else.
+//
+// Bounded on purpose (the digest is a last-write-wins payload, so it must not grow
+// without limit): unscored domains are dropped (a domain with nothing scored says
+// nothing), the rest are ranked by `scored` and capped. Ties break by name so the
+// payload is DETERMINISTIC — an unstable key order would make every deposit look
+// like a change.
+export const DIGEST_DOMAIN_CAP = 8;
+
+const slimBucket = (b) => ({
+  rate: b.rate,
+  scored: b.scored,
+  agreements: b.agreements,
+  disagreements: b.disagreements,
+  non_directional: b.non_directional,
+  awaiting_user_action: b.awaiting_user_action,
+});
+
+// (receipts, { windowDays, now, domainCap }) -> { window_days, overall, domains }
+export function agreementDigest(receipts, { windowDays = DEFAULT_WINDOW_DAYS, now = Date.now(), domainCap = DIGEST_DOMAIN_CAP } = {}) {
+  const report = computeAgreement(receipts, { windowDays, now });
+  const domains = {};
+  Object.entries(report.domains)
+    .filter(([, b]) => b.scored > 0)
+    .sort((a, b) => (b[1].scored - a[1].scored) || a[0].localeCompare(b[0]))
+    .slice(0, Math.max(0, domainCap))
+    .forEach(([name, b]) => { domains[name] = slimBucket(b); });
+  return { window_days: windowDays, overall: slimBucket(report.overall), domains };
+}
+
 // ── Dev CLI: `node agreement.js` / `npm run agreement` — local readout only ───
 // Decrypts the local receipt store with the local key; nothing leaves the device.
 // NOT product UX and NOT fed back into deference (see header).

package/ap2.js

@@ -0,0 +1,214 @@
+// Anamnesis ↔ AP2 profile — standing authorizations as Intent Mandates.
+//
+// WHY THIS EXISTS. The standing risk to Anamnesis is not that a rival builds a
+// better decision oracle; it is the standards cold-start. One implementer is a
+// format, not a standard, and evangelism has not moved that number. Binding to a
+// standard that ALREADY has implementers does: every AP2 participant becomes a
+// partial Anamnesis consumer without adopting Anamnesis.
+//
+// AP2 (Google → FIDO Alliance, May 2026; Mastercard's Verifiable Intent
+// co-contributed; the FIDO Payments TWG is chaired by Mastercard and Visa) defines
+// an INTENT MANDATE: a verifiable credential, signed by the user with a
+// hardware-backed device key, TTL'd, carrying structured constraints and the
+// agent's stated understanding of the request ("prompt playback"), plus an
+// intentionally open-ended risk payload.
+//
+// Read that against §10.5. An Intent Mandate is a standing authorization
+// (`match` + `amount_gt` + `expires_at`) rendered as a credential the card networks
+// already accept — and Phaedo's escalate-to-phone flow is architecturally the signing
+// ceremony, once §8.3 gives the phone a signing key. The two designs arrived
+// at the same primitive from opposite ends. "Prompt playback" is the payments
+// industry independently discovering §10.2 `action_binding`.
+//
+// WHAT THIS MODULE DOES, AND DOES NOT. It is a PURE SERIALIZER: it renders the
+// subject's authorizations into the Intent Mandate payload shape, and renders a
+// consultation signal into a risk-payload entry. It does NOT sign — and today
+// NOTHING does: §8.3 asymmetric signing is unbuilt, so no subject signing key
+// exists anywhere in the product yet. That is the honest current state; the
+// intended design is that the key is generated non-extractably on the phone and
+// the ceremony that turns this payload into a credential is the phone's, not the
+// server's. Deliberately unreachable from here either way. Scope + the P-256 vs
+// Ed25519 decision: docs/roadmap/asymmetric-signing-scope-2026-07-23.md.
+//
+// The mapping is lossy in ONE direction on purpose. Anamnesis carries dispositions
+// and inferred signals that have no place in a payment credential, so only the
+// deterministic, subject-authored half crosses: authorizations, their bounds, and
+// their expiry. Nothing inferred, no layer content, no persona. That is the §10.4
+// boundary applied to a new transport, and it is also why this is safe to hand to a
+// merchant's stack.
+//
+// PURE: no I/O, no crypto, no network.
+
+import { signingInput } from './signing.js';
+
+const MAG_RANK = { low: 0, medium: 1, high: 2 };
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+// AP2 expresses shopping constraints as structured fields, not prose. §10.5 `match`
+// is already structured, so the translation is mechanical — the only real decision is
+// which constraints have a faithful counterpart and which must be dropped rather than
+// approximated. `magnitude` has none (it is a behavioral notion, not a commerce one),
+// so it is carried as an advisory annotation, never as a spend limit.
+function matchToConstraints(match) {
+  const m = isObj(match) ? match : {};
+  const out = {};
+  const domains = Array.isArray(m.domains) ? m.domains.map((d) => String(d)).filter(Boolean) : [];
+  if (domains.length) out.categories = domains;
+  // AP2's `max_amount` is a spend cap, so only a genuine CEILING may fill it.
+  // `amount_lt` is that ceiling. `amount_gt` is a FLOOR — "fires above N" — and on an
+  // autoproceed rule it means "auto-proceed only the LARGE ones", the opposite of a
+  // cap. Mapping it to `max_amount` (as this did before `amount_lt` existed) would
+  // have told a merchant the subject capped spending at exactly the figure above
+  // which they wanted extra scrutiny. It is carried as an annotation instead.
+  // Both ceiling forms map to `max_amount`, and when both are present the LOWER wins — AP2 has
+  // one field and no way to say "exclusive", so the credential must not assert more headroom than
+  // the rule grants. `amount_lte: 20` becomes `max_amount: 20`; `amount_lt: 20` also becomes 20,
+  // which is the pre-existing (slightly generous by one cent) mapping, unchanged.
+  const ceilings = [m.amount_lt, m.amount_lte].filter((v) => typeof v === 'number' && Number.isFinite(v));
+  if (ceilings.length) {
+    out.max_amount = Math.min(...ceilings);
+  }
+  if (typeof m.amount_gt === 'number' && Number.isFinite(m.amount_gt)) {
+    out.annotations = { ...(out.annotations || {}), anamnesis_amount_floor: m.amount_gt };
+  }
+  if (typeof m.reversible === 'boolean') out.refundable_only = m.reversible;
+  if (m.magnitude_max && MAG_RANK[m.magnitude_max] !== undefined) {
+    out.annotations = { ...(out.annotations || {}), anamnesis_magnitude_max: m.magnitude_max };
+  }
+  return out;
+}
+
+// One §10.5 authorization → the Intent Mandate constraint block it corresponds to,
+// or null when it has no faithful translation.
+//
+// Only AUTOPROCEED authorizations become mandates. That is the whole semantic match:
+// an Intent Mandate is a grant of authority to act without the human present, and
+// `autoproceed` is the only Anamnesis effect that grants anything. An `escalate` or
+// `decline` rule is the ABSENCE of a mandate — the correct AP2 rendering of "ask me
+// first" is not a restrictive credential, it is no credential at all, and emitting
+// one would invert its meaning to a merchant.
+export function authorizationToIntentConstraints(rule, { now = Date.now() } = {}) {
+  if (!isObj(rule)) return null;
+  if (rule.kind !== undefined && rule.kind !== 'authorization') return null;
+  if (rule.effect !== 'autoproceed') return null;
+  // A lapsed authorization must not be exported as live authority.
+  const exp = Date.parse(rule.expires_at);
+  if (Number.isFinite(exp) && exp <= now) return null;
+  // Nor must a CLIENT-SCOPED one (§10.5 `agents`). AP2 has no vocabulary for "this
+  // specific paired client", so a scoped grant cannot be expressed in a mandate — and
+  // emitting it unscoped would tell a merchant the subject granted unconditionally
+  // what they in fact granted to exactly one client. That is the same inversion this
+  // function already refuses for restrictive rules, and it crosses to a third party,
+  // where it is least correctable. A scope that cannot be carried must instead
+  // withhold the credential: the correct AP2 rendering of a grant this format cannot
+  // express is no grant at all. (An ABSENT `agents` is unscoped and exports normally;
+  // an empty array is a scope naming nobody, so it withholds too.)
+  if (Array.isArray(rule.agents)) return null;
+  return {
+    source_rule_id: rule.instruction_id || rule.id || null,
+    constraints: matchToConstraints(rule.match),
+    // §10.5 require_binding maps onto AP2's own posture that a mandate authorizes a
+    // BOUNDED transaction, not open-ended spending. Carried through so a verifier can
+    // see the subject demanded the agent commit to a concrete action.
+    requires_action_binding: rule.require_binding === true,
+    expires_at: Number.isFinite(exp) ? new Date(exp).toISOString() : null,
+  };
+}
+
+// The unsigned Intent Mandate payload for a subject's live authorizations.
+//
+// Returns null when the subject has granted nothing — which is the common case and
+// the right answer: no authority, no mandate. Callers MUST NOT synthesize an empty
+// mandate, because an empty credential reads to a merchant as "authorized with no
+// constraints", the exact inversion this module exists to avoid.
+export function buildIntentMandatePayload(fp, opts = {}) {
+  const {
+    now = Date.now(),
+    agentId = null,
+    promptPlayback = null,          // the agent's stated understanding (AP2 "prompt playback")
+    consultSignal = null,           // §10.3 signal, if a consultation preceded this
+  } = opts;
+
+  // A standing authorization lives in EITHER home (spec §10.5: "a `consult_policies` rule
+  // or `standing_rules` authorization"), so an Intent Mandate — the subject's live
+  // authorizations — must read both. Reading only `standing_rules` silently dropped every
+  // autoproceed guardrail authored through the extension's Decision-guardrails form (which
+  // writes `consult_policies`), so a subject with real grants got an empty mandate. The
+  // per-rule guards are unchanged and live in authorizationToIntentConstraints: autoproceed
+  // only, not lapsed, and never a client-scoped grant (AP2 can't express `agents`).
+  const standingRules = Array.isArray(fp?.standing_rules) ? fp.standing_rules : [];
+  const policyRules   = Array.isArray(fp?.consult_policies?.rules) ? fp.consult_policies.rules : [];
+  // §10.5 tombstones — a REVOKED authorization must never become a mandate grant. This is
+  // the highest-stakes read of the two homes: a grant here is what a payment credential is
+  // minted against, so a rule the subject revoked that survived in a stale or restored copy
+  // would sign away authority they took back. Same consumer MUST as normalizePolicies.
+  const revoked = new Set(
+    (Array.isArray(fp?.consult_policies?.revoked) ? fp.consult_policies.revoked : [])
+      .map((t) => (t && typeof t === 'object' && t.id != null ? String(t.id) : null))
+      .filter(Boolean)
+  );
+  const grants = [];
+  const seen = new Set();   // dedupe by source rule id — the same authorization must not
+  for (const r of [...standingRules, ...policyRules]) {           // become two mandate grants
+    if (r && typeof r === 'object') {
+      const rid = r.id != null ? String(r.id) : (r.instruction_id != null ? String(r.instruction_id) : null);
+      if (rid && revoked.has(rid)) continue;
+    }
+    const g = authorizationToIntentConstraints(r, { now });
+    if (!g) continue;
+    if (g.source_rule_id && seen.has(g.source_rule_id)) continue;
+    if (g.source_rule_id) seen.add(g.source_rule_id);
+    grants.push(g);
+  }
+  if (!grants.length) return null;
+
+  // The mandate expires with the FIRST grant to lapse — an aggregate credential must
+  // not outlive the narrowest authority inside it.
+  const expiries = grants.map((g) => Date.parse(g.expires_at)).filter(Number.isFinite);
+  const expiresAt = expiries.length ? new Date(Math.min(...expiries)).toISOString() : null;
+
+  return {
+    mandate_type: 'intent',
+    // Version the profile, not the payment protocol: AP2 moves on its own cadence and
+    // a verifier needs to know which mapping produced this.
+    anamnesis_profile: '0.1',
+    issued_at: new Date(now).toISOString(),
+    expires_at: expiresAt,
+    ...(agentId ? { agent_id: String(agentId) } : {}),
+    ...(promptPlayback ? { prompt_playback: String(promptPlayback).slice(0, 500) } : {}),
+    grants,
+    // AP2 leaves the risk payload open-ended for exactly this kind of signal. It is
+    // the ONE place a behavioral system has something to say to a payments network,
+    // and it says it in the §10.4 currency: a constrained signal, never persona.
+    risk_payload: buildRiskPayload({ consultSignal }),
+    // Unsigned by construction. The server CANNOT sign: per §8.3 the subject's key is
+    // non-extractable in the phone's Secure Enclave, so signing is a ceremony that belongs
+    // to the device holding the key. `intentMandateSigningInput()` below computes the exact
+    // bytes the phone would be asked to sign. Until a signature comes back, this object is
+    // a proposal, never a credential.
+    signature: null,
+  };
+}
+
+/**
+ * The exact bytes a §8.3 signature over an Intent Mandate covers: the §6 RFC 8785 canonical
+ * form of the payload with `signature` omitted. This is the seam between the server (which
+ * builds the mandate) and the phone (which holds the only key that can sign it) — both sides
+ * must agree on these bytes or the resulting signature verifies nowhere.
+ *
+ * Omitting `signature` is what keeps the input stable once the signature is attached, so a
+ * verifier recomputes the same bytes from the finished credential.
+ */
+export function intentMandateSigningInput(payload) {
+  return signingInput(payload, { field: 'signature' });
+}
+
+// §10.3 signal → AP2 risk-payload entry. Deliberately minimal: a merchant learns
+// that the subject's own oracle was consulted and what it said — which is exactly the
+// claim that makes a mandate more trustworthy — and learns nothing about the subject.
+export function buildRiskPayload({ consultSignal = null } = {}) {
+  const payload = { anamnesis_consulted: !!consultSignal };
+  if (consultSignal) payload.anamnesis_signal = String(consultSignal);
+  return payload;
+}