@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/staging/txn/transaction.js

@@ -0,0 +1,75 @@
+/**
+ * The journaled commit itself: journal (fsynced) → swap → renames → clear,
+ * with archive's ordering on the failure path — the rollback decides the
+ * outcome, and only then does the journal have nothing left to describe. A
+ * crash anywhere inside leaves either the journal plus a recoverable tree
+ * (roll forward finishes it) or a fully rolled-back tree whose stale journal
+ * the next recovery reads as the consistent pre-state.
+ *
+ * Callers stage for themselves before committing, on purpose: vouch's
+ * byte-level raced check and gherkin's planned-vs-read compare both have to
+ * run BETWEEN staging and the swap, against the pre-images staging read.
+ *
+ * The DIRECTORY RENAMES (`spec.moves`, `subsystem move`'s half) come after
+ * every file swap, deliberately: the generated views file must land in the
+ * same commit as the renames or the tree is left failing between two states,
+ * and a failure mid-renames still has the swapped files' pre-images in hand
+ * to roll everything back together — renames undone newest-first, then the
+ * files, one failure list, one verdict.
+ */
+import { rename } from "node:fs/promises";
+import { message, rollbackMessage, rollbackStaged, StagingRaceError, swapStaged } from "../commit.js";
+import {} from "../writes.js";
+import { clearTxnIntent, writeTxnIntent } from "./journal.js";
+/**
+ * `what` is the verb the rollback sentence uses for the half-state ("merged",
+ * "stamped", "written") — each caller keeps the word its operators already
+ * grep their logs for.
+ */
+export async function commitStaged(spec, staged, what) {
+    await writeTxnIntent(spec, staged);
+    const performed = [];
+    try {
+        await swapStaged(staged);
+        for (const move of spec.moves ?? []) {
+            await rename(move.from, move.to);
+            performed.push(move);
+        }
+    }
+    catch (err) {
+        // Renames back first, newest-first: each is its own inverse, and a
+        // directory that cannot go back is exactly as reportable as a file that
+        // cannot — it joins the same failure list and forces the same verdict.
+        const failures = [];
+        for (const move of [...performed].reverse()) {
+            try {
+                await rename(move.to, move.from);
+            }
+            catch (undoErr) {
+                failures.push(`${move.to} (${message(undoErr)})`);
+            }
+        }
+        failures.push(...(await rollbackStaged(staged)));
+        // The journal is cleared only when the rollback HELD. On rollback-incomplete
+        // the tree is genuinely half-written and the temps are gone — the journal
+        // is the one durable record of which files, so doctor keeps naming them,
+        // validate keeps refusing to grade the tree green, and the next writer
+        // refuses commit-interrupted instead of writing over the wreckage. Archive
+        // pays the same way by retaining its snapshot on this path.
+        if (failures.length === 0)
+            await clearTxnIntent(spec.root);
+        const raced = err instanceof StagingRaceError || err.code === "EEXIST";
+        if (failures.length > 0) {
+            // NEVER raced, whatever threw: callers remap a raced failure onto their
+            // own softer code (vouch-raced, already-exists) with "nothing was
+            // written" prose — and here something WAS written and could not be
+            // taken back. rollback-incomplete is the one answer that demands a
+            // human, and no remap may swallow the file list that says where.
+            return { ok: false, code: "rollback-incomplete", message: rollbackMessage(err, failures, what), raced: false };
+        }
+        return { ok: false, code: "merge-failed", message: `${message(err)} — rolled back, nothing was written`, raced };
+    }
+    await clearTxnIntent(spec.root);
+    return { ok: true };
+}
+//# sourceMappingURL=transaction.js.map

