@davesheffer/hunch 1.38.1 → 1.39.0

package/dist/cli/index.js

@@ -52,7 +52,7 @@ import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
-import { installPostCommitHook, installPreCommitHook, installPostMergeHook, hookStatus } from "../integrations/hooks.js";
+import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
@@ -78,7 +78,10 @@ import { deriveChangeProof } from "../core/changeProof.js";
 import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
 import { diffProjectDna } from "../core/projectDnaDelta.js";
 import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
-import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
+import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness, workspacesConfig } from "../core/config.js";
+import { loadOrCreateMachine, setMachineLabel, machineFile, labelLeaksIdentity } from "../core/machine.js";
+import { worktreeRows, branchRows } from "../core/workspace.js";
+import { workspaceLedgerView, recordWorkspaceSnapshot, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, prunePlanFor, renderPrunePlan, applyPrune, confirmPrune } from "../integrations/workspaceLedger.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { isHumanConfirmed } from "../core/strictgate.js";
 import { appendEvent, readEvents } from "../core/events.js";
@@ -393,6 +396,8 @@ program
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`);
         const pm = installPostMergeHook(root, inv.shell);
         console.log(`  ✓ post-merge hook ${pm.action} (squash-merge provenance repair + re-syncs grounding docs after a merge that brought memory in)`);
+        const pc = installPostCheckoutHook(root, inv.shell);
+        console.log(`  ✓ post-checkout hook ${pc.action} (workspace ledger: records this machine's branches + worktrees on checkout)`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
@@ -481,8 +486,11 @@ program
     // re-running init by hand. Gated on already having post-commit: `index`
     // is not a setup command (it runs in CI, on any git repo), so it must
     // never be what FIRST hooks a repo that never ran init at all.
-    if (isGitRepo(root) && hookStatus(root).postCommit)
-        installPostMergeHook(root, resolveInvocation().shell);
+    if (isGitRepo(root) && hookStatus(root).postCommit) {
+        const inv = resolveInvocation().shell;
+        installPostMergeHook(root, inv);
+        installPostCheckoutHook(root, inv); // same upgrade path for the workspace-ledger hook
+    }
     const res = indexRepo(store, root, { requireClean: true });
     const { counts } = store.reindex();
     const correctionSweep = new ConstitutionService(store, root).upgradeCorrections();
@@ -707,7 +715,7 @@ program
             const sweep = constitution.g2ShadowSweep();
             g2Recorded = sweep.recorded.length;
             if (!opts.quiet) {
-                console.log(`  ↳ G2 shadow: ${sweep.recorded.length} recorded · ${sweep.existing.length} existing · ${sweep.failures.length} failed; authority none`);
+                console.log(`  ↳ G2 shadow: ${sweep.recorded.length} recorded · ${sweep.existing.length} existing · ${sweep.failures.length} failed${sweep.retired.length ? ` · ${sweep.retired.length} retired (skipped)` : ""}; authority none`);
             }
         }
     }
@@ -1245,6 +1253,8 @@ function configureOverlay(dir, opts, mode) {
             hookNote = `  ✓ post-commit hook ${h.action} — captured decisions route here${opts.autoCommit ? " (auto-commit+push on)" : ""}\n`;
             const pm = installPostMergeHook(root, inv.shell);
             hookNote += `  ✓ post-merge hook ${pm.action} (squash-merge provenance repair + re-syncs grounding docs after a merge that brought memory in)\n`;
+            const pc = installPostCheckoutHook(root, inv.shell);
+            hookNote += `  ✓ post-checkout hook ${pc.action} (workspace ledger: this machine's branches + worktrees sync through the overlay)\n`;
         }
         // 5) one-time migration: MOVE existing public memory INTO the overlay, then make
         //    THIS repo code-only. Records are absorbed (union by id) BEFORE the public
@@ -1409,11 +1419,220 @@ program
             openStore = null;
         }
     }
