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

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

@@ -0,0 +1,237 @@
+/**
+ * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements
+ * applied into each living service spec. The contract merges live beside it in
+ * `./contracts/` — one file per axis, split out when the OpenAPI half made
+ * this one carry two merges.
+ *
+ * ONE code path for the pair of requirement-carrying files — the business
+ * spec.md and the architecture arch.spec.md ride the same delta algebra, the
+ * same prose-preserving rewrite and the same guards, parameterized by filename.
+ * A fork here would be two places the merge could disagree.
+ *
+ * Nothing is written. Everything lands in the `Plan`, so a failure on any axis
+ * leaves the living docs exactly as they were.
+ */
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { rebaseLinks } from "../../../core/links/parse.js";
+import { planWrite, readUtf8 } from "../../../core/staging/writes.js";
+import { featureSpecPaths, SPEC_AXES } from "../../../core/repo/paths.js";
+import { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from "../../../core/repo/authored/paths.js";
+import { featureGlossary, livingTermPath } from "../../../core/glossary/delta.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
+import { isRequirementsHeading, parseRequirements, sectionHeadings, splitRequirementsSection, } from "../../../core/document/parse.js";
+import { applyRequirementDelta } from "../../../core/document/apply.js";
+import { serializeRequirements } from "../../../core/document/spec.js";
+import {} from "../../../core/document/spec.js";
+import { ArchiveFailure } from "./refusal.js";
+import {} from "./state.js";
+export async function planSpecs(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes } = plan;
+    // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service
+    // spec. ONE code path for the pair of requirement-carrying files: the business
+    // spec.md and the architecture arch.spec.md ride the same delta algebra, the
+    // same prose-preserving rewrite and the same guards, parameterized by filename
+    // (SPEC_AXES) — a fork here would be two places the merge could disagree.
+    for (const svc of deltaServices) {
+        for (const axis of SPEC_AXES) {
+            const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];
+            if (!existsSync(deltaPath))
+                continue;
+            // The shared context: this is a deltaServices × SPEC_AXES loop, and a
+            // context-less locate is a full fleet walk per iteration.
+            const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];
+            // Resolved BEFORE the delta is parsed, because the parse now depends on
+            // it: a requirement's markdown links are relative to the file they were
+            // written in, and this merge moves the text two directories up the tree.
+            // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering
+            // here is what lets the fix see both ends of the move, including a
+            // service filed under a subsystem, whose living directory is deeper still.
+            const deltaReqs = parseRequirements(rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }));
+            if (!existsSync(livingPath)) {
+                // New service (or first arch spec) — create the living file from the
+                // ADDED/MODIFIED requirements.
+                const created = applyRequirementDelta([], deltaReqs);
+                if (created.length === 0) {
+                    say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);
+                    continue;
+                }
+                const heading = axis.key === "spec" ? svc : `${svc} — architecture`;
+                const frontmatter = `---\nservice: ${svc}\nstatus: draft\n---\n\n# ${heading}\n\n`;
+                writes.push(planWrite(livingPath, `${frontmatter}## Requirements\n\n${serializeRequirements(created)}`));
+                say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);
+                continue;
+            }
+            const livingText = await readUtf8(livingPath);
+            // TWO `## Requirements` headings would put the rewrite's one-section
+            // invariant to a choice it must not make: the run of the first would be
+            // rewritten while the second survived verbatim in the tail — and its
+            // requirements, collected by parseRequirements, would land in the run TOO.
+            // Mechanical, like a model-less landscape, so merge-failed, not --approve.
+            const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
+            if (reqHeadings.length > 1) {
+                throw new ArchiveFailure("merge-failed", `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+            }
+            const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
+            writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
+            const c = summarize(deltaReqs);
+            say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
+        }
+    }
+}
+/**
+ * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas
+ * applied into the living `capabilities/<id>/spec.md`.
+ *
+ * Here rather than in a sixth file in this package because this module already
+ * owns "requirements merged into a living document" — it owns
+ * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`
+ * call, and the business corpus needs all three unchanged. What differs from
+ * `planSpecs` above is only where the living document lives and what a CREATED
+ * one says at the top.
+ *
+ * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service
+ * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),
+ * so an archive that merged into a file it refused to create would make the
+ * whole delta merge nothing — which is the `delta.no-delta-sections` failure
+ * class, arriving through the merge instead of through the grammar.
+ *
+ * NO FRONTMATTER on a created capability document, and that is a decision
+ * rather than an omission. Nothing reads a capability document's frontmatter:
+ * `readCapabilityTree` classifies by the file's PRESENCE and
+ * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A
+ * `status:` field invented here would be the "second list nothing keeps
+ * current" this axis was designed against.
+ *
+ * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`
+ * creates `capabilities/`, which is one of the two ways a fleet opts INTO the
+ * capability axis — from the next command on, `loam validate --all` grades a
+ * corpus that did not exist before. A merge that changes what the whole fleet
+ * is graded on must not do it silently.
+ */
+export async function planCapabilities(config, gated, plan, say) {
+    const { writes } = plan;
+    // Whether `capabilities/` exists is asked BEFORE the loop, because the loop
+    // is what would create it; `creating` records whether this run actually
+    // materialises a document, so the adoption line below is not printed by a
+    // run whose every capability delta merged into a document already there.
+    const adopting = !existsSync(capabilityDocsDir(config.docsDir));
+    let creating = false;
+    for (const doc of gated.capabilityDeltas) {
+        const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;
+        // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two
+        // directories deeper than `capabilities/<id>/`, so a citation of a glossary
+        // term or an ADR would land pointing above the repository.
+        const deltaReqs = parseRequirements(rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }));
+        if (!existsSync(livingPath)) {
+            const created = applyRequirementDelta([], deltaReqs);
+            if (created.length === 0) {
+                say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);
+                continue;
+            }
+            // The heading is the id and nothing else. loam merges requirements and
+            // never prose, so it must not fabricate the narrative that is the whole
+            // point of the document — the line below tells the author it is theirs.
+            writes.push(planWrite(livingPath, `# ${doc.id}\n\n## Requirements\n\n${serializeRequirements(created)}`));
+            creating = true;
+            say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);
+            say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);
+            continue;
+        }
+        const livingText = await readUtf8(livingPath);
+        // The same one-section invariant as the service axis above, and the same
+        // reason it cannot be guessed at.
+        const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
+        if (reqHeadings.length > 1) {
+            throw new ArchiveFailure("merge-failed", `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+        }
+        const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
+        writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
+        const c = summarize(deltaReqs);
+        say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
+    }
+    if (adopting && creating) {
+        say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \`loam validate --all\` grades it from now on`);
+    }
+}
+/**
+ * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:
+ * everything before the first requirement inside `## Requirements` (the intro,
+ * the heading line, prose under the heading) and everything from the section's
+ * end onward (the next `## ` heading to EOF) — the old cut was a substring
+ * `indexOf("\n## Requirements")`, a prefix match that also hit
+ * `## Requirements Extra` and silently destroyed every section after the
+ * requirements. Prose BETWEEN requirements is body text of whatever is open
+ * above it (parseRequirements attributes it to the previous requirement's last
+ * scenario, or its text) and survives inside the re-serialized run, framing
+ * normalized. `merged` must contain every living requirement — runArchive's
+ * stray guard refuses any document whose requirements sit outside the section,
+ * using the same heading definition, before this output is ever written.
+ */
+function rewriteRequirementsRun(text, merged) {
+    const s = splitRequirementsSection(text);
+    // No `## Requirements` at all: the stray guard has already refused any doc
+    // whose requirements live elsewhere, so this one has none — open the section.
+    if (s === null)
+        return `${text.trimEnd()}\n\n## Requirements\n\n${serializeRequirements(merged)}`;
+    const body = serializeRequirements(merged);
+    // head/tail are raw slices; only the run's own framing is normalized. When
+    // the section held no requirements yet, the glue supplies the blank line the
+    // author never had reason to write.
+    const headGlue = s.run !== "" || s.head.endsWith("\n\n") ? "" : s.head.endsWith("\n") ? "\n" : "\n\n";
+    const tailGlue = s.tail === "" ? "" : "\n";
+    return s.head + headGlue + body + tailGlue + s.tail;
+}
+function summarize(reqs) {
+    const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };
+    for (const r of reqs) {
+        if (r.kind === "ADDED")
+            c.ADDED += 1;
+        else if (r.kind === "MODIFIED")
+            c.MODIFIED += 1;
+        else if (r.kind === "REMOVED")
+            c.REMOVED += 1;
+    }
+    return c;
+}
+/**
+ * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to
+ * `glossary/<term>.md`.
+ *
+ * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta
+ * is folded into a living document by the requirement algebra because the two
+ * documents share identified parts; a term document has one part, and merging
+ * two definitions of one word is not something a machine may attempt. So the
+ * definition the author wrote in the feature IS the definition that lands,
+ * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing
+ * else, not even the trailing newline.
+ *
+ * CREATE-ONLY, which is why this loop has no other branch. A term the living
+ * glossary already defines was refused at the gate (`glossary.term-exists`,
+ * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs
+ * every path here is a file that does not exist. `planWrite` marks it
+ * `exclusive`, so a race that created it between the gate and the commit fails
+ * the write rather than overwriting somebody.
+ *
+ * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as
+ * `planCapabilities` does for `capabilities/`: the directory's existence is the
+ * axis's opt-in, so this merge changes what `loam validate --all` grades from
+ * the next command on, and a merge that widens the fleet's own gate must not do
+ * it silently.
+ */
+export async function planGlossary(config, gated, plan, say) {
+    const glossary = await featureGlossary(gated.featureDir);
+    if (!glossary.present || glossary.terms.length === 0)
+        return;
+    // Asked BEFORE the loop, because the loop is what would create it.
+    const adopting = !existsSync(glossaryDir(config.docsDir));
+    for (const term of glossary.terms) {
+        plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));
+        say(`  glossary: ${term.id} — created glossary/${term.id}.md`);
+    }
+    if (adopting) {
+        say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \`loam validate --all\` grades it from now on`);
+    }
+}
+//# sourceMappingURL=specs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/specs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements\n * applied into each living service spec. The contract merges live beside it in\n * `./contracts/` — one file per axis, split out when the OpenAPI half made\n * this one carry two merges.\n *\n * ONE code path for the pair of requirement-carrying files — the business\n * spec.md and the architecture arch.spec.md ride the same delta algebra, the\n * same prose-preserving rewrite and the same guards, parameterized by filename.\n * A fork here would be two places the merge could disagree.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { rebaseLinks } from \"../../../core/links/parse.js\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from \"../../../core/repo/authored/paths.js\";\nimport { featureGlossary, livingTermPath } from \"../../../core/glossary/delta.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport {\n  isRequirementsHeading,\n  parseRequirements,\n  sectionHeadings,\n  splitRequirementsSection,\n} from \"../../../core/document/parse.js\";\nimport { applyRequirementDelta } from \"../../../core/document/apply.js\";\nimport { serializeRequirements } from \"../../../core/document/spec.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { ArchiveFailure } from \"./refusal.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function planSpecs(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes } = plan;\n  // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service\n  // spec. ONE code path for the pair of requirement-carrying files: the business\n  // spec.md and the architecture arch.spec.md ride the same delta algebra, the\n  // same prose-preserving rewrite and the same guards, parameterized by filename\n  // (SPEC_AXES) — a fork here would be two places the merge could disagree.\n  for (const svc of deltaServices) {\n    for (const axis of SPEC_AXES) {\n      const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];\n      if (!existsSync(deltaPath)) continue;\n\n      // The shared context: this is a deltaServices × SPEC_AXES loop, and a\n      // context-less locate is a full fleet walk per iteration.\n      const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];\n      // Resolved BEFORE the delta is parsed, because the parse now depends on\n      // it: a requirement's markdown links are relative to the file they were\n      // written in, and this merge moves the text two directories up the tree.\n      // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering\n      // here is what lets the fix see both ends of the move, including a\n      // service filed under a subsystem, whose living directory is deeper still.\n      const deltaReqs = parseRequirements(\n        rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }),\n      );\n      if (!existsSync(livingPath)) {\n        // New service (or first arch spec) — create the living file from the\n        // ADDED/MODIFIED requirements.\n        const created = applyRequirementDelta([], deltaReqs);\n        if (created.length === 0) {\n          say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);\n          continue;\n        }\n        const heading = axis.key === \"spec\" ? svc : `${svc} — architecture`;\n        const frontmatter = `---\\nservice: ${svc}\\nstatus: draft\\n---\\n\\n# ${heading}\\n\\n`;\n        writes.push(planWrite(livingPath, `${frontmatter}## Requirements\\n\\n${serializeRequirements(created)}`));\n        say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);\n        continue;\n      }\n      const livingText = await readUtf8(livingPath);\n      // TWO `## Requirements` headings would put the rewrite's one-section\n      // invariant to a choice it must not make: the run of the first would be\n      // rewritten while the second survived verbatim in the tail — and its\n      // requirements, collected by parseRequirements, would land in the run TOO.\n      // Mechanical, like a model-less landscape, so merge-failed, not --approve.\n      const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n      if (reqHeadings.length > 1) {\n        throw new ArchiveFailure(\n          \"merge-failed\",\n          `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n        );\n      }\n      const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n      writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n\n      const c = summarize(deltaReqs);\n      say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n    }\n  }\n}\n\n/**\n * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas\n * applied into the living `capabilities/<id>/spec.md`.\n *\n * Here rather than in a sixth file in this package because this module already\n * owns \"requirements merged into a living document\" — it owns\n * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`\n * call, and the business corpus needs all three unchanged. What differs from\n * `planSpecs` above is only where the living document lives and what a CREATED\n * one says at the top.\n *\n * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service\n * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),\n * so an archive that merged into a file it refused to create would make the\n * whole delta merge nothing — which is the `delta.no-delta-sections` failure\n * class, arriving through the merge instead of through the grammar.\n *\n * NO FRONTMATTER on a created capability document, and that is a decision\n * rather than an omission. Nothing reads a capability document's frontmatter:\n * `readCapabilityTree` classifies by the file's PRESENCE and\n * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A\n * `status:` field invented here would be the \"second list nothing keeps\n * current\" this axis was designed against.\n *\n * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`\n * creates `capabilities/`, which is one of the two ways a fleet opts INTO the\n * capability axis — from the next command on, `loam validate --all` grades a\n * corpus that did not exist before. A merge that changes what the whole fleet\n * is graded on must not do it silently.\n */\nexport async function planCapabilities(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { writes } = plan;\n  // Whether `capabilities/` exists is asked BEFORE the loop, because the loop\n  // is what would create it; `creating` records whether this run actually\n  // materialises a document, so the adoption line below is not printed by a\n  // run whose every capability delta merged into a document already there.\n  const adopting = !existsSync(capabilityDocsDir(config.docsDir));\n  let creating = false;\n  for (const doc of gated.capabilityDeltas) {\n    const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;\n    // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two\n    // directories deeper than `capabilities/<id>/`, so a citation of a glossary\n    // term or an ADR would land pointing above the repository.\n    const deltaReqs = parseRequirements(\n      rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }),\n    );\n    if (!existsSync(livingPath)) {\n      const created = applyRequirementDelta([], deltaReqs);\n      if (created.length === 0) {\n        say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);\n        continue;\n      }\n      // The heading is the id and nothing else. loam merges requirements and\n      // never prose, so it must not fabricate the narrative that is the whole\n      // point of the document — the line below tells the author it is theirs.\n      writes.push(planWrite(livingPath, `# ${doc.id}\\n\\n## Requirements\\n\\n${serializeRequirements(created)}`));\n      creating = true;\n      say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);\n      say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);\n      continue;\n    }\n    const livingText = await readUtf8(livingPath);\n    // The same one-section invariant as the service axis above, and the same\n    // reason it cannot be guessed at.\n    const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n    if (reqHeadings.length > 1) {\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n      );\n    }\n    const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n    writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n    const c = summarize(deltaReqs);\n    say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n  }\n  if (adopting && creating) {\n    say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n\n/**\n * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:\n * everything before the first requirement inside `## Requirements` (the intro,\n * the heading line, prose under the heading) and everything from the section's\n * end onward (the next `## ` heading to EOF) — the old cut was a substring\n * `indexOf(\"\\n## Requirements\")`, a prefix match that also hit\n * `## Requirements Extra` and silently destroyed every section after the\n * requirements. Prose BETWEEN requirements is body text of whatever is open\n * above it (parseRequirements attributes it to the previous requirement's last\n * scenario, or its text) and survives inside the re-serialized run, framing\n * normalized. `merged` must contain every living requirement — runArchive's\n * stray guard refuses any document whose requirements sit outside the section,\n * using the same heading definition, before this output is ever written.\n */\nfunction rewriteRequirementsRun(text: string, merged: Requirement[]): string {\n  const s = splitRequirementsSection(text);\n  // No `## Requirements` at all: the stray guard has already refused any doc\n  // whose requirements live elsewhere, so this one has none — open the section.\n  if (s === null) return `${text.trimEnd()}\\n\\n## Requirements\\n\\n${serializeRequirements(merged)}`;\n  const body = serializeRequirements(merged);\n  // head/tail are raw slices; only the run's own framing is normalized. When\n  // the section held no requirements yet, the glue supplies the blank line the\n  // author never had reason to write.\n  const headGlue = s.run !== \"\" || s.head.endsWith(\"\\n\\n\") ? \"\" : s.head.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  const tailGlue = s.tail === \"\" ? \"\" : \"\\n\";\n  return s.head + headGlue + body + tailGlue + s.tail;\n}\n\nfunction summarize(reqs: Requirement[]): { ADDED: number; MODIFIED: number; REMOVED: number } {\n  const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };\n  for (const r of reqs) {\n    if (r.kind === \"ADDED\") c.ADDED += 1;\n    else if (r.kind === \"MODIFIED\") c.MODIFIED += 1;\n    else if (r.kind === \"REMOVED\") c.REMOVED += 1;\n  }\n  return c;\n}\n\n/**\n * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to\n * `glossary/<term>.md`.\n *\n * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta\n * is folded into a living document by the requirement algebra because the two\n * documents share identified parts; a term document has one part, and merging\n * two definitions of one word is not something a machine may attempt. So the\n * definition the author wrote in the feature IS the definition that lands,\n * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing\n * else, not even the trailing newline.\n *\n * CREATE-ONLY, which is why this loop has no other branch. A term the living\n * glossary already defines was refused at the gate (`glossary.term-exists`,\n * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs\n * every path here is a file that does not exist. `planWrite` marks it\n * `exclusive`, so a race that created it between the gate and the commit fails\n * the write rather than overwriting somebody.\n *\n * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as\n * `planCapabilities` does for `capabilities/`: the directory's existence is the\n * axis's opt-in, so this merge changes what `loam validate --all` grades from\n * the next command on, and a merge that widens the fleet's own gate must not do\n * it silently.\n */\nexport async function planGlossary(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const glossary = await featureGlossary(gated.featureDir);\n  if (!glossary.present || glossary.terms.length === 0) return;\n  // Asked BEFORE the loop, because the loop is what would create it.\n  const adopting = !existsSync(glossaryDir(config.docsDir));\n  for (const term of glossary.terms) {\n    plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));\n    say(`  glossary: ${term.id} — created glossary/${term.id}.md`);\n  }\n  if (adopting) {\n    say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n"]}

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

