phaedo-mcp 0.2.2 → 0.3.1

package/vendor/capture/owner.js

@@ -0,0 +1,35 @@
+// Phaedo capture — the merge-owner precedence predicate.
+//
+// Resolves open question Q3 of docs/roadmap/desktop-capture-deposit.md. A capture
+// surface deposits a signal delta to the `capture_to_owner` mailbox lane; exactly ONE
+// device drains and reconciles it. Which device is the owner is a presence-based
+// precedence ROLE, not a hardwired device:
+//
+//   1. phone       — if a phone is paired (canonical vault owner; re-broadcasts §5)
+//   2. extension   — else, if the extension is present (today's browser-primary user)
+//   3. mcp-local   — else (phone-less + browser-less desktop/CLI — the Claude Code dev)
+//
+// Anti-deadlock (the Q3 concern — "confirm the claim rule can't have BOTH yield"):
+// the order is TOTAL and MONOTONIC in presence. The top tier (phone) never yields;
+// each lower tier yields only when a STRICTLY HIGHER tier is present. So there is
+// always exactly one owner and never zero — "both yield" is unreachable. A pairing
+// still verifying counts as NOT present (fail toward the lower, always-available
+// tier), so the extension keeps owning until the phone's pairing is verified, then
+// yields; the brief two-owner overlap during that handoff is harmless because the
+// reconcile is per-source idempotent (Q2 / §3).
+
+export const TIERS = ['phone', 'extension', 'mcp-local'];
+
+// presence — { phonePaired?: bool, extensionPresent?: bool }. Unknown/undefined
+// treated as absent (fail toward the always-available mcp-local tier).
+export function resolveMergeOwner(presence = {}) {
+  if (presence.phonePaired) return 'phone';
+  if (presence.extensionPresent) return 'extension';
+  return 'mcp-local';
+}
+
+// Does `tier` own the capture lane given this presence? Exactly one tier is true for
+// any presence, so a drainer calls isOwner(myTier, presence) to decide whether to drain.
+export function isOwner(tier, presence = {}) {
+  return resolveMergeOwner(presence) === tier;
+}

package/vendor/capture/package.json

@@ -0,0 +1,4 @@
+{
+  "//": "Declares capture/*.js as ES modules so Node (the Claude Code capture hook, tests) can import them directly. Surface-agnostic Track-A capture contract: transcript parsing, source-id derivation, merge-owner precedence. Node-only; nothing here ships in the browser extension.",
+  "type": "module"
+}

package/vendor/capture/source-id.js

@@ -0,0 +1,56 @@
+// Phaedo capture — stable per-surface, per-MACHINE source device id.
+//
+// Resolves open question Q2 of docs/roadmap/desktop-capture-deposit.md. Every capture
+// surface tags its deposits with a `source_device_id`; the merge owner's per-source
+// idempotent reconcile (replace-that-source's-snapshot, never sum) depends on this id
+// being (a) STABLE across process restarts AND pairing changes, and (b) UNIQUE per
+// (machine, surface).
+//
+// The id is derived from a persistent random MACHINE id — NOT the pairing — for two
+// reasons the review surfaced:
+//   1. Pairing-derived ids CHANGE when the user pairs/re-pairs (or fixes a
+//      pairing.capture.json), so everything captured before that transition would be
+//      stranded under an orphaned key (unpaired→paired stranding).
+//   2. Two machines that export the SAME extension pairing (desktop + laptop, per the
+//      runbook) would derive the IDENTICAL pairing-based id and clobber each other's
+//      cumulative snapshots on the owner (replace-per-source under-counts).
+// A per-machine uuid persisted once in the state dir is stable across both, and
+// distinct per machine — so each machine's snapshot accumulates as its own source.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+function defaultMachineIdPath(env = process.env) {
+  const dir = env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return join(dir, 'machine-id');
+}
+
+// Read (or first-time create) the persistent per-machine id. Best-effort: if the
+// state dir is unwritable we fall back to a process-stable in-memory id (capture still
+// works for the session; only cross-restart stability is lost on a read-only FS).
+let _memMachineId = null;
+export function machineId(env = process.env) {
+  const path = defaultMachineIdPath(env);
+  try {
+    return readFileSync(path, 'utf8').trim() || createAndStore(path);
+  } catch {
+    return createAndStore(path);
+  }
+}
+function createAndStore(path) {
+  const id = randomUUID();
+  try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, id + '\n', 'utf8'); }
+  catch { if (!_memMachineId) _memMachineId = randomUUID(); return _memMachineId; }
+  return id;
+}
+
+// surface — a stable string naming the capture surface, e.g. 'claude-code' or 'a11y-macos'.
+// The `pairing` param is kept for signature compatibility with callers but is NO LONGER
+// used to derive the id (see the header): the id is per-machine + per-surface.
+export function deriveSourceDeviceId(_pairing, surface, env = process.env) {
+  const tag = String(surface || 'unknown');
+  const digest = createHash('sha256').update(`${machineId(env)} ${tag}`).digest('base64url');
+  return `cap_${tag}_${digest.slice(0, 16)}`;
+}

