phaedo-mcp 0.2.2 → 0.3.0

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;
+})();

package/vendor/capture/capture-core.js

@@ -0,0 +1,67 @@
+// Phaedo capture — the tier-agnostic spine: exchange_batch → signal delta.
+//
+// Every capture surface (the Claude Code JSONL hook, the Track B a11y helper, a future
+// OCR tier) converges here once it has an exchange_batch (capture/transcript.js or
+// capture/exchanges.js). This module runs the shared tail — deterministic Path-A
+// detectors (+ optional local-model enrichment) → per-session state fold (resume-safe
+// REPLACE) → cumulative delta lift — and returns the source='delta' signals. It does NOT
+// touch the network: building + depositing the envelope is the transport layer's job
+// (mcp/capture-sync.js), which keeps capture/ deposit-free and lets each surface own its
+// pairing resolution. So a new front-end is a batch producer, not a new pipeline.
+//
+// Pure except the injected state file I/O (capture/state.js), exactly like the hook.
+
+import { accumulateBatchCounts } from './detectors.js';
+import { captureModelOpts, enrichCountsWithModel } from './model-detect.js';
+import { loadState, saveState, applySession, cumulativeCounts, defaultStatePath } from './state.js';
+import { liftDeltaSignals } from '../extraction/delta-lift.js';
+
+// Fold one batch into this surface's cumulative signal delta.
+//   batch — an exchange_batch ({ exchanges, user_prompts, session_local_id }).
+//   opts:
+//     sourceId       — the per-machine+surface source_device_id (capture/source-id.js).
+//     surface        — surface tag echoed into the result (e.g. 'a11y-macos').
+//     statePath      — durable per-surface state file (default: state.js defaultStatePath).
+//     sessionLocalId — STABLE per-conversation id → per-session REPLACE (idempotent re-reads).
+//     now            — ISO timestamp (fixed for deterministic tests).
+//     captureModel   — option (b) model opts, or undefined to auto-resolve from env; falsy = off.
+//     env            — process.env (for captureModelOpts auto-resolution).
+// Returns { signals, counts, modelAdded, sourceId, surface } — never throws on a bad
+// batch (empty → zero signals); state I/O failures are swallowed (counters just restart).
+export async function foldBatchToSignals(batch, opts = {}) {
+  const statePath = opts.statePath || defaultStatePath();
+  const nowIso = opts.now || new Date().toISOString();
+  const sourceId = opts.sourceId || null;
+  const sessionLocalId = opts.sessionLocalId || (batch && batch.session_local_id) || null;
+
+  const exchanges = (batch && batch.exchanges) || [];
+  const prompts = (batch && Array.isArray(batch.user_prompts)) ? batch.user_prompts : exchanges;
+  if (!prompts.length) return { signals: [], counts: null, modelAdded: 0, sourceId, surface: opts.surface || null };
+
+  let counts = accumulateBatchCounts(batch);
+
+  // Option (b): fold local-model classifications of the regex-MISS user messages into
+  // this session's counts BEFORE the state apply, so re-reads stay resume-safe and the
+  // deposit stays pure delta. Opt-in + fail-safe (any error leaves regex counts intact).
+  let modelAdded = 0;
+  const modelOpts = opts.captureModel !== undefined ? opts.captureModel : captureModelOpts(opts.env);
+  if (modelOpts && modelOpts.model) {
+    try {
+      const enriched = await enrichCountsWithModel(batch, counts, modelOpts);
+      counts = enriched.counts;
+      modelAdded = enriched.added;
+    } catch { /* model down/slow/garbage → regex-only, unchanged */ }
+  }
+
+  let state;
+  try {
+    state = applySession(loadState(statePath), sourceId, sessionLocalId, counts, { now: nowIso });
+    try { saveState(statePath, state); } catch { /* state loss just restarts counters — never fatal */ }
+  } catch {
+    // A corrupt state file must never break capture: fold against an empty baseline.
+    state = applySession(null, sourceId, sessionLocalId, counts, { now: nowIso });
+  }
+
+  const signals = liftDeltaSignals(cumulativeCounts(state, sourceId).behavioral_signals, nowIso);
+  return { signals, counts, modelAdded, sourceId, surface: opts.surface || null };
+}