phaedo-mcp 0.2.2 → 0.3.1

package/signing.js

@@ -0,0 +1,176 @@
+// §8.3 asymmetric signing — the verification half, server-side.
+//
+// The MCP server CANNOT sign: the subject's signing key is non-extractable inside the
+// phone's Secure Enclave (spec §8.3, verified on hardware 2026-07-23). What the server
+// does is (a) compute the exact bytes a signature covers, so the phone can be asked to
+// sign them, and (b) VERIFY a signature once the phone returns one. Signing itself is a
+// ceremony that belongs to the device holding the key, and deliberately stays there.
+//
+// PURE: no I/O, no globals. Crypto is node:crypto only — no third-party dependency is
+// introduced into the verification path.
+
+import { createPublicKey, verify as nodeVerify } from 'node:crypto';
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+// ── RFC 8785 canonical JSON (spec §6) ────────────────────────────────────────
+//
+// ⚠️ A FAITHFUL PORT. This is the FOURTH copy in the repo — envelope.js (extension),
+// mobile/src/lib/envelope.ts, the mirror in scripts/test_cross_compat.mjs, and now this
+// one. It MUST stay byte-identical to those three: a signature is only verifiable if every
+// implementation agrees on the bytes, so a divergence here silently produces signatures
+// nobody else can check. Locked by the published TC-CANON vectors in
+// mcp/test-signing.mjs — if this drifts, that suite fails.
+//
+// JSON.stringify already emits RFC 8785-conformant scalars in ECMAScript (shortest
+// round-trip numbers, minimal string escaping). What it does NOT do is order keys
+// recursively, and it silently turns non-finite numbers into null. Full RFC 8785 here =
+// UTF-16 code-unit key sort + explicit REJECTION of values JSON cannot express.
+const notJson = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
+
+export function canonicalStringify(value) {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new Error('canonicalStringify: non-finite numbers are not expressible in RFC 8785 JSON');
+  }
+  if (value === null || typeof value !== 'object') {
+    const s = JSON.stringify(typeof value === 'string' ? value.normalize('NFC') : value);
+    if (s === undefined) throw new Error('canonicalStringify: a ' + typeof value + ' is not expressible in JSON');
+    return s;
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(v => (notJson(v) ? 'null' : canonicalStringify(v))).join(',') + ']';
+  }
+  // §6.2 NFC — "Implementations MUST normalize text to NFC before canonicalization to avoid
+  // signature breakage from equivalent but byte different strings." It was implemented nowhere.
+  // This is the VERIFIER: if the phone ever normalizes and this does not, every signature it
+  // produces fails here, over text that looks identical in any log. KEYS too, and a post-NFC
+  // collision is REJECTED rather than silently dropping one. Byte-identical to envelope.js and
+  // mobile/src/lib/envelope.ts.
+  const seen = new Map();
+  for (const k of Object.keys(value)) {
+    if (notJson(value[k])) continue;
+    const nk = k.normalize('NFC');
+    if (seen.has(nk)) throw new Error('canonicalStringify: keys collide under NFC: ' + JSON.stringify(k));
+    seen.set(nk, value[k]);
+  }
+  const keys = [...seen.keys()].sort();   // UTF-16 code-unit order (RFC 8785 §3.2.3), post-NFC
+  const parts = [];
+  for (const k of keys) parts.push(JSON.stringify(k) + ':' + canonicalStringify(seen.get(k)));
+  return '{' + parts.join(',') + '}';
+}
+
+// ── What a signature covers ──────────────────────────────────────────────────
+
+/**
+ * The exact bytes a §8.3 signature is computed over: the §6 canonical serialization of
+ * the object with the signature field itself OMITTED. Omitting it is what makes the input
+ * well defined no matter how many signatures are later appended — the same construction
+ * §8.2 bootstrap mode uses for `digest`.
+ *
+ * @param {object} obj
+ * @param {{ field?: string }} [opts] field to omit (default 'signatures'; AP2 uses 'signature')
+ * @returns {Buffer} UTF-8 canonical bytes
+ */
+export function signingInput(obj, { field = 'signatures' } = {}) {
+  if (!isObj(obj)) throw new Error('signingInput: expected an object');
+  const rest = {};
+  for (const k of Object.keys(obj)) {
+    if (k !== field) rest[k] = obj[k];
+  }
+  return Buffer.from(canonicalStringify(rest), 'utf8');
+}
+
+// ── Key + signature encodings ────────────────────────────────────────────────
+
+/**
+ * Convert an X9.63 uncompressed EC point (0x04 || X || Y, 65 bytes) — what the Secure
+ * Enclave exports — into a node:crypto public key.
+ */
+export function publicKeyFromRawPoint(raw) {
+  const bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+  if (bytes.length !== 65 || bytes[0] !== 0x04) {
+    throw new Error('publicKeyFromRawPoint: expected a 65-byte uncompressed P-256 point (0x04 || X || Y)');
+  }
+  return createPublicKey({
+    key: {
+      kty: 'EC',
+      crv: 'P-256',
+      x: bytes.subarray(1, 33).toString('base64url'),
+      y: bytes.subarray(33, 65).toString('base64url'),
+    },
+    format: 'jwk',
+  });
+}
+
+/**
+ * Convert a DER (X9.62) ECDSA signature — what SecKeyCreateSignature emits — into the raw
+ * r||s form (64 bytes) that JOSE ES256 and the W3C VC suites use.
+ *
+ * This conversion is the boundary the spec deferred: the enclave speaks DER, interoperable
+ * verifiers expect raw, and something has to translate. Doing it here means the wire form
+ * is the interoperable one while the device keeps using its native output.
+ */
+export function derToRawSignature(der) {
+  const b = Buffer.isBuffer(der) ? der : Buffer.from(der);
+  let i = 0;
+  if (b[i++] !== 0x30) throw new Error('derToRawSignature: not a DER SEQUENCE');
+  let seqLen = b[i++];
+  if (seqLen & 0x80) {                       // long form length
+    const n = seqLen & 0x7f;
+    if (n < 1 || n > 2) throw new Error('derToRawSignature: unsupported DER length');
+    seqLen = 0;
+    for (let k = 0; k < n; k++) seqLen = (seqLen << 8) | b[i++];
+  }
+  if (i + seqLen !== b.length) throw new Error('derToRawSignature: DER length mismatch');
+
+  const readInt = () => {
+    if (b[i++] !== 0x02) throw new Error('derToRawSignature: expected DER INTEGER');
+    const len = b[i++];
+    if (len & 0x80) throw new Error('derToRawSignature: unsupported INTEGER length');
+    let v = b.subarray(i, i + len);
+    i += len;
+    // DER integers are signed and minimally encoded: strip leading zero padding, then
+    // left-pad to the 32-byte field width the raw form requires.
+    while (v.length > 1 && v[0] === 0x00) v = v.subarray(1);
+    if (v.length > 32) throw new Error('derToRawSignature: integer wider than P-256 field');
+    return Buffer.concat([Buffer.alloc(32 - v.length), v]);
+  };
+
+  const r = readInt();
+  const s = readInt();
+  if (i !== b.length) throw new Error('derToRawSignature: trailing bytes after signature');
+  return Buffer.concat([r, s]);
+}
+
+// ── Verification ─────────────────────────────────────────────────────────────
+
+/**
+ * Verify a §8.3 ES256 signature over an object.
+ *
+ * Never throws on a bad signature — returns false. A malformed key or an unusable
+ * encoding still throws, because that is a caller bug rather than a failed verification,
+ * and the two must not be conflated (silently returning false for a broken key would
+ * report "not the subject's signature" when the truth is "we could not check").
+ *
+ * @param {object}  args.payload    the signed object (signature field may be present; it is omitted)
+ * @param {Buffer|Uint8Array} args.signature
+ * @param {Buffer|Uint8Array} args.publicKey  X9.63 uncompressed point (65 bytes)
+ * @param {'der'|'raw'} [args.encoding='raw']
+ * @param {string} [args.field='signatures']  which field to omit from the signing input
+ * @returns {boolean}
+ */
+export function verifyEs256({ payload, signature, publicKey, encoding = 'raw', field = 'signatures' }) {
+  if (encoding !== 'der' && encoding !== 'raw') {
+    throw new Error(`verifyEs256: unknown signature encoding '${encoding}'`);
+  }
+  const key = publicKeyFromRawPoint(publicKey);      // throws on a malformed key — deliberate
+  const data = signingInput(payload, { field });
+  const sig = Buffer.isBuffer(signature) ? signature : Buffer.from(signature);
+  try {
+    return nodeVerify('sha256', data, { key, dsaEncoding: encoding === 'der' ? 'der' : 'ieee-p1363' }, sig);
+  } catch {
+    // node throws on structurally invalid signature bytes; that is a failed verification,
+    // not a caller error.
+    return false;
+  }
+}