package/vendor/capture/state.js

@@ -0,0 +1,148 @@
+// Phaedo capture — cumulative per-surface counter state.
+//
+// delta-lift's idempotency contract requires that a deposited signal's
+// observation_count be the surface's CUMULATIVE total (reconcile REPLACES a
+// source='delta' signal on key match rather than summing). A hook run is
+// per-session, so the hook needs durable local state that accumulates counts
+// across sessions — this module is that state.
+//
+// Resume-safety: Claude Code fires SessionEnd more than once for the same
+// session (clear / resume / logout), and each firing re-processes the FULL
+// transcript. Counts are therefore stored PER SESSION and REPLACED on
+// re-processing (never added), so a resumed session can only update its own
+// contribution — no double-count. The cumulative total = baseline + Σ sessions;
+// old sessions are evicted into the baseline beyond a cap so the file stays small.
+//
+// Contains COUNTS ONLY — signal names and integers, never conversation text
+// (the discard-raw contract). Plaintext JSON is acceptable at this sensitivity
+// (same class as the extension's phaedo_behavioral_signals counters); the state
+// file lives in the MCP state dir (default ~/.phaedo-mcp/, 0600-style dir the
+// server already uses for its key + cache).
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const VERSION = 1;
+const DEFAULT_MAX_SESSIONS = 200;
+
+export function defaultStatePath(env = process.env) {
+  const dir = env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return join(dir, 'capture-state.json');
+}
+
+export function emptyState() {
+  return { version: VERSION, surfaces: {} };
+}
+
+// ── pure helpers ─────────────────────────────────────────────────────────────
+
+function emptyCounts() {
+  return { behavioral_signals: {}, positive_count: 0, mental_models: {}, message_count: 0 };
+}
+
+// counts + counts → counts. Robust to a malformed source (null, wrong shape, string
+// counters): a hand-edited or partially-written state file must never throw here — the
+// throw happens AFTER saveState in the hook, so it would re-persist the bad entry and
+// silently kill capture forever. Non-object sources are skipped; counters are coerced
+// to finite numbers (a stray string '7' can't corrupt the sum into '07').
+const num = (v) => (Number.isFinite(v) ? v : (Number.isFinite(Number(v)) ? Number(v) : 0));
+export function mergeCounts(a, b) {
+  const out = emptyCounts();
+  for (const src of [a, b]) {
+    if (!src || typeof src !== 'object') continue;
+    for (const [layer, sigs] of Object.entries(src.behavioral_signals || {})) {
+      if (!sigs || typeof sigs !== 'object') continue;
+      if (!out.behavioral_signals[layer]) out.behavioral_signals[layer] = {};
+      for (const [sig, n] of Object.entries(sigs)) {
+        out.behavioral_signals[layer][sig] = (out.behavioral_signals[layer][sig] || 0) + num(n);
+      }
+    }
+    for (const [fw, n] of Object.entries(src.mental_models || {})) {
+      out.mental_models[fw] = (out.mental_models[fw] || 0) + num(n);
+    }
+    out.positive_count += num(src.positive_count);
+    out.message_count += num(src.message_count);
+  }
+  return out;
+}
+
+// Record a session's counts for a surface, REPLACING any prior contribution from
+// the same sessionId (resume-safe). Evicts oldest sessions into the baseline
+// beyond maxSessions. Pure — returns a new state.
+//
+// Once a session is evicted its counts are frozen into the opaque baseline sum, which
+// can't be decomposed — so if that SAME session re-fires (SessionEnd on clear/resume of
+// a long-lived session outliving 200 others), re-adding it would DOUBLE-count it
+// permanently. We track evicted ids and skip a re-fire of one: its counts stay as
+// frozen in baseline (bounded staleness) rather than doubling. The evicted-id list is
+// itself capped; an id that ages out of it is doubly-rare to re-fire.
+export function applySession(state, sourceId, sessionId, counts, { now, maxSessions = DEFAULT_MAX_SESSIONS } = {}) {
+  const stamp = now || new Date().toISOString();
+  const prev = (state && state.surfaces) || {};
+  const surface = prev[sourceId] || { baseline: emptyCounts(), sessions: {}, evicted: [] };
+  const sid = String(sessionId || 'unknown');
+  const evicted = Array.isArray(surface.evicted) ? surface.evicted.slice() : [];
+  // Drop any malformed (null / non-object) session entry from a hand-edited file so the
+  // eviction sort below (sessions[x].updated_at) can't throw.
+  const priorSessions = {};
+  for (const [k, v] of Object.entries(surface.sessions || {})) if (v && typeof v === 'object') priorSessions[k] = v;
+
+  // A re-fire of an already-evicted session: don't re-add (its counts are in baseline).
+  if (evicted.includes(sid) && !priorSessions[sid]) {
+    return { version: VERSION, surfaces: { ...prev, [sourceId]: { ...surface, sessions: priorSessions, evicted, updated_at: stamp } } };
+  }
+
+  const sessions = { ...priorSessions, [sid]: { counts, updated_at: stamp } };
+
+  // Evict oldest (by updated_at) into baseline beyond the cap.
+  let baseline = surface.baseline || emptyCounts();
+  const ids = Object.keys(sessions);
+  if (ids.length > maxSessions) {
+    ids.sort((x, y) => String(sessions[x].updated_at).localeCompare(String(sessions[y].updated_at)));
+    for (const id of ids.slice(0, ids.length - maxSessions)) {
+      baseline = mergeCounts(baseline, sessions[id].counts);
+      delete sessions[id];
+      if (!evicted.includes(id)) evicted.push(id);
+    }
+  }
+  while (evicted.length > maxSessions) evicted.shift();   // bound the evicted-id list
+
+  return {
+    version: VERSION,
+    surfaces: { ...prev, [sourceId]: { baseline, sessions, evicted, updated_at: stamp } },
+  };
+}
+
+// The cumulative counts for a surface: baseline + Σ sessions. This is what the
+// hook lifts (observation_count = cumulative total, per delta-lift's contract).
+export function cumulativeCounts(state, sourceId) {
+  const surface = state && state.surfaces && state.surfaces[sourceId];
+  if (!surface) return emptyCounts();
+  // Run the baseline through mergeCounts too, so a malformed/hand-edited baseline (null,
+  // string counters) is sanitized rather than returned raw. A null/malformed session
+  // entry is skipped (mergeCounts ignores a non-object src; guard the `.counts` access).
+  let out = mergeCounts(emptyCounts(), surface.baseline);
+  for (const s of Object.values(surface.sessions || {})) out = mergeCounts(out, s && s.counts);
+  return out;
+}
+
+// ── IO (sync — the hook is a short-lived script) ─────────────────────────────
+
+// Missing or corrupt file → empty state (a broken state file must never break a
+// session or a capture; it just restarts the counters).
+export function loadState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed && parsed.version === VERSION && parsed.surfaces) return parsed;
+  } catch { /* fall through */ }
+  return emptyState();
+}
+
+// Atomic: temp file + rename (same pattern as the receipts/auth stores).
+export function saveState(path, state) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), 'utf8');
+  renameSync(tmp, path);
+}

