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

package/dist/commands/archive/plan/landscape.js

@@ -0,0 +1,298 @@
+/**
+ * The fleet map merge, the flows drawn over it, and the services this archive
+ * brings into existence.
+ *
+ * The landscape is the one document every feature writes into, so it is spliced
+ * rather than rewritten: the authored file keeps its shape and the delta's
+ * elements are placed into it. A service arriving on the architecture axis alone
+ * has no `model.likec4` yet, and the finding for that is carried out of the plan
+ * — `validate` would report it next, at the same severity, and reporting it here
+ * is what stops that being a surprise.
+ *
+ * The map is not the only document the C4 axis writes. What a delta nests
+ * INSIDE a service belongs to that service's `model.likec4` when the model
+ * extends the map — the splicer routes it there, this stages the write, and
+ * `./model/extending.ts` proves the result parses beside the merged map before
+ * anything lands.
+ *
+ * `planFlows` at the bottom is the other half of the same axis and shares this
+ * module for that reason rather than for the file cap: both write into
+ * `architecture/`, and the two merges are read together — the map gains the
+ * elements, the flow gains the ordered hops over them. It is a whole-file copy
+ * where the landscape is a splice, because a flow is a document of its own and
+ * there is nothing to merge partially.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { planWrite, readUtf8 } from "../../../core/staging/writes.js";
+import { planLandscapeMerge } from "../../../core/c4/splice/landscape-merge.js";
+import { spliceModel } from "../../../core/c4/splice/model/merge.js";
+import { titleOf } from "../../../core/c4/splice/identity/edges.js";
+import { parseServiceId } from "../../../core/kernel/ids/service.js";
+import { isPathInside } from "../../../core/kernel/path-safety.js";
+import { landscapePath as landscapeFile, unfiledServicePaths } from "../../../core/repo/paths.js";
+import { enumeratedServiceIds } from "../../../core/repo/service-target.js";
+import { createdServiceModels } from "../../../core/c4/service-model/created/models.js";
+import { extendingModels } from "../../../core/c4/service-model/fleet/extending.js";
+import { modelMergeErrors } from "./model/extending.js";
+import {} from "./state.js";
+import { CodedFailure } from "../../../core/envelope/json.js";
+import { featurePaths } from "../../../core/repo/paths.js";
+import { featureFlows, livingFlowPath, USECASE_SUBDIR } from "../../../core/usecases/delta/flows.js";
+import { featureDeployments, livingDeploymentPath } from "../../../core/deployment/delta.js";
+export async function planLandscape(config, gated, plan, say) {
+    const { id, featureDir, deltaDoc, deltaServices } = gated;
+    const deltaLikec4 = featurePaths(featureDir).delta;
+    const { writes, planWarns, architectureServices } = plan;
+    const landscapePath = landscapeFile(config.docsDir);
+    // "New" is enumeration membership, not an existsSync of services/<svc>/ at
+    // the root: a FILED service exists wherever the tree walk found it, and the
+    // root probe would grade every filed service as newly created here.
+    const enumerated = new Set(await enumeratedServiceIds(config.docsDir));
+    // The empty extending model of every service this archive creates and the
+    // merged map draws — the rule, and the case for writing it, are
+    // `createdServiceModels`'s. With no delta or no map there is no merge, and
+    // no model.
+    const fresh = deltaDoc === undefined || !existsSync(landscapePath)
+        ? []
+        : await createdServiceModels({
+            docsDir: config.docsDir,
+            featureDir,
+            featureId: id,
+            drawn: [...(await config.fleet.loadLikeC4(landscapePath)).elements, ...deltaDoc.elements.filter((e) => e.tags.includes(id))],
+            fleet: config.fleet,
+        });
+    // The services that leave this archive with a model.likec4 it wrote.
+    const modelled = new Set();
+    if (deltaDoc !== undefined) {
+        const delta = deltaDoc;
+        if (delta.errors.length > 0) {
+            // --approve overrides loam's JUDGMENT about coherence, never its ability to
+            // read an axis. Skipping here would silently drop one merge axis in the one
+            // command engineered against quiet partial merges — same rule as an
+            // unparseable landscape or openapi: the plan stops before anything is written.
+            throw new CodedFailure("merge-failed", `delta.likec4 has ${delta.errors.length} parse error(s) — the architecture axis cannot be merged; fix it (\`loam validate --feature ${id}\`) or delete the file`);
+        }
+        // The feature tag is the whole selection mechanism of this merge, and since
+        // LikeC4 1.59.0 a specification KIND can carry a tag that every element or
+        // edge of that kind then inherits. A delta declaring its own feature tag on
+        // a kind makes `newEls`/`newRels` below select the entire document —
+        // including the context declarations the scaffold ships commented out
+        // precisely so they are NOT merged — and archive would splice somebody
+        // else's services into the fleet map at exit 0. Mechanical, so `--approve`
+        // does not reach it, and refused before the merge is even planned.
+        const kindTagged = [
+            ...Object.entries(delta.specification?.elementKindTags ?? {}),
+            ...Object.entries(delta.specification?.relationshipKindTags ?? {}),
+        ].find(([, tags]) => tags.includes(id));
+        if (kindTagged !== undefined) {
+            throw new CodedFailure("merge-failed", `delta.likec4 declares the feature tag '#${id}' on kind '${kindTagged[0]}' in its specification block, so every ` +
+                `'${kindTagged[0]}' in the file inherits it — the merge would treat the whole document as this feature's ` +
+                `additions, context elements included, and splice them into architecture/landscape.likec4. Nothing was ` +
+                `written. Remove '#${id}' from the kind and tag only the declarations ${id} actually adds.`);
+        }
+        const newEls = delta.elements.filter((e) => e.tags.includes(id));
+        const newRels = delta.relationships.filter((r) => r.tags.includes(id));
+        if (existsSync(landscapePath)) {
+            const deltaText = await readUtf8(deltaLikec4);
+            const plan = await planLandscapeMerge({
+                landscapeText: await readUtf8(landscapePath),
+                deltaText,
+                deltaElements: delta.elements,
+                newEls,
+                newRels,
+                featureId: id,
+                // The tags a relationship kind gives every edge of it: the parsed
+                // additions carry them, the delta's statements do not.
+                deltaKindTags: delta.specification?.relationshipKindTags ?? {},
+                // A service whose model EXTENDS the map owns its own interior, so the
+                // merge routes what is nested under it into that model instead of the
+                // map (verification 2026-09-04, E1) — and so does a service this
+                // archive creates, whose model is written below.
+                models: [...(await extendingModels(config.docsDir, config.fleet)), ...fresh],
+            });
+            // A service can arrive on the ARCHITECTURE axis alone: an element this
+            // merge ADDS, carrying a `metadata { service }` binding, with no
+            // `specs/<svc>/` anywhere in the feature. It is a service the fleet gate
+            // will demand a directory for the moment this merge lands, so it owes the
+            // same warning as one arriving with a requirement delta — and until it
+            // did, the closing "complete + current" line printed over a landscape
+            // this very archive had just made red. Read off the ADDED elements, not
+            // the tagged ones: an element the living landscape already had is not
+            // arriving, and one that is never merged is not there to demand anything.
+            // A binding is document text, which the service path builders no longer accept.
+            // The parse cannot actually filter anything here: an illegal binding is
+            // `c4.service-binding-invalid`, a coherence ERROR `--approve` does not
+            // override, refused before any merge is planned — so the `ok` test only
+            // carries the compiler's proof that document text never reaches a path.
+            for (const e of plan.addedEls) {
+                const parsed = e.service === undefined ? undefined : parseServiceId(e.service);
+                if (parsed?.ok === true)
+                    architectureServices.add(parsed.id);
+            }
+            if (plan.content !== null)
+                writes.push(planWrite(landscapePath, plan.content));
+            say(`\n  architecture: merged into landscape.likec4 — +${plan.addedEls.length} element(s), +${plan.addedRels.length} relationship(s)`);
+            for (const e of plan.addedEls)
+                say(`      + ${e.title} (${e.kind})`);
+            for (const r of plan.addedRels) {
+                say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  "${r.title ?? ""}"`);
+            }
+            for (const additions of plan.models) {
+                const content = spliceModel({
+                    additions,
+                    deltaText,
+                    featureId: id,
+                    deltaKindTags: delta.specification?.relationshipKindTags ?? {},
+                });
+                // The model's own parse net, and it has to be a PROJECT one: an
+                // extending model resolves against the map, and against the map this
+                // very archive would leave — so the merged landscape goes into the set
+                // beside it. Refused here, at plan time, nothing written, exactly as an
+                // unparseable merged landscape is.
+                const errors = await modelMergeErrors({
+                    docsDir: config.docsDir,
+                    landscape: plan.content,
+                    model: { path: additions.model.path, content },
+                });
+                if (errors.length > 0) {
+                    throw new CodedFailure("merge-failed", `the merged ${additions.model.path} would not parse (${errors.length} error(s): ${errors.slice(0, 3).join("; ")}) — ` +
+                        `nothing was written. This model is read beside architecture/landscape.likec4 and nothing else, so an addition ` +
+                        `fits only if the map declares its kind and every element it names. Most often it is a kind or tag missing from ` +
+                        `the map's specification block, or a reference to ANOTHER service's interior, which lives in that service's own ` +
+                        `model and is not in this project — draw that call service to service on the map instead. Fix the map's ` +
+                        `specification or the delta, then re-run`);
+                }
+                writes.push(planWrite(join(config.docsDir, ...additions.model.path.split("/")), content));
+                const created = fresh.some((m) => m.path === additions.model.path);
+                if (created)
+                    modelled.add(additions.model.service);
+                say(`  architecture: ${created ? "created" : "merged into"} ${additions.model.path} — ` +
+                    `+${additions.els.length} element(s), +${additions.rels.length} relationship(s)`);
+                for (const e of additions.els)
+                    say(`      + ${e.title} (${e.kind})`);
+                for (const r of additions.rels) {
+                    say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  "${r.title ?? ""}"`);
+                }
+            }
+        }
+        else {
+            say(`\n  architecture: no landscape.likec4 — ${newEls.length} element(s) not merged`);
+        }
+    }
+    // A created service the delta drew no interior for still gets its model:
+    // empty, which is the whole of what the archive knows about its inside.
+    for (const model of fresh.filter((m) => !modelled.has(m.service))) {
+        writes.push(planWrite(join(config.docsDir, ...model.path.split("/")), model.text));
+        modelled.add(model.service);
+        say(`  architecture: created ${model.path} — empty; ${model.service}'s containers go in an \`extend\` block there`);
+    }
+    // A service this archive BRINGS INTO EXISTENCE without writing its model
+    // arrives without the one file `validate` demands of every service. Two
+    // shapes: one arriving on the architecture axis alone — a binding the map
+    // gains with no `specs/<svc>/` in the feature, so no directory either, and a
+    // model would be the one document in a directory the archive invented — and
+    // a `specs/<svc>/` the merged map never draws, which the gate calls an unknown
+    // service and only `--approve` brings here. The archive says so instead, and
+    // stops claiming the docs are complete. Non-gating: the merge is correct;
+    // what is missing is the next step, and refusing here would make onboarding
+    // a new service impossible in one command.
+    const newServices = [...new Set([...deltaServices, ...architectureServices])].filter((svc) => !enumerated.has(svc));
+    await sayUnfiled(config, fresh.map((m) => m.service), say);
+    // Whether a planned write lands in the service's would-be directory — the
+    // spec merge writes nothing for a delta that leaves no requirements, and then
+    // there is no directory to speak of.
+    const createsDir = (svc) => {
+        const dir = unfiledServicePaths(config.docsDir, svc).dir;
+        return writes.some((w) => w.content !== null && isPathInside(dir, w.path));
+    };
+    for (const svc of newServices.filter((s) => !modelled.has(s))) {
+        // `validate --all` reports the two under different codes, both errors: the
+        // directory a requirement delta creates with no model in it is the service
+        // target's `service.no-model`; a binding with no directory behind it, the
+        // fleet map's `landscape.binding-unknown`. The message names the one that
+        // fires, and a service for which neither lands is owed nothing.
+        const createsItsDir = deltaServices.some((d) => d === svc) && createsDir(svc);
+        if (!createsItsDir && !architectureServices.has(svc))
+            continue;
+        const owed = createsItsDir
+            ? { creates: `this archive creates services/${svc}/, but nothing writes services/${svc}/model.likec4`, reports: "service.no-model" }
+            : { creates: `this archive puts '${svc}' in the landscape, but the fleet has no services/${svc}/ at all`, reports: "landscape.binding-unknown" };
+        // An ERROR that does not gate — the two questions `Issue` keeps apart
+        // (core/vocabulary/issue.ts). Severity says whether the documents are valid,
+        // and validate files either shape as an error: the plan used to call it a
+        // warning, so the same fact read as advice here and as a failure one
+        // command later (the real-fleet review, 2026-10-21). Gating says whether the
+        // MERGE is safe, and it is — what is missing is the next step, as above.
+        planWarns.push({
+            severity: "error",
+            gates: false,
+            code: "service.no-model",
+            subject: svc,
+            message: `${svc}: ${owed.creates} — 'loam validate --all' will report ${owed.reports}, an error, until it exists. Run 'loam adopt --service ${svc}' from the service repo, or write the model by hand.`,
+        });
+    }
+}
+/**
+ * The one step left for a service the archive creates in a tree that files its
+ * services: moving it there. Printed only when the tree has a subsystem — in a
+ * flat tree every service is unfiled and that is normal, never a finding — and
+ * never as a guess at WHICH subsystem: the map's nesting is not a placement the
+ * tree may read.
+ */
+async function sayUnfiled(config, created, say) {
+    // No `services/` yet is a flat tree too — and the walk refuses a docs repo without one.
+    if (created.length === 0 || !existsSync(join(config.docsDir, "services")))
+        return;
+    if ((await config.fleet.fleetTree(config.docsDir)).subsystems.length === 0)
+        return;
+    for (const svc of created) {
+        say(`  ${svc}: created unfiled, at services/${svc}/ — 'loam subsystem move ${svc} --into <subsystem>' files it`);
+    }
+}
+/**
+ * The flows this feature brings, copied into `architecture/usecases/`.
+ *
+ * A create-only whole-file copy, and the smallest merge in the command: the
+ * document is views-only, it names nothing the landscape merge has not already
+ * placed (`planFlowOverlay` in the gate is what proves that, before this runs),
+ * and a flow the living tree already holds was refused at the gate
+ * (`usecase.flow-exists`, `core/usecases/delta/flows.ts` has the reasoning). So
+ * by the time this runs every path here is a file that does not exist, and
+ * `planWrite` marks it `exclusive` — a race that created it between the gate and
+ * the commit fails the write rather than overwriting somebody.
+ *
+ * It lives beside `planLandscape` rather than beside the requirement merges
+ * because it writes into `architecture/`, and the two merges are read together:
+ * the landscape gains the elements, the flow gains the hops over them.
+ * `unarchive` needs nothing new — a create is undone by deleting, which the
+ * snapshot manifest already records for every write in the plan.
+ */
+export async function planFlows(config, gated, plan, say) {
+    const flows = await featureFlows(gated.featureDir);
+    if (flows.length === 0)
+        return;
+    for (const flow of flows) {
+        plan.writes.push(planWrite(livingFlowPath(config.docsDir, flow.rel), await readUtf8(flow.path)));
+        say(`  use case: ${flow.rel} — created architecture/${USECASE_SUBDIR}/${flow.rel}`);
+    }
+}
+/**
+ * The same copy for the third whole-file axis: the topology a feature brings.
+ *
+ * Beside `planFlows` rather than folded into it, because the two write to
+ * different places — a flow into `architecture/usecases/`, a topology straight
+ * into `architecture/` — and one function taking a subdirectory argument would
+ * make that difference a parameter instead of a decision each axis states.
+ * `unarchive` needs nothing here either: a create is undone by deleting.
+ */
+export async function planDeployments(config, gated, plan, say) {
+    const docs = await featureDeployments(gated.featureDir);
+    if (docs.length === 0)
+        return;
+    for (const doc of docs) {
+        plan.writes.push(planWrite(livingDeploymentPath(config.docsDir, doc.rel), await readUtf8(doc.path)));
+        say(`  deployment: ${doc.rel} — created architecture/${doc.rel}`);
+    }
+}
+//# sourceMappingURL=landscape.js.map

