@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/dist/core/workspace/discover.js

@@ -0,0 +1,239 @@
+/**
+ * Member discovery for `loam open` — pure computation, no printing.
+ *
+ * The hard problem this module solves is binding DIRECTION: each service
+ * repo's committed loam.json points AT the docs repo, and the docs repo knows
+ * nothing about who points at it. So membership is a join computed at run
+ * time — {candidate directory has a loam.json} ∧ {that config resolves its
+ * docsDir to this docs repo} — over a deliberately bounded search: a depth-1
+ * readdir of a handful of roots, never a disk walk. Same committed files plus
+ * same filesystem always produce the same member set, in the same order.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { CONFIG_FILENAME, parseConfig } from "../envelope/config.js";
+import { inOrder } from "../kernel/concurrency.js";
+import { DocsRepoUnavailableError } from "../repo/state.js";
+/**
+ * One directory's identity for "is this the same checkout?" comparisons.
+ *
+ * Realpath first, because two spellings of one directory (a symlinked sibling,
+ * an 8.3 short name, a `..` route) must not become two workspace folders.
+ * Case-folded only on win32, because NTFS resolves names case-insensitively
+ * and `realpathSync` does not promise canonical case — without the fold,
+ * `C:\Repos` and `c:\repos` read as two checkouts of one service and convict
+ * an innocent tree of `binding-duplicate`. The fold is NOT applied elsewhere:
+ * on a case-sensitive filesystem two genuinely distinct directories may differ
+ * only by case, and folding there would silently merge them.
+ *
+ * `null` means the path names nothing on this machine — for a candidate's
+ * docsDir that is the answer "bound to a missing or foreign fleet", never an
+ * error.
+ */
+function identityOf(dir) {
+    try {
+        const real = realpathSync(dir);
+        return process.platform === "win32" ? real.toLowerCase() : real;
+    }
+    catch {
+        // Unresolvable is a fact about the filesystem, not a failure of the scan.
+        return null;
+    }
+}
+/** Read and validate one candidate directory's committed binding. */
+async function readBinding(dir) {
+    let raw;
+    try {
+        // The read stays inside the try that classifies it: a loam.json that is a
+        // directory, or one whose permissions refuse us, is "exists but cannot be
+        // believed", exactly as loadConfig treats the same failures.
+        raw = await readFile(join(dir, CONFIG_FILENAME), "utf8");
+    }
+    catch (err) {
+        const e = err;
+        // Not present reads as "not bound to anything" — most siblings of a docs
+        // repo are ordinary directories, and silence is the honest answer for them.
+        if (e.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "unreadable", problem: err instanceof Error ? err.message : String(err) };
+    }
+    try {
+        // THE config validator — a second opinion here would let `loam open` count
+        // a checkout every other command refuses to load, or vice versa.
+        return { kind: "config", config: parseConfig(raw, dir) };
+    }
+    catch (err) {
+        return { kind: "unreadable", problem: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Depth-1 candidate directories under one scan root, sorted by name so the
+ * member set never depends on readdir order — or the reason the root could
+ * not be listed at all. The failure is DATA here, not a degrade: whether an
+ * unlistable root reads as empty (a default root a CI sandbox denies) or as a
+ * refusal (an explicit `--root` that owes an honest answer) is the caller's
+ * decision, and this function deciding it would hide the second case forever.
+ */
+async function candidateDirs(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (err) {
+        return { kind: "unlistable", problem: err instanceof Error ? err.message : String(err) };
+    }
+    const dirs = [];
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        const candidate = join(root, entry.name);
+        if (entry.isDirectory()) {
+            dirs.push(candidate);
+            continue;
+        }
+        if (!entry.isSymbolicLink())
+            continue;
+        try {
+            // A symlinked sibling is a real checkout on its other end — developers
+            // link worktrees beside a docs repo — so it is classified by its target.
+            if (statSync(candidate).isDirectory())
+                dirs.push(candidate);
+        }
+        catch {
+            // A dangling link names nothing; there is no checkout to consider.
+        }
+    }
+    return { kind: "listed", dirs };
+}
+/**
+ * Derive the workspace member set from the committed bindings.
+ *
+ * The docs repo and the current repo are always members — their bindings are
+ * the committed facts `loadConfig` already validated. A scanned sibling is a
+ * member iff its loam.json parses and resolves its docsDir to this docs repo.
+ * Ordering is deterministic: docs repo, current repo, then scan members
+ * sorted by folder name and path.
+ *
+ * Throws `DocsRepoUnavailableError` when the docs repo's own identity cannot
+ * be established — it passed the readiness gate moments ago, so an
+ * unresolvable realpath here means it vanished mid-run. Failing closed is the
+ * doctrine: comparing candidates against a guessed identity would silently
+ * drop every member and answer `no-members` about a fleet nobody scanned.
+ */
+export async function discoverMembers(req) {
+    const docsIdentity = identityOf(req.docsDir);
+    if (docsIdentity === null) {
+        throw new DocsRepoUnavailableError({ kind: "missing", path: req.docsDir }, `The configured docs repo does not exist: ${req.docsDir}. ` +
+            "Fix `docsDir` in loam.json, clone the docs repo there, " +
+            "or run `loam init --docs <dir> --create` to make a new one.");
+    }
+    const seen = new Set([docsIdentity]);
+    const docsMember = {
+        path: req.docsDir,
+        name: basename(req.docsDir),
+        service: null,
+        via: "docs-repo",
+    };
+    // Run from the docs repo itself, the current repo IS the docs repo: one
+    // member, and it answers as the docs repo — "docs-repo" is the stronger
+    // fact. The `?? spelling` fallback only feeds the dedupe key: an
+    // unresolvable configRoot still becomes a member, it just dedupes by its
+    // own spelling instead of a canonical one.
+    const currentIdentity = identityOf(req.configRoot) ?? req.configRoot;
+    const currentMember = seen.has(currentIdentity)
+        ? null
+        : {
+            path: req.configRoot,
+            name: req.service ?? basename(req.configRoot),
+            service: req.service ?? null,
+            via: "current-repo",
+        };
+    if (currentMember !== null)
+        seen.add(currentIdentity);
+    // Default roots: beside the docs repo and beside the current repo — the
+    // side-by-side layout SCHEMA.md's "../docs-repo" example already assumes.
+    // Usually one directory; identity-deduped so it is scanned once.
+    const scannedRoots = [];
+    const rootIds = new Set();
+    for (const root of req.roots ?? [dirname(req.docsDir), dirname(req.configRoot)]) {
+        const id = identityOf(root) ?? root;
+        if (rootIds.has(id))
+            continue;
+        rootIds.add(id);
+        scannedRoots.push(root);
+    }
+    const unreadableRoots = [];
+    const skipped = [];
+    const scanMembers = [];
+    // The ROOT loop is sequential on purpose: `seen` is a shared accumulator
+    // and "the earlier root wins" is the documented tie-break for a checkout
+    // reachable under two roots — scanning roots in parallel would make
+    // membership depend on I/O timing. The candidates WITHIN a root carry no
+    // such ordering, so their bindings are read through the shared pool;
+    // `inOrder` returns them in listing order, which keeps the verdicts below
+    // deterministic anyway.
+    for (const root of scannedRoots) {
+        const listing = await candidateDirs(root);
+        if (listing.kind === "unlistable") {
+            unreadableRoots.push({ root, problem: listing.problem });
+            continue;
+        }
+        const bindings = await inOrder(listing.dirs, async (dir) => ({
+            dir,
+            binding: await readBinding(dir),
+        }));
+        for (const { dir, binding } of bindings) {
+            // Identity first, before any verdict: a candidate that already IS a
+            // member (the docs repo itself, the current repo, a symlink twin from
+            // an earlier root) must not be re-reported — least of all as skipped,
+            // which would call one checkout both a member and unreadable.
+            const id = identityOf(dir) ?? dir;
+            if (seen.has(id))
+                continue;
+            if (binding.kind === "absent")
+                continue;
+            if (binding.kind === "unreadable") {
+                // Reported, never fatal — "a file loam cannot read is reported, never
+                // skipped" — but never a member either: an unreadable binding proves
+                // nothing about which fleet the checkout belongs to.
+                skipped.push({ path: join(dir, CONFIG_FILENAME), problem: binding.problem });
+                continue;
+            }
+            // The join itself: bound to THIS docs repo, or not a member. `null`
+            // (docsDir names nothing here) is a checkout of a missing or foreign
+            // fleet — silently out, exactly like one bound elsewhere.
+            if (identityOf(binding.config.docsDir) !== docsIdentity)
+                continue;
+            seen.add(id);
+            scanMembers.push({
+                path: dir,
+                name: binding.config.service ?? basename(dir),
+                service: binding.config.service ?? null,
+                via: "scan",
+                root,
+            });
+        }
+    }
+    scanMembers.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    // Two realpath-DISTINCT checkouts declaring one service id: loam cannot know
+    // which one speaks for the service, and a workspace is derived, not guessed.
+    // The current repo participates — a scanned twin of the repo you are
+    // standing in is the commonest way this happens (a second worktree).
+    const byService = new Map();
+    for (const member of [...(currentMember === null ? [] : [currentMember]), ...scanMembers]) {
+        if (member.service === null)
+            continue;
+        byService.set(member.service, [...(byService.get(member.service) ?? []), member.path]);
+    }
+    const duplicates = [...byService.entries()]
+        .filter(([, paths]) => paths.length > 1)
+        .map(([service, paths]) => ({ service, paths }))
+        .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));
+    return {
+        members: [docsMember, ...(currentMember === null ? [] : [currentMember]), ...scanMembers],
+        scannedRoots,
+        unreadableRoots,
+        skipped,
+        duplicates,
+    };
+}
+//# sourceMappingURL=discover.js.map

