@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/commands/diff/diff.js

@@ -1,13 +1,11 @@
-import { loadConfig } from "../../core/envelope/config.js";
-import { emitJson, fail, reportNoConfig } from "../../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail } from "../../core/envelope/json.js";
 import { findingJson } from "../../core/vocabulary/report.js";
-import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
+import { baseOrRefuse, docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
 import { FleetContext } from "../../core/fleet-context.js";
-import { resolveBase } from "../../core/diff/base-git.js";
 import { readBaseFleet } from "../../core/diff/base-state.js";
-import { readCurrentFleet } from "../../core/diff/current-state.js";
-import { victimIndex } from "../../core/diff/victims.js";
+import { livingFleet } from "../../core/consumers/current.js";
+import { consumerIndex } from "../../core/consumers/consumers.js";
 import { computeDiff } from "../../core/diff/semantic.js";
 import { printDiff } from "./print.js";
 export function registerDiff(program) {
@@ -18,43 +16,38 @@ export function registerDiff(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const { docsDir } = loaded.config;
+        const { docsDir } = config;
         // "services" on purpose: both sides of the diff are enumerations of the
         // fleet, and a docsDir with no services/ has no fleet to diff.
         if (!docsRepoReady(json, docsDir, "services"))
             return;
-        const base = await resolveBase(docsDir, opts.base);
         // Unlike provenance's "git will not say", diff REFUSES when git cannot
         // answer: without the base there is no honest diff, and a silently
-        // empty base would report the whole fleet as added.
-        if (base.kind === "no-git") {
-            fail(json, "repository-unavailable", `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +
-                `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +
-                `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`);
-            return;
-        }
-        if (base.kind === "no-ref") {
-            fail(json, "unknown-target", `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +
-                `${base.detail === "" ? "" : ` (${base.detail})`}. ` +
-                `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`);
+        // empty base would report the whole fleet as added. The two refusals
+        // are `loam gate --since`'s too, so they live in commands/policy/gate.ts.
+        const base = await baseOrRefuse(json, docsDir, {
+            flag: "--base",
+            ref: opts.base,
+            reads: "loam diff reads the base state",
+        });
+        if (base === null)
             return;
-        }
         const context = new FleetContext();
         let diff;
         try {
-            const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });
+            const baseFleet = await readBaseFleet(base);
             if (baseFleet.kind === "failed") {
                 fail(json, "repository-unavailable", `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +
                     `without the base tree there is no honest diff. Re-run once git can answer.`);
                 return;
             }
-            const current = await readCurrentFleet(docsDir, context);
-            const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });
+            // The index reads the same memoised fleet (`livingFleet`), so the
+            // working-tree side and the victims are one read of one snapshot.
+            const current = await livingFleet(docsDir, context);
+            const victims = consumerIndex({ docsDir, context });
             diff = await computeDiff({ base: baseFleet.fleet, current, victims });
         }
         catch (err) {

package/dist/commands/diff/diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/commands/diff/diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam diff --base <ref>` — the review lens over a docs-repo branch: what\n * changed in fleet-meaningful terms since a base git ref of the DOCS repo,\n * with the current consumers of every removal named. Read-only by\n * construction: the base state comes out of git's object store\n * (`core/diff/base-git.ts`), the current state off the working tree, and\n * nothing is written anywhere.\n *\n * Exit semantics: 0 when the diff was computed and nothing is breaking AND\n * every artifact on both sides could be read; 1 for a refusal, for any\n * error-severity finding (a removal the fleet still consumes — which is what\n * makes this a free gate on a docs-repo PR), and for a diff with suspended\n * axes — \"nobody could look\" must not exit as \"nothing changed\"\n * (`loam context` set that precedent for silent holes).\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, fail, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { resolveBase } from \"../../core/diff/base-git.js\";\nimport { readBaseFleet } from \"../../core/diff/base-state.js\";\nimport { readCurrentFleet } from \"../../core/diff/current-state.js\";\nimport { victimIndex } from \"../../core/diff/victims.js\";\nimport { computeDiff, type FleetDiff } from \"../../core/diff/semantic.js\";\nimport { printDiff } from \"./print.js\";\n\ninterface DiffOptions {\n  base: string;\n  json?: boolean;\n}\n\nexport function registerDiff(program: Command): void {\n  program\n    .command(\"diff\")\n    .description(\"Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named\")\n    .requiredOption(\"--base <ref>\", \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DiffOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const { docsDir } = loaded.config;\n      // \"services\" on purpose: both sides of the diff are enumerations of the\n      // fleet, and a docsDir with no services/ has no fleet to diff.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      const base = await resolveBase(docsDir, opts.base);\n      // Unlike provenance's \"git will not say\", diff REFUSES when git cannot\n      // answer: without the base there is no honest diff, and a silently\n      // empty base would report the whole fleet as added.\n      if (base.kind === \"no-git\") {\n        fail(\n          json,\n          \"repository-unavailable\",\n          `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n            `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +\n            `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`,\n        );\n        return;\n      }\n      if (base.kind === \"no-ref\") {\n        fail(\n          json,\n          \"unknown-target\",\n          `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +\n            `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n            `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n        );\n        return;\n      }\n\n      const context = new FleetContext();\n      let diff: FleetDiff;\n      try {\n        const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });\n        if (baseFleet.kind === \"failed\") {\n          fail(\n            json,\n            \"repository-unavailable\",\n            `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +\n              `without the base tree there is no honest diff. Re-run once git can answer.`,\n          );\n          return;\n        }\n        const current = await readCurrentFleet(docsDir, context);\n        const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });\n        diff = await computeDiff({ base: baseFleet.fleet, current, victims });\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        reportRepositoryUnavailable(json, err, \"the fleet could not be diffed\", docsDir);\n        return;\n      }\n\n      // Error findings gate (the validate convention); suspended axes gate too,\n      // because an exit 0 over a diff nobody could fully read would be the\n      // \"green over zero services\" failure one step later.\n      if (diff.breaking || diff.summary.unreadable > 0) process.exitCode = 1;\n      if (json) {\n        emitJson({\n          command: \"diff\",\n          docsDir,\n          base: { ref: opts.base, commit: base.commit },\n          services: diff.services.map((s) => ({\n            id: s.id,\n            change: s.change,\n            findings: s.findings.map((finding) =>\n              findingJson(finding, { path: `services/${s.id}`, role: \"scope\" }),\n            ),\n            unreadable: s.unreadable,\n            ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),\n          })),\n          breaking: diff.breaking,\n          summary: diff.summary,\n        });\n        return;\n      }\n      printDiff(diff, { ref: opts.base, commit: base.commit });\n    });\n}\n"]}
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/commands/diff/diff.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAClH,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAE,WAAW,EAAkB,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOvC,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,qJAAqJ,CAAC;SAClK,cAAc,CAAC,cAAc,EAAE,sEAAsE,CAAC;SACtG,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAiB,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,wEAAwE;QACxE,+DAA+D;QAC/D,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC;YAAE,OAAO;QAEtD,uEAAuE;QACvE,mEAAmE;QACnE,qEAAqE;QACrE,0EAA0E;QAC1E,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE;YAC7C,IAAI,EAAE,QAAQ;YACd,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,KAAK,EAAE,gCAAgC;SACxC,CAAC,CAAC;QACH,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAE1B,MAAM,OAAO,GAAG,IAAI,YAAY,EAAE,CAAC;QACnC,IAAI,IAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAChC,IAAI,CACF,IAAI,EACJ,wBAAwB,EACxB,mCAAmC,IAAI,CAAC,IAAI,wBAAwB,OAAO,KAAK,SAAS,CAAC,MAAM,MAAM;oBACpG,4EAA4E,CAC/E,CAAC;gBACF,OAAO;YACT,CAAC;YACD,kEAAkE;YAClE,kEAAkE;YAClE,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpD,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;YACpD,IAAI,GAAG,MAAM,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,wBAAwB,EAAE,CAAC;gBAC5C,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC/B,OAAO;YACT,CAAC;YACD,2BAA2B,CAAC,IAAI,EAAE,GAAG,EAAE,+BAA+B,EAAE,OAAO,CAAC,CAAC;YACjF,OAAO;QACT,CAAC;QAED,0EAA0E;QAC1E,qEAAqE;QACrE,qDAAqD;QACrD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvE,IAAI,IAAI,EAAE,CAAC;YACT,QAAQ,CAAC;gBACP,OAAO,EAAE,MAAM;gBACf,OAAO;gBACP,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;gBAC7C,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAClC,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACnC,WAAW,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAClE;oBACD,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;iBACjE,CAAC,CAAC;gBACH,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,SAAS,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * `loam diff --base <ref>` — the review lens over a docs-repo branch: what\n * changed in fleet-meaningful terms since a base git ref of the DOCS repo,\n * with the authored consumers of every removal, deprecation and contract\n * modification named. Read-only by\n * construction: the base state comes out of git's object store\n * (`core/diff/base-git.ts`), the current state off the working tree, and\n * nothing is written anywhere.\n *\n * Exit semantics: 0 when the diff was computed and nothing is breaking AND\n * every artifact on both sides could be read; 1 for a refusal, for any\n * error-severity finding (a removal the fleet still consumes — which is what\n * makes this a free gate on a docs-repo PR), and for a diff with suspended\n * axes — \"nobody could look\" must not exit as \"nothing changed\"\n * (`loam context` set that precedent for silent holes). A contract that cannot\n * be read but is byte-identical at the base is not a suspended axis: the branch\n * did not touch it, and core/diff/semantic.ts skips it rather than failing every\n * PR over a file nobody changed.\n */\nimport type { Command } from \"commander\";\nimport { configOrRefuse, emitJson, fail } from \"../../core/envelope/json.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport { baseOrRefuse, docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { readBaseFleet } from \"../../core/diff/base-state.js\";\nimport { livingFleet } from \"../../core/consumers/current.js\";\nimport { consumerIndex } from \"../../core/consumers/consumers.js\";\nimport { computeDiff, type FleetDiff } from \"../../core/diff/semantic.js\";\nimport { printDiff } from \"./print.js\";\n\ninterface DiffOptions {\n  base: string;\n  json?: boolean;\n}\n\nexport function registerDiff(program: Command): void {\n  program\n    .command(\"diff\")\n    .description(\"Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named\")\n    .requiredOption(\"--base <ref>\", \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DiffOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // \"services\" on purpose: both sides of the diff are enumerations of the\n      // fleet, and a docsDir with no services/ has no fleet to diff.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      // Unlike provenance's \"git will not say\", diff REFUSES when git cannot\n      // answer: without the base there is no honest diff, and a silently\n      // empty base would report the whole fleet as added. The two refusals\n      // are `loam gate --since`'s too, so they live in commands/policy/gate.ts.\n      const base = await baseOrRefuse(json, docsDir, {\n        flag: \"--base\",\n        ref: opts.base,\n        reads: \"loam diff reads the base state\",\n      });\n      if (base === null) return;\n\n      const context = new FleetContext();\n      let diff: FleetDiff;\n      try {\n        const baseFleet = await readBaseFleet(base);\n        if (baseFleet.kind === \"failed\") {\n          fail(\n            json,\n            \"repository-unavailable\",\n            `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +\n              `without the base tree there is no honest diff. Re-run once git can answer.`,\n          );\n          return;\n        }\n        // The index reads the same memoised fleet (`livingFleet`), so the\n        // working-tree side and the victims are one read of one snapshot.\n        const current = await livingFleet(docsDir, context);\n        const victims = consumerIndex({ docsDir, context });\n        diff = await computeDiff({ base: baseFleet.fleet, current, victims });\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        reportRepositoryUnavailable(json, err, \"the fleet could not be diffed\", docsDir);\n        return;\n      }\n\n      // Error findings gate (the validate convention); suspended axes gate too,\n      // because an exit 0 over a diff nobody could fully read would be the\n      // \"green over zero services\" failure one step later.\n      if (diff.breaking || diff.summary.unreadable > 0) process.exitCode = 1;\n      if (json) {\n        emitJson({\n          command: \"diff\",\n          docsDir,\n          base: { ref: opts.base, commit: base.commit },\n          services: diff.services.map((s) => ({\n            id: s.id,\n            change: s.change,\n            findings: s.findings.map((finding) =>\n              findingJson(finding, { path: `services/${s.id}`, role: \"scope\" }),\n            ),\n            unreadable: s.unreadable,\n            ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),\n          })),\n          breaking: diff.breaking,\n          summary: diff.summary,\n        });\n        return;\n      }\n      printDiff(diff, { ref: opts.base, commit: base.commit });\n    });\n}\n"]}