package/dist/commands/archive/plan/landscape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet map merge, the flows drawn over it, and the services this archive\n * brings into existence.\n *\n * The landscape is the one document every feature writes into, so it is spliced\n * rather than rewritten: the authored file keeps its shape and the delta's\n * elements are placed into it. A service arriving on the architecture axis alone\n * has no `model.likec4` yet, and the finding for that is carried out of the plan\n * — `validate` would report it next, at the same severity, and reporting it here\n * is what stops that being a surprise.\n *\n * The map is not the only document the C4 axis writes. What a delta nests\n * INSIDE a service belongs to that service's `model.likec4` when the model\n * extends the map — the splicer routes it there, this stages the write, and\n * `./model/extending.ts` proves the result parses beside the merged map before\n * anything lands.\n *\n * `planFlows` at the bottom is the other half of the same axis and shares this\n * module for that reason rather than for the file cap: both write into\n * `architecture/`, and the two merges are read together — the map gains the\n * elements, the flow gains the ordered hops over them. It is a whole-file copy\n * where the landscape is a splice, because a flow is a document of its own and\n * there is nothing to merge partially.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { planLandscapeMerge } from \"../../../core/c4/splice/landscape-merge.js\";\nimport { spliceModel } from \"../../../core/c4/splice/model/merge.js\";\nimport { titleOf } from \"../../../core/c4/splice/identity/edges.js\";\nimport { parseServiceId, type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { isPathInside } from \"../../../core/kernel/path-safety.js\";\nimport { landscapePath as landscapeFile, unfiledServicePaths } from \"../../../core/repo/paths.js\";\nimport { enumeratedServiceIds } from \"../../../core/repo/service-target.js\";\nimport { createdServiceModels } from \"../../../core/c4/service-model/created/models.js\";\nimport { extendingModels } from \"../../../core/c4/service-model/fleet/extending.js\";\nimport { modelMergeErrors } from \"./model/extending.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport { CodedFailure } from \"../../../core/envelope/json.js\";\nimport { featurePaths } from \"../../../core/repo/paths.js\";\nimport { featureFlows, livingFlowPath, USECASE_SUBDIR } from \"../../../core/usecases/delta/flows.js\";\nimport { featureDeployments, livingDeploymentPath } from \"../../../core/deployment/delta.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function planLandscape(\n  config: { docsDir: DocsDir; fleet: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { id, featureDir, deltaDoc, deltaServices } = gated;\n  const deltaLikec4 = featurePaths(featureDir).delta;\n  const { writes, planWarns, architectureServices } = plan;\n  const landscapePath = landscapeFile(config.docsDir);\n  // \"New\" is enumeration membership, not an existsSync of services/<svc>/ at\n  // the root: a FILED service exists wherever the tree walk found it, and the\n  // root probe would grade every filed service as newly created here.\n  const enumerated = new Set<string>(await enumeratedServiceIds(config.docsDir));\n  // The empty extending model of every service this archive creates and the\n  // merged map draws — the rule, and the case for writing it, are\n  // `createdServiceModels`'s. With no delta or no map there is no merge, and\n  // no model.\n  const fresh =\n    deltaDoc === undefined || !existsSync(landscapePath)\n      ? []\n      : await createdServiceModels({\n          docsDir: config.docsDir,\n          featureDir,\n          featureId: id,\n          drawn: [...(await config.fleet.loadLikeC4(landscapePath)).elements, ...deltaDoc.elements.filter((e) => e.tags.includes(id))],\n          fleet: config.fleet,\n        });\n  // The services that leave this archive with a model.likec4 it wrote.\n  const modelled = new Set<string>();\n  if (deltaDoc !== undefined) {\n    const delta = deltaDoc;\n    if (delta.errors.length > 0) {\n      // --approve overrides loam's JUDGMENT about coherence, never its ability to\n      // read an axis. Skipping here would silently drop one merge axis in the one\n      // command engineered against quiet partial merges — same rule as an\n      // unparseable landscape or openapi: the plan stops before anything is written.\n      throw new CodedFailure(\n        \"merge-failed\",\n        `delta.likec4 has ${delta.errors.length} parse error(s) — the architecture axis cannot be merged; fix it (\\`loam validate --feature ${id}\\`) or delete the file`,\n      );\n    }\n    // The feature tag is the whole selection mechanism of this merge, and since\n    // LikeC4 1.59.0 a specification KIND can carry a tag that every element or\n    // edge of that kind then inherits. A delta declaring its own feature tag on\n    // a kind makes `newEls`/`newRels` below select the entire document —\n    // including the context declarations the scaffold ships commented out\n    // precisely so they are NOT merged — and archive would splice somebody\n    // else's services into the fleet map at exit 0. Mechanical, so `--approve`\n    // does not reach it, and refused before the merge is even planned.\n    const kindTagged = [\n      ...Object.entries(delta.specification?.elementKindTags ?? {}),\n      ...Object.entries(delta.specification?.relationshipKindTags ?? {}),\n    ].find(([, tags]) => tags.includes(id));\n    if (kindTagged !== undefined) {\n      throw new CodedFailure(\n        \"merge-failed\",\n        `delta.likec4 declares the feature tag '#${id}' on kind '${kindTagged[0]}' in its specification block, so every ` +\n          `'${kindTagged[0]}' in the file inherits it — the merge would treat the whole document as this feature's ` +\n          `additions, context elements included, and splice them into architecture/landscape.likec4. Nothing was ` +\n          `written. Remove '#${id}' from the kind and tag only the declarations ${id} actually adds.`,\n      );\n    }\n    const newEls = delta.elements.filter((e) => e.tags.includes(id));\n    const newRels = delta.relationships.filter((r) => r.tags.includes(id));\n    if (existsSync(landscapePath)) {\n      const deltaText = await readUtf8(deltaLikec4);\n      const plan = await planLandscapeMerge({\n        landscapeText: await readUtf8(landscapePath),\n        deltaText,\n        deltaElements: delta.elements,\n        newEls,\n        newRels,\n        featureId: id,\n        // The tags a relationship kind gives every edge of it: the parsed\n        // additions carry them, the delta's statements do not.\n        deltaKindTags: delta.specification?.relationshipKindTags ?? {},\n        // A service whose model EXTENDS the map owns its own interior, so the\n        // merge routes what is nested under it into that model instead of the\n        // map (verification 2026-09-04, E1) — and so does a service this\n        // archive creates, whose model is written below.\n        models: [...(await extendingModels(config.docsDir, config.fleet)), ...fresh],\n      });\n      // A service can arrive on the ARCHITECTURE axis alone: an element this\n      // merge ADDS, carrying a `metadata { service }` binding, with no\n      // `specs/<svc>/` anywhere in the feature. It is a service the fleet gate\n      // will demand a directory for the moment this merge lands, so it owes the\n      // same warning as one arriving with a requirement delta — and until it\n      // did, the closing \"complete + current\" line printed over a landscape\n      // this very archive had just made red. Read off the ADDED elements, not\n      // the tagged ones: an element the living landscape already had is not\n      // arriving, and one that is never merged is not there to demand anything.\n      // A binding is document text, which the service path builders no longer accept.\n      // The parse cannot actually filter anything here: an illegal binding is\n      // `c4.service-binding-invalid`, a coherence ERROR `--approve` does not\n      // override, refused before any merge is planned — so the `ok` test only\n      // carries the compiler's proof that document text never reaches a path.\n      for (const e of plan.addedEls) {\n        const parsed = e.service === undefined ? undefined : parseServiceId(e.service);\n        if (parsed?.ok === true) architectureServices.add(parsed.id);\n      }\n      if (plan.content !== null) writes.push(planWrite(landscapePath, plan.content));\n      say(`\\n  architecture: merged into landscape.likec4 — +${plan.addedEls.length} element(s), +${plan.addedRels.length} relationship(s)`);\n      for (const e of plan.addedEls) say(`      + ${e.title} (${e.kind})`);\n      for (const r of plan.addedRels) {\n        say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  \"${r.title ?? \"\"}\"`);\n      }\n      for (const additions of plan.models) {\n        const content = spliceModel({\n          additions,\n          deltaText,\n          featureId: id,\n          deltaKindTags: delta.specification?.relationshipKindTags ?? {},\n        });\n        // The model's own parse net, and it has to be a PROJECT one: an\n        // extending model resolves against the map, and against the map this\n        // very archive would leave — so the merged landscape goes into the set\n        // beside it. Refused here, at plan time, nothing written, exactly as an\n        // unparseable merged landscape is.\n        const errors = await modelMergeErrors({\n          docsDir: config.docsDir,\n          landscape: plan.content,\n          model: { path: additions.model.path, content },\n        });\n        if (errors.length > 0) {\n          throw new CodedFailure(\n            \"merge-failed\",\n            `the merged ${additions.model.path} would not parse (${errors.length} error(s): ${errors.slice(0, 3).join(\"; \")}) — ` +\n              `nothing was written. This model is read beside architecture/landscape.likec4 and nothing else, so an addition ` +\n              `fits only if the map declares its kind and every element it names. Most often it is a kind or tag missing from ` +\n              `the map's specification block, or a reference to ANOTHER service's interior, which lives in that service's own ` +\n              `model and is not in this project — draw that call service to service on the map instead. Fix the map's ` +\n              `specification or the delta, then re-run`,\n          );\n        }\n        writes.push(planWrite(join(config.docsDir, ...additions.model.path.split(\"/\")), content));\n        const created = fresh.some((m) => m.path === additions.model.path);\n        if (created) modelled.add(additions.model.service);\n        say(\n          `  architecture: ${created ? \"created\" : \"merged into\"} ${additions.model.path} — ` +\n            `+${additions.els.length} element(s), +${additions.rels.length} relationship(s)`,\n        );\n        for (const e of additions.els) say(`      + ${e.title} (${e.kind})`);\n        for (const r of additions.rels) {\n          say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  \"${r.title ?? \"\"}\"`);\n        }\n      }\n    } else {\n      say(`\\n  architecture: no landscape.likec4 — ${newEls.length} element(s) not merged`);\n    }\n  }\n  // A created service the delta drew no interior for still gets its model:\n  // empty, which is the whole of what the archive knows about its inside.\n  for (const model of fresh.filter((m) => !modelled.has(m.service))) {\n    writes.push(planWrite(join(config.docsDir, ...model.path.split(\"/\")), model.text));\n    modelled.add(model.service);\n    say(`  architecture: created ${model.path} — empty; ${model.service}'s containers go in an \\`extend\\` block there`);\n  }\n\n  // A service this archive BRINGS INTO EXISTENCE without writing its model\n  // arrives without the one file `validate` demands of every service. Two\n  // shapes: one arriving on the architecture axis alone — a binding the map\n  // gains with no `specs/<svc>/` in the feature, so no directory either, and a\n  // model would be the one document in a directory the archive invented — and\n  // a `specs/<svc>/` the merged map never draws, which the gate calls an unknown\n  // service and only `--approve` brings here. The archive says so instead, and\n  // stops claiming the docs are complete. Non-gating: the merge is correct;\n  // what is missing is the next step, and refusing here would make onboarding\n  // a new service impossible in one command.\n  const newServices = [...new Set([...deltaServices, ...architectureServices])].filter(\n    (svc) => !enumerated.has(svc),\n  );\n  await sayUnfiled(config, fresh.map((m) => m.service), say);\n  // Whether a planned write lands in the service's would-be directory — the\n  // spec merge writes nothing for a delta that leaves no requirements, and then\n  // there is no directory to speak of.\n  const createsDir = (svc: PathableService): boolean => {\n    const dir = unfiledServicePaths(config.docsDir, svc).dir;\n    return writes.some((w) => w.content !== null && isPathInside(dir, w.path));\n  };\n  for (const svc of newServices.filter((s) => !modelled.has(s))) {\n    // `validate --all` reports the two under different codes, both errors: the\n    // directory a requirement delta creates with no model in it is the service\n    // target's `service.no-model`; a binding with no directory behind it, the\n    // fleet map's `landscape.binding-unknown`. The message names the one that\n    // fires, and a service for which neither lands is owed nothing.\n    const createsItsDir = deltaServices.some((d) => d === svc) && createsDir(svc);\n    if (!createsItsDir && !architectureServices.has(svc)) continue;\n    const owed = createsItsDir\n      ? { creates: `this archive creates services/${svc}/, but nothing writes services/${svc}/model.likec4`, reports: \"service.no-model\" }\n      : { creates: `this archive puts '${svc}' in the landscape, but the fleet has no services/${svc}/ at all`, reports: \"landscape.binding-unknown\" };\n    // An ERROR that does not gate — the two questions `Issue` keeps apart\n    // (core/vocabulary/issue.ts). Severity says whether the documents are valid,\n    // and validate files either shape as an error: the plan used to call it a\n    // warning, so the same fact read as advice here and as a failure one\n    // command later (the real-fleet review, 2026-10-21). Gating says whether the\n    // MERGE is safe, and it is — what is missing is the next step, as above.\n    planWarns.push({\n      severity: \"error\",\n      gates: false,\n      code: \"service.no-model\",\n      subject: svc,\n      message: `${svc}: ${owed.creates} — 'loam validate --all' will report ${owed.reports}, an error, until it exists. Run 'loam adopt --service ${svc}' from the service repo, or write the model by hand.`,\n    });\n  }\n}\n\n/**\n * The one step left for a service the archive creates in a tree that files its\n * services: moving it there. Printed only when the tree has a subsystem — in a\n * flat tree every service is unfiled and that is normal, never a finding — and\n * never as a guess at WHICH subsystem: the map's nesting is not a placement the\n * tree may read.\n */\nasync function sayUnfiled(config: { docsDir: DocsDir; fleet: FleetContext }, created: string[], say: (line?: string) => void): Promise<void> {\n  // No `services/` yet is a flat tree too — and the walk refuses a docs repo without one.\n  if (created.length === 0 || !existsSync(join(config.docsDir, \"services\"))) return;\n  if ((await config.fleet.fleetTree(config.docsDir)).subsystems.length === 0) return;\n  for (const svc of created) {\n    say(`  ${svc}: created unfiled, at services/${svc}/ — 'loam subsystem move ${svc} --into <subsystem>' files it`);\n  }\n}\n\n/**\n * The flows this feature brings, copied into `architecture/usecases/`.\n *\n * A create-only whole-file copy, and the smallest merge in the command: the\n * document is views-only, it names nothing the landscape merge has not already\n * placed (`planFlowOverlay` in the gate is what proves that, before this runs),\n * and a flow the living tree already holds was refused at the gate\n * (`usecase.flow-exists`, `core/usecases/delta/flows.ts` has the reasoning). So\n * by the time this runs every path here is a file that does not exist, and\n * `planWrite` marks it `exclusive` — a race that created it between the gate and\n * the commit fails the write rather than overwriting somebody.\n *\n * It lives beside `planLandscape` rather than beside the requirement merges\n * because it writes into `architecture/`, and the two merges are read together:\n * the landscape gains the elements, the flow gains the hops over them.\n * `unarchive` needs nothing new — a create is undone by deleting, which the\n * snapshot manifest already records for every write in the plan.\n */\nexport async function planFlows(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const flows = await featureFlows(gated.featureDir);\n  if (flows.length === 0) return;\n  for (const flow of flows) {\n    plan.writes.push(planWrite(livingFlowPath(config.docsDir, flow.rel), await readUtf8(flow.path)));\n    say(`  use case: ${flow.rel} — created architecture/${USECASE_SUBDIR}/${flow.rel}`);\n  }\n}\n\n/**\n * The same copy for the third whole-file axis: the topology a feature brings.\n *\n * Beside `planFlows` rather than folded into it, because the two write to\n * different places — a flow into `architecture/usecases/`, a topology straight\n * into `architecture/` — and one function taking a subdirectory argument would\n * make that difference a parameter instead of a decision each axis states.\n * `unarchive` needs nothing here either: a create is undone by deleting.\n */\nexport async function planDeployments(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const docs = await featureDeployments(gated.featureDir);\n  if (docs.length === 0) return;\n  for (const doc of docs) {\n    plan.writes.push(planWrite(livingDeploymentPath(config.docsDir, doc.rel), await readUtf8(doc.path)));\n    say(`  deployment: ${doc.rel} — created architecture/${doc.rel}`);\n  }\n}\n"]}