package/dist/core/workspace/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/core/workspace/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAmB,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAoD5D;;;;;;;;;;;;;;;GAeG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAQD,qEAAqE;AACrE,KAAK,UAAU,WAAW,CAAC,GAAW;IACpC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,0EAA0E;QAC1E,0EAA0E;QAC1E,6DAA6D;QAC7D,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAA4B,CAAC;QACvC,yEAAyE;QACzE,4EAA4E;QAC5E,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3F,CAAC;IACD,IAAI,CAAC;QACH,2EAA2E;QAC3E,iEAAiE;QACjE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3F,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAY;IAEZ,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3F,CAAC;IACD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7F,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE;YAAE,SAAS;QACtC,IAAI,CAAC;YACH,uEAAuE;YACvE,yEAAyE;YACzE,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;gBAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9D,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAoB;IACxD,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,IAAI,wBAAwB,CAChC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,EACtC,4CAA4C,GAAG,CAAC,OAAO,IAAI;YACzD,yDAAyD;YACzD,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAoB;QAClC,IAAI,EAAE,GAAG,CAAC,OAAO;QACjB,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;QAC3B,OAAO,EAAE,IAAI;QACb,GAAG,EAAE,WAAW;KACjB,CAAC;IAEF,wEAAwE;IACxE,wEAAwE;IACxE,iEAAiE;IACjE,yEAAyE;IACzE,2CAA2C;IAC3C,MAAM,eAAe,GAAG,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC;IACrE,MAAM,aAAa,GAA2B,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC;QACrE,CAAC,CAAC,IAAI;QACN,CAAC,CAAC;YACE,IAAI,EAAE,GAAG,CAAC,UAAU;YACpB,IAAI,EAAE,GAAG,CAAC,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;YAC7C,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,GAAG,EAAE,cAAc;SACpB,CAAC;IACN,IAAI,aAAa,KAAK,IAAI;QAAE,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAEtD,wEAAwE;IACxE,0EAA0E;IAC1E,iEAAiE;IACjE,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;QACpC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC9B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,eAAe,GAAiC,EAAE,CAAC;IACzD,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,MAAM,WAAW,GAAsB,EAAE,CAAC;IAC1C,yEAAyE;IACzE,yEAAyE;IACzE,oEAAoE;IACpE,yEAAyE;IACzE,qEAAqE;IACrE,0EAA0E;IAC1E,wBAAwB;IACxB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAClC,eAAe,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACzD,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YAC3D,GAAG;YACH,OAAO,EAAE,MAAM,WAAW,CAAC,GAAG,CAAC;SAChC,CAAC,CAAC,CAAC;QACJ,KAAK,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,QAAQ,EAAE,CAAC;YACxC,oEAAoE;YACpE,sEAAsE;YACtE,sEAAsE;YACtE,8DAA8D;YAC9D,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;YAClC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC3B,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;gBAAE,SAAS;YACxC,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAClC,sEAAsE;gBACtE,qEAAqE;gBACrE,qDAAqD;gBACrD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7E,SAAS;YACX,CAAC;YACD,oEAAoE;YACpE,qEAAqE;YACrE,0DAA0D;YAC1D,IAAI,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,YAAY;gBAAE,SAAS;YAClE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC;gBAC7C,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI;gBACvC,GAAG,EAAE,MAAM;gBACX,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACxB,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC5F,CAAC;IAEF,6EAA6E;IAC7E,6EAA6E;IAC7E,qEAAqE;IACrE,qEAAqE;IACrE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC9C,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC;QAC1F,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;YAAE,SAAS;QACtC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;SAC/C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhF,OAAO;QACL,OAAO,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC;QACzF,YAAY;QACZ,eAAe;QACf,OAAO;QACP,UAAU;KACX,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Member discovery for `loam open` — pure computation, no printing.\n *\n * The hard problem this module solves is binding DIRECTION: each service\n * repo's committed loam.json points AT the docs repo, and the docs repo knows\n * nothing about who points at it. So membership is a join computed at run\n * time — {candidate directory has a loam.json} ∧ {that config resolves its\n * docsDir to this docs repo} — over a deliberately bounded search: a depth-1\n * readdir of a handful of roots, never a disk walk. Same committed files plus\n * same filesystem always produce the same member set, in the same order.\n */\nimport { realpathSync, statSync } from \"node:fs\";\nimport { readFile, readdir } from \"node:fs/promises\";\nimport { basename, dirname, join } from \"node:path\";\nimport { CONFIG_FILENAME, parseConfig, type LoamConfig } from \"../envelope/config.js\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { ServiceId } from \"../kernel/ids/service.js\";\nimport { DocsRepoUnavailableError } from \"../repo/state.js\";\n\ninterface MemberFacts {\n  /** Absolute path of the member's repository root. */\n  path: string;\n  /** Folder display name: the member's service id when bound, else its basename. */\n  name: string;\n  service: ServiceId | null;\n}\n\n/**\n * One folder of the workspace being derived, with where it came from. A\n * variant, not an optional field: `root` exists exactly when the member was\n * found by the scan, and the union makes an always-member carrying a scan\n * root — or a scan member missing one — unrepresentable. One arm per `via`\n * value (not \"docs-repo\" | \"current-repo\" folded into one), because a\n * single-literal discriminant is what the checker's narrowing filters on.\n */\nexport type WorkspaceMember =\n  | (MemberFacts & { via: \"docs-repo\" })\n  | (MemberFacts & { via: \"current-repo\" })\n  | (MemberFacts & { via: \"scan\"; root: string });\n\n/** Everything the scan learned, as data — the command decides what refuses. */\nexport interface Discovery {\n  members: WorkspaceMember[];\n  /** The roots actually scanned, deduped, in scan order. */\n  scannedRoots: string[];\n  /**\n   * Roots whose depth-1 listing itself failed. Recorded, never swallowed:\n   * \"nothing is wrong\" and \"I could not look\" are opposite facts, and only\n   * the caller knows whether the root was a degradable default or an explicit\n   * `--root` that owes a refusal.\n   */\n  unreadableRoots: { root: string; problem: string }[];\n  /** Candidates whose loam.json exists but cannot be believed — reported, never members. */\n  skipped: { path: string; problem: string }[];\n  /** Service ids declared by two or more realpath-distinct member checkouts. */\n  duplicates: { service: string; paths: string[] }[];\n}\n\nexport interface DiscoverRequest {\n  /** Resolved docs repo root — the identity every candidate binding is compared against. */\n  docsDir: DocsDir;\n  /** Root of the repo whose loam.json governs this invocation (`config.root`). */\n  configRoot: string;\n  /** The service that repo declares, when it declares one. */\n  service?: ServiceId;\n  /** Explicit scan roots. When present they REPLACE the defaults — an explicit scan is exactly what was asked. */\n  roots?: string[];\n}\n\n/**\n * One directory's identity for \"is this the same checkout?\" comparisons.\n *\n * Realpath first, because two spellings of one directory (a symlinked sibling,\n * an 8.3 short name, a `..` route) must not become two workspace folders.\n * Case-folded only on win32, because NTFS resolves names case-insensitively\n * and `realpathSync` does not promise canonical case — without the fold,\n * `C:\\Repos` and `c:\\repos` read as two checkouts of one service and convict\n * an innocent tree of `binding-duplicate`. The fold is NOT applied elsewhere:\n * on a case-sensitive filesystem two genuinely distinct directories may differ\n * only by case, and folding there would silently merge them.\n *\n * `null` means the path names nothing on this machine — for a candidate's\n * docsDir that is the answer \"bound to a missing or foreign fleet\", never an\n * error.\n */\nfunction identityOf(dir: string): string | null {\n  try {\n    const real = realpathSync(dir);\n    return process.platform === \"win32\" ? real.toLowerCase() : real;\n  } catch {\n    // Unresolvable is a fact about the filesystem, not a failure of the scan.\n    return null;\n  }\n}\n\n/** A parsed candidate binding, or the reason it cannot be believed. */\ntype Candidate =\n  | { kind: \"config\"; config: LoamConfig }\n  | { kind: \"unreadable\"; problem: string }\n  | { kind: \"absent\" };\n\n/** Read and validate one candidate directory's committed binding. */\nasync function readBinding(dir: string): Promise<Candidate> {\n  let raw: string;\n  try {\n    // The read stays inside the try that classifies it: a loam.json that is a\n    // directory, or one whose permissions refuse us, is \"exists but cannot be\n    // believed\", exactly as loadConfig treats the same failures.\n    raw = await readFile(join(dir, CONFIG_FILENAME), \"utf8\");\n  } catch (err) {\n    const e = err as NodeJS.ErrnoException;\n    // Not present reads as \"not bound to anything\" — most siblings of a docs\n    // repo are ordinary directories, and silence is the honest answer for them.\n    if (e.code === \"ENOENT\") return { kind: \"absent\" };\n    return { kind: \"unreadable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n  try {\n    // THE config validator — a second opinion here would let `loam open` count\n    // a checkout every other command refuses to load, or vice versa.\n    return { kind: \"config\", config: parseConfig(raw, dir) };\n  } catch (err) {\n    return { kind: \"unreadable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/**\n * Depth-1 candidate directories under one scan root, sorted by name so the\n * member set never depends on readdir order — or the reason the root could\n * not be listed at all. The failure is DATA here, not a degrade: whether an\n * unlistable root reads as empty (a default root a CI sandbox denies) or as a\n * refusal (an explicit `--root` that owes an honest answer) is the caller's\n * decision, and this function deciding it would hide the second case forever.\n */\nasync function candidateDirs(\n  root: string,\n): Promise<{ kind: \"listed\"; dirs: string[] } | { kind: \"unlistable\"; problem: string }> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (err) {\n    return { kind: \"unlistable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n  const dirs: string[] = [];\n  for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {\n    const candidate = join(root, entry.name);\n    if (entry.isDirectory()) {\n      dirs.push(candidate);\n      continue;\n    }\n    if (!entry.isSymbolicLink()) continue;\n    try {\n      // A symlinked sibling is a real checkout on its other end — developers\n      // link worktrees beside a docs repo — so it is classified by its target.\n      if (statSync(candidate).isDirectory()) dirs.push(candidate);\n    } catch {\n      // A dangling link names nothing; there is no checkout to consider.\n    }\n  }\n  return { kind: \"listed\", dirs };\n}\n\n/**\n * Derive the workspace member set from the committed bindings.\n *\n * The docs repo and the current repo are always members — their bindings are\n * the committed facts `loadConfig` already validated. A scanned sibling is a\n * member iff its loam.json parses and resolves its docsDir to this docs repo.\n * Ordering is deterministic: docs repo, current repo, then scan members\n * sorted by folder name and path.\n *\n * Throws `DocsRepoUnavailableError` when the docs repo's own identity cannot\n * be established — it passed the readiness gate moments ago, so an\n * unresolvable realpath here means it vanished mid-run. Failing closed is the\n * doctrine: comparing candidates against a guessed identity would silently\n * drop every member and answer `no-members` about a fleet nobody scanned.\n */\nexport async function discoverMembers(req: DiscoverRequest): Promise<Discovery> {\n  const docsIdentity = identityOf(req.docsDir);\n  if (docsIdentity === null) {\n    throw new DocsRepoUnavailableError(\n      { kind: \"missing\", path: req.docsDir },\n      `The configured docs repo does not exist: ${req.docsDir}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n  }\n  const seen = new Set<string>([docsIdentity]);\n  const docsMember: WorkspaceMember = {\n    path: req.docsDir,\n    name: basename(req.docsDir),\n    service: null,\n    via: \"docs-repo\",\n  };\n\n  // Run from the docs repo itself, the current repo IS the docs repo: one\n  // member, and it answers as the docs repo — \"docs-repo\" is the stronger\n  // fact. The `?? spelling` fallback only feeds the dedupe key: an\n  // unresolvable configRoot still becomes a member, it just dedupes by its\n  // own spelling instead of a canonical one.\n  const currentIdentity = identityOf(req.configRoot) ?? req.configRoot;\n  const currentMember: WorkspaceMember | null = seen.has(currentIdentity)\n    ? null\n    : {\n        path: req.configRoot,\n        name: req.service ?? basename(req.configRoot),\n        service: req.service ?? null,\n        via: \"current-repo\",\n      };\n  if (currentMember !== null) seen.add(currentIdentity);\n\n  // Default roots: beside the docs repo and beside the current repo — the\n  // side-by-side layout SCHEMA.md's \"../docs-repo\" example already assumes.\n  // Usually one directory; identity-deduped so it is scanned once.\n  const scannedRoots: string[] = [];\n  const rootIds = new Set<string>();\n  for (const root of req.roots ?? [dirname(req.docsDir), dirname(req.configRoot)]) {\n    const id = identityOf(root) ?? root;\n    if (rootIds.has(id)) continue;\n    rootIds.add(id);\n    scannedRoots.push(root);\n  }\n\n  const unreadableRoots: Discovery[\"unreadableRoots\"] = [];\n  const skipped: Discovery[\"skipped\"] = [];\n  const scanMembers: WorkspaceMember[] = [];\n  // The ROOT loop is sequential on purpose: `seen` is a shared accumulator\n  // and \"the earlier root wins\" is the documented tie-break for a checkout\n  // reachable under two roots — scanning roots in parallel would make\n  // membership depend on I/O timing. The candidates WITHIN a root carry no\n  // such ordering, so their bindings are read through the shared pool;\n  // `inOrder` returns them in listing order, which keeps the verdicts below\n  // deterministic anyway.\n  for (const root of scannedRoots) {\n    const listing = await candidateDirs(root);\n    if (listing.kind === \"unlistable\") {\n      unreadableRoots.push({ root, problem: listing.problem });\n      continue;\n    }\n    const bindings = await inOrder(listing.dirs, async (dir) => ({\n      dir,\n      binding: await readBinding(dir),\n    }));\n    for (const { dir, binding } of bindings) {\n      // Identity first, before any verdict: a candidate that already IS a\n      // member (the docs repo itself, the current repo, a symlink twin from\n      // an earlier root) must not be re-reported — least of all as skipped,\n      // which would call one checkout both a member and unreadable.\n      const id = identityOf(dir) ?? dir;\n      if (seen.has(id)) continue;\n      if (binding.kind === \"absent\") continue;\n      if (binding.kind === \"unreadable\") {\n        // Reported, never fatal — \"a file loam cannot read is reported, never\n        // skipped\" — but never a member either: an unreadable binding proves\n        // nothing about which fleet the checkout belongs to.\n        skipped.push({ path: join(dir, CONFIG_FILENAME), problem: binding.problem });\n        continue;\n      }\n      // The join itself: bound to THIS docs repo, or not a member. `null`\n      // (docsDir names nothing here) is a checkout of a missing or foreign\n      // fleet — silently out, exactly like one bound elsewhere.\n      if (identityOf(binding.config.docsDir) !== docsIdentity) continue;\n      seen.add(id);\n      scanMembers.push({\n        path: dir,\n        name: binding.config.service ?? basename(dir),\n        service: binding.config.service ?? null,\n        via: \"scan\",\n        root,\n      });\n    }\n  }\n  scanMembers.sort((a, b) =>\n    a.name < b.name ? -1 : a.name > b.name ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0,\n  );\n\n  // Two realpath-DISTINCT checkouts declaring one service id: loam cannot know\n  // which one speaks for the service, and a workspace is derived, not guessed.\n  // The current repo participates — a scanned twin of the repo you are\n  // standing in is the commonest way this happens (a second worktree).\n  const byService = new Map<string, string[]>();\n  for (const member of [...(currentMember === null ? [] : [currentMember]), ...scanMembers]) {\n    if (member.service === null) continue;\n    byService.set(member.service, [...(byService.get(member.service) ?? []), member.path]);\n  }\n  const duplicates = [...byService.entries()]\n    .filter(([, paths]) => paths.length > 1)\n    .map(([service, paths]) => ({ service, paths }))\n    .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));\n\n  return {\n    members: [docsMember, ...(currentMember === null ? [] : [currentMember]), ...scanMembers],\n    scannedRoots,\n    unreadableRoots,\n    skipped,\n    duplicates,\n  };\n}\n"]}