package/vendor/authored-source.js

@@ -0,0 +1,250 @@
+// Where authored content comes FROM — the step-3 read path.
+//
+// Authored standing rules live in two places during the migration: the fingerprint A-home
+// (`fp.standing_rules`, Proposal 0007) and the §5 User Configuration (`standing_instructions`,
+// derived from the A-home on every write). The sequencing decision is that the §5 copy is
+// AUTHORITATIVE ON READ where both exist, so that step 3 can later delete the A-home and change
+// nothing about what readers see. Every reader routing through here is what makes that true.
+//
+// WHY A RESOLVER AND NOT `cfg.standing_instructions || fp.standing_rules`:
+//
+//   1. §5.4. A configuration that does not name the fingerprint it arrived with is not this
+//      subject's — stale, mis-routed, or hostile. Letting it govern would let one identity's
+//      authored rules apply to another. It must fall back, not be trusted.
+//   2. ABSENT and EMPTY are different. No §5 document at all means "this surface has not been
+//      migrated, use the A-home". A §5 document with an empty list means "the subject has no
+//      rules", and falling back there would RESURRECT rules the subject deleted — the same
+//      failure as the union-vs-tombstone bug in §10.5 revocation (#247).
+//   3. The caller needs to know WHICH home answered. A reader that cannot report its provenance
+//      cannot be verified on device, and "it works" would be indistinguishable from "it silently
+//      read the old home the whole time".
+//
+// Mirrored by mobile/src/lib/authoredSource.ts; kept honest by
+// scripts/test_mobile_authored_source_parity.mjs, which RUNS both over the same inputs.
+
+(function () {
+  'use strict';
+
+  /**
+   * WHICH HOME IS AUTHORITATIVE for authored rules — the step-3 cutover switch.
+   *
+   * It lives HERE, with the resolver, because "where does authored content live" is one question
+   * and both the reader and the writer must answer it identically. authored-write.js re-exports
+   * it; user-config.js reads it to decide whether a re-derive may overwrite standing_instructions.
+   * This module imports nothing, so every consumer can read it without an import cycle.
+   *
+   * 'fingerprint' — today. Rules live on the A-home; §5 is DERIVED from it on every write.
+   * 'config'      — after step 3. §5 is the source; the A-home is a mirror, and the derive must
+   *                 stop overwriting §5 or a routine fingerprint write erases authored rules.
+   *
+   * Flipping this IS the cutover. It ships only once the upgrade gate reads green against real
+   * device reports (owner decision 2026-07-27: release check, not runtime interlock).
+   *
+   * FLIPPED to 'config' on 2026-07-28 and REVERTED the same day, before any device carried it.
+   * The revert is the mechanism working: one constant, so a bad answer costs one line.
+   *
+   * A post-flip review found SIX confirmed paths that lose authored content, every one of them
+   * benign while the A-home is authoritative and live the moment it is not:
+   *   1. the phone's chokepoint replaces §5 wholesale from the mirror, so any authored save
+   *      destroys a §5-only rule (mobile/src/lib/authoredWrite.ts)
+   *   2. background.js never loads THIS module, so the vault write finalizer throws on every
+   *      service-worker write and §5 is never maintained there
+   *   3. the live /v1/profile sync path carries no §5 at all (popup.js silentSync)
+   *   4. popup.js _actOnOverride authors a rule outside the write chokepoint
+   *   5. the SW capture re-deposit strips the §5 envelope off the wire, so authored rules and
+   *      the irreplaceable example_corpus never reach the phone
+   *   6. a non-governing §5 document is never cleared, and absorbs authored content into a
+   *      document that can never govern — and is excluded from §8.2 backup at the same moment
+   *
+   * WHAT MUST BE TRUE BEFORE FLIPPING AGAIN — all six closed, plus:
+   *   - every authoring site routes through the chokepoint, enumerated BY BEHAVIOUR
+   *   - every reader routes through resolveStandingInstructions, likewise
+   *   - the upgrade gate is actually CONSULTED (it currently has zero production call sites)
+   *   - the phone advertises config_home_v0.2 only once it genuinely satisfies it
+   *   - a device pass on a build that carries the phone half
+   * See docs/state/current-state.md and scripts/test_cutover_readiness.mjs.
+   */
+  const AUTHORED_HOME = 'config';
+
+  // ── The upgrade gate, wired ────────────────────────────────────────────────────────────────
+  //
+  // `AUTHORED_HOME` ARMS the cutover. It does not perform it. The effective home is `'config'`
+  // only when the constant says so AND capabilities.js reports every reader current — so flipping
+  // the constant on a fleet where the phone or the agent is behind changes NOTHING until they
+  // catch up, instead of retiring the A-home out from under them.
+  //
+  // This is the wiring the gate was missing. `canRetireAHome` and `retirementBlockers` were
+  // correct and well tested and had ZERO production call sites: evidence was collected into
+  // `phaedo_peer_capabilities` and never asked. The 2026-07-28 flip shipped without the mechanism
+  // designed to authorise it ever being consulted, and six loss paths went with it.
+  //
+  // WHY A LATCH RATHER THAN A READ. The consumers (user-config.js, authored-write.js) are pure
+  // functions over a vault object, and the capability record lives outside the vault on purpose —
+  // it is fleet metadata, and the gate must be answerable without unlocking anything. Making
+  // those functions async, or handing them a storage handle, would put I/O on the authoring path.
+  // So the surface that CAN read storage pushes the record in, and the pure modules read it
+  // synchronously.
+  //
+  // IT FAILS CLOSED IN EVERY DIRECTION. Unset (nobody pushed a record), capabilities.js not
+  // loaded, an empty record, a reader that never reported, a reader on an older build, a report
+  // too old — all of them resolve to `'fingerprint'`. Silence is not consent; the only path to
+  // `'config'` is positive evidence from every reader.
+  let _peerCapabilities = null;
+
+  /**
+   * Publish what the fleet last reported. Called by whichever surface can read storage
+   * (background.js on startup, popup.js after each mailbox drain).
+   */
+  function setPeerCapabilities(known) {
+    _peerCapabilities = isObj(known) ? known : null;
+  }
+
+  /** What was last published. Exposed so a caller can show the subject the same evidence. */
+  function peerCapabilities() { return _peerCapabilities; }
+
+  /**
+   * The home that is actually in force, and why. Returns a REASON so a withheld cutover can be
+   * explained rather than merely observed — the same discipline `retirementBlockers` follows.
+   *
+   * @returns {{ home: string, armed: boolean, blockers: Array, reason: string }}
+   */
+  function effectiveAuthoredHomeDetail(now) {
+    // Read the PUBLISHED value, not the closure constant. `api.AUTHORED_HOME` is what every
+    // consumer sees, so reading anything else would let the module disagree with its own exports
+    // — and it is the value the cutover suites set to stage post-cutover conditions, which means
+    // they exercise this path rather than a parallel one.
+    const armed = (api && api.AUTHORED_HOME) || AUTHORED_HOME;
+    if (armed !== 'config') {
+      return { home: 'fingerprint', armed: false, blockers: [], reason: 'not_armed' };
+    }
+    const CAP = (typeof globalThis !== 'undefined' && globalThis.PhaedoCapabilities) || null;
+    if (!CAP || typeof CAP.retirementBlockers !== 'function') {
+      // The gate module is not present, so the fleet's state is unknowable here. Unknowable is
+      // not the same as fine — this is the `[].every(...)` trap the gate itself was built around.
+      return { home: 'fingerprint', armed: true, blockers: [], reason: 'gate_unavailable' };
+    }
+    if (!isObj(_peerCapabilities)) {
+      return { home: 'fingerprint', armed: true, blockers: [], reason: 'no_capability_record' };
+    }
+    // NAME THE ASKER. The extension's peers are the phone and the agent; passing nothing would
+    // fall back to checking all three including itself, which never reports and would block
+    // forever. See readersFor in capabilities.js.
+    const blockers = CAP.retirementBlockers(_peerCapabilities, now, { self: 'extension' });
+    if (blockers.length) {
+      return { home: 'fingerprint', armed: true, blockers, reason: 'readers_behind' };
+    }
+    return { home: 'config', armed: true, blockers: [], reason: 'fleet_current' };
+  }
+
+  /** The home in force. Use `effectiveAuthoredHomeDetail` when you need to explain a fallback. */
+  function effectiveAuthoredHome(now) {
+    return effectiveAuthoredHomeDetail(now).home;
+  }
+
+  /** Where an answer came from. Returned, never inferred by the caller. */
+  const SOURCE = {
+    CONFIG: 'config',            // §5 — the post-cutover home
+    FINGERPRINT: 'fingerprint',  // the A-home — the fallback step 3 removes
+    NONE: 'none',                // neither home had anything to say
+  };
+
+  function isObj(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+  /**
+   * The configuration's live instructions — those not buried by a §5.2 tombstone.
+   *
+   * Keyed by the FROZEN identity in sync-merge.js. When that module is absent (a reader that
+   * loads only the resolver) the tombstones cannot be evaluated, and the honest answer is to
+   * return the rules unchanged rather than guess: dropping rules we cannot key would lose
+   * authored content, and that is the worse direction here.
+   */
+  function withoutRevoked(cfg) {
+    const rules = cfg.standing_instructions;
+    const tombs = Array.isArray(cfg.revoked_instructions) ? cfg.revoked_instructions : [];
+    if (!tombs.length) return rules;
+    const SM = (typeof globalThis !== 'undefined' && globalThis.PhaedoSyncMerge) || null;
+    if (!SM || typeof SM.instructionKey !== 'function') return rules;
+    const dead = new Set(tombs.map((t) => (isObj(t) ? t.key : null)).filter(Boolean));
+    if (!dead.size) return rules;
+    return rules.filter((r) => !dead.has(SM.instructionKey(r)));
+  }
+
+  /**
+   * Does this configuration belong to this fingerprint? Mirrors config-sync.js `pairingHolds`
+   * deliberately rather than importing it: this module is loaded by readers that have no reason
+   * to pull in the transport, and the rule is three lines. Parity between the two is asserted in
+   * scripts/test_authored_source.mjs so the duplication cannot drift.
+   */
+  function configGoverns(cfg, fp) {
+    if (!isObj(cfg) || !isObj(fp)) return false;
+    if (typeof fp.fingerprint_id !== 'string' || !fp.fingerprint_id) return false;
+    if (cfg.fingerprint_id !== fp.fingerprint_id) return false;
+    if (typeof fp.subject_id === 'string' && fp.subject_id &&
+        typeof cfg.subject_id === 'string' && cfg.subject_id &&
+        cfg.subject_id !== fp.subject_id) return false;
+    return true;
+  }
+
+  /**
+   * The authoritative standing instructions, and where they came from.
+   *
+   * §5 wins whenever it is present AND governs — including when it is EMPTY, because an empty
+   * authored set is a statement ("I have no rules"), not an absence. Only a missing or
+   * non-governing configuration falls through to the A-home.
+   *
+   * @returns {{ rules: Array, source: string, reason?: string }}
+   */
+  function resolveStandingInstructions(fp, cfg) {
+    const aHome = isObj(fp) && Array.isArray(fp.standing_rules) ? fp.standing_rules : null;
+
+    if (isObj(cfg) && Array.isArray(cfg.standing_instructions)) {
+      if (configGoverns(cfg, fp)) {
+        // §5.2 tombstones are enforced HERE, not only at the merge. A device that has not merged
+        // since the revocation still holds the rule in `standing_instructions`; honouring the
+        // tombstone at read time is what makes the revocation take effect immediately rather
+        // than on the next sync. §10.5 learned this the hard way — ap2.js honoured its
+        // tombstones while the consult resolver did not, so one artifact gave two answers.
+        return { rules: withoutRevoked(cfg), source: SOURCE.CONFIG };
+      }
+      // Present but not this subject's. Fall back rather than trust it, and SAY so — a §5.4
+      // rejection that looks identical to "no configuration here" is how a mis-paired document
+      // would go unnoticed for months.
+      //
+      // BUT ITS DELETIONS STILL COUNT. The A-home has no revocation concept, and its copy is
+      // union-merged, so a rule the subject deleted comes back from any peer that still holds it
+      // — and falling back to that copy put the deleted rule into force again (measured
+      // 2026-08-12). Honouring the tombstones on a document we otherwise refuse is safe in a way
+      // that honouring its rules would not be: a tombstone can only ever REMOVE an instruction,
+      // never add one or change what it says. The worst it can do is withhold a rule the subject
+      // wanted; the alternative is obeying one they revoked, which is the direction that cannot
+      // be noticed from the outside.
+      if (aHome) {
+        return { rules: withoutRevoked({ standing_instructions: aHome, revoked_instructions: cfg.revoked_instructions }),
+                 source: SOURCE.FINGERPRINT, reason: 'config_pairing_failed' };
+      }
+      return { rules: [], source: SOURCE.NONE, reason: 'config_pairing_failed' };
+    }
+
+    if (aHome) return { rules: aHome, source: SOURCE.FINGERPRINT, reason: 'no_config' };
+    return { rules: [], source: SOURCE.NONE, reason: 'no_config' };
+  }
+
+  /**
+   * True once this surface would behave identically with the A-home deleted — i.e. §5 answered.
+   * This is the evidence a surface needs before it may advertise `config_home_v0.2` to the
+   * upgrade gate. Claiming the capability on the strength of "the code is deployed" rather than
+   * "the read actually resolved to §5" is exactly how a gate opens on the wrong evidence.
+   */
+  function readsFromConfigHome(fp, cfg) {
+    return resolveStandingInstructions(fp, cfg).source === SOURCE.CONFIG;
+  }
+
+  // Declared before the functions above can run (they only read it at call time), so
+  // `effectiveAuthoredHomeDetail` can consult the published value.
+  const api = {
+    AUTHORED_HOME, SOURCE, configGoverns, resolveStandingInstructions, readsFromConfigHome,
+    setPeerCapabilities, peerCapabilities, effectiveAuthoredHome, effectiveAuthoredHomeDetail,
+  };
+  if (typeof globalThis !== 'undefined') globalThis.PhaedoAuthoredSource = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();

package/vendor/capabilities.js

@@ -0,0 +1,203 @@
+// The §5 step-3 upgrade gate — who is current, and may the A-home be retired yet.
+//
+// WHY THIS EXISTS. Step 3 deletes the fingerprint A-home, which is where authored content lives
+// today. A surface that has not upgraded then reads NOTHING where the subject's rules used to be,
+// and the failure is asymmetric: a missing GRANT fails safe (no `autoproceed` match, so the agent
+// asks) but a missing PROHIBITION does not — with no `escalate`/`decline` rule present the
+// inferred signal governs, and that can be "proceed". Retiring the A-home while any reader is
+// behind therefore removes caution specifically, never permission.
+//
+// Sequencing decision 3 (config-home-v02-sequencing-2026-07-26) defines the gate: with one user
+// it is "Randy's phone and extension are both on the new build." This module makes that a
+// runtime fact instead of a release-day memory.
+//
+// THE SHAPE THAT MATTERS: this fails CLOSED, and the way it fails closed is not the obvious one.
+// `[].every(...)` is TRUE in JavaScript, so a naive "do all peers support it?" answers YES when
+// NO PEER HAS EVER REPORTED. That is this codebase's recurring failure exactly — silence read as
+// success. Silence here means "you do not know", and not knowing means do not retire anything.
+//
+// Mirrored by mobile/src/lib/capabilities.ts; kept honest by
+// scripts/test_mobile_capabilities_parity.mjs, which RUNS both over the same inputs.
+
+(function () {
+  'use strict';
+
+  /** This surface can send and receive the §5 artifact. True on both surfaces since #266/#267. */
+  const CONFIG_TRANSPORT = 'config_transport_v0.1';
+
+  /**
+   * The capability step 3 requires: this surface SOURCES authored content from §5 and stays
+   * correct when the A-home is absent. Deliberately distinct from CONFIG_TRANSPORT — carrying
+   * the artifact and reading from it are different claims, and conflating them is how a gate
+   * ends up opening on the wrong evidence. Nothing advertises this yet; the step-3 read path
+   * is what earns it.
+   */
+  //
+  // ⚠️ NECESSARY BUT NOT SUFFICIENT FOR STEP 3 — found on device 2026-07-27. Every surface now
+  // genuinely READS from §5, and this gate goes green on that basis. But §5 cannot yet CARRY an
+  // authored rule between devices: mergeConfig folds only `example_corpus`, so a rule authored on
+  // the extension is discarded by the phone's merge. Correct today (standing_instructions is
+  // re-derived from the A-home, which is what actually syncs rules) and broken the moment step 3
+  // makes §5 the authored home. See scripts/test_config_sync_rules_gap.mjs — the tripwire that
+  // must be deleted, not silenced, when the merge learns to carry rules.
+  const CONFIG_HOME = 'config_home_v0.2';
+
+  /**
+   * What each surface implements — PER SURFACE, not one shared list.
+   *
+   * This file is loaded by the extension AND vendored into the published MCP, and the two do not
+   * become §5-native at the same moment. A single shared list would have made the agent claim
+   * CONFIG_HOME the instant the extension earned it, which is precisely the "gate opens on the
+   * wrong evidence" failure the gate exists to prevent — and it would have been invisible, since
+   * the agent would simply have started reading a home it does not understand.
+   *
+   * A surface earns CONFIG_HOME only when EVERY one of its authored-content reads resolves
+   * through §5 and it stays correct with the A-home absent.
+   */
+  const CAPABILITIES_BY_SURFACE = {
+    // Both read sites go through §5: the injection path (context-block.js renderContextBlock)
+    // and the popup's rule display (_readStandingRules → authored-source.js).
+    extension: [CONFIG_TRANSPORT, CONFIG_HOME],
+    // The agent's authored-content readers (ap2.js, autonomy-promotion.js, consult-core.js) all
+    // take a FINGERPRINT rather than a vault, so §5 is folded in ONCE at the vd boundary
+    // (fingerprint-source.js foldConfigHome) and every one of them is §5-canonical by
+    // construction. Same boundary carries the §5.4 check.
+    agent: [CONFIG_TRANSPORT, CONFIG_HOME],
+  };
+
+  /** Back-compat for callers that ask without naming a surface: the conservative intersection. */
+  const CAPABILITIES = [CONFIG_TRANSPORT];
+
+
+  // WHO MUST BE CURRENT depends on WHO IS ASKING. Retiring the A-home harms any surface that READS
+  // authored content, and there are three; the asker is not one of its own peers, because it knows
+  // its own capability from CAPABILITIES_BY_SURFACE — it is the code that is running.
+  //
+  // This used to be a single list, ['phone', 'agent'], which is the EXTENSION's view written as if
+  // it were universal. The moment the phone gained a gate of its own that list had it checking
+  // ITSELF and the agent while never hearing about the extension — the one peer whose readiness
+  // actually matters to it.
+  //
+  // `self` is REQUIRED in effect: an unrecognised value falls back to checking all three, which
+  // can only add blockers. The opposite default — assuming a caller meant the extension — could
+  // REMOVE one, and a gate that quietly stops checking a reader is the failure this whole module
+  // exists to prevent.
+  const ALL_READERS = ['extension', 'phone', 'agent'];
+  function readersFor(self) {
+    return ALL_READERS.includes(self) ? ALL_READERS.filter((s) => s !== self) : ALL_READERS.slice();
+  }
+
+  /** The extension's peer set. Kept as a named export because callers and tests reference it. */
+  const READERS = readersFor('extension');
+
+  // A report older than this is not evidence about the fleet as it stands now — a device can be
+  // reinstalled, downgraded, or simply gone. 30 days is long enough that a phone left in a drawer
+  // over a holiday does not trip the gate, short enough that a stale record cannot authorise a
+  // one-way door months later.
+  const MAX_REPORT_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+  function isObj(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+  /**
+   * The payload a surface stamps into what it deposits. Deliberately a CAPABILITY LIST rather
+   * than a version number: "what can you do" survives version drift and forks, "what version are
+   * you" needs a comparison table that nobody maintains.
+   */
+  function advertise(surface, now) {
+    if (typeof surface !== 'string' || !surface) return null;
+    // An UNKNOWN surface gets the conservative set, never the most capable one. Guessing upward
+    // here would let a surface nobody has audited close the gate's last blocker.
+    const caps = CAPABILITIES_BY_SURFACE[surface] || CAPABILITIES;
+    return {
+      surface,
+      capabilities: caps.slice(),
+      stamped_at: now || new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Fold an incoming advertisement into the record of what each peer last reported. Keyed by
+   * surface, newest-wins — a surface only ever describes itself, so there is no merge conflict
+   * to resolve and no union to get wrong.
+   */
+  function recordPeer(known, incoming) {
+    const base = isObj(known) ? known : {};
+    if (!isObj(incoming) || typeof incoming.surface !== 'string' || !incoming.surface) return base;
+    const prior = base[incoming.surface];
+    const pt = prior ? Date.parse(prior.stamped_at) || 0 : 0;
+    const it = Date.parse(incoming.stamped_at) || 0;
+    if (it <= pt) return base;
+    return {
+      ...base,
+      [incoming.surface]: {
+        capabilities: Array.isArray(incoming.capabilities) ? incoming.capabilities.slice() : [],
+        stamped_at: incoming.stamped_at,
+      },
+    };
+  }
+
+  /**
+   * Fold a LIST of advertisements. The phone deposits its own plus any it is couriering for a
+   * paired agent, because the agent has no direct channel to the extension — the same courier
+   * role the phone already plays for capture snapshots and delegation suggestions.
+   */
+  function recordPeers(known, list) {
+    if (!Array.isArray(list)) return isObj(known) ? known : {};
+    return list.reduce((acc, ad) => recordPeer(acc, ad), isObj(known) ? known : {});
+  }
+
+  /**
+   * May the A-home be retired? Returns a REASON, not just a boolean — the caller has to be able
+   * to tell the subject why their cutover is being withheld, and "false" alone cannot.
+   *
+   * Fails closed on: no record at all, a reader that has never reported, a reader that reported
+   * without the capability, and a report too old to be evidence.
+   */
+  function retirementBlockers(known, now, opts) {
+    const at = now ? Date.parse(now) : Date.now();
+    const rec = isObj(known) ? known : {};
+    const blockers = [];
+    for (const surface of readersFor(opts && opts.self)) {
+      const entry = rec[surface];
+      if (!isObj(entry)) {
+        // The empty-record case. This is the branch `[].every(...)` would have answered "fine".
+        blockers.push({ surface, reason: 'never_reported' });
+        continue;
+      }
+      const caps = Array.isArray(entry.capabilities) ? entry.capabilities : [];
+      if (!caps.includes(CONFIG_HOME)) {
+        blockers.push({ surface, reason: 'lacks_capability' });
+        continue;
+      }
+      const stamped = Date.parse(entry.stamped_at) || 0;
+      if (!stamped || at - stamped > MAX_REPORT_AGE_MS) {
+        blockers.push({ surface, reason: 'report_too_old' });
+      }
+    }
+    return blockers;
+  }
+
+  /** Convenience over retirementBlockers. Never call this without surfacing the blockers. */
+  function canRetireAHome(known, now, opts) {
+    return retirementBlockers(known, now, opts).length === 0;
+  }
+
+  /** One line a human can act on. */
+  function describeBlockers(blockers) {
+    if (!Array.isArray(blockers) || !blockers.length) return 'every reader is current';
+    const words = {
+      never_reported: 'has never reported in',
+      lacks_capability: 'is on an older build',
+      report_too_old: 'has not been seen recently enough to count',
+    };
+    return blockers.map((b) => `${b.surface} ${words[b.reason] || b.reason}`).join('; ');
+  }
+
+  const api = {
+    CONFIG_TRANSPORT, CONFIG_HOME, CAPABILITIES, CAPABILITIES_BY_SURFACE, READERS, ALL_READERS,
+    readersFor, MAX_REPORT_AGE_MS,
+    advertise, recordPeer, recordPeers, retirementBlockers, canRetireAHome, describeBlockers,
+  };
+  if (typeof globalThis !== 'undefined') globalThis.PhaedoCapabilities = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();