@@ -0,0 +1,27 @@
+/**
+ * What one phase of an archive hands the next.
+ *
+ * `Gated` is everything the refusals resolved on the way through — the
+ * canonical id, the delta document parsed once, the issue lists. `Plan` is what
+ * the merges accumulate. Neither is a bag of conveniences: a value is in here
+ * exactly when two phases have to agree about it, and the alternative was
+ * fifteen parameters threaded through three functions in the same order.
+ */
+import {} from "../../../core/vocabulary/issue.js";
+import {} from "../../../core/staging/writes.js";
+import {} from "../../../core/kernel/ids/dirs.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/capabilities/tree.js";
+import {} from "../../../core/staging/interrupted.js";
+export function emptyPlan() {
+    return {
+        writes: [],
+        planWarns: [],
+        planGates: [],
+        openapiRemovals: [],
+        asyncapiRemovals: [],
+        architectureServices: new Set(),
+    };
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAc,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAmB,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAuB,MAAM,sCAAsC,CAAC;AA6C3E,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,oBAAoB,EAAE,IAAI,GAAG,EAAmB;KACjD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What one phase of an archive hands the next.\n *\n * `Gated` is everything the refusals resolved on the way through — the\n * canonical id, the delta document parsed once, the issue lists. `Plan` is what\n * the merges accumulate. Neither is a bag of conveniences: a value is in here\n * exactly when two phases have to agree about it, and the alternative was\n * fifteen parameters threaded through three functions in the same order.\n */\nimport { type Issue } from \"../../../core/vocabulary/issue.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { type FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type CapabilityDoc } from \"../../../core/capabilities/tree.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\n\nexport interface Gated {\n  /** The canonical feature id. The raw argument does not survive the gate. */\n  id: string;\n  dirName: string;\n  featureDir: FeatureDir;\n  /** Parsed ONCE for the whole run — loading it spins up a fresh Langium workspace. */\n  deltaDoc: LoadedDoc | undefined;\n  deltaServices: PathableService[];\n  /**\n   * The capability documents this feature's delta carries, walked ONCE in the\n   * gate. Three phases downstream ask about them — the conflict-marker scan,\n   * the strayed-requirement scan and the merge — and a second walk is a second\n   * chance to disagree about which capabilities the merge touches.\n   */\n  capabilityDeltas: CapabilityDoc[];\n  gating: Issue[];\n  advisory: Issue[];\n  archiveDir: string;\n  archiveDest: string;\n  /** The interrupted commit this run repaired, if any — `--json` reports it. */\n  recovered: CommitRecovery | null;\n  /** Every coherence issue the gate read, gating and advisory together. */\n  issues: Issue[];\n}\n\nexport interface Plan {\n  writes: PlannedWrite[];\n  /**\n   * Warnings born in the plan itself (openapi.op-modified,\n   * openapi.component-modified, the asyncapi.*-modified trio) — printed with\n   * the plan and carried into the `--json` envelope beside the coherence\n   * warnings.\n   */\n  planWarns: Issue[];\n  /** Gating issues born in the plan itself (openapi.ref-unresolved, asyncapi.ref-unresolved). */\n  planGates: Issue[];\n  openapiRemovals: Array<{ service: string; operations: string[] }>;\n  /** Living asyncapi slots the plan deletes on removal markers, by their labels. */\n  asyncapiRemovals: Array<{ service: string; slots: string[] }>;\n  /** Services this feature introduces on the architecture axis alone. */\n  architectureServices: Set<PathableService>;\n}\n\nexport function emptyPlan(): Plan {\n  return {\n    writes: [],\n    planWarns: [],\n    planGates: [],\n    openapiRemovals: [],\n    asyncapiRemovals: [],\n    architectureServices: new Set<PathableService>(),\n  };\n}\n"]}