package/dist/commands/archive/plan/model/extending.js

@@ -0,0 +1,85 @@
+/**
+ * Whether the model this merge would leave behind is one LikeC4 can read.
+ *
+ * It is here because this is the seam that HAS the other document: an extending
+ * model is never parsed alone, it is parsed beside the `architecture/` project,
+ * and the project the merge must be proven against is the one this very archive
+ * would leave behind — the merged map, not the living one. `core/c4/splice` is
+ * a pure text-to-text computation — texts in, texts out — so proving the result
+ * stays with the command that decides to write.
+ *
+ * READING the fleet's extending models used to be here too, as the other half
+ * of one seam. It moved to `core/c4/service-model/fleet/extending.ts` when the
+ * archive stopped being the only reader: `core/c4/project/staged.ts` previews
+ * the same merge for every feature-side gate, and `core/` may not import
+ * `commands/`. That module's header carries the fail-open the move closes.
+ */
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { errorText } from "../../../../core/c4/likec4.js";
+import { architectureProjectDocuments } from "../../../../core/c4/project/architecture.js";
+import { asLoadedDoc, loadProject } from "../../../../core/c4/project/load.js";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { landscapePath } from "../../../../core/repo/paths.js";
+/**
+ * What LikeC4 says about the model this merge would leave, read the way the
+ * per-service grade reads it — the `architecture/` project plus this one file.
+ *
+ * Empty means clean. Anything else refuses the archive at plan time, with
+ * nothing written, for the reason the landscape's own parse net exists:
+ * splicing is text surgery, and a document that does not parse takes a whole
+ * service's grade down (`c4.invalid`) the moment it lands.
+ *
+ * Errors carry the path the author wrote rather than the staged copy's, and a
+ * staging failure is reported as an error rather than swallowed: a merge that
+ * could not be proven is not one that passed.
+ */
+export async function modelMergeErrors(proof) {
+    const { docsDir, landscape, model } = proof;
+    let root;
+    try {
+        root = await mkdtemp(join(tmpdir(), "loam-model-merge-"));
+        const map = resolve(landscapePath(docsDir));
+        const authored = new Map();
+        const staged = [];
+        for (const path of await architectureProjectDocuments(docsDir)) {
+            const rel = repoPath(docsDir, path);
+            const at = landscape !== null && resolve(path) === map
+                ? await write(root, rel, landscape)
+                : await copy(root, rel, path);
+            authored.set(at, rel);
+            staged.push(at);
+        }
+        const at = await write(root, model.path, model.content);
+        authored.set(at, model.path);
+        staged.push(at);
+        const doc = asLoadedDoc(await loadProject(root, staged));
+        return doc.errors.map((e) => {
+            const where = e.sourceFsPath === undefined ? undefined : authored.get(resolve(e.sourceFsPath));
+            return where === undefined ? errorText(e) : `${where} ${errorText(e)}`;
+        });
+    }
+    catch (err) {
+        return [err instanceof Error ? err.message : String(err)];
+    }
+    finally {
+        if (root !== undefined)
+            await rm(root, { recursive: true, force: true });
+    }
+}
+/** Mirror one authored document into the staged tree at its docs-relative path. */
+async function copy(root, rel, path) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(path, dest);
+    return resolve(dest);
+}
+/** The same for bytes loam holds rather than a file — the merge previews. */
+async function write(root, rel, content) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content, "utf8");
+    return resolve(dest);
+}
+//# sourceMappingURL=extending.js.map