package/dist/core/workspace/render.js

@@ -0,0 +1,52 @@
+/**
+ * Deterministic `.code-workspace` rendering — pure computation, no printing.
+ *
+ * The output is a derived file: same members plus same target path must
+ * produce the same bytes on every machine, which is why every path is spelled
+ * with forward slashes (VS Code and Cursor accept them on Windows too, and
+ * they are the one spelling that diffs identically across checkouts) and why
+ * the JSON shape follows saveConfig's convention — 2-space indent, trailing
+ * newline.
+ */
+import { dirname, isAbsolute, relative } from "node:path";
+/**
+ * The `path` a folder entry gets, from the already-computed relative and the
+ * member's absolute path.
+ *
+ * Split out of `renderWorkspace` because the fallback decision is win32-only
+ * on a win32 host — `relative()` answers a cross-drive pair with the ABSOLUTE
+ * target, since no `..` chain crosses drives — and a POSIX test host can
+ * therefore never steer the platform `relative()` into producing one. Taking
+ * `rel` as data lets the suite exercise the branch with win32-shaped input.
+ *
+ * The drive-letter test backs up `isAbsolute` because that check is also
+ * platform-bound: on POSIX, `D:\other\svc` reads as a relative name. A POSIX
+ * directory literally named `D:` would match too and get the absolute
+ * spelling instead of the relative one — a stranger workspace file, but a
+ * correct one, and the pathological name is not worth a platform fork here.
+ */
+export function workspacePathSpelling(rel, absolute) {
+    const spelling = rel === "" ? "." : isAbsolute(rel) || /^[A-Za-z]:[\\/]/.test(rel) ? absolute : rel;
+    return spelling.split(/[\\/]/).join("/");
+}
+/**
+ * Render the workspace document for `members`, targeted at `outPath`.
+ *
+ * Folder paths are relative to the file's own directory, so the committed
+ * side-by-side layout opens on every machine that checks it out; a member on
+ * another drive keeps its absolute path, because no relative spelling exists.
+ * The folders are returned still attached to their members so the command can
+ * echo the exact written spelling into its `--json` payload without joining
+ * two arrays by position.
+ */
+export function renderWorkspace(members, outPath) {
+    const outDir = dirname(outPath);
+    const folders = members.map((member) => ({
+        member,
+        name: member.name,
+        path: workspacePathSpelling(relative(outDir, member.path), member.path),
+    }));
+    const text = JSON.stringify({ folders: folders.map(({ name, path }) => ({ name, path })) }, null, 2) + "\n";
+    return { text, folders };
+}
+//# sourceMappingURL=render.js.map