package/dist/core/staging/txn/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../../src/core/staging/txn/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtG,OAAO,EAAoB,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAgB,MAAM,cAAc,CAAC;AAkB5E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAa,EAAE,MAAqB,EAAE,IAAY;IACnF,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,SAAS,GAAmC,EAAE,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YACpC,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YACjC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mEAAmE;QACnE,wEAAwE;QACxE,uEAAuE;QACvE,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,OAAO,EAAE,CAAC;gBACjB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACjD,6EAA6E;QAC7E,0EAA0E;QAC1E,yEAAyE;QACzE,uEAAuE;QACvE,2EAA2E;QAC3E,4DAA4D;QAC5D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,GAAG,YAAY,gBAAgB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,CAAC;QAClG,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,wEAAwE;YACxE,kEAAkE;YAClE,mEAAmE;YACnE,mEAAmE;YACnE,iEAAiE;YACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACjH,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,qCAAqC,EAAE,KAAK,EAAE,CAAC;IACnH,CAAC;IACD,MAAM,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC","sourcesContent":["/**\n * The journaled commit itself: journal (fsynced) → swap → renames → clear,\n * with archive's ordering on the failure path — the rollback decides the\n * outcome, and only then does the journal have nothing left to describe. A\n * crash anywhere inside leaves either the journal plus a recoverable tree\n * (roll forward finishes it) or a fully rolled-back tree whose stale journal\n * the next recovery reads as the consistent pre-state.\n *\n * Callers stage for themselves before committing, on purpose: vouch's\n * byte-level raced check and gherkin's planned-vs-read compare both have to\n * run BETWEEN staging and the swap, against the pre-images staging read.\n *\n * The DIRECTORY RENAMES (`spec.moves`, `subsystem move`'s half) come after\n * every file swap, deliberately: the generated views file must land in the\n * same commit as the renames or the tree is left failing between two states,\n * and a failure mid-renames still has the swapped files' pre-images in hand\n * to roll everything back together — renames undone newest-first, then the\n * files, one failure list, one verdict.\n */\nimport { rename } from \"node:fs/promises\";\nimport { message, rollbackMessage, rollbackStaged, StagingRaceError, swapStaged } from \"../commit.js\";\nimport { type StagedWrite } from \"../writes.js\";\nimport { clearTxnIntent, writeTxnIntent, type TxnSpec } from \"./journal.js\";\n\nexport type StagedCommit =\n  | { ok: true }\n  | {\n      ok: false;\n      code: \"merge-failed\" | \"rollback-incomplete\";\n      message: string;\n      /**\n       * The failure was another writer winning a race (an exclusive create\n       * losing to a concurrent one, or the pre-image compare firing), so the\n       * caller may map it to its own stable race code — `new` answers\n       * `already-exists`, vouch answers `vouch-raced` — instead of the\n       * generic merge failure.\n       */\n      raced: boolean;\n    };\n\n/**\n * `what` is the verb the rollback sentence uses for the half-state (\"merged\",\n * \"stamped\", \"written\") — each caller keeps the word its operators already\n * grep their logs for.\n */\nexport async function commitStaged(spec: TxnSpec, staged: StagedWrite[], what: string): Promise<StagedCommit> {\n  await writeTxnIntent(spec, staged);\n  const performed: { from: string; to: string }[] = [];\n  try {\n    await swapStaged(staged);\n    for (const move of spec.moves ?? []) {\n      await rename(move.from, move.to);\n      performed.push(move);\n    }\n  } catch (err) {\n    // Renames back first, newest-first: each is its own inverse, and a\n    // directory that cannot go back is exactly as reportable as a file that\n    // cannot — it joins the same failure list and forces the same verdict.\n    const failures: string[] = [];\n    for (const move of [...performed].reverse()) {\n      try {\n        await rename(move.to, move.from);\n      } catch (undoErr) {\n        failures.push(`${move.to} (${message(undoErr)})`);\n      }\n    }\n    failures.push(...(await rollbackStaged(staged)));\n    // The journal is cleared only when the rollback HELD. On rollback-incomplete\n    // the tree is genuinely half-written and the temps are gone — the journal\n    // is the one durable record of which files, so doctor keeps naming them,\n    // validate keeps refusing to grade the tree green, and the next writer\n    // refuses commit-interrupted instead of writing over the wreckage. Archive\n    // pays the same way by retaining its snapshot on this path.\n    if (failures.length === 0) await clearTxnIntent(spec.root);\n    const raced = err instanceof StagingRaceError || (err as NodeJS.ErrnoException).code === \"EEXIST\";\n    if (failures.length > 0) {\n      // NEVER raced, whatever threw: callers remap a raced failure onto their\n      // own softer code (vouch-raced, already-exists) with \"nothing was\n      // written\" prose — and here something WAS written and could not be\n      // taken back. rollback-incomplete is the one answer that demands a\n      // human, and no remap may swallow the file list that says where.\n      return { ok: false, code: \"rollback-incomplete\", message: rollbackMessage(err, failures, what), raced: false };\n    }\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — rolled back, nothing was written`, raced };\n  }\n  await clearTxnIntent(spec.root);\n  return { ok: true };\n}\n"]}

package/dist/core/staging/writes.js

