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

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":"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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 * 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":"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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  // 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);
     }

package/dist/commands/gherkin/commit.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/gherkin/commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,EAAE,aAAa,EAAuB,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC/G,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAA8B,MAAM,gBAAgB,CAAC;AAM5D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAY;IACpD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACjF,IAAI,OAA4B,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,sBAAsB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,aAAa;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAChG,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,sBAAsB;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAClH,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAqD,EACrD,IAAuE;IAEvE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACtC,wEAAwE;IACxE,sEAAsE;IACtE,kEAAkE;IAClE,qDAAqD;IACrD,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,OAA4B,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,sBAAsB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,WAAW;YAAE,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,GAAG,YAAY,aAAa;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAChG,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,wEAAwE;QACxE,gEAAgE;QAChE,IAAI,SAAgC,CAAC;QACrC,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,wBAAwB,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,sBAAsB;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;YAClH,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,GAAmB;YAC9B,sEAAsE;YACtE,wEAAwE;YACxE,8CAA8C;YAC9C,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgB,EAAE,CACrC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CACtH;YACD,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;SAC5E,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;QAE1C,uEAAuE;QACvE,oEAAoE;QACpE,qEAAqE;QACrE,0BAA0B;QAC1B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QACpF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM;aACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACZ,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrC,OAAO,GAAG,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3E,CAAC,CAAC;aACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,cAAc;gBACpB,OAAO,EACL,6DAA6D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAChF,qFAAqF;aACxF,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,YAAY,CAClC;YACE,IAAI;YACJ,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,cAAc;YACpF,MAAM,EAAE,OAAO;SAChB,EACD,MAAM,EACN,SAAS,CACV,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,SAAS,CAAC,KAAK;gBACpB,CAAC,CAAC;oBACE,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,cAAc;oBACpB,OAAO,EACL,qFAAqF;wBACrF,GAAG,SAAS,CAAC,OAAO,2DAA2D;iBAClF;gBACH,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;QACtE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;QAChB,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAAE,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACrF,CAAC;AACH,CAAC","sourcesContent":["/**\n * The emission's commit window: lock the owned root, recover a predecessor,\n * stage every write and delete, prove the tree still matches what reconcile\n * graded, and land it through the journaled transaction.\n *\n * Split from gherkin.ts so the lock's extent is visible in the code shape,\n * exactly as vouch's commitStamp is — and because this is the writer the\n * roadmap named: a kill inside the old write/delete loop left a half-old,\n * half-new suite with no marker, in the one repo (the service's own) where\n * nothing else of loam's ever looked.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { quietRmdir, rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { COMMIT_INTENT, type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type ActionRow, type Scope } from \"./reconcile.js\";\n\nexport type EmissionCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | { ok: false; code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * Roll a predecessor's interrupted emission forward before ANYTHING reads the\n * suite — reconcile grades the very bytes a half-commit corrupts. Cheap when\n * there is nothing to do: no journal, no lock, no I/O beyond one existsSync.\n */\nexport async function recoverEmissionRoot(root: string): Promise<EmissionCommit> {\n  if (!existsSync(join(root, COMMIT_INTENT))) return { ok: true, recovered: null };\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);\n  } catch (err) {\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    return { ok: true, recovered: await recoverInterruptedCommit(root) };\n  } catch (err) {\n    if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n    throw err;\n  } finally {\n    await release();\n  }\n}\n\n/**\n * Stage, compare, journal, swap. The compare is against the bytes RECONCILE\n * read: a `.feature` that changed (or appeared) between the grading and this\n * commit is refused by name, never buried — the suite is code somebody may be\n * editing, and \"refused, not buried\" is the no-clobber rule the roadmap\n * spells for exactly this writer.\n */\nexport async function commitEmission(\n  spec: { root: string; service: string; scope: Scope },\n  plan: { writes: ActionRow[]; orphans: { path: string; raw: Buffer }[] },\n): Promise<EmissionCommit> {\n  const { root, service, scope } = spec;\n  // The lock file lives in the root, so the root must exist first. If the\n  // commit then fails having created it, the empty directory is removed\n  // again — an empty loam/ flips the repo into \"opted in\" and tells\n  // `loam validate` the whole living suite is missing.\n  const rootExisted = existsSync(root);\n  await mkdir(root, { recursive: true });\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLockWaiting(root, LOCK_WAIT_MS);\n  } catch (err) {\n    if (!rootExisted) await quietRmdir(root);\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    // A writer can have crashed between the command-start recovery and this\n    // window; the re-check is one existsSync when nothing happened.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(root);\n    } catch (err) {\n      if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n      throw err;\n    }\n\n    const planned: PlannedWrite[] = [\n      // A \"written\" row was graded against an ABSENT file, so its create is\n      // exclusive: a file appearing after planning loses the link(2) race and\n      // the run refuses rather than overwriting it.\n      ...plan.writes.map((a): PlannedWrite =>\n        a.action === \"written\" ? { path: a.path, content: a.content, exclusive: true } : { path: a.path, content: a.content },\n      ),\n      ...plan.orphans.map((o): PlannedWrite => ({ path: o.path, content: null })),\n    ];\n    const staged = await stageWrites(planned);\n\n    // The bytes reconcile graded must be the bytes this commit replaces or\n    // deletes. `swapStaged` re-checks against ITS read just before each\n    // rename; this compare closes the other half of the window, from the\n    // grading to the staging.\n    const graded = new Map<string, Buffer>();\n    for (const a of plan.writes) if (a.action === \"replaced\") graded.set(a.path, a.raw);\n    for (const o of plan.orphans) graded.set(o.path, o.raw);\n    const moved = staged\n      .filter((s) => {\n        const raw = graded.get(s.write.path);\n        return raw !== undefined && (s.before === null || !s.before.equals(raw));\n      })\n      .map((s) => s.write.path);\n    if (moved.length > 0) {\n      await rollbackStaged(staged);\n      return {\n        ok: false,\n        code: \"merge-failed\",\n        message:\n          `the suite changed while this emission was being planned — ${moved.join(\", \")} ` +\n          `no longer holds the bytes the plan was graded against. Nothing was written: re-run.`,\n      };\n    }\n\n    const committed = await commitStaged(\n      {\n        root,\n        command: \"gherkin\",\n        rerun: scope.mode === \"feature\" ? `loam gherkin ${scope.featureId}` : \"loam gherkin\",\n        target: service,\n      },\n      staged,\n      \"emitted\",\n    );\n    if (!committed.ok) {\n      return committed.raced\n        ? {\n            ok: false,\n            code: \"merge-failed\",\n            message:\n              \"a .feature file appeared after planning and the emission refused to overwrite it — \" +\n              `${committed.message}. Nothing else was written: re-run to grade the new file.`,\n          }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await release();\n    if (!rootExisted && !existsSync(join(root, COMMIT_INTENT))) await quietRmdir(root);\n  }\n}\n\n"]}
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/gherkin/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The emission's commit window: lock the owned root, recover a predecessor,\n * stage every write and delete, prove the tree still matches what reconcile\n * graded, and land it through the journaled transaction.\n *\n * Split from gherkin.ts so the lock's extent is visible in the code shape,\n * exactly as vouch's commitStamp is — and because this is the writer the\n * roadmap named: a kill inside the old write/delete loop left a half-old,\n * half-new suite with no marker, in the one repo (the service's own) where\n * nothing else of loam's ever looked.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { quietRmdir, rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { COMMIT_INTENT, type CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type ActionRow, type Scope } from \"./reconcile.js\";\n\nexport type EmissionCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | { ok: false; code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * Stage, compare, journal, swap. The compare is against the bytes RECONCILE\n * read: a `.feature` that changed (or appeared) between the grading and this\n * commit is refused by name, never buried — the suite is code somebody may be\n * editing, and \"refused, not buried\" is the no-clobber rule the roadmap\n * spells for exactly this writer.\n */\nexport async function commitEmission(\n  spec: { root: string; service: string; scope: Scope },\n  plan: { writes: ActionRow[]; orphans: { path: string; raw: Buffer }[] },\n): Promise<EmissionCommit> {\n  const { root, service, scope } = spec;\n  // The lock file lives in the root, so the root must exist first. If the\n  // commit then fails having created it, the empty directory is removed\n  // again — an empty loam/ flips the repo into \"opted in\" and tells\n  // `loam validate` the whole living suite is missing. A window that does not\n  // open is such a failure too, so the removal sits in the one `finally`\n  // every path out of here takes.\n  const rootExisted = existsSync(root);\n  await mkdir(root, { recursive: true });\n  let release: (() => Promise<void>) | null = null;\n  try {\n    // A writer can have crashed between the command-start recovery and this\n    // window; the re-check is one existsSync when nothing happened.\n    const opened = await openCommitWindow(root, LOCK_WAIT_MS);\n    if (!opened.ok) return opened;\n    release = opened.release;\n    const { recovered } = opened;\n\n    const planned: PlannedWrite[] = [\n      // A \"written\" row was graded against an ABSENT file, so its create is\n      // exclusive: a file appearing after planning loses the link(2) race and\n      // the run refuses rather than overwriting it.\n      ...plan.writes.map((a): PlannedWrite =>\n        a.action === \"written\" ? { path: a.path, content: a.content, exclusive: true } : { path: a.path, content: a.content },\n      ),\n      ...plan.orphans.map((o): PlannedWrite => ({ path: o.path, content: null })),\n    ];\n    const staged = await stageWrites(planned);\n\n    // The bytes reconcile graded must be the bytes this commit replaces or\n    // deletes. `swapStaged` re-checks against ITS read just before each\n    // rename; this compare closes the other half of the window, from the\n    // grading to the staging.\n    const graded = new Map<string, Buffer>();\n    for (const a of plan.writes) if (a.action === \"replaced\") graded.set(a.path, a.raw);\n    for (const o of plan.orphans) graded.set(o.path, o.raw);\n    const moved = staged\n      .filter((s) => {\n        const raw = graded.get(s.write.path);\n        return raw !== undefined && (s.before === null || !s.before.equals(raw));\n      })\n      .map((s) => s.write.path);\n    if (moved.length > 0) {\n      await rollbackStaged(staged);\n      return {\n        ok: false,\n        code: \"merge-failed\",\n        message:\n          `the suite changed while this emission was being planned — ${moved.join(\", \")} ` +\n          `no longer holds the bytes the plan was graded against. Nothing was written: re-run.`,\n      };\n    }\n\n    const committed = await commitStaged(\n      {\n        root,\n        command: \"gherkin\",\n        rerun: scope.mode === \"feature\" ? `loam gherkin ${scope.featureId}` : \"loam gherkin\",\n        target: service,\n      },\n      staged,\n      \"emitted\",\n    );\n    if (!committed.ok) {\n      return committed.raced\n        ? {\n            ok: false,\n            code: \"merge-failed\",\n            message:\n              \"a .feature file appeared after planning and the emission refused to overwrite it — \" +\n              `${committed.message}. Nothing else was written: re-run to grade the new file.`,\n          }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await release?.();\n    if (!rootExisted && !existsSync(join(root, COMMIT_INTENT))) await quietRmdir(root);\n  }\n}\n\n"]}

