@izagood/avcs 0.29.1 → 0.31.0

package/dist/api/repo.js

@@ -20,8 +20,17 @@ import { defaultPolicy, MATERIALIZER_VERSION } from "../reducer/policy.js";
 import { Keyring, generateKeypair, signMessage, } from "../core/identity.js";
 import { checkLease, isActive, scopesOverlap } from "../concurrency/lease.js";
 import { isBinary } from "../core/bytes.js";
+import { lcsLineLength } from "../merge/merge3.js";
 import { Metrics } from "../observe/metrics.js";
 import { silentLogger } from "../observe/logger.js";
+/** The trunk branch assumed when `.avcs/config.json` records none (docs/20 §3.1). */
+export const DEFAULT_TRUNK = "main";
+/**
+ * The branch names that count as trunk when none is configured. The pre-trunk bridge
+ * special-cased exactly this pair, so keeping both is what makes an unconfigured repository
+ * — including a `master`-default one — behave as it always did (docs/20 W7).
+ */
+export const LEGACY_TRUNK_BRANCHES = ["main", "master"];
 // 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).
@@ -946,6 +955,12 @@ export class Repo {
             }
             // required checks — unless an active break-glass Override waives them (Phase 12)
             const cp = await this.store.get(args.newCheckpoint);
+            // A workspace-scoped checkpoint (docs/20 §3.3) froze a tree containing ops that have
+            // not landed on the base line. Advancing a protected head to it would publish
+            // unlanded work under a verified head, so it is refused outright.
+            if (cp.workspace) {
+                return { finalized: false, reason: `checkpoint ${args.newCheckpoint.slice(0, 16)} is scoped to workspace ${cp.workspace} — land it first (\`avcs workspace land ${cp.workspace}\`)` };
+            }
             const waived = await this.#activeWaivers(args.view);
             for (const k of prot?.requiredChecks ?? []) {
                 if (waived.has(k))
@@ -1754,6 +1769,19 @@ export class Repo {
     async landedWorkspaces() {
         return [...(await this.#landedWorkspaces())].sort();
     }
+    /**
+     * Every workspace that actually carries operations. A workspace is not a stored object —
+     * it exists exactly as a tag on ops — so this is the only way to ask whether a NAME names
+     * anything. The `post-merge` land seam uses it as a guard: landing is append-only and
+     * irreversible, so a name it cannot corroborate is not landed (docs/20 §3.4, R1).
+     */
+    async workspaceNames() {
+        const names = new Set();
+        for (const op of await this.#allOpsTailed())
+            if (op.workspace)
+                names.add(op.workspace);
+        return [...names].sort();
+    }
     /**
      * Land a workspace onto its base line (docs/16): its ops join the base view and merge
      * there. There is no "rebase" — reduce always 3-way-merges the full op set, and any
@@ -1790,17 +1818,22 @@ export class Repo {
         const allOps = await this.#allOpsTailed();
         const inherited = await this.#inheritedOps(lineName, allOps);
         const wsName = opts?.workspace;
-        // A base view also includes ops from workspaces that have LANDED (promoted onto base).
-        const landed = wsName ? null : await this.#landedWorkspaces();
+        // Landing makes a workspace's ops BASE-ACCEPTED (docs/16 §4.3), so the landed set is
+        // read for EVERY view, not only base ones. A workspace view that ignored it would keep
+        // a sibling's already-landed work invisible and rediscover the conflict at land time
+        // (docs/20 §1.3).
+        const landed = await this.#landedWorkspaces();
         const ops = [];
         for (const op of allOps) {
             const onLine = (op.line ?? "main") === lineName || inherited.has(op.oid);
             if (!onLine)
                 continue;
-            // Workspace isolation (docs/16): a base view excludes workspace-tagged ops UNLESS
-            // that workspace has landed; a workspace view (wsName=W) sees base ops + W's own.
+            // Workspace isolation (docs/16): a view excludes a workspace-tagged op unless that
+            // workspace has landed, or it is this view's OWN workspace. With `wsName` undefined
+            // the middle clause is vacuously true, so a BASE view's op set is exactly what it was
+            // — exclude tagged-and-unlanded, keep everything else.
             const opWs = op.workspace;
-            if (wsName ? (!!opWs && opWs !== wsName) : (!!opWs && !landed.has(opWs)))
+            if (opWs && opWs !== wsName && !landed.has(opWs))
                 continue;
             if (exclude.has(op.oid))
                 continue;
@@ -1976,6 +2009,15 @@ export class Repo {
     // repeats). A clone is returned so callers can mutate without corrupting the cache.
     #reduceCache = new Map();
     static REDUCE_CACHE_MAX = 64;
+    /**
+     * Minimum line similarity for the capture path to call a removed × added pair a MOVE
+     * rather than an unrelated delete + create (docs/19 §3.1, and §6 R3 asks for exactly one
+     * place to tune it). 0.5 is git's `-M` default, so a tree avcs captures and the same tree
+     * `git diff -M` describes agree about what moved. Raising it makes capture more
+     * conservative (more moves recorded as delete + create, which is the pre-Stage-0
+     * behaviour); lowering it risks attaching a wrong merge base, which is worse than none.
+     */
+    static RENAME_SIMILARITY = 0.5;
     #cloneResult(r) {
         return {
             tree: new Map(r.tree),
@@ -2208,6 +2250,102 @@ export class Repo {
             return false;
         return Buffer.from(buf.toString("utf8"), "utf8").equals(buf);
     }
+    /**
+     * Pair `removed` paths against `added` ones to recover MOVES from a path-set diff
+     * (docs/19 §3.1, Stage 0).
+     *
+     * `commitWorkingTree` compares path sets, so a move arrives as a removal plus an
+     * unrelated-looking addition — which the reducer then sees as a delete racing an edit,
+     * plus a create with no merge base. Recovering the move here is what makes Stage 1's
+     * commutativity reachable from actual usage.
+     *
+     * Two tiers, both deterministic and language-blind:
+     *
+     *   1. EXACT content match. Content is hashed, so this is an O(n) bucket join and a pure
+     *      relocation — the common case, and the whole of the binary case — never pays for a
+     *      line diff at all.
+     *   2. LINE SIMILARITY `2·LCS / (linesP + linesQ)` over the leftovers, using merge3's own
+     *      LCS. Binary content (a NUL byte) is excluded: a line diff over bytes is noise, so
+     *      binary is exact-match-only.
+     *
+     * A pair is only accepted when it is UNAMBIGUOUS in both directions — one candidate for
+     * the source and one for the destination. Anything else stays a delete + create rather
+     * than a guess: naming the wrong file as "the same file" invents history, and a wrong
+     * merge base is worse than no merge base. That is also why there is no tie-breaking to
+     * get wrong; ambiguity is not resolved, it is declined.
+     */
+    #detectRenames(removed, added, before, after) {
+        if (!removed.length || !added.length)
+            return [];
+        const sources = [...removed].sort();
+        const destinations = [...added].sort();
+        /** Accept only pairs that are the single candidate on BOTH sides. */
+        const unambiguous = (links) => {
+            const inverse = new Map();
+            for (const [from, tos] of links)
+                for (const to of tos)
+                    (inverse.get(to) ?? inverse.set(to, new Set()).get(to)).add(from);
+            const out = [];
+            for (const from of [...links.keys()].sort()) {
+                const tos = links.get(from);
+                if (tos.size !== 1)
+                    continue;
+                const to = [...tos][0];
+                if (inverse.get(to).size !== 1)
+                    continue;
+                out.push({ from, to });
+            }
+            return out;
+        };
+        // ── Tier 1: exact content ──
+        const byContent = new Map();
+        for (const to of destinations) {
+            const h = sha256hex(after.get(to));
+            (byContent.get(h) ?? byContent.set(h, []).get(h)).push(to);
+        }
+        const exact = new Map();
+        for (const from of sources) {
+            const hits = byContent.get(sha256hex(before.get(from)));
+            if (hits)
+                exact.set(from, new Set(hits));
+        }
+        const pairs = unambiguous(exact);
+        // ── Tier 2: line similarity over what tier 1 left ──
+        const takenFrom = new Set(pairs.map((p) => p.from));
+        const takenTo = new Set(pairs.map((p) => p.to));
+        const similar = new Map();
+        const linesCache = new Map();
+        const linesOf = (path, buf) => {
+            if (!linesCache.has(path))
+                linesCache.set(path, isBinary(buf) ? null : buf.toString("utf8").split("\n"));
+            return linesCache.get(path);
+        };
+        for (const from of sources) {
+            if (takenFrom.has(from))
+                continue;
+            const fromLines = linesOf(`-${from}`, before.get(from));
+            if (!fromLines)
+                continue; // binary: exact match only (rule 4)
+            for (const to of destinations) {
+                if (takenTo.has(to))
+                    continue;
+                const toLines = linesOf(`+${to}`, after.get(to));
+                if (!toLines)
+                    continue;
+                const n = fromLines.length;
+                const m = toLines.length;
+                // Sound pre-filter (docs/19 R4): LCS ≤ min(n, m), so this is an upper bound on the
+                // similarity and can never skip a pair that would have passed. It keeps a large
+                // relocation from running an O(n·m) line DP against every unrelated candidate.
+                if ((2 * Math.min(n, m)) / (n + m) < _a.RENAME_SIMILARITY)
+                    continue;
+                if ((2 * lcsLineLength(fromLines, toLines)) / (n + m) < _a.RENAME_SIMILARITY)
+                    continue;
+                (similar.get(from) ?? similar.set(from, new Set()).get(from)).add(to);
+            }
+        }
+        return [...pairs, ...unambiguous(similar)].sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0));
+    }
     /**
      * Commit a working tree: diff `workDir`'s files against the materialized view and
      * author edit_file / put_file / delete_file ops for the changes (the git `add`+`commit`
@@ -2220,19 +2358,35 @@ export class Repo {
      * ADDED files keep `put_file` (a create genuinely has no base), and so does any content that
      * is not losslessly UTF-8 text (see `#isMergeableText`).
      *
-     * Capture also runs the early conflict warning with CROSS-LINE visibility: the git bridge
-     * maps each branch to its own line, so a competing session is on a *different* line and a
-     * line-scoped check would never see it. The warnings are returned (`contention`) so the CLI
-     * can put them in front of the human running `git commit`.
+     * A MOVED file is recovered from the removed × added pair (`#detectRenames`, docs/19 §3.1)
+     * and captured as `rename_file` — plus an `edit_file` at the NEW path, based on the content
+     * from BEFORE the move, when it was edited on the way. Without this the reducer's whole
+     * rename × edit commutativity is unreachable from real usage: a path-set diff turns every
+     * move into a delete racing an edit and a create with nothing to merge against. Recovered
+     * moves are reported in `renamed` and are NOT double-counted in `added`/`removed`.
+     *
+     * `workspace` scopes the capture to a converging workspace (docs/20 §3.3) — the git bridge
+     * maps a topic branch to one. It has to reach BOTH ends: the authored ops carry the tag, and
+     * the projection this diffs against is the WORKSPACE's view. Diffing disk against the base
+     * view instead would re-capture the workspace's own earlier edits as brand-new changes on
+     * every commit, and — since a move is recovered from a removal paired with an addition —
+     * those stale removals could pair into renames that never happened.
+     *
+     * Capture also runs the early conflict warning with CROSS-LINE visibility: a competing
+     * session may be on a different line, and a line-scoped check would never see it. The
+     * warnings are returned (`contention`) so the CLI can put them in front of the human
+     * running `git commit`.
      */
     async commitWorkingTree(workDir, opts) {
         const view = opts.line ?? "main";
-        const res = await this.materialize(view);
+        const ws = opts.workspace ? { workspace: opts.workspace } : {};
+        // The base to diff disk against is THIS scope's projection, workspace included.
+        const res = await this.materialize(view, ws);
         const current = new Map((await this.materializedBytes(res)).map((f) => [f.path, f.bytes]));
         const disk = await this.#readWorkTree(workDir, opts.ignorePredicate);
-        const added = [];
+        let added = [];
         const modified = [];
-        const removed = [];
+        let removed = [];
         for (const [path, content] of disk) {
             if (!current.has(path))
                 added.push(path);
@@ -2242,10 +2396,19 @@ export class Repo {
         for (const path of current.keys())
             if (!disk.has(path))
                 removed.push(path);
+        // Recover moves before deciding op kinds: a paired path is a move, not an unrelated
+        // delete + create, and must not be counted as both.
+        const renamed = this.#detectRenames(removed, added, current, disk);
+        if (renamed.length) {
+            const movedFrom = new Set(renamed.map((r) => r.from));
+            const movedTo = new Set(renamed.map((r) => r.to));
+            removed = removed.filter((p) => !movedFrom.has(p));
+            added = added.filter((p) => !movedTo.has(p));
+        }
         const ops = [];
         const contention = [];
-        if (!added.length && !modified.length && !removed.length)
-            return { ops, added, modified, removed, intent: "", contention };
+        if (!added.length && !modified.length && !removed.length && !renamed.length)
+            return { ops, added, modified, removed, renamed, intent: "", contention };
         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;
@@ -2260,21 +2423,45 @@ export class Repo {
             }
         };
         const warn = { warnContention: true, contentionAcrossLines: true, onContention: collect };
+        // Moves first, sorted by source. The paired `edit_file` must causally FOLLOW its own
+        // rename: it names the destination path, so if the two were concurrent the reducer would
+        // read them as a move and an unrelated edit fighting over that path (docs/19 §3.2 leaves
+        // rename-vs-destination a genuine contest, and rightly so). Depending on the rename also
+        // states the truth — the author moved the file, then wrote to where it now lives.
+        for (const { from, to } of renamed) {
+            const rn = await this.proposeOperation({
+                sessionOid: sess, intentOid: intent, actor: opts.actor,
+                target: { entityKind: "file", entityId: from },
+                body: { kind: "rename_file", fromPath: from, path: to },
+                declaredPurpose: `move ${from} → ${to}`, causalDeps: deps, line: opts.line, ...ws, ...warn,
+            });
+            ops.push(rn);
+            const base = current.get(from);
+            const content = disk.get(to);
+            if (base.equals(content))
+                continue; // a pure move needs no second op
+            // Content changed on the way. Only mergeable text can say so as an edit; otherwise the
+            // move stands and the new bytes go in byte-exact as a `put_file` at the new path.
+            const common = { sessionOid: sess, intentOid: intent, actor: opts.actor, path: to, declaredPurpose: opts.message, causalDeps: [...deps, rn], line: opts.line, ...ws, ...warn };
+            ops.push(this.#isMergeableText(base) && this.#isMergeableText(content)
+                ? await this.proposeEdit({ ...common, newText: content.toString("utf8"), baseBlobOid: await this.putBlob(base) })
+                : await this.proposeFileWrite({ ...common, content }));
+        }
         const isModified = new Set(modified);
         // One sorted pass over both categories keeps op authoring order (and therefore lamport
         // assignment) exactly as before; only the op KIND differs per category.
         for (const path of [...added, ...modified].sort()) {
             const content = disk.get(path);
             const base = isModified.has(path) ? current.get(path) : undefined;
-            const common = { sessionOid: sess, intentOid: intent, actor: opts.actor, path, declaredPurpose: opts.message, causalDeps: deps, line: opts.line, ...warn };
+            const common = { sessionOid: sess, intentOid: intent, actor: opts.actor, path, declaredPurpose: opts.message, causalDeps: deps, line: opts.line, ...ws, ...warn };
             ops.push(base !== undefined && this.#isMergeableText(base) && this.#isMergeableText(content)
                 ? await this.proposeEdit({ ...common, newText: content.toString("utf8"), baseBlobOid: await this.putBlob(base) })
                 : await this.proposeFileWrite({ ...common, content }));
         }
         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, ...warn }));
+            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, ...ws, ...warn }));
         }