package/dist/commands/explore.js

@@ -1,7 +1,6 @@
-import { loadConfig } from "../core/envelope/config.js";
 import { explore } from "../core/explore/explore.js";
 import { FleetContext } from "../core/fleet-context.js";
-import { emitJson, fail, reportNoConfig } from "../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail } from "../core/envelope/json.js";
 import { featureIdProblem } from "../core/kernel/ids/feature.js";
 import { parseServiceIds } from "../core/kernel/ids/service.js";
 import { DocsRepoUnavailableError } from "../core/repo/state.js";
@@ -59,7 +58,7 @@ export function registerExplore(program) {
         }
         // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is
         // guarded at the command boundary. Every id here reaches the service path builders.
-        // Before `loadConfig`, exactly as `loam new` guards its `--touches` list:
+        // Before the config is loaded, exactly as `loam new` guards its `--touches` list:
         // the grammar is a fact about the argument, not about the repository, so
         // an unusable id should answer the same whether or not you are standing
         // in a wired repo.
@@ -72,12 +71,9 @@ export function registerExplore(program) {
             fail(json, "invalid-option", seeds.problem);
             return;
         }
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         const { docsDir } = config;
         // `services`, not `docs`: every answer here is a statement about the
         // fleet, and an empty ring read out of a directory that is not a docs

package/dist/commands/explore.js.map