package/dist/core/workspace/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/core/workspace/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAY1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,QAAgB;IACjE,MAAM,QAAQ,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;IACpG,OAAO,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAmC,EACnC,OAAe;IAEf,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvC,MAAM;QACN,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,qBAAqB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC;KACxE,CAAC,CAAC,CAAC;IACJ,MAAM,IAAI,GACR,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACjG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["/**\n * Deterministic `.code-workspace` rendering — pure computation, no printing.\n *\n * The output is a derived file: same members plus same target path must\n * produce the same bytes on every machine, which is why every path is spelled\n * with forward slashes (VS Code and Cursor accept them on Windows too, and\n * they are the one spelling that diffs identically across checkouts) and why\n * the JSON shape follows saveConfig's convention — 2-space indent, trailing\n * newline.\n */\nimport { dirname, isAbsolute, relative } from \"node:path\";\nimport type { WorkspaceMember } from \"./discover.js\";\n\n/** One folder row, still carrying the member it was derived from. */\nexport interface RenderedFolder {\n  member: WorkspaceMember;\n  /** Exactly what lands in the file's `name`. */\n  name: string;\n  /** Exactly what lands in the file's `path` — the forward-slash spelling. */\n  path: string;\n}\n\n/**\n * The `path` a folder entry gets, from the already-computed relative and the\n * member's absolute path.\n *\n * Split out of `renderWorkspace` because the fallback decision is win32-only\n * on a win32 host — `relative()` answers a cross-drive pair with the ABSOLUTE\n * target, since no `..` chain crosses drives — and a POSIX test host can\n * therefore never steer the platform `relative()` into producing one. Taking\n * `rel` as data lets the suite exercise the branch with win32-shaped input.\n *\n * The drive-letter test backs up `isAbsolute` because that check is also\n * platform-bound: on POSIX, `D:\\other\\svc` reads as a relative name. A POSIX\n * directory literally named `D:` would match too and get the absolute\n * spelling instead of the relative one — a stranger workspace file, but a\n * correct one, and the pathological name is not worth a platform fork here.\n */\nexport function workspacePathSpelling(rel: string, absolute: string): string {\n  const spelling = rel === \"\" ? \".\" : isAbsolute(rel) || /^[A-Za-z]:[\\\\/]/.test(rel) ? absolute : rel;\n  return spelling.split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * Render the workspace document for `members`, targeted at `outPath`.\n *\n * Folder paths are relative to the file's own directory, so the committed\n * side-by-side layout opens on every machine that checks it out; a member on\n * another drive keeps its absolute path, because no relative spelling exists.\n * The folders are returned still attached to their members so the command can\n * echo the exact written spelling into its `--json` payload without joining\n * two arrays by position.\n */\nexport function renderWorkspace(\n  members: readonly WorkspaceMember[],\n  outPath: string,\n): { text: string; folders: RenderedFolder[] } {\n  const outDir = dirname(outPath);\n  const folders = members.map((member) => ({\n    member,\n    name: member.name,\n    path: workspacePathSpelling(relative(outDir, member.path), member.path),\n  }));\n  const text =\n    JSON.stringify({ folders: folders.map(({ name, path }) => ({ name, path })) }, null, 2) + \"\\n\";\n  return { text, folders };\n}\n"]}

