@izagood/avcs 0.1.0

package/dist/api/repo.js

@@ -0,0 +1,1772 @@
+// High-level repository facade.
+//
+// This is the single API surface that the CLI, the demo, and the MCP server all
+// call. It hides the object store and reducer behind verbs that map 1:1 onto the
+// agent workflow: intent → session → propose op → attach evidence → materialize →
+// decide → checkpoint.
+var _a;
+import { mkdir, writeFile, rm, readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { Buffer } from "node:buffer";
+import { ObjectStore } from "../store/objectStore.js";
+import { LamportClock } from "../core/clock.js";
+import { computeOid, sha256hex, canonicalize } from "../core/canonical.js";
+import { reduce, conflictIdFor, keysOf, detectCrossGranularity } from "../reducer/reducer.js";
+import { reduceIncremental, snapshotReduce, NonIncrementalError, serializeSnapshot, deserializeSnapshot } from "../reducer/incremental.js";
+import { encodeCbor, decodeCbor } from "../core/cbor.js";
+import { detectSemanticConflicts } from "../semantic/contract.js";
+import { computeReliability } from "../policy/reliability.js";
+import { defaultPolicy, MATERIALIZER_VERSION } from "../reducer/policy.js";
+import { Keyring, generateKeypair, signMessage, } from "../core/identity.js";
+import { checkLease, isActive } from "../concurrency/lease.js";
+import { Metrics } from "../observe/metrics.js";
+import { silentLogger } from "../observe/logger.js";
+// Sidecar: ignore EVERYTHING under .avcs/ (the `*` also ignores this file itself), so the
+// directory contributes nothing to git — the team's git history is untouched by AVCS.
+const GITIGNORE_SIDECAR = `# AVCS — sidecar mode (default).
+# AVCS history stays LOCAL; git tracks only the materialized projection, so adopting
+# AVCS needs no team decision. To commit the history team-wide once agreed, run:
+#   avcs git-mode committed
+*
+`;
+// Committed: track objects/refs/HEAD/config; ignore only rebuildable caches & local locks.
+// objects/ is immutable & content-addressed (distinct filenames ⇒ git unions cleanly).
+const GITIGNORE_COMMITTED = `# AVCS — committed mode.
+# objects/ and refs/ travel with the repo via git; only rebuildable caches & local
+# working state are ignored (regenerated by \`avcs reindex\` / lazy backfill).
+/indexes/
+/snapshot/
+/locks/
+/packs/
+/oplog
+/objlog
+/.git-pending
+*.lock
+*.tmp*
+`;
+export class Repo {
+    dir;
+    store;
+    keyring = new Keyring();
+    metrics = new Metrics();
+    /** Structured logger (silent by default; CLI/hub/MCP wire a console/OTel sink). */
+    logger = silentLogger();
+    #clock = new LamportClock();
+    // Warm in-memory caches (docs/11 A6). Operations are tailed from the append-only op-log
+    // (so a +1op materialize reads one new object, not every shard); blobs are content-
+    // addressed and immutable except via redaction, so they cache by oid. Both are pure
+    // optimizations over disk — correctness never depends on them, and they are cleared on
+    // the rare mutations that can invalidate them (gc deletes; redaction overwrites bytes).
+    #opCache = new Map();
+    #blobCache = new Map();
+    // Last full reduction's snapshot, for opt-in incremental reduce (docs/11 A6b). Only the
+    // main materialize path updates it; reduceIncremental is correct for ANY append-superset
+    // (harness-proven) and throws NonIncrementalError otherwise (→ fall back to full reduce),
+    // so no filter key is needed. Opt-in via AVCS_INCREMENTAL=1 (default off = full reduce);
+    // AVCS_VERIFY_INCREMENTAL=1 cross-checks every incremental result against a full reduce.
+    #incSnap = null;
+    #forceSnapshot = false; // set by compact() to capture a snapshot regardless of env flags
+    constructor(dir, store) {
+        this.dir = dir;
+        this.store = store;
+    }
+    static async init(dir) {
+        const store = new ObjectStore(dir);
+        await store.init();
+        const repo = new _a(dir, store);
+        // Seed the default policy and the `main` view if absent.
+        if (!(await store.getRef("policy"))) {
+            const policyOid = await store.put(defaultPolicy());
+            await store.setRef("policy", policyOid);
+        }
+        if (!(await store.getRef("view:main"))) {
+            const view = {
+                type: "view",
+                name: "main",
+                baseViewOid: null,
+                query: { includeStatuses: ["accepted"] },
+                createdAt: new Date().toISOString(),
+            };
+            const oid = await store.put(view);
+            await store.setRef("view:main", oid);
+        }
+        return repo;
+    }
+    static async open(dir) {
+        if (!ObjectStore.isRepo(dir)) {
+            throw new Error(`not an AVCS repo: ${dir} (run \`avcs init\`)`);
+        }
+        const store = new ObjectStore(dir);
+        const repo = new _a(dir, store);
+        // Re-seed the Lamport clock past the highest operation we've seen.
+        let max = 0;
+        for await (const op of store.list("operation"))
+            max = Math.max(max, op.lamport);
+        repo.#clock = new LamportClock(max);
+        await repo.#loadKeyring();
+        return repo;
+    }
+    async policy() {
+        const oid = await this.store.getRef("policy");
+        if (!oid)
+            return defaultPolicy();
+        return this.store.get(oid);
+    }
+    /** Replace the active policy (new version ⇒ a distinguishable checkpoint). */
+    async setPolicy(policy) {
+        const oid = await this.store.put(policy);
+        await this.store.setRef("policy", oid);
+        return oid;
+    }
+    /** Set code-owner rules (Phase 5), bumping the policy version. */
+    async setOwners(owners) {
+        const current = await this.policy();
+        return this.setPolicy({ ...current, owners, version: `${current.version}+owners`, createdAt: new Date().toISOString() });
+    }
+    /** actorId → learned reliability nudge, from history. */
+    async reliability() {
+        const ops = await this.store.collect("operation");
+        const evidence = this.#verifiedEvidence(await this.store.collect("evidence"));
+        const decisions = await this.store.collect("decision");
+        return computeReliability(ops, evidence, decisions);
+    }
+    // ── identity / keyring (Phase 3) ──────────────────────────────────────────
+    #keysDir() {
+        return join(this.store.root, "keys");
+    }
+    async #loadKeyring() {
+        const dir = this.#keysDir();
+        if (!existsSync(dir))
+            return;
+        for (const f of await readdir(dir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const rec = JSON.parse(await readFile(join(dir, f), "utf8"));
+            this.keyring.register(rec);
+        }
+    }
+    /** Persist a public key as trusted and load it into the keyring. */
+    async registerPublicKey(rec) {
+        await mkdir(this.#keysDir(), { recursive: true });
+        await writeFile(join(this.#keysDir(), `${rec.keyId}.json`), JSON.stringify(rec), "utf8");
+        this.keyring.register(rec);
+    }
+    /**
+     * Mint a keypair for an actor, register the public half as trusted, and return
+     * the private half for the caller to hold. (MVP: a real deployment keeps private
+     * keys with the actor, never in the repo.)
+     */
+    async generateActorKey(actor, keyId = actor.id) {
+        const { publicKey, privateKey } = generateKeypair();
+        await this.registerPublicKey({ keyId, publicKey, actorId: actor.id, actorKind: actor.kind });
+        return { keyId, privateKey, publicKey };
+    }
+    #sign(type, payload, signWith) {
+        if (!signWith)
+            return undefined;
+        const oid = computeOid(type, payload);
+        return { keyId: signWith.keyId, alg: "ed25519", sig: signMessage(signWith.privateKey, oid) };
+    }
+    // ── reading ──────────────────────────────────────────────────────────────
+    async readIntent(oid) {
+        return this.store.get(oid);
+    }
+    async listIntents() {
+        return this.store.collect("intent");
+    }
+    // ── authoring ──────────────────────────────────────────────────────────
+    async createIntent(args) {
+        const intent = {
+            type: "intent",
+            title: args.title,
+            owner: args.owner,
+            kind: args.kind ?? "feature",
+            priority: args.priority ?? "normal",
+            constraints: args.constraints ?? [],
+            constraintKinds: args.constraintKinds,
+            successCriteria: args.successCriteria ?? [],
+            allowedScopes: args.allowedScopes ?? [],
+            createdAt: new Date().toISOString(),
+        };
+        return this.store.put(intent);
+    }
+    async startSession(args) {
+        const session = {
+            type: "session",
+            intentOid: args.intentOid,
+            actor: args.actor,
+            baseViewOid: args.baseViewOid ?? (await this.store.getRef("view:main")),
+            summary: args.summary ?? "",
+            openedEntities: args.openedEntities ?? [],
+            toolCalls: [],
+            startedAt: new Date().toISOString(),
+        };
+        return this.store.put(session);
+    }
+    // Large blobs are chunked so a huge file never inflates one JSON object, and
+    // identical chunks dedup by content address. (Phase 9b)
+    static CHUNK_THRESHOLD = 256 * 1024;
+    static CHUNK_SIZE = 64 * 1024;
+    async putBlob(content) {
+        const data = Buffer.from(typeof content === "string" ? Buffer.from(content, "utf8") : content);
+        if (data.length <= _a.CHUNK_THRESHOLD) {
+            return this.store.put({ type: "blob", data: data.toString("base64"), encoding: "base64" });
+        }
+        const chunks = [];
+        for (let i = 0; i < data.length; i += _a.CHUNK_SIZE) {
+            const part = data.subarray(i, i + _a.CHUNK_SIZE);
+            chunks.push(await this.store.put({ type: "blob", data: part.toString("base64"), encoding: "base64" }));
+        }
+        return this.store.put({ type: "blob", data: "", encoding: "base64", chunked: true, chunks });
+    }
+    async readBlob(oid) {
+        const cached = this.#blobCache.get(oid);
+        if (cached)
+            return cached;
+        const blob = await this.store.get(oid);
+        const buf = blob.chunked && blob.chunks
+            ? Buffer.concat(await Promise.all(blob.chunks.map((c) => this.readBlob(c))))
+            : Buffer.from(blob.data, "base64");
+        this.#blobCache.set(oid, buf);
+        return buf;
+    }
+    /**
+     * All operations, tailed from the op-log (docs/11 A6): read only oids not already in
+     * the warm cache, in first-write order. Replaces a full `collect("operation")` shard
+     * scan on every materialize — a +1op materialize touches one new object file. Tolerates
+     * op-log entries whose object was GC'd (skips them; the store is the source of truth)
+     * and backfills the log for a store created before A5.
+     */
+    async #allOpsTailed() {
+        let log = await this.store.readOpLog();
+        if (log.length === 0) {
+            // Pre-A5 store (no log yet) — scan once, backfill the log, warm the cache.
+            const scanned = await this.store.collect("operation");
+            if (scanned.length === 0)
+                return [];
+            await this.store.rebuildOpLog();
+            for (const o of scanned)
+                this.#opCache.set(o.oid, o);
+            log = await this.store.readOpLog();
+        }
+        const ops = [];
+        for (const oid of log) {
+            let op = this.#opCache.get(oid);
+            if (!op) {
+                if (!(await this.store.has(oid)))
+                    continue; // GC'd since logged — skip
+                op = await this.store.get(oid);
+                this.#opCache.set(oid, op);
+            }
+            ops.push(op);
+        }
+        return ops;
+    }
+    async proposeOperation(args) {
+        const op = {
+            type: "operation",
+            sessionOid: args.sessionOid,
+            intentOid: args.intentOid,
+            actor: args.actor,
+            target: args.target,
+            body: args.body,
+            declaredPurpose: args.declaredPurpose,
+            causalDeps: args.causalDeps ?? [],
+            effects: args.effects,
+            lamport: this.#clock.tick(),
+            createdAt: new Date().toISOString(),
+            confidence: args.confidence,
+            // Only store `line` when it is non-default, so existing (line-less) repos and
+            // their oids stay byte-identical — backward compatibility with "main".
+            ...(args.line && args.line !== "main" ? { line: args.line } : {}),
+            ...(args.derivedFrom ? { derivedFrom: args.derivedFrom } : {}),
+            ...(args.revertOf ? { revertOf: args.revertOf } : {}),
+            ...(args.coAuthors && args.coAuthors.length ? { coAuthors: args.coAuthors } : {}),
+            ...(args.private ? { private: true } : {}),
+        };
+        op.sig = this.#sign("operation", op, args.signWith);
+        const oid = await this.store.put(op);
+        // Maintain the entity index (Phase 9): key → op oids for fast history/blame.
+        for (const key of keysOf({ ...op, oid }))
+            await this.store.appendEntityIndex(key, oid);
+        return oid;
+    }
+    /** Convenience: write file content as a blob + a put_file operation. */
+    async proposeFileWrite(args) {
+        const blobOid = await this.putBlob(args.content);
+        return this.proposeOperation({
+            sessionOid: args.sessionOid,
+            intentOid: args.intentOid,
+            actor: args.actor,
+            target: { entityKind: "file", entityId: args.path },
+            body: { kind: "put_file", path: args.path, blobOid },
+            declaredPurpose: args.declaredPurpose,
+            causalDeps: args.causalDeps,
+            effects: args.effects,
+            line: args.line,
+            signWith: args.signWith,
+        });
+    }
+    /**
+     * Phase 2: replace one named top-level symbol within a file. Two such edits to
+     * different symbols of the same file auto-merge. Should causally depend on the op
+     * that established the file (`causalDeps`) so reconstruction starts from it.
+     */
+    async proposeSymbolEdit(args) {
+        const blobOid = await this.putBlob(args.newText);
+        return this.proposeOperation({
+            sessionOid: args.sessionOid,
+            intentOid: args.intentOid,
+            actor: args.actor,
+            target: { entityKind: "symbol", entityId: `${args.path}#${args.symbolName}` },
+            body: { kind: "set_symbol", path: args.path, symbolName: args.symbolName, blobOid },
+            declaredPurpose: args.declaredPurpose,
+            causalDeps: args.causalDeps,
+            effects: args.effects,
+            line: args.line,
+            signWith: args.signWith,
+        });
+    }
+    /**
+     * M3 AST op: rename a top-level symbol (declaration + same-file references). Contends
+     * on both the old and new symbol keys. Should causally depend on the op that
+     * established the file. Cross-file references are a follow-up (needs reference analysis).
+     */
+    async proposeRenameSymbol(args) {
+        return this.proposeOperation({
+            sessionOid: args.sessionOid,
+            intentOid: args.intentOid,
+            actor: args.actor,
+            target: { entityKind: "symbol", entityId: `${args.path}#${args.from}` },
+            body: { kind: "rename_symbol", path: args.path, symbolName: args.from, newName: args.to },
+            declaredPurpose: args.declaredPurpose,
+            causalDeps: args.causalDeps,
+            line: args.line,
+        });
+    }
+    /**
+     * M3 AST op: move a top-level symbol from one file to another. Contends on the
+     * symbol at both source and destination. Cross-file references are a follow-up.
+     */
+    async proposeMoveSymbol(args) {
+        return this.proposeOperation({
+            sessionOid: args.sessionOid,
+            intentOid: args.intentOid,
+            actor: args.actor,
+            target: { entityKind: "symbol", entityId: `${args.fromPath}#${args.symbolName}` },
+            body: { kind: "move_symbol", fromPath: args.fromPath, path: args.toPath, symbolName: args.symbolName },
+            declaredPurpose: args.declaredPurpose,
+            causalDeps: args.causalDeps,
+            line: args.line,
+            signWith: args.signWith,
+        });
+    }
+    async attachEvidence(args) {
+        const ev = {
+            type: "evidence",
+            forOps: args.forOps,
+            kind: args.kind,
+            result: args.result,
+            producedBy: args.producedBy,
+            command: args.command,
+            detail: args.detail,
+            createdAt: new Date().toISOString(),
+            ...(args.fromUntrustedRunner ? { fromUntrustedRunner: true } : {}),
+        };
+        ev.sig = this.#sign("evidence", ev, args.signWith);
+        return this.store.put(ev);
+    }
+    async recordDecision(args) {
+        const dec = {
+            type: "decision",
+            conflictId: args.conflictId,
+            chosenOps: args.chosenOps,
+            rejectedOps: args.rejectedOps,
+            reason: args.reason,
+            decidedBy: args.decidedBy,
+            futurePolicy: args.futurePolicy,
+            createdAt: new Date().toISOString(),
+        };
+        dec.sig = this.#sign("decision", dec, args.signWith);
+        return this.store.put(dec);
+    }
+    // ── leases (Phase 3) ───────────────────────────────────────────────────────
+    async activeLeases() {
+        const now = new Date().toISOString();
+        return (await this.store.collect("lease")).filter((l) => isActive(l, now));
+    }
+    /**
+     * Request a soft write-lease over scopes. Returns the granted lease oid, or the
+     * conflicts that block it (overlapping active exclusive lease held by another).
+     */
+    async requestLease(args) {
+        const mode = args.mode ?? "exclusive";
+        // H-6: check-then-write under a lock so two concurrent requesters cannot both
+        // read "no conflict" and both acquire an overlapping exclusive lease (TOCTOU).
+        return this.store.withLock("leases", async () => {
+            const conflicts = checkLease({ writeScopes: args.writeScopes, mode, actorId: args.actor.id }, await this.activeLeases());
+            if (conflicts.length)
+                return { granted: false, conflicts };
+            const now = Date.now();
+            const lease = {
+                type: "lease",
+                intentOid: args.intentOid,
+                sessionOid: args.sessionOid,
+                actor: args.actor,
+                writeScopes: args.writeScopes,
+                mode,
+                acquiredAt: new Date(now).toISOString(),
+                expiresAt: new Date(now + (args.ttlMs ?? 30 * 60_000)).toISOString(),
+            };
+            return { granted: true, leaseOid: await this.store.put(lease) };
+        });
+    }
+    /** Build a minimal repair packet for ops whose validation failed. */
+    async repairContext(opOids) {
+        const { buildRepairContext } = await import("../validation/repair.js");
+        const ops = [];
+        for (const oid of opOids)
+            ops.push(await this.store.get(oid));
+        const evidence = await this.store.collect("evidence");
+        const decisions = await this.store.collect("decision");
+        return buildRepairContext(ops, evidence, decisions);
+    }
+    /**
+     * When a keyring is configured, trust must be earned by signature: evidence that
+     * claims a trusted (non-agent) producer is dropped unless it carries a valid
+     * signature for that actor. Forged or tampered evidence simply disappears, so the
+     * op it vouched for stays gated. With no keyring, fall back to the Phase-1
+     * producedBy heuristic (keep everything; the policy ignores agent self-reports).
+     */
+    #verifiedEvidence(all) {
+        if (this.keyring.size === 0)
+            return all;
+        return all.filter((e) => {
+            if (e.producedBy.kind === "ai_agent")
+                return true; // policy ignores these anyway
+            return this.keyring.verifyFor(e.producedBy.id, e.oid, e.sig);
+        });
+    }
+    // ── views & materialization ──────────────────────────────────────────────
+    async getView(name) {
+        const oid = await this.store.getRef(`view:${name}`);
+        if (!oid)
+            throw new Error(`no such view: ${name}`);
+        return this.store.get(oid);
+    }
+    async createView(name, query, baseViewOid = null) {
+        const view = {
+            type: "view",
+            name,
+            baseViewOid,
+            query,
+            createdAt: new Date().toISOString(),
+        };
+        const oid = await this.store.put(view);
+        await this.store.setRef(`view:${name}`, oid);
+        return oid;
+    }
+    // ── lineage (Phase 8) ──────────────────────────────────────────────────────
+    async #getLine(name) {
+        const oid = await this.store.getRef(`line:${name}`);
+        return oid ? this.store.get(oid) : null;
+    }
+    /** Oids inherited by a line: the causal closure of its fork checkpoint's frontier. */
+    async #inheritedOps(lineName, allOps) {
+        const line = await this.#getLine(lineName);
+        if (!line?.forkCheckpointOid)
+            return new Set();
+        const cp = await this.store.get(line.forkCheckpointOid);
+        const byId = new Map(allOps.map((o) => [o.oid, o]));
+        const seen = new Set();
+        const stack = [...cp.headOps];
+        while (stack.length) {
+            const id = stack.pop();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            for (const dep of byId.get(id)?.causalDeps ?? [])
+                if (!seen.has(dep))
+                    stack.push(dep);
+        }
+        return seen;
+    }
+    async listLines() {
+        return this.store.collect("line");
+    }
+    /**
+     * Fork a new line from `fromLine` at its current (or a given) checkpoint. The fork
+     * checkpoint freezes what the new line inherits; everything the base line does
+     * afterwards stays out of the new line. Also creates a same-named view selecting it.
+     */
+    async createLine(name, fromLine = "main", atCheckpointOid) {
+        if (await this.#getLine(name))
+            throw new Error(`line already exists: ${name}`);
+        const forkCheckpointOid = atCheckpointOid ?? (await this.createCheckpoint(fromLine, `fork point for line ${name}`));
+        const line = {
+            type: "line",
+            name,
+            baseLine: fromLine,
+            forkCheckpointOid,
+            createdAt: new Date().toISOString(),
+        };
+        const oid = await this.store.put(line);
+        await this.store.setRef(`line:${name}`, oid);
+        await this.createView(name, { includeStatuses: ["accepted"], line: name });
+        return oid;
+    }
+    /** Frontier (accepted head ops) of a line — the causalDeps a new op should build on. */
+    async lineFrontier(lineName) {
+        return (await this.materialize(lineName)).headOps;
+    }
+    /**
+     * Port (cherry-pick / backport) an operation onto another line: mint a NEW op on
+     * the target line carrying the source's body, based on the target line's current
+     * frontier, with `derivedFrom` provenance. set_symbol re-splices against the target
+     * line's content automatically at materialize; put_file replaces on the target line.
+     */
+    async portOp(sourceOpOid, targetLine, actor) {
+        const src = await this.store.get(sourceOpOid);
+        await this.getView(targetLine); // ensure the target line/view exists
+        return this.proposeOperation({
+            sessionOid: src.sessionOid,
+            intentOid: src.intentOid,
+            actor: actor ?? src.actor,
+            target: src.target,
+            body: src.body,
+            declaredPurpose: `backport ${sourceOpOid.slice(0, 16)} → ${targetLine}: ${src.declaredPurpose}`,
+            causalDeps: await this.lineFrontier(targetLine),
+            effects: src.effects,
+            line: targetLine,
+            derivedFrom: sourceOpOid,
+        });
+    }
+    // ── governance: membership, roles, protection, finalize (Phase 7) ──────────
+    static ROLE_WEIGHT = {
+        reader: 0,
+        proposer: 1,
+        reviewer: 2,
+        maintainer: 3,
+        admin: 4,
+    };
+    /** Issue a root-signed membership granting a role; registers the member's key. */
+    async registerMembership(args) {
+        const m = {
+            type: "membership",
+            actorId: args.actorId,
+            publicKey: args.publicKey,
+            role: args.role,
+            scopes: args.scopes,
+            issuedBy: args.root.keyId,
+            createdAt: new Date().toISOString(),
+        };
+        m.sig = this.#sign("membership", m, args.root);
+        const oid = await this.store.put(m);
+        await this.store.setRef(`member:${args.actorId}`, oid);
+        await this.registerPublicKey({ keyId: args.actorId, publicKey: args.publicKey, actorId: args.actorId, actorKind: args.actorKind ?? "ai_agent" });
+        return oid;
+    }
+    async membershipOf(actorId) {
+        const oid = await this.store.getRef(`member:${actorId}`);
+        if (!oid)
+            return null;
+        const m = await this.store.get(oid);
+        return m.revokedAt ? null : m;
+    }
+    async roleOf(actorId) {
+        return (await this.membershipOf(actorId))?.role ?? "reader";
+    }
+    async hasRole(actorId, min) {
+        return _a.ROLE_WEIGHT[await this.roleOf(actorId)] >= _a.ROLE_WEIGHT[min];
+    }
+    /** deciderId → role weight, for authority-weighted decision precedence (docs/08 §4). */
+    async #authorityMap() {
+        const m = new Map();
+        for (const mem of await this.store.collect("membership")) {
+            if (mem.revokedAt)
+                continue;
+            m.set(mem.actorId, _a.ROLE_WEIGHT[mem.role]);
+        }
+        return m;
+    }
+    /** Revoke a membership (admin only): future ops/decisions by this actor lose trust. */
+    async revokeMembership(actorId, byAdmin) {
+        if (!(await this.hasRole(byAdmin, "admin"))) {
+            throw new Error(`revoke requires role admin; ${byAdmin} is ${await this.roleOf(byAdmin)}`);
+        }
+        const m = await this.membershipOf(actorId);
+        if (!m)
+            return;
+        const revoked = { ...m, revokedAt: new Date().toISOString() };
+        delete revoked.oid;
+        revoked.sig = undefined;
+        const oid = await this.store.put(revoked);
+        await this.store.setRef(`member:${actorId}`, oid);
+    }
+    async setProtection(p) {
+        const protection = { type: "protection", ...p, createdAt: new Date().toISOString() };
+        const oid = await this.store.put(protection);
+        await this.store.setRef(`protection:${p.view}`, oid);
+        return oid;
+    }
+    async getProtection(view) {
+        const oid = await this.store.getRef(`protection:${view}`);
+        return oid ? this.store.get(oid) : null;
+    }
+    /** Current protected head (a checkpoint oid) of a view, or null if never finalized. */
+    async protectedHead(view) {
+        return this.store.getRef(`head:${view}`);
+    }
+    /**
+     * Finalize (= PR merge): advance a view's protected head to `newCheckpoint` via a
+     * compare-and-swap on `parentHead`. Rejects a stale (non-fast-forward) finalize
+     * even for admins unless allowForcePush — this is the causal-currency guard (docs/08
+     * §6/§9): authority never licenses overwriting fresher history.
+     */
+    async finalize(args) {
+        const result = await this.store.withLock(`finalize:${args.view}`, async () => {
+            const prot = await this.getProtection(args.view);
+            const current = await this.protectedHead(args.view);
+            // CAS / non-fast-forward check
+            if (current !== args.parentHead && !(prot?.allowForcePush)) {
+                return { finalized: false, reason: `head moved: ${current ?? "∅"} ≠ parent ${args.parentHead ?? "∅"} — pull and re-reduce first` };
+            }
+            // role gate
+            const minRole = prot?.finalizeRole ?? "maintainer";
+            if (prot && !(await this.hasRole(args.by, minRole))) {
+                return { finalized: false, reason: `${args.by} lacks role ${minRole} to finalize ${args.view}` };
+            }
+            // required checks — unless an active break-glass Override waives them (Phase 12)
+            const cp = await this.store.get(args.newCheckpoint);
+            const waived = await this.#activeWaivers(args.view);
+            for (const k of prot?.requiredChecks ?? []) {
+                if (cp.evidence[k] !== "pass" && !waived.has(k)) {
+                    return { finalized: false, reason: `required check ${k} not pass` };
+                }
+            }
+            // causal-complete gate (docs/08 C-3): never finalize a partially-synced tree —
+            // every causalDep behind the checkpoint's frontier must be present locally.
+            const missing = await this.#missingCausalDeps(cp.headOps);
+            if (missing.length) {
+                return { finalized: false, reason: `incomplete causal history: ${missing.length} object(s) missing — pull before finalizing` };
+            }
+            // required approvals (= PR approvals). A request_changes from any reviewer blocks.
+            if (prot && (prot.requiredApprovals > 0 || prot.requireOwnerApproval)) {
+                const verdict = await this.#approvalVerdicts(args.newCheckpoint);
+                if ([...verdict.values()].includes("request_changes")) {
+                    return { finalized: false, reason: "changes requested by a reviewer" };
+                }
+                const approvers = [...verdict].filter(([, v]) => v === "approve").map(([id]) => id);
+                if (approvers.length < prot.requiredApprovals) {
+                    return { finalized: false, reason: `needs ${prot.requiredApprovals} approval(s), have ${approvers.length}` };
+                }
+                if (prot.requireOwnerApproval) {
+                    let owner = false;
+                    for (const id of approvers)
+                        if (await this.hasRole(id, "maintainer")) {
+                            owner = true;
+                            break;
+                        }
+                    if (!owner)
+                        return { finalized: false, reason: "requires an owner (maintainer+) approval" };
+                }
+            }
+            await this.store.setRef(`head:${args.view}`, args.newCheckpoint);
+            return { finalized: true, head: args.newCheckpoint };
+        });
+        if (result.finalized) {
+            this.logger.info("finalize.accepted", { view: args.view, head: result.head, parentHead: args.parentHead, by: args.by });
+        }
+        else {
+            this.logger.warn("finalize.rejected", { view: args.view, by: args.by, reason: result.reason });
+        }
+        return result;
+    }
+    // ── security (Phase 12) ────────────────────────────────────────────────────
+    /**
+     * Redact (tombstone) a blob's bytes — for a leaked secret. Admin-only. The oid is
+     * preserved so all references and the treeHash stay valid; the plaintext is evicted
+     * from this store (and, once a real sync ships, propagated to every replica).
+     */
+    async redact(blobOid, reason, by, signWith) {
+        if (!(await this.hasRole(by, "admin"))) {
+            throw new Error(`redact requires role admin; ${by} is ${await this.roleOf(by)}`);
+        }
+        const blob = await this.store.get(blobOid);
+        const original = Buffer.from(blob.data, "base64");
+        const redaction = {
+            type: "redaction",
+            blobOid,
+            sha256: sha256hex(original),
+            length: original.length,
+            reason,
+            by,
+            createdAt: new Date().toISOString(),
+        };
+        // Sign so other replicas can verify it's a genuine admin redaction (not a forged
+        // DoS). Required when governance is active (see applyRedactions).
+        redaction.sig = this.#sign("redaction", redaction, signWith);
+        const redactionOid = await this.store.put(redaction);
+        // Evict the bytes: overwrite the blob in place with the (deterministic) stub.
+        const { redactedStub } = await import("../store/applyRedactions.js");
+        await this.store.overwriteAt(blobOid, redactedStub(reason, redactionOid));
+        this.#blobCache.delete(blobOid); // bytes changed under a stable oid — evict the cache
+        this.logger.warn("redact.applied", { blobOid, redactionOid, by, reason, length: original.length });
+        return redactionOid;
+    }
+    async #activeWaivers(view) {
+        const now = new Date().toISOString();
+        const out = new Set();
+        for (const o of await this.store.collect("override")) {
+            if (o.view === view && o.expiresAt > now)
+                for (const k of o.waiveChecks)
+                    out.add(k);
+        }
+        return out;
+    }
+    /** Break-glass: a maintainer/admin grants an expiring waiver of required checks. */
+    async grantOverride(args) {
+        if (!(await this.hasRole(args.by, "maintainer"))) {
+            throw new Error(`override requires role >= maintainer; ${args.by} is ${await this.roleOf(args.by)}`);
+        }
+        const o = {
+            type: "override",
+            view: args.view,
+            waiveChecks: args.waiveChecks,
+            reason: args.reason,
+            by: args.by,
+            expiresAt: new Date(Date.now() + (args.ttlMs ?? 30 * 60_000)).toISOString(),
+            createdAt: new Date().toISOString(),
+        };
+        return this.store.put(o);
+    }
+    /**
+     * Rollback a protected head to an earlier checkpoint — FORWARD-only: it advances the
+     * head (a new finalize CAS) to point at a prior state, never rewriting history.
+     */
+    async rollbackTo(view, checkpointOid, by) {
+        return this.finalize({ view, newCheckpoint: checkpointOid, parentHead: await this.protectedHead(view), by });
+    }
+    /** A reviewer approves (or requests changes on) a checkpoint. = PR approve. */
+    async approve(checkpointOid, by, verdict = "approve", opts = {}) {
+        if (!(await this.hasRole(by, "reviewer"))) {
+            throw new Error(`approve requires role >= reviewer; ${by} is ${await this.roleOf(by)}`);
+        }
+        const a = { type: "approval", checkpointOid, by, verdict, reason: opts.reason, createdAt: new Date().toISOString() };
+        a.sig = this.#sign("approval", a, opts.signWith);
+        return this.store.put(a);
+    }
+    /** Latest verdict per reviewer for a checkpoint (later canonical approval wins). */
+    async #approvalVerdicts(checkpointOid) {
+        const all = (await this.store.collect("approval"))
+            .filter((a) => a.checkpointOid === checkpointOid)
+            .sort((x, y) => (x.createdAt < y.createdAt ? -1 : x.createdAt > y.createdAt ? 1 : 0));
+        const out = new Map();
+        for (const a of all)
+            if (await this.hasRole(a.by, "reviewer"))
+                out.set(a.by, a.verdict);
+        return out;
+    }
+    /** Objects missing from the causal closure of a frontier (incomplete sync). */
+    async #missingCausalDeps(headOps) {
+        const seen = new Set();
+        const missing = [];
+        const stack = [...headOps];
+        while (stack.length) {
+            const id = stack.pop();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            if (!(await this.store.has(id))) {
+                missing.push(id);
+                continue;
+            }
+            const op = await this.store.get(id);
+            for (const d of op.causalDeps)
+                if (!seen.has(d))
+                    stack.push(d);
+        }
+        return missing;
+    }
+    // ── sync: object gossip between two stores (Phase 7) ───────────────────────
+    /**
+     * Pull objects from another repo's store into this one. Objects are append-only and
+     * content-addressed, so sync is a conflict-free union of whatever the other side has
+     * that we lack. `gate` (optional) lets a hub reject ops not signed by a known member.
+     * Returns counts. Refs (governance) are NOT synced — those are hub-authoritative.
+     */
+    async pull(otherDir, opts = {}) {
+        const other = new ObjectStore(otherDir);
+        let copied = 0;
+        let rejected = 0;
+        for await (const obj of other.list()) {
+            const oid = obj.oid;
+            if (await this.store.has(oid))
+                continue;
+            // Stash: private ops are local-only — never gossiped (Phase 7 follow-up).
+            if (obj.type === "operation" && obj.private)
+                continue;
+            if (opts.requireSignedMembers && obj.type === "operation") {
+                const op = obj;
+                const ok = this.keyring.verifyFor(op.actor.id, oid, op.sig) && (await this.hasRole(op.actor.id, "proposer"));
+                if (!ok) {
+                    rejected++;
+                    continue;
+                }
+            }
+            await this.store.put(obj);
+            if (obj.type === "operation")
+                for (const k of keysOf(obj))
+                    await this.store.appendEntityIndex(k, oid);
+            copied++;
+        }
+        // Propagate redactions: evict plaintext for any blob we already had before a peer
+        // redacted it (pull skips already-present oids, so the redaction must be applied).
+        await this.applyRedactions();
+        return { copied, rejected };
+    }
+    /** Apply all known redaction tombstones locally (evict bytes; oids preserved). */
+    async applyRedactions() {
+        const { applyRedactions } = await import("../store/applyRedactions.js");
+        const n = await applyRedactions(this.store);
+        if (n > 0)
+            this.#blobCache.clear(); // bytes changed under stable oids — evict the cache
+        return n;
+    }
+    /** Push objects this repo holds that a network hub lacks (M2 / docs/10 WS-B). */
+    async pushHub(hubUrl) {
+        const { pushToHub } = await import("../hub/hubClient.js");
+        return pushToHub(this.dir, hubUrl);
+    }
+    /** Request a finalize (= PR merge) on a network hub via its CAS endpoint (E6). */
+    async finalizeHub(hubUrl, args) {
+        const { finalizeOnHub } = await import("../hub/hubClient.js");
+        return finalizeOnHub(hubUrl, args);
+    }
+    /** Pull objects a network hub holds that this repo lacks. */
+    async pullHub(hubUrl) {
+        const { pullFromHub } = await import("../hub/hubClient.js");
+        const r = await pullFromHub(this.dir, hubUrl);
+        // pull may have applied redactions (blob bytes overwritten under stable oids) and
+        // wrote through a separate ObjectStore; drop the warm blob cache so reads re-hit disk.
+        this.#blobCache.clear();
+        return r;
+    }
+    /** Resolve a view's query into the candidate operation set, then reduce. */
+    async materialize(viewName = "main") {
+        this.metrics.inc("materialize.calls");
+        // Compaction (B3): on a cold instance, seed the incremental base from the persisted
+        // snapshot so this materialize re-reduces only ops added since it, not all history.
+        if (process.env.AVCS_COMPACT === "1" && !this.#incSnap)
+            await this.#loadPersistedSnapshot(viewName);
+        const view = await this.getView(viewName);
+        const q = view.query;
+        const exclude = new Set(q.excludeOps ?? []);
+        const intentFilter = q.intentOids && q.intentOids.length ? new Set(q.intentOids) : null;
+        const sessionFilter = q.sessionOids && q.sessionOids.length ? new Set(q.sessionOids) : null;
+        // Lineage (Phase 8): a line materializes its own ops + everything inherited from
+        // its fork checkpoint (the base line's frozen frontier). Ops authored on the base
+        // line AFTER the fork are excluded, which is what keeps lines divergent.
+        const lineName = q.line ?? "main";
+        const allOps = await this.#allOpsTailed();
+        const inherited = await this.#inheritedOps(lineName, allOps);
+        const ops = [];
+        for (const op of allOps) {
+            const onLine = (op.line ?? "main") === lineName || inherited.has(op.oid);
+            if (!onLine)
+                continue;
+            if (exclude.has(op.oid))
+                continue;
+            if (intentFilter && !intentFilter.has(op.intentOid))
+                continue;
+            if (sessionFilter && !sessionFilter.has(op.sessionOid))
+                continue;
+            ops.push(op);
+        }
+        // E4 (docs/13): hold back causally-incomplete ops. A push is N independent POSTs,
+        // so an op can arrive before its causalDeps (partial/out-of-order sync). Projecting
+        // it without its ancestor yields a transient WRONG tree (the reducer would otherwise
+        // treat the missing dep as an absent edge and apply the op anyway). We exclude any op
+        // a dep of which is absent from the store entirely, transitively. For a complete op
+        // set nothing is held back, so determinism for settled history is unchanged.
+        const present = new Set(allOps.map((o) => o.oid));
+        const { complete, pending } = this.#causallyComplete(ops, present);
+        if (pending.length) {
+            this.metrics.inc("materialize.causallyPending", pending.length);
+            this.logger.info("materialize.pending", { view: viewName, pending: pending.length });
+        }
+        // Phase 11: in a governed repo, ops authored by non-members (outsiders) are
+        // quarantined — excluded from the materialized tree until a reviewer promotes them.
+        const { kept, quarantined } = await this.#partitionQuarantine(complete);
+        const res = await this.#reduceOpSet(kept, q.includeStatuses, true); // main path: opt-in incremental
+        for (const oid of quarantined)
+            res.statuses.set(oid, "quarantined");
+        return res;
+    }
+    /**
+     * Partition candidate ops into those whose transitive causalDeps are all PRESENT in
+     * the store vs those still waiting on a missing dep (E4). A dep absent from the store
+     * entirely (`!present.has`) makes its dependents incomplete; incompleteness propagates.
+     * A dep that exists in the store but isn't a candidate here (e.g. another line) counts
+     * as satisfied — only genuinely-unsynced deps hold an op back, so no false holdback.
+     */
+    #causallyComplete(candidates, present) {
+        const byId = new Map(candidates.map((o) => [o.oid, o]));
+        const memo = new Map();
+        const ok = (oid) => {
+            const cached = memo.get(oid);
+            if (cached !== undefined)
+                return cached;
+            if (!present.has(oid))
+                return false; // dep never arrived
+            const op = byId.get(oid);
+            if (!op)
+                return true; // present in the store but not a candidate (other line) — satisfied
+            memo.set(oid, true); // cycle guard (an append-only DAG has none)
+            for (const d of op.causalDeps)
+                if (!ok(d)) {
+                    memo.set(oid, false);
+                    return false;
+                }
+            memo.set(oid, true);
+            return true;
+        };
+        const complete = [];
+        const pending = [];
+        for (const op of candidates)
+            (ok(op.oid) ? complete : pending).push(op);
+        return { complete, pending };
+    }
+    /** Split ops into kept vs quarantined (outsider, not-yet-promoted) for a governed repo. */
+    async #partitionQuarantine(ops) {
+        const memberships = await this.store.collect("membership");
+        if (memberships.length === 0)
+            return { kept: ops, quarantined: new Set() }; // governance off
+        const members = new Set(memberships.filter((m) => !m.revokedAt).map((m) => m.actorId));
+        const promoted = new Set((await this.store.collect("promotion")).flatMap((p) => p.ops));
+        const kept = [];
+        const quarantined = new Set();
+        for (const op of ops) {
+            if (!members.has(op.actor.id) && !promoted.has(op.oid))
+                quarantined.add(op.oid);
+            else
+                kept.push(op);
+        }
+        return { kept, quarantined };
+    }
+    /** List currently-quarantined ops (outsider contributions awaiting review). */
+    async quarantinedOps(line = "main") {
+        const res = await this.materialize(line);
+        return [...res.statuses].filter(([, s]) => s === "quarantined").map(([oid]) => oid);
+    }
+    /**
+     * Phase 11: a non-member (external contributor) submits an op. It self-signs and
+     * lands quarantined. Admission control caps outstanding outsider ops per actor.
+     */
+    async proposeOutsider(args) {
+        const cap = args.maxOutstanding ?? 50;
+        const mine = (await this.store.collect("operation")).filter((o) => o.actor.id === args.actor.id);
+        if (mine.length >= cap)
+            throw new Error(`admission cap (${cap}) reached for outsider ${args.actor.id}`);
+        return this.proposeOperation(args);
+    }
+    /** A reviewer promotes quarantined outsider ops into the normal accepted flow. */
+    async promote(opOids, byActor, reason) {
+        if (!(await this.hasRole(byActor, "reviewer"))) {
+            throw new Error(`promote requires role >= reviewer; ${byActor} is ${await this.roleOf(byActor)}`);
+        }
+        const p = { type: "promotion", ops: opOids, by: byActor, reason, createdAt: new Date().toISOString() };
+        const oid = await this.store.put(p);
+        this.logger.info("promote", { promotionOid: oid, ops: opOids.length, by: byActor, reason });
+        return oid;
+    }
+    /**
+     * Revert an op: a forward-only inverse. Restores the op's file to its pre-op content
+     * (or deletes it if it didn't exist before) as a NEW op with `revertOf` provenance —
+     * append-only, recorded, itself revertable. File-granular in the MVP.
+     */
+    async revert(opOid, actor, line = "main") {
+        const target = await this.store.get(opOid);
+        const path = target.body.path ?? target.target.entityId.split("#")[0];
+        const before = await this.materializeAt(target.causalDeps);
+        const prev = (await this.materializedFiles(before)).find((f) => f.path === path);
+        const causalDeps = await this.lineFrontier(line);
+        const common = {
+            sessionOid: target.sessionOid,
+            intentOid: target.intentOid,
+            actor,
+            declaredPurpose: `revert ${opOid.slice(0, 16)}: ${target.declaredPurpose}`,
+            causalDeps,
+            line,
+            revertOf: opOid,
+        };
+        if (prev === undefined) {
+            return this.proposeOperation({ ...common, target: { entityKind: "file", entityId: path }, body: { kind: "delete_file", path } });
+        }
+        return this.proposeOperation({
+            ...common,
+            target: { entityKind: "file", entityId: path },
+            body: { kind: "put_file", path, blobOid: await this.putBlob(prev.content) },
+        });
+    }
+    /**
+     * Reduce an explicit operation set (with the semantic-conflict 2-pass). Shared by
+     * `materialize` (view-selected ops) and `materializeAt` (a frontier's closure).
+     */
+    // M1: cache reduction results keyed on a signature of the inputs. reduce() is a
+    // pure function of (ops, evidence, decisions, policy, materializer), so identical
+    // inputs ⇒ identical result — we skip the grouping/eval/semantic-2-pass/blob-load
+    // cost on repeat calls (the hundreds-of-agents-re-materialize case, and CLI/MCP
+    // repeats). A clone is returned so callers can mutate without corrupting the cache.
+    #reduceCache = new Map();
+    static REDUCE_CACHE_MAX = 64;
+    #cloneResult(r) {
+        return {
+            tree: new Map(r.tree),
+            treeHash: r.treeHash,
+            statuses: new Map(r.statuses),
+            conflicts: r.conflicts.map((c) => ({ ...c })),
+            autoDecisions: r.autoDecisions.map((a) => ({ ...a })),
+            semanticConflicts: r.semanticConflicts.map((s) => ({ ...s })),
+            headOps: [...r.headOps],
+            synthBlobs: new Map(r.synthBlobs),
+        };
+    }
+    /**
+     * Pass-1 reduce (docs/11 A6b). With AVCS_INCREMENTAL=1 and a prior snapshot, re-reduce
+     * only the delta via `reduceIncremental` (falling back to a full `snapshotReduce` if the
+     * preconditions don't hold — e.g. policy changed, or `base` is not an append-superset of
+     * the snapshot). Default (flag off) is the plain full `reduce`, untouched. Only the main
+     * materialize path passes `useInc`, so subset reducers (materializeAt/history/bisect)
+     * never read or pollute the snapshot. AVCS_VERIFY_INCREMENTAL=1 cross-checks each
+     * incremental result against a full reduce and throws on any divergence (CI safety net).
+     */
+    #pass1Reduce(base, useInc) {
+        // Opt-in incremental: AVCS_INCREMENTAL (warm in-process delta), AVCS_COMPACT (cold start
+        // from a persisted snapshot base, B3), or compact() capturing a fresh snapshot.
+        const optIn = useInc && (process.env.AVCS_INCREMENTAL === "1" || process.env.AVCS_COMPACT === "1" || this.#forceSnapshot);
+        if (!optIn)
+            return reduce(base);
+        let snap;
+        if (this.#incSnap) {
+            try {
+                snap = reduceIncremental(this.#incSnap, base);
+            }
+            catch (e) {
+                if (!(e instanceof NonIncrementalError))
+                    throw e;
+                snap = snapshotReduce(base);
+                this.metrics.inc("reduce.incremental.fallback");
+            }
+        }
+        else {
+            snap = snapshotReduce(base);
+        }
+        if (process.env.AVCS_VERIFY_INCREMENTAL === "1") {
+            this.#assertReduceEqual(snap.result, snapshotReduce(base).result);
+        }
+        this.#incSnap = snap;
+        return snap.result;
+    }
+    /** Throw if an incremental reduction diverges from the full one (treeHash/statuses/
+     *  conflicts/headOps) — incremental reduce must NEVER break the determinism invariant. */
+    #assertReduceEqual(inc, full) {
+        // canonicalize (recursive key-sort) so the compare is key-order-insensitive — a
+        // CBOR-deserialized base (B3) yields sorted-key objects vs freshly-built insertion
+        // order, which are logically identical.
+        const norm = (r) => canonicalize({
+            treeHash: r.treeHash,
+            statuses: [...r.statuses].sort(),
+            conflicts: r.conflicts,
+            autoDecisions: r.autoDecisions,
+            headOps: [...r.headOps].sort(),
+            synth: [...r.synthBlobs.keys()].sort(),
+        });
+        if (norm(inc) !== norm(full)) {
+            throw new Error(`incremental reduce diverged from full reduce (treeHash inc=${inc.treeHash} full=${full.treeHash}) — determinism invariant violated`);
+        }
+    }
+    async #reduceOpSet(ops, includeStatuses, useInc = false) {
+        const evidence = this.#verifiedEvidence(await this.store.collect("evidence"));
+        const decisions = await this.store.collect("decision");
+        // Redactions overwrite blob bytes while keeping the oid, so they don't change op
+        // oids — include them in the signature so a redaction invalidates the cache.
+        const redactions = await this.store.collect("redaction");
+        const sig = sha256hex([
+            ops.map((o) => o.oid).sort().join(","),
+            evidence.map((e) => e.oid).sort().join(","),
+            decisions.map((d) => d.oid).sort().join(","),
+            redactions.map((r) => r.oid).sort().join(","),
+            // memberships affect authority-weighted decisions → invalidate on change
+            (await this.store.collect("membership")).map((m) => m.oid).sort().join(","),
+            (await this.store.getRef("policy")) ?? "default",
+            MATERIALIZER_VERSION,
+            (includeStatuses ?? []).join("+"),
+        ].join("|"));
+        const hit = this.#reduceCache.get(sig);
+        if (hit) {
+            this.metrics.inc("reduce.cache.hit");
+            return this.#cloneResult(hit);
+        }
+        this.metrics.inc("reduce.cache.miss");
+        const result = await this.metrics.time("reduce.ms", () => this.#reduceOpSetUncached(ops, includeStatuses, evidence, decisions, useInc));
+        if (this.#reduceCache.size >= _a.REDUCE_CACHE_MAX) {
+            this.#reduceCache.delete(this.#reduceCache.keys().next().value);
+        }
+        this.#reduceCache.set(sig, result);
+        return this.#cloneResult(result);
+    }
+    async #reduceOpSetUncached(ops, includeStatuses, evidence, decisions, useInc = false) {
+        const intents = new Map();
+        for await (const it of this.store.list("intent"))
+            intents.set(it.oid, it);
+        // Preload blob content needed by content-aware ops (set_symbol reconstructs text).
+        const blobContent = new Map();
+        for (const op of ops) {
+            const oid = op.body.blobOid;
+            if (oid && !blobContent.has(oid))
+                blobContent.set(oid, (await this.readBlob(oid)).toString("utf8"));
+        }
+        const policy = await this.policy();
+        const reliability = computeReliability(ops, evidence, decisions);
+        const authority = await this.#authorityMap();
+        const base = { ops, evidence, decisions, intents, policy, materializeStatuses: includeStatuses, blobContent, reliability, authority };
+        const pass1 = this.#pass1Reduce(base, useInc);
+        // Second-pass conflicts that the text-clean grouping accepted but that must be
+        // held back (re-reduce excluding them so the tree stays safe — base content falls
+        // back in automatically): (a) Phase-4 semantic contract breaks, and (b) the
+        // cross-granularity determinism hole — a whole-file op concurrent with a symbol
+        // edit on the same file (found by the determinism harness).
+        const semantic = detectSemanticConflicts(ops, pass1, evidence, blobContent);
+        const cross = detectCrossGranularity(ops, pass1);
+        if (semantic.length === 0 && cross.length === 0)
+            return pass1;
+        const held = new Set([...semantic.map((s) => s.breakingOp), ...cross.flatMap((c) => c.ops)]);
+        const pass2 = reduce({ ...base, ops: ops.filter((o) => !held.has(o.oid)) });
+        for (const s of semantic) {
+            pass2.statuses.set(s.breakingOp, "needs_decision");
+            for (const d of s.dependentOps)
+                pass2.statuses.set(d, pass2.statuses.get(d) ?? "needs_decision");
+        }
+        for (const oid of cross.flatMap((c) => c.ops))
+            pass2.statuses.set(oid, "needs_decision");
+        pass2.semanticConflicts = semantic;
+        for (const s of semantic) {
+            pass2.conflicts.push({
+                id: `conflict_sem_${(s.symbol.split("#")[1] ?? s.symbol).slice(0, 16)}`,
+                key: `contract:${s.symbol}`,
+                kind: "needs_human",
+                reason: s.reason,
+                recommendedOp: null,
+                options: [s.breakingOp, ...s.dependentOps].map((oid) => ({
+                    opOid: oid, actor: "", purpose: oid === s.breakingOp ? "contract change" : "depends on old contract",
+                    evidence: [], score: 0, blocked: false, requiresHuman: true,
+                })),
+            });
+        }
+        for (const c of cross) {
+            pass2.conflicts.push({
+                id: conflictIdFor(`file:${c.file}`),
+                key: `file:${c.file}`,
+                kind: "concurrent_write",
+                reason: `whole-file write and symbol edit on ${c.file} are concurrent — can't both apply deterministically`,
+                recommendedOp: null,
+                options: c.ops.map((oid) => ({ opOid: oid, actor: "", purpose: "concurrent whole-file/symbol edit", evidence: [], score: 0, blocked: false, requiresHuman: false })),
+            });
+        }
+        return pass2;
+    }
+    // ── git-like working tree (checkout / commit) ─────────────────────────────
+    /** Read a working directory's files (relative paths → content), skipping .avcs/. */
+    async #readWorkTree(workDir) {
+        const out = new Map();
+        if (!existsSync(workDir))
+            return out;
+        for (const ent of await readdir(workDir, { recursive: true, withFileTypes: true })) {
+            if (!ent.isFile())
+                continue;
+            const rel = join(ent.parentPath ?? ent.path ?? workDir, ent.name).slice(workDir.length + 1);
+            if (rel.startsWith(".avcs") || rel === ".avcs-workspace" || rel.startsWith(".git"))
+                continue;
+            out.set(rel.split("\\").join("/"), await readFile(join(workDir, rel), "utf8"));
+        }
+        return out;
+    }
+    /** Write a view's materialized files into `workDir` (alongside .avcs, like git). */
+    async checkoutInto(workDir, view = "main") {
+        const res = await this.materialize(view);
+        const written = [];
+        for (const [path, blobOid] of res.tree) {
+            const full = join(workDir, path);
+            await mkdir(dirname(full), { recursive: true });
+            const synth = res.synthBlobs.get(blobOid);
+            await writeFile(full, synth !== undefined ? Buffer.from(synth, "utf8") : await this.readBlob(blobOid));
+            written.push(path);
+        }
+        return written.sort();
+    }
+    /**
+     * Commit a working tree: diff `workDir`'s files against the materialized view and
+     * author put_file / delete_file ops for the changes (the git `add`+`commit` step,
+     * which agents do via operation.propose). Causally builds on the current frontier.
+     */
+    async commitWorkingTree(workDir, opts) {
+        const view = opts.line ?? "main";
+        const res = await this.materialize(view);
+        const current = new Map((await this.materializedFiles(res)).map((f) => [f.path, f.content]));
+        const disk = await this.#readWorkTree(workDir);
+        const added = [];
+        const modified = [];
+        const removed = [];
+        for (const [path, content] of disk) {
+            if (!current.has(path))
+                added.push(path);
+            else if (current.get(path) !== content)
+                modified.push(path);
+        }
+        for (const path of current.keys())
+            if (!disk.has(path))
+                removed.push(path);
+        const ops = [];
+        if (!added.length && !modified.length && !removed.length)
+            return { ops, added, modified, removed, intent: "" };
+        const intent = await this.createIntent({ title: opts.message, owner: opts.actor.id });
+        const sess = await this.startSession({ intentOid: intent, actor: opts.actor });
+        const deps = res.headOps;
+        for (const path of [...added, ...modified].sort()) {
+            ops.push(await this.proposeFileWrite({ sessionOid: sess, intentOid: intent, actor: opts.actor, path, content: disk.get(path), declaredPurpose: opts.message, causalDeps: deps, line: opts.line }));
+        }
+        for (const path of removed.sort()) {
+            ops.push(await this.proposeOperation({ sessionOid: sess, intentOid: intent, actor: opts.actor, target: { entityKind: "file", entityId: path }, body: { kind: "delete_file", path }, declaredPurpose: `delete ${path}`, causalDeps: deps, line: opts.line }));
+        }
+        return { ops, added: added.sort(), modified: modified.sort(), removed: removed.sort(), intent };
+    }
+    // ── git bridge (docs/14) ───────────────────────────────────────────────────
+    /** Read `.avcs/config.json` (a torn/absent file is treated as empty). */
+    async #readConfig() {
+        const p = join(this.dir, ".avcs", "config.json");
+        if (!existsSync(p))
+            return {};
+        try {
+            return JSON.parse(await readFile(p, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Read the repo-local git-bridge mode (default `sidecar` for pre-existing repos). */
+    async getGitMode() {
+        return (await this.#readConfig()).gitMode === "committed" ? "committed" : "sidecar";
+    }
+    /** Whether `git-sync --commit` injects AVCS provenance trailers (default on). */
+    async gitTrailerEnabled() {
+        return (await this.#readConfig()).trailer !== false;
+    }
+    /** Persist the git-bridge mode and (re)write `.avcs/.gitignore` to match it. */
+    async setGitMode(mode) {
+        const cfg = await this.#readConfig();
+        cfg.gitMode = mode;
+        await this.store.writeAux("config.json", JSON.stringify(cfg, null, 2) + "\n");
+        await this.#writeGitignore(mode);
+        this.logger.info("git.mode", { mode });
+    }
+    /**
+     * Build the commit-message trailer block that links a git commit to its AVCS provenance
+     * (the git→avcs half). A reader with the `.avcs/` history can resolve the checkpoint;
+     * for a teammate without AVCS it is a harmless annotation (like `Co-authored-by`).
+     */
+    gitTrailer(info) {
+        const lines = [`AVCS-Checkpoint: ${info.checkpoint}`, `AVCS-TreeHash: ${info.treeHash}`];
+        if (info.intent)
+            lines.push(`AVCS-Intent: ${info.intent}`);
+        return lines.join("\n");
+    }
+    /** Record the git commit ↔ AVCS checkpoint back-link (the avcs→git half of provenance). */
+    async recordGitCommit(sha, checkpointOid) {
+        await this.store.setRef(`git:${sha}`, checkpointOid);
+        this.logger.info("git.link", { sha, checkpoint: checkpointOid });
+    }
+    /** The checkpoint a git commit was synced from, if a back-link was recorded locally. */
+    async gitCheckpoint(sha) {
+        return this.store.getRef(`git:${sha}`);
+    }
+    /**
+     * Resolve the canonical projection (path→content) a checkpoint froze, for provenance
+     * verification. `treeHashOk` re-confirms the checkpoint's recorded treeHash still
+     * reproduces from its frontier (internal integrity); `files` is what git's committed
+     * tree at the linked SHA must match exactly for the commit to be a faithful projection.
+     */
+    async checkpointFiles(checkpointOid) {
+        const cp = await this.store.get(checkpointOid);
+        const res = await this.materializeAt(cp.headOps);
+        return { treeHash: cp.treeHash, treeHashOk: res.treeHash === cp.treeHash, files: await this.materializedFiles(res) };
+    }
+    /** Write `.avcs/.gitignore` for `mode`. Idempotent; safe to call on every sync. */
+    async #writeGitignore(mode) {
+        await this.store.writeAux(".gitignore", mode === "committed" ? GITIGNORE_COMMITTED : GITIGNORE_SIDECAR);
+        // In committed mode, a `.avcs/.gitattributes` (scoped to this dir — never the repo
+        // root) keeps immutable object files out of diffs and off git's text-merge path; they
+        // are content-addressed so distinct oids never collide, and identical oids are
+        // byte-identical (no conflict). Mutable refs CAN still conflict — resolved by the
+        // post-merge reindex+checkout, see docs/14.
+        if (mode === "committed") {
+            await this.store.writeAux(".gitattributes", "objects/** -diff -merge\noplog -diff\nobjlog -diff\n");
+        }
+    }
+    /**
+     * Persist the provenance handoff for the git-hook trio (pre-commit writes it; the
+     * prepare-commit-msg and post-commit hooks consume it). Local working state, git-ignored.
+     */
+    async writeGitPending(info) {
+        await this.store.writeAux(".git-pending", JSON.stringify(info) + "\n");
+    }
+    /** Read the pending provenance handoff, or null if none is staged. */
+    async readGitPending() {
+        const p = join(this.dir, ".avcs", ".git-pending");
+        if (!existsSync(p))
+            return null;
+        try {
+            return JSON.parse(await readFile(p, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Clear the pending provenance handoff (post-commit, after recording the back-link). */
+    async clearGitPending() {
+        await rm(join(this.dir, ".avcs", ".git-pending"), { force: true });
+    }
+    /**
+     * Rebuild every rebuildable cache from the object store: the entity index AND the
+     * op-log/obj-log. This is the recovery path after objects arrive OUTSIDE the normal
+     * authoring code path — e.g. a `git pull`/`merge` that unions committed-mode
+     * `.avcs/objects` straight onto disk. Those logs are git-ignored, so without this the
+     * op-LOG (which `materialize` reads its op SET from) would stay stale and silently miss
+     * the pulled ops. Rebuilding the op-log is therefore essential, not just cosmetic.
+     * Idempotent.
+     */
+    async reindex() {
+        await rm(join(this.dir, ".avcs", "indexes"), { recursive: true, force: true });
+        let ops = 0;
+        for await (const op of this.store.list("operation")) {
+            const oid = op.oid;
+            for (const k of keysOf(op))
+                await this.store.appendEntityIndex(k, oid);
+            ops++;
+        }
+        // Rebuild the op-log (materialize's op-set source) and refresh the obj-log (hub sync
+        // cursor) so both reflect objects that arrived via git rather than the store's writes.
+        await this.store.rebuildOpLog();
+        this.#opCache.clear();
+        await rm(join(this.dir, ".avcs", "objlog"), { force: true }); // lazily backfilled on next read
+        this.logger.info("reindex", { ops });
+        return { ops };
+    }
+    /**
+     * One-shot "prepare the working tree for `git commit`" (docs/14). The bridge between
+     * AVCS development and a `git add`/`commit`/`push`:
+     *   1. capture any direct working-tree edits as ops (so nothing a human/agent typed is
+     *      lost — direct edits and agent-proposed ops converge into one history),
+     *   2. gate: if the view has open (needs-human) conflicts, REFUSE — never let a
+     *      conflicted tree be committed; the caller routes the human to `avcs conflicts`,
+     *   3. checkpoint the verified state vector (the git "commit unit"), and
+     *   4. re-project so the working tree is EXACTLY reduce()'s output (folding in any
+     *      auto-merged concurrent ops), making git track the deterministic projection.
+     * Git invocation (`git add`) is intentionally left to the caller/CLI so this core stays
+     * git-agnostic; `.avcs/.gitignore` (ensured here) makes a plain `git add -A` mode-correct.
+     */
+    async gitSync(opts) {
+        const view = opts.line ?? "main";
+        const lineOpt = opts.line ? { line: opts.line } : {};
+        // 1. Capture direct working-tree edits as ops before anything else.
+        const cap = await this.commitWorkingTree(this.dir, { message: opts.message, actor: opts.actor, ...lineOpt });
+        const captured = { ops: cap.ops, added: cap.added, modified: cap.modified, removed: cap.removed, intent: cap.intent };
+        // Ensure the gitignore reflects the current mode (pre-existing repos never wrote one).
+        const mode = await this.getGitMode();
+        await this.#writeGitignore(mode);
+        // 2. Conflict gate.
+        const res = await this.materialize(view);
+        if (res.conflicts.length > 0)
+            return { mode, captured, conflicts: res.conflicts };
+        // 3. Checkpoint the verified state. 4. Re-project the working tree.
+        const checkpoint = await this.createCheckpoint(view, opts.message);
+        const written = await this.checkoutInto(this.dir, view);
+        this.logger.info("git.sync", { view, mode, capturedOps: captured.ops.length, checkpoint, treeHash: res.treeHash });
+        return { mode, captured, conflicts: [], checkpoint, treeHash: res.treeHash, reprojected: written.length };
+    }
+    // ── backup / transfer (docs/10 WS-F) ──────────────────────────────────────
+    /** Export the whole repo (all objects + refs) as a portable bundle for backup/transfer. */
+    async exportBundle() {
+        const objects = [];
+        for await (const o of this.store.list())
+            objects.push(o);
+        return { version: 1, objects, refs: Object.fromEntries(await this.store.listRefs()) };
+    }
+    /** Import a bundle into this repo (idempotent, content-addressed). Rebuilds the entity index. */
+    async importBundle(bundle) {
+        for (const o of bundle.objects) {
+            const oid = await this.store.put(o);
+            if (o.type === "operation")
+                for (const k of keysOf(o))
+                    await this.store.appendEntityIndex(k, oid);
+        }
+        let refs = 0;
+        for (const [name, oid] of Object.entries(bundle.refs ?? {})) {
+            if (await this.store.has(oid)) {
+                await this.store.setRef(name, oid);
+                refs++;
+            }
+        }
+        return { objects: bundle.objects.length, refs };
+    }
+    /**
+     * Pack loose objects into a packfile (docs/11 B2) — a maintenance op that reduces inode
+     * count and speeds full scans. Reads stay correct throughout (loose-first, then packs);
+     * blobs are intentionally left loose so redaction can always scrub their bytes.
+     */
+    async pack() {
+        const r = await this.store.pack();
+        this.logger.info("pack", { packed: r.packed });
+        return r;
+    }
+    /**
+     * Compaction (docs/11 B3): persist the current reduction of `view` as a durable base
+     * snapshot. A later COLD materialize (with AVCS_COMPACT=1) loads it and `reduceIncremental`s
+     * only the ops added since — folding settled history into the base instead of replaying
+     * it — while the original ops stay on disk (append-only audit preserved). Correctness is
+     * the same invariant as Track A: reduceIncremental(base, current) ≡ full reduce, gated by
+     * the property harness and (with AVCS_VERIFY_INCREMENTAL=1) a per-call self-check.
+     */
+    async compact(view = "main") {
+        this.#forceSnapshot = true;
+        try {
+            await this.materialize(view); // produces & stores #incSnap via #pass1Reduce
+        }
+        finally {
+            this.#forceSnapshot = false;
+        }
+        if (!this.#incSnap)
+            return { baseOps: 0 };
+        // Atomic write (D2): a plain writeFile could leave a torn CBOR snapshot on a crash.
+        // writeAux routes through the store's temp→fsync→rename→fsync-dir path. A torn read
+        // would still fall back to a full reduce (#loadPersistedSnapshot catches decode
+        // errors), but a durable atomic write means the base is never silently corrupt.
+        await this.store.writeAux(join("snapshot", `${view}.cbor`), encodeCbor(serializeSnapshot(this.#incSnap)));
+        const baseOps = this.#incSnap.input.ops.length;
+        this.logger.info("compact", { view, baseOps });
+        return { baseOps };
+    }
+    /** Load a persisted compaction base into the in-memory incremental snapshot (B3). */
+    async #loadPersistedSnapshot(view) {
+        const p = join(this.dir, ".avcs", "snapshot", `${view}.cbor`);
+        if (!existsSync(p))
+            return;
+        try {
+            this.#incSnap = deserializeSnapshot(decodeCbor(await readFile(p)));
+        }
+        catch {
+            this.#incSnap = null; // corrupt/incompatible snapshot → full reduce (always correct)
+        }
+    }
+    /**
+     * Garbage-collect (docs/10 WS-C). Reclaims only objects UNREACHABLE from the
+     * authoritative graph — never the append-only audit history of accepted ops:
+     *  - orphan blobs: stored blobs no remaining op references (incl. chunk blobs whose
+     *    manifest is gone);
+     *  - expired quarantine: outsider ops still quarantined (non-member, never promoted),
+     *    past `quarantineTtlMs`, that nothing else builds on — the one place append-only
+     *    yields (abandoned/spam contributions, docs/09 G5).
+     * `dryRun` reports without deleting.
+     */
+    async gc(opts = {}) {
+        const ops = await this.store.collect("operation");
+        const ttl = opts.quarantineTtlMs ?? 7 * 24 * 3600_000;
+        const now = Date.now();
+        const memberships = await this.store.collect("membership");
+        const governanceActive = memberships.length > 0;
+        const members = new Set(memberships.filter((m) => !m.revokedAt).map((m) => m.actorId));
+        const promoted = new Set((await this.store.collect("promotion")).flatMap((p) => p.ops));
+        const dependedOn = new Set(ops.flatMap((o) => o.causalDeps));
+        const quarantinedOps = [];
+        const removed = new Set();
+        if (governanceActive) {
+            for (const o of ops) {
+                const oid = o.oid;
+                const quarantined = !members.has(o.actor.id) && !promoted.has(oid);
+                if (!quarantined || dependedOn.has(oid))
+                    continue;
+                if (now - Date.parse(o.createdAt) < ttl)
+                    continue;
+                quarantinedOps.push(oid);
+                removed.add(oid);
+            }
+        }
+        // Blobs referenced by REMAINING ops (+ chunks of referenced chunked manifests).
+        const referenced = new Set();
+        for (const o of ops) {
+            if (removed.has(o.oid))
+                continue;
+            const b = o.body.blobOid;
+            if (!b)
+                continue;
+            referenced.add(b);
+            const blob = await this.store.get(b).catch(() => null);
+            if (blob?.chunked && blob.chunks)
+                for (const c of blob.chunks)
+                    referenced.add(c);
+        }
+        const blobs = (await this.store.collect("blob"))
+            .map((b) => b.oid)
+            .filter((oid) => !referenced.has(oid));
+        if (!opts.dryRun) {
+            for (const oid of quarantinedOps)
+                await this.store.deleteObject(oid);
+            for (const oid of blobs)
+                await this.store.deleteObject(oid);
+            // Objects were deleted from under the warm caches — drop them so the next
+            // materialize re-tails from disk (GC'd op-log entries are then skipped).
+            for (const oid of quarantinedOps)
+                this.#opCache.delete(oid);
+            for (const oid of blobs)
+                this.#blobCache.delete(oid);
+        }
+        this.logger.info("gc", { dryRun: opts.dryRun ?? false, blobs: blobs.length, quarantinedOps: quarantinedOps.length });
+        return { blobs, quarantinedOps };
+    }
+    /**
+     * Materialize the state AT a given frontier: reduce only the causal closure of
+     * `headOps`. The basis for time-travel — history, bisect, and diff-at-point all
+     * reduce over a prefix instead of the whole graph. (Phase 9 / Phase 10)
+     */
+    async materializeAt(headOps, includeStatuses = ["accepted"]) {
+        const allOps = await this.store.collect("operation");
+        const byId = new Map(allOps.map((o) => [o.oid, o]));
+        const closure = new Set();
+        const stack = [...headOps];
+        while (stack.length) {
+            const id = stack.pop();
+            if (closure.has(id))
+                continue;
+            closure.add(id);
+            for (const dep of byId.get(id)?.causalDeps ?? [])
+                if (!closure.has(dep))
+                    stack.push(dep);
+        }
+        return this.#reduceOpSet(allOps.filter((o) => closure.has(o.oid)), includeStatuses);
+    }
+    /**
+     * History of one entity (file path or `<path>#<symbol>`) in causal order, via the
+     * entity index — O(ops-on-that-entity), not a full-store scan. The basis for blame
+     * and `log -p`. (Phase 9 / Phase 10)
+     */
+    async historyOf(entityKey) {
+        const oids = await this.store.readEntityIndex(entityKey);
+        const ops = [];
+        for (const o of oids)
+            if (await this.store.has(o))
+                ops.push(await this.store.get(o)); // skip GC'd
+        return ops.sort((a, b) => a.lamport - b.lamport || ((a.oid ?? "") < (b.oid ?? "") ? -1 : 1));
+    }
+    // ── observability (Phase 10) ────────────────────────────────────────────
+    /**
+     * Blame: who currently owns an entity and WHY — the accepted head op on its key,
+     * with actor + intent + purpose. Stronger than git blame: the 'why' is first-class.
+     */
+    async blame(entityKey, line = "main") {
+        const res = await this.materialize(line);
+        const hist = await this.historyOf(entityKey);
+        const owner = [...hist].reverse().find((o) => res.statuses.get(o.oid) === "accepted");
+        if (!owner)
+            return null;
+        const intent = await this.readIntent(owner.intentOid).catch(() => null);
+        return {
+            op: owner.oid,
+            actor: owner.actor,
+            purpose: owner.declaredPurpose,
+            ...(intent ? { intentTitle: intent.title } : {}),
+            at: owner.createdAt,
+        };
+    }
+    /** `log -p` for one entity: each op with its before/after content reconstructed. */
+    async logP(entityKey, filePath) {
+        const hist = await this.historyOf(entityKey);
+        const out = [];
+        const fileOf = async (heads) => (await this.materializedFiles(await this.materializeAt(heads))).find((f) => f.path === filePath)?.content ?? "";
+        for (const o of hist) {
+            out.push({
+                op: o.oid,
+                purpose: o.declaredPurpose,
+                before: await fileOf(o.causalDeps),
+                after: await fileOf([o.oid]),
+            });
+        }
+        return out;
+    }
+    /** Diff two views (or, with materializeAt, two frontiers). */
+    async diff(viewA, viewB) {
+        const { diffTrees } = await import("../query/diff.js");
+        return diffTrees(await this.materialize(viewA), await this.materialize(viewB));
+    }
+    /**
+     * Bisect: find the first operation (between a known-good and known-bad frontier)
+     * that makes `isBad` true. Deterministic — re-reduces at each step with no checkout.
+     */
+    async bisect(goodHeads, badHeads, isBad) {
+        const allOps = await this.store.collect("operation");
+        const byId = new Map(allOps.map((o) => [o.oid, o]));
+        const closure = (heads) => {
+            const seen = new Set();
+            const stack = [...heads];
+            while (stack.length) {
+                const id = stack.pop();
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                for (const d of byId.get(id)?.causalDeps ?? [])
+                    if (!seen.has(d))
+                        stack.push(d);
+            }
+            return seen;
+        };
+        const good = closure(goodHeads);
+        const between = [...closure(badHeads)]
+            .filter((id) => !good.has(id))
+            .map((id) => byId.get(id))
+            .sort((a, b) => a.lamport - b.lamport || ((a.oid ?? "") < (b.oid ?? "") ? -1 : 1));
+        // smallest k in [0..n] such that good ∪ first-k-between is bad
+        let lo = 0;
+        let hi = between.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            const heads = [...goodHeads, ...between.slice(0, mid).map((o) => o.oid)];
+            if (await isBad(await this.materializeAt(heads)))
+                hi = mid;
+            else
+                lo = mid + 1;
+        }
+        return lo > 0 && lo <= between.length ? between[lo - 1].oid : null;
+    }
+    /**
+     * Decision memory: given a conflict key, recall prior human rulings on the same
+     * key — their verdict, reason, and any distilled `futurePolicy`. The next agent
+     * (and the conflict UI) can reuse them instead of re-litigating.
+     */
+    async recallDecisions(conflictKey) {
+        const cid = conflictIdFor(conflictKey);
+        const decisions = await this.store.collect("decision");
+        return decisions
+            .filter((d) => d.conflictId === cid || d.conflictId === conflictKey)
+            .map((d) => ({ reason: d.reason, futurePolicy: d.futurePolicy, decidedBy: d.decidedBy.id }));
+    }
+    /** All distilled `futurePolicy` rules a human has left behind — learned constraints. */
+    async learnedPolicies() {
+        const decisions = await this.store.collect("decision");
+        return [...new Set(decisions.map((d) => d.futurePolicy).filter((p) => !!p))];
+    }
+    /**
+     * Write the materialized tree to a directory. Refuses to clobber an existing
+     * non-empty directory unless it carries our marker, so a stray `--out` can't
+     * `rm -rf` someone's source tree.
+     */
+    async writeWorkspace(result, targetDir) {
+        const marker = join(targetDir, ".avcs-workspace");
+        if (existsSync(targetDir)) {
+            const entries = await readdir(targetDir);
+            const nonEmpty = entries.filter((e) => e !== "." && e !== "..");
+            if (nonEmpty.length > 0 && !existsSync(marker)) {
+                throw new Error(`refusing to overwrite non-empty directory without an .avcs-workspace marker: ${targetDir}`);
+            }
+            await rm(targetDir, { recursive: true, force: true });
+        }
+        await mkdir(targetDir, { recursive: true });
+        await writeFile(marker, `materialized ${result.treeHash}\n`, "utf8");
+        for (const [path, blobOid] of result.tree) {
+            const full = join(targetDir, path);
+            await mkdir(dirname(full), { recursive: true });
+            // Symbol-merged files are synthesized content, not a stored blob.
+            const synth = result.synthBlobs.get(blobOid);
+            await writeFile(full, synth !== undefined ? Buffer.from(synth, "utf8") : await this.readBlob(blobOid));
+        }
+    }
+    async createCheckpoint(viewName, summary) {
+        const view = await this.getView(viewName);
+        const result = await this.materialize(viewName);
+        const evidence = {};
+        // Deterministic aggregation: process evidence in canonical (createdAt, oid) order
+        // so the "last result wins per kind" outcome is replica-independent.
+        const allEvidence = (await this.store.collect("evidence")).sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0) ||
+            ((a.oid ?? "") < (b.oid ?? "") ? -1 : 1));
+        for (const ev of allEvidence) {
+            // Only count trusted evidence for accepted ops.
+            if (ev.producedBy.kind === "ai_agent")
+                continue;
+            if (ev.forOps.some((o) => result.statuses.get(o) === "accepted")) {
+                evidence[ev.kind] = ev.result;
+            }
+        }
+        const cp = {
+            type: "checkpoint",
+            viewOid: view.oid,
+            headOps: result.headOps,
+            treeHash: result.treeHash,
+            policyOid: (await this.store.getRef("policy")),
+            materializerVersion: MATERIALIZER_VERSION,
+            evidence,
+            status: result.conflicts.length === 0 ? "verified" : "draft",
+            summary,
+            createdAt: new Date().toISOString(),
+        };
+        const oid = await this.store.put(cp);
+        await this.store.setRef(`checkpoint:${viewName}:latest`, oid);
+        return oid;
+    }
+    /** Resolve the materialized tree into {path, content} entries. */
+    async materializedFiles(result) {
+        const out = [];
+        for (const [path, blobOid] of result.tree) {
+            const synth = result.synthBlobs.get(blobOid);
+            out.push({ path, content: synth ?? (await this.readBlob(blobOid)).toString("utf8") });
+        }
+        return out;
+    }
+    /**
+     * Phase 6: cut a Release — a verified checkpoint + its evidence + an SBOM of what
+     * shipped + signed-off artifacts. Refuses unless the view is conflict-free (no open
+     * conflicts and no semantic contract breaks): you cannot release an unverified tree.
+     */
+    async cutRelease(viewName, opts = {}) {
+        const result = await this.materialize(viewName);
+        if (result.conflicts.length || result.semanticConflicts.length) {
+            return {
+                released: false,
+                reason: `view has ${result.conflicts.length} open conflict(s) and ${result.semanticConflicts.length} contract break(s); resolve them before releasing`,
+            };
+        }
+        const checkpointOid = await this.createCheckpoint(viewName, opts.summary ?? `release of ${viewName}`);
+        const checkpoint = await this.store.get(checkpointOid);
+        const { generateSbom } = await import("../release/sbom.js");
+        const sbom = generateSbom(await this.materializedFiles(result));
+        const release = {
+            type: "release",
+            checkpointOid,
+            treeHash: result.treeHash,
+            sbom,
+            artifacts: opts.artifacts ?? [],
+            evidence: checkpoint.evidence,
+            signedBy: opts.signedBy ?? (opts.signWith ? [opts.signWith.keyId] : []),
+            status: "released",
+            ...(opts.version ? { version: opts.version } : {}),
+            ...(opts.supportStatus ? { supportStatus: opts.supportStatus } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        release.sig = this.#sign("release", release, opts.signWith);
+        const oid = await this.store.put(release);
+        await this.store.setRef(`release:${viewName}:latest`, oid);
+        if (opts.version)
+            await this.store.setRef(`release:${viewName}:${opts.version}`, oid);
+        return { released: true, releaseOid: oid };
+    }
+}
+_a = Repo;
+//# sourceMappingURL=repo.js.map