@@ -0,0 +1,113 @@
+/**
+ * What a write IS before anything touches disk: the planned record, the staged
+ * record, and the bytes both are made of.
+ *
+ * This is the package's floor. Everything else here — the lock, the swap, the
+ * snapshot, the recovery journal — is a rule about WHEN bytes may land; only
+ * this module decides what they are. Decoding lives here for the same reason:
+ * text is produced only where a parser needs it and `readUtf8` is the one door,
+ * so no later addition can reach a docs file through `readFile(…, "utf8")` and
+ * silently substitute U+FFFD for bytes loam did not understand.
+ */
+import { isUtf8 } from "node:buffer";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+/** The one place a planned write becomes bytes. */
+export function toBytes(content) {
+    return typeof content === "string" ? Buffer.from(content, "utf8") : content;
+}
+/**
+ * The one place that decides whether a planned write is a CREATE *from the
+ * filesystem*. (`core/verify/store/commit.ts` is the deliberate second rule:
+ * it decides from the caller's held pre-image instead, because a CAS must
+ * follow the read it promised, not what `existsSync` says now.)
+ *
+ * `exclusive` is a no-clobber create (link(2)), so it can only be asked of a
+ * path that does not exist yet: asking it of an overwrite would fail EEXIST on
+ * every single run. Deciding here — rather than at each of the dozen
+ * `writes.push` sites in archive and unarchive — is what keeps the two commands
+ * from disagreeing about which of their writes may safely lose a race. An
+ * OVERWRITE is not left unguarded: `swapStaged` compares the target against the
+ * pre-image immediately before the rename, so a file another writer changed
+ * under us stops the commit instead of silently burying their bytes.
+ */
+export function planWrite(path, content) {
+    if (content !== null && !existsSync(path))
+        return { path, content, exclusive: true };
+    return { path, content };
+}
+/**
+ * A file loam must PARSE that does not decode as the UTF-8 text loam owns.
+ *
+ * Commands map this to `merge-failed`: nothing was written, the file is named,
+ * and re-saving it as UTF-8 makes the command work. The read-only migration
+ * ingest already refuses non-UTF-8 input outright (core/openspec/) —
+ * the destructive path has strictly more to lose, so it refuses the same way
+ * rather than substituting U+FFFD and rewriting the file over the author.
+ *
+ * `reason` says what the bytes actually ARE, because the two ways a document
+ * fails this test destroy different things: one substitutes bytes, the other
+ * erases the whole document's meaning. A reader told the wrong one goes looking
+ * in the wrong place. The advice that follows is the same either way, so it is
+ * spelled once, here.
+ */
+export class NotUtf8Error extends Error {
+    path;
+    name = "NotUtf8Error";
+    constructor(path, reason) {
+        super(`${path} ${reason} Nothing was written. Re-save it as UTF-8, then re-run.`);
+        this.path = path;
+    }
+}
+/**
+ * Decode bytes a parser is about to be handed, or refuse naming the file.
+ *
+ * Two tests, the same two the read path makes (document-bytes.ts's
+ * `decodeDocument`), because this side has strictly more to lose by missing
+ * either. `isUtf8` catches the byte sequences that cannot be UTF-8 at all —
+ * which is what a byte-order mark makes UTF-16 into. Without a BOM, UTF-16LE of
+ * ASCII is a sequence of perfectly VALID UTF-8 bytes: every other byte is NUL,
+ * so `isUtf8` says yes, the file decodes with a U+0000 between every character,
+ * and every parser loam owns reads its requirements, frontmatter and headings
+ * as absent rather than as unreadable. On the read path that is a document
+ * graded green while nothing in it was checked; here it is worse, because
+ * `archive` merges against that empty baseline and writes the result back — the
+ * author's requirements are not mis-read, they are gone, and the undo snapshot
+ * records the same emptiness as the pre-image.
+ */
+function decodeUtf8(bytes, path) {
+    if (!isUtf8(bytes)) {
+        throw new NotUtf8Error(path, `is not valid UTF-8 — loam parses this file as text and writes it back, which would replace every ` +
+            `undecodable byte with U+FFFD, in the living document AND in the undo snapshot.`);
+    }
+    const text = bytes.toString("utf8");
+    if (text.includes("\u0000")) {
+        throw new NotUtf8Error(path, `holds NUL characters, which no document loam owns does — almost always UTF-16 saved without a byte-order ` +
+            `mark. Its bytes are valid UTF-8, so it decodes without complaint into text whose requirements, ` +
+            `frontmatter and headings all parse as ABSENT: the merge would compute over an empty baseline and write ` +
+            `that back, taking every requirement in the file with it.`);
+    }
+    return text;
+}
+/** Read a file loam is going to parse. The only supported way to turn a docs file into a string. */
+export async function readUtf8(path) {
+    return decodeUtf8(await readFile(path), path);
+}
+/** Same bytes? Absence is its own value: a file that is gone is not a file that is empty. */
+export function sameBytes(a, b) {
+    return a === null || b === null ? a === b : a.equals(b);
+}
+/* ------------------------------------------------------------------ */
+/* Reading loam's own records back off the disk                        */
+/* ------------------------------------------------------------------ */
+/** The one spelling of a sha256 loam wrote, for reading one back out of a record. */
+export function isDigest(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+export function sha256(content) {
+    return typeof content === "string"
+        ? createHash("sha256").update(content, "utf8").digest("hex")
+        : createHash("sha256").update(content).digest("hex");
+}
+//# sourceMappingURL=writes.js.map

package/dist/core/staging/writes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writes.js","sourceRoot":"","sources":["../../../src/core/staging/writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA+B5C,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,OAA+B;IACrD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAA+B;IACrE,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAuBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAI1B,IAAI;IAHG,IAAI,GAAG,cAAc,CAAC;IAExC,YACW,IAAY,EACrB,MAAc;QAEd,KAAK,CAAC,GAAG,IAAI,IAAI,MAAM,yDAAyD,CAAC,CAAC;oBAHzE,IAAI;IAIf,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,UAAU,CAAC,KAAa,EAAE,IAAY;IAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,mGAAmG;YACjG,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,2GAA2G;YACzG,iGAAiG;YACjG,yGAAyG;YACzG,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,SAAS,CAAC,CAAgB,EAAE,CAAgB;IAC1D,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,OAAO,OAAO,KAAK,QAAQ;QAChC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC5D,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC","sourcesContent":["/**\n * What a write IS before anything touches disk: the planned record, the staged\n * record, and the bytes both are made of.\n *\n * This is the package's floor. Everything else here — the lock, the swap, the\n * snapshot, the recovery journal — is a rule about WHEN bytes may land; only\n * this module decides what they are. Decoding lives here for the same reason:\n * text is produced only where a parser needs it and `readUtf8` is the one door,\n * so no later addition can reach a docs file through `readFile(…, \"utf8\")` and\n * silently substitute U+FFFD for bytes loam did not understand.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\n\n/**\n * A planned file write — the merge is computed fully before anything touches\n * disk. `content: null` means \"delete this file\": `unarchive` takes back a file the\n * archive created, and `subsystem sync` removes the generated views file and a\n * stray per-service project file beside an extending model.\n *\n * BYTES, not text. The whole write path — pre-image, staged content, snapshot,\n * the compare-and-set before each swap — moves Buffers, because a docs repo is\n * not guaranteed to hold text loam can decode: `Buffer.toString(\"utf8\")` never\n * fails, it substitutes U+FFFD, so reading a file as a string and writing the\n * string back is a silent, permanent rewrite of every byte loam did not\n * understand. It reached the snapshot too, so `unarchive` restored the damage\n * and reported success. Text is now produced only where a PARSER needs it, by\n * `decodeUtf8`, which refuses instead of substituting.\n */\nexport interface PlannedWrite {\n  path: string;\n  /**\n   * A `string` is accepted for the callers whose new version IS text they\n   * composed from nothing (a re-pinned delta, a restamped spec) and is encoded\n   * as UTF-8 once, at staging. A caller holding BYTES — anything derived from a\n   * file loam read — must hand over the Buffer: the round trip through a string\n   * is the corruption above.\n   */\n  content: string | Buffer | null;\n  /** Create the target atomically without replacing a concurrently created file. */\n  exclusive?: boolean;\n}\n\n/** The one place a planned write becomes bytes. */\nexport function toBytes(content: string | Buffer | null): Buffer | null {\n  return typeof content === \"string\" ? Buffer.from(content, \"utf8\") : content;\n}\n\n/**\n * The one place that decides whether a planned write is a CREATE *from the\n * filesystem*. (`core/verify/store/commit.ts` is the deliberate second rule:\n * it decides from the caller's held pre-image instead, because a CAS must\n * follow the read it promised, not what `existsSync` says now.)\n *\n * `exclusive` is a no-clobber create (link(2)), so it can only be asked of a\n * path that does not exist yet: asking it of an overwrite would fail EEXIST on\n * every single run. Deciding here — rather than at each of the dozen\n * `writes.push` sites in archive and unarchive — is what keeps the two commands\n * from disagreeing about which of their writes may safely lose a race. An\n * OVERWRITE is not left unguarded: `swapStaged` compares the target against the\n * pre-image immediately before the rename, so a file another writer changed\n * under us stops the commit instead of silently burying their bytes.\n */\nexport function planWrite(path: string, content: string | Buffer | null): PlannedWrite {\n  if (content !== null && !existsSync(path)) return { path, content, exclusive: true };\n  return { path, content };\n}\n\n/** A planned write with its new bytes parked next to the target, ready to swap in. */\nexport interface StagedWrite {\n  write: PlannedWrite;\n  /** What this write puts on disk — `write.content` encoded once. Null for a delete. */\n  content: Buffer | null;\n  /** Temp file holding the new bytes, in the target's OWN directory. Null for a delete. */\n  tmp: string | null;\n  /** The target's bytes before the swap; null when it did not exist. */\n  before: Buffer | null;\n  /**\n   * Topmost directory this write had to create, if any — a rollback owes the repo\n   * its directories back too. An empty `services/<svc>/` left standing is the\n   * fleet claiming a service that was never merged. Spelled as\n   * `mkdirReportingCreated` returns it, never as Node's raw `mkdir` report.\n   */\n  createdDir: string | null;\n  swapped: boolean;\n}\n\n\n\n/**\n * A file loam must PARSE that does not decode as the UTF-8 text loam owns.\n *\n * Commands map this to `merge-failed`: nothing was written, the file is named,\n * and re-saving it as UTF-8 makes the command work. The read-only migration\n * ingest already refuses non-UTF-8 input outright (core/openspec/) —\n * the destructive path has strictly more to lose, so it refuses the same way\n * rather than substituting U+FFFD and rewriting the file over the author.\n *\n * `reason` says what the bytes actually ARE, because the two ways a document\n * fails this test destroy different things: one substitutes bytes, the other\n * erases the whole document's meaning. A reader told the wrong one goes looking\n * in the wrong place. The advice that follows is the same either way, so it is\n * spelled once, here.\n */\nexport class NotUtf8Error extends Error {\n  override readonly name = \"NotUtf8Error\";\n\n  constructor(\n    readonly path: string,\n    reason: string,\n  ) {\n    super(`${path} ${reason} Nothing was written. Re-save it as UTF-8, then re-run.`);\n  }\n}\n\n/**\n * Decode bytes a parser is about to be handed, or refuse naming the file.\n *\n * Two tests, the same two the read path makes (document-bytes.ts's\n * `decodeDocument`), because this side has strictly more to lose by missing\n * either. `isUtf8` catches the byte sequences that cannot be UTF-8 at all —\n * which is what a byte-order mark makes UTF-16 into. Without a BOM, UTF-16LE of\n * ASCII is a sequence of perfectly VALID UTF-8 bytes: every other byte is NUL,\n * so `isUtf8` says yes, the file decodes with a U+0000 between every character,\n * and every parser loam owns reads its requirements, frontmatter and headings\n * as absent rather than as unreadable. On the read path that is a document\n * graded green while nothing in it was checked; here it is worse, because\n * `archive` merges against that empty baseline and writes the result back — the\n * author's requirements are not mis-read, they are gone, and the undo snapshot\n * records the same emptiness as the pre-image.\n */\nfunction decodeUtf8(bytes: Buffer, path: string): string {\n  if (!isUtf8(bytes)) {\n    throw new NotUtf8Error(\n      path,\n      `is not valid UTF-8 — loam parses this file as text and writes it back, which would replace every ` +\n        `undecodable byte with U+FFFD, in the living document AND in the undo snapshot.`,\n    );\n  }\n  const text = bytes.toString(\"utf8\");\n  if (text.includes(\"\\u0000\")) {\n    throw new NotUtf8Error(\n      path,\n      `holds NUL characters, which no document loam owns does — almost always UTF-16 saved without a byte-order ` +\n        `mark. Its bytes are valid UTF-8, so it decodes without complaint into text whose requirements, ` +\n        `frontmatter and headings all parse as ABSENT: the merge would compute over an empty baseline and write ` +\n        `that back, taking every requirement in the file with it.`,\n    );\n  }\n  return text;\n}\n\n/** Read a file loam is going to parse. The only supported way to turn a docs file into a string. */\nexport async function readUtf8(path: string): Promise<string> {\n  return decodeUtf8(await readFile(path), path);\n}\n\n/** Same bytes? Absence is its own value: a file that is gone is not a file that is empty. */\nexport function sameBytes(a: Buffer | null, b: Buffer | null): boolean {\n  return a === null || b === null ? a === b : a.equals(b);\n}\n\n/* ------------------------------------------------------------------ */\n/* Reading loam's own records back off the disk                        */\n/* ------------------------------------------------------------------ */\n\n/** The one spelling of a sha256 loam wrote, for reading one back out of a record. */\nexport function isDigest(value: unknown): value is string {\n  return typeof value === \"string\" && /^[0-9a-f]{64}$/.test(value);\n}\n\nexport function sha256(content: Buffer | string): string {\n  return typeof content === \"string\"\n    ? createHash(\"sha256\").update(content, \"utf8\").digest(\"hex\")\n    : createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\n"]}