package/examples/README.md

@@ -0,0 +1,189 @@
+# The example fleet
+
+`docs/` is a complete, runnable loam docs repo. It is small enough to read in one sitting and large
+enough that every row of [SCHEMA.md](../SCHEMA.md)'s canonical-joins table is exercised by something
+— including the joins that only appear once a fleet has more than two services in it.
+
+Run it from a clone. `docs/loam.json` is committed and says `"docsDir": "."`, so the tree governs
+itself: every command below resolves to this fleet because it is run from inside it. There is
+nothing to write first and nothing to delete afterwards.
+
+```bash
+cd examples/docs
+loam list                          # the fleet and its maturity ladder
+loam status                        # what to do next, derived from the files
+loam validate --all                # the gate CI runs
+loam archive FEAT-101 --dry-run    # the three-axis merge plan, writing nothing
+loam archive FEAT-112 --dry-run    # an operation being retired, writing nothing
+loam verify FEAT-088               # a shipped feature's done-check: attested
+loam verify FEAT-120               # …and its pair, the same check: verified
+loam dependencies                  # the active-feature graph
+```
+
+Working on loam itself and running from source, use `npx tsx ../../src/cli.ts <args>` in place of
+`loam`. Not `npm run dev --`: npm runs a script from the package root, so it would leave
+`examples/docs` and resolve some other `loam.json` — the fleet it reported would not be this one.
+
+`test/examples.test.ts` pins the validate summary, every finding code and the archive plans
+file-for-file, so nothing below can drift away from the code without a test going red.
+
+## What is in it
+
+Five services, drawn inside one grouping element so the map looks like ordinary grouped C4:
+
+| service | what it is here to show |
+|---|---|
+| `checkout-web` | a UI service: page-specs under `ui/pages/`, no `openapi.yaml` of its own, and the one spec in the fleet that names no `sources` |
+| `order-service` | the busiest spine: four operations, a produced event, a consumed event, and a deprecated operation with a feature already open to retire it |
+| `payment-service` | the outbox, the acquirer, and an `arch.spec.md` whose `Covers:` lines reach the C4 model *and* the health signals |
+| `identity-service` | the permission vocabulary's owner, and a deprecated operation whose consumer has not migrated — filed into `services/platform/` |
+| `notification-service` | a service with no HTTP API at all — three consumed messages, one of them from a producer outside the fleet — filed into `services/platform/` |
+
+Around them: `kafka` as an `#external` `#platform` system with a topic per channel (edges point at
+the topic, never at the broker), `stripe` and `salesforce` as external systems, and
+`architecture/permissions.yaml` as the fleet's authorization vocabulary.
+
+**Three authored capability documents**, which are the business tree rather than the architecture:
+`capabilities/checkout/spec.md`, `capabilities/identity/tokens/spec.md` and
+`capabilities/order-notifications/spec.md`. The third carries the axis's second realizer: its one
+promise — "a placed order produces exactly one confirmation" — is cross-service by construction, so
+no service's `spec.md` can keep it, and `architecture/usecases/order-notification.likec4` claims it
+with `#req-NOTIFY-ONCE` beside its `#cap-` tag. The other two are kept by service requirements
+through `Realizes:`. Both ids are also declared in `architecture/capabilities.yaml` — the vocabulary
+is the union of the two sides, and a name a document elaborates does not have to leave the YAML,
+which is what keeps the metadata (`description`, `owner`) that a document has no field for. The
+nested one carries the lesson: the id `identity/tokens` keeps its slash everywhere it is written, so
+the tree spells it as directories, and `capabilities/identity/` holding no `spec.md` of its own is a
+GROUP and earns no finding. Each requirement in both files is a promise a customer could check,
+names no service, and carries a `Requirement-ID:` — required here, unlike in a service spec, because
+these documents outlive every service that realizes them.
+
+**Two glossary terms**, `glossary/order.md` and the nested `glossary/payments/authorization.md`,
+each cited from the capability documents that use the word. This is the axis's whole mechanism in
+two files: the citation is an ordinary markdown link, so `loam validate` resolves it like any other
+and `loam list glossary` can answer "which documents use this term" as a join rather than a grep.
+The two terms also cite EACH OTHER, which is deliberate — a glossary is a network of definitions —
+and that reciprocal pair is exactly what does NOT count as adoption: both terms stay out of
+`glossary.unlinked` because a capability document cites them, not because they cite each other.
+Delete either of those two capability citations and the example gains a tenth warning.
+
+**One architectural obligation, declared and applied and met** — which is three files agreeing, and
+the axis's whole mechanism. `architecture/adrs/0001-transactional-outbox.md` says WHAT was decided;
+`#obl-outbox` on the `payment-service → kafka.paymentEvents` edge in the fleet map says WHERE it
+holds (on the publish edge, not on the service — payment-service also serves an API that owes
+nothing of the kind); `architecture/obligations.yaml` declares the name so a mistyped tag is an
+error rather than a word nobody notices; and `ARCH-PAY-OUTBOX` in payment-service's `arch.spec.md`
+covers that same edge, which is the team saying it is met. Because all four line up, the example is
+SILENT about the outbox — the working join produces no finding, which is what a working join should
+do. The second declaration, `idempotency-key`, is the one that talks: it is declared and placed
+nowhere, and `obligation.unapplied` is the warning in the table below.
+
+**On the event spine the arrow follows the message** — producer → topic for `publishes`, topic →
+consumer for `consumes` — and that is load-bearing rather than aesthetic. `publishes` binds the
+edge's source and `consumes` binds its target, so a consume edge drawn the other way round binds to
+nothing: the metadata parses, the document validates, and the check silently grades zero edges.
+Nothing in loam reports that today, which is why the landscape says so in a comment.
+
+## Four features, at four points in their life
+
+The two archived ones are a **matched pair**, and the pairing is the point: same command, same
+shape of record, two different verdicts. A showcase that demonstrated only one would teach that the
+distinction is decorative — and keeping those two answers apart is most of what loam claims to be
+for.
+
+- **`features/archive/FEAT-088-refunds/`** — shipped, and **`attested`**. It was merged by the real
+  `loam archive`, so its `.loam-before/` snapshot holds the exact bytes the merge overwrote and
+  `loam unarchive FEAT-088` would put them back. Its `verification.yaml` is the done-check written
+  down: every claim is confirmed, but the scenario claims rest on an agent's word instead of a
+  digest-matched test run. loam does not pretend those are the same thing.
+- **`features/archive/FEAT-120-refund-notification/`** — shipped, and **`verified`**. The sequel
+  FEAT-088 left open: the money went back and nobody told the customer. It publishes
+  `payment.PaymentRefunded` from payment-service and has notification-service turn it into the
+  message the customer is waiting for — so it exercises the event spine end to end, across two
+  services, with no HTTP anywhere in it.
+
+  Its five scenario claims were answered by `--results` from the `scenario-report.json` beside it:
+  loam's own runner-neutral `{"loamScenarioReport": 1, …}` shape, which any runner can be adapted
+  into. Its two `event.declares` claims still rest on an agent's word. That mix is the honest
+  common case — a suite that answers the scenarios, and wiring claims a human vouches for — and it
+  still reads `verified`, because the verdict turns on the scenario claims alone.
+- **`features/FEAT-101-payment-splitting/`** — in flight, and the big one: a new service arriving
+  with its own requirements, architecture requirements and contract, a C4 delta that splices a
+  nested element into the living landscape, a `MODIFIED` requirement that **renames its heading**
+  while keeping its `Requirement-ID` — loam's rename mechanism — and an **event-contract delta**
+  (`specs/payment-service/asyncapi.yaml`): a complete AsyncAPI 3.0 document restating
+  payment-service's living contract under `loam rebase`-written `x-loam-based-on` pins and adding
+  one new producer side, so the archive merges the new slots and leaves every pinned quote to the
+  living contract's own copy.
+- **`features/FEAT-112-retire-order-v1/`** — in flight, and the smallest legal shape: no
+  `delta.likec4` at all, because retiring an operation moves no boxes. It carries the two halves
+  loam requires together for a removal — a `REMOVED` requirement and an `x-loam-remove: true` marker
+  inside the operation object.
+
+## The warnings are the lesson
+
+`loam validate --all` reports **0 errors and 10 warnings** here, and every one of them is
+deliberate. An example that reported nothing would teach nothing about what these checks catch:
+
+| finding | what it is demonstrating |
+|---|---|
+| `sources.absent` | `checkout-web`'s spec names no `sources`, so nothing ties it to code and `loam vouch` would refuse to stamp it |
+| `spine.op-link-missing` | one landscape edge says it calls payment-service and names no operation, so no check can tell whether the call still exists |
+| `spine.op-deprecated` | payment-service still calls identity-service's `validateToken`, which that contract marks `deprecated: true` — the consumer, not the provider, is the one being told |
+| `api.requirement-deprecated` (×2) | `IDN-VALIDATE-LEGACY` and `ORD-PLACE-V1` each govern only a deprecated operation: promised behaviour on its way out |
+| `permissions.unenforced` | `user/profile:read` is declared in the vocabulary and named by no requirement — the shape a vocabulary drifts into |
+| `capability.unrealized` | `payments/settlement` is declared in `architecture/capabilities.yaml` and no living requirement's `Capability:` line names it — a promise nobody implemented, or a word nobody adopted; `loam list capabilities` shows it as `0 — unrealized` beside the realized ones |
+| `capability.requirement-unrealized` | `checkout#CHECKOUT-PRICE-HONOURED` — one promise inside a capability whose OTHER promise three services realize, so the row above says nothing about it. That contrast IS the demonstration: `capability.unrealized` finds a capability nobody claimed, and only this code finds the gap inside a capability that looks healthy. Three requirements do carry `Realizes:` lines — `WEB-CHECKOUT`, `ORD-PLACE` and `PAY-AUTHORIZE` all name `checkout#CHECKOUT-CHARGE-ONCE` — and the fourth promise is simply not implemented, which is a normal state for a business document written ahead of the fleet |
+| `c4.uncovered` | FEAT-101 adds a `checkout-web → payment-split-service` edge that no arch requirement covers, so its architectural obligations would ship untested |
+| `obligation.unapplied` | `idempotency-key` is declared in `architecture/obligations.yaml` and no `#obl-` tag applies it anywhere on the fleet map — a decision that was reversed and left its word behind, or one nobody has placed yet. Its sibling `outbox` IS placed and IS covered, and says nothing: that contrast is the demonstration |
+
+**Two of the five are filed into a subsystem.** `services/platform/` (its `subsystem.yaml` is the
+marker — title and description, never members) groups `identity-service` and `notification-service`,
+while the other three sit unfiled — the permanent, normal state a partially organized fleet lives
+in, counted by `loam list` and never a finding. Placement is not identity: both services' specs,
+contracts and digests are byte-identical to their unfiled days, every command addresses them by bare
+id, and `architecture/subsystems.likec4` — GENERATED by `loam subsystem sync`, one view per
+subsystem, one `include` per line — is the only file the grouping added. Edit the tree with
+`loam subsystem move|rename|rm` and the views file travels in the same transaction; edit it by hand
+and `validate --all` answers `subsystem.views-stale`. (`order-service` and `payment-service` stay
+unfiled deliberately: FEAT-088's committed version-2 snapshot restores them by literal path, and the
+`loam unarchive FEAT-088` walkthrough must keep working byte-for-byte.)
+
+Plus one count rather than a finding: `sourcesUnverifiableFromHere: 4`. Four specs name paths in
+their own service repositories, and this is none of those repositories — the fleet gate reports the
+blind spot instead of resolving it. Running `loam validate --service <id>` inside each service repo
+is what closes it.
+
+## What the example deliberately does not carry
+
+- **`AGENTS.md`.** A real docs repo has one, written by `loam init --docs . --create`. It is left
+  out here because a generated `AGENTS.md` carries the version stamp of the binary that wrote it,
+  and this tree is committed while the binary keeps moving — a stamped copy in the repository would
+  be stale by the next release and would say so to every reader of the example.
+
+  **`loam.json` used to be left out with it**, on the same "keep the tree a pure set of documents"
+  reasoning, and that trade was wrong: without it the example could not be RUN. `loam status` here
+  answered "No loam.json found" and exited 1, and the workaround this page printed instead — a
+  throwaway `loam.json` at the repository root — then governed every other directory in the clone,
+  so `loam init` from anywhere below it refused, and forgetting to delete it silently pointed later
+  commands at the example fleet. It is committed now, byte-for-byte the two lines `loam init` writes
+  for a docs repo that governs itself, which makes `cd examples/docs` the whole of the setup.
+- **`payment-split-service`'s own `asyncapi.yaml`.** The async axis has the full feature lifecycle
+  now — FEAT-101's `specs/payment-service/asyncapi.yaml` demonstrates the merge half on a living
+  contract — but the NEW service's contract for the drawn `PaymentSplit` edge is deliberately
+  deferred: the edge keeps the message in its title and no `metadata { publishes }`, because that
+  metadata is a join and the join demands a contract declaring the send
+  (`c4-event.message-undefined` refuses one without it). A
+  `specs/payment-split-service/asyncapi.yaml` would ride the archive's creation branch once the
+  consumer of `PaymentSplit` exists. The comment in `delta.likec4` says so rather than leaving it to
+  be discovered.
+- **A generated Gherkin suite.** `loam gherkin` writes into a *service's* repository, and there are
+  none here — this fleet is six repositories, and `docs/` is one of them. The same reason leaves
+  `sources` unresolvable and every service `draft`: `loam vouch` only runs where the code is, so no
+  SERVICE in this tree can be promoted past `draft`.
+
+  That is a different word from FEAT-120's `verified` verdict and the two must not be read as one.
+  A service's ladder rung (`empty → partial → documented → sourced → vouched`) says a human stamped
+  its living spec against the code; a feature's verdict says how its claims were answered. FEAT-120
+  is `verified` in a fleet whose services are all `draft`, which is exactly the state a team is in
+  the day its first suite goes green.

