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

package/dist/commands/gate/gate.js

@@ -0,0 +1,152 @@
+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 { 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 config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        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"
+        // over an empty fleet (docsRepoReady's whole doctrine).
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        // The deploy-pipeline invocation is literally `loam gate --json` in a
+        // bound service repo: the binding IS the service being deployed.
+        const service = opts.service ?? config.service;
+        if (!service) {
+            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 {
+            // Enumeration first, grammar second — service-target.ts's banner: the
+            // one directory a caller most needs to ask about may carry a name the
+            // grammar refuses, so the raw argument is never assertServiceId'd here.
+            const resolved = await resolveServiceTarget(docsDir, service, "--service", fleet);
+            if (!resolved.ok) {
+                fail(json, "invalid-option", resolved.problem);
+                return;
+            }
+            if (resolved.dir === undefined) {
+                // Grammar-legal but unenumerated: a question recorded evidence
+                // cannot answer — Pact's gate answers unknown participants with a
+                // refusal, not a pass (status's `unknown-service` precedent).
+                const near = nearestIds(resolved.id, await enumeratedServiceIds(docsDir, fleet));
+                fail(json, "unknown-service", `No service '${resolved.id}' under ${docsDir}/services/ — nothing is recorded for a service nobody adopted, so the deploy question is unanswerable.` +
+                    (near.length > 0 ? ` Did you mean: ${near.join(", ")}?` : "") +
+                    ` Run \`loam adopt --service ${resolved.id}\` to write its baseline first.`);
+                return;
+            }
+            // `sources` only mean something from inside the service's own
+            // repository — validate's repoOf rule. `config.root` rather than
+            // process.cwd(): the config's own directory is the repo root, and a
+            // run from src/deep/ must grade the same paths as one from the root.
+            const bound = config.service;
+            const report = await gateReport({
+                docsDir,
+                service: resolved.id,
+                repoDir: bound === resolved.id ? (config.root ?? process.cwd()) : undefined,
+                fleet,
+                since,
+            });
+            const verdict = gateVerdict(report.checks);
+            const summary = gateSummary(report.checks);
+            if (json) {
+                emitJson({
+                    command: "gate",
+                    docsDir,
+                    service: report.service,
+                    verdict,
+                    strict: opts.strict === true,
+                    since: report.since,
+                    landscape: report.landscape,
+                    partners: report.partners,
+                    features: report.features,
+                    checks: report.checks.map((c) => ({
+                        check: c.check,
+                        findings: c.findings.map((finding) => findingJson(finding)),
+                    })),
+                    summary,
+                });
+            }
+            else {
+                printGate(report, verdict, summary);
+            }
+            // --strict moves only the exit code, never the verdict or the payload
+            // — validate's exact stance, documented on its own strict block: two
+            // pipelines reading one repo may grade the same report differently
+            // and both are telling the truth.
+            if (verdict === "fail" || (opts.strict === true && summary.warnings > 0)) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            // The docs repo went away between the gate above and the reads.
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            // An IO failure the per-subject containment could not localise — it
+            // happened in an enumeration, so no partial report exists to give.
+            // The recognizer throws anything carrying no errno untouched.
+            reportRepositoryUnavailable(json, err, `the deploy question for '${service}' is unanswerable`, docsDir);
+        }
+    });
+}
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +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 * 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