package/dist/core/status/actions/execution.js

@@ -0,0 +1,60 @@
+const EDIT_STEPS = new Set([
+    "next.author-intent",
+    "next.touch-service",
+    "next.author-spec",
+    "next.author-openapi",
+    "next.author-scenarios",
+]);
+const SERVICE_REPO_STEPS = new Set([
+    "next.bind-service",
+    "next.adopt-first",
+    "next.generate-tests",
+    "next.verify-unconfirmed",
+    "next.attest-service",
+    "next.verify-attested",
+]);
+function placeholders(command) {
+    return [...command.matchAll(/<([^>]+)>/g)].map((match) => match[1]);
+}
+function execution(step) {
+    if (EDIT_STEPS.has(step.code)) {
+        return {
+            kind: "edit",
+            runnable: false,
+            cwd: "docs-repo",
+            after: step.command,
+            needs: [step.path ?? "the artifact named in statement"],
+        };
+    }
+    if (step.code === "next.recover-commit" && step.command === "loam doctor --json") {
+        return {
+            kind: "human-review",
+            runnable: false,
+            cwd: "docs-repo",
+            needs: ["compare the living docs with version control"],
+        };
+    }
+    // A vouch is a person's act, never an agent's (`loam vouch` refuses without a
+    // terminal or `--yes`), so the step is NOT runnable: an agent prepares the
+    // reading list with `loam vouch --pack` and hands the stamp to a person.
+    if (step.code === "next.revouch") {
+        return {
+            kind: "human-review",
+            runnable: false,
+            cwd: "service-repo",
+            needs: ["a person who re-reads the moved document and vouches for it from the service's own repository"],
+        };
+    }
+    const needs = placeholders(step.command);
+    const serviceRepo = SERVICE_REPO_STEPS.has(step.code);
+    return {
+        kind: serviceRepo ? "external-repo" : "command",
+        runnable: needs.length === 0,
+        cwd: serviceRepo ? "service-repo" : "configured-repo",
+        ...(needs.length === 0 ? { command: step.command } : { needs }),
+    };
+}
+export function executableNext(step) {
+    return { ...step, execution: execution(step) };
+}
+//# sourceMappingURL=execution.js.map