package/examples/docs/architecture/adrs/0001-transactional-outbox.md

@@ -0,0 +1,33 @@
+# 0001 — Event publishers write through a transactional outbox
+
+Status: accepted
+Date: 2026-08-28
+
+## Context
+
+A service that writes its own state and then publishes an event about it has two
+places to fail between. The failure is silent and asymmetric: the state change
+lands, the event does not, and every consumer's view of the world is quietly
+wrong until somebody reconciles by hand.
+
+## Decision
+
+A service that publishes a domain event SHALL write the event and the state
+change it reports in one database transaction, and relay it to the broker
+afterwards. Never a dual write.
+
+## Scope
+
+This is not a fleet-wide policy every service inherits — that is the shape this
+repository deliberately does not use. It applies where it is tagged: see
+`#obl-outbox` in [the fleet map](../landscape.likec4), which today marks the
+`payment-service → kafka.paymentEvents` edge and nothing else.
+`payment-service`'s [ARCH-PAY-OUTBOX](../../services/payment-service/arch.spec.md)
+is the requirement that keeps it.
+
+## Consequences
+
+A publisher needs an outbox table and a relay. A consumer must tolerate a
+duplicate: the relay guarantees at-least-once, which is why
+`checkout#CHECKOUT-CHARGE-ONCE` is a promise about the customer's card and not
+about the number of messages.