package/dist/commands/gherkin/gherkin.js

@@ -1,9 +1,8 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { relative } from "node:path";
-import { loadConfig } from "../../core/envelope/config.js";
 import { decodeDocument, NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
-import { emitJson, emitJsonError, fail, NO_SERVICE_MESSAGE, reportNoConfig, } from "../../core/envelope/json.js";
+import { configOrRefuse, emitJson, emitJsonError, fail, NO_SERVICE_MESSAGE, } from "../../core/envelope/json.js";
 import { featureSpecPaths, SPEC_AXES } from "../../core/repo/paths.js";
 import { locateServicePaths } from "../../core/repo/service-target.js";
 import { listFeatures, missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
@@ -13,7 +12,8 @@ import { axisLabel, planEmission } from "../../core/gherkin/emit.js";
 import { gherkinRoot } from "../../core/gherkin/stamp.js";
 import { LOAM_VERSION } from "../../core/envelope/version.js";
 import { UnsafePathError } from "../../core/kernel/path-safety.js";
-import { commitEmission, recoverEmissionRoot } from "./commit.js";
+import { recoverIfJournaled } from "../../core/staging/recovery/recover.js";
+import { commitEmission } from "./commit.js";
 import { reconcile } from "./reconcile.js";
 import { render } from "./render.js";
 import { sayRecovered } from "../policy/format.js";
@@ -28,12 +28,9 @@ export function registerGherkin(program) {
         .action(async (featureArg, opts) => {
         const json = opts.json === true;
         const dryRun = opts.dryRun === 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 service = opts.service ?? config.service;
         if (service === undefined) {
             return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
@@ -83,8 +80,10 @@ export function registerGherkin(program) {
         // name a feature that has since ARCHIVED, whose recovery must still
         // work. `new` fixed the same ordering and documented it; refusing
         // unknown-target over a wedged root left doctor printing a repair that
-        // could never run.
-        const early = await recoverEmissionRoot(root);
+        // could never run. The lock is the emission root's own, given straight
+        // back: the slow half below runs unlocked, and `commitEmission` retakes
+        // it for the commit window.
+        const early = await recoverIfJournaled(root);
         if (!early.ok)
             return fail(json, early.code, early.message);
         let recovered = early.recovered;
@@ -146,11 +145,8 @@ export function registerGherkin(program) {
             featureTag: scope.mode === "feature" ? scope.featureId : undefined,
             version: LOAM_VERSION,
         });
-        // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns
-        // only its own emissions: stamped files carrying this feature's tag whose
-        // file is no longer in the plan (a requirement renamed or dropped).
-        // `Set<string>`, not the ids' own brand: this set answers membership
-        // questions for tags read out of .feature files — document text.
+        // `Set<string>`, not the ids' own brand — core/gherkin/stale.ts's reason:
+        // it answers membership for tags read out of .feature files.
         const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));
         let reconciled;
         try {
@@ -162,11 +158,8 @@ export function registerGherkin(program) {
             return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}.`);
         }
         const { actions, orphans, conflicts } = reconciled;
-        // All or nothing: one conflicting file refuses the whole emission, so a
-        // half-written suite can never be the state an agent has to reason about.
-        // Only a feature run can conflict — living mode keeps the in-flight file
-        // rather than refusing — and standing inside that scope is also how the
-        // message names the feature without asserting there is one.
+        // All or nothing, and only a feature run can conflict — `./reconcile.ts`
+        // records why, where the conflicts are collected.
         if (scope.mode === "feature" && conflicts.length > 0) {
             const detail = conflicts
                 .map((c) => `${rel(c.path)} is @${c.owners.join(" @")} (requirement '${c.requirement.name}')`)
@@ -216,6 +209,29 @@ export function registerGherkin(program) {
                     // emission), not the emission that was withheld.
                     scenarios: a.action === "kept" ? a.kept.scenarios.length : a.digests.length,
                     digests: a.action === "kept" ? a.kept.scenarios.map((s) => s.digest) : a.digests,
+                    // `digests` is a bare array and `scenarios` a bare count, so the one
+                    // thing a consumer actually needs — which stamp belongs to which
+                    // scenario — was the one thing this payload could not say, and the
+                    // only way to learn it was to go read the generated file back off
+                    // disk. `stamped` is that pairing; `digests` stays exactly as it was
+                    // beside it, because the envelope permits adding a key and never
+                    // changing one (core/envelope/json.ts).
+                    //
+                    // The positional zip is sound because `renderFeature`
+                    // (core/gherkin/emit.ts) pushes exactly one digest per scenario, in
+                    // scenario order, inside the same loop that writes the `Scenario:`
+                    // line — but it is written to FAIL CLOSED rather than to assert
+                    // that: a scenario with no digest opposite it drops out of the
+                    // pairing instead of being published with a null one. A kept row
+                    // reads its pairs off the file that is really on disk, because its
+                    // numbers describe the in-flight emission that stayed, not the one
+                    // that was withheld.
+                    stamped: a.action === "kept"
+                        ? a.kept.scenarios.map((s) => ({ scenario: s.name, digest: s.digest }))
+                        : a.requirement.scenarios.flatMap((s, i) => {
+                            const digest = a.digests[i];
+                            return digest === undefined ? [] : [{ scenario: s.name, digest }];
+                        }),
                     ...(a.action === "kept"
                         ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }
                         : {

package/dist/commands/gherkin/gherkin.js.map

@@ -1 +1 @@
-{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../../../src/commands/gherkin/gherkin.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam gherkin` — the third writer in the CLI (after archive and vouch), and\n * the only one that writes into the SERVICE repo, never the docs repo: the\n * docs state what must be true, the tests live with the code that makes it so.\n *\n * Two scopes, one emitter. `loam gherkin <FEAT>` emits the feature's ADDED and\n * MODIFIED requirements for this service — both spec axes — as the acceptance\n * skeleton to implement against, each file tagged with the feature id.\n * `loam gherkin --service <id>` (no feature) emits the full living suite from\n * spec.md + arch.spec.md: the regression skeleton a legacy service gets at\n * adoption. Either way the output is `<gherkinDir>/loam/` inside this repo,\n * a directory loam owns outright: the scope's files are rewritten, the scope's\n * orphans are deleted (and reported), and nothing outside `loam/` is touched —\n * except that a living run neither deletes NOR overwrites a file tagged with a\n * feature still in flight: it answers to that feature's delta until it\n * archives, and is reported as kept. A FEATURE run cannot keep — the file it\n * wants holds one feature's delta — so when the file it would write belongs to\n * a different feature still in flight, the whole run refuses (`gherkin-conflict`)\n * and names the owner rather than reverting it.\n *\n * It refuses to run anywhere but the service's own repo — vouch's discipline,\n * for vouch's reason: the output lands in the repo loam is standing in, and\n * from anywhere else that repo is somebody else's.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport {\n  emitJson,\n  emitJsonError,\n  fail,\n  NO_SERVICE_MESSAGE,\n  reportNoConfig,\n} from \"../../core/envelope/json.js\";\nimport { featureSpecPaths, SPEC_AXES, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { listFeatures, missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { parseRequirements } from \"../../core/document/parse.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { axisLabel, planEmission } from \"../../core/gherkin/emit.js\";\nimport { gherkinRoot } from \"../../core/gherkin/stamp.js\";\nimport { LOAM_VERSION } from \"../../core/envelope/version.js\";\nimport { UnsafePathError } from \"../../core/kernel/path-safety.js\";\nimport { commitEmission, recoverEmissionRoot } from \"./commit.js\";\nimport { reconcile, type Scope } from \"./reconcile.js\";\nimport { render } from \"./render.js\";\nimport { sayRecovered } from \"../policy/format.js\";\n\ninterface GherkinOptions {\n  service?: string;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\nexport function registerGherkin(program: Command): void {\n  program\n    .command(\"gherkin\")\n    .argument(\"[featureId]\", \"feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite\")\n    .description(\n      \"Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/\",\n    )\n    .option(\"--service <id>\", \"service to emit for (defaults to the configured service)\")\n    .option(\n      \"--dry-run\",\n      \"print the plan (writes, replacements, deletions) and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: GherkinOptions) => {\n      const json = opts.json === true;\n      const dryRun = opts.dryRun === true;\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 service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // The emission writes into the repo loam is standing in, so it can only\n      // run where that repo is this service's — vouch's refusal, verbatim logic.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); gherkin\n      // and vouch now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd: `config.root` is the directory loam.json\n      // was actually found in, and config discovery walks upward. Taken from\n      // `process.cwd()` this emitted the whole suite into whatever directory\n      // the caller happened to stand in — `src/api/features/loam/…` inside the\n      // source tree, which the next run from the root neither finds, replaces\n      // nor deletes, and which `loam validate` grades as a suite that was never\n      // generated.\n      const repoDir = config.root ?? process.cwd();\n      let root: string;\n      try {\n        root = gherkinRoot(repoDir, config.gherkinDir);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(\n          json,\n          \"invalid-option\",\n          `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`,\n        );\n      }\n      const rel = (abs: string): string => relative(repoDir, abs).split(/[\\\\/]/).join(\"/\");\n\n      // A predecessor's interrupted emission is rolled forward before ANY\n      // read — and before the feature argument resolves: reconcile grades the\n      // very bytes a half-commit corrupts, and the journal's stored rerun may\n      // name a feature that has since ARCHIVED, whose recovery must still\n      // work. `new` fixed the same ordering and documented it; refusing\n      // unknown-target over a wedged root left doctor printing a repair that\n      // could never run.\n      const early = await recoverEmissionRoot(root);\n      if (!early.ok) return fail(json, early.code, early.message);\n      let recovered = early.recovered;\n\n      const feature =\n        featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, \"exclude\");\n      if (featureArg !== undefined && feature === null) {\n        return fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg));\n      }\n      const scope: Scope =\n        feature === null ? { mode: \"living\" } : { mode: \"feature\", featureId: feature.id };\n\n      // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —\n      // a BASE requirement is the living state quoted, a REMOVED one is being\n      // retired, and neither is behaviour anybody is about to test. Living mode\n      // takes everything the living files hold.\n      //\n      // Read through `decodeDocument`, not `readFile(…, \"utf8\")`, and refused\n      // rather than degraded: a spec.md saved as UTF-16 decodes to a document\n      // with no requirements in it, which here is not merely a wrong answer but\n      // a destructive one — an empty plan makes every existing .feature under\n      // loam/ an orphan, and a living run DELETES its orphans. The whole\n      // generated suite would go because a docs file was written by PowerShell.\n      const byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }> = [];\n      const readSpec = async (path: string): Promise<Requirement[]> =>\n        parseRequirements(decodeDocument(await readFile(path), path));\n      try {\n        if (feature !== null) {\n          // `config.service`, not `service`: the guard above proved they are\n          // the same id, and only the config's copy carries the load-time\n          // parse, so it is the pathable spelling — same as the else arm.\n          const paths = featureSpecPaths(feature.dir, config.service);\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path)\n              ? (await readSpec(path)).filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")\n              : [];\n            byAxis.push({ axis, reqs });\n          }\n        } else {\n          // The guard above proved `service` IS `config.service`; only the\n          // latter carries the load-time parse, so it is the pathable spelling.\n          const paths = await locateServicePaths(config.docsDir, config.service);\n          if (!existsSync(paths.spec)) {\n            return fail(\n              json,\n              \"unknown-target\",\n              `No living spec at ${paths.spec}. Run \\`loam adopt\\` for '${service}' first.`,\n            );\n          }\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== \"REMOVED\") : [];\n            byAxis.push({ axis, reqs });\n          }\n        }\n      } catch (err) {\n        if (!(err instanceof NotUtf8DocumentError)) throw err;\n        return fail(json, \"repository-unavailable\", `Cannot emit gherkin: ${err.message}`);\n      }\n\n      // `service` is not decoration: it salts every `@loam-digest-…` stamp, and\n      // it is the same string `loam verify` files the matching claims under.\n      const plan = planEmission(byAxis, {\n        service,\n        featureTag: scope.mode === \"feature\" ? scope.featureId : undefined,\n        version: LOAM_VERSION,\n      });\n\n      // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns\n      // only its own emissions: stamped files carrying this feature's tag whose\n      // file is no longer in the plan (a requirement renamed or dropped).\n\n      // `Set<string>`, not the ids' own brand: this set answers membership\n      // questions for tags read out of .feature files — document text.\n      const activeIds = new Set<string>((await listFeatures(config.docsDir)).map((f) => f.id));\n      let reconciled;\n      try {\n        reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(json, \"invalid-option\", `Cannot emit Gherkin: ${err.message}.`);\n      }\n      const { actions, orphans, conflicts } = reconciled;\n\n      // All or nothing: one conflicting file refuses the whole emission, so a\n      // half-written suite can never be the state an agent has to reason about.\n      // Only a feature run can conflict — living mode keeps the in-flight file\n      // rather than refusing — and standing inside that scope is also how the\n      // message names the feature without asserting there is one.\n      if (scope.mode === \"feature\" && conflicts.length > 0) {\n        const detail = conflicts\n          .map((c) => `${rel(c.path)} is @${c.owners.join(\" @\")} (requirement '${c.requirement.name}')`)\n          .join(\"; \");\n        const message =\n          `Cannot emit gherkin for ${scope.featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +\n          `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \\`loam verify --results\\` matches on. ` +\n          `Archive (or abandon) the owning feature first, or rename the requirement in ${scope.featureId}'s delta so the two stop sharing a file name.`;\n        if (json) {\n          emitJsonError(\"gherkin-conflict\", message, {\n            conflicts: conflicts.map((c) => ({\n              path: rel(c.path),\n              action: \"conflict\",\n              requirement: c.requirement.name,\n              inFlight: c.owners,\n            })),\n          });\n          return;\n        }\n        return fail(json, \"gherkin-conflict\", message);\n      }\n\n      const writes = actions.filter((a) => a.action !== \"kept\");\n\n      if (!dryRun && (writes.length > 0 || orphans.length > 0)) {\n        // The commit window: locked, journaled, compared against the bytes\n        // reconcile graded. A zero-op run takes no lock and creates no root —\n        // an emission with nothing to emit must not flip the repo into\n        // \"opted in\", where an empty loam/ tells `loam validate` the whole\n        // living suite is missing.\n        const committed = await commitEmission({ root, service, scope }, { writes, orphans });\n        if (!committed.ok) return fail(json, committed.code, committed.message);\n        recovered = committed.recovered ?? recovered;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"gherkin\",\n          mode: scope.mode,\n          ...(scope.mode === \"feature\" ? { feature: scope.featureId } : {}),\n          service,\n          root: rel(root),\n          written: !dryRun,\n          files: actions.map((a) => ({\n            path: rel(a.path),\n            action: a.action,\n            axis: axisLabel(a.axis),\n            requirement: a.requirement.name,\n            // A kept file's numbers describe what STAYS on disk (the in-flight\n            // emission), not the emission that was withheld.\n            scenarios: a.action === \"kept\" ? a.kept.scenarios.length : a.digests.length,\n            digests: a.action === \"kept\" ? a.kept.scenarios.map((s) => s.digest) : a.digests,\n            ...(a.action === \"kept\"\n              ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }\n              : {\n                  stepless: a.stepless,\n                  malformedExamples: a.malformedExamples,\n                  strandedBlocks: a.strandedBlocks,\n                }),\n          })),\n          deleted: orphans.map((o) => rel(o.path)),\n          ...(recovered === null ? {} : { recovered }),\n        });\n        return;\n      }\n\n      if (recovered !== null) console.log(`${sayRecovered(recovered)}\\n`);\n      render(actions, {\n        service,\n        root: rel(root),\n        absRoot: root,\n        featureId: scope.mode === \"feature\" ? scope.featureId : null,\n        dryRun,\n        activeIds,\n        writes: writes.length,\n        orphans: orphans.map((o) => o.path),\n      });\n    });\n}\n"]}
+{"version":3,"file":"gherkin.js","sourceRoot":"","sources":["../../../src/commands/gherkin/gherkin.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam gherkin` — the third writer in the CLI (after archive and vouch), and\n * the only one that writes into the SERVICE repo, never the docs repo: the\n * docs state what must be true, the tests live with the code that makes it so.\n *\n * Two scopes, one emitter. `loam gherkin <FEAT>` emits the feature's ADDED and\n * MODIFIED requirements for this service — both spec axes — as the acceptance\n * skeleton to implement against, each file tagged with the feature id.\n * `loam gherkin --service <id>` (no feature) emits the full living suite from\n * spec.md + arch.spec.md: the regression skeleton a legacy service gets at\n * adoption. Either way the output is `<gherkinDir>/loam/` inside this repo,\n * a directory loam owns outright: the scope's files are rewritten, the scope's\n * orphans are deleted (and reported), and nothing outside `loam/` is touched —\n * except that a living run neither deletes NOR overwrites a file tagged with a\n * feature still in flight: it answers to that feature's delta until it\n * archives, and is reported as kept. A FEATURE run cannot keep — the file it\n * wants holds one feature's delta — so when the file it would write belongs to\n * a different feature still in flight, the whole run refuses (`gherkin-conflict`)\n * and names the owner rather than reverting it.\n *\n * It refuses to run anywhere but the service's own repo — vouch's discipline,\n * for vouch's reason: the output lands in the repo loam is standing in, and\n * from anywhere else that repo is somebody else's.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport {\n  configOrRefuse,\n  emitJson,\n  emitJsonError,\n  fail,\n  NO_SERVICE_MESSAGE,\n} from \"../../core/envelope/json.js\";\nimport { featureSpecPaths, SPEC_AXES, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { listFeatures, missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { parseRequirements } from \"../../core/document/parse.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { axisLabel, planEmission } from \"../../core/gherkin/emit.js\";\nimport { gherkinRoot } from \"../../core/gherkin/stamp.js\";\nimport { LOAM_VERSION } from \"../../core/envelope/version.js\";\nimport { UnsafePathError } from \"../../core/kernel/path-safety.js\";\nimport { recoverIfJournaled } from \"../../core/staging/recovery/recover.js\";\nimport { commitEmission } from \"./commit.js\";\nimport { reconcile, type Scope } from \"./reconcile.js\";\nimport { render } from \"./render.js\";\nimport { sayRecovered } from \"../policy/format.js\";\n\ninterface GherkinOptions {\n  service?: string;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\nexport function registerGherkin(program: Command): void {\n  program\n    .command(\"gherkin\")\n    .argument(\"[featureId]\", \"feature id — emit its ADDED/MODIFIED requirements; omit for the full living suite\")\n    .description(\n      \"Emit Gherkin .feature files from spec scenarios into this service repo's <gherkinDir>/loam/\",\n    )\n    .option(\"--service <id>\", \"service to emit for (defaults to the configured service)\")\n    .option(\n      \"--dry-run\",\n      \"print the plan (writes, replacements, deletions) and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: GherkinOptions) => {\n      const json = opts.json === true;\n      const dryRun = opts.dryRun === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // The emission writes into the repo loam is standing in, so it can only\n      // run where that repo is this service's — vouch's refusal, verbatim logic.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); gherkin\n      // and vouch now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot emit gherkin for '${service}' from here: this is not a service repo. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot emit gherkin for '${service}' from here: this repo is '${config.service}'. Generated .feature files land in the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd: `config.root` is the directory loam.json\n      // was actually found in, and config discovery walks upward. Taken from\n      // `process.cwd()` this emitted the whole suite into whatever directory\n      // the caller happened to stand in — `src/api/features/loam/…` inside the\n      // source tree, which the next run from the root neither finds, replaces\n      // nor deletes, and which `loam validate` grades as a suite that was never\n      // generated.\n      const repoDir = config.root ?? process.cwd();\n      let root: string;\n      try {\n        root = gherkinRoot(repoDir, config.gherkinDir);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(\n          json,\n          \"invalid-option\",\n          `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`,\n        );\n      }\n      const rel = (abs: string): string => relative(repoDir, abs).split(/[\\\\/]/).join(\"/\");\n\n      // A predecessor's interrupted emission is rolled forward before ANY\n      // read — and before the feature argument resolves: reconcile grades the\n      // very bytes a half-commit corrupts, and the journal's stored rerun may\n      // name a feature that has since ARCHIVED, whose recovery must still\n      // work. `new` fixed the same ordering and documented it; refusing\n      // unknown-target over a wedged root left doctor printing a repair that\n      // could never run. The lock is the emission root's own, given straight\n      // back: the slow half below runs unlocked, and `commitEmission` retakes\n      // it for the commit window.\n      const early = await recoverIfJournaled(root);\n      if (!early.ok) return fail(json, early.code, early.message);\n      let recovered = early.recovered;\n\n      const feature =\n        featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, \"exclude\");\n      if (featureArg !== undefined && feature === null) {\n        return fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg));\n      }\n      const scope: Scope =\n        feature === null ? { mode: \"living\" } : { mode: \"feature\", featureId: feature.id };\n\n      // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —\n      // a BASE requirement is the living state quoted, a REMOVED one is being\n      // retired, and neither is behaviour anybody is about to test. Living mode\n      // takes everything the living files hold.\n      //\n      // Read through `decodeDocument`, not `readFile(…, \"utf8\")`, and refused\n      // rather than degraded: a spec.md saved as UTF-16 decodes to a document\n      // with no requirements in it, which here is not merely a wrong answer but\n      // a destructive one — an empty plan makes every existing .feature under\n      // loam/ an orphan, and a living run DELETES its orphans. The whole\n      // generated suite would go because a docs file was written by PowerShell.\n      const byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }> = [];\n      const readSpec = async (path: string): Promise<Requirement[]> =>\n        parseRequirements(decodeDocument(await readFile(path), path));\n      try {\n        if (feature !== null) {\n          // `config.service`, not `service`: the guard above proved they are\n          // the same id, and only the config's copy carries the load-time\n          // parse, so it is the pathable spelling — same as the else arm.\n          const paths = featureSpecPaths(feature.dir, config.service);\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path)\n              ? (await readSpec(path)).filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")\n              : [];\n            byAxis.push({ axis, reqs });\n          }\n        } else {\n          // The guard above proved `service` IS `config.service`; only the\n          // latter carries the load-time parse, so it is the pathable spelling.\n          const paths = await locateServicePaths(config.docsDir, config.service);\n          if (!existsSync(paths.spec)) {\n            return fail(\n              json,\n              \"unknown-target\",\n              `No living spec at ${paths.spec}. Run \\`loam adopt\\` for '${service}' first.`,\n            );\n          }\n          for (const axis of SPEC_AXES) {\n            const path = paths[axis.key];\n            const reqs = existsSync(path) ? (await readSpec(path)).filter((r) => r.kind !== \"REMOVED\") : [];\n            byAxis.push({ axis, reqs });\n          }\n        }\n      } catch (err) {\n        if (!(err instanceof NotUtf8DocumentError)) throw err;\n        return fail(json, \"repository-unavailable\", `Cannot emit gherkin: ${err.message}`);\n      }\n\n      // `service` is not decoration: it salts every `@loam-digest-…` stamp, and\n      // it is the same string `loam verify` files the matching claims under.\n      const plan = planEmission(byAxis, {\n        service,\n        featureTag: scope.mode === \"feature\" ? scope.featureId : undefined,\n        version: LOAM_VERSION,\n      });\n\n      // `Set<string>`, not the ids' own brand — core/gherkin/stale.ts's reason:\n      // it answers membership for tags read out of .feature files.\n      const activeIds = new Set<string>((await listFeatures(config.docsDir)).map((f) => f.id));\n      let reconciled;\n      try {\n        reconciled = await reconcile(plan, { root, repoDir }, scope, activeIds);\n      } catch (err) {\n        if (!(err instanceof UnsafePathError)) throw err;\n        return fail(json, \"invalid-option\", `Cannot emit Gherkin: ${err.message}.`);\n      }\n      const { actions, orphans, conflicts } = reconciled;\n\n      // All or nothing, and only a feature run can conflict — `./reconcile.ts`\n      // records why, where the conflicts are collected.\n      if (scope.mode === \"feature\" && conflicts.length > 0) {\n        const detail = conflicts\n          .map((c) => `${rel(c.path)} is @${c.owners.join(\" @\")} (requirement '${c.requirement.name}')`)\n          .join(\"; \");\n        const message =\n          `Cannot emit gherkin for ${scope.featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +\n          `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \\`loam verify --results\\` matches on. ` +\n          `Archive (or abandon) the owning feature first, or rename the requirement in ${scope.featureId}'s delta so the two stop sharing a file name.`;\n        if (json) {\n          emitJsonError(\"gherkin-conflict\", message, {\n            conflicts: conflicts.map((c) => ({\n              path: rel(c.path),\n              action: \"conflict\",\n              requirement: c.requirement.name,\n              inFlight: c.owners,\n            })),\n          });\n          return;\n        }\n        return fail(json, \"gherkin-conflict\", message);\n      }\n\n      const writes = actions.filter((a) => a.action !== \"kept\");\n\n      if (!dryRun && (writes.length > 0 || orphans.length > 0)) {\n        // The commit window: locked, journaled, compared against the bytes\n        // reconcile graded. A zero-op run takes no lock and creates no root —\n        // an emission with nothing to emit must not flip the repo into\n        // \"opted in\", where an empty loam/ tells `loam validate` the whole\n        // living suite is missing.\n        const committed = await commitEmission({ root, service, scope }, { writes, orphans });\n        if (!committed.ok) return fail(json, committed.code, committed.message);\n        recovered = committed.recovered ?? recovered;\n      }\n\n      if (json) {\n        emitJson({\n          command: \"gherkin\",\n          mode: scope.mode,\n          ...(scope.mode === \"feature\" ? { feature: scope.featureId } : {}),\n          service,\n          root: rel(root),\n          written: !dryRun,\n          files: actions.map((a) => ({\n            path: rel(a.path),\n            action: a.action,\n            axis: axisLabel(a.axis),\n            requirement: a.requirement.name,\n            // A kept file's numbers describe what STAYS on disk (the in-flight\n            // emission), not the emission that was withheld.\n            scenarios: a.action === \"kept\" ? a.kept.scenarios.length : a.digests.length,\n            digests: a.action === \"kept\" ? a.kept.scenarios.map((s) => s.digest) : a.digests,\n            // `digests` is a bare array and `scenarios` a bare count, so the one\n            // thing a consumer actually needs — which stamp belongs to which\n            // scenario — was the one thing this payload could not say, and the\n            // only way to learn it was to go read the generated file back off\n            // disk. `stamped` is that pairing; `digests` stays exactly as it was\n            // beside it, because the envelope permits adding a key and never\n            // changing one (core/envelope/json.ts).\n            //\n            // The positional zip is sound because `renderFeature`\n            // (core/gherkin/emit.ts) pushes exactly one digest per scenario, in\n            // scenario order, inside the same loop that writes the `Scenario:`\n            // line — but it is written to FAIL CLOSED rather than to assert\n            // that: a scenario with no digest opposite it drops out of the\n            // pairing instead of being published with a null one. A kept row\n            // reads its pairs off the file that is really on disk, because its\n            // numbers describe the in-flight emission that stayed, not the one\n            // that was withheld.\n            stamped:\n              a.action === \"kept\"\n                ? a.kept.scenarios.map((s) => ({ scenario: s.name, digest: s.digest }))\n                : a.requirement.scenarios.flatMap((s, i) => {\n                    const digest = a.digests[i];\n                    return digest === undefined ? [] : [{ scenario: s.name, digest }];\n                  }),\n            ...(a.action === \"kept\"\n              ? { inFlight: a.kept.tags.filter((t) => activeIds.has(t)) }\n              : {\n                  stepless: a.stepless,\n                  malformedExamples: a.malformedExamples,\n                  strandedBlocks: a.strandedBlocks,\n                }),\n          })),\n          deleted: orphans.map((o) => rel(o.path)),\n          ...(recovered === null ? {} : { recovered }),\n        });\n        return;\n      }\n\n      if (recovered !== null) console.log(`${sayRecovered(recovered)}\\n`);\n      render(actions, {\n        service,\n        root: rel(root),\n        absRoot: root,\n        featureId: scope.mode === \"feature\" ? scope.featureId : null,\n        dryRun,\n        activeIds,\n        writes: writes.length,\n        orphans: orphans.map((o) => o.path),\n      });\n    });\n}\n"]}