package/vendor/capture/transcript.js

@@ -0,0 +1,184 @@
+// Phaedo capture — Claude Code transcript → exchange_batch.
+//
+// Track A of the desktop-capture plan (docs/roadmap/desktop-capture-helper.md):
+// the Claude Code / Cowork capture hook reads the local session JSONL and turns it
+// into the SAME exchange_batch the extension's Loop 2 produces (loop2-capture
+// buildBatchPayload shape), so the surface-agnostic extraction engine
+// (extraction/orchestrator.js) consumes it unchanged.
+//
+// Pure parsing only — no model, no network, no persistence. Raw transcript text
+// lives here only as the returned in-memory batch; the caller runs extraction and
+// discards it (the discard-raw contract, architecture/persona-vs-conversation-memory.md).
+//
+// Claude Code writes one JSON object per line to
+// ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. The fields we rely on are the
+// stable ones (type, timestamp, sessionId, message.role, message.content); the format
+// is internal and can drift, so every access is defensive and a malformed line is
+// skipped rather than thrown (a broken transcript must never corrupt the fingerprint).
+
+const PLATFORM = 'claude-code';
+
+// Pull plain text out of a message.content that is either a string or an array of
+// content blocks. Only 'text' blocks count — 'thinking', 'tool_use', 'tool_result'
+// and images are not conversational prose and are ignored.
+function contentText(content) {
+  if (typeof content === 'string') return content.trim();
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (block && block.type === 'text' && typeof block.text === 'string') parts.push(block.text);
+  }
+  return parts.join('\n').trim();
+}
+
+// A user line is a genuine subject prompt only when it is a real typed human turn.
+// EXCLUDES machine-authored records that Claude Code writes as user-role lines:
+//   - isMeta:true    — resume text ("Continue from where you left off"), slash-command
+//                      expansions, "[Request interrupted by user]", harness notices;
+//   - isSidechain:true — subagent (Task tool) turns, authored by the assistant;
+//   - isVisibleInTranscriptOnly / isCompactSummary — injected/synthetic context.
+// Without this filter the detectors mine documentation and harness text and fabricate
+// source='delta' signals that reach max confidence (the capture-review finding).
+function isMachineAuthored(rec) {
+  return !!(rec && (rec.isMeta || rec.isSidechain || rec.isVisibleInTranscriptOnly || rec.isCompactSummary));
+}
+function isUserPrompt(rec) {
+  return rec && rec.type === 'user' && rec.message && rec.message.role !== 'assistant'
+    && !isMachineAuthored(rec);
+}
+
+// WHO wrote a user-role line, when the transcript says (2026-10-20). Newer Claude Code writes
+// `origin` on user records: `{kind: "human"}` for a typed turn, another kind (e.g.
+// "task-notification") or null for text the app injects — CI-monitor events, background-task
+// notices, side-session reports. Those carry plain prose, so isMachineAuthored above let them
+// through and the detectors read an injected "do not stop to report" as the SUBJECT's
+// correction. Measured on the dev Mac since 2026-09-20: 363 human lines, 33 task notifications,
+// 21 unmarked lines in marked files (scripted probes) — all of the latter counted as Randy's.
+//   - a transcript that carries origin markers → only `kind: "human"` lines are the subject's;
+//   - a transcript with none (older format) → today's behaviour, minus prose that opens with an
+//     app envelope tag, which no person types.
+// Includes Phaedo's OWN injected profile (`<phaedo_user_profile>`, the SessionStart hook's
+// projection): it describes the subject in their words ("too long", "be concise"), so read as a
+// prompt it scored the profile as the subject correcting the AI — a loop feeding itself.
+const MACHINE_ENVELOPE = /^<(task-notification|ci-monitor-event|side-sessions-event|system-reminder|command-(name|message|args)|local-command-stdout|user-prompt-submit-hook|phaedo_user_profile|phaedo_fingerprint)\b/i;
+function hasOriginMarkers(recs) {
+  return recs.some((r) => r && r.type === 'user' && Object.prototype.hasOwnProperty.call(r, 'origin'));
+}
+function isSubjectAuthored(rec, text, marked) {
+  if (MACHINE_ENVELOPE.test(text)) return false;      // an app envelope is never typed, marked or not
+  if (marked) return !!(rec.origin && typeof rec.origin === 'object' && rec.origin.kind === 'human');
+  return true;
+}
+function isAssistant(rec) {
+  return rec && rec.type === 'assistant' && rec.message && !rec.isSidechain;
+}
+
+// The active conversation path only. The transcript is an append-only uuid/parentUuid
+// TREE: an esc-esc edit/rewind leaves the abandoned branch in the file alongside the
+// retry. A linear scan emits an exchange for EVERY branch, so one edited correction is
+// counted N times (the capture-review finding). We walk parentUuid from the leaf (the
+// last record — the most recent append is always on the live path) back to the root and
+// keep only that chain. Falls back to all records when the tree can't be reconstructed
+// (missing uuids / older format) so nothing breaks.
+function activePathRecords(recs) {
+  const byUuid = new Map();
+  for (const r of recs) if (r && r.uuid) byUuid.set(r.uuid, r);
+  // No usable tree → linear (current behavior, safe).
+  if (byUuid.size < 2) return recs;
+  let leaf = null;
+  for (let i = recs.length - 1; i >= 0; i--) { if (recs[i] && recs[i].uuid) { leaf = recs[i]; break; } }
+  if (!leaf) return recs;
+  const onPath = new Set();
+  let cur = leaf, guard = 0;
+  while (cur && guard++ < byUuid.size + 1) {
+    onPath.add(cur.uuid);
+    cur = cur.parentUuid ? byUuid.get(cur.parentUuid) : null;
+  }
+  // If the walk covered almost nothing (broken/mixed parent links), don't trust it.
+  if (onPath.size < 2) return recs;
+  return recs.filter((r) => !r || !r.uuid || onPath.has(r.uuid));
+}
+
+// Parse a raw JSONL string (or a pre-split array of lines) into records, skipping
+// blank and malformed lines. Exported for callers that already hold the text.
+export function parseJsonl(text) {
+  const lines = Array.isArray(text) ? text : String(text || '').split('\n');
+  const out = [];
+  for (const line of lines) {
+    const s = typeof line === 'string' ? line.trim() : '';
+    if (!s) continue;
+    try { out.push(JSON.parse(s)); } catch { /* skip a torn/partial line */ }
+  }
+  return out;
+}
+
+// Records → exchange_batch. Each user prompt is paired with the assistant text that
+// follows it (concatenated across multiple assistant lines) up to the next user
+// prompt. A trailing user prompt with no reply yet is dropped (incomplete exchange),
+// matching the web path's complete-only shipping.
+//   records — array already parsed (parseJsonl), or a raw JSONL string.
+//   opts.sessionId — override; otherwise taken from the first record's sessionId.
+// Returns { exchange_batch_version, session_local_id, exchanges: [...] }.
+export function recordsToBatch(records, opts = {}) {
+  const parsed = typeof records === 'string' ? parseJsonl(records) : (Array.isArray(records) ? records : []);
+  const recs = activePathRecords(parsed);   // drop abandoned edit/rewind branches
+  const sessionId = opts.sessionId
+    || recs.find((r) => r && r.sessionId)?.sessionId
+    || null;
+
+  const marked = hasOriginMarkers(recs);
+  const exchanges = [];
+  const user_prompts = [];                  // EVERY genuine user prompt (answered or not)
+  const user_prompt_times = [];             // parallel to user_prompts: each prompt's timestamp (or null)
+  let pending = null;                       // the open user prompt awaiting a reply
+  let replyParts = [];
+
+  const flush = () => {
+    if (pending && replyParts.length) {
+      const ai = replyParts.join('\n').trim();
+      if (ai) {
+        exchanges.push({
+          exchange_id: pending.id,
+          session_id: sessionId,
+          platform: PLATFORM,
+          timestamp: pending.timestamp,
+          user_msg: pending.text,
+          ai_response: ai,
+          delta_annotations: {},            // Path-A detector output is filled in by the caller (slice 2)
+        });
+      }
+    }
+    pending = null;
+    replyParts = [];
+  };
+
+  for (const rec of recs) {
+    if (isUserPrompt(rec)) {
+      const text = contentText(rec.message.content);
+      if (!text) continue;                  // tool_result-only user line — not prose
+      if (!isSubjectAuthored(rec, text, marked)) continue;   // app-injected prose — not the subject
+      // Pasted blocks are someone else's words — terminal output, a log, a document — that the
+      // subject quoted, not typed. The app wraps them; keep only what was typed around them.
+      const typed = text.replace(/<pasted_content\b[^>]*>[\s\S]*?<\/pasted_content\b[^>]*>/gi, ' ').trim();
+      if (!typed) continue;
+      flush();                              // close any previous exchange first
+      user_prompts.push(typed);             // count Path-A per SENT prompt (extension parity)
+      user_prompt_times.push(rec.timestamp || null);
+      pending = { id: rec.uuid || `ex-${exchanges.length}`, text: typed, timestamp: rec.timestamp || null };
+    } else if (isAssistant(rec) && pending) {
+      const text = contentText(rec.message.content);
+      if (text) replyParts.push(text);
+    }
+  }
+  flush();                                  // close the final exchange
+
+  // exchanges = COMPLETE pairs (for the future model/Loop-2 path); user_prompts = every
+  // sent prompt (for Path-A counters — the web path counts at SEND time, so an
+  // interrupted / unanswered correction must still count, unlike exchange shipping).
+  return { exchange_batch_version: 'v0.1', session_local_id: sessionId, exchanges, user_prompts, user_prompt_times };
+}
+
+// Convenience: raw JSONL text → batch in one call.
+export function transcriptToBatch(text, opts = {}) {
+  return recordsToBatch(parseJsonl(text), opts);
+}