package/dist/commands/archive/plan/model/extending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extending.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/model/extending.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Whether the model this merge would leave behind is one LikeC4 can read.\n *\n * It is here because this is the seam that HAS the other document: an extending\n * model is never parsed alone, it is parsed beside the `architecture/` project,\n * and the project the merge must be proven against is the one this very archive\n * would leave behind — the merged map, not the living one. `core/c4/splice` is\n * a pure text-to-text computation — texts in, texts out — so proving the result\n * stays with the command that decides to write.\n *\n * READING the fleet's extending models used to be here too, as the other half\n * of one seam. It moved to `core/c4/service-model/fleet/extending.ts` when the\n * archive stopped being the only reader: `core/c4/project/staged.ts` previews\n * the same merge for every feature-side gate, and `core/` may not import\n * `commands/`. That module's header carries the fail-open the move closes.\n */\nimport { copyFile, mkdir, mkdtemp, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { errorText } from \"../../../../core/c4/likec4.js\";\nimport { architectureProjectDocuments } from \"../../../../core/c4/project/architecture.js\";\nimport { asLoadedDoc, loadProject } from \"../../../../core/c4/project/load.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { landscapePath } from \"../../../../core/repo/paths.js\";\n\nexport interface ModelProof {\n  docsDir: DocsDir;\n  /** The merged landscape, or null when this archive leaves the map as it is. */\n  landscape: string | null;\n  /** The merged model: repo-relative path, and the text the archive would write. */\n  model: { path: string; content: string };\n}\n\n/**\n * What LikeC4 says about the model this merge would leave, read the way the\n * per-service grade reads it — the `architecture/` project plus this one file.\n *\n * Empty means clean. Anything else refuses the archive at plan time, with\n * nothing written, for the reason the landscape's own parse net exists:\n * splicing is text surgery, and a document that does not parse takes a whole\n * service's grade down (`c4.invalid`) the moment it lands.\n *\n * Errors carry the path the author wrote rather than the staged copy's, and a\n * staging failure is reported as an error rather than swallowed: a merge that\n * could not be proven is not one that passed.\n */\nexport async function modelMergeErrors(proof: ModelProof): Promise<string[]> {\n  const { docsDir, landscape, model } = proof;\n  let root: string | undefined;\n  try {\n    root = await mkdtemp(join(tmpdir(), \"loam-model-merge-\"));\n    const map = resolve(landscapePath(docsDir));\n    const authored = new Map<string, string>();\n    const staged: string[] = [];\n    for (const path of await architectureProjectDocuments(docsDir)) {\n      const rel = repoPath(docsDir, path);\n      const at =\n        landscape !== null && resolve(path) === map\n          ? await write(root, rel, landscape)\n          : await copy(root, rel, path);\n      authored.set(at, rel);\n      staged.push(at);\n    }\n    const at = await write(root, model.path, model.content);\n    authored.set(at, model.path);\n    staged.push(at);\n    const doc = asLoadedDoc(await loadProject(root, staged));\n    return doc.errors.map((e) => {\n      const where = e.sourceFsPath === undefined ? undefined : authored.get(resolve(e.sourceFsPath));\n      return where === undefined ? errorText(e) : `${where} ${errorText(e)}`;\n    });\n  } catch (err) {\n    return [err instanceof Error ? err.message : String(err)];\n  } finally {\n    if (root !== undefined) await rm(root, { recursive: true, force: true });\n  }\n}\n\n/** Mirror one authored document into the staged tree at its docs-relative path. */\nasync function copy(root: string, rel: string, path: string): Promise<string> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await copyFile(path, dest);\n  return resolve(dest);\n}\n\n/** The same for bytes loam holds rather than a file — the merge previews. */\nasync function write(root: string, rel: string, content: string): Promise<string> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await writeFile(dest, content, \"utf8\");\n  return resolve(dest);\n}\n"]}

