@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

@@ -1 +1 @@
-{"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, 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"]}

package/dist/commands/gherkin/reconcile.js

@@ -21,9 +21,12 @@ import { dirname, join, relative } from "node:path";
 import {} from "../../core/gherkin/emit.js";
 import { parseStampedFeature } from "../../core/gherkin/read.js";
 import { featureFilesUnder } from "../../core/gherkin/stale.js";
-import { isPathInside, resolveInside, UnsafePathError } from "../../core/kernel/path-safety.js";
+import { isPathInside, resolveInside } from "../../core/kernel/path-safety.js";
 export async function reconcile(plan, where, scope, activeIds) {
     const { root, repoDir } = where;
+    // 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).
     // Living mode owns the whole suite — any .feature not in the plan goes —
     // EXCEPT files tagged with a feature still in flight: those answer to
     // their feature's delta until it archives, and `loam gherkin <FEAT>` is
@@ -100,18 +103,12 @@ export async function reconcile(plan, where, scope, activeIds) {
     // or the requirement renamed.
     const actions = [];
     for (const f of plan) {
-        let path;
-        try {
-            // Check the final file as well as the owned root: a pre-planted
-            // `<slug>.feature` symlink must not turn writeFile into an overwrite
-            // outside the repository.
-            path = resolveInside(repoDir, relative(repoDir, join(root, f.fileName)), `gherkin file '${f.fileName}'`);
-        }
-        catch (err) {
-            if (!(err instanceof UnsafePathError))
-                throw err;
-            throw err;
-        }
+        // Check the final file as well as the owned root: a pre-planted
+        // `<slug>.feature` symlink must not turn writeFile into an overwrite
+        // outside the repository. The UnsafePathError is left to escape: the one
+        // caller (./gherkin.ts) refuses it as `invalid-option`, and a catch here
+        // could only rethrow it.
+        const path = resolveInside(repoDir, relative(repoDir, join(root, f.fileName)), `gherkin file '${f.fileName}'`);
         if (!existsSync(path)) {
             actions.push({ ...f, path, action: "written" });
             continue;

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

@@ -1 +1 @@
-{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/commands/gherkin/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAuB,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAuB,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AA8ChG,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAsB,EACtB,KAAmB,EACnB,KAAY,EACZ,SAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAChC,yEAAyE;IACzE,sEAAsE;IACtE,wEAAwE;IACxE,sBAAsB;IACtB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrD,yEAAyE;IACzE,qEAAqE;IACrE,wEAAwE;IACxE,mEAAmE;IACnE,yEAAyE;IACzE,0EAA0E;IAC1E,kEAAkE;IAClE,mEAAmE;IACnE,wEAAwE;IACxE,8BAA8B;IAC9B,EAAE;IACF,wEAAwE;IACxE,yEAAyE;IACzE,wEAAwE;IACxE,WAAW;IACX,MAAM,UAAU,GAAG,CAAC,CAAS,EAAiB,EAAE;QAC9C,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IACF,yEAAyE;IACzE,uEAAuE;IACvE,wEAAwE;IACxE,0EAA0E;IAC1E,wBAAwB;IACxB,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,OAAO,GAAoC,EAAE,CAAC;IACpD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,MAAM,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAAE,SAAS;YACxE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACxC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAAE,SAAS;YACjE,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC1D,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;YACnG,CAAC;iBAAM,CAAC;gBACN,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBAAE,SAAS;gBAC7E,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,wEAAwE;IACxE,uEAAuE;IACvE,wEAAwE;IACxE,qEAAqE;IACrE,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,iEAAiE;IACjE,wBAAwB;IACxB,EAAE;IACF,sEAAsE;IACtE,oEAAoE;IACpE,yEAAyE;IACzE,qEAAqE;IACrE,wEAAwE;IACxE,uEAAuE;IACvE,0EAA0E;IAC1E,8BAA8B;IAC9B,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,gEAAgE;YAChE,qEAAqE;YACrE,0BAA0B;YAC1B,IAAI,GAAG,aAAa,CAClB,OAAO,EACP,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EACzC,iBAAiB,CAAC,CAAC,QAAQ,GAAG,CAC/B,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;gBAAE,MAAM,GAAG,CAAC;YACjD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YAChD,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAC7D,SAAS;YACX,CAAC;QACH,CAAC;aAAM,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7B,kEAAkE;YAClE,mEAAmE;YACnE,6BAA6B;YAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACtF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;gBACzE,SAAS;YACX,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,yEAAyE;IACzE,wEAAwE;IACxE,4DAA4D;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS;QACxC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAmD,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC;QACjG,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACzC,CAAC","sourcesContent":["/**\n * The plan against what is already on disk: which files are orphans, which are\n * written, replaced, kept, or owned by another feature.\n *\n * A module of its own because it is the only part of `loam gherkin` that\n * DELETES, and the reasoning that makes deletion safe is all here: a candidate\n * is an orphan only when its containing directory really resolves inside the\n * owned root, and a root that does not resolve proves nothing about what lives\n * beneath it, so nothing is collected. Leaving an orphan behind is\n * self-repairing — `loam validate` grades it and the next run removes it — and a\n * deletion taken on an unproven path is not.\n *\n * The in-flight exemption is here for the same reason: files are named by\n * requirement slug in both modes, so a MODIFIED requirement's living emission\n * always collides with the active feature's file, and replacing it reverted the\n * delta's wording mid-flight with its digest stamps destroyed.\n */\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { type PlannedFeature } from \"../../core/gherkin/emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"../../core/gherkin/read.js\";\nimport { featureFilesUnder } from \"../../core/gherkin/stale.js\";\nimport { isPathInside, resolveInside, UnsafePathError } from \"../../core/kernel/path-safety.js\";\n\n/**\n * The run's scope as ONE value, not a mode with an id lying beside it that only\n * one of the modes ever fills in: the emission tag, the orphan filter, the\n * overwrite rule and the conflict refusal all want the feature id exactly when\n * the run is a feature run. A union states that; two variables could only be\n * asserted to agree.\n */\nexport type Scope = { mode: \"living\" } | { mode: \"feature\"; featureId: string };\n\nexport type Emission = PlannedFeature & { path: string };\n\n/**\n * The row's shape follows its action instead of carrying every field any action\n * might want: only a kept or a conflicting row has read the file that is\n * already there, and only a conflicting one has owners. Held as one flat row\n * with optional fields, every reader had to assert what the writer three lines\n * up already knew.\n */\nexport type ActionRow =\n  | (Emission & { action: \"written\" })\n  // A replaced row carries the exact bytes it was graded against, so the\n  // commit can prove the file did not move between the grading and the swap —\n  // planning and committing must compare the same read, or a mismatch is\n  // buried instead of refused.\n  | (Emission & { action: \"replaced\"; raw: Buffer })\n  | (Emission & { action: \"kept\"; kept: StampedFeature })\n  | (Emission & { action: \"conflict\"; kept: StampedFeature; owners: string[] });\n\nexport type Action = ActionRow[\"action\"];\n\n/** Where the suite lives: the owned root, inside the service repository. */\nexport interface EmissionRoot {\n  root: string;\n  repoDir: string;\n}\n\nexport interface Reconciliation {\n  /** Each orphan with the bytes its grading read — the commit compares them before deleting. */\n  orphans: { path: string; raw: Buffer }[];\n  actions: ActionRow[];\n  /** Non-empty only in feature mode; one entry refuses the whole emission. */\n  conflicts: Extract<ActionRow, { action: \"conflict\" }>[];\n}\n\nexport async function reconcile(\n  plan: PlannedFeature[],\n  where: EmissionRoot,\n  scope: Scope,\n  activeIds: ReadonlySet<string>,\n): Promise<Reconciliation> {\n  const { root, repoDir } = where;\n  // Living mode owns the whole suite — any .feature not in the plan goes —\n  // EXCEPT files tagged with a feature still in flight: those answer to\n  // their feature's delta until it archives, and `loam gherkin <FEAT>` is\n  // their regeneration.\n  const planned = new Set(plan.map((f) => f.fileName));\n  // \"Inside loam/\" has to hold after the links are resolved, not merely in\n  // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and\n  // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->\n  // /outside` hands back candidates that read as ours while `unlink`\n  // resolves them and destroys files that were never in this repo. Planned\n  // names are flat, so nothing nested is ever spared by `planned.has(...)`,\n  // and deletion is the one irreversible thing this command does: a\n  // candidate is an orphan only when its CONTAINING directory really\n  // resolves inside the owned root. The write path below refuses the same\n  // attack for the same reason.\n  //\n  // The candidate FILE is deliberately NOT resolved. A symlinked .feature\n  // sitting directly in loam/ is loam's to remove — unlinking it takes the\n  // link and leaves its target alone — so only the directory chain has to\n  // be ours.\n  const realOrNull = (p: string): string | null => {\n    try {\n      return realpathSync(p);\n    } catch {\n      return null;\n    }\n  };\n  // A root that does not resolve — absent, dangling, or vanished mid-run —\n  // proves nothing about what lives beneath it, so nothing is collected.\n  // Leaving an orphan behind is self-repairing (`loam validate` grades it\n  // `gherkin.orphaned` and the next run removes it); a deletion taken on an\n  // unproven path is not.\n  const rootReal = realOrNull(root);\n  const orphans: { path: string; raw: Buffer }[] = [];\n  if (rootReal !== null) {\n    for (const abs of await featureFilesUnder(root)) {\n      if (planned.has(relative(root, abs).split(/[\\\\/]/).join(\"/\"))) continue;\n      const holder = realOrNull(dirname(abs));\n      if (holder === null || !isPathInside(rootReal, holder)) continue;\n      const raw = await readFile(abs);\n      const stamped = parseStampedFeature(raw.toString(\"utf8\"));\n      if (scope.mode === \"feature\") {\n        if (stamped !== null && stamped.tags.includes(scope.featureId)) orphans.push({ path: abs, raw });\n      } else {\n        if (stamped !== null && stamped.tags.some((t) => activeIds.has(t))) continue;\n        orphans.push({ path: abs, raw });\n      }\n    }\n  }\n\n  // The in-flight exemption guards the OVERWRITE path too, not only the\n  // orphan scan above: files are named by requirement slug in both modes,\n  // so a MODIFIED requirement's living emission always collides with the\n  // active feature's file — and replacing it reverted the delta's wording\n  // mid-flight, feature tag and new digest stamps destroyed, invisibly\n  // (the reverted file grades current against the living spec). A planned\n  // path whose existing content is stamped and tagged with a feature still\n  // in flight is KEPT and reported as such; it answers to its feature's\n  // delta until the feature archives, and then living regeneration\n  // replaces it normally.\n  //\n  // FEATURE mode has the same collision and cannot solve it by keeping:\n  // two features in flight against one requirement slug want the same\n  // file, and whichever runs second used to `replace` — silently reverting\n  // the other feature's wording, feature tag and digest stamps, so its\n  // `verify --results` could never confirm a scenario again. Nothing loam\n  // can write is right here (the file holds ONE feature's delta), so the\n  // run refuses and names the owner: the two features have to be sequenced,\n  // or the requirement renamed.\n  const actions: ActionRow[] = [];\n  for (const f of plan) {\n    let path: string;\n    try {\n      // Check the final file as well as the owned root: a pre-planted\n      // `<slug>.feature` symlink must not turn writeFile into an overwrite\n      // outside the repository.\n      path = resolveInside(\n        repoDir,\n        relative(repoDir, join(root, f.fileName)),\n        `gherkin file '${f.fileName}'`,\n      );\n    } catch (err) {\n      if (!(err instanceof UnsafePathError)) throw err;\n      throw err;\n    }\n    if (!existsSync(path)) {\n      actions.push({ ...f, path, action: \"written\" });\n      continue;\n    }\n    const raw = await readFile(path);\n    const existing = parseStampedFeature(raw.toString(\"utf8\"));\n    if (scope.mode === \"living\") {\n      if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {\n        actions.push({ ...f, path, action: \"kept\", kept: existing });\n        continue;\n      }\n    } else if (existing !== null) {\n      // An unstamped file is nobody's delta — it owns nothing, so it is\n      // replaced like any other, which is what the empty owner list used\n      // to say the long way round.\n      const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));\n      if (owners.length > 0) {\n        actions.push({ ...f, path, action: \"conflict\", kept: existing, owners });\n        continue;\n      }\n    }\n    actions.push({ ...f, path, action: \"replaced\", raw });\n  }\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  const conflicts = scope.mode === \"feature\"\n    ? actions.filter((a): a is Extract<ActionRow, { action: \"conflict\" }> => a.action === \"conflict\")\n    : [];\n\n  return { orphans, actions, conflicts };\n}\n"]}
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/commands/gherkin/reconcile.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The plan against what is already on disk: which files are orphans, which are\n * written, replaced, kept, or owned by another feature.\n *\n * A module of its own because it is the only part of `loam gherkin` that\n * DELETES, and the reasoning that makes deletion safe is all here: a candidate\n * is an orphan only when its containing directory really resolves inside the\n * owned root, and a root that does not resolve proves nothing about what lives\n * beneath it, so nothing is collected. Leaving an orphan behind is\n * self-repairing — `loam validate` grades it and the next run removes it — and a\n * deletion taken on an unproven path is not.\n *\n * The in-flight exemption is here for the same reason: files are named by\n * requirement slug in both modes, so a MODIFIED requirement's living emission\n * always collides with the active feature's file, and replacing it reverted the\n * delta's wording mid-flight with its digest stamps destroyed.\n */\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { type PlannedFeature } from \"../../core/gherkin/emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"../../core/gherkin/read.js\";\nimport { featureFilesUnder } from \"../../core/gherkin/stale.js\";\nimport { isPathInside, resolveInside } from \"../../core/kernel/path-safety.js\";\n\n/**\n * The run's scope as ONE value, not a mode with an id lying beside it that only\n * one of the modes ever fills in: the emission tag, the orphan filter, the\n * overwrite rule and the conflict refusal all want the feature id exactly when\n * the run is a feature run. A union states that; two variables could only be\n * asserted to agree.\n */\nexport type Scope = { mode: \"living\" } | { mode: \"feature\"; featureId: string };\n\nexport type Emission = PlannedFeature & { path: string };\n\n/**\n * The row's shape follows its action instead of carrying every field any action\n * might want: only a kept or a conflicting row has read the file that is\n * already there, and only a conflicting one has owners. Held as one flat row\n * with optional fields, every reader had to assert what the writer three lines\n * up already knew.\n */\nexport type ActionRow =\n  | (Emission & { action: \"written\" })\n  // A replaced row carries the exact bytes it was graded against, so the\n  // commit can prove the file did not move between the grading and the swap —\n  // planning and committing must compare the same read, or a mismatch is\n  // buried instead of refused.\n  | (Emission & { action: \"replaced\"; raw: Buffer })\n  | (Emission & { action: \"kept\"; kept: StampedFeature })\n  | (Emission & { action: \"conflict\"; kept: StampedFeature; owners: string[] });\n\nexport type Action = ActionRow[\"action\"];\n\n/** Where the suite lives: the owned root, inside the service repository. */\nexport interface EmissionRoot {\n  root: string;\n  repoDir: string;\n}\n\nexport interface Reconciliation {\n  /** Each orphan with the bytes its grading read — the commit compares them before deleting. */\n  orphans: { path: string; raw: Buffer }[];\n  actions: ActionRow[];\n  /** Non-empty only in feature mode; one entry refuses the whole emission. */\n  conflicts: Extract<ActionRow, { action: \"conflict\" }>[];\n}\n\nexport async function reconcile(\n  plan: PlannedFeature[],\n  where: EmissionRoot,\n  scope: Scope,\n  activeIds: ReadonlySet<string>,\n): Promise<Reconciliation> {\n  const { root, repoDir } = where;\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  // Living mode owns the whole suite — any .feature not in the plan goes —\n  // EXCEPT files tagged with a feature still in flight: those answer to\n  // their feature's delta until it archives, and `loam gherkin <FEAT>` is\n  // their regeneration.\n  const planned = new Set(plan.map((f) => f.fileName));\n  // \"Inside loam/\" has to hold after the links are resolved, not merely in\n  // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and\n  // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->\n  // /outside` hands back candidates that read as ours while `unlink`\n  // resolves them and destroys files that were never in this repo. Planned\n  // names are flat, so nothing nested is ever spared by `planned.has(...)`,\n  // and deletion is the one irreversible thing this command does: a\n  // candidate is an orphan only when its CONTAINING directory really\n  // resolves inside the owned root. The write path below refuses the same\n  // attack for the same reason.\n  //\n  // The candidate FILE is deliberately NOT resolved. A symlinked .feature\n  // sitting directly in loam/ is loam's to remove — unlinking it takes the\n  // link and leaves its target alone — so only the directory chain has to\n  // be ours.\n  const realOrNull = (p: string): string | null => {\n    try {\n      return realpathSync(p);\n    } catch {\n      return null;\n    }\n  };\n  // A root that does not resolve — absent, dangling, or vanished mid-run —\n  // proves nothing about what lives beneath it, so nothing is collected.\n  // Leaving an orphan behind is self-repairing (`loam validate` grades it\n  // `gherkin.orphaned` and the next run removes it); a deletion taken on an\n  // unproven path is not.\n  const rootReal = realOrNull(root);\n  const orphans: { path: string; raw: Buffer }[] = [];\n  if (rootReal !== null) {\n    for (const abs of await featureFilesUnder(root)) {\n      if (planned.has(relative(root, abs).split(/[\\\\/]/).join(\"/\"))) continue;\n      const holder = realOrNull(dirname(abs));\n      if (holder === null || !isPathInside(rootReal, holder)) continue;\n      const raw = await readFile(abs);\n      const stamped = parseStampedFeature(raw.toString(\"utf8\"));\n      if (scope.mode === \"feature\") {\n        if (stamped !== null && stamped.tags.includes(scope.featureId)) orphans.push({ path: abs, raw });\n      } else {\n        if (stamped !== null && stamped.tags.some((t) => activeIds.has(t))) continue;\n        orphans.push({ path: abs, raw });\n      }\n    }\n  }\n\n  // The in-flight exemption guards the OVERWRITE path too, not only the\n  // orphan scan above: files are named by requirement slug in both modes,\n  // so a MODIFIED requirement's living emission always collides with the\n  // active feature's file — and replacing it reverted the delta's wording\n  // mid-flight, feature tag and new digest stamps destroyed, invisibly\n  // (the reverted file grades current against the living spec). A planned\n  // path whose existing content is stamped and tagged with a feature still\n  // in flight is KEPT and reported as such; it answers to its feature's\n  // delta until the feature archives, and then living regeneration\n  // replaces it normally.\n  //\n  // FEATURE mode has the same collision and cannot solve it by keeping:\n  // two features in flight against one requirement slug want the same\n  // file, and whichever runs second used to `replace` — silently reverting\n  // the other feature's wording, feature tag and digest stamps, so its\n  // `verify --results` could never confirm a scenario again. Nothing loam\n  // can write is right here (the file holds ONE feature's delta), so the\n  // run refuses and names the owner: the two features have to be sequenced,\n  // or the requirement renamed.\n  const actions: ActionRow[] = [];\n  for (const f of plan) {\n    // Check the final file as well as the owned root: a pre-planted\n    // `<slug>.feature` symlink must not turn writeFile into an overwrite\n    // outside the repository. The UnsafePathError is left to escape: the one\n    // caller (./gherkin.ts) refuses it as `invalid-option`, and a catch here\n    // could only rethrow it.\n    const path = resolveInside(\n      repoDir,\n      relative(repoDir, join(root, f.fileName)),\n      `gherkin file '${f.fileName}'`,\n    );\n    if (!existsSync(path)) {\n      actions.push({ ...f, path, action: \"written\" });\n      continue;\n    }\n    const raw = await readFile(path);\n    const existing = parseStampedFeature(raw.toString(\"utf8\"));\n    if (scope.mode === \"living\") {\n      if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {\n        actions.push({ ...f, path, action: \"kept\", kept: existing });\n        continue;\n      }\n    } else if (existing !== null) {\n      // An unstamped file is nobody's delta — it owns nothing, so it is\n      // replaced like any other, which is what the empty owner list used\n      // to say the long way round.\n      const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));\n      if (owners.length > 0) {\n        actions.push({ ...f, path, action: \"conflict\", kept: existing, owners });\n        continue;\n      }\n    }\n    actions.push({ ...f, path, action: \"replaced\", raw });\n  }\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  const conflicts = scope.mode === \"feature\"\n    ? actions.filter((a): a is Extract<ActionRow, { action: \"conflict\" }> => a.action === \"conflict\")\n    : [];\n\n  return { orphans, actions, conflicts };\n}\n"]}

package/dist/commands/init/first-hour.js

@@ -25,4 +25,48 @@ export function firstHour(service) {
         ["loam status", "what to do next, derived from the files"],
     ];
 }
+/**
+ * The first hour of a docs repo created with NO service bound — WORKFLOW.md's
+ * Day zero steps 2–4, and the same rungs `loam status` answers on an empty
+ * fleet (`next.author-landscape`, `next.bind-service`, `next.adopt-first`).
+ *
+ * This run used to print nothing after the scaffold list: the single-repo
+ * table above needs a service id to name, and the guard that withheld it read
+ * "nothing is bound" as "nothing to say". But this is the Day zero composition
+ * itself — the person who just created the fleet's shared repo — and its next
+ * steps are as fixed as the trial's: state the map, bind each service's own
+ * repo, adopt. The ids are placeholders because nothing here knows them yet,
+ * which is also why the runnable-commands suite substitutes them like every
+ * other `<id>` it parses. Exported for that suite, by import, for the reason
+ * the header gives.
+ *
+ * The bind line names `--agent-profile service` because it is run in a
+ * SERVICE checkout of a fleet whose features are authored and archived here,
+ * in this docs repo: the profile defaults to `full`, and `full` puts
+ * `loam-feature` and `loam-ship` into every service repo — the outcome
+ * README's "Pass the profile explicitly" warns against. Agents type the
+ * command loam prints, not the README.
+ */
+export function docsRepoFirstHour() {
+    return [
+        ["loam seed --from fleet.yaml", "the fleet map from a fleet.yaml you write, or draw it by hand"],
+        ["loam init --docs <docs-repo> --service <id> --agent-profile service",
+            "in each service's own repo: bind it, commit loam.json"],
+        ["loam adopt --service <id> --json", "there: the brief, an agent writes the baseline as draft"],
+        ["loam status", "what to do next, derived from the files"],
+    ];
+}
+/**
+ * The epilogue's printed lines — the heading and one aligned `command   # why`
+ * row per step — for whichever first hour this run earned. Rendering only:
+ * init.ts decides WHETHER (never on a join), this decides which table and how
+ * it reads, so the two variants cannot drift into two layouts.
+ */
+export function firstHourLines(service) {
+    const [heading, steps] = service === undefined
+        ? ["next — the docs repo's first hour:", docsRepoFirstHour()]
+        : ["next — the first hour:", firstHour(service)];
+    const width = Math.max(...steps.map(([command]) => command.length));
+    return [`  ${heading}`, ...steps.map(([command, why]) => `    ${command.padEnd(width)}   # ${why}`)];
+}
 //# sourceMappingURL=first-hour.js.map

package/dist/commands/init/first-hour.js.map

@@ -1 +1 @@
-{"version":3,"file":"first-hour.js","sourceRoot":"","sources":["../../../src/commands/init/first-hour.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;QACL,CAAC,wBAAwB,OAAO,SAAS;YACvC,kEAAkE,CAAC;QACrE,CAAC,2BAA2B,OAAO,EAAE,EAAE,+BAA+B,CAAC;QACvE,CAAC,wBAAwB,OAAO,EAAE,EAAE,uCAAuC,CAAC;QAC5E,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAC3D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The four commands of the single-repo trial's first hour, each with the\n * reason it is there. `init` prints them as its epilogue when one run both\n * creates the docs repo and leaves a service bound (init.ts holds that guard\n * and the why).\n *\n * A module of its own for two reasons. The seam: init.ts is the wiring — the\n * flag guards and the scaffold sequence — while this table is what the trial\n * user is told, and the table alone pushed init.ts past the 300-line limit.\n * The export: test/agent-commands-runnable.test.ts feeds these commands\n * through the real commander program by IMPORT, because the printed lines are\n * plain text inside template literals — no markdown backticks, no\n * single-quoted `loam` forms — so that suite's literal scrape cannot see\n * them, and they are the first instruction a single-repo trial user receives:\n * the exact class its header records shipping broken once as `loam adopt\n * <id>`. README.md's Quick start reprints the same four lines, and\n * test/cli.test.ts pins that copy to this table.\n */\nexport function firstHour(service: string): Array<[command: string, why: string]> {\n  return [\n    [`loam adopt --service ${service} --json`,\n      \"the brief: an agent reads the code, writes the baseline as draft\"],\n    [`loam validate --service ${service}`, \"grade the result in this repo\"],\n    [`loam vouch --service ${service}`, \"you, not the agent: draft -> verified\"],\n    [\"loam status\", \"what to do next, derived from the files\"],\n  ];\n}\n"]}
+{"version":3,"file":"first-hour.js","sourceRoot":"","sources":["../../../src/commands/init/first-hour.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;QACL,CAAC,wBAAwB,OAAO,SAAS;YACvC,kEAAkE,CAAC;QACrE,CAAC,2BAA2B,OAAO,EAAE,EAAE,+BAA+B,CAAC;QACvE,CAAC,wBAAwB,OAAO,EAAE,EAAE,uCAAuC,CAAC;QAC5E,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,CAAC,6BAA6B,EAAE,+DAA+D,CAAC;QAChG,CAAC,qEAAqE;YACpE,uDAAuD,CAAC;QAC1D,CAAC,kCAAkC,EAAE,yDAAyD,CAAC;QAC/F,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA2B;IACxD,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,KAAK,SAAS;QAC5C,CAAC,CAAC,CAAC,oCAAoC,EAAE,iBAAiB,EAAE,CAAC;QAC7D,CAAC,CAAC,CAAC,wBAAwB,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,KAAK,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC;AACvG,CAAC","sourcesContent":["/**\n * The four commands of the single-repo trial's first hour, each with the\n * reason it is there. `init` prints them as its epilogue when one run both\n * creates the docs repo and leaves a service bound (init.ts holds that guard\n * and the why).\n *\n * A module of its own for two reasons. The seam: init.ts is the wiring — the\n * flag guards and the scaffold sequence — while this table is what the trial\n * user is told, and the table alone pushed init.ts past the 300-line limit.\n * The export: test/agent-commands-runnable.test.ts feeds these commands\n * through the real commander program by IMPORT, because the printed lines are\n * plain text inside template literals — no markdown backticks, no\n * single-quoted `loam` forms — so that suite's literal scrape cannot see\n * them, and they are the first instruction a single-repo trial user receives:\n * the exact class its header records shipping broken once as `loam adopt\n * <id>`. README.md's Quick start reprints the same four lines, and\n * test/cli.test.ts pins that copy to this table.\n */\nexport function firstHour(service: string): Array<[command: string, why: string]> {\n  return [\n    [`loam adopt --service ${service} --json`,\n      \"the brief: an agent reads the code, writes the baseline as draft\"],\n    [`loam validate --service ${service}`, \"grade the result in this repo\"],\n    [`loam vouch --service ${service}`, \"you, not the agent: draft -> verified\"],\n    [\"loam status\", \"what to do next, derived from the files\"],\n  ];\n}\n\n/**\n * The first hour of a docs repo created with NO service bound — WORKFLOW.md's\n * Day zero steps 2–4, and the same rungs `loam status` answers on an empty\n * fleet (`next.author-landscape`, `next.bind-service`, `next.adopt-first`).\n *\n * This run used to print nothing after the scaffold list: the single-repo\n * table above needs a service id to name, and the guard that withheld it read\n * \"nothing is bound\" as \"nothing to say\". But this is the Day zero composition\n * itself — the person who just created the fleet's shared repo — and its next\n * steps are as fixed as the trial's: state the map, bind each service's own\n * repo, adopt. The ids are placeholders because nothing here knows them yet,\n * which is also why the runnable-commands suite substitutes them like every\n * other `<id>` it parses. Exported for that suite, by import, for the reason\n * the header gives.\n *\n * The bind line names `--agent-profile service` because it is run in a\n * SERVICE checkout of a fleet whose features are authored and archived here,\n * in this docs repo: the profile defaults to `full`, and `full` puts\n * `loam-feature` and `loam-ship` into every service repo — the outcome\n * README's \"Pass the profile explicitly\" warns against. Agents type the\n * command loam prints, not the README.\n */\nexport function docsRepoFirstHour(): Array<[command: string, why: string]> {\n  return [\n    [\"loam seed --from fleet.yaml\", \"the fleet map from a fleet.yaml you write, or draw it by hand\"],\n    [\"loam init --docs <docs-repo> --service <id> --agent-profile service\",\n      \"in each service's own repo: bind it, commit loam.json\"],\n    [\"loam adopt --service <id> --json\", \"there: the brief, an agent writes the baseline as draft\"],\n    [\"loam status\", \"what to do next, derived from the files\"],\n  ];\n}\n\n/**\n * The epilogue's printed lines — the heading and one aligned `command   # why`\n * row per step — for whichever first hour this run earned. Rendering only:\n * init.ts decides WHETHER (never on a join), this decides which table and how\n * it reads, so the two variants cannot drift into two layouts.\n */\nexport function firstHourLines(service: string | undefined): string[] {\n  const [heading, steps] = service === undefined\n    ? [\"next — the docs repo's first hour:\", docsRepoFirstHour()]\n    : [\"next — the first hour:\", firstHour(service)];\n  const width = Math.max(...steps.map(([command]) => command.length));\n  return [`  ${heading}`, ...steps.map(([command, why]) => `    ${command.padEnd(width)}   # ${why}`)];\n}\n"]}

package/dist/commands/init/init.js

@@ -10,7 +10,7 @@ import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.j
 import { detectAgentTools, plannedCommandFiles, syncAgentCommands, updatedAgentFileManifest, } from "../../core/agent/scaffold.js";
 import { AGENT_TOOLS } from "../../core/agent/tools/registry.js";
 import { initExample } from "./example.js";
-import { firstHour } from "./first-hour.js";
+import { firstHourLines } from "./first-hour.js";
 import { MCP_CONFIG_FILENAME, mcpConfigPath, mcpServerSnippet, writeMcpConfig } from "./mcp.js";
 import { isDocsRepo, resolveAgentProfile, resolveTools, storedDocsDir } from "./options.js";
 export function registerInit(program) {
@@ -299,27 +299,23 @@ export function registerInit(program) {
             for (const line of mcpServerSnippet(cwd, opts.mcpAuthor === true))
                 console.log(`               ${line}`);
         }
-        // Printed ONLY for the single-repo trial composition: one run that both
-        // created the docs repo and left a service bound (the binding may
-        // predate the run — the config spread above carries an existing
-        // loam.json's `service` forward). `loam status` is NOT mute here — its
-        // first-hour ladder (core/status/fleet/next.ts) already answers
-        // `next.adopt-bound` in exactly this state — but status has to be run
-        // to say so, and no status rung ever names `loam vouch`, the one step
-        // of this loop that is a person's; init's output is already on screen,
-        // so it prints the whole hour once. A join stays silent on purpose: a
-        // joined fleet has other repositories already through this loop, and
-        // `loam status` in its docs repo is the working guide there. The --json
-        // path returned above, so the envelope is byte-identical to before
-        // this block existed.
-        if (!joining && config.service !== undefined) {
-            const steps = firstHour(config.service);
-            const width = Math.max(...steps.map(([command]) => command.length));
-            console.log("  next — the first hour:");
-            for (const [command, why] of steps) {
-                console.log(`    ${command.padEnd(width)}   # ${why}`);
-            }
-        }
+        // Printed ONLY when this run created the docs repo. With a service bound
+        // (the binding may predate the run — the config spread above carries an
+        // existing loam.json's `service` forward) it is the single-repo trial's
+        // hour. `loam status` is NOT mute here — its first-hour ladder
+        // (core/status/fleet/next.ts) already answers `next.adopt-bound` in
+        // exactly this state — but status has to be run to say so, and no status
+        // rung ever names `loam vouch`, the one step of this loop that is a
+        // person's; init's output is already on screen, so it prints the whole
+        // hour once. With none bound it is the docs repo's own hour (map, bind,
+        // adopt — first-hour.ts says why that used to be silence). A join stays
+        // silent on purpose: a joined fleet has other repositories already
+        // through this loop, and `loam status` in its docs repo is the working
+        // guide there. The --json path returned above, so the envelope is
+        // byte-identical to before this block existed: neither variant has a key.
+        if (!joining)
+            for (const line of firstHourLines(config.service))
+                console.log(line);
     });
 }
 //# sourceMappingURL=init.js.map