@@ -1 +1 @@
-{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../src/commands/explore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../core/envelope/config.js\";\nimport { explore, type Exploration, type ExploreService } from \"../core/explore/explore.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/envelope/json.js\";\nimport { featureIdProblem } from \"../core/kernel/ids/feature.js\";\nimport { parseServiceIds } from \"../core/kernel/ids/service.js\";\nimport { DocsRepoUnavailableError } from \"../core/repo/state.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"./policy/gate.js\";\nimport { plural } from \"./policy/format.js\";\n\n/**\n * The feature id in the suggested command line when `--as` did not say.\n *\n * It has to satisfy the feature-id grammar, because `scaffold` is documented as\n * the literal `loam new` line and AGENTS.md's rule is that an instruction loam\n * prints and loam refuses is a defect. `FEAT-NNN` — the obvious placeholder —\n * is exactly that: `loam new FEAT-NNN` comes back `invalid-option`, so the last\n * line of every default run was a command that could not be run.\n *\n * `FEAT-000` parses and is still unmistakably a placeholder, which buys the\n * property the refusal was standing in for: an agent that pastes it unedited\n * gets a feature called FEAT-000, visible in `loam list` within seconds and\n * deletable with `git rm -r`. A plausible id (FEAT-1) would not be.\n */\nconst PLACEHOLDER = \"FEAT-000\";\n\ninterface ExploreOptions {\n  json?: boolean;\n  op?: string[];\n  capability?: string[];\n  as?: string;\n}\n\nexport function registerExplore(program: Command): void {\n  program\n    .command(\"explore\")\n    .argument(\"[service...]\", \"service ids the change starts from\")\n    .description(\"Read the fleet around a change nobody has written down yet — writes nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .option(\n      \"--op <operationId>\",\n      \"seed from an operation instead of a service; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\n      \"--capability <id>\",\n      \"seed from a declared capability's realizing services; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\"--as <FEAT>\", `feature id for the suggested command line (default: ${PLACEHOLDER})`)\n    .action(async (serviceArgs: string[], opts: ExploreOptions) => {\n      const json = opts.json === true;\n      const services = serviceArgs ?? [];\n      const operations = opts.op ?? [];\n      const capabilities = opts.capability ?? [];\n\n      // `--as` is interpolated into the `loam new` line this command prints\n      // under `next:` and returns as `scaffold`, and `loam-feature` teaches an\n      // agent to pass `$1` straight into it. Unchecked, `explore` hands back a\n      // command `loam new` then refuses — loam instructing an agent to run\n      // something loam rejects, which is the one thing the printed-command\n      // guard exists to prevent and the one shape it cannot see, because it\n      // reads literal source strings and this line is assembled from argv.\n      // Same grammar as `new`'s, from core/kernel/ids/feature.ts, so the two cannot disagree.\n      if (opts.as !== undefined) {\n        const problem = featureIdProblem(opts.as, \"feature id for --as\");\n        if (problem !== null) {\n          fail(json, \"invalid-option\", problem);\n          return;\n        }\n      }\n      if (services.length === 0 && operations.length === 0 && capabilities.length === 0) {\n        fail(\n          json,\n          \"invalid-option\",\n          \"Nothing to explore from. Name at least one service, or pass --op <operationId> or --capability <id>. \" +\n            \"`loam list services` is the fleet; `loam show <service>` is one of them; \" +\n            \"`loam list capabilities` is what the fleet promises.\",\n        );\n        return;\n      }\n\n      // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is\n      // guarded at the command boundary. Every id here reaches the service path builders.\n      // Before `loadConfig`, exactly as `loam new` guards its `--touches` list:\n      // the grammar is a fact about the argument, not about the repository, so\n      // an unusable id should answer the same whether or not you are standing\n      // in a wired repo.\n      //\n      // A seed naming a service that does not EXIST is fine and reported as\n      // `unknown` — the feature may be introducing it — but one that could not\n      // be a service directory at all is a typo, not an intention.\n      const seeds = parseServiceIds(services, \"service\");\n      if (!seeds.ok) {\n        fail(json, \"invalid-option\", seeds.problem);\n        return;\n      }\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      const { docsDir } = config;\n      // `services`, not `docs`: every answer here is a statement about the\n      // fleet, and an empty ring read out of a directory that is not a docs\n      // repo says \"nothing calls this service\" about a repo nobody looked in.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      try {\n        const result = await explore({\n          docsDir,\n          services: seeds.ids,\n          operations,\n          capabilities,\n          featureId: opts.as ?? PLACEHOLDER,\n          context: new FleetContext(),\n        });\n        if (json) {\n          emitJson({ command: \"explore\", docsDir, ...result });\n          return;\n        }\n        print(result);\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // The scan is all-or-nothing — it reads every seed's contract to build\n        // one table — so the honest answer to an unreadable file is a refusal\n        // naming the path, not a ring with a silent hole in it.\n        reportRepositoryUnavailable(json, err, \"the exploration would be missing a service\", docsDir);\n      }\n    });\n}\n\n/* ------------------------------------------------------------------ */\n\nfunction print(r: Exploration): void {\n  if (!r.landscape.present || !r.landscape.parses) {\n    // Said first and without hedging: with no readable map there IS no ring,\n    // and a reader who takes the empty neighbour list at face value concludes\n    // the change is contained when nothing checked that.\n    // Same rule as `context`'s printer: name the document that actually failed.\n    // `parses` answers for the `architecture/` PROJECT, so the document at fault\n    // is very often a SIBLING beside a landscape that reads perfectly, and\n    // naming the landscape was a claim about bytes loam read fine (verification\n    // 2026-09-04). `present` is still about the FILE — it is the write target\n    // every brief asks for edits to — so the absent arm keeps the file name.\n    const named = !r.landscape.present\n      ? \"architecture/landscape.likec4 does not exist\"\n      : r.landscape.broken.length === 0\n        ? \"the fleet map (architecture/) does not parse\"\n        : `${r.landscape.broken.join(\", \")} ${r.landscape.broken.length > 1 ? \"do\" : \"does\"} not parse`;\n    console.log(`! ${named} — no neighbour below is derived, and none is missing either\\n`);\n  }\n\n  for (const s of r.services) {\n    console.log(`${s.id}   ${label(s)}`);\n    if (!s.known) {\n      // Two different facts wear the same absence. A SEED nobody typed by\n      // accident is a service the feature introduces; one typed by accident is\n      // a typo, and the near-miss list is what separates them. A neighbour is\n      // neither — the fleet map drew an edge to something with no\n      // `services/<id>/`, which is usually an external system and occasionally\n      // a service nobody has adopted. Saying \"typo\" about that one sends a\n      // reader looking for a mistake they did not make.\n      const near = r.unknown.find((u) => u.id === s.id)?.nearest ?? [];\n      const why =\n        s.reason === \"seed\"\n          ? \"the feature introduces it, or the id is a typo\"\n          : \"an external system, or a service nobody has adopted\";\n      console.log(\n        `    no services/${s.id}/ — ${why}` +\n          (near.length > 0 ? `; closest existing: ${near.join(\", \")}` : \"\"),\n      );\n    } else {\n      if (s.missing.length > 0) console.log(`    missing: ${s.missing.join(\", \")}`);\n      if (!s.modelled) console.log(`    not in the fleet map — no edge into it can be checked`);\n      // Said before `exposes`, and said at all: an unreadable contract exposes\n      // an empty list, and printing nothing there reads as \"this service offers\n      // no endpoints\" — the answer that turns a MODIFIED requirement into an\n      // ADDED one.\n      if (s.openapi.unreadable) {\n        console.log(`    ! openapi.yaml does not parse — nothing here lists what ${s.id} exposes`);\n        if (s.openapi.error !== undefined) console.log(`      ${s.openapi.error}`);\n      } else if (s.operations.length > 0) {\n        console.log(`    exposes: ${s.operations.join(\", \")}`);\n      }\n    }\n    for (const e of s.inbound) console.log(`    ← ${e.service}${edgeNote(e.op, e.title)}`);\n    for (const e of s.outbound) console.log(`    → ${e.service}${edgeNote(e.op, e.title)}`);\n    console.log(\"\");\n  }\n\n  if (r.unresolvedOperations.length > 0) {\n    console.log(\n      `! no living contract defines ${r.unresolvedOperations.join(\", \")} — ` +\n        `the feature is adding ${r.unresolvedOperations.length === 1 ? \"it\" : \"them\"}, or the id is wrong\\n`,\n    );\n  }\n\n  if (r.unresolvedCapabilities.length > 0) {\n    console.log(\n      `! no realizing service seeds ${r.unresolvedCapabilities.join(\", \")} — ` +\n        `not declared in architecture/capabilities.yaml, or declared and realized by nothing\\n`,\n    );\n  }\n\n  if (r.neighbours.length > 0) {\n    // The whole point of the command, so it is stated as a question rather than\n    // a list: these are candidates for --touches, and loam does not know which\n    // of them this change actually touches.\n    console.log(\n      `${plural(r.neighbours.length, \"neighbour\")} one hop out: ${r.neighbours.join(\", \")}`,\n    );\n    console.log(\"  weigh each one — loam knows they are connected, not whether you change them\\n\");\n  }\n\n  if (r.overlaps.length > 0) {\n    console.log(\"already in flight over this ground\");\n    for (const o of r.overlaps) console.log(`  ${o.feature}  ${o.services.join(\", \")}`);\n    console.log(\"  `loam dependencies` says which must archive first, and what no ordering fixes\\n\");\n  }\n\n  console.log(`next: ${r.scaffold}`);\n}\n\nfunction label(s: ExploreService): string {\n  const where = s.reason === \"seed\" ? \"seed\" : s.reason === \"calls-seed\" ? \"calls a seed\" : \"called by a seed\";\n  // `known`, matching the branch in `print` — not `maturity === null`. The two\n  // are set together and cannot disagree today, but discriminating on different\n  // fields for the same question is how they start to: a reader fixing one\n  // branch has no reason to look at the other.\n  return s.known ? `${where} · ${s.maturity}` : `${where} · not in the docs repo`;\n}\n\nfunction edgeNote(op: string | null, title: string | null): string {\n  if (op !== null) return `  ${op}`;\n  return title !== null ? `  \"${title}\"` : \"\";\n}\n"]}
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../src/commands/explore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { explore, type Exploration, type ExploreService } from \"../core/explore/explore.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { configOrRefuse, emitJson, fail } from \"../core/envelope/json.js\";\nimport { featureIdProblem } from \"../core/kernel/ids/feature.js\";\nimport { parseServiceIds } from \"../core/kernel/ids/service.js\";\nimport { DocsRepoUnavailableError } from \"../core/repo/state.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"./policy/gate.js\";\nimport { plural } from \"./policy/format.js\";\n\n/**\n * The feature id in the suggested command line when `--as` did not say.\n *\n * It has to satisfy the feature-id grammar, because `scaffold` is documented as\n * the literal `loam new` line and AGENTS.md's rule is that an instruction loam\n * prints and loam refuses is a defect. `FEAT-NNN` — the obvious placeholder —\n * is exactly that: `loam new FEAT-NNN` comes back `invalid-option`, so the last\n * line of every default run was a command that could not be run.\n *\n * `FEAT-000` parses and is still unmistakably a placeholder, which buys the\n * property the refusal was standing in for: an agent that pastes it unedited\n * gets a feature called FEAT-000, visible in `loam list` within seconds and\n * deletable with `git rm -r`. A plausible id (FEAT-1) would not be.\n */\nconst PLACEHOLDER = \"FEAT-000\";\n\ninterface ExploreOptions {\n  json?: boolean;\n  op?: string[];\n  capability?: string[];\n  as?: string;\n}\n\nexport function registerExplore(program: Command): void {\n  program\n    .command(\"explore\")\n    .argument(\"[service...]\", \"service ids the change starts from\")\n    .description(\"Read the fleet around a change nobody has written down yet — writes nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .option(\n      \"--op <operationId>\",\n      \"seed from an operation instead of a service; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\n      \"--capability <id>\",\n      \"seed from a declared capability's realizing services; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\"--as <FEAT>\", `feature id for the suggested command line (default: ${PLACEHOLDER})`)\n    .action(async (serviceArgs: string[], opts: ExploreOptions) => {\n      const json = opts.json === true;\n      const services = serviceArgs ?? [];\n      const operations = opts.op ?? [];\n      const capabilities = opts.capability ?? [];\n\n      // `--as` is interpolated into the `loam new` line this command prints\n      // under `next:` and returns as `scaffold`, and `loam-feature` teaches an\n      // agent to pass `$1` straight into it. Unchecked, `explore` hands back a\n      // command `loam new` then refuses — loam instructing an agent to run\n      // something loam rejects, which is the one thing the printed-command\n      // guard exists to prevent and the one shape it cannot see, because it\n      // reads literal source strings and this line is assembled from argv.\n      // Same grammar as `new`'s, from core/kernel/ids/feature.ts, so the two cannot disagree.\n      if (opts.as !== undefined) {\n        const problem = featureIdProblem(opts.as, \"feature id for --as\");\n        if (problem !== null) {\n          fail(json, \"invalid-option\", problem);\n          return;\n        }\n      }\n      if (services.length === 0 && operations.length === 0 && capabilities.length === 0) {\n        fail(\n          json,\n          \"invalid-option\",\n          \"Nothing to explore from. Name at least one service, or pass --op <operationId> or --capability <id>. \" +\n            \"`loam list services` is the fleet; `loam show <service>` is one of them; \" +\n            \"`loam list capabilities` is what the fleet promises.\",\n        );\n        return;\n      }\n\n      // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is\n      // guarded at the command boundary. Every id here reaches the service path builders.\n      // Before the config is loaded, exactly as `loam new` guards its `--touches` list:\n      // the grammar is a fact about the argument, not about the repository, so\n      // an unusable id should answer the same whether or not you are standing\n      // in a wired repo.\n      //\n      // A seed naming a service that does not EXIST is fine and reported as\n      // `unknown` — the feature may be introducing it — but one that could not\n      // be a service directory at all is a typo, not an intention.\n      const seeds = parseServiceIds(services, \"service\");\n      if (!seeds.ok) {\n        fail(json, \"invalid-option\", seeds.problem);\n        return;\n      }\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // `services`, not `docs`: every answer here is a statement about the\n      // fleet, and an empty ring read out of a directory that is not a docs\n      // repo says \"nothing calls this service\" about a repo nobody looked in.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      try {\n        const result = await explore({\n          docsDir,\n          services: seeds.ids,\n          operations,\n          capabilities,\n          featureId: opts.as ?? PLACEHOLDER,\n          context: new FleetContext(),\n        });\n        if (json) {\n          emitJson({ command: \"explore\", docsDir, ...result });\n          return;\n        }\n        print(result);\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // The scan is all-or-nothing — it reads every seed's contract to build\n        // one table — so the honest answer to an unreadable file is a refusal\n        // naming the path, not a ring with a silent hole in it.\n        reportRepositoryUnavailable(json, err, \"the exploration would be missing a service\", docsDir);\n      }\n    });\n}\n\n/* ------------------------------------------------------------------ */\n\nfunction print(r: Exploration): void {\n  if (!r.landscape.present || !r.landscape.parses) {\n    // Said first and without hedging: with no readable map there IS no ring,\n    // and a reader who takes the empty neighbour list at face value concludes\n    // the change is contained when nothing checked that.\n    // Same rule as `context`'s printer: name the document that actually failed.\n    // `parses` answers for the `architecture/` PROJECT, so the document at fault\n    // is very often a SIBLING beside a landscape that reads perfectly, and\n    // naming the landscape was a claim about bytes loam read fine (verification\n    // 2026-09-04). `present` is still about the FILE — it is the write target\n    // every brief asks for edits to — so the absent arm keeps the file name.\n    const named = !r.landscape.present\n      ? \"architecture/landscape.likec4 does not exist\"\n      : r.landscape.broken.length === 0\n        ? \"the fleet map (architecture/) does not parse\"\n        : `${r.landscape.broken.join(\", \")} ${r.landscape.broken.length > 1 ? \"do\" : \"does\"} not parse`;\n    console.log(`! ${named} — no neighbour below is derived, and none is missing either\\n`);\n  }\n\n  for (const s of r.services) {\n    console.log(`${s.id}   ${label(s)}`);\n    if (!s.known) {\n      // Two different facts wear the same absence. A SEED nobody typed by\n      // accident is a service the feature introduces; one typed by accident is\n      // a typo, and the near-miss list is what separates them. A neighbour is\n      // neither — the fleet map drew an edge to something with no\n      // `services/<id>/`, which is usually an external system and occasionally\n      // a service nobody has adopted. Saying \"typo\" about that one sends a\n      // reader looking for a mistake they did not make.\n      const near = r.unknown.find((u) => u.id === s.id)?.nearest ?? [];\n      const why =\n        s.reason === \"seed\"\n          ? \"the feature introduces it, or the id is a typo\"\n          : \"an external system, or a service nobody has adopted\";\n      console.log(\n        `    no services/${s.id}/ — ${why}` +\n          (near.length > 0 ? `; closest existing: ${near.join(\", \")}` : \"\"),\n      );\n    } else {\n      if (s.missing.length > 0) console.log(`    missing: ${s.missing.join(\", \")}`);\n      if (!s.modelled) console.log(`    not in the fleet map — no edge into it can be checked`);\n      // Said before `exposes`, and said at all: an unreadable contract exposes\n      // an empty list, and printing nothing there reads as \"this service offers\n      // no endpoints\" — the answer that turns a MODIFIED requirement into an\n      // ADDED one.\n      if (s.openapi.unreadable) {\n        console.log(`    ! openapi.yaml does not parse — nothing here lists what ${s.id} exposes`);\n        if (s.openapi.error !== undefined) console.log(`      ${s.openapi.error}`);\n      } else if (s.operations.length > 0) {\n        console.log(`    exposes: ${s.operations.join(\", \")}`);\n      }\n    }\n    for (const e of s.inbound) console.log(`    ← ${e.service}${edgeNote(e.op, e.title)}`);\n    for (const e of s.outbound) console.log(`    → ${e.service}${edgeNote(e.op, e.title)}`);\n    console.log(\"\");\n  }\n\n  if (r.unresolvedOperations.length > 0) {\n    console.log(\n      `! no living contract defines ${r.unresolvedOperations.join(\", \")} — ` +\n        `the feature is adding ${r.unresolvedOperations.length === 1 ? \"it\" : \"them\"}, or the id is wrong\\n`,\n    );\n  }\n\n  if (r.unresolvedCapabilities.length > 0) {\n    console.log(\n      `! no realizing service seeds ${r.unresolvedCapabilities.join(\", \")} — ` +\n        `not declared in architecture/capabilities.yaml, or declared and realized by nothing\\n`,\n    );\n  }\n\n  if (r.neighbours.length > 0) {\n    // The whole point of the command, so it is stated as a question rather than\n    // a list: these are candidates for --touches, and loam does not know which\n    // of them this change actually touches.\n    console.log(\n      `${plural(r.neighbours.length, \"neighbour\")} one hop out: ${r.neighbours.join(\", \")}`,\n    );\n    console.log(\"  weigh each one — loam knows they are connected, not whether you change them\\n\");\n  }\n\n  if (r.overlaps.length > 0) {\n    console.log(\"already in flight over this ground\");\n    for (const o of r.overlaps) console.log(`  ${o.feature}  ${o.services.join(\", \")}`);\n    console.log(\"  `loam dependencies` says which must archive first, and what no ordering fixes\\n\");\n  }\n\n  console.log(`next: ${r.scaffold}`);\n}\n\nfunction label(s: ExploreService): string {\n  const where = s.reason === \"seed\" ? \"seed\" : s.reason === \"calls-seed\" ? \"calls a seed\" : \"called by a seed\";\n  // `known`, matching the branch in `print` — not `maturity === null`. The two\n  // are set together and cannot disagree today, but discriminating on different\n  // fields for the same question is how they start to: a reader fixing one\n  // branch has no reason to look at the other.\n  return s.known ? `${where} · ${s.maturity}` : `${where} · not in the docs repo`;\n}\n\nfunction edgeNote(op: string | null, title: string | null): string {\n  if (op !== null) return `  ${op}`;\n  return title !== null ? `  \"${title}\"` : \"\";\n}\n"]}

