@izagood/avcs 0.15.1 → 0.17.0

package/dist/api/repo.js

@@ -60,13 +60,18 @@ export class Repo {
     // 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.
+    // Last full reduction's snapshot, for incremental reduce (docs/11 A6b — DEFAULT ON since
+    // Phase 13.3). 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 OUT via AVCS_INCREMENTAL=0;
+    // AVCS_VERIFY_INCREMENTAL=1 cross-checks every incremental result against a full reduce
+    // (run as a dedicated CI job, not recommended on the hot path).
     #incSnap = null;
-    #forceSnapshot = false; // set by compact() to capture a snapshot regardless of env flags
+    #forceSnapshot = false; // set by compact() to capture a snapshot even when opted out
+    // Op count of the last PERSISTED base per view (Phase 13.3 amortized auto-compaction):
+    // once the live snapshot is ≥ AUTO_COMPACT_DELTA ops past it, materialize re-persists.
+    #persistedBaseOps = new Map();
+    static AUTO_COMPACT_DELTA = 256;
     constructor(dir, store) {
         this.dir = dir;
         this.store = store;
@@ -770,6 +775,336 @@ export class Repo {
         }
         return result;
     }
+    // ── integration queue (Phase 14, docs/17) ──────────────────────────────────
+    // The end of "head moved — pull and re-reduce first": since ops are an append-only
+    // union and reduce is deterministic, a stale submission is never rejected for
+    // staleness — the queue re-reduces the frontier UNION on the submitter's behalf.
+    // This is a repo API (not hub-only): it also kills the local multi-process funnel.
+    /** Causal closure (op oids) of a frontier. Missing objects are skipped — callers gate
+     *  completeness separately via #missingCausalDeps. */
+    async #closureOf(heads) {
+        const seen = new Set();
+        const stack = [...heads];
+        while (stack.length) {
+            const id = stack.pop();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            if (!(await this.store.has(id)))
+                continue;
+            const op = await this.store.get(id);
+            for (const d of op.causalDeps)
+                if (!seen.has(d))
+                    stack.push(d);
+        }
+        return seen;
+    }
+    #queueRel(view) {
+        return join("queue", `${view}.json`);
+    }
+    async #readReservation(view) {
+        const raw = await this.store.readAux(this.#queueRel(view));
+        if (!raw)
+            return null;
+        try {
+            const r = JSON.parse(raw.toString("utf8"));
+            return r && typeof r.ticketId === "string" ? r : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async #writeReservation(view, resv) {
+        await this.store.writeAux(this.#queueRel(view), JSON.stringify(resv) + "\n");
+    }
+    /** Record an Integration verdict (append-only audit) and point the idempotency ref at it. */
+    async #recordIntegration(fields) {
+        const integ = { type: "integration", ...fields, createdAt: new Date().toISOString() };
+        const oid = await this.store.put(integ);
+        await this.store.setRef(`integration:${fields.view}:${fields.ticketId}`, oid);
+        return oid;
+    }
+    /** Author a checkpoint AT an integrated frontier (never `materialize(view)` — §1-(A):
+     *  a view materialize would sweep in un-submitted third-party ops). */
+    async #authorIntegratedCheckpoint(view, integrated, evidence, evidenceBinding, summary) {
+        const v = await this.getView(view);
+        const cp = {
+            type: "checkpoint",
+            viewOid: v.oid,
+            headOps: integrated.headOps,
+            treeHash: integrated.treeHash,
+            policyOid: (await this.store.getRef("policy")),
+            materializerVersion: MATERIALIZER_VERSION,
+            evidence,
+            ...(evidenceBinding && Object.keys(evidenceBinding).length ? { evidenceBinding } : {}),
+            status: integrated.conflicts.length === 0 ? "verified" : "draft",
+            summary,
+            createdAt: new Date().toISOString(),
+        };
+        return this.store.put(cp);
+    }
+    /** Verified (non-agent, canonically ordered) evidence bound to exactly `treeHash`. */
+    async #boundEvidenceFor(treeHash) {
+        const out = {};
+        const all = this.#verifiedEvidence(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 all) {
+            if (ev.producedBy.kind === "ai_agent")
+                continue;
+            if (ev.treeHash === treeHash)
+                out[ev.kind] = ev.result;
+        }
+        return out;
+    }
+    /** Keys touched by a set of op oids (contention surface of a delta). */
+    async #keysOfOps(oids) {
+        const keys = new Set();
+        for (const oid of oids) {
+            if (!(await this.store.has(oid)))
+                continue;
+            const op = await this.store.get(oid);
+            for (const k of keysOf(op))
+                keys.add(k);
+        }
+        return keys;
+    }
+    /**
+     * Submit a draft checkpoint to the integration queue (docs/17 §14.2). Runs under the
+     * same `finalize:<view>` lock as finalize — the existing mkdir lock IS the serializer
+     * (no separate queue structure in v1). The outcome is always one of the four verdicts;
+     * "pull and redo" does not exist on any path.
+     *
+     * Idempotency: an `advanced` ticket replays its recorded verdict forever. Non-terminal
+     * verdicts (conflict/needs_evidence/rejected/expired) re-evaluate on resubmission —
+     * the world legitimately changes under them (a decision lands, evidence arrives, a
+     * missing object syncs), and a frozen replay would wedge the ticket.
+     */
+    async submitIntegration(args) {
+        const view = args.view;
+        const ticketId = args.ticketId ?? sha256hex(`${view}:${args.checkpoint}`);
+        const result = await this.store.withLock(`finalize:${view}`, async () => {
+            // 1. Idempotency — a terminal success replays as-is (safe resubmission).
+            const priorRef = await this.store.getRef(`integration:${view}:${ticketId}`);
+            if (priorRef && (await this.store.has(priorRef))) {
+                const prior = await this.store.get(priorRef);
+                if (prior.verdict === "advanced") {
+                    return { verdict: "advanced", head: prior.resultCheckpoint, integration: priorRef };
+                }
+            }
+            // 2. Reservation — one in-flight needs_evidence ticket at a time (TTL-bounded).
+            let resv = await this.#readReservation(view);
+            if (resv && Date.parse(resv.expiresAt) <= Date.now()) {
+                // Expired: audit it and let the queue move on (docs/17 §14 contract test).
+                await this.#recordIntegration({
+                    view, ticketId: resv.ticketId, submittedCheckpoint: resv.submittedCheckpoint,
+                    baseHead: await this.protectedHead(view), resultCheckpoint: resv.integratedCheckpoint,
+                    verdict: "expired", reason: `needs_evidence reservation expired at ${resv.expiresAt}`, by: resv.by,
+                });
+                await this.#writeReservation(view, null);
+                resv = null;
+            }
+            if (resv && resv.ticketId !== ticketId) {
+                return { verdict: "queued", behindTicket: resv.ticketId, retryAfterMs: 1000 + Math.floor(Math.random() * 500) };
+            }
+            // 3. Causal completeness — never judge (or advance to) a partially-synced tree.
+            const cp = await this.store.get(args.checkpoint);
+            const missing = await this.#missingCausalDeps(cp.headOps);
+            if (missing.length) {
+                await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead: await this.protectedHead(view), verdict: "rejected", reason: `incomplete causal history: ${missing.length} object(s) missing`, by: args.by });
+                return { verdict: "rejected", reason: `incomplete causal history: ${missing.length} object(s) missing — push them first (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""})` };
+            }
+            // Role gate (same as finalize).
+            const prot = await this.getProtection(view);
+            if (prot && !(await this.hasRole(args.by, prot.finalizeRole ?? "maintainer"))) {
+                const reason = `${args.by} lacks role ${prot.finalizeRole ?? "maintainer"} to integrate ${view}`;
+                await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead: await this.protectedHead(view), verdict: "rejected", reason, by: args.by });
+                return { verdict: "rejected", reason };
+            }
+            // 4. Integration reduce — the frontier UNION via the materializeAt path (NEVER
+            // materialize(view): §1-(A), un-submitted third-party ops must stay out).
+            const baseHead = await this.protectedHead(view);
+            const curHeads = baseHead ? (await this.store.get(baseHead)).headOps : [];
+            const unionHeads = [...new Set([...curHeads, ...cp.headOps])];
+            const integrated = await this.materializeAt(unionHeads);
+            const subClosure = await this.#closureOf(cp.headOps);
+            const fastForward = curHeads.every((h) => subClosure.has(h));
+            // 5. Conflicts — the ONLY outcome that needs a human/agent decision, and it
+            // arrives as a minimal repair packet with decision memory, not "pull and redo".
+            if (integrated.conflicts.length > 0) {
+                const packet = { conflicts: [] };
+                for (const c of integrated.conflicts) {
+                    const fc = integrated.fileConflicts.find((f) => `file:${f.file}` === c.key);
+                    packet.conflicts.push({
+                        key: c.key,
+                        reason: c.reason,
+                        options: c.options.map((o) => ({ op: o.opOid, actor: o.actor, purpose: o.purpose })),
+                        ...(fc ? { regions: fc.regions } : {}),
+                        priorDecisions: await this.recallDecisions(c.key),
+                    });
+                }
+                const integration = await this.#recordIntegration({
+                    view, ticketId, submittedCheckpoint: args.checkpoint, baseHead,
+                    verdict: "conflict", conflictKeys: packet.conflicts.map((c) => c.key), by: args.by,
+                });
+                return { verdict: "conflict", packet, integration };
+            }
+            // 6. Gates: approvals carry from the SUBMITTED checkpoint to the integrated one
+            // (GitHub counts PR approvals independently of the merge commit — same isomorphism).
+            let carriedApprovals;
+            if (prot && (prot.requiredApprovals > 0 || prot.requireOwnerApproval)) {
+                const verdicts = await this.#approvalVerdicts(args.checkpoint);
+                if ([...verdicts.values()].includes("request_changes")) {
+                    const reason = "changes requested by a reviewer";
+                    await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                    return { verdict: "rejected", reason };
+                }
+                const approvers = [...verdicts].filter(([, v]) => v === "approve").map(([id]) => id);
+                if (approvers.length < prot.requiredApprovals) {
+                    const reason = `needs ${prot.requiredApprovals} approval(s), have ${approvers.length}`;
+                    await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                    return { verdict: "rejected", reason };
+                }
+                if (prot.requireOwnerApproval) {
+                    let owner = false;
+                    for (const id of approvers)
+                        if (await this.hasRole(id, "maintainer")) {
+                            owner = true;
+                            break;
+                        }
+                    if (!owner) {
+                        const reason = "requires an owner (maintainer+) approval";
+                        await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                        return { verdict: "rejected", reason };
+                    }
+                }
+                if (prot.integration?.carryApprovals !== false) {
+                    carriedApprovals = (await this.store.collect("approval"))
+                        .filter((a) => a.checkpointOid === args.checkpoint)
+                        .map((a) => a.oid);
+                }
+            }
+            const waived = await this.#activeWaivers(view);
+            const required = (prot?.requiredChecks ?? []).filter((k) => !waived.has(k));
+            const advance = async (headCp, evidenceBinding, resultIsSubmitted = false) => {
+                await this.store.setRef(`head:${view}`, headCp);
+                const integration = await this.#recordIntegration({
+                    view, ticketId, submittedCheckpoint: args.checkpoint, baseHead,
+                    resultCheckpoint: resultIsSubmitted ? undefined : headCp,
+                    verdict: "advanced", evidenceBinding, ...(carriedApprovals ? { carriedApprovals } : {}), by: args.by,
+                });
+                if (resv?.ticketId === ticketId)
+                    await this.#writeReservation(view, null);
+                this.logger.info("integrate.advanced", { view, ticketId, head: headCp, evidenceBinding });
+                return { verdict: "advanced", head: headCp, integration };
+            };
+            // 7a. Fast-forward — the current head is inside the submission's causal closure:
+            // classic finalize semantics, fresh binding, no re-authored checkpoint.
+            if (fastForward) {
+                for (const k of required) {
+                    if (cp.evidence[k] !== "pass") {
+                        const reason = `required check ${k} not pass`;
+                        await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                        return { verdict: "rejected", reason };
+                    }
+                    if (prot?.requireBoundEvidence && cp.evidenceBinding?.[k] !== "bound") {
+                        const reason = `required check ${k} passed but its evidence is not bound to this tree`;
+                        await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                        return { verdict: "rejected", reason };
+                    }
+                }
+                return advance(args.checkpoint, "fresh", true);
+            }
+            // 7b. Head moved: the integrated tree differs from the submitted one, so the
+            // submitted evidence does NOT prove it (docs/17 §14.5). Decide by evidence mode.
+            const T = integrated.treeHash;
+            const needsEvidence = async () => {
+                const draft = resv?.ticketId === ticketId && resv.treeHash === T
+                    ? resv.integratedCheckpoint
+                    : await this.#authorIntegratedCheckpoint(view, integrated, {}, undefined, `integration ${ticketId.slice(0, 12)} (awaiting evidence)`);
+                const ttl = prot?.integration?.reserveTtlMs ?? 10 * 60_000;
+                await this.#writeReservation(view, {
+                    ticketId, submittedCheckpoint: args.checkpoint, integratedCheckpoint: draft,
+                    treeHash: T, requiredChecks: required, by: args.by,
+                    expiresAt: new Date(Date.now() + ttl).toISOString(),
+                });
+                // What the submitter is missing locally to reproduce T: the head-side delta ops
+                // plus the blobs they reference (determinism does the rest — docs/17 §14.5 fresh).
+                const headClosure = await this.#closureOf(curHeads);
+                const missingLocally = [];
+                for (const oid of headClosure) {
+                    if (subClosure.has(oid))
+                        continue;
+                    missingLocally.push(oid);
+                    if (await this.store.has(oid)) {
+                        const op = await this.store.get(oid);
+                        for (const b of [op.body.blobOid, op.body.baseBlobOid])
+                            if (b)
+                                missingLocally.push(b);
+                    }
+                }
+                const integration = await this.#recordIntegration({
+                    view, ticketId, submittedCheckpoint: args.checkpoint, baseHead,
+                    resultCheckpoint: draft, verdict: "needs_evidence", by: args.by,
+                });
+                return { verdict: "needs_evidence", integratedCheckpoint: draft, treeHash: T, requiredChecks: required, missingLocally, ticketId, integration };
+            };
+            // Resubmission holding the reservation: accept iff fresh evidence bound to the
+            // reserved tree now covers the required checks — exactly one validation run.
+            if (resv && resv.ticketId === ticketId && resv.treeHash === T) {
+                const bound = await this.#boundEvidenceFor(T);
+                if (required.every((k) => bound[k] === "pass")) {
+                    const binding = {};
+                    for (const k of Object.keys(bound))
+                        binding[k] = "bound";
+                    const finalCp = await this.#authorIntegratedCheckpoint(view, integrated, bound, binding, `integration ${ticketId.slice(0, 12)}`);
+                    return advance(finalCp, "fresh");
+                }
+                return needsEvidence(); // reservation refreshed; still exactly one validation owed
+            }
+            if (required.length === 0) {
+                // Nothing to prove — integrate directly (evidence-less views).
+                const finalCp = await this.#authorIntegratedCheckpoint(view, integrated, {}, undefined, `integration ${ticketId.slice(0, 12)}`);
+                return advance(finalCp, "fresh");
+            }
+            const mode = prot?.integration?.evidenceMode ?? "carry-disjoint";
+            let carry = mode === "carry-always";
+            if (mode === "carry-disjoint") {
+                const headClosure = await this.#closureOf(curHeads);
+                const oursOnly = [...subClosure].filter((o) => !headClosure.has(o));
+                const theirsOnly = [...headClosure].filter((o) => !subClosure.has(o));
+                const ourKeys = await this.#keysOfOps(oursOnly);
+                const theirKeys = await this.#keysOfOps(theirsOnly);
+                // Disjoint deltas + zero new conflicts (checked above) ⇒ the same risk a git
+                // user already accepts when merging two independently-green branches — but
+                // machine-checked, recorded, and opt-out-able (docs/17 §14.5).
+                carry = [...ourKeys].every((k) => !theirKeys.has(k));
+            }
+            // Carried evidence is not tree-bound; a protection that demands bound evidence
+            // therefore forces the fresh path whenever the head has moved.
+            if (prot?.requireBoundEvidence)
+                carry = false;
+            if (carry) {
+                for (const k of required) {
+                    if (cp.evidence[k] !== "pass") {
+                        const reason = `required check ${k} not pass`;
+                        await this.#recordIntegration({ view, ticketId, submittedCheckpoint: args.checkpoint, baseHead, verdict: "rejected", reason, by: args.by });
+                        return { verdict: "rejected", reason };
+                    }
+                }
+                // The carry is never silent: recorded on BOTH the checkpoint and the Integration.
+                const binding = {};
+                for (const k of Object.keys(cp.evidence))
+                    binding[k] = "carried";
+                const finalCp = await this.#authorIntegratedCheckpoint(view, integrated, cp.evidence, binding, `integration ${ticketId.slice(0, 12)} (carried evidence)`);
+                return advance(finalCp, "carried");
+            }
+            return needsEvidence();
+        });
+        if (result.verdict !== "advanced") {
+            this.logger.info("integrate.verdict", { view, ticketId, verdict: result.verdict });
+        }
+        return result;
+    }
     // ── security (Phase 12) ────────────────────────────────────────────────────
     /**
      * Redact (tombstone) a blob's bytes — for a leaked secret. Admin-only. The oid is
@@ -997,6 +1332,47 @@ export class Repo {
             throw new Error(`unknown remote: ${nameOrUrl} (run \`avcs remote add ${nameOrUrl} <url>\`)`);
         return r.url;
     }
+    /** Public remote-name → hub-URL resolution (a literal URL passes through). */
+    async remoteUrl(nameOrUrl) {
+        return this.#resolveRemote(nameOrUrl);
+    }
+    /**
+     * Submit a draft checkpoint to a REMOTE hub's integration queue (Phase 14, docs/17
+     * §14.4), with capability detection: a hub advertising `integrate` on GET /version
+     * gets the queue path (one judgment, no redo); an older hub falls back to the legacy
+     * finalize + pull retry funnel (bounded) — the exact loop the queue exists to kill,
+     * kept only for backward compatibility.
+     */
+    async integrateHub(remoteOrUrl, args) {
+        const url = await this.#resolveRemote(remoteOrUrl);
+        const signWith = args.signWith ?? (await this.#resolveHubSigner(args.by));
+        let hasIntegrate = false;
+        try {
+            const v = (await (await fetch(`${url}/version`)).json());
+            hasIntegrate = v.integrate === true;
+        }
+        catch { /* unreachable /version → treat as legacy */ }
+        if (hasIntegrate) {
+            const { integrateWithHub } = await import("../hub/hubClient.js");
+            const r = await integrateWithHub(this.dir, url, { ...args, signWith });
+            // needs_evidence pulled delta objects through a separate store — refresh caches.
+            this.#blobCache.clear();
+            return r;
+        }
+        // Legacy fallback (old hub): finalize CAS + pull, bounded retries. This CAN lose
+        // races (that is exactly the funnel Phase 14 removes) — surfaced honestly.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            await this.pullHub(url);
+            const parentHead = await this.protectedHead(args.view);
+            await this.pushHub(url, { as: args.by });
+            const r = await this.finalizeHub(url, { view: args.view, newCheckpoint: args.checkpoint, parentHead, by: args.by, signWith });
+            if (r.finalized)
+                return { verdict: "advanced", head: r.head ?? args.checkpoint, legacy: true };
+            if (!/head moved/.test(r.reason ?? ""))
+                return { verdict: "rejected", reason: r.reason ?? `finalize failed (${r.status})`, legacy: true };
+        }
+        return { verdict: "rejected", reason: "legacy hub: lost the finalize CAS race 3 times — retry, or upgrade the hub for queue semantics", legacy: true };
+    }
     /**
      * Bidirectional convergence with a named remote (default "origin"): pull what the hub
      * has that we lack, then push what we have that it lacks. Pure object gossip — union
@@ -1047,9 +1423,11 @@ export class Repo {
     }
     async materialize(viewName = "main", opts) {
         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)
+        // Compaction (B3, default since 13.3): 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. A corrupt/stale/version-mismatched snapshot is discarded (→ full
+        // reduce), so correctness never depends on the file.
+        if (process.env.AVCS_INCREMENTAL !== "0" && !this.#incSnap)
             await this.#loadPersistedSnapshot(viewName);
         const view = await this.getView(viewName);
         const q = view.query;
@@ -1101,11 +1479,37 @@ export class Repo {
         // A caller may override the view's default status filter (e.g. to project pending/gated
         // ops so their computed 3-way merge can be inspected before acceptance — issue #13).
         const includeStatuses = opts?.includeStatuses ?? q.includeStatuses;
-        const res = await this.#reduceOpSet(kept, includeStatuses, true); // main path: opt-in incremental
+        const res = await this.#reduceOpSet(kept, includeStatuses, true); // main path: incremental by default
         for (const oid of quarantined)
             res.statuses.set(oid, "quarantined");
+        await this.#maybeAutoCompact(viewName, res);
         return res;
     }
+    /**
+     * Amortized compaction (Phase 13.3): after a main-path materialize, re-persist the base
+     * snapshot once the live snapshot is ≥ AUTO_COMPACT_DELTA ops past the last persisted
+     * base, so a cold start never replays an unbounded history. The treeHash guard ties the
+     * in-memory snapshot to THIS view's result (a reduce-cache hit may have left #incSnap
+     * pointing at another view's reduction). Best-effort: a persist failure only logs — the
+     * read path never depends on it.
+     */
+    async #maybeAutoCompact(viewName, res) {
+        if (process.env.AVCS_INCREMENTAL === "0")
+            return;
+        const snap = this.#incSnap;
+        if (!snap || snap.result.treeHash !== res.treeHash)
+            return;
+        const base = this.#persistedBaseOps.get(viewName) ?? 0;
+        if (snap.input.ops.length - base < _a.AUTO_COMPACT_DELTA)
+            return;
+        try {
+            await this.store.withLock(`snapshot:${viewName}`, () => this.#persistSnapshot(viewName, snap));
+            this.metrics.inc("snapshot.auto.persisted");
+        }
+        catch (e) {
+            this.logger.warn("snapshot.auto.failed", { view: viewName, error: e.message });
+        }
+    }
     /**
      * 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
@@ -1236,19 +1640,18 @@ export class Repo {
         };
     }
     /**
-     * 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).
+     * Pass-1 reduce (docs/11 A6b — incremental is the DEFAULT since Phase 13.3). With 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). Opt OUT with AVCS_INCREMENTAL=0 (plain full
+     * `reduce`, the pre-13.3 default). 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 (runs as a dedicated CI job).
      */
     #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)