-        return { ops, added: added.sort(), modified: modified.sort(), removed: removed.sort(), intent, contention };
+        return { ops, added: added.sort(), modified: modified.sort(), removed: removed.sort(), renamed, intent, contention };
     }
     // ── git bridge (docs/14) ───────────────────────────────────────────────────
     /** Read `.avcs/config.json` (a torn/absent file is treated as empty). */
@@ -2305,6 +2492,32 @@ export class Repo {
         await this.#writeGitignore(mode);
         this.logger.info("git.mode", { mode });
     }
+    /**
+     * The git branch that carries the base view (docs/20 §3.1). The core stays git-agnostic:
+     * this is a recorded NAME, and only the bridge ever compares it against a real branch.
+     * Unset ⇒ `main`, which is what the bridge assumed before trunk existed.
+     */
+    async getTrunk() {
+        const t = (await this.#readConfig()).trunk;
+        return typeof t === "string" && t.length ? t : DEFAULT_TRUNK;
+    }
+    /**
+     * Every branch name that counts as trunk. With `trunk` configured it is the single
+     * answer; with nothing configured BOTH `main` and `master` are trunk — exactly the pair
+     * the pre-trunk bridge special-cased, so an unconfigured repository (a `master`-default
+     * one included) keeps behaving as it always did (docs/20 W7).
+     */
+    async trunkBranches() {
+        const t = (await this.#readConfig()).trunk;
+        return typeof t === "string" && t.length ? [t] : [...LEGACY_TRUNK_BRANCHES];
+    }
+    /** Record the trunk branch. Shares `config.json` with the git mode, so read-modify-write. */
+    async setTrunk(branch) {
+        const cfg = await this.#readConfig();
+        cfg.trunk = branch;
+        await this.store.writeAux("config.json", JSON.stringify(cfg, null, 2) + "\n");
+        this.logger.info("git.trunk", { trunk: branch });
+    }
     /**
      * 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;
@@ -2427,20 +2640,25 @@ export class Repo {
         const workDir = opts.workDir ?? this.dir;
         const view = opts.line ?? "main";
         const lineOpt = opts.line ? { line: opts.line } : {};
+        // A workspace scope (docs/20 §3.3) has to travel the WHOLE round trip: the capture tags
+        // its ops and diffs against the workspace's projection, the conflict gate reads the same
+        // view, and the re-projection writes it back. Any one of them left on base would make
+        // this working tree oscillate between two different trees.
+        const wsOpt = opts.workspace ? { workspace: opts.workspace } : undefined;
         // 1. Capture direct working-tree edits as ops before anything else.
-        const cap = await this.commitWorkingTree(workDir, { message: opts.message, actor: opts.actor, ...lineOpt, ...(opts.ignorePredicate ? { ignorePredicate: opts.ignorePredicate } : {}) });
-        const captured = { ops: cap.ops, added: cap.added, modified: cap.modified, removed: cap.removed, intent: cap.intent };
+        const cap = await this.commitWorkingTree(workDir, { message: opts.message, actor: opts.actor, ...lineOpt, ...(wsOpt ?? {}), ...(opts.ignorePredicate ? { ignorePredicate: opts.ignorePredicate } : {}) });
+        const captured = { ops: cap.ops, added: cap.added, modified: cap.modified, removed: cap.removed, renamed: cap.renamed, 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);
+        const res = await this.materialize(view, wsOpt);
         if (res.conflicts.length > 0)
             return { mode, captured, contention: cap.contention, 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(workDir, view);
-        this.logger.info("git.sync", { view, mode, capturedOps: captured.ops.length, checkpoint, treeHash: res.treeHash });
+        const checkpoint = await this.createCheckpoint(view, opts.message, wsOpt);
+        const written = await this.checkoutInto(workDir, view, wsOpt);
+        this.logger.info("git.sync", { view, mode, workspace: opts.workspace, capturedOps: captured.ops.length, checkpoint, treeHash: res.treeHash });
         return { mode, captured, contention: cap.contention, conflicts: [], checkpoint, treeHash: res.treeHash, reprojected: written.length };
     }
     // ── backup / transfer (docs/10 WS-F) ──────────────────────────────────────
@@ -2839,9 +3057,16 @@ export class Repo {
             await writeFile(full, synth ?? await this.readBlob(blobOid));
         }
     }
-    async createCheckpoint(viewName, summary) {
+    /**
+     * Freeze a view's verified state. `workspace` freezes that WORKSPACE's projection instead
+     * of the bare base view (docs/20 §3.3): a commit on a topic branch contains the workspace's
+     * tree, so a checkpoint of the base view would describe a tree git does not hold and
+     * `avcs verify-git` would report every such commit as a mismatch. The scope is recorded on
+     * the checkpoint so it can never be mistaken for a base-view one (`finalize` refuses it).
+     */
+    async createCheckpoint(viewName, summary, opts) {
         const view = await this.getView(viewName);
-        const result = await this.materialize(viewName);
+        const result = await this.materialize(viewName, opts?.workspace ? { workspace: opts.workspace } : undefined);
         const evidence = {};
         const evidenceBinding = {};
         // Deterministic aggregation: process evidence in canonical (createdAt, oid) order
@@ -2878,12 +3103,15 @@ export class Repo {
             // Only present when some evidence aggregated — an evidence-less checkpoint's
             // bytes (and oid) are identical to pre-13.4.
             ...(Object.keys(evidenceBinding).length ? { evidenceBinding } : {}),
+            ...(opts?.workspace ? { workspace: opts.workspace } : {}),
             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);
+        // `checkpoint:<view>:latest` names the view's own latest state; a workspace checkpoint is
+        // a different tree, so it gets its own ref rather than displacing the base view's.
+        await this.store.setRef(opts?.workspace ? `checkpoint:${viewName}:workspace:${opts.workspace}:latest` : `checkpoint:${viewName}:latest`, oid);
         return oid;
     }
     /** Resolve the materialized tree into {path, bytes} entries (byte-preserving). */