package/dist/commands/gate/gate.js

@@ -1,29 +1,61 @@
-import { loadConfig } from "../../core/envelope/config.js";
-import { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE } from "../../core/envelope/json.js";
 import { FleetContext } from "../../core/fleet-context.js";
+import { listBaseSubdirs, subdirsChangedSince } from "../../core/diff/base-git.js";
 import { gateReport } from "../../core/gate/checks.js";
 import { gateSummary, gateVerdict } from "../../core/gate/report.js";
 import { nearestIds } from "../../core/repo/entries.js";
+import { archiveDir } from "../../core/repo/paths.js";
 import { enumeratedServiceIds, resolveServiceTarget } from "../../core/repo/service-target.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
 import { findingJson } from "../../core/vocabulary/report.js";
-import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable, } from "../policy/gate.js";
+import { baseOrRefuse, docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable, } from "../policy/gate.js";
 import { printGate } from "./print.js";
+/**
+ * `--since <ref>` resolved against the docs repo's history, or null after
+ * refusing. A listing git declines is a refusal too, never an empty one: "no
+ * archive at the ref" grades every archived feature in the repo as shipped
+ * since, and reading "could not list" as that would be a guess. The second
+ * question — which of those directories changed since — has a safe answer to
+ * fall to, and falls to it (see below).
+ */
+async function readSince(json, docsDir, ref) {
+    const base = await baseOrRefuse(json, docsDir, {
+        flag: "--since",
+        ref,
+        reads: "loam gate --since reads which features were already archived at that ref",
+    });
+    if (base === null)
+        return null;
+    const listing = await listBaseSubdirs(base, archiveDir(docsDir));
+    if (listing.kind === "failed") {
+        fail(json, "repository-unavailable", `git could not list features/archive/ at ${ref} in the docs repo at ${docsDir} (${listing.detail}) — ` +
+            `without it there is no telling which features shipped since, and the gate will not guess. Re-run once git can answer.`);
+        return null;
+    }
+    // Present at the ref is not enough to have shipped by then: a feature
+    // unarchived, edited and archived again sits at the same path with
+    // different contents, and it is this deploy's to answer for. Only a
+    // directory whose contents are what they were at the ref stays out. When
+    // git will not say what changed, every one of them is graded — the
+    // direction this gate fails in is "looked at too much", never "skipped a
+    // ship" — unlike the listing above, which has no safe default to fall to.
+    const changed = await subdirsChangedSince(base, archiveDir(docsDir));
+    const moved = changed.kind === "ok" ? changed.names : new Set(listing.names);
+    return { ref, commit: base.commit, shippedAtRef: new Set(listing.names.filter((name) => !moved.has(name))) };
+}
 export function registerGate(program) {
     program
         .command("gate")
         .description("Can this service deploy? A read-only query over recorded evidence — advisory by default")
         .option("--service <id>", "the service being deployed (defaults to the configured service)")
+        .option("--since <ref>", "also grade the features archived after this docs-repo git ref (e.g. the docs commit your last deploy recorded) — without it only in-flight features are read")
         .option("--strict", "exit 1 on any warning too — a per-invocation CI lever; the report and --json payload do not change")
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         const { docsDir } = config;
         // The gate joins partners and enumerates features against services/ —
         // a docsDir that is not a docs repo must refuse, never answer "pass"
@@ -37,6 +69,9 @@ export function registerGate(program) {
             fail(json, "invalid-option", NO_SERVICE_MESSAGE);
             return;
         }
+        const since = opts.since === undefined ? undefined : await readSince(json, docsDir, opts.since);
+        if (since === null)
+            return;
         // One invocation, one filesystem snapshot (validate's rule).
         const fleet = new FleetContext();
         try {
@@ -68,6 +103,7 @@ export function registerGate(program) {
                 service: resolved.id,
                 repoDir: bound === resolved.id ? (config.root ?? process.cwd()) : undefined,
                 fleet,
+                since,
             });
             const verdict = gateVerdict(report.checks);
             const summary = gateSummary(report.checks);
@@ -78,6 +114,7 @@ export function registerGate(program) {
                     service: report.service,
                     verdict,
                     strict: opts.strict === true,
+                    since: report.since,
                     landscape: report.landscape,
                     partners: report.partners,
                     features: report.features,

package/dist/commands/gate/gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/commands/gate/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam gate` — can this service deploy, as far as RECORDED evidence can say?\n *\n * A pure query for DEPLOY pipelines outside loam's own lifecycle (Pact's\n * can-i-deploy insight: the gate executes nothing and queries evidence\n * previously recorded). It reads, never writes, never takes the docs lock, and\n * deliberately changes NOTHING about what gates `loam archive` — verify still\n * never gates the merge (WORKFLOW.md, \"What actually gates\"); this command's\n * verdict is advice to a pipeline loam does not own. Advisory by default:\n * warnings exit 0, errors exit 1, and `--strict` is the CI lever that\n * escalates warnings — validate's exact idiom, not a second spelling of it.\n *\n * Not to be confused with `commands/policy/gate.ts`, which is the docs-repo\n * READINESS doctrine (docsRepoReady and friends) every reading command shares\n * — including this one, one import below.\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { gateReport } from \"../../core/gate/checks.js\";\nimport { gateSummary, gateVerdict } from \"../../core/gate/report.js\";\nimport { nearestIds } from \"../../core/repo/entries.js\";\nimport { enumeratedServiceIds, resolveServiceTarget } from \"../../core/repo/service-target.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport {\n  docsRepoReady,\n  reportDocsRepoError,\n  reportRepositoryUnavailable,\n} from \"../policy/gate.js\";\nimport { printGate } from \"./print.js\";\n\ninterface GateOptions {\n  service?: string;\n  strict?: boolean;\n  json?: boolean;\n}\n\nexport function registerGate(program: Command): void {\n  program\n    .command(\"gate\")\n    .description(\"Can this service deploy? A read-only query over recorded evidence — advisory by default\")\n    .option(\"--service <id>\", \"the service being deployed (defaults to the configured service)\")\n    .option(\"--strict\", \"exit 1 on any warning too — a per-invocation CI lever; the report and --json payload do not change\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: GateOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      const { docsDir } = config;\n      // The gate joins partners and enumerates features against services/ —\n      // a docsDir that is not a docs repo must refuse, never answer \"pass\"\n      // over an empty fleet (docsRepoReady's whole doctrine).\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n      // The deploy-pipeline invocation is literally `loam gate --json` in a\n      // bound service repo: the binding IS the service being deployed.\n      const service = opts.service ?? config.service;\n      if (!service) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      // One invocation, one filesystem snapshot (validate's rule).\n      const fleet = new FleetContext();\n\n      try {\n        // Enumeration first, grammar second — service-target.ts's banner: the\n        // one directory a caller most needs to ask about may carry a name the\n        // grammar refuses, so the raw argument is never assertServiceId'd here.\n        const resolved = await resolveServiceTarget(docsDir, service, \"--service\", fleet);\n        if (!resolved.ok) {\n          fail(json, \"invalid-option\", resolved.problem);\n          return;\n        }\n        if (resolved.dir === undefined) {\n          // Grammar-legal but unenumerated: a question recorded evidence\n          // cannot answer — Pact's gate answers unknown participants with a\n          // refusal, not a pass (status's `unknown-service` precedent).\n          const near = nearestIds(resolved.id, await enumeratedServiceIds(docsDir, fleet));\n          fail(\n            json,\n            \"unknown-service\",\n            `No service '${resolved.id}' under ${docsDir}/services/ — nothing is recorded for a service nobody adopted, so the deploy question is unanswerable.` +\n              (near.length > 0 ? ` Did you mean: ${near.join(\", \")}?` : \"\") +\n              ` Run \\`loam adopt --service ${resolved.id}\\` to write its baseline first.`,\n          );\n          return;\n        }\n        // `sources` only mean something from inside the service's own\n        // repository — validate's repoOf rule. `config.root` rather than\n        // process.cwd(): the config's own directory is the repo root, and a\n        // run from src/deep/ must grade the same paths as one from the root.\n        const bound: string | undefined = config.service;\n        const report = await gateReport({\n          docsDir,\n          service: resolved.id,\n          repoDir: bound === resolved.id ? (config.root ?? process.cwd()) : undefined,\n          fleet,\n        });\n        const verdict = gateVerdict(report.checks);\n        const summary = gateSummary(report.checks);\n        if (json) {\n          emitJson({\n            command: \"gate\",\n            docsDir,\n            service: report.service,\n            verdict,\n            strict: opts.strict === true,\n            landscape: report.landscape,\n            partners: report.partners,\n            features: report.features,\n            checks: report.checks.map((c) => ({\n              check: c.check,\n              findings: c.findings.map((finding) => findingJson(finding)),\n            })),\n            summary,\n          });\n        } else {\n          printGate(report, verdict, summary);\n        }\n        // --strict moves only the exit code, never the verdict or the payload\n        // — validate's exact stance, documented on its own strict block: two\n        // pipelines reading one repo may grade the same report differently\n        // and both are telling the truth.\n        if (verdict === \"fail\" || (opts.strict === true && summary.warnings > 0)) {\n          process.exitCode = 1;\n        }\n      } catch (err) {\n        // The docs repo went away between the gate above and the reads.\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // An IO failure the per-subject containment could not localise — it\n        // happened in an enumeration, so no partial report exists to give.\n        // The recognizer throws anything carrying no errno untouched.\n        reportRepositoryUnavailable(\n          json,\n          err,\n          `the deploy question for '${service}' is unanswerable`,\n          docsDir,\n        );\n      }\n    });\n}\n"]}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/commands/gate/gate.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAkB,MAAM,2BAA2B,CAAC;AAErF,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC/F,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EACL,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AASvC;;;;;;;GAOG;AACH,KAAK,UAAU,SAAS,CAAC,IAAa,EAAE,OAAgB,EAAE,GAAW;IACnE,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE;QAC7C,IAAI,EAAE,SAAS;QACf,GAAG;QACH,KAAK,EAAE,0EAA0E;KAClF,CAAC,CAAC;IACH,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CACF,IAAI,EACJ,wBAAwB,EACxB,2CAA2C,GAAG,wBAAwB,OAAO,KAAK,OAAO,CAAC,MAAM,MAAM;YACpG,uHAAuH,CAC1H,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,sEAAsE;IACtE,mEAAmE;IACnE,oEAAoE;IACpE,yEAAyE;IACzE,mEAAmE;IACnE,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7E,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/G,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,yFAAyF,CAAC;SACtG,MAAM,CAAC,gBAAgB,EAAE,iEAAiE,CAAC;SAC3F,MAAM,CACL,eAAe,EACf,8JAA8J,CAC/J;SACA,MAAM,CAAC,UAAU,EAAE,oGAAoG,CAAC;SACxH,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAiB,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,sEAAsE;QACtE,qEAAqE;QACrE,wDAAwD;QACxD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC;YAAE,OAAO;QACtD,sEAAsE;QACtE,iEAAiE;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YACjD,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAChG,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO;QAC3B,6DAA6D;QAC7D,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;QAEjC,IAAI,CAAC;YACH,sEAAsE;YACtE,sEAAsE;YACtE,wEAAwE;YACxE,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;YAClF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAC/C,OAAO;YACT,CAAC;YACD,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC/B,+DAA+D;gBAC/D,kEAAkE;gBAClE,8DAA8D;gBAC9D,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;gBACjF,IAAI,CACF,IAAI,EACJ,iBAAiB,EACjB,eAAe,QAAQ,CAAC,EAAE,WAAW,OAAO,wGAAwG;oBAClJ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7D,+BAA+B,QAAQ,CAAC,EAAE,iCAAiC,CAC9E,CAAC;gBACF,OAAO;YACT,CAAC;YACD,8DAA8D;YAC9D,iEAAiE;YACjE,oEAAoE;YACpE,qEAAqE;YACrE,MAAM,KAAK,GAAuB,MAAM,CAAC,OAAO,CAAC;YACjD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC;gBAC9B,OAAO;gBACP,OAAO,EAAE,QAAQ,CAAC,EAAE;gBACpB,OAAO,EAAE,KAAK,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC3E,KAAK;gBACL,KAAK;aACN,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,IAAI,EAAE,CAAC;gBACT,QAAQ,CAAC;oBACP,OAAO,EAAE,MAAM;oBACf,OAAO;oBACP,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,OAAO;oBACP,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,IAAI;oBAC5B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAChC,KAAK,EAAE,CAAC,CAAC,KAAK;wBACd,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;qBAC5D,CAAC,CAAC;oBACH,OAAO;iBACR,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YACtC,CAAC;YACD,sEAAsE;YACtE,qEAAqE;YACrE,mEAAmE;YACnE,kCAAkC;YAClC,IAAI,OAAO,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gEAAgE;YAChE,IAAI,GAAG,YAAY,wBAAwB,EAAE,CAAC;gBAC5C,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC/B,OAAO;YACT,CAAC;YACD,oEAAoE;YACpE,mEAAmE;YACnE,8DAA8D;YAC9D,2BAA2B,CACzB,IAAI,EACJ,GAAG,EACH,4BAA4B,OAAO,mBAAmB,EACtD,OAAO,CACR,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * `loam gate` — can this service deploy, as far as RECORDED evidence can say?\n *\n * A pure query for DEPLOY pipelines outside loam's own lifecycle (Pact's\n * can-i-deploy insight: the gate executes nothing and queries evidence\n * previously recorded). It reads, never writes, never takes the docs lock, and\n * deliberately changes NOTHING about what gates `loam archive` — verify still\n * never gates the merge (WORKFLOW.md, \"What actually gates\"); this command's\n * verdict is advice to a pipeline loam does not own. Advisory by default:\n * warnings exit 0, errors exit 1, and `--strict` is the CI lever that\n * escalates warnings — validate's exact idiom, not a second spelling of it.\n *\n * Without `--since` the verification check reads IN-FLIGHT features only: a\n * feature leaves it the moment it is archived, so a deploy that ships slices\n * after their feature archived would be gated without it. `--since <ref>` —\n * a docs-repo git ref, the commit the pipeline last deployed from — adds every\n * feature archived after it, read out of git exactly as `loam diff --base`\n * reads its base (`core/diff/base-git.ts`), with the same two refusals when\n * git cannot answer (`baseOrRefuse`). Nothing is stored: the pipeline already\n * knows its last-deployed ref, and loam keeps no deployment state.\n *\n * Not to be confused with `commands/policy/gate.ts`, which is the docs-repo\n * READINESS doctrine (docsRepoReady and friends, and `baseOrRefuse` for a git\n * ref) every reading command shares — including this one, one import below.\n */\nimport type { Command } from \"commander\";\nimport { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE } from \"../../core/envelope/json.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { listBaseSubdirs, subdirsChangedSince } from \"../../core/diff/base-git.js\";\nimport { gateReport } from \"../../core/gate/checks.js\";\nimport { gateSummary, gateVerdict, type GateSince } from \"../../core/gate/report.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { nearestIds } from \"../../core/repo/entries.js\";\nimport { archiveDir } from \"../../core/repo/paths.js\";\nimport { enumeratedServiceIds, resolveServiceTarget } from \"../../core/repo/service-target.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport {\n  baseOrRefuse,\n  docsRepoReady,\n  reportDocsRepoError,\n  reportRepositoryUnavailable,\n} from \"../policy/gate.js\";\nimport { printGate } from \"./print.js\";\n\ninterface GateOptions {\n  service?: string;\n  since?: string;\n  strict?: boolean;\n  json?: boolean;\n}\n\n/**\n * `--since <ref>` resolved against the docs repo's history, or null after\n * refusing. A listing git declines is a refusal too, never an empty one: \"no\n * archive at the ref\" grades every archived feature in the repo as shipped\n * since, and reading \"could not list\" as that would be a guess. The second\n * question — which of those directories changed since — has a safe answer to\n * fall to, and falls to it (see below).\n */\nasync function readSince(json: boolean, docsDir: DocsDir, ref: string): Promise<GateSince | null> {\n  const base = await baseOrRefuse(json, docsDir, {\n    flag: \"--since\",\n    ref,\n    reads: \"loam gate --since reads which features were already archived at that ref\",\n  });\n  if (base === null) return null;\n  const listing = await listBaseSubdirs(base, archiveDir(docsDir));\n  if (listing.kind === \"failed\") {\n    fail(\n      json,\n      \"repository-unavailable\",\n      `git could not list features/archive/ at ${ref} in the docs repo at ${docsDir} (${listing.detail}) — ` +\n        `without it there is no telling which features shipped since, and the gate will not guess. Re-run once git can answer.`,\n    );\n    return null;\n  }\n  // Present at the ref is not enough to have shipped by then: a feature\n  // unarchived, edited and archived again sits at the same path with\n  // different contents, and it is this deploy's to answer for. Only a\n  // directory whose contents are what they were at the ref stays out. When\n  // git will not say what changed, every one of them is graded — the\n  // direction this gate fails in is \"looked at too much\", never \"skipped a\n  // ship\" — unlike the listing above, which has no safe default to fall to.\n  const changed = await subdirsChangedSince(base, archiveDir(docsDir));\n  const moved = changed.kind === \"ok\" ? changed.names : new Set(listing.names);\n  return { ref, commit: base.commit, shippedAtRef: new Set(listing.names.filter((name) => !moved.has(name))) };\n}\n\nexport function registerGate(program: Command): void {\n  program\n    .command(\"gate\")\n    .description(\"Can this service deploy? A read-only query over recorded evidence — advisory by default\")\n    .option(\"--service <id>\", \"the service being deployed (defaults to the configured service)\")\n    .option(\n      \"--since <ref>\",\n      \"also grade the features archived after this docs-repo git ref (e.g. the docs commit your last deploy recorded) — without it only in-flight features are read\",\n    )\n    .option(\"--strict\", \"exit 1 on any warning too — a per-invocation CI lever; the report and --json payload do not change\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: GateOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // The gate joins partners and enumerates features against services/ —\n      // a docsDir that is not a docs repo must refuse, never answer \"pass\"\n      // over an empty fleet (docsRepoReady's whole doctrine).\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n      // The deploy-pipeline invocation is literally `loam gate --json` in a\n      // bound service repo: the binding IS the service being deployed.\n      const service = opts.service ?? config.service;\n      if (!service) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      const since = opts.since === undefined ? undefined : await readSince(json, docsDir, opts.since);\n      if (since === null) return;\n      // One invocation, one filesystem snapshot (validate's rule).\n      const fleet = new FleetContext();\n\n      try {\n        // Enumeration first, grammar second — service-target.ts's banner: the\n        // one directory a caller most needs to ask about may carry a name the\n        // grammar refuses, so the raw argument is never assertServiceId'd here.\n        const resolved = await resolveServiceTarget(docsDir, service, \"--service\", fleet);\n        if (!resolved.ok) {\n          fail(json, \"invalid-option\", resolved.problem);\n          return;\n        }\n        if (resolved.dir === undefined) {\n          // Grammar-legal but unenumerated: a question recorded evidence\n          // cannot answer — Pact's gate answers unknown participants with a\n          // refusal, not a pass (status's `unknown-service` precedent).\n          const near = nearestIds(resolved.id, await enumeratedServiceIds(docsDir, fleet));\n          fail(\n            json,\n            \"unknown-service\",\n            `No service '${resolved.id}' under ${docsDir}/services/ — nothing is recorded for a service nobody adopted, so the deploy question is unanswerable.` +\n              (near.length > 0 ? ` Did you mean: ${near.join(\", \")}?` : \"\") +\n              ` Run \\`loam adopt --service ${resolved.id}\\` to write its baseline first.`,\n          );\n          return;\n        }\n        // `sources` only mean something from inside the service's own\n        // repository — validate's repoOf rule. `config.root` rather than\n        // process.cwd(): the config's own directory is the repo root, and a\n        // run from src/deep/ must grade the same paths as one from the root.\n        const bound: string | undefined = config.service;\n        const report = await gateReport({\n          docsDir,\n          service: resolved.id,\n          repoDir: bound === resolved.id ? (config.root ?? process.cwd()) : undefined,\n          fleet,\n          since,\n        });\n        const verdict = gateVerdict(report.checks);\n        const summary = gateSummary(report.checks);\n        if (json) {\n          emitJson({\n            command: \"gate\",\n            docsDir,\n            service: report.service,\n            verdict,\n            strict: opts.strict === true,\n            since: report.since,\n            landscape: report.landscape,\n            partners: report.partners,\n            features: report.features,\n            checks: report.checks.map((c) => ({\n              check: c.check,\n              findings: c.findings.map((finding) => findingJson(finding)),\n            })),\n            summary,\n          });\n        } else {\n          printGate(report, verdict, summary);\n        }\n        // --strict moves only the exit code, never the verdict or the payload\n        // — validate's exact stance, documented on its own strict block: two\n        // pipelines reading one repo may grade the same report differently\n        // and both are telling the truth.\n        if (verdict === \"fail\" || (opts.strict === true && summary.warnings > 0)) {\n          process.exitCode = 1;\n        }\n      } catch (err) {\n        // The docs repo went away between the gate above and the reads.\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // An IO failure the per-subject containment could not localise — it\n        // happened in an enumeration, so no partial report exists to give.\n        // The recognizer throws anything carrying no errno untouched.\n        reportRepositoryUnavailable(\n          json,\n          err,\n          `the deploy question for '${service}' is unanswerable`,\n          docsDir,\n        );\n      }\n    });\n}\n"]}