package/vendor/commitments.js

@@ -0,0 +1,169 @@
+// §5.7 Commitments — decision STATE, projected into the §10.5 policy engine.
+//
+// The eight fingerprint layers are dispositional. Read the catalog: they model
+// response length, tone, iteration style, ambiguity posture, evidence threshold —
+// how a person decides. Even `temporal_and_context` is traits (early-project mode,
+// urgency baseline, working mode), not situation. And §4.6 forbids episodic content
+// in behavioral layers on purpose, so a behavioral model never quietly becomes a
+// dossier.
+//
+// That leaves a hole an agent acting on someone's behalf falls straight into. The
+// oracle can say "you would be cautious about this" when the true answer is "you
+// already decided this" — you already told that vendor no, you are on leave until
+// the 4th, that budget is frozen, you are mid-negotiation with those people. Style
+// without state is how a proxy contradicts the person it represents.
+//
+// Commitments fill exactly that hole and nothing more. They are NOT memory: no
+// recall, no retrieval, no conversation history. They are a short, authored,
+// always-expiring list of things that should change a DECISION, consumed only at
+// the consultation boundary.
+//
+// Three properties keep this from becoming a second product:
+//
+//   1. Authored only (§5.6). A producer MUST NOT infer a commitment. `source` is an
+//      enum of exactly `subject` so an inferred value is a schema violation.
+//   2. Deferential only. `effect` cannot be `autoproceed`. Being bound by something
+//      is never a reason to hand an agent more latitude; autonomy expansion has one
+//      path (§10.5 authorization via §10.7) and this is not it.
+//   3. Perishable. `expires_at` is REQUIRED. Decision state that outlives its
+//      situation silently blocks work forever, which is worse than not recording it.
+//
+// And they are never injected. The §9 projection is untouched — a commitment's text
+// is episodic by nature (it names counterparties and amounts), so it goes to the
+// consultation boundary, not into a context block that reaches a model verbatim.
+// Even there the statement is withheld unless the subject marked it `disclose`.
+//
+// This module is the projection into the §10.5 rule shape the resolver already
+// understands, which is what makes the whole feature small: precedence, expiry
+// enforcement, domain matching and the deterministic pre-flight all work unchanged.
+//
+// Loaded as a CLASSIC script in popup.html (globalThis.PhaedoCommitments) and
+// required by node tests + the MCP resolver — the dual pattern of sync-merge.js /
+// rule-review.js.
+
+(function () {
+  'use strict';
+
+  var EFFECTS = ['escalate', 'decline', 'bias_cautious'];
+  var KINDS = ['commitment', 'constraint'];
+
+  function uuid() {
+    return (typeof crypto !== 'undefined' && crypto.randomUUID)
+      ? crypto.randomUUID()
+      : 'cm-' + Math.random().toString(36).slice(2, 10);
+  }
+
+  function isObj(x) { return x !== null && typeof x === 'object' && !Array.isArray(x); }
+
+  // Live entries only. A lapsed commitment is inert — same fail-safe direction as a
+  // lapsed §10.5 authorization: authority narrows, never widens, when time passes.
+  function activeCommitments(fp, now) {
+    now = (now == null) ? Date.now() : now;
+    var list = (fp && Array.isArray(fp.commitments)) ? fp.commitments : [];
+    return list.filter(function (c) {
+      if (!isObj(c) || !c.statement || EFFECTS.indexOf(c.effect) === -1) return false;
+      var t = Date.parse(c.expires_at);
+      return Number.isFinite(t) && t > now;      // no expiry ⇒ NaN ⇒ inert (expires_at is required)
+    });
+  }
+
+  // The generic hint used when a commitment must not be disclosed. It tells the agent
+  // the truth — a standing decision covers this — without telling it WHAT the subject
+  // decided or with whom. That distinction is the point: an arbitrary agent learning
+  // "already told ACME no" is a disclosure, not a rationale.
+  var OPAQUE_NOTE = 'a standing commitment of yours covers this';
+
+  // Commitments → §10.5 policy rules. `disclose:false` (the default) substitutes the
+  // opaque note, so the resolver's existing "Per your standing rule: …" phrasing never
+  // leaks episodic text to a calling agent.
+  function commitmentsAsPolicies(fp, opts) {
+    opts = opts || {};
+    var now = (opts.now == null) ? Date.now() : opts.now;
+    return activeCommitments(fp, now).map(function (c) {
+      return {
+        id: c.commitment_id || null,
+        match: { domains: Array.isArray(c.domains) ? c.domains.filter(Boolean) : [] },
+        effect: c.effect,
+        note: c.disclose === true ? String(c.statement) : OPAQUE_NOTE,
+        expires_at: c.expires_at,
+        // Marks the rule as decision STATE rather than a standing policy. The resolver
+        // uses it for one thing: a `bias_cautious` commitment still says WHY it nudged.
+        // The generic "nudged per your preference" is fine for a disposition, but for a
+        // commitment it hides the only useful fact — that something the subject is
+        // currently bound by is in play.
+        rule_kind: 'commitment',
+      };
+    });
+  }
+
+  // Author a commitment (the subject's write — §5.6). Returns a NEW fingerprint, or
+  // the input unchanged when the entry would be invalid. Deliberately strict rather
+  // than coercing: a commitment that silently loses its expiry or its effect is a
+  // guardrail that quietly does nothing.
+  function addCommitment(fp, input, opts) {
+    opts = opts || {};
+    input = input || {};
+    var statement = String(input.statement == null ? '' : input.statement).trim();
+    if (!statement) return fp;
+    if (EFFECTS.indexOf(input.effect) === -1) return fp;
+    var t = Date.parse(input.expires_at);
+    if (!Number.isFinite(t)) return fp;
+    var now = opts.now || new Date().toISOString();
+    var entry = {
+      commitment_id: uuid(),
+      kind: KINDS.indexOf(input.kind) === -1 ? 'commitment' : input.kind,
+      statement: statement.slice(0, 500),
+      domains: Array.isArray(input.domains)
+        ? input.domains.map(function (d) { return String(d).trim(); }).filter(Boolean)
+        : [],
+      effect: input.effect,
+      disclose: input.disclose === true,
+      expires_at: new Date(t).toISOString(),
+      source: 'subject',
+      created_at: now,
+      updated_at: now,
+    };
+    var list = (fp && Array.isArray(fp.commitments)) ? fp.commitments : [];
+    var next = {};
+    for (var k in fp) if (Object.prototype.hasOwnProperty.call(fp, k)) next[k] = fp[k];
+    next.commitments = list.concat([entry]);
+    // Same signal authored rules use, so the §0008 sync merge keeps this device's write.
+    next.rules_updated_at = now;
+    return next;
+  }
+
+  // Remove one (the subject changed their mind, or it is done). Lapsed entries are
+  // ALSO dropped here — pruning on any write keeps the list from accumulating dead
+  // state without needing a background job.
+  function removeCommitment(fp, commitmentId, opts) {
+    opts = opts || {};
+    var now = opts.now || new Date().toISOString();
+    var list = (fp && Array.isArray(fp.commitments)) ? fp.commitments : [];
+    if (!list.length) return fp;
+    var nowMs = Date.parse(now);
+    var kept = list.filter(function (c) {
+      if (!isObj(c)) return false;
+      if (c.commitment_id === commitmentId) return false;
+      var t = Date.parse(c.expires_at);
+      return !(Number.isFinite(t) && Number.isFinite(nowMs) && t <= nowMs);
+    });
+    if (kept.length === list.length) return fp;
+    var next = {};
+    for (var k in fp) if (Object.prototype.hasOwnProperty.call(fp, k)) next[k] = fp[k];
+    next.commitments = kept;
+    next.rules_updated_at = now;
+    return next;
+  }
+
+  var api = {
+    EFFECTS: EFFECTS,
+    KINDS: KINDS,
+    OPAQUE_NOTE: OPAQUE_NOTE,
+    activeCommitments: activeCommitments,
+    commitmentsAsPolicies: commitmentsAsPolicies,
+    addCommitment: addCommitment,
+    removeCommitment: removeCommitment,
+  };
+  if (typeof globalThis !== 'undefined') globalThis.PhaedoCommitments = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();