@izagood/avcs 0.16.0 → 0.18.0

package/dist/api/repo.js

@@ -18,7 +18,7 @@ import { encodeCbor, decodeCbor } from "../core/cbor.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 { checkLease, isActive, scopesOverlap } 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
@@ -205,6 +205,17 @@ export class Repo {
      * a no-auth/read-public hub, so signing is opt-in by having a key, not mandatory.
      */
     async #resolveHubSigner(explicitActorId) {
+        const actorId = await this.localActorId(explicitActorId);
+        if (!actorId)
+            return undefined;
+        const privateKey = await this.loadLocalKey(actorId);
+        return privateKey ? { keyId: actorId, privateKey } : undefined;
+    }
+    /** The replica's local actor identity, resolved by the same order #resolveHubSigner
+     *  uses (explicit → AVCS_ACTOR → config.json → sole private key) but WITHOUT requiring
+     *  a private key to exist — a contention check (Phase 15.3) needs a perspective, not a
+     *  credential. Returns undefined when nothing resolves. */
+    async localActorId(explicitActorId) {
         let actorId = explicitActorId ?? process.env.AVCS_ACTOR;
         if (!actorId) {
             const cfg = await this.#readConfig();
@@ -219,10 +230,7 @@ export class Repo {
             }
             catch { /* no private keystore yet */ }
         }
-        if (!actorId)
-            return undefined;
-        const privateKey = await this.loadLocalKey(actorId);
-        return privateKey ? { keyId: actorId, privateKey } : undefined;
+        return actorId;
     }
     /**
      * Provision an owner key: mint a keypair, register the public half as trusted, and
@@ -386,6 +394,18 @@ export class Repo {
         // 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);
+        if (args.warnContention) {
+            const warnings = await this.contention({ keys: [...keysOf({ ...op, oid })], actorId: op.actor.id, line: args.line });
+            for (const w of warnings) {
+                this.metrics.inc("contention.warnings");
+                this.logger.warn("contention.warn", {
+                    key: w.key,
+                    op: oid,
+                    theirs: w.theirs.map((t) => `${t.actor}:${t.op.slice(0, 16)}`),
+                    leaseHolders: w.leaseHolders.map((l) => l.actor),
+                });
+            }
+        }
         return oid;
     }
     /** Convenience: write file content as a blob + a put_file operation. */