package/dist/commands/gate/print.js

@@ -32,13 +32,25 @@ export function printGate(report, verdict, summary) {
     if (freshness.length === 0)
         console.log(`  ${SEVERITY_MARK.ok} nothing recorded has gone stale`);
     printFindings(freshness);
-    console.log("\nverification");
+    // Under --since the heading names the bound, so a deploy log says which
+    // shipped features it graded; without it, that only in-flight ones were.
+    const since = report.since;
+    console.log(since === null ? "\nverification" : `\nverification — in flight, and archived since ${since.ref}`);
     for (const f of report.features) {
         const attested = f.attested > 0 ? `, ${f.attested} on an agent's word` : "";
-        console.log(`  ${f.id} · ${f.verdict} (${f.state}; ${f.confirmed}/${f.claims} confirmed${attested})`);
+        const shipped = f.archived === true ? " · archived" : "";
+        console.log(`  ${f.id} · ${f.verdict} (${f.state}; ${f.confirmed}/${f.claims} confirmed${attested})${shipped}`);
+        // A record read as frozen history because its archive captured no
+        // checklist (`checklistAtArchive: null`) was not held to the feature that
+        // shipped; a deploy log must not read that row as one that was.
+        if (f.archived === true && f.checklistAtArchive === null && f.state === "recorded") {
+            console.log("    its archive captured no checklist (archived by an older loam), so whether the record still answered the feature when it shipped is unknown — read as frozen history");
+        }
     }
     if (report.features.length === 0) {
-        console.log("  (no active feature carries a delta for this service)");
+        console.log(since === null
+            ? "  (no active feature carries a delta for this service)"
+            : `  (no feature in flight or archived since ${since.ref} carries a delta for this service)`);
     }
     printFindings(check("verification"));
     console.log("\ninterrupted");

package/dist/commands/gate/print.js.map

@@ -1 +1 @@
-{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/gate/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The human rendering of a gate report: one block per check, the partner and\n * feature tables as data lines, findings with the shared severity glyphs, and\n * the verdict last — the line a person scanning a deploy log reads first from\n * the bottom. The JSON contract never comes through here; `gate.ts` emits the\n * envelope from the same report, which is what keeps the two views one\n * derivation.\n */\nimport { SEVERITY_MARK, type Finding } from \"../../core/vocabulary/report.js\";\nimport type { GateReport, GateVerdict } from \"../../core/gate/report.js\";\nimport { plural } from \"../policy/format.js\";\n\nfunction printFindings(findings: Finding[]): void {\n  for (const f of findings) {\n    console.log(`  ${SEVERITY_MARK[f.severity]} ${f.message}`);\n    for (const d of f.details ?? []) console.log(`    - ${d}`);\n  }\n}\n\nexport function printGate(\n  report: GateReport,\n  verdict: GateVerdict,\n  summary: { errors: number; warnings: number },\n): void {\n  console.log(`gate — ${report.service} (a query over recorded evidence; it executes nothing)`);\n\n  const check = (name: (typeof report.checks)[number][\"check\"]): Finding[] =>\n    report.checks.find((c) => c.check === name)?.findings ?? [];\n\n  console.log(`\\npartners — landscape ${report.landscape}`);\n  for (const p of report.partners) {\n    const rung = p.external ? \"external\" : (p.maturity ?? \"no services/ directory\");\n    console.log(`  ${p.service} · ${rung} · ${p.role} · ${p.via.join(\", \")}`);\n  }\n  if (report.partners.length === 0 && report.landscape === \"read\") {\n    console.log(\"  (the landscape draws no join into or out of this service)\");\n  }\n  printFindings(check(\"partners\"));\n\n  console.log(\"\\nfreshness\");\n  const freshness = check(\"freshness\");\n  if (freshness.length === 0) console.log(`  ${SEVERITY_MARK.ok} nothing recorded has gone stale`);\n  printFindings(freshness);\n\n  console.log(\"\\nverification\");\n  for (const f of report.features) {\n    const attested = f.attested > 0 ? `, ${f.attested} on an agent's word` : \"\";\n    console.log(`  ${f.id} · ${f.verdict} (${f.state}; ${f.confirmed}/${f.claims} confirmed${attested})`);\n  }\n  if (report.features.length === 0) {\n    console.log(\"  (no active feature carries a delta for this service)\");\n  }\n  printFindings(check(\"verification\"));\n\n  console.log(\"\\ninterrupted\");\n  const interrupted = check(\"interrupted\");\n  if (interrupted.length === 0) console.log(`  ${SEVERITY_MARK.ok} no interrupted commit in the docs repo`);\n  printFindings(interrupted);\n\n  console.log(\n    `\\nverdict: ${verdict} — ${plural(summary.errors, \"error\")}, ${plural(summary.warnings, \"warning\")}` +\n      (verdict === \"pass\" && summary.warnings > 0\n        ? \" (advisory — `--strict` turns warnings into exit 1)\"\n        : \"\"),\n  );\n}\n"]}
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/gate/print.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAgB,MAAM,iCAAiC,CAAC;AAE9E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,SAAS,aAAa,CAAC,QAAmB;IACxC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,MAAkB,EAClB,OAAoB,EACpB,OAA6C;IAE7C,OAAO,CAAC,GAAG,CAAC,UAAU,MAAM,CAAC,OAAO,wDAAwD,CAAC,CAAC;IAE9F,MAAM,KAAK,GAAG,CAAC,IAA6C,EAAa,EAAE,CACzE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,EAAE,QAAQ,IAAI,EAAE,CAAC;IAE9D,OAAO,CAAC,GAAG,CAAC,0BAA0B,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,wBAAwB,CAAC,CAAC;QAChF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,MAAM,IAAI,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;QAChE,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;IAC7E,CAAC;IACD,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,aAAa,CAAC,EAAE,kCAAkC,CAAC,CAAC;IACjG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEzB,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,kDAAkD,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/G,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,aAAa,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;QAChH,kEAAkE;QAClE,0EAA0E;QAC1E,gEAAgE;QAChE,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,kBAAkB,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACnF,OAAO,CAAC,GAAG,CACT,yKAAyK,CAC1K,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,GAAG,CACT,KAAK,KAAK,IAAI;YACZ,CAAC,CAAC,wDAAwD;YAC1D,CAAC,CAAC,6CAA6C,KAAK,CAAC,GAAG,oCAAoC,CAC/F,CAAC;IACJ,CAAC;IACD,aAAa,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAErC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,aAAa,CAAC,EAAE,yCAAyC,CAAC,CAAC;IAC1G,aAAa,CAAC,WAAW,CAAC,CAAC;IAE3B,OAAO,CAAC,GAAG,CACT,cAAc,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE;QAClG,CAAC,OAAO,KAAK,MAAM,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC;YACzC,CAAC,CAAC,qDAAqD;YACvD,CAAC,CAAC,EAAE,CAAC,CACV,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The human rendering of a gate report: one block per check, the partner and\n * feature tables as data lines, findings with the shared severity glyphs, and\n * the verdict last — the line a person scanning a deploy log reads first from\n * the bottom. The JSON contract never comes through here; `gate.ts` emits the\n * envelope from the same report, which is what keeps the two views one\n * derivation.\n */\nimport { SEVERITY_MARK, type Finding } from \"../../core/vocabulary/report.js\";\nimport type { GateReport, GateVerdict } from \"../../core/gate/report.js\";\nimport { plural } from \"../policy/format.js\";\n\nfunction printFindings(findings: Finding[]): void {\n  for (const f of findings) {\n    console.log(`  ${SEVERITY_MARK[f.severity]} ${f.message}`);\n    for (const d of f.details ?? []) console.log(`    - ${d}`);\n  }\n}\n\nexport function printGate(\n  report: GateReport,\n  verdict: GateVerdict,\n  summary: { errors: number; warnings: number },\n): void {\n  console.log(`gate — ${report.service} (a query over recorded evidence; it executes nothing)`);\n\n  const check = (name: (typeof report.checks)[number][\"check\"]): Finding[] =>\n    report.checks.find((c) => c.check === name)?.findings ?? [];\n\n  console.log(`\\npartners — landscape ${report.landscape}`);\n  for (const p of report.partners) {\n    const rung = p.external ? \"external\" : (p.maturity ?? \"no services/ directory\");\n    console.log(`  ${p.service} · ${rung} · ${p.role} · ${p.via.join(\", \")}`);\n  }\n  if (report.partners.length === 0 && report.landscape === \"read\") {\n    console.log(\"  (the landscape draws no join into or out of this service)\");\n  }\n  printFindings(check(\"partners\"));\n\n  console.log(\"\\nfreshness\");\n  const freshness = check(\"freshness\");\n  if (freshness.length === 0) console.log(`  ${SEVERITY_MARK.ok} nothing recorded has gone stale`);\n  printFindings(freshness);\n\n  // Under --since the heading names the bound, so a deploy log says which\n  // shipped features it graded; without it, that only in-flight ones were.\n  const since = report.since;\n  console.log(since === null ? \"\\nverification\" : `\\nverification — in flight, and archived since ${since.ref}`);\n  for (const f of report.features) {\n    const attested = f.attested > 0 ? `, ${f.attested} on an agent's word` : \"\";\n    const shipped = f.archived === true ? \" · archived\" : \"\";\n    console.log(`  ${f.id} · ${f.verdict} (${f.state}; ${f.confirmed}/${f.claims} confirmed${attested})${shipped}`);\n    // A record read as frozen history because its archive captured no\n    // checklist (`checklistAtArchive: null`) was not held to the feature that\n    // shipped; a deploy log must not read that row as one that was.\n    if (f.archived === true && f.checklistAtArchive === null && f.state === \"recorded\") {\n      console.log(\n        \"    its archive captured no checklist (archived by an older loam), so whether the record still answered the feature when it shipped is unknown — read as frozen history\",\n      );\n    }\n  }\n  if (report.features.length === 0) {\n    console.log(\n      since === null\n        ? \"  (no active feature carries a delta for this service)\"\n        : `  (no feature in flight or archived since ${since.ref} carries a delta for this service)`,\n    );\n  }\n  printFindings(check(\"verification\"));\n\n  console.log(\"\\ninterrupted\");\n  const interrupted = check(\"interrupted\");\n  if (interrupted.length === 0) console.log(`  ${SEVERITY_MARK.ok} no interrupted commit in the docs repo`);\n  printFindings(interrupted);\n\n  console.log(\n    `\\nverdict: ${verdict} — ${plural(summary.errors, \"error\")}, ${plural(summary.warnings, \"warning\")}` +\n      (verdict === \"pass\" && summary.warnings > 0\n        ? \" (advisory — `--strict` turns warnings into exit 1)\"\n        : \"\"),\n  );\n}\n"]}