+        const on = useInc && (process.env.AVCS_INCREMENTAL !== "0" || this.#forceSnapshot);
+        if (!on)
             return reduce(base);
         let snap;
         if (this.#incSnap) {
@@ -1672,7 +2075,7 @@ export class Repo {
     }
     /**
      * 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
+     * snapshot. A COLD materialize loads it BY DEFAULT (Phase 13.3) 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
@@ -1688,25 +2091,45 @@ export class Repo {
         }
         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)));
+        await this.#persistSnapshot(view, 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). */
+    /**
+     * Persist a snapshot as the view's durable compaction base, stamped with the
+     * materializer version + active policy oid (Phase 13.3): a cold load rejects the file
+     * when either changed, so a merge-algorithm or policy update silently invalidates stale
+     * bases (the warm path's invalidation is NonIncrementalError, handled in #pass1Reduce).
+     * Atomic write (D2): writeAux routes through the store's temp→fsync→rename→fsync-dir
+     * path, so a reader sees old-or-complete — never a torn CBOR file.
+     */
+    async #persistSnapshot(view, snap) {
+        const header = { materializerVersion: MATERIALIZER_VERSION, policyOid: (await this.store.getRef("policy")) ?? "default" };
+        await this.store.writeAux(join("snapshot", `${view}.cbor`), encodeCbor({ header, snapshot: serializeSnapshot(snap) }));
+        this.#persistedBaseOps.set(view, snap.input.ops.length);
+    }
+    /** Load a persisted compaction base into the in-memory incremental snapshot (B3).
+     *  Rejects (and ignores) a corrupt file, a pre-13.3 headerless file, or a header whose
+     *  materializer version / policy oid no longer matches — full reduce is always correct. */
     async #loadPersistedSnapshot(view) {
         const p = join(this.dir, ".avcs", "snapshot", `${view}.cbor`);
         if (!existsSync(p))
             return;
         try {
-            this.#incSnap = deserializeSnapshot(decodeCbor(await readFile(p)));
+            const raw = decodeCbor(await readFile(p));
+            const policyOid = (await this.store.getRef("policy")) ?? "default";
+            if (raw.header?.materializerVersion !== MATERIALIZER_VERSION || raw.header?.policyOid !== policyOid || raw.snapshot === undefined) {
+                this.metrics.inc("snapshot.cold.rejected");
+                return; // stale/incompatible base → full reduce
+            }
+            this.#incSnap = deserializeSnapshot(raw.snapshot);
+            this.#persistedBaseOps.set(view, this.#incSnap.input.ops.length);
+            this.metrics.inc("snapshot.cold.loaded");
         }
         catch {
-            this.#incSnap = null; // corrupt/incompatible snapshot → full reduce (always correct)
+            this.#incSnap = null; // corrupt snapshot → full reduce (always correct)
+            this.metrics.inc("snapshot.cold.rejected");
         }
     }
     /**