@@ -403,6 +423,7 @@ export class Repo {
             line: args.line,
             workspace: args.workspace,
             signWith: args.signWith,
+            warnContention: args.warnContention,
         });
     }
     /**
@@ -429,6 +450,7 @@ export class Repo {
             line: args.line,
             workspace: args.workspace,
             signWith: args.signWith,
+            warnContention: args.warnContention,
         });
     }
     async attachEvidence(args) {
@@ -492,6 +514,88 @@ export class Repo {
             return { granted: true, leaseOid: await this.store.put(lease) };
         });
     }
+    // ── contention: early conflict warning (Phase 15.3, docs/17 §15.3) ──────────
+    /**
+     * Report contention on entity keys BEFORE finalize would discover it: for each key,
+     * the operations by other actors that the caller has not built on (outside the
+     * caller's causal closure) and are still live (neither decision-rejected nor built
+     * upon by a later op on the key), plus other actors' active leases overlapping the
+     * key. Discovery is via the entity index — O(ops-on-key), no reduce.
+     *
+     * Perspective resolution ("mine"), first hit wins:
+     *  - `sessionOid`: that session's actor; its ops seed both the key set and the closure.
+     *  - `actorId` (+ optional `keys`): that actor's ops on the resolved keys seed the
+     *    closure; with no `keys` given, every key the actor has authored on is checked.
+     *  - `keys` alone: no closure filter — everything live by anyone on the key reports.
+     */
+    async contention(args) {
+        const line = args.line ?? "main";
+        let mine = args.actorId;
+        const keys = new Set(args.keys ?? []);
+        const myOpOids = [];
+        if (args.sessionOid) {
+            const sess = await this.store.get(args.sessionOid);
+            mine ??= sess.actor.id;
+            for (const op of await this.#allOpsTailed()) {
+                if (op.sessionOid !== args.sessionOid)
+                    continue;
+                myOpOids.push(op.oid);
+                for (const k of keysOf(op))
+                    keys.add(k);
+            }
+        }
+        else if (mine) {
+            for (const op of await this.#allOpsTailed()) {
+                if (op.actor.id !== mine)
+                    continue;
+                if (keys.size && ![...keysOf(op)].some((k) => keys.has(k)))
+                    continue;
+                myOpOids.push(op.oid);
+                if (!args.keys?.length)
+                    for (const k of keysOf(op))
+                        keys.add(k);
+            }
+        }
+        if (!keys.size)
+            return [];
+        // Ops I've already seen/built on are not surprises — they're my history.
+        const myClosure = myOpOids.length ? await this.#closureOf(myOpOids) : new Set();
+        const rejected = new Set((await this.store.collect("decision")).flatMap((d) => d.rejectedOps));
+        const leases = await this.activeLeases();
+        const out = [];
+        for (const key of [...keys].sort()) {
+            const ops = [];
+            for (const oid of await this.store.readEntityIndex(key)) {
+                if (!(await this.store.has(oid)))
+                    continue; // GC'd since indexed
+                const op = await this.store.get(oid);
+                if ((op.line ?? "main") !== line || op.private)
+                    continue;
+                ops.push({ ...op, oid });
+            }
+            // An op some later op (on any key) causally builds on is superseded work, not
+            // contention — one ancestry walk over the union of the key ops' deps finds them.
+            const builtUpon = await this.#closureOf(ops.flatMap((o) => o.causalDeps));
+            const theirs = ops
+                .filter((o) => {
+                const oid = o.oid;
+                return o.actor.id !== mine && !myClosure.has(oid) && !rejected.has(oid) && !builtUpon.has(oid);
+            })
+                .sort((a, b) => a.lamport - b.lamport || String(a.oid).localeCompare(String(b.oid)))
+                .map((o) => ({ op: o.oid, actor: o.actor.id, lamport: o.lamport, purpose: o.declaredPurpose, createdAt: o.createdAt }));
+            const leaseHolders = leases
+                .filter((l) => l.actor.id !== mine && l.writeScopes.some((s) => scopesOverlap(key, s)))
+                .map((l) => ({
+                actor: l.actor.id,
+                leaseOid: l.oid,
+                scope: l.writeScopes.find((s) => scopesOverlap(key, s)),
+                expiresAt: l.expiresAt,
+            }));
+            if (theirs.length || leaseHolders.length)
+                out.push({ key, theirs, leaseHolders });
+        }
+        return out;
+    }
     /** Build a minimal repair packet for ops whose validation failed. */
     async repairContext(opOids) {
         const { buildRepairContext } = await import("../validation/repair.js");
@@ -775,6 +879,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
@@ -1002,6 +1436,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
@@ -1011,9 +1486,118 @@ export class Repo {
         const url = await this.#resolveRemote(remote);
         const { pulled } = await this.pullHub(url);
         const { pushed, rejected } = await this.pushHub(url, opts);
+        await this.#recordSyncAt(remote); // Phase 15.2: the freshness window keys off this stamp
         this.logger.info("sync.completed", { remote, url, pulled, pushed, rejected });
         return { pulled, pushed, rejected };
     }
+    // ── live convergence: freshness window (Phase 15.2, docs/17 §15.2) ─────────
+    // `.avcs/last-sync.json` — remote name → ISO timestamp of the last successful sync.
+    // An aux file like remotes.json: per-replica state, never an object, never gossiped.
+    /** Freshness window applied to an `autoSync` remote that doesn't set `freshnessMs`. */
+    static DEFAULT_FRESHNESS_MS = 30_000;
+    async #readLastSync() {
+        const raw = await this.store.readAux("last-sync.json");
+        if (!raw)
+            return {};
+        try {
+            return JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    async #recordSyncAt(remote) {
+        const last = await this.#readLastSync();
+        last[remote] = new Date().toISOString();
+        await this.store.writeAux("last-sync.json", JSON.stringify(last, null, 2) + "\n");
+    }
+    /** Milliseconds since the last successful sync with `remote` (Infinity when never). */
+    async syncAgeMs(remote = "origin") {
+        const at = Date.parse((await this.#readLastSync())[remote] ?? "");
+        return Number.isFinite(at) ? Date.now() - at : Infinity;
+    }
+    /**
+     * BLOCKING freshness sync (Phase 15.2): sync each named remote (default: every
+     * `autoSync` remote) whose last successful sync is older than its freshness window.
+     * For callers that must not read stale state (e.g. just before a submit). The read
+     * path itself never calls this — materialize only ever fires a BACKGROUND revalidate.
+     */
+    async syncIfStale(remote, opts) {
+        const remotes = await this.#readRemotes();
+        const names = remote !== undefined ? [remote] : Object.keys(remotes).filter((n) => remotes[n].autoSync);
+        const synced = [];
+        for (const name of names) {
+            const cfg = remotes[name];
+            if (!cfg && !/^https?:\/\//.test(name))
+                throw new Error(`unknown remote: ${name}`);
+            const freshnessMs = cfg?.freshnessMs ?? _a.DEFAULT_FRESHNESS_MS;
+            if ((await this.syncAgeMs(name)) < freshnessMs)
+                continue;
+            await this.sync(name, opts);
+            synced.push(name);
+        }
+        return { synced };
+    }
+    // Stale-while-revalidate on materialize: when an autoSync remote's window has lapsed,
+    // fire a background sync and return immediately — the read path is the throughput-
+    // critical path and is NEVER blocked on the network. In-flight + a 1s re-check
+    // throttle keep the hot loop to at most one aux read per second.
+    //
+    // The in-flight run is KEPT as a promise rather than a boolean: "fire and forget" with
+    // no handle is unobservable from outside, and a revalidate outlives the observable
+    // effect that a caller would naturally wait on (pull lands the objects, but push and
+    // the last-sync stamp write still follow). Whoever tears the repo down next — a test's
+    // rm, a daemon shutdown — would otherwise race those writes. See settleBackgroundSync.
+    #bgSync = null;
+    #lastFreshnessCheck = 0;
+    /**
+     * Await any in-flight background revalidation, resolving immediately when idle. The
+     * quiesce handle for the fire-and-forget path, mirroring the promise `runSyncWatch`
+     * returns for the daemon: call it before tearing a repo down (shutdown, teardown) so
+     * no `.avcs` write is still outstanding. Never rejects — a failed revalidate is logged
+     * and swallowed, exactly as it is on the read path.
+     */
+    async settleBackgroundSync() {
+        // Loop rather than a single await: a materialize concurrent with the settle can start
+        // the next run while we're waiting on this one.
+        for (let inFlight = this.#bgSync; inFlight; inFlight = this.#bgSync)
+            await inFlight;
+    }
+    #maybeBackgroundSync() {
+        const now = Date.now();
+        if (this.#bgSync || now - this.#lastFreshnessCheck < 1_000)
+            return;
+        this.#lastFreshnessCheck = now;
+        // Publish the handle BEFORE arranging its clear, and clear by identity: a body that
+        // ever settles without suspending would otherwise null the field first and be
+        // resurrected by this assignment, wedging the guard above at "always in flight".
+        const run = this.#revalidateStaleRemotes();
+        this.#bgSync = run;
+        void run.finally(() => { if (this.#bgSync === run)
+            this.#bgSync = null; });
+    }
+    /** One revalidation pass: sync every autoSync remote past its freshness window.
+     *  Never rejects — see the catch. */
+    async #revalidateStaleRemotes() {
+        try {
+            const remotes = await this.#readRemotes();
+            for (const [name, cfg] of Object.entries(remotes)) {
+                if (!cfg.autoSync)
+                    continue;
+                const freshnessMs = cfg.freshnessMs ?? _a.DEFAULT_FRESHNESS_MS;
+                const age = await this.syncAgeMs(name);
+                if (age < freshnessMs)
+                    continue;
+                this.logger.info("sync.freshness.revalidate", { remote: name, ageMs: age === Infinity ? null : Math.round(age) });
+                await this.sync(name);
+            }
+        }
+        catch (e) {
+            // Background revalidation failing (hub down, network) must never surface into
+            // the read path — log and try again after the next materialize + throttle.
+            this.logger.warn("sync.freshness.fail", { error: String(e.message) });
+        }
+    }
     /** Resolve a view's query into the candidate operation set, then reduce. */
     /**
      * Workspaces that have LANDED onto their base line (docs/16). A landed workspace's ops
@@ -1052,6 +1636,9 @@ export class Repo {
     }
     async materialize(viewName = "main", opts) {
         this.metrics.inc("materialize.calls");
+        // Phase 15.2 stale-while-revalidate: an autoSync remote past its freshness window
+        // triggers a BACKGROUND sync. Fire-and-forget — this read never waits on the network.
+        this.#maybeBackgroundSync();
         // 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