package/dist/core/status/actions/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../../../src/core/status/actions/execution.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,oBAAoB;IACpB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,uBAAuB;CACxB,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,mBAAmB;IACnB,kBAAkB;IAClB,qBAAqB;IACrB,yBAAyB;IACzB,qBAAqB;IACrB,sBAAsB;CACvB,CAAC,CAAC;AAEH,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,SAAS,CAAC,IAAc;IAC/B,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,KAAK;YACf,GAAG,EAAE,WAAW;YAChB,KAAK,EAAE,IAAI,CAAC,OAAO;YACnB,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,iCAAiC,CAAC;SACxD,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,qBAAqB,IAAI,IAAI,CAAC,OAAO,KAAK,oBAAoB,EAAE,CAAC;QACjF,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,QAAQ,EAAE,KAAK;YACf,GAAG,EAAE,WAAW;YAChB,KAAK,EAAE,CAAC,8CAA8C,CAAC;SACxD,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACjC,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,QAAQ,EAAE,KAAK;YACf,GAAG,EAAE,cAAc;YACnB,KAAK,EAAE,CAAC,+FAA+F,CAAC;SACzG,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;QAC/C,QAAQ,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC;QAC5B,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,iBAAiB;QACrD,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;KAChE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,OAAO,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;AACjD,CAAC","sourcesContent":["/** The executable machine contract layered over status's legacy command hint. */\nimport type {\n  ExecutableNextStep,\n  NextExecution,\n  NextStep,\n} from \"../report.js\";\n\nconst EDIT_STEPS = new Set([\n  \"next.author-intent\",\n  \"next.touch-service\",\n  \"next.author-spec\",\n  \"next.author-openapi\",\n  \"next.author-scenarios\",\n]);\n\nconst SERVICE_REPO_STEPS = new Set([\n  \"next.bind-service\",\n  \"next.adopt-first\",\n  \"next.generate-tests\",\n  \"next.verify-unconfirmed\",\n  \"next.attest-service\",\n  \"next.verify-attested\",\n]);\n\nfunction placeholders(command: string): string[] {\n  return [...command.matchAll(/<([^>]+)>/g)].map((match) => match[1]!);\n}\n\nfunction execution(step: NextStep): NextExecution {\n  if (EDIT_STEPS.has(step.code)) {\n    return {\n      kind: \"edit\",\n      runnable: false,\n      cwd: \"docs-repo\",\n      after: step.command,\n      needs: [step.path ?? \"the artifact named in statement\"],\n    };\n  }\n  if (step.code === \"next.recover-commit\" && step.command === \"loam doctor --json\") {\n    return {\n      kind: \"human-review\",\n      runnable: false,\n      cwd: \"docs-repo\",\n      needs: [\"compare the living docs with version control\"],\n    };\n  }\n  // A vouch is a person's act, never an agent's (`loam vouch` refuses without a\n  // terminal or `--yes`), so the step is NOT runnable: an agent prepares the\n  // reading list with `loam vouch --pack` and hands the stamp to a person.\n  if (step.code === \"next.revouch\") {\n    return {\n      kind: \"human-review\",\n      runnable: false,\n      cwd: \"service-repo\",\n      needs: [\"a person who re-reads the moved document and vouches for it from the service's own repository\"],\n    };\n  }\n  const needs = placeholders(step.command);\n  const serviceRepo = SERVICE_REPO_STEPS.has(step.code);\n  return {\n    kind: serviceRepo ? \"external-repo\" : \"command\",\n    runnable: needs.length === 0,\n    cwd: serviceRepo ? \"service-repo\" : \"configured-repo\",\n    ...(needs.length === 0 ? { command: step.command } : { needs }),\n  };\n}\n\nexport function executableNext(step: NextStep): ExecutableNextStep {\n  return { ...step, execution: execution(step) };\n}\n"]}