package/dist/commands/archive/plan/refusal.js

@@ -0,0 +1,106 @@
+/**
+ * How `loam archive` refuses, and what a refusal prints.
+ *
+ * Every arm here keeps one property: a refusal means nothing was written. The
+ * `--json` shapes carry the issues that caused it so an agent can act on the
+ * list rather than on the sentence, and a refusal thrown from below is a
+ * `CodedFailure` (core/envelope/json.ts) so a merge that could not be computed
+ * reports as a merge failure rather than as `internal` — a read-only directory
+ * or an unreadable pre-image is not a bug in loam, and saying so sends the
+ * reader looking for one.
+ */
+import { existsSync } from "node:fs";
+import { emitJsonError, repoPath } from "../../../core/envelope/json.js";
+import { approveOverrides, issueFinding, } from "../../../core/vocabulary/issue.js";
+import {} from "../../../core/staging/interrupted.js";
+import {} from "../../../core/staging/writes.js";
+import { findingJson } from "../../../core/vocabulary/report.js";
+/**
+ * An Issue as the `--json` envelope spells it — the whole Finding shape, `details`
+ * included (`[]` when the issue carries none; the overwrite warnings list their
+ * current consumers there), plus `overridable`.
+ * `gates` and `overridable` are always present and already resolved: a consumer
+ * must not have to re-implement the severity default to know what blocks
+ * archive, nor keep a code list to know what `--approve` can move.
+ */
+export function issueJson(i, scope) {
+    return {
+        ...findingJson(issueFinding(i), scope === undefined ? undefined : { path: scope, role: "scope" }),
+        overridable: approveOverrides(i),
+    };
+}
+/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */
+export function refuseJson(code, msg, issues, scope) {
+    emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });
+}
+/**
+ * The same envelope for a refusal computed from `Finding`s rather than
+ * `Issue`s — the plan-time checks whose codes are not coherence's (they belong
+ * to the LIVING documents, not to the feature) and so are not `IssueCode`s.
+ *
+ * `gates: true` is asserted rather than derived: every finding listed in a
+ * refusal is a reason archive stopped, which is what the field means. Nothing
+ * advisory reaches here.
+ */
+export function refuseFindings(code, msg, findings, scope) {
+    emitJsonError(code, msg, {
+        issues: findings.map((finding) => ({
+            ...findingJson(finding, scope === undefined ? undefined : { path: scope, role: "scope" }),
+            gates: true,
+        })),
+    });
+}
+/**
+ * Take the docs repo's advisory lock for the WHOLE plan+commit window, then
+ * archive.
+ *
+ * The window is the point. Two archives that overlap do not fight over a
+ * rename: they each read the living landscape, each splice their additions into
+ * the bytes they read, and the second write replaces the first — both exit 0,
+ * and `validate` stays green over a landscape that is missing one feature's
+ * architecture, because a document with fewer elements is not an invalid one.
+ * That is the only silent-loss path in loam that a later command cannot even
+ * detect, so it is closed at the coarsest possible granularity: one writer per
+ * docs repo, refusing rather than queueing, because a CLI that blocks for an
+ * unknown time is worse for an agent than one that says `docs-busy`.
+ */
+/**
+ * What the recovery did, before this command's own output — a docs repo that
+ * changed under the caller is the first thing they have to be told, not a
+ * footnote. Shared by archive and unarchive through the same CommitRecovery.
+ */
+export function sayRecovery(r) {
+    const what = `an interrupted \`loam ${r.command} ${r.feature}\``;
+    if (r.outcome === "completed") {
+        console.log(`⚠ ${what} had in fact finished — cleared its commit record.\n`);
+        return;
+    }
+    if (r.outcome === "consistent") {
+        console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\n`);
+        return;
+    }
+    // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —
+    // the merged text a restore was replacing is written down nowhere, so there is
+    // nothing to go back to. Say which happened; the paths are the same either way.
+    const what_ = r.command === "archive" ? "put them back from" : "finished them from";
+    console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);
+    for (const p of r.repaired)
+        console.log(`  ↩ ${p}`);
+    console.log("");
+}
+/** The full plan, as files: what a dry run shows instead of doing. */
+export function printPlan(docsDir, writes, dirName, owed) {
+    console.log(`\n  plan — ${writes.length} file(s):`);
+    for (const w of writes) {
+        const verb = existsSync(w.path) ? "update" : "create";
+        console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);
+    }
+    console.log(`    move    features/${dirName} → features/archive/${dirName}`);
+    // What the real run would print in place of "complete + current" (../closing.ts).
+    if (owed.length > 0)
+        console.log("");
+    for (const line of owed)
+        console.log(line);
+    console.log("\n  dry run — nothing was written.");
+}
+//# sourceMappingURL=refusal.js.map

package/dist/commands/archive/plan/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/refusal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How `loam archive` refuses, and what a refusal prints.\n *\n * Every arm here keeps one property: a refusal means nothing was written. The\n * `--json` shapes carry the issues that caused it so an agent can act on the\n * list rather than on the sentence, and a refusal thrown from below is a\n * `CodedFailure` (core/envelope/json.ts) so a merge that could not be computed\n * reports as a merge failure rather than as `internal` — a read-only directory\n * or an unreadable pre-image is not a bug in loam, and saying so sends the\n * reader looking for one.\n */\nimport { existsSync } from \"node:fs\";\nimport { emitJsonError, repoPath, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport {\n  approveOverrides,\n  issueFinding,\n  type Issue,\n} from \"../../../core/vocabulary/issue.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { findingJson, type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface ArchiveOptions {\n  approve?: boolean;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\n/**\n * An Issue as the `--json` envelope spells it — the whole Finding shape, `details`\n * included (`[]` when the issue carries none; the overwrite warnings list their\n * current consumers there), plus `overridable`.\n * `gates` and `overridable` are always present and already resolved: a consumer\n * must not have to re-implement the severity default to know what blocks\n * archive, nor keep a code list to know what `--approve` can move.\n */\nexport function issueJson(i: Issue, scope?: string): Record<string, unknown> {\n  return {\n    ...findingJson(\n      issueFinding(i),\n      scope === undefined ? undefined : { path: scope, role: \"scope\" },\n    ),\n    overridable: approveOverrides(i),\n  };\n}\n\n/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */\nexport function refuseJson(code: ErrorCode, msg: string, issues: Issue[], scope?: string): void {\n  emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });\n}\n\n/**\n * The same envelope for a refusal computed from `Finding`s rather than\n * `Issue`s — the plan-time checks whose codes are not coherence's (they belong\n * to the LIVING documents, not to the feature) and so are not `IssueCode`s.\n *\n * `gates: true` is asserted rather than derived: every finding listed in a\n * refusal is a reason archive stopped, which is what the field means. Nothing\n * advisory reaches here.\n */\nexport function refuseFindings(\n  code: ErrorCode,\n  msg: string,\n  findings: Finding[],\n  scope?: string,\n): void {\n  emitJsonError(code, msg, {\n    issues: findings.map((finding) => ({\n      ...findingJson(\n        finding,\n        scope === undefined ? undefined : { path: scope, role: \"scope\" },\n      ),\n      gates: true,\n    })),\n  });\n}\n\n/**\n * Take the docs repo's advisory lock for the WHOLE plan+commit window, then\n * archive.\n *\n * The window is the point. Two archives that overlap do not fight over a\n * rename: they each read the living landscape, each splice their additions into\n * the bytes they read, and the second write replaces the first — both exit 0,\n * and `validate` stays green over a landscape that is missing one feature's\n * architecture, because a document with fewer elements is not an invalid one.\n * That is the only silent-loss path in loam that a later command cannot even\n * detect, so it is closed at the coarsest possible granularity: one writer per\n * docs repo, refusing rather than queueing, because a CLI that blocks for an\n * unknown time is worse for an agent than one that says `docs-busy`.\n */\n\n/**\n * What the recovery did, before this command's own output — a docs repo that\n * changed under the caller is the first thing they have to be told, not a\n * footnote. Shared by archive and unarchive through the same CommitRecovery.\n */\nexport function sayRecovery(r: CommitRecovery): void {\n  const what = `an interrupted \\`loam ${r.command} ${r.feature}\\``;\n  if (r.outcome === \"completed\") {\n    console.log(`⚠ ${what} had in fact finished — cleared its commit record.\\n`);\n    return;\n  }\n  if (r.outcome === \"consistent\") {\n    console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\\n`);\n    return;\n  }\n  // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —\n  // the merged text a restore was replacing is written down nowhere, so there is\n  // nothing to go back to. Say which happened; the paths are the same either way.\n  const what_ = r.command === \"archive\" ? \"put them back from\" : \"finished them from\";\n  console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);\n  for (const p of r.repaired) console.log(`  ↩ ${p}`);\n  console.log(\"\");\n}\n\n/** The full plan, as files: what a dry run shows instead of doing. */\nexport function printPlan(docsDir: string, writes: PlannedWrite[], dirName: string, owed: readonly string[]): void {\n  console.log(`\\n  plan — ${writes.length} file(s):`);\n  for (const w of writes) {\n    const verb = existsSync(w.path) ? \"update\" : \"create\";\n    console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);\n  }\n  console.log(`    move    features/${dirName} → features/archive/${dirName}`);\n  // What the real run would print in place of \"complete + current\" (../closing.ts).\n  if (owed.length > 0) console.log(\"\");\n  for (const line of owed) console.log(line);\n  console.log(\"\\n  dry run — nothing was written.\");\n}\n"]}