package/examples/docs/architecture/capabilities.yaml

@@ -0,0 +1,31 @@
+# The fleet's capability vocabulary, joined to requirements by `Capability:`.
+#
+# Opt-in the OTHER way round from permissions.yaml: the FILE is the opt-in, not the line.
+# A fleet without this file gets no capability findings at all, however many `Capability:`
+# lines its requirements carry; writing it is the moment the axis turns on. `loam validate`
+# then grades both directions — an undeclared name is `capability.unknown` (error, with
+# close-name suggestions), an unreadable file is `capability.invalid` exactly once per run,
+# and a declared capability nothing realizes is `capability.unrealized` (warning, one per
+# capability). `loam list capabilities` reports the whole rollup: which requirements realize
+# each capability, in which services, and how much of that rests on drafts.
+#
+# Ids are flat keys with `/` allowed for nesting — `identity/tokens` is ONE id, exactly the
+# token a requirement writes, never collapsed to `identity`. Descriptions and owners are
+# explanatory; nothing resolves them.
+capabilities:
+  checkout:
+    description: carry a customer from a filled cart to a confirmed, paid order
+    owner: checkout-team
+  identity/tokens:
+    description: issue and answer for the access tokens every fleet call presents
+    owner: platform-identity
+  order-notifications:
+    description: tell the customer what happened to their order, exactly once per event
+    owner: growth-team
+  # Declared, and realized by no living requirement anywhere in the fleet — the example's
+  # `capability.unrealized` (warning) demonstration. It is the shape this axis exists to
+  # make visible: a capability page was agreed in a meeting, the word entered the fleet's
+  # vocabulary, and no requirement anywhere claims to implement any part of it.
+  payments/settlement:
+    description: pay merchants out for captured orders
+    owner: payments-team