package/dist/core/status/contracts.js

@@ -0,0 +1,126 @@
+/**
+ * Who owes a service its `openapi.yaml`, and which features in flight already
+ * carry one. Shared between the artifact table and the fleet form, because the
+ * two must never disagree about whether a feature owes a contract.
+ */
+import { existsSync } from "node:fs";
+import { calledServices } from "../coherence/calls/called.js";
+import { featureSpecPaths } from "../repo/paths.js";
+import { listFeatures } from "../repo/repo.js";
+import { governedServices } from "./scan.js";
+/**
+ * Does this feature owe `svc` an openapi.yaml?
+ *
+ * Keyed on the living CONTRACT FILE, never on `services/<svc>/` merely existing
+ * as a directory. A service adopted without a contract is precisely the case
+ * where a feature that governs operations has to write one, and the directory
+ * test answered "none owed" there — printing `(not written — none owed)` beside
+ * the `spec-api.op-undefined` finding, in the same payload, about that very
+ * file, while suppressing the only step that names it.
+ *
+ * Two ways to owe nothing, both about somebody else discharging it: the living
+ * docs already carry the contract, or another feature in flight brings it — the
+ * same softening coherence applies with its `*-pending` codes, where an
+ * operation "defined by another feature still in flight" is an ordering fact
+ * and not a hole.
+ *
+ * Otherwise the contract is owed exactly when something this feature wrote
+ * already joins into it (`evidence`, see {@link contractEvidence}): a
+ * requirement's `Operations:` line, or a tagged delta edge calling an
+ * operation on the service. Those are the two links the gates grade against
+ * the file — `spec-api.op-undefined` and `c4-api.op-undefined` — and the same
+ * two `service.no-openapi` reads once the service is living, where a service
+ * nothing joins into is the documented silence. A UI, a worker, a service whose
+ * only edges go OUT has no API to write down, and that holds for a service the
+ * feature introduces exactly as for an adopted one. Demanding a file from a new
+ * one regardless was loam telling an author to invent a contract — and authors
+ * did, as `paths: {}` stubs the archive then published as living contracts.
+ *
+ * The evidence is THIS feature's own, as every gate it mirrors is. Another
+ * feature in flight drawing an op-linked edge into a service this one
+ * introduces is that feature's `c4-api.op-undefined` (or `-pending`) to raise,
+ * on its own status; this one's gate says nothing about it, so neither does
+ * this projection.
+ *
+ * `evidence` undefined means loam could not look — the delta does not parse —
+ * and then the old reading stands: owed for a service the living docs have
+ * never heard of, not for an adopted one. `delta.invalid` gates either way.
+ */
+export function owesContract(entry, contracted, evidence) {
+    // Both living facts come off the ENUMERATION's entry rather than root
+    // existsSync probes: a service filed into a subsystem lives wherever the
+    // tree walk found it, so the root probe read every filed service as "living
+    // docs have never heard of it" and demanded a contract from all of them.
+    // `undefined` IS that never-heard-of case — nothing enumerated the id
+    // anywhere. `contracted` arrives resolved by the caller, and deliberately
+    // not through the entry: another feature in flight discharges the debt for
+    // a service the living docs have NOT heard of yet — that is the ordinary
+    // introduce-then-build ordering, and it must keep answering "none owed".
+    if (entry?.has.openapi === true)
+        return false;
+    if (contracted)
+        return false;
+    return evidence ?? entry === undefined;
+}
+/**
+ * Per service, whether this feature wrote anything that joins into its
+ * contract — `true`/`false`, or `undefined` when the delta could not be read.
+ * One function for both status forms, so they cannot disagree about whether a
+ * feature owes a contract: the `Operations:` lines come off the scan they have
+ * already made, and the op-linked edges off the delta parse they have already
+ * paid for (the coherence pass in one, the dependency graph in the other).
+ */
+export async function contractEvidence(docsDir, feature, scans, context) {
+    const governs = governedServices(scans);
+    const called = await calledServices({ docsDir, featureDir: feature.dir, featureId: feature.id }, context);
+    return (service) => (governs.has(service) ? true : called === "unreadable" ? undefined : called.has(service));
+}
+/**
+ * Which features in flight carry an `openapi.yaml` for which service — one
+ * enumeration of the whole index, service by service.
+ *
+ * The owners are recorded as feature IDS rather than directories because that
+ * is the comparison {@link contractsHeldElsewhere} makes: two directories that
+ * spell the same id are one feature as far as this question goes, and an index
+ * keyed by directory would let a duplicated id answer "somebody else has it"
+ * about its own twin.
+ *
+ * Enumeration only — the feature list and its `specs/` subdirectories are
+ * already in the request-scoped index by the time anything asks.
+ */
+export async function contractOwners(docsDir, context) {
+    const out = new Map();
+    for (const f of await listFeatures(docsDir, {}, context)) {
+        for (const svc of f.services) {
+            if (!existsSync(featureSpecPaths(f.dir, svc).openapi))
+                continue;
+            const owners = out.get(svc);
+            if (owners === undefined)
+                out.set(svc, new Set([f.id]));
+            else
+                owners.add(f.id);
+        }
+    }
+    return out;
+}
+/**
+ * Services some OTHER active feature already carries an `openapi.yaml` for.
+ *
+ * Derived from the shared index rather than re-walked, because the answer for
+ * feature A and the answer for feature B are two readings of one enumeration:
+ * asking it once per feature made the fleet form pay F²·S `existsSync` calls
+ * over the two quantities that actually grow.
+ */
+export function contractsHeldElsewhere(owners, self) {
+    const out = new Set();
+    for (const [svc, ids] of owners) {
+        for (const id of ids) {
+            if (id !== self) {
+                out.add(svc);
+                break;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=contracts.js.map

package/dist/core/status/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/core/status/contracts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Who owes a service its `openapi.yaml`, and which features in flight already\n * carry one. Shared between the artifact table and the fleet form, because the\n * two must never disagree about whether a feature owes a contract.\n */\nimport { existsSync } from \"node:fs\";\nimport { calledServices } from \"../coherence/calls/called.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport type { FeatureEntry, ServiceEntry } from \"../repo/entries.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { governedServices, type DeltaScan } from \"./scan.js\";\n\n/**\n * Does this feature owe `svc` an openapi.yaml?\n *\n * Keyed on the living CONTRACT FILE, never on `services/<svc>/` merely existing\n * as a directory. A service adopted without a contract is precisely the case\n * where a feature that governs operations has to write one, and the directory\n * test answered \"none owed\" there — printing `(not written — none owed)` beside\n * the `spec-api.op-undefined` finding, in the same payload, about that very\n * file, while suppressing the only step that names it.\n *\n * Two ways to owe nothing, both about somebody else discharging it: the living\n * docs already carry the contract, or another feature in flight brings it — the\n * same softening coherence applies with its `*-pending` codes, where an\n * operation \"defined by another feature still in flight\" is an ordering fact\n * and not a hole.\n *\n * Otherwise the contract is owed exactly when something this feature wrote\n * already joins into it (`evidence`, see {@link contractEvidence}): a\n * requirement's `Operations:` line, or a tagged delta edge calling an\n * operation on the service. Those are the two links the gates grade against\n * the file — `spec-api.op-undefined` and `c4-api.op-undefined` — and the same\n * two `service.no-openapi` reads once the service is living, where a service\n * nothing joins into is the documented silence. A UI, a worker, a service whose\n * only edges go OUT has no API to write down, and that holds for a service the\n * feature introduces exactly as for an adopted one. Demanding a file from a new\n * one regardless was loam telling an author to invent a contract — and authors\n * did, as `paths: {}` stubs the archive then published as living contracts.\n *\n * The evidence is THIS feature's own, as every gate it mirrors is. Another\n * feature in flight drawing an op-linked edge into a service this one\n * introduces is that feature's `c4-api.op-undefined` (or `-pending`) to raise,\n * on its own status; this one's gate says nothing about it, so neither does\n * this projection.\n *\n * `evidence` undefined means loam could not look — the delta does not parse —\n * and then the old reading stands: owed for a service the living docs have\n * never heard of, not for an adopted one. `delta.invalid` gates either way.\n */\nexport function owesContract(\n  entry: ServiceEntry | undefined,\n  contracted: boolean,\n  evidence: boolean | undefined,\n): boolean {\n  // Both living facts come off the ENUMERATION's entry rather than root\n  // existsSync probes: a service filed into a subsystem lives wherever the\n  // tree walk found it, so the root probe read every filed service as \"living\n  // docs have never heard of it\" and demanded a contract from all of them.\n  // `undefined` IS that never-heard-of case — nothing enumerated the id\n  // anywhere. `contracted` arrives resolved by the caller, and deliberately\n  // not through the entry: another feature in flight discharges the debt for\n  // a service the living docs have NOT heard of yet — that is the ordinary\n  // introduce-then-build ordering, and it must keep answering \"none owed\".\n  if (entry?.has.openapi === true) return false;\n  if (contracted) return false;\n  return evidence ?? entry === undefined;\n}\n\n/**\n * Per service, whether this feature wrote anything that joins into its\n * contract — `true`/`false`, or `undefined` when the delta could not be read.\n * One function for both status forms, so they cannot disagree about whether a\n * feature owes a contract: the `Operations:` lines come off the scan they have\n * already made, and the op-linked edges off the delta parse they have already\n * paid for (the coherence pass in one, the dependency graph in the other).\n */\nexport async function contractEvidence(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  scans: readonly DeltaScan[],\n  context: FleetContext,\n): Promise<(service: string) => boolean | undefined> {\n  const governs = governedServices(scans);\n  const called = await calledServices({ docsDir, featureDir: feature.dir, featureId: feature.id }, context);\n  return (service) => (governs.has(service) ? true : called === \"unreadable\" ? undefined : called.has(service));\n}\n\n/**\n * Which features in flight carry an `openapi.yaml` for which service — one\n * enumeration of the whole index, service by service.\n *\n * The owners are recorded as feature IDS rather than directories because that\n * is the comparison {@link contractsHeldElsewhere} makes: two directories that\n * spell the same id are one feature as far as this question goes, and an index\n * keyed by directory would let a duplicated id answer \"somebody else has it\"\n * about its own twin.\n *\n * Enumeration only — the feature list and its `specs/` subdirectories are\n * already in the request-scoped index by the time anything asks.\n */\nexport async function contractOwners(docsDir: DocsDir, context: FleetContext): Promise<Map<string, Set<string>>> {\n  const out = new Map<string, Set<string>>();\n  for (const f of await listFeatures(docsDir, {}, context)) {\n    for (const svc of f.services) {\n      if (!existsSync(featureSpecPaths(f.dir, svc).openapi)) continue;\n      const owners = out.get(svc);\n      if (owners === undefined) out.set(svc, new Set([f.id]));\n      else owners.add(f.id);\n    }\n  }\n  return out;\n}\n\n/**\n * Services some OTHER active feature already carries an `openapi.yaml` for.\n *\n * Derived from the shared index rather than re-walked, because the answer for\n * feature A and the answer for feature B are two readings of one enumeration:\n * asking it once per feature made the fleet form pay F²·S `existsSync` calls\n * over the two quantities that actually grow.\n */\nexport function contractsHeldElsewhere(owners: ReadonlyMap<string, ReadonlySet<string>>, self: string): Set<string> {\n  const out = new Set<string>();\n  for (const [svc, ids] of owners) {\n    for (const id of ids) {\n      if (id !== self) {\n        out.add(svc);\n        break;\n      }\n    }\n  }\n  return out;\n}\n"]}