+    // 4) the workspace ledger: the new worktree is exactly what other machines want to know about.
+    let ledgerNote = "";
+    try {
+        const lstore = openTeamStore(root).store;
+        try {
+            const out = recordWorkspaceSnapshot(lstore, root);
+            if (out.status === "written")
+                ledgerNote = `\n  ✓ workspace ledger updated (${out.record.worktrees.length} worktree(s) on this machine → ${out.home === "private" ? "overlay" : "public .hunch/"})`;
+        }
+        finally {
+            lstore.close();
+            openStore = null;
+        }
+    }
+    catch { /* the ledger is a side effect; the worktree itself is what this command promised */ }
     console.log(`✓ worktree created → ${dest}${opts.branch ? ` (new branch ${opts.branch})` : ""}\n` +
-        `${shareNote}${indexNote}\n` +
+        `${shareNote}${indexNote}${ledgerNote}\n` +
         `  hooks + MCP server are shared (worktree-aware) — open your assistant in the new worktree to start.\n` +
         `  (needs \`hunch\` installed globally; a worktree has no node_modules of its own)`);
 });
+// ---- workspaces / branches (workspace ledger — docs/workspace-ledger.md) ---------------
+// One shared code path (src/integrations/workspaceLedger.ts): this machine is always read
+// LIVE from git, other machines from the store, and stored records are display-only.
+const workspacesCmd = program
+    .command("workspaces")
+    .description("Workspace ledger: which worktrees are open on which machine (this machine live, other machines from memory). Read-only unless you run `snapshot`.");
+workspacesCmd
+    .command("list", { isDefault: true })
+    .description("Every worktree across machines: branch, dirty, last commit, when the machine last reported.")
+    .option("--machine <label>", "only this machine")
+    .option("--branch <name>", "only worktrees on this branch")
+    .option("--fetch", "run `git fetch --prune` first (network; off by default)")
+    .option("--json", "emit the rows as JSON")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (!isGitRepo(root))
+            return fail("`hunch workspaces` needs a git repo");
+        const view = workspaceLedgerView(store, root, { fetch: opts.fetch });
+        let rows = worktreeRows(view.records, { staleAfterDays: view.config.stale_after_days });
+        if (opts.machine)
+            rows = rows.filter((r) => r.machine === opts.machine);
+        if (opts.branch)
+            rows = rows.filter((r) => r.branch === opts.branch);
+        if (opts.json)
+            return console.log(JSON.stringify({ machine: view.machine.label, worktrees: rows }, null, 2));
+        console.log(renderWorktreeTable(view, rows));
+    }
+    finally {
+        store.close();
+    }
+});
+workspacesCmd
+    .command("snapshot")
+    .description("Record this machine's worktrees and branches into memory (the overlay when one is configured). Offline unless --fetch. Also run by the post-checkout / post-commit hooks and at MCP session start.")
+    .option("--fetch", "run `git fetch --prune` first (network; off by default)")
+    .option("--dry-run", "print the record that WOULD be written and write nothing")
+    .option("--json", "print the record as JSON")
+    .option("--quiet", "no output on success (for hooks)")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (!isGitRepo(root))
+            return fail("`hunch workspaces snapshot` needs a git repo");
+        const out = recordWorkspaceSnapshot(store, root, { fetch: opts.fetch, dryRun: opts.dryRun });
+        if (out.status !== "off" && (opts.dryRun || opts.json))
+            console.log(JSON.stringify(out.record, null, 2));
+        if (opts.quiet || out.status === "dry-run")
+            return;
+        switch (out.status) {
+            case "off":
+                return console.log("workspaces.publish is \"off\" in .hunch/config.json — nothing recorded.");
+            case "no-home":
+                console.log("No memory overlay is configured, so this machine's record is not written (queries read this machine live).");
+                console.log("  · run `hunch private` or `hunch shared --repo <url>` to sync workspaces across machines");
+                return console.log("  · or set .hunch/config.json {\"workspaces\":{\"publish_public\":true}} to commit it into this repo's .hunch/");
+            case "unchanged":
+                return console.log(`✓ unchanged since ${out.previous.observed_at} (${out.record.id}) — nothing written`);
+            case "collision":
+                return fail(`not written: ${out.reason}\n  · \`hunch workspaces forget ${out.record.id}\` removes the stale copy (a normal, revertable memory move), then snapshot again`);
+            case "written":
+                return console.log(`✓ recorded ${out.record.worktrees.length} worktree(s), ${out.record.branches.length} branch(es) as ${out.record.machine.label} (${out.record.id}, publish=${out.record.publish}) → ${out.home === "private" ? "overlay" : "public .hunch/"}${out.flushed ? `, ${out.flushed}` : ""}`);
+        }
+    }
+    finally {
+        store.close();
+    }
+});
+workspacesCmd
+    .command("prune")
+    .description("Branches and worktrees that are provably merged and safe to delete. Prints the exact git commands per machine (dry run). --apply runs them on THIS machine only — never a remote, never another machine — from a live snapshot, with `git branch -d` / `git worktree remove` (no force flags), after confirmation.")
+    .option("--apply", "execute this machine's commands (asks for confirmation; --yes in a non-interactive shell)")
+    .option("--yes", "skip the confirmation prompt (required with --apply when stdin is not a terminal)")
+    .option("--fetch", "run `git fetch --prune` first (network; off by default)")
+    .option("--json", "emit the plan (and results) as JSON")
+    .action(async (opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (!isGitRepo(root))
+            return fail("`hunch workspaces prune` needs a git repo");
+        const view = workspaceLedgerView(store, root, { fetch: opts.fetch });
+        const plan = prunePlanFor(view);
+        if (!opts.apply) {
+            if (opts.json)
+                return console.log(JSON.stringify({ machine: view.machine.label, plan }, null, 2));
+            console.log(renderPrunePlan(view, plan));
+            return console.log(plan.local.length ? "\n(dry run — `hunch workspaces prune --apply` runs this machine's commands after confirmation)" : "\n(dry run — nothing to apply on this machine)");
+        }
+        if (!plan.local.length) {
+            if (opts.json)
+                return console.log(JSON.stringify({ machine: view.machine.label, plan, results: [] }, null, 2));
+            console.log(renderPrunePlan(view, plan));
+            return console.log("\nnothing to apply on this machine");
+        }
+        if (!opts.json)
+            console.log(renderPrunePlan(view, plan));
+        if (!opts.yes) {
+            const worktrees = plan.local.filter((s) => s.worktree).length;
+            const ok = await confirmPrune(`Delete ${plan.local.length} branch(es)${worktrees ? ` and remove ${worktrees} worktree(s)` : ""} on ${view.machine.label}?`);
+            if (!ok)
+                return fail(process.stdin.isTTY ? "not confirmed — nothing was deleted" : "refusing to apply without confirmation: stdin is not a terminal; pass --yes to confirm explicitly");
+        }
+        const results = applyPrune(root, plan.local);
+        // Memory follows what actually happened: re-snapshot so other machines see the change.
+        // Best effort — the deletions above are real whatever the ledger write says.
+        let recorded;
+        try {
+            recorded = recordWorkspaceSnapshot(store, root).status;
+        }
+        catch (error) {
+            recorded = `failed: ${error.message}`;
+        }
+        if (opts.json)
+            return console.log(JSON.stringify({ machine: view.machine.label, plan, results, recorded }, null, 2));
+        console.log("");
+        for (const r of results)
+            console.log(`  ${r.outcome === "deleted" ? "✓" : "✗"} ${r.step.branch}: ${r.detail}`);
+        const failed = results.filter((r) => r.outcome === "failed").length;
+        const ledger = recorded === "written" ? " · ledger updated" : recorded === "unchanged" || recorded === "no-home" || recorded === "off" ? "" : ` · ledger not updated (${recorded})`;
+        console.log(`\n${results.length - failed} deleted, ${failed} refused by git${ledger}`);
+        if (failed)
+            process.exitCode = 1;
+    }
+    finally {
+        store.close();
+    }
+});
+workspacesCmd
+    .command("label [label]")
+    .description("Show or set this machine's label (what other machines see). Defaults to machine-<id>; never the hostname.")
+    .action((label) => {
+    const identity = label ? setMachineLabel(label) : loadOrCreateMachine();
+    console.log(`${identity.label}  (${identity.id}, ${machineFile()})`);
+    const leak = labelLeaksIdentity(identity.label);
+    if (leak)
+        console.log(`  ⚠ the label equals this machine's ${leak}; in a shared store every teammate sees it`);
+});
+workspacesCmd
+    .command("forget <machine>")
+    .description("Remove a machine's stored workspace record (by label or id) — e.g. a retired laptop. A memory move like any other: revertable via `hunch log`.")
+    .action((machine) => {
+    const { store, root } = storeFor();
+    try {
+        const victims = store.recs("workspaces").filter((r) => r.machine.label === machine || r.machine.id === machine || r.id === machine);
+        if (!victims.length)
+            return fail(`no workspace record for "${machine}" — \`hunch workspaces\` lists the machines in memory`);
+        // Decide each record's home BEFORE deleting it, then flush exactly those homes.
+        const homes = victims.map((v) => store.getPrivateRec("workspaces", v.id) ? "private" : "public");
+        for (const v of victims)
+            store.deleteWhereItLives("workspaces", v.id);
+        pumpMemoryHomes(store, root, homes, `hunch: forget workspace ${machine}`);
+        console.log(`✓ forgot ${victims.length} record(s) for ${machine}`);
+    }
+    finally {
+        store.close();
+    }
+});
+program
+    .command("branches")
+    .description("Every local branch across machines with a deterministic verdict: merged (ancestry / squash / rebase), pushed, dirty worktree, and a recommended action. Read-only; never deletes anything.")
+    .option("--merged", "only branches proven merged")
+    .option("--unpushed", "only branches with no upstream")
+    .option("--stale <days>", "only branches whose last commit is older than N days")
+    .option("--machine <label>", "only branches present on this machine")
+    .option("--fetch", "run `git fetch --prune` first (network; off by default)")
+    .option("--json", "emit the rows as JSON")
+    .action((opts) => {
+    const { store, root } = storeFor();
+    try {
+        if (!isGitRepo(root))
+            return fail("`hunch branches` needs a git repo");
+        const view = workspaceLedgerView(store, root, { fetch: opts.fetch });
+        const now = new Date();
+        let rows = branchRows(view.records, { staleAfterDays: view.config.stale_after_days, now });
+        if (opts.merged)
+            rows = rows.filter((r) => r.merged.status === "merged");
+        if (opts.unpushed)
+            rows = rows.filter((r) => r.upstream === null);
+        if (opts.machine)
+            rows = rows.filter((r) => r.machines.includes(opts.machine));
+        if (opts.stale) {
+            const days = Number(opts.stale);
+            if (!Number.isFinite(days) || days < 0)
+                return fail("--stale takes a number of days");
+            rows = rows.filter((r) => !r.last_commit_at || now.getTime() - Date.parse(r.last_commit_at) > days * 86_400_000);
+        }
+        if (opts.json)
+            return console.log(JSON.stringify({ machine: view.machine.label, branches: rows }, null, 2));
+        console.log(renderBranchTable(view, rows));
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- query ----------------------------------------------------------------
 program
     .command("query")
@@ -6502,6 +6721,10 @@ program
             console.log(`\n📊 ${rankingStatusLine(resolveTaskRankingMode(store.publicRoot, store))}`);
         }
         catch { /* no task records or no cache dir: nothing to say */ }
+        // Workspace ledger, from stored records only (no git) so the hot view stays fast.
+        const ws = workspaceSummaryLine(opts.private ? store.recs("workspaces") : store.json.loadAll("workspaces"), workspacesConfig(readConfig(hunchPaths(store.publicRoot))));
+        if (ws)
+            console.log(`\n${ws}`);
     }
     finally {
         store.close();
@@ -6770,6 +6993,17 @@ program
         console.log(`hooks:      ${missing.length
             ? `⚠ missing ${missing.join(", ")} — ${fix}`
             : `post-commit, post-merge installed${hooks.preCommit ? " (+ pre-commit)" : ""}`}`);
+        // Workspace ledger: what this machine is called, whether its record is in memory,
+        // and whether the checkout hook that keeps it fresh is installed.
+        try {
+            const machine = loadOrCreateMachine();
+            const stored = store.recs("workspaces").find((r) => r.machine.id === machine.id);
+            const others = store.recs("workspaces").filter((r) => r.machine.id !== machine.id).length;
+            const leak = labelLeaksIdentity(machine.label);
+            console.log(`workspaces: this machine is ${machine.label}${leak ? ` (⚠ label equals the ${leak})` : ""} · record in memory: ${stored ? `yes (${stored.observed_at})` : "no"} · ${others} other machine(s)` +
+                `${hooks.postCheckout ? " · post-checkout hook installed" : hooks.postCommit ? " · post-checkout hook not installed (`hunch index` adds it)" : ""}`);
+        }
+        catch { /* no machine file writable: nothing to report */ }
     }
     // In unified mode the public .hunch directory is only a routing shell.
     // Report the same effective manifest that `hunch migrate` reads and stamps,

package/dist/cli/serve.js

@@ -35,6 +35,7 @@ export function registerServeCommands(program) {
         app.listen(port, "127.0.0.1", () => {
             console.log(`hunch ${HUNCH_VERSION} serving nuryel.state/1 on http://127.0.0.1:${port} — ${config.partitions.map((p) => scopePath(p.scope)).join(", ")} (${config.principals.length} principal(s))`);
             console.log(`Shared state view: http://127.0.0.1:${port}/operator`);
+            console.log(`MCP (streamable HTTP): http://127.0.0.1:${port}/nuryel/v1/mcp`);
         });
         const stop = () => { app.close(() => { app.closeStores(); process.exit(0); }); };
         process.on("SIGINT", stop);

package/dist/client/readOrCompute.d.ts

@@ -0,0 +1,77 @@
+/**
+ * readOrCompute — the reuse rule every derived-state writer otherwise re-derives by hand, and
+ * gets wrong first. No dependencies beyond the platform: canonical JSON and WebCrypto SHA-256.
+ *
+ * Rules applied, in order (docs/nuryel-state-contract.md, "Read or compute"):
+ *  1. Read the subject. A current statement under the same transform whose dependency SET equals
+ *     the given one is reused and nothing is computed. The set, not the order: the server derives
+ *     a statement's identity from its dependency hashes sorted, so order never makes it new.
+ *  2. Otherwise run `compute` once and write the result as the subject's current statement.
+ *  3. The idempotency key names the REQUEST: subject, transform and dependencies, the content
+ *     hash, and computed_at. A key without the content hash is reused when the same evidence
+ *     yields new wording, and the contract refuses a reused key with another payload for good
+ *     (the pilot's stuck outbox).
+ *  4. `supersedes` names the current statement it replaces under the same transform; the server
+ *     keeps one current statement per subject and transform and refuses a second.
+ *  5. The audience carries forward: without an explicit `visibility` the new statement keeps the
+ *     one it supersedes (audiences are preserved across supersession). An explicit change sends
+ *     the predecessor's record hash as `expected_version`, which the server requires.
+ *  6. No retries. A refusal or a transport failure surfaces to the caller. Calling again re-reads
+ *     first, so a write that did land is reused instead of written twice.
+ */
+import type { DependencyRef, DerivedState, ReadResponse, RecordsResponse, Scope, WriteResult } from "../core/stateContract.js";
+/** What the helper needs from a client; `createStateClient` satisfies it. */
+export interface ReadOrComputeClient {
+    read(request: {
+        scope: Scope;
+        subject: string;
+        facets: ["derived"];
+    }): Promise<ReadResponse>;
+    records(request: {
+        scope: Scope;
+        ids: string[];
+    }): Promise<RecordsResponse>;
+    write(request: {
+        scope: Scope;
+        facet: "derived";
+        record: Record<string, unknown>;
+        idempotency_key: string;
+        supersedes?: string;
+        expected_version?: string;
+    }): Promise<WriteResult>;
+}
+export interface ComputedContent {
+    content: string;
+    field_provenance?: DerivedState["field_provenance"];
+}
+export interface ReadOrComputeRequest {
+    scope: Scope;
+    subject: string;
+    transform_version: string;
+    /** What the statement rests on; at least one. Equal sets reuse, whatever their order. */
+    dependencies: DependencyRef[];
+    provenance: DerivedState["provenance"];
+    /** Record audience. Omitted: the superseded statement's audience is kept. */
+    visibility?: DerivedState["visibility"];
+    /** Runs only when no current statement rests on exactly these dependencies. */
+    compute: () => string | ComputedContent | Promise<string | ComputedContent>;
+    /** ISO timestamp for computed_at; defaults to the clock. */
+    now?: () => string;
+}
+export type ReadOrComputeResult = {
+    reused: true;
+    record: DerivedState;
+    read_receipt: string;
+} | {
+    reused: false;
+    record: DerivedState;
+    write: WriteResult;
+    superseded: string | null;
+    read_receipt: string;
+};
+/** The server's canonical form (src/core/stateCanonical.ts): keys in code-unit order, undefined
+ *  dropped, non-finite numbers and `__proto__` refused. Kept in step by test. */
+export declare function canonicalJson(value: unknown): string;
+/** `sha256:<hex>` over the canonical form — the server's stateHash. */
+export declare function stateHash(value: unknown): Promise<string>;
+export declare function readOrCompute(client: ReadOrComputeClient, request: ReadOrComputeRequest): Promise<ReadOrComputeResult>;

package/dist/client/readOrCompute.js

@@ -0,0 +1,85 @@
+const DERIVED_SCHEMA = "nuryel.derived/1";
+/** The server's canonical form (src/core/stateCanonical.ts): keys in code-unit order, undefined
+ *  dropped, non-finite numbers and `__proto__` refused. Kept in step by test. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonical(value));
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical form rejects non-finite numbers");
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            if (key === "__proto__")
+                throw new Error("canonical form rejects reserved key __proto__");
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = canonical(v);
+        }
+        return out;
+    }
+    throw new Error(`canonical form rejects ${typeof value}`);
+}
+/** `sha256:<hex>` over the canonical form — the server's stateHash. */
+export async function stateHash(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(value)));
+    return `sha256:${Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+function dependencySet(dependencies) {
+    return dependencies.map(canonicalJson).sort().join("\n");
+}
+function sameScope(a, b) {
+    return !!a && a.kind === b.kind && a.id === b.id;
+}
+export async function readOrCompute(client, request) {
+    const { scope, subject, transform_version, dependencies, provenance } = request;
+    if (!Array.isArray(dependencies) || dependencies.length === 0)
+        throw new Error("readOrCompute: derived state needs at least one dependency (a statement nothing can invalidate is not state)");
+    const read = await client.read({ scope, subject, facets: ["derived"] });
+    const refs = (read.state_of_record?.current ?? []).filter((ref) => ref.facet === "derived" && sameScope(ref.scope, scope));
+    const recordHash = new Map(refs.map((ref) => [ref.id, ref.record_hash]));
+    let records = read.records ?? {};
+    const unseen = refs.map((ref) => ref.id).filter((id) => !records[id]);
+    // Hosts that predate `records` on the read answer by id instead.
+    if (unseen.length)
+        records = { ...records, ...(await client.records({ scope, ids: unseen })).records };
+    const current = refs
+        .map((ref) => records[ref.id])
+        .filter((r) => !!r && r.schema === DERIVED_SCHEMA && r.subject === subject && r.transform_version === transform_version && r.state === "current" && r.valid_to == null);
+    const wanted = dependencySet(dependencies);
+    const reusable = current.find((r) => dependencySet(r.dependencies) === wanted);
+    if (reusable)
+        return { reused: true, record: reusable, read_receipt: read.receipt_id };
+    const computed = await request.compute();
+    const { content, field_provenance } = typeof computed === "string" ? { content: computed, field_provenance: undefined } : computed;
+    if (typeof content !== "string" || content.length === 0)
+        throw new Error("readOrCompute: compute must return non-empty content");
+    const content_hash = await stateHash(content);
+    const computed_at = (request.now ?? (() => new Date().toISOString()))();
+    const incumbent = current.find((r) => dependencySet(r.dependencies) !== wanted) ?? null;
+    const statement = await stateHash({ scope, subject, transform_version, dependencies: dependencies.map(canonicalJson).sort() });
+    const idempotency_key = `derived:${statement.slice(7, 23)}:${content_hash.slice(7, 23)}:${computed_at}`;
+    const visibility = request.visibility !== undefined ? request.visibility : incumbent?.visibility;
+    const audienceChanges = !!incumbent && canonicalJson(incumbent.visibility ?? null) !== canonicalJson(visibility ?? null);
+    const record = {
+        ...(visibility ? { visibility } : {}),
+        schema: DERIVED_SCHEMA, scope, subject, content, content_hash, dependencies,
+        ...(field_provenance ? { field_provenance } : {}),
+        transform_version, computed_at, valid_to: null, state: "current", provenance,
+    };
+    const write = await client.write({
+        scope, facet: "derived", record, idempotency_key,
+        ...(incumbent ? { supersedes: incumbent.id } : {}),
+        ...(audienceChanges ? { expected_version: recordHash.get(incumbent.id) } : {}),
+    });
+    const stored = (write.record ?? { ...record, id: write.record_id });
+    return { reused: false, record: stored, write, superseded: incumbent?.id ?? null, read_receipt: read.receipt_id };
+}
+//# sourceMappingURL=readOrCompute.js.map

package/dist/client/state.d.ts

@@ -314,3 +314,4 @@ export declare function createStateClient(opts: StateClientOptions): {
     }>;
 };
 export type StateClient = ReturnType<typeof createStateClient>;
+export { readOrCompute, type ReadOrComputeClient, type ReadOrComputeRequest, type ReadOrComputeResult, type ComputedContent } from "./readOrCompute.js";

package/dist/client/state.js

@@ -62,4 +62,5 @@ export function createStateClient(opts) {
         health: () => call("GET", "/nuryel/v1/health"),
     };
 }
+export { readOrCompute } from "./readOrCompute.js";
 //# sourceMappingURL=state.js.map

package/dist/constitution/g2.d.ts

@@ -131,6 +131,7 @@ export interface G2ShadowSweepReport {
         policy_id: string;
         error: string;
     }>;
+    retired: string[];
     skipped_reason: string | null;
     authority: "none";
     effects: "shadow_only";

package/dist/constitution/service.js

@@ -677,6 +677,7 @@ export class ConstitutionService {
         const recorded = [];
         const existing = [];
         const failures = [];
+        const retired = [];
         if (manifest) {
             const before = new Set(this.repository.listShadowEvaluations({ privateOnly: true }).map((record) => record.id));
             for (const policyId of manifest.policy_ids) {
@@ -686,6 +687,12 @@ export class ConstitutionService {
                     if (!policy || publicDuplicate || this.repository.homeOfPolicy(policyId) !== "private" || policy.data_class === "public") {
                         throw new Error("selected policy is not in one exact private-only home");
                     }
+                    // A retired policy has closed its valid-time window: observing it again is
+                    // not evidence, only growth. Its recorded history stays untouched.
+                    if (policy.state === "retired") {
+                        retired.push(policyId);
+                        continue;
+                    }
                     const record = this.recordShadow(policyId, { now: opts.now });
                     if (before.has(record.id))
                         existing.push(record.id);
@@ -705,6 +712,7 @@ export class ConstitutionService {
             recorded: recorded.sort(),
             existing: existing.sort(),
             failures: failures.sort((left, right) => left.policy_id.localeCompare(right.policy_id)),
+            retired: retired.sort(),
             skipped_reason: manifest ? null : "No current private G2 plan; shadow sweep wrote nothing.",
             authority: "none",
             effects: "shadow_only",

package/dist/constitution/sourceMutation.js

@@ -93,16 +93,21 @@ function parsedSymbolFor(graphSymbol, parsed) {
     const base = symbolId(graphSymbol.file, graphSymbol.name, graphSymbol.kind);
     return matches.find((_symbol, index) => (index === 0 ? base : `${base}_${index}`) === graphSymbol.id) ?? null;
 }
-function spliceBytes(source, replacements) {
-    let bytes = Buffer.from(source, "utf8");
+/** `start`/`end` are JS string (UTF-16 code unit) indices. Despite their
+ *  names, parse.ts's startByte/endByte/atByte carry the same units — native
+ *  tree-sitter indexes the JS string it was handed, not its UTF-8 encoding —
+ *  so every scan and splice against them must be string-based, never Buffer-
+ *  based. */
+function spliceChars(source, replacements) {
+    let result = source;
     for (const replacement of [...replacements].sort((a, b) => b.start - a.start)) {
-        bytes = Buffer.concat([
-            bytes.subarray(0, replacement.start),
-            Buffer.from(replacement.text, "utf8"),
-            bytes.subarray(replacement.end),
-        ]);
+        result = result.slice(0, replacement.start) + replacement.text + result.slice(replacement.end);
     }
-    return bytes.toString("utf8");
+    return result;
+}
+/** Where a new top-level statement (an import) can be inserted without splitting a shebang line. */
+function insertionPoint(source) {
+    return source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
 }
 function mutateSource(policy, base, sourceFile, source) {
     const assertion = policy.assertion;
@@ -145,10 +150,10 @@ function mutateSource(policy, base, sourceFile, source) {
         const specifier = relativeSpecifier(sourceFile, targetFile);
         if (parsed.imports.some((candidate) => candidate === specifier))
             return { error: "mutation-component-import-already-present" };
-        const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+        const insertion = insertionPoint(source);
         return {
             file: sourceFile,
-            source: spliceBytes(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n` }]),
+            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n` }]),
         };
     }
     const subject = symbolForSelector(base, assertion.subject);
@@ -161,7 +166,7 @@ function mutateSource(policy, base, sourceFile, source) {
     if (!definition)
         return { error: "mutation-subject-definition-unresolved" };
     if (assertion.kind === "exists") {
-        return { file: subject.file, source: spliceBytes(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
+        return { file: subject.file, source: spliceChars(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
     }
     if (assertion.kind === "not-reaches"
         && assertion.relation.edges.length === 1
@@ -173,10 +178,10 @@ function mutateSource(policy, base, sourceFile, source) {
         if (parsed.imports.some((specifier) => externalPackage(specifier) === dependency)) {
             return { error: "mutation-forbidden-import-already-present" };
         }
-        const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+        const insertion = insertionPoint(source);
         return {
             file: subject.file,
-            source: spliceBytes(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n` }]),
+            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n` }]),
         };
     }
     const object = symbolForSelector(base, assertion.object);
@@ -193,19 +198,19 @@ function mutateSource(policy, base, sourceFile, source) {
             .map((call) => ({ start: call.atByte, end: call.endByte, text: "hunchMutationRemovedCall" }));
         if (!replacements.length)
             return { error: "mutation-required-call-unresolved" };
-        return { file: subject.file, source: spliceBytes(source, replacements) };
+        return { file: subject.file, source: spliceChars(source, replacements) };
     }
     if (!assertion.relation.edges.includes("calls"))
         return { error: "mutation-call-edge-not-supported" };
-    const bytes = Buffer.from(source, "utf8");
-    const open = bytes.indexOf("{".charCodeAt(0), definition.startByte);
+    // String search, matching definition.startByte/endByte's actual units -- see spliceChars' doc comment.
+    const open = source.indexOf("{", definition.startByte);
     if (open < 0 || open >= definition.endByte)
         return { error: "mutation-subject-body-unsupported" };
     const replacements = [{ start: open + 1, end: open + 1, text: `\n  ${object.name}(); // hunch deterministic source mutation\n` }];
     if (object.file !== subject.file) {
         const specifier = relativeSpecifier(subject.file, object.file);
         if (!parsed.imports.includes(specifier)) {
-            const insertion = source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+            const insertion = insertionPoint(source);
             replacements.push({
                 start: insertion,
                 end: insertion,
@@ -215,7 +220,7 @@ function mutateSource(policy, base, sourceFile, source) {
     }
     return {
         file: subject.file,
-        source: spliceBytes(source, replacements),
+        source: spliceChars(source, replacements),
     };
 }
 function removeWorktree(root, hooks, env, checkout) {