package/dist/commands/archive/run.js

@@ -0,0 +1,252 @@
+/**
+ * The archive itself, under the docs lock: gate, plan, commit.
+ *
+ * The order is the command's whole safety property. Every refusal happens before
+ * a byte is planned (`./plan/gate.ts`), the plan is computed entirely in memory
+ * so a failure on any axis leaves the living docs untouched (`./plan/specs.ts`,
+ * `./plan/contracts/`, `./plan/landscape.ts`), and only a plan that succeeded
+ * on every axis is staged
+ * and swapped. `--dry-run` returns between the second and the third.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { emitJson, repoPath, sayExplain } from "../../core/envelope/json.js";
+import { message, quietPruneEmptyParents, quietRm, rollbackError, rollbackStaged, stageWrites, swapStaged, } from "../../core/staging/commit.js";
+import { clearCommitIntent, writeCommitIntent } from "../../core/staging/recovery/intent.js";
+import { SNAPSHOT_DIR, SnapshotClobberError, snapshotDir, writeSnapshot, } from "../../core/staging/snapshot.js";
+import { enumeratedServices } from "../../core/repo/service-target.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { gate } from "./plan/gate.js";
+import {} from "./plan/refusal.js";
+import { planCapabilities, planGlossary, planSpecs } from "./plan/specs.js";
+import { planOpenapiContracts } from "./plan/contracts/openapi.js";
+import { planAsyncapiContracts } from "./plan/contracts/asyncapi.js";
+import { planDeployments, planFlows, planLandscape } from "./plan/landscape.js";
+import { emptyPlan } from "./plan/state.js";
+import { issueJson, refuseJson } from "./plan/refusal.js";
+import { ArchiveFailure } from "./plan/refusal.js";
+import { printPlan } from "./plan/refusal.js";
+export async function archiveLocked(config, featureId, opts) {
+    const dryRun = opts.dryRun === true;
+    const json = opts.json === true;
+    // All prose goes through here so `--json` keeps stdout a single JSON document.
+    const say = (line = "") => {
+        if (!json)
+            console.log(line);
+    };
+    // One read index for the whole run, threaded through every planner's
+    // config record: gate, the spec merge and both contract merges each hold
+    // per-service loops that resolve living paths through the enumeration, and
+    // without a shared context every one of those calls re-walks the fleet —
+    // O(services²) work under a lock that guarantees the tree is not moving.
+    // The snapshot resolver below reads through the same context, so it pays
+    // for that enumeration too.
+    const read = { docsDir: config.docsDir, fleet: new FleetContext() };
+    const gated = await gate(read, featureId, opts, say);
+    if (gated === null)
+        return;
+    const { id, dirName, featureDir, gating, advisory, archiveDir, archiveDest, recovered, issues } = gated;
+    say(`archive ${id}${dryRun ? "  (dry run)" : ""}\n`);
+    // PLAN — compute every merge in memory. Nothing is written until the whole plan
+    // succeeds, so a failure on any axis leaves the living docs untouched.
+    const planned = emptyPlan();
+    await planSpecs(read, gated, planned, say);
+    // The business corpus, beside the service one and before the contracts: both
+    // are requirement merges, and reading them together is how a plan stays
+    // legible as "what this feature promises" followed by "how it is built".
+    await planCapabilities(read, gated, planned, say);
+    // The vocabulary the change brings with it, beside the promises it makes:
+    // a create-only whole-file copy, refused at the gate if the word already
+    // lives (`core/glossary/delta.ts`).
+    await planGlossary(read, gated, planned, say);
+    await planOpenapiContracts(read, gated, planned, say);
+    await planAsyncapiContracts(read, gated, planned, say);
+    await planLandscape(config, gated, planned, say);
+    // The flows this feature brings, after the elements they draw hops over: the
+    // copy is create-only and refused at the gate if the living tree already holds
+    // one (`core/usecases/delta/flows.ts`), and it is ordered after the landscape
+    // merge so a reader of the plan sees the map change before the sequence drawn
+    // on it.
+    await planFlows(config, gated, planned, say);
+    await planDeployments(config, gated, planned, say);
+    const { writes, planWarns, planGates, openapiRemovals, asyncapiRemovals } = planned;
+    // Gate on what only the plan could see: a merged operation pointing at a
+    // component that exists nowhere, a removal marker addressing no operation.
+    // Same doctrine as the coherence gate — a judgment call --approve overrides
+    // (unlike the mechanical merge-failed refusals), and a dry run is gated too.
+    // Checked after the whole plan so the refusal costs nothing: no write has
+    // happened yet either way.
+    if (planGates.length > 0 && !opts.approve) {
+        const msg = `archive ${id} — BLOCKED: ${planGates.length} issue(s) in the contract merge`;
+        if (json) {
+            refuseJson("not-coherent", msg, [...issues, ...planWarns, ...planGates], `features/${dirName}`);
+            return;
+        }
+        console.error(`${msg}:`);
+        for (const i of planGates)
+            console.error(`  ✗ ${i.message}`);
+        console.error(`\nFix them in the feature's openapi.yaml / asyncapi.yaml — or re-run with --approve to merge anyway.`);
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return;
+    }
+    if (planGates.length > 0) {
+        say(`\n  ⚠ archiving despite ${planGates.length} contract merge issue(s) (--approve):`);
+        for (const i of planGates)
+            say(`      ✗ ${i.message}`);
+    }
+    // The plan as data, verb decided now — after the commit everything would read
+    // as an update. The `--json` payload is identical for a dry run and the real
+    // thing except for `archived`; what WOULD happen is what DOES happen.
+    const warnings = [...advisory, ...planWarns];
+    const overridden = opts.approve === true ? [...gating, ...planGates] : [];
+    const plan = writes.map((w) => ({
+        path: repoPath(config.docsDir, w.path),
+        action: existsSync(w.path) ? "update" : "create",
+    }));
+    plan.push({ path: `features/${dirName}`, action: "move", to: `features/archive/${dirName}` });
+    const payload = (archived) => ({
+        command: "archive",
+        feature: id,
+        archived,
+        path: repoPath(config.docsDir, archiveDest),
+        plan,
+        warnings: warnings.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),
+        overridden: overridden.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),
+        openapiRemovals,
+        asyncapiRemovals,
+        // Present only when this run found an interrupted commit and dealt with it:
+        // an agent that sees the docs change under it deserves to be told why, and
+        // the absent field is the ordinary case.
+        ...(recovered === null ? {} : { recovered }),
+    });
+    if (dryRun) {
+        if (json)
+            emitJson(payload(false));
+        else
+            printPlan(config.docsDir, writes, dirName);
+        return;
+    }
+    // COMMIT — the whole plan computed cleanly. Stage every new version beside its
+    // target, snapshot what is about to be overwritten, then swap them into place.
+    // Staging touches the filesystem — a read-only `architecture/`, a full disk,
+    // a target whose pre-image cannot be read. None of that is a bug in loam, and
+    // reporting `internal` sends the reader looking for one; it is the same
+    // answer as any other merge that could not be computed: nothing was written.
+    let staged;
+    try {
+        staged = await stageWrites(writes);
+    }
+    catch (err) {
+        throw new ArchiveFailure("merge-failed", `${message(err)} — nothing was written`);
+    }
+    let snapshot = false;
+    let createdArchiveDir;
+    try {
+        // The snapshot's resolver pair: how a docs-relative path decomposes into a
+        // service identity, and where that identity lives NOW. Built here — the
+        // command layer's view of the tree — and injected, so the snapshot module
+        // never learns the repo layout. The seam the flat wave left is now
+        // threaded: both answers come from the enumeration, so a service filed
+        // into a subsystem keys its snapshot rows by the directory it actually
+        // lives in, and the clobber guard grades a leftover claim at that same
+        // address. The root-level parse stays as the fallback for the one path
+        // shape the enumeration cannot know yet — a service this archive CREATES,
+        // which always materialises unfiled at services/<id>/.
+        // Tolerant on purpose: a docs repo whose services/ is absent still
+        // archives a landscape-only feature exactly as before — the enumeration
+        // is empty, every row keys by the flat fallback, and the missing
+        // directory stays doctor's diagnosis rather than a merge-failed here.
+        const dirOf = new Map((await enumeratedServices(config.docsDir, read.fleet)).map((s) => [s.id, repoPath(config.docsDir, s.dir)]));
+        const serviceKeyOf = (rel) => {
+            for (const [service, dir] of dirOf) {
+                if (rel.startsWith(`${dir}/`))
+                    return { service, artifact: rel.slice(dir.length + 1) };
+            }
+            const m = /^services\/([^/]+)\/(.+)$/.exec(rel);
+            return m ? { service: m[1], artifact: m[2] } : null;
+        };
+        const serviceDirOf = (service) => dirOf.get(service) ?? null;
+        await writeSnapshot({
+            featureDir,
+            docsDir: config.docsDir,
+            feature: { featureId: id, dirName },
+            staged,
+            serviceKeyOf,
+            serviceDirOf,
+        });
+        snapshot = true;
+        // The journal, fsynced, BEFORE the first rename: swapStaged is N renames and
+        // only each one of them is atomic, so a kill between two used to leave a
+        // half-merged repo that nothing could name — `doctor` and `status` called it
+        // healthy and `validate --all` blamed the delta. Written from `staged`, so
+        // it records the same digests the swaps are about to produce.
+        await writeCommitIntent(config.docsDir, { command: "archive", restore: "before", feature: id, moveFrom: featureDir, moveTo: archiveDest }, staged);
+        await swapStaged(staged);
+        createdArchiveDir = await mkdir(archiveDir, { recursive: true });
+        await rename(featureDir, archiveDest);
+        // Last: while it exists, the commit is in flight.
+        await clearCommitIntent(config.docsDir);
+    }
+    catch (err) {
+        if (err instanceof SnapshotClobberError) {
+            // Nothing swapped — the refusal happens before the journal is even
+            // written — so this only takes the temp files away. Its own code, because
+            // the answer is not "re-run": a previous archive of this feature is still
+            // sitting in the living docs.
+            await rollbackStaged(staged);
+            throw new ArchiveFailure("commit-interrupted", err.message);
+        }
+        // Everything this run made, unmade: the swapped files, the snapshot inside the
+        // feature that is staying put, and features/archive/ if we are the ones who
+        // created it (mkdir reports nothing when it was already there).
+        const failures = await rollbackStaged(staged);
+        // The rollback decided the outcome, so the journal has nothing left to
+        // describe — including on rollback-incomplete, where the files it names are
+        // the ones the message tells a human to look at.
+        await clearCommitIntent(config.docsDir);
+        // The snapshot goes only when the rollback HELD. On rollback-incomplete it
+        // holds the only on-disk pre-images of the very files the message tells the
+        // reader to repair by hand — a MODIFIED requirement's previous text appears
+        // nowhere else. Retaining it is safe: the next archive of this feature reads
+        // it before it would replace it, and refuses if the living docs have moved.
+        if (snapshot && failures.length === 0)
+            await quietRm(snapshotDir(featureDir));
+        // `features/archive/` is shared the moment it exists: another archive can
+        // have moved a whole feature into it between our mkdir and this rollback,
+        // and a recursive remove of "the directory we created" took that feature —
+        // snapshot and all — with it, on OUR failure path, in silence. Empty
+        // directories only, stopping at the first that is not.
+        if (createdArchiveDir !== undefined)
+            await quietPruneEmptyParents(archiveDir, createdArchiveDir);
+        // The code is a caller's answer to "can I trust the repo?": merge-failed
+        // means yes (rolled back), rollback-incomplete means look at it by hand.
+        const wrapped = rollbackError(err, failures);
+        const kept = snapshot && failures.length > 0
+            ? ` Pre-images of the overwritten files are kept in features/${dirName}/${SNAPSHOT_DIR}/files/.`
+            : "";
+        throw new ArchiveFailure(failures.length > 0 ? "rollback-incomplete" : "merge-failed", wrapped.message + kept);
+    }
+    if (json) {
+        emitJson(payload(true));
+        return;
+    }
+    console.log(`\n  archived: features/${dirName} → features/archive/${dirName}`);
+    console.log(`  snapshot: features/archive/${dirName}/${SNAPSHOT_DIR}/ — \`loam unarchive ${id}\` puts it back`);
+    // The closing line is a claim about the whole docs repo, and it is the line a
+    // reader stops at. It may be printed only when this archive left nothing the
+    // next `validate --all` will fail on — a service with no model, or a gate the
+    // caller told it to merge past. Printing it over either is how a red fleet
+    // gets reported as a finished one.
+    const incomplete = planWarns.filter((w) => w.code === "service.no-model");
+    if (incomplete.length === 0 && overridden.length === 0) {
+        console.log("  living spec + landscape are now complete + current.");
+        return;
+    }
+    for (const w of incomplete)
+        console.log(`  ⚠ ${w.message}`);
+    if (overridden.length > 0) {
+        console.log(`  ⚠ merged past ${overridden.length} gating issue(s) with --approve — the living docs carry them now; \`loam validate --all\` says what they cost.`);
+    }
+}
+//# sourceMappingURL=run.js.map