package/dist/commands/gherkin/commit.js

@@ -13,41 +13,12 @@ import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { quietRmdir, rollbackStaged, stageWrites } from "../../core/staging/commit.js";
-import { COMMIT_INTENT, InterruptedCommitError } from "../../core/staging/interrupted.js";
-import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { COMMIT_INTENT } from "../../core/staging/interrupted.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../core/staging/txn/transaction.js";
 import {} from "../../core/staging/writes.js";
 import {} from "./reconcile.js";
-/**
- * Roll a predecessor's interrupted emission forward before ANYTHING reads the
- * suite — reconcile grades the very bytes a half-commit corrupts. Cheap when
- * there is nothing to do: no journal, no lock, no I/O beyond one existsSync.
- */
-export async function recoverEmissionRoot(root) {
-    if (!existsSync(join(root, COMMIT_INTENT)))
-        return { ok: true, recovered: null };
-    let release;
-    try {
-        release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (err instanceof DocsBusyError)
-            return { ok: false, code: "docs-busy", message: err.message };
-        throw err;
-    }
-    try {
-        return { ok: true, recovered: await recoverInterruptedCommit(root) };
-    }
-    catch (err) {
-        if (err instanceof InterruptedCommitError)
-            return { ok: false, code: "commit-interrupted", message: err.message };
-        throw err;
-    }
-    finally {
-        await release();
-    }
-}
 /**
  * Stage, compare, journal, swap. The compare is against the bytes RECONCILE
  * read: a `.feature` that changed (or appeared) between the grading and this
@@ -60,32 +31,20 @@ export async function commitEmission(spec, plan) {
     // The lock file lives in the root, so the root must exist first. If the
     // commit then fails having created it, the empty directory is removed
     // again — an empty loam/ flips the repo into "opted in" and tells
-    // `loam validate` the whole living suite is missing.
+    // `loam validate` the whole living suite is missing. A window that does not
+    // open is such a failure too, so the removal sits in the one `finally`
+    // every path out of here takes.
     const rootExisted = existsSync(root);
     await mkdir(root, { recursive: true });
-    let release;
-    try {
-        release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (!rootExisted)
-            await quietRmdir(root);
-        if (err instanceof DocsBusyError)
-            return { ok: false, code: "docs-busy", message: err.message };
-        throw err;
-    }
+    let release = null;
     try {
         // A writer can have crashed between the command-start recovery and this
         // window; the re-check is one existsSync when nothing happened.
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(root);
-        }
-        catch (err) {
-            if (err instanceof InterruptedCommitError)
-                return { ok: false, code: "commit-interrupted", message: err.message };
-            throw err;
-        }
+        const opened = await openCommitWindow(root, LOCK_WAIT_MS);
+        if (!opened.ok)
+            return opened;
+        release = opened.release;
+        const { recovered } = opened;
         const planned = [
             // A "written" row was graded against an ABSENT file, so its create is
             // exclusive: a file appearing after planning loses the link(2) race and
@@ -138,7 +97,7 @@ export async function commitEmission(spec, plan) {
         return { ok: true, recovered };
     }
     finally {
-        await release();
+        await release?.();
         if (!rootExisted && !existsSync(join(root, COMMIT_INTENT)))
             await quietRmdir(root);
     }