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

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;AA8B5C,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;AAsBD;;;;;;;;;;;;;;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\"; only `unarchive` plans those,\n * to take back a file the archive created.\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.\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,49 @@
+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"],
+        };
+    }
+    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,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  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,102 @@
+/**
+ * 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 { featureSpecPaths } from "../repo/paths.js";
+import { listFeatures } from "../repo/repo.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. And one way to owe nothing at all: a service that ALREADY
+ * EXISTS under `services/`, has no living contract, and that this feature sends
+ * no operation to. A UI or a worker nobody calls has no API to write down,
+ * which is the reading `validate` and `list` already take — demanding one from
+ * an adopted service of that shape would be loam telling an author to invent a
+ * contract.
+ *
+ * That last exemption is deliberately withheld from a service the living docs
+ * have never heard of. A feature that introduces a service and sends it no
+ * operation still owes the file, because nothing else in the repository will
+ * ever describe its surface, and `c4-api.op-undefined` fires on an op-tagged
+ * delta edge whether or not any `Operations:` line was written — so answering
+ * "none owed" there printed `(not written — none owed)` in the same payload as
+ * an error about that very file.
+ */
+export function owesContract(entry, contracted, governsOperations) {
+    // 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 entry === undefined || governsOperations;
+}
+/**
+ * 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":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,YAAY,CAC1B,KAA+B,EAC/B,UAAmB,EACnB,iBAA0B;IAE1B,sEAAsE;IACtE,yEAAyE;IACzE,4EAA4E;IAC5E,yEAAyE;IACzE,sEAAsE;IACtE,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,IAAI,KAAK,EAAE,GAAG,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,UAAU;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,KAAK,KAAK,SAAS,IAAI,iBAAiB,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAqB;IAC1E,MAAM,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC;gBAAE,SAAS;YAChE,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,MAAM,KAAK,SAAS;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;gBACnD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAgD,EAAE,IAAY;IACnG,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;QAChC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACb,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","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 type { FleetContext } from \"../fleet-context.js\";\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport type { ServiceEntry } from \"../repo/entries.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.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. And one way to owe nothing at all: a service that ALREADY\n * EXISTS under `services/`, has no living contract, and that this feature sends\n * no operation to. A UI or a worker nobody calls has no API to write down,\n * which is the reading `validate` and `list` already take — demanding one from\n * an adopted service of that shape would be loam telling an author to invent a\n * contract.\n *\n * That last exemption is deliberately withheld from a service the living docs\n * have never heard of. A feature that introduces a service and sends it no\n * operation still owes the file, because nothing else in the repository will\n * ever describe its surface, and `c4-api.op-undefined` fires on an op-tagged\n * delta edge whether or not any `Operations:` line was written — so answering\n * \"none owed\" there printed `(not written — none owed)` in the same payload as\n * an error about that very file.\n */\nexport function owesContract(\n  entry: ServiceEntry | undefined,\n  contracted: boolean,\n  governsOperations: boolean,\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 entry === undefined || governsOperations;\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"]}

package/dist/core/status/feature/artifacts.js

@@ -0,0 +1,196 @@
+/**
+ * The artifact table: which files a feature owes, whether each is on disk, and
+ * which finding turns a row `draft`. Nothing is graded here — the shared
+ * checks already ran, and this module only attributes what they reported to
+ * the file a reader should edit.
+ */
+import { existsSync } from "node:fs";
+import { repoPath } from "../../envelope/json.js";
+import { featurePaths, featureSpecPaths } from "../../repo/paths.js";
+import { verificationPath } from "../../verify/record.js";
+import { owesContract } from "../contracts.js";
+import { verificationStatus } from "../verification.js";
+/**
+ * The `capability.*` codes filed against a capability DOCUMENT rather than
+ * against a service requirement's join line. Spelled out rather than matched by
+ * prefix because the family straddles both corpora, and the whole point of this
+ * table is to name one file.
+ */
+const CAPABILITY_DOCUMENT_CODES = new Set([
+    "capability.requirement-unidentified",
+    "capability.requirement-service-scoped",
+    "capability.requirement-inert-join",
+    "capability.uncovered",
+    "capability.remove-requirement-realized",
+]);
+/**
+ * Which artifact an error names.
+ *
+ * Attribution is by code family, because that is the only machine-readable
+ * pointer an `Issue` carries: `subject` narrows to a NAME, never to a file.
+ * The families are unambiguous — `c4-api.*`/`c4-event.*`/`c4.*` and the two
+ * `delta.*` codes about the LikeC4 document itself grade the architecture
+ * axis, `openapi.*` grades the API contract, `asyncapi.*` the event contract,
+ * and the remaining `delta.*` codes plus `spec-api.*`/`spec-event.*` are the
+ * delta-shape checks, every one of which is about a requirement in a spec
+ * delta.
+ *
+ * An error that maps to nothing (or whose subject is unknown) still lands in
+ * `checks.issues` and still drives `next.fix-coherence` — it just does not turn
+ * any single artifact `draft`, because guessing which file to blame is how a
+ * reader gets sent to edit the wrong one.
+ *
+ * THE BUSINESS CORPUS IS THE ONE PLACE THE CODE FAMILY IS NOT ENOUGH. A
+ * `delta.*` issue's `subject` is a service id OR a capability id
+ * (`core/delta/scope.ts`), and so is a `scaffold.placeholder`'s
+ * (`core/coherence/authoring/scaffold.ts` files one per unedited capability
+ * delta), and nothing in either code says which — so this
+ * function answers `spec` for both and `featureArtifacts` below resolves it by
+ * MEMBERSHIP, against the two lists it already holds. Where a name is only a
+ * capability the capability row is turned `draft` and no service row is; where
+ * a fleet holds a service AND a capability of the same name, BOTH are, which is
+ * the pessimistic answer this module is required to give and strictly better
+ * than the old one (it named the service's spec delta and was silently wrong).
+ * The capability-document codes below need no such resolution: they are only
+ * ever filed against a capability.
+ */
+function faultedArtifact(code, subject) {
+    if (code === "delta.invalid" || code === "delta.nothing-tagged")
+        return "delta";
+    if (code.startsWith("c4-api.") || code.startsWith("c4-event.") || code.startsWith("c4."))
+        return "delta";
+    if (code.startsWith("openapi."))
+        return "openapi";
+    if (code.startsWith("asyncapi."))
+        return "asyncapi";
+    // The capability document's own grades, and the two halves of the `Realizes:`
+    // join a feature can break — every one of them names a
+    // `features/<FEAT>/capabilities/<id>/spec.md`, never a service delta. The two
+    // `capability.*` codes deliberately absent are `capability.unknown` and
+    // `capability.realizes-unknown`: those grade a SERVICE requirement's join
+    // lines and carry a service id, so the prefix alone would send their reader
+    // to the wrong file.
+    if (CAPABILITY_DOCUMENT_CODES.has(code))
+        return "capabilities";
+    if (code.startsWith("delta.") || code.startsWith("spec-api.") || code.startsWith("spec-event."))
+        return "spec";
+    // The two families validate contributes: the frontmatter checks read only
+    // intent.md, and a requirement with no scenario is a requirement in a spec
+    // delta. Both name exactly one file, so both may turn a row `draft`.
+    if (code.startsWith("frontmatter."))
+        return "intent";
+    if (code === "requirements.missing-scenarios")
+        return "spec";
+    // The authoring gate names exactly one file per finding too — leaving these
+    // unmapped had the table calling intent.md `done` ("nothing is owed here")
+    // while the archive exited 1 because it says nothing. A placeholder finding
+    // carries no subject when it is the C4 delta's scaffolded description; with a
+    // subject it is a SPEC DELTA IN EITHER CORPUS — a service id when the text
+    // sits in `specs/<svc>/`, a capability id when it sits in
+    // `capabilities/<id>/` — which is why `spec` here is resolved by membership
+    // below and must not be narrowed to the service list.
+    if (code === "intent.empty")
+        return "intent";
+    if (code === "scaffold.placeholder")
+        return subject === undefined ? "delta" : "spec";
+    return null;
+}
+export function featureArtifacts(docsDir, feature, services, grading) {
+    const { blocking, verification, contracted, governs, living, capabilities } = grading;
+    const paths = featurePaths(feature.dir);
+    const rel = (abs) => repoPath(docsDir, abs);
+    const faults = blocking.map((f) => ({ artifact: faultedArtifact(f.code, f.subject), subject: f.subject }));
+    const faulted = (id, service) => faults.some((f) => f.artifact === id && (service === null || f.subject === service));
+    const out = [
+        fileState("intent", { service: null, path: rel(paths.intent), exists: existsSync(paths.intent) }, true, faulted("intent", null)),
+        fileState("delta", { service: null, path: rel(paths.delta), exists: existsSync(paths.delta) }, false, faulted("delta", null)),
+    ];
+    // One row per capability document the feature carries, and none at all when
+    // it carries none: the row is the answer to "which file do I edit", and a
+    // fleet that has not adopted the axis has no such file to name. Never
+    // `required` — no feature owes a business change — so absence never shows up
+    // as work owed, and only a fault turns one `draft`. A `delta.*` fault carries
+    // the capability id in `subject` with nothing saying it is not a service, so
+    // the membership test is the resolution the code family cannot give.
+    for (const doc of capabilities) {
+        out.push({
+            id: "capabilities",
+            service: null,
+            capability: doc.id,
+            path: rel(doc.spec),
+            exists: existsSync(doc.spec),
+            required: false,
+            status: faulted("capabilities", doc.id) || faulted("spec", doc.id) ? "draft" : "done",
+            blockedBy: [],
+        });
+    }
+    for (const svc of services) {
+        const p = featureSpecPaths(feature.dir, svc);
+        const specFault = faulted("spec", svc);
+        // What a service delta owes is a REQUIREMENT DELTA, not specifically the
+        // business one. `arch.spec.md` is the other corpus, with the same grammar
+        // and the same delta algebra, and `featureChecklist` derives claims from
+        // it — so a directory holding only the architectural document is a
+        // complete delta, and every gate already reads it as one: `coherence`'s
+        // `service.no-requirement-delta` counts the DIRECTORY, and
+        // `validate --feature` grades an arch-only delta clean at exit 0.
+        //
+        // Requiring `spec.md` unconditionally made this module the one document
+        // that disagreed. An architecture-only feature — an outbox added, a retry
+        // policy, an alert; the changes `arch.spec.md` exists for because no
+        // business scenario was ever going to carry them — reported `missing` and
+        // emitted `next.author-spec`, sending the author to write business
+        // requirements the change does not have, about a feature the gate accepts.
+        // status may be redder than the gates on a question they also ask; it may
+        // not invent an obligation they do not.
+        const archExists = existsSync(p.archSpec);
+        out.push(fileState("spec", { service: svc, path: rel(p.spec), exists: existsSync(p.spec) }, !archExists, specFault));
+        out.push(fileState("arch-spec", { service: svc, path: rel(p.archSpec), exists: archExists }, false, specFault));
+        out.push(fileState("openapi", { service: svc, path: rel(p.openapi), exists: existsSync(p.openapi) }, owesContract(living.get(svc), contracted.has(svc), governs.has(svc)), faulted("openapi", svc)));
+        // Never required: an event contract is genuinely optional — the axis's own
+        // absence-grading rests on that — so absence is `done`, exactly like
+        // arch.spec.md. Present and faulted still turns the row `draft`.
+        out.push(fileState("asyncapi", { service: svc, path: rel(p.asyncapi), exists: existsSync(p.asyncapi) }, false, faulted("asyncapi", svc)));
+    }
+    // The record is the one artifact with a real prerequisite: its checklist is
+    // derived from the delta and the per-service deltas, so with none of them
+    // written there is nothing to answer — authoring one is impossible rather
+    // than merely premature, which is the whole distinction `blocked` carries.
+    //
+    // `capabilities` is excluded for exactly that reason and not by oversight:
+    // `featureChecklist` derives no claim from a capability document — a business
+    // promise is realized by service requirements, and those are what the record
+    // answers — so counting one as a feeder would report a capability-only
+    // feature as ready to verify against a checklist with nothing in it.
+    //
+    // `arch-spec` used to be excluded beside it, and that failed the same test
+    // the comment above states: `featureChecklist` DOES read `arch.spec.md`
+    // (`core/verify/checklist.ts`), and `loam verify` on an architecture-only
+    // feature returns a real checklist. The row said `blocked … needs delta,
+    // spec, openapi, asyncapi` and `next.verify` said there was nothing to derive
+    // a checklist from, about a command that derives one — which is the failure
+    // `blocked` is supposed to prevent, pointed the wrong way.
+    const feeders = out.filter((a) => a.id !== "intent" && a.id !== "capabilities" && a.exists);
+    out.push({
+        id: "verification",
+        service: null,
+        path: rel(verificationPath(feature.dir)),
+        exists: verification.state !== "absent",
+        required: true,
+        status: feeders.length === 0 ? "blocked" : verificationStatus(verification),
+        blockedBy: feeders.length === 0 ? ["delta", "spec", "arch-spec", "openapi", "asyncapi"] : [],
+    });
+    return out;
+}
+function fileState(id, file, required, faulted) {
+    const { service, path, exists } = file;
+    const status = !exists
+        ? required
+            ? "missing"
+            : "done"
+        : faulted
+            ? "draft"
+            : "done";
+    return { id, service, path, exists, required, status, blockedBy: [] };
+}
+//# sourceMappingURL=artifacts.js.map