@@ -0,0 +1,66 @@
+/**
+ * The human rendering of a gate report: one block per check, the partner and
+ * feature tables as data lines, findings with the shared severity glyphs, and
+ * the verdict last — the line a person scanning a deploy log reads first from
+ * the bottom. The JSON contract never comes through here; `gate.ts` emits the
+ * envelope from the same report, which is what keeps the two views one
+ * derivation.
+ */
+import { SEVERITY_MARK } from "../../core/vocabulary/report.js";
+import { plural } from "../policy/format.js";
+function printFindings(findings) {
+    for (const f of findings) {
+        console.log(`  ${SEVERITY_MARK[f.severity]} ${f.message}`);
+        for (const d of f.details ?? [])
+            console.log(`    - ${d}`);
+    }
+}
+export function printGate(report, verdict, summary) {
+    console.log(`gate — ${report.service} (a query over recorded evidence; it executes nothing)`);
+    const check = (name) => report.checks.find((c) => c.check === name)?.findings ?? [];
+    console.log(`\npartners — landscape ${report.landscape}`);
+    for (const p of report.partners) {
+        const rung = p.external ? "external" : (p.maturity ?? "no services/ directory");
+        console.log(`  ${p.service} · ${rung} · ${p.role} · ${p.via.join(", ")}`);
+    }
+    if (report.partners.length === 0 && report.landscape === "read") {
+        console.log("  (the landscape draws no join into or out of this service)");
+    }
+    printFindings(check("partners"));
+    console.log("\nfreshness");
+    const freshness = check("freshness");
+    if (freshness.length === 0)
+        console.log(`  ${SEVERITY_MARK.ok} nothing recorded has gone stale`);
+    printFindings(freshness);
+    // 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` : "";
+        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(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");
+    const interrupted = check("interrupted");
+    if (interrupted.length === 0)
+        console.log(`  ${SEVERITY_MARK.ok} no interrupted commit in the docs repo`);
+    printFindings(interrupted);
+    console.log(`\nverdict: ${verdict} — ${plural(summary.errors, "error")}, ${plural(summary.warnings, "warning")}` +
+        (verdict === "pass" && summary.warnings > 0
+            ? " (advisory — `--strict` turns warnings into exit 1)"
+            : ""));
+}
+//# sourceMappingURL=print.js.map

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

@@ -0,0 +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  // 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

@@ -0,0 +1,105 @@
+/**
+ * The emission's commit window: lock the owned root, recover a predecessor,
+ * stage every write and delete, prove the tree still matches what reconcile
+ * graded, and land it through the journaled transaction.
+ *
+ * Split from gherkin.ts so the lock's extent is visible in the code shape,
+ * exactly as vouch's commitStamp is — and because this is the writer the
+ * roadmap named: a kill inside the old write/delete loop left a half-old,
+ * half-new suite with no marker, in the one repo (the service's own) where
+ * nothing else of loam's ever looked.
+ */
+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 } 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";
+/**
+ * Stage, compare, journal, swap. The compare is against the bytes RECONCILE
+ * read: a `.feature` that changed (or appeared) between the grading and this
+ * commit is refused by name, never buried — the suite is code somebody may be
+ * editing, and "refused, not buried" is the no-clobber rule the roadmap
+ * spells for exactly this writer.
+ */
+export async function commitEmission(spec, plan) {
+    const { root, service, scope } = spec;
+    // 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. 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 = null;
+    try {
+        // A writer can have crashed between the command-start recovery and this
+        // window; the re-check is one existsSync when nothing happened.
+        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
+            // the run refuses rather than overwriting it.
+            ...plan.writes.map((a) => a.action === "written" ? { path: a.path, content: a.content, exclusive: true } : { path: a.path, content: a.content }),
+            ...plan.orphans.map((o) => ({ path: o.path, content: null })),
+        ];
+        const staged = await stageWrites(planned);
+        // The bytes reconcile graded must be the bytes this commit replaces or
+        // deletes. `swapStaged` re-checks against ITS read just before each
+        // rename; this compare closes the other half of the window, from the
+        // grading to the staging.
+        const graded = new Map();
+        for (const a of plan.writes)
+            if (a.action === "replaced")
+                graded.set(a.path, a.raw);
+        for (const o of plan.orphans)
+            graded.set(o.path, o.raw);
+        const moved = staged
+            .filter((s) => {
+            const raw = graded.get(s.write.path);
+            return raw !== undefined && (s.before === null || !s.before.equals(raw));
+        })
+            .map((s) => s.write.path);
+        if (moved.length > 0) {
+            await rollbackStaged(staged);
+            return {
+                ok: false,
+                code: "merge-failed",
+                message: `the suite changed while this emission was being planned — ${moved.join(", ")} ` +
+                    `no longer holds the bytes the plan was graded against. Nothing was written: re-run.`,
+            };
+        }
+        const committed = await commitStaged({
+            root,
+            command: "gherkin",
+            rerun: scope.mode === "feature" ? `loam gherkin ${scope.featureId}` : "loam gherkin",
+            target: service,
+        }, staged, "emitted");
+        if (!committed.ok) {
+            return committed.raced
+                ? {
+                    ok: false,
+                    code: "merge-failed",
+                    message: "a .feature file appeared after planning and the emission refused to overwrite it — " +
+                        `${committed.message}. Nothing else was written: re-run to grade the new file.`,
+                }
+                : { ok: false, code: committed.code, message: committed.message };
+        }
+        return { ok: true, recovered };
+    }
+    finally {
+        await release?.();
+        if (!rootExisted && !existsSync(join(root, COMMIT_INTENT)))
+            await quietRmdir(root);
+    }
+}
+//# sourceMappingURL=commit.js.map

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

@@ -0,0 +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,MAAM,mCAAmC,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAA8B,MAAM,gBAAgB,CAAC;AAM5D;;;;;;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,4EAA4E;IAC5E,uEAAuE;IACvE,gCAAgC;IAChC,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,OAAO,GAAiC,IAAI,CAAC;IACjD,IAAI,CAAC;QACH,wEAAwE;QACxE,gEAAgE;QAChE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC;QAC9B,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;QAE7B,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,EAAE,CAAC;QAClB,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 } 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"]}