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

package/dist/commands/seed/commit.js

@@ -0,0 +1,192 @@
+/**
+ * Seed's commit window: lock, recover, the under-lock provenance and
+ * fleet-consistency checks, one journaled transaction. Modeled line for line
+ * on commands/new/commit.ts and on the same seam: everything in here holds
+ * the docs lock, nothing outside it does, and the module prints nothing —
+ * the caller renders every arm.
+ *
+ * The checks live UNDER the lock on purpose: the never-overwrite promise is a
+ * statement about the landscape as it is at the moment of the write, and an
+ * unlocked classification would be a TOCTOU against every other docs writer.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { landscapeProvenance } from "../../core/c4/seed/stamp.js";
+import { isLandscapeStub } from "../../core/scaffold/landscape.js";
+import { parseServiceId } from "../../core/kernel/ids/service.js";
+import { landscapePath } from "../../core/repo/paths.js";
+import { listFleetTree } from "../../core/repo/repo.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import { planSeedWrites } from "./plan.js";
+export async function commitSeed(req) {
+    const { docsDir } = req;
+    let releaseLock;
+    try {
+        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (err instanceof DocsBusyError)
+            return { ok: false, code: "docs-busy", message: err.message };
+        throw err;
+    }
+    try {
+        let recovered;
+        try {
+            recovered = await recoverInterruptedCommit(docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof InterruptedCommitError))
+                throw err;
+            return { ok: false, code: "commit-interrupted", message: err.message };
+        }
+        // Provenance first, then the tree: both read the repo as this run will
+        // leave it, and both refusals must prove nothing was written.
+        const landscape = await classifyLandscape(docsDir);
+        if ("refusal" in landscape) {
+            return { ok: false, code: "seed-landscape-edited", message: landscape.refusal };
+        }
+        let tree;
+        try {
+            tree = await listFleetTree(docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof DocsRepoUnavailableError))
+                throw err;
+            return { ok: false, repoGone: err };
+        }
+        const inconsistency = preflight(tree, req.seed);
+        if (inconsistency !== null)
+            return inconsistency;
+        const plan = await planSeedWrites(req, tree);
+        const staged = await stageWrites(plan.writes);
+        const committed = await commitStaged({ root: docsDir, command: "seed", rerun: req.rerun, target: "landscape" }, staged, "seeded");
+        if (!committed.ok) {
+            // `committed.raced` is deliberately NOT remapped: the lock serialises
+            // loam writers, so a fired CAS or a lost exclusive create here means an
+            // out-of-band editor, and seed has no softer race answer the way `new`
+            // has already-exists — merge-failed's "nothing was written, re-run" is
+            // the honest sentence either way.
+            return { ok: false, code: committed.code, message: committed.message };
+        }
+        return {
+            ok: true,
+            landscape: landscape.disposition,
+            written: plan.writes.filter((w) => w.content !== null).map((w) => w.path),
+            removed: plan.writes.filter((w) => w.content === null).map((w) => w.path),
+            services: plan.services,
+            recovered,
+        };
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * May seed write the landscape? Absent and untouched-scaffold-stub are the
+ * two states with provably no human work in them; a matching stamp digest is
+ * the third (`core/c4/seed/stamp.ts`). Everything else refuses.
+ */
+async function classifyLandscape(docsDir) {
+    const path = landscapePath(docsDir);
+    if (!existsSync(path))
+        return { disposition: "created" };
+    const text = (await readFile(path)).toString("utf8");
+    // `isLandscapeStub`, never a byte-compare of our own: that function IS the
+    // repo's answer to "is this still the scaffold's untouched map", it is what
+    // `loam status` reads before telling the reader to run seed, and it is
+    // suffix-matched and CRLF-normalised for two reasons seed shares —
+    // `migrate-openspec` prepends a preamble to the identical stub, and a
+    // checkout under `core.autocrlf` (Git for Windows' installer default)
+    // rewrites every line without touching a fact. A stricter compare here made
+    // status and seed contradict each other about the same file.
+    if (isLandscapeStub(text))
+        return { disposition: "replaced-stub" };
+    const provenance = landscapeProvenance(text);
+    if (provenance === "seed-stamped")
+        return { disposition: "regenerated" };
+    return {
+        refusal: `architecture/landscape.likec4 ${provenance === "seed-edited"
+            ? "was seeded but has been hand-edited since — the line-1 stamp's digest no longer matches the content"
+            : "was not written by `loam seed`: it carries no line-1 stamp and is not the scaffold's untouched stub"}. Seed never overwrites human work; nothing was written. Either fold the edits into ` +
+            `fleet.yaml and delete the file, then re-run — or keep the hand-authored map and stop ` +
+            `using seed here.`,
+    };
+}
+/**
+ * The fleet-consistency preflight. Seed regenerates the landscape WHOLESALE —
+ * that is the only posture the stamp can prove safe — so every existing
+ * services/<id>/ must be named in fleet.yaml, or the regenerate would orphan
+ * it into `landscape.service-unmodelled`. And the file's names must not
+ * collide with what the tree already holds under a different kind: one flat
+ * namespace, the same rule the walk enforces.
+ */
+function preflight(tree, seed) {
+    const treeSubs = new Set(tree.subsystems.map((s) => s.name));
+    const treeIds = new Set(tree.services.map((s) => s.id));
+    // The collision scan runs BEFORE the missing-service scan, and the order is
+    // load-bearing. A name the file declares as a subsystem or an external while
+    // the tree holds it as a service DIRECTORY is both facts at once: it is a
+    // namespace collision, and it is also an existing service the file does not
+    // name. With the missing scan first, the caller was told to paste that name
+    // into `services:` — advice that walks straight into `seed-duplicate-service`
+    // on the next run, because the file already declares it as something else.
+    const collisions = [];
+    for (const sub of seed.subsystems) {
+        if (treeIds.has(sub))
+            collisions.push(`subsystem '${sub}' is an existing service directory`);
+    }
+    for (const s of seed.services) {
+        if (treeSubs.has(s.id))
+            collisions.push(`service '${s.id}' is an existing subsystem directory`);
+    }
+    for (const x of seed.externals) {
+        if (treeIds.has(x))
+            collisions.push(`external '${x}' is an existing service directory`);
+        if (treeSubs.has(x))
+            collisions.push(`external '${x}' is an existing subsystem directory`);
+    }
+    if (collisions.length > 0) {
+        return {
+            ok: false,
+            code: "seed-file-invalid",
+            message: `fleet.yaml collides with the services/ tree — service ids, subsystem names and externals ` +
+                `share one flat namespace: ${collisions.join("; ")}. Rename the fleet.yaml side (or the ` +
+                `directory, with \`loam subsystem rename <from> <to>\`), then re-run. Nothing was written.`,
+            missingServices: [],
+        };
+    }
+    const ids = new Set(seed.services.map((s) => s.id));
+    const missing = tree.services.map((s) => s.id).filter((id) => !ids.has(id)).sort();
+    if (missing.length === 0)
+        return null;
+    // The ids are partitioned because one half cannot take the other's advice.
+    // `tree.services` carries RAW ids — a directory whose name fails the service
+    // grammar is still a service to the walk, by design — and "add it to
+    // services: exactly as spelled" is impossible for one of those: the fleet
+    // file would refuse the entry. Without this split, seed was simply unusable
+    // on such a repo and never said so.
+    const legal = missing.filter((id) => parseServiceId(id, "services entry").ok);
+    const illegal = missing.filter((id) => !parseServiceId(id, "services entry").ok);
+    const fixes = [];
+    if (legal.length > 0)
+        fixes.push(`add ${legal.join(", ")} to services:, exactly as spelled`);
+    if (illegal.length > 0) {
+        fixes.push(`rename the ${illegal.length === 1 ? "directory" : "directories"} ${illegal.join(", ")} ` +
+            `first — ${illegal.length === 1 ? "that name is not a legal service id" : "those names are not legal service ids"}, ` +
+            `so no services: entry can name ${illegal.length === 1 ? "it" : "them"}`);
+    }
+    return {
+        ok: false,
+        code: "seed-file-invalid",
+        message: `fleet.yaml must name every existing service — seed regenerates the landscape wholesale, ` +
+            `and these services/ directories are not in it: ${missing.join(", ")}. ` +
+            `To fix: ${fixes.join("; and ")}. Then re-run. Nothing was written.`,
+        missingServices: missing,
+    };
+}
+//# sourceMappingURL=commit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/seed/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Seed's commit window: lock, recover, the under-lock provenance and\n * fleet-consistency checks, one journaled transaction. Modeled line for line\n * on commands/new/commit.ts and on the same seam: everything in here holds\n * the docs lock, nothing outside it does, and the module prints nothing —\n * the caller renders every arm.\n *\n * The checks live UNDER the lock on purpose: the never-overwrite promise is a\n * statement about the landscape as it is at the moment of the write, and an\n * unlocked classification would be a TOCTOU against every other docs writer.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { FleetSeed } from \"../../core/c4/seed/fleet-file.js\";\nimport { landscapeProvenance } from \"../../core/c4/seed/stamp.js\";\nimport { isLandscapeStub } from \"../../core/scaffold/landscape.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { parseServiceId } from \"../../core/kernel/ids/service.js\";\nimport { landscapePath } from \"../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../core/repo/repo.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport type { FleetTree } from \"../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { 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 { planSeedWrites, type SeedPlanInput } from \"./plan.js\";\n\n/** The plan's input, plus the one fact only the transaction needs. */\nexport interface SeedCommitRequest extends SeedPlanInput {\n  /** How a human re-runs this command — the transaction journal's `rerun`. */\n  rerun: string;\n}\n\n/** What happened to architecture/landscape.likec4 — the three writes seed may prove safe. */\nexport type LandscapeDisposition = \"created\" | \"replaced-stub\" | \"regenerated\";\n\nexport type SeedCommit =\n  | {\n      ok: true;\n      landscape: LandscapeDisposition;\n      /** Absolute path of every file the transaction wrote, in write order. */\n      written: string[];\n      /**\n       * Absolute path of every file the transaction REMOVED — only ever the\n       * generated views file, when the resulting tree has no subsystems left\n       * to view. Separate from `written` because \"+ path\" is a lie about a\n       * delete.\n       */\n      removed: string[];\n      /** Service ids split by whether this run created the directory. */\n      services: { created: string[]; existing: string[] };\n      recovered: CommitRecovery | null;\n    }\n  | {\n      ok: false;\n      code:\n        | \"docs-busy\"\n        | \"commit-interrupted\"\n        | \"merge-failed\"\n        | \"rollback-incomplete\"\n        | \"seed-landscape-edited\";\n      message: string;\n    }\n  /** The under-lock fleet-consistency preflight refusing; see `missingServices`. */\n  | { ok: false; code: \"seed-file-invalid\"; message: string; missingServices: string[] }\n  /** The docs repo went away between the command's gate and the locked read — new/commit.ts says why this is not a `code:` arm. */\n  | { ok: false; repoGone: DocsRepoUnavailableError };\n\nexport async function commitSeed(req: SeedCommitRequest): Promise<SeedCommit> {\n  const { docsDir } = req;\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, 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    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      return { ok: false, code: \"commit-interrupted\", message: err.message };\n    }\n\n    // Provenance first, then the tree: both read the repo as this run will\n    // leave it, and both refusals must prove nothing was written.\n    const landscape = await classifyLandscape(docsDir);\n    if (\"refusal\" in landscape) {\n      return { ok: false, code: \"seed-landscape-edited\", message: landscape.refusal };\n    }\n\n    let tree: FleetTree;\n    try {\n      tree = await listFleetTree(docsDir);\n    } catch (err) {\n      if (!(err instanceof DocsRepoUnavailableError)) throw err;\n      return { ok: false, repoGone: err };\n    }\n    const inconsistency = preflight(tree, req.seed);\n    if (inconsistency !== null) return inconsistency;\n\n    const plan = await planSeedWrites(req, tree);\n    const staged = await stageWrites(plan.writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"seed\", rerun: req.rerun, target: \"landscape\" },\n      staged,\n      \"seeded\",\n    );\n    if (!committed.ok) {\n      // `committed.raced` is deliberately NOT remapped: the lock serialises\n      // loam writers, so a fired CAS or a lost exclusive create here means an\n      // out-of-band editor, and seed has no softer race answer the way `new`\n      // has already-exists — merge-failed's \"nothing was written, re-run\" is\n      // the honest sentence either way.\n      return { ok: false, code: committed.code, message: committed.message };\n    }\n    return {\n      ok: true,\n      landscape: landscape.disposition,\n      written: plan.writes.filter((w) => w.content !== null).map((w) => w.path),\n      removed: plan.writes.filter((w) => w.content === null).map((w) => w.path),\n      services: plan.services,\n      recovered,\n    };\n  } finally {\n    await releaseLock();\n  }\n}\n\n/**\n * May seed write the landscape? Absent and untouched-scaffold-stub are the\n * two states with provably no human work in them; a matching stamp digest is\n * the third (`core/c4/seed/stamp.ts`). Everything else refuses.\n */\nasync function classifyLandscape(\n  docsDir: DocsDir,\n): Promise<{ disposition: LandscapeDisposition } | { refusal: string }> {\n  const path = landscapePath(docsDir);\n  if (!existsSync(path)) return { disposition: \"created\" };\n  const text = (await readFile(path)).toString(\"utf8\");\n  // `isLandscapeStub`, never a byte-compare of our own: that function IS the\n  // repo's answer to \"is this still the scaffold's untouched map\", it is what\n  // `loam status` reads before telling the reader to run seed, and it is\n  // suffix-matched and CRLF-normalised for two reasons seed shares —\n  // `migrate-openspec` prepends a preamble to the identical stub, and a\n  // checkout under `core.autocrlf` (Git for Windows' installer default)\n  // rewrites every line without touching a fact. A stricter compare here made\n  // status and seed contradict each other about the same file.\n  if (isLandscapeStub(text)) return { disposition: \"replaced-stub\" };\n  const provenance = landscapeProvenance(text);\n  if (provenance === \"seed-stamped\") return { disposition: \"regenerated\" };\n  return {\n    refusal:\n      `architecture/landscape.likec4 ${\n        provenance === \"seed-edited\"\n          ? \"was seeded but has been hand-edited since — the line-1 stamp's digest no longer matches the content\"\n          : \"was not written by `loam seed`: it carries no line-1 stamp and is not the scaffold's untouched stub\"\n      }. Seed never overwrites human work; nothing was written. Either fold the edits into ` +\n      `fleet.yaml and delete the file, then re-run — or keep the hand-authored map and stop ` +\n      `using seed here.`,\n  };\n}\n\n/**\n * The fleet-consistency preflight. Seed regenerates the landscape WHOLESALE —\n * that is the only posture the stamp can prove safe — so every existing\n * services/<id>/ must be named in fleet.yaml, or the regenerate would orphan\n * it into `landscape.service-unmodelled`. And the file's names must not\n * collide with what the tree already holds under a different kind: one flat\n * namespace, the same rule the walk enforces.\n */\nfunction preflight(tree: FleetTree, seed: FleetSeed): SeedCommit | null {\n  const treeSubs = new Set(tree.subsystems.map((s) => s.name));\n  const treeIds = new Set(tree.services.map((s) => s.id as string));\n\n  // The collision scan runs BEFORE the missing-service scan, and the order is\n  // load-bearing. A name the file declares as a subsystem or an external while\n  // the tree holds it as a service DIRECTORY is both facts at once: it is a\n  // namespace collision, and it is also an existing service the file does not\n  // name. With the missing scan first, the caller was told to paste that name\n  // into `services:` — advice that walks straight into `seed-duplicate-service`\n  // on the next run, because the file already declares it as something else.\n  const collisions: string[] = [];\n  for (const sub of seed.subsystems) {\n    if (treeIds.has(sub as string)) collisions.push(`subsystem '${sub}' is an existing service directory`);\n  }\n  for (const s of seed.services) {\n    if (treeSubs.has(s.id as string)) collisions.push(`service '${s.id}' is an existing subsystem directory`);\n  }\n  for (const x of seed.externals) {\n    if (treeIds.has(x)) collisions.push(`external '${x}' is an existing service directory`);\n    if (treeSubs.has(x)) collisions.push(`external '${x}' is an existing subsystem directory`);\n  }\n  if (collisions.length > 0) {\n    return {\n      ok: false,\n      code: \"seed-file-invalid\",\n      message:\n        `fleet.yaml collides with the services/ tree — service ids, subsystem names and externals ` +\n        `share one flat namespace: ${collisions.join(\"; \")}. Rename the fleet.yaml side (or the ` +\n        `directory, with \\`loam subsystem rename <from> <to>\\`), then re-run. Nothing was written.`,\n      missingServices: [],\n    };\n  }\n\n  const ids = new Set(seed.services.map((s) => s.id as string));\n  const missing = tree.services.map((s) => s.id as string).filter((id) => !ids.has(id)).sort();\n  if (missing.length === 0) return null;\n  // The ids are partitioned because one half cannot take the other's advice.\n  // `tree.services` carries RAW ids — a directory whose name fails the service\n  // grammar is still a service to the walk, by design — and \"add it to\n  // services: exactly as spelled\" is impossible for one of those: the fleet\n  // file would refuse the entry. Without this split, seed was simply unusable\n  // on such a repo and never said so.\n  const legal = missing.filter((id) => parseServiceId(id, \"services entry\").ok);\n  const illegal = missing.filter((id) => !parseServiceId(id, \"services entry\").ok);\n  const fixes: string[] = [];\n  if (legal.length > 0) fixes.push(`add ${legal.join(\", \")} to services:, exactly as spelled`);\n  if (illegal.length > 0) {\n    fixes.push(\n      `rename the ${illegal.length === 1 ? \"directory\" : \"directories\"} ${illegal.join(\", \")} ` +\n        `first — ${illegal.length === 1 ? \"that name is not a legal service id\" : \"those names are not legal service ids\"}, ` +\n        `so no services: entry can name ${illegal.length === 1 ? \"it\" : \"them\"}`,\n    );\n  }\n  return {\n    ok: false,\n    code: \"seed-file-invalid\",\n    message:\n      `fleet.yaml must name every existing service — seed regenerates the landscape wholesale, ` +\n      `and these services/ directories are not in it: ${missing.join(\", \")}. ` +\n      `To fix: ${fixes.join(\"; and \")}. Then re-run. Nothing was written.`,\n    missingServices: missing,\n  };\n}\n"]}

package/dist/commands/seed/plan.js

@@ -0,0 +1,133 @@
+/**
+ * What a seed run will write, decided in full before a byte lands. Split from
+ * `./commit.ts` on the phase seam: that module owns the WINDOW — the lock, the
+ * interrupted-commit recovery, the two refusals and the transaction — while
+ * this one answers the single question "given the tree as it is and the fleet
+ * file as it reads, which files change and how". Nothing here acquires
+ * anything, and nothing here writes: it is called under the lock and hands
+ * back a plan the transaction executes or rolls back whole.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { serviceDirOf } from "../../core/kernel/ids/dirs.js";
+import { landscapePath, servicePathsUnder, servicesDir, subsystemPathUnder, subsystemViewsPath, unfiledServicePaths, } from "../../core/repo/paths.js";
+import { SUBSYSTEM_MARKER } from "../../core/repo/tree/marker.js";
+import { renderSubsystemViews, viewsAgree } from "../../core/repo/tree/views.js";
+import { TEMP_FILE_RE } from "../../core/staging/commit.js";
+import { planWrite } from "../../core/staging/writes.js";
+/**
+ * Does this existing service directory hold nothing git would keep? An empty
+ * directory is a service to the walk but nothing at all to git, so a landscape
+ * declaring it clones into a repo where `validate --all` fails on a service
+ * that exists only on the author's disk. Seed's own crash window produces
+ * exactly this tree — `stageWrites` creates directories before the journal is
+ * written, so a kill in between leaves directories no recovery knows about —
+ * and so does a plain `mkdir`. Staging temps do not count as content: they are
+ * that same crash's litter, not somebody's file.
+ */
+async function keepsNothing(dir) {
+    try {
+        return (await readdir(dir)).every((entry) => TEMP_FILE_RE.test(entry));
+    }
+    catch {
+        // Unreadable is not empty: the walk found this directory a moment ago, and
+        // inventing a write into a directory we cannot list is the wrong guess.
+        return false;
+    }
+}
+/**
+ * The complete plan, in memory, before a byte lands: the sealed landscape, one
+ * marker per NEW subsystem, one `.gitkeep` per service directory this commit
+ * creates — and per existing one holding nothing git would keep (see
+ * `keepsNothing`) — and the generated views file rendered from the tree AS
+ * THIS COMMIT LEAVES IT, never from a re-walk between two states
+ * (commands/subsystem/txn/views.ts's `movedTree` doctrine). That last one is
+ * the only write that can be a DELETE: a tree with no subsystems owes no views
+ * file, and a leftover is a finding.
+ *
+ * Existing directories are never moved: fleet.yaml's placement is ignored for
+ * a service that already exists — moving is `loam subsystem move <id> --into
+ * <name>`'s job, under its own guards — and nothing anywhere is deleted except
+ * that one generated file.
+ */
+export async function planSeedWrites(req, tree) {
+    const { docsDir, seed } = req;
+    const writes = [planWrite(landscapePath(docsDir), req.landscape)];
+    const existingSubs = new Map(tree.subsystems.map((s) => [s.name, s]));
+    const newSubs = [];
+    for (const sub of seed.subsystems) {
+        if (existingSubs.has(sub))
+            continue;
+        const dir = subsystemPathUnder(servicesDir(docsDir), sub);
+        // A comment line parses to null — a valid empty marker (tree/marker.ts).
+        writes.push(planWrite(join(dir, SUBSYSTEM_MARKER), "# subsystem marker\n"));
+        newSubs.push({ name: sub, path: [sub], dir, meta: {} });
+    }
+    const treeDirs = new Map(tree.services.map((s) => [s.id, s.dir]));
+    // Every existing directory inspected at once — independent reads, so the
+    // loop below stays synchronous.
+    const invisible = new Map(await Promise.all([...treeDirs].map(async ([id, dir]) => [id, await keepsNothing(dir)])));
+    const created = [];
+    const existing = [];
+    const newWalked = [];
+    for (const s of seed.services) {
+        const already = treeDirs.get(s.id);
+        if (already !== undefined) {
+            existing.push(s.id);
+            // Existing, but git-invisible: give it the `.gitkeep` a created service
+            // gets, or the landscape about to be written declares a directory the
+            // next clone will not have. `planWrite` makes this a no-op when the file
+            // is already there, so a real service is never touched.
+            if (invisible.get(s.id) === true)
+                writes.push(planWrite(join(already, ".gitkeep"), ""));
+            continue;
+        }
+        created.push(s.id);
+        const parent = s.subsystem === null ? null : existingSubs.get(s.subsystem) ?? null;
+        const dir = s.subsystem === null
+            ? unfiledServicePaths(docsDir, s.id).dir
+            : parent !== null
+                ? servicePathsUnder(parent.dir, s.id).dir
+                : // A subsystem this same commit creates: the creation spelling,
+                    // through the same branded joins the subsystem verbs use.
+                    serviceDirOf(join(subsystemPathUnder(servicesDir(docsDir), s.subsystem), s.id));
+        writes.push(planWrite(join(dir, ".gitkeep"), ""));
+        newWalked.push({
+            // A ServiceId IS a RawServiceId (the checked subtype), so no re-cast.
+            id: s.id,
+            dir,
+            subsystem: s.subsystem === null ? [] : parent !== null ? parent.path : [s.subsystem],
+        });
+    }
+    const plannedTree = {
+        findings: [],
+        services: [...tree.services, ...newWalked],
+        subsystems: [...tree.subsystems, ...newSubs],
+    };
+    // The generated views file, including its ABSENCE. `renderSubsystemViews`
+    // returning null means the tree has no subsystems, and its contract is that
+    // the file must then not exist — `validate` grades a leftover as
+    // `subsystem.views-stale`, so a seed that ignored the file would exit 0 and
+    // send the caller, via its own `next` list, into a failing gate over a file
+    // it had in hand. `content: null` is the delete the transaction understands
+    // (commands/subsystem/txn/txn.ts's `"removed"`), and a file that already
+    // SAYS this is left out of the journal entirely rather than written back
+    // over itself.
+    //
+    // "Already says this" is content, not bytes: `viewsAgree` performs the
+    // comparison and records the Windows reason for it, beside the generator
+    // that mints the bytes. What gets WRITTEN is unchanged — the LF render, as a
+    // Buffer — so this decode is a comparison only, never the string round trip
+    // to disk that writes.ts forbids; a views file whose bytes are not UTF-8
+    // therefore fails the compare and is regenerated, which is the right answer
+    // for it anyway.
+    const viewsPath = subsystemViewsPath(docsDir);
+    const views = renderSubsystemViews(plannedTree, req.elements);
+    const wanted = views === null ? null : Buffer.from(views, "utf8");
+    const onDisk = existsSync(viewsPath) ? await readFile(viewsPath, "utf8") : null;
+    if (!viewsAgree(onDisk, views))
+        writes.push({ path: viewsPath, content: wanted });
+    return { writes, services: { created: created.sort(), existing: existing.sort() } };
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/seed/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/commands/seed/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a seed run will write, decided in full before a byte lands. Split from\n * `./commit.ts` on the phase seam: that module owns the WINDOW — the lock, the\n * interrupted-commit recovery, the two refusals and the transaction — while\n * this one answers the single question \"given the tree as it is and the fleet\n * file as it reads, which files change and how\". Nothing here acquires\n * anything, and nothing here writes: it is called under the lock and hands\n * back a plan the transaction executes or rolls back whole.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { Elem } from \"../../core/c4/likec4.js\";\nimport type { FleetSeed } from \"../../core/c4/seed/fleet-file.js\";\nimport { serviceDirOf, type DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport {\n  landscapePath,\n  servicePathsUnder,\n  servicesDir,\n  subsystemPathUnder,\n  subsystemViewsPath,\n  unfiledServicePaths,\n} from \"../../core/repo/paths.js\";\nimport { SUBSYSTEM_MARKER } from \"../../core/repo/tree/marker.js\";\nimport { renderSubsystemViews, viewsAgree } from \"../../core/repo/tree/views.js\";\nimport type { FleetTree, SubsystemEntry, WalkedService } from \"../../core/repo/tree/walk.js\";\nimport { TEMP_FILE_RE } from \"../../core/staging/commit.js\";\nimport { planWrite, type PlannedWrite } from \"../../core/staging/writes.js\";\n\n/** Everything the plan reads. The commit request extends this and adds only `rerun`. */\nexport interface SeedPlanInput {\n  docsDir: DocsDir;\n  seed: FleetSeed;\n  /** The sealed landscape text (stamp on line 1), already proven to parse. */\n  landscape: string;\n  /**\n   * That same text's parsed elements — the loadSource self-check's output,\n   * reused for the views join so the generated views file agrees byte for byte\n   * with what `validate --all` will recompute from the committed landscape.\n   */\n  elements: Elem[];\n}\n\nexport interface SeedPlan {\n  writes: PlannedWrite[];\n  /** Service ids split by whether this run creates the directory. */\n  services: { created: string[]; existing: string[] };\n}\n\n/**\n * Does this existing service directory hold nothing git would keep? An empty\n * directory is a service to the walk but nothing at all to git, so a landscape\n * declaring it clones into a repo where `validate --all` fails on a service\n * that exists only on the author's disk. Seed's own crash window produces\n * exactly this tree — `stageWrites` creates directories before the journal is\n * written, so a kill in between leaves directories no recovery knows about —\n * and so does a plain `mkdir`. Staging temps do not count as content: they are\n * that same crash's litter, not somebody's file.\n */\nasync function keepsNothing(dir: string): Promise<boolean> {\n  try {\n    return (await readdir(dir)).every((entry) => TEMP_FILE_RE.test(entry));\n  } catch {\n    // Unreadable is not empty: the walk found this directory a moment ago, and\n    // inventing a write into a directory we cannot list is the wrong guess.\n    return false;\n  }\n}\n\n/**\n * The complete plan, in memory, before a byte lands: the sealed landscape, one\n * marker per NEW subsystem, one `.gitkeep` per service directory this commit\n * creates — and per existing one holding nothing git would keep (see\n * `keepsNothing`) — and the generated views file rendered from the tree AS\n * THIS COMMIT LEAVES IT, never from a re-walk between two states\n * (commands/subsystem/txn/views.ts's `movedTree` doctrine). That last one is\n * the only write that can be a DELETE: a tree with no subsystems owes no views\n * file, and a leftover is a finding.\n *\n * Existing directories are never moved: fleet.yaml's placement is ignored for\n * a service that already exists — moving is `loam subsystem move <id> --into\n * <name>`'s job, under its own guards — and nothing anywhere is deleted except\n * that one generated file.\n */\nexport async function planSeedWrites(req: SeedPlanInput, tree: FleetTree): Promise<SeedPlan> {\n  const { docsDir, seed } = req;\n  const writes: PlannedWrite[] = [planWrite(landscapePath(docsDir), req.landscape)];\n\n  const existingSubs = new Map(tree.subsystems.map((s) => [s.name, s]));\n  const newSubs: SubsystemEntry[] = [];\n  for (const sub of seed.subsystems) {\n    if (existingSubs.has(sub as string)) continue;\n    const dir = subsystemPathUnder(servicesDir(docsDir), sub);\n    // A comment line parses to null — a valid empty marker (tree/marker.ts).\n    writes.push(planWrite(join(dir, SUBSYSTEM_MARKER), \"# subsystem marker\\n\"));\n    newSubs.push({ name: sub as string, path: [sub as string], dir, meta: {} });\n  }\n\n  const treeDirs = new Map(tree.services.map((s) => [s.id as string, s.dir]));\n  // Every existing directory inspected at once — independent reads, so the\n  // loop below stays synchronous.\n  const invisible = new Map(\n    await Promise.all([...treeDirs].map(async ([id, dir]) => [id, await keepsNothing(dir)] as const)),\n  );\n  const created: string[] = [];\n  const existing: string[] = [];\n  const newWalked: WalkedService[] = [];\n  for (const s of seed.services) {\n    const already = treeDirs.get(s.id as string);\n    if (already !== undefined) {\n      existing.push(s.id);\n      // Existing, but git-invisible: give it the `.gitkeep` a created service\n      // gets, or the landscape about to be written declares a directory the\n      // next clone will not have. `planWrite` makes this a no-op when the file\n      // is already there, so a real service is never touched.\n      if (invisible.get(s.id as string) === true) writes.push(planWrite(join(already, \".gitkeep\"), \"\"));\n      continue;\n    }\n    created.push(s.id);\n    const parent = s.subsystem === null ? null : existingSubs.get(s.subsystem as string) ?? null;\n    const dir =\n      s.subsystem === null\n        ? unfiledServicePaths(docsDir, s.id).dir\n        : parent !== null\n          ? servicePathsUnder(parent.dir, s.id).dir\n          : // A subsystem this same commit creates: the creation spelling,\n            // through the same branded joins the subsystem verbs use.\n            serviceDirOf(join(subsystemPathUnder(servicesDir(docsDir), s.subsystem), s.id));\n    writes.push(planWrite(join(dir, \".gitkeep\"), \"\"));\n    newWalked.push({\n      // A ServiceId IS a RawServiceId (the checked subtype), so no re-cast.\n      id: s.id,\n      dir,\n      subsystem: s.subsystem === null ? [] : parent !== null ? parent.path : [s.subsystem as string],\n    });\n  }\n\n  const plannedTree: FleetTree = {\n    findings: [],\n    services: [...tree.services, ...newWalked],\n    subsystems: [...tree.subsystems, ...newSubs],\n  };\n  // The generated views file, including its ABSENCE. `renderSubsystemViews`\n  // returning null means the tree has no subsystems, and its contract is that\n  // the file must then not exist — `validate` grades a leftover as\n  // `subsystem.views-stale`, so a seed that ignored the file would exit 0 and\n  // send the caller, via its own `next` list, into a failing gate over a file\n  // it had in hand. `content: null` is the delete the transaction understands\n  // (commands/subsystem/txn/txn.ts's `\"removed\"`), and a file that already\n  // SAYS this is left out of the journal entirely rather than written back\n  // over itself.\n  //\n  // \"Already says this\" is content, not bytes: `viewsAgree` performs the\n  // comparison and records the Windows reason for it, beside the generator\n  // that mints the bytes. What gets WRITTEN is unchanged — the LF render, as a\n  // Buffer — so this decode is a comparison only, never the string round trip\n  // to disk that writes.ts forbids; a views file whose bytes are not UTF-8\n  // therefore fails the compare and is regenerated, which is the right answer\n  // for it anyway.\n  const viewsPath = subsystemViewsPath(docsDir);\n  const views = renderSubsystemViews(plannedTree, req.elements);\n  const wanted = views === null ? null : Buffer.from(views, \"utf8\");\n  const onDisk = existsSync(viewsPath) ? await readFile(viewsPath, \"utf8\") : null;\n  if (!viewsAgree(onDisk, views)) writes.push({ path: viewsPath, content: wanted });\n\n  return { writes, services: { created: created.sort(), existing: existing.sort() } };\n}\n"]}

package/dist/commands/seed/seed.js

@@ -0,0 +1,172 @@
+import { resolve } from "node:path";
+import { loadSource } from "../../core/c4/likec4.js";
+import { readFleetFile } from "../../core/c4/seed/fleet-file.js";
+import { sealLandscape } from "../../core/c4/seed/stamp.js";
+import { renderLandscape } from "../../core/c4/seed/template.js";
+import { loadConfig } from "../../core/envelope/config.js";
+import { emitJson, emitJsonError, fail, repoPath, reportNoConfig } from "../../core/envelope/json.js";
+import { NotUtf8Error, readUtf8 } from "../../core/staging/writes.js";
+import { sayRecovered } from "../policy/format.js";
+import { docsRepoReady, reportDocsRepoError } from "../policy/gate.js";
+import { serviceTreePathOf } from "../../core/repo/service-target.js";
+import { commitSeed } from "./commit.js";
+export function registerSeed(program) {
+    program
+        .command("seed")
+        .description("Template the fleet map and service directories from a tiny human-authored fleet.yaml")
+        .option("--from <file>", "the fleet file to read (default: fleet.yaml in the current directory)")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts) => {
+        const json = opts.json === true;
+        const fromArg = opts.from ?? "fleet.yaml";
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const { docsDir } = loaded.config;
+        // `services`, not `docs`: every id in fleet.yaml becomes a
+        // services/<id>/ directory, and the under-lock preflight enumerates the
+        // tree — a run without the directory that IS the fleet is guessing.
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        // The fleet file is INPUT only — read once, from wherever the caller
+        // keeps it (it may legitimately live outside both repos), never stored
+        // and never written back. Refusals name the spelling the caller typed.
+        let text;
+        try {
+            text = await readUtf8(resolve(fromArg));
+        }
+        catch (err) {
+            if (err instanceof NotUtf8Error)
+                return fail(json, "seed-file-invalid", err.message);
+            const e = err;
+            if (e.code === "ENOENT") {
+                return fail(json, "seed-file-invalid", `${fromArg} does not exist — write the fleet file (a services: list of ids, plus ` +
+                    `optional subsystems:, externals: and calls: like 'checkout -> payments'), or ` +
+                    `point --from at where it lives. Nothing was written.`);
+            }
+            // An errno is a filesystem answer (EISDIR, EACCES, …) about the named
+            // file; anything without one is a real bug and stays `internal`.
+            if (e.path !== undefined || typeof e.errno === "number") {
+                return fail(json, "seed-file-invalid", `${fromArg} could not be read as the fleet file — ${e.message}. Nothing was written.`);
+            }
+            throw err;
+        }
+        const read = readFleetFile(text, fromArg);
+        if (!read.ok)
+            return refuseFleetFile(json, read.problem);
+        const seed = read.seed;
+        // The self-check: the emitted DSL is parsed in memory BEFORE anything
+        // is written, so a templater bug can never land as a broken landscape.
+        // Its parsed elements are reused for the generated views join.
+        const sealed = sealLandscape(renderLandscape(seed));
+        const doc = await loadSource(sealed);
+        const firstError = doc.errors[0];
+        if (firstError !== undefined) {
+            return fail(json, "internal", `loam's own templater produced a landscape that does not parse — a bug in loam, not ` +
+                `in ${fromArg}; nothing was written. First error: ${firstError.message}`);
+        }
+        const committed = await commitSeed({
+            docsDir,
+            seed,
+            landscape: sealed,
+            elements: doc.elements,
+            rerun: `loam seed --from ${fromArg}`,
+        });
+        if (!committed.ok)
+            return refuseCommit(json, committed);
+        const written = committed.written.map((w) => repoPath(docsDir, w));
+        const removed = committed.removed.map((w) => repoPath(docsDir, w));
+        const firstCreated = committed.services.created[0];
+        const next = [
+            "loam validate --all",
+            "loam list --needs-work",
+            // Interpolation is agent-safe: the id already passed the grammar.
+            ...(firstCreated === undefined ? [] : [`loam adopt --service ${firstCreated}`]),
+        ];
+        if (json) {
+            emitJson({
+                command: "seed",
+                fleetFile: fromArg,
+                landscape: committed.landscape,
+                created: written,
+                removed,
+                services: committed.services,
+                subsystems: [...seed.subsystems].sort(),
+                externals: [...seed.externals].sort(),
+                calls: seed.calls.length,
+                next,
+                ...(committed.recovered === null ? {} : { recovered: committed.recovered }),
+            });
+            return;
+        }
+        if (committed.recovered !== null && committed.recovered.outcome !== "consistent") {
+            console.log(`note: ${sayRecovered(committed.recovered)}`);
+        }
+        console.log(`architecture/landscape.likec4 ${LANDSCAPE_SENTENCE[committed.landscape]} — ` +
+            `${seed.services.length} service(s), ${seed.calls.length} call(s), from ${fromArg}`);
+        for (const w of written)
+            console.log(`  + ${w}`);
+        // Only ever the generated views file, and only when the resulting tree
+        // has no subsystems left to view — but a removal printed as `+` would be
+        // a lie, and an unmentioned one a surprise in `git status`.
+        for (const w of removed)
+            console.log(`  - ${w} (generated, and this tree has no subsystems)`);
+        for (const id of committed.services.existing) {
+            // Spelled from the enumeration, and this line is the one place it matters
+            // most: the sentence is ABOUT placement, so naming the root form would
+            // say "left exactly where it is" while pointing at somewhere it is not.
+            const at = await serviceTreePathOf(docsDir, id);
+            console.log(`  = ${at}/ already exists — left exactly where it is (fleet.yaml's ` +
+                `placement is ignored for an existing service; \`loam subsystem move ${id} ` +
+                `--into <name>\` is how one moves)`);
+        }
+        console.log("\nNext:");
+        for (const n of next)
+            console.log(`  ${n}`);
+    });
+}
+const LANDSCAPE_SENTENCE = {
+    created: "created",
+    "replaced-stub": "written (replaced the scaffold's untouched stub)",
+    regenerated: "regenerated (the line-1 stamp proved no hand edits)",
+};
+/** One stable code per problem kind — the mapping the fleet-file union exists for. */
+function refuseFleetFile(json, problem) {
+    switch (problem.kind) {
+        case "invalid":
+            return fail(json, "seed-file-invalid", problem.message);
+        case "duplicate":
+            return fail(json, "seed-duplicate-service", problem.message);
+        case "unknown-subsystem":
+            return fail(json, "seed-unknown-subsystem", problem.message);
+        case "unknown-endpoint":
+            // The existing code, not a fifth new one: the caller's action is the
+            // same as for every other unknown service — fix the name, re-run.
+            return fail(json, "unknown-service", problem.message);
+    }
+    // Exhaustiveness checked, not assumed, and the branch is genuinely dead:
+    // without it a fifth `kind` falls out of the switch printing nothing and
+    // leaving `process.exitCode` unset — a refused fleet file exiting 0, which
+    // is the worst answer available.
+    const unreachable = problem;
+    throw new Error(`refuseFleetFile: no code for fleet-file problem '${JSON.stringify(unreachable)}'`);
+}
+function refuseCommit(json, committed) {
+    if ("repoGone" in committed)
+        return reportDocsRepoError(json, committed.repoGone);
+    if (committed.code === "seed-file-invalid") {
+        // The exact ids to paste ride as data beside the prose, so an agent can
+        // repair fleet.yaml without parsing a sentence.
+        if (json) {
+            emitJsonError("seed-file-invalid", committed.message, {
+                missingServices: committed.missingServices,
+            });
+            return;
+        }
+        return fail(json, "seed-file-invalid", committed.message);
+    }
+    return fail(json, committed.code, committed.message);
+}
+//# sourceMappingURL=seed.js.map

package/dist/commands/seed/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../src/commands/seed/seed.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam seed` — the fleet map's first hour, mechanically: a tiny\n * human-authored fleet.yaml (service ids, optional subsystems, externals and\n * `a -> b` calls) templated into architecture/landscape.likec4 plus one\n * services/<id>/ directory per service, in one journaled transaction.\n *\n * NOT an extractor, deliberately: a human stated every fact in the file —\n * which services exist and who calls whom is the one thing no generator can\n * read off a repository (core/docs.ts's landscape doctrine) — and loam does\n * mechanical templating over those statements, the same category as\n * `loam new`. Seed never overwrites human work: it writes the landscape only\n * when the file is absent, is the scaffold's untouched stub, or carries its\n * own verified line-1 stamp (`core/c4/seed/stamp.ts`); everything else\n * refuses `seed-landscape-edited`.\n */\nimport type { Command } from \"commander\";\nimport { resolve } from \"node:path\";\nimport { loadSource } from \"../../core/c4/likec4.js\";\nimport { readFleetFile, type SeedFileProblem } from \"../../core/c4/seed/fleet-file.js\";\nimport { sealLandscape } from \"../../core/c4/seed/stamp.js\";\nimport { renderLandscape } from \"../../core/c4/seed/template.js\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, emitJsonError, fail, repoPath, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { NotUtf8Error, readUtf8 } from \"../../core/staging/writes.js\";\nimport { sayRecovered } from \"../policy/format.js\";\nimport { docsRepoReady, reportDocsRepoError } from \"../policy/gate.js\";\nimport { serviceTreePathOf } from \"../../core/repo/service-target.js\";\nimport { commitSeed, type LandscapeDisposition, type SeedCommit } from \"./commit.js\";\n\ninterface SeedOptions {\n  from?: string;\n  json?: boolean;\n}\n\nexport function registerSeed(program: Command): void {\n  program\n    .command(\"seed\")\n    .description(\n      \"Template the fleet map and service directories from a tiny human-authored fleet.yaml\",\n    )\n    .option(\"--from <file>\", \"the fleet file to read (default: fleet.yaml in the current directory)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: SeedOptions) => {\n      const json = opts.json === true;\n      const fromArg = opts.from ?? \"fleet.yaml\";\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const { docsDir } = loaded.config;\n      // `services`, not `docs`: every id in fleet.yaml becomes a\n      // services/<id>/ directory, and the under-lock preflight enumerates the\n      // tree — a run without the directory that IS the fleet is guessing.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      // The fleet file is INPUT only — read once, from wherever the caller\n      // keeps it (it may legitimately live outside both repos), never stored\n      // and never written back. Refusals name the spelling the caller typed.\n      let text: string;\n      try {\n        text = await readUtf8(resolve(fromArg));\n      } catch (err) {\n        if (err instanceof NotUtf8Error) return fail(json, \"seed-file-invalid\", err.message);\n        const e = err as NodeJS.ErrnoException;\n        if (e.code === \"ENOENT\") {\n          return fail(\n            json,\n            \"seed-file-invalid\",\n            `${fromArg} does not exist — write the fleet file (a services: list of ids, plus ` +\n              `optional subsystems:, externals: and calls: like 'checkout -> payments'), or ` +\n              `point --from at where it lives. Nothing was written.`,\n          );\n        }\n        // An errno is a filesystem answer (EISDIR, EACCES, …) about the named\n        // file; anything without one is a real bug and stays `internal`.\n        if (e.path !== undefined || typeof e.errno === \"number\") {\n          return fail(\n            json,\n            \"seed-file-invalid\",\n            `${fromArg} could not be read as the fleet file — ${e.message}. Nothing was written.`,\n          );\n        }\n        throw err;\n      }\n\n      const read = readFleetFile(text, fromArg);\n      if (!read.ok) return refuseFleetFile(json, read.problem);\n      const seed = read.seed;\n\n      // The self-check: the emitted DSL is parsed in memory BEFORE anything\n      // is written, so a templater bug can never land as a broken landscape.\n      // Its parsed elements are reused for the generated views join.\n      const sealed = sealLandscape(renderLandscape(seed));\n      const doc = await loadSource(sealed);\n      const firstError = doc.errors[0];\n      if (firstError !== undefined) {\n        return fail(\n          json,\n          \"internal\",\n          `loam's own templater produced a landscape that does not parse — a bug in loam, not ` +\n            `in ${fromArg}; nothing was written. First error: ${firstError.message}`,\n        );\n      }\n\n      const committed = await commitSeed({\n        docsDir,\n        seed,\n        landscape: sealed,\n        elements: doc.elements,\n        rerun: `loam seed --from ${fromArg}`,\n      });\n      if (!committed.ok) return refuseCommit(json, committed);\n\n      const written = committed.written.map((w) => repoPath(docsDir, w));\n      const removed = committed.removed.map((w) => repoPath(docsDir, w));\n      const firstCreated = committed.services.created[0];\n      const next = [\n        \"loam validate --all\",\n        \"loam list --needs-work\",\n        // Interpolation is agent-safe: the id already passed the grammar.\n        ...(firstCreated === undefined ? [] : [`loam adopt --service ${firstCreated}`]),\n      ];\n\n      if (json) {\n        emitJson({\n          command: \"seed\",\n          fleetFile: fromArg,\n          landscape: committed.landscape,\n          created: written,\n          removed,\n          services: committed.services,\n          subsystems: [...seed.subsystems].sort(),\n          externals: [...seed.externals].sort(),\n          calls: seed.calls.length,\n          next,\n          ...(committed.recovered === null ? {} : { recovered: committed.recovered }),\n        });\n        return;\n      }\n      if (committed.recovered !== null && committed.recovered.outcome !== \"consistent\") {\n        console.log(`note: ${sayRecovered(committed.recovered)}`);\n      }\n      console.log(\n        `architecture/landscape.likec4 ${LANDSCAPE_SENTENCE[committed.landscape]} — ` +\n          `${seed.services.length} service(s), ${seed.calls.length} call(s), from ${fromArg}`,\n      );\n      for (const w of written) console.log(`  + ${w}`);\n      // Only ever the generated views file, and only when the resulting tree\n      // has no subsystems left to view — but a removal printed as `+` would be\n      // a lie, and an unmentioned one a surprise in `git status`.\n      for (const w of removed) console.log(`  - ${w} (generated, and this tree has no subsystems)`);\n      for (const id of committed.services.existing) {\n        // Spelled from the enumeration, and this line is the one place it matters\n        // most: the sentence is ABOUT placement, so naming the root form would\n        // say \"left exactly where it is\" while pointing at somewhere it is not.\n        const at = await serviceTreePathOf(docsDir, id);\n        console.log(\n          `  = ${at}/ already exists — left exactly where it is (fleet.yaml's ` +\n            `placement is ignored for an existing service; \\`loam subsystem move ${id} ` +\n            `--into <name>\\` is how one moves)`,\n        );\n      }\n      console.log(\"\\nNext:\");\n      for (const n of next) console.log(`  ${n}`);\n    });\n}\n\nconst LANDSCAPE_SENTENCE: Record<LandscapeDisposition, string> = {\n  created: \"created\",\n  \"replaced-stub\": \"written (replaced the scaffold's untouched stub)\",\n  regenerated: \"regenerated (the line-1 stamp proved no hand edits)\",\n};\n\n/** One stable code per problem kind — the mapping the fleet-file union exists for. */\nfunction refuseFleetFile(json: boolean, problem: SeedFileProblem): void {\n  switch (problem.kind) {\n    case \"invalid\":\n      return fail(json, \"seed-file-invalid\", problem.message);\n    case \"duplicate\":\n      return fail(json, \"seed-duplicate-service\", problem.message);\n    case \"unknown-subsystem\":\n      return fail(json, \"seed-unknown-subsystem\", problem.message);\n    case \"unknown-endpoint\":\n      // The existing code, not a fifth new one: the caller's action is the\n      // same as for every other unknown service — fix the name, re-run.\n      return fail(json, \"unknown-service\", problem.message);\n  }\n  // Exhaustiveness checked, not assumed, and the branch is genuinely dead:\n  // without it a fifth `kind` falls out of the switch printing nothing and\n  // leaving `process.exitCode` unset — a refused fleet file exiting 0, which\n  // is the worst answer available.\n  const unreachable: never = problem;\n  throw new Error(`refuseFleetFile: no code for fleet-file problem '${JSON.stringify(unreachable)}'`);\n}\n\nfunction refuseCommit(json: boolean, committed: Exclude<SeedCommit, { ok: true }>): void {\n  if (\"repoGone\" in committed) return reportDocsRepoError(json, committed.repoGone);\n  if (committed.code === \"seed-file-invalid\") {\n    // The exact ids to paste ride as data beside the prose, so an agent can\n    // repair fleet.yaml without parsing a sentence.\n    if (json) {\n      emitJsonError(\"seed-file-invalid\", committed.message, {\n        missingServices: committed.missingServices,\n      });\n      return;\n    }\n    return fail(json, \"seed-file-invalid\", committed.message);\n  }\n  return fail(json, committed.code, committed.message);\n}\n"]}