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

package/dist/commands/archive/plan/contracts/openapi.js

@@ -8,7 +8,9 @@
  * leaves the living docs exactly as they were.
  */
 import { existsSync } from "node:fs";
-import { repoPath } from "../../../../core/envelope/json.js";
+import { parse } from "yaml";
+import { CodedFailure, repoPath } from "../../../../core/envelope/json.js";
+import { isRecord } from "../../../../core/kernel/records.js";
 import { planWrite, readUtf8 } from "../../../../core/staging/writes.js";
 import { featureSpecPaths } from "../../../../core/repo/paths.js";
 import { locateServicePaths } from "../../../../core/repo/service-target.js";
@@ -16,11 +18,12 @@ import { readOpenapi } from "../../../../core/openapi/doc.js";
 import { OpenapiMergeError } from "../../../../core/openapi/merge/error.js";
 import { stripOpenapiRemovalMarkers } from "../../../../core/openapi/merge/markers.js";
 import { mergeOpenapiPaths } from "../../../../core/openapi/merge/merge.js";
-import { ArchiveFailure } from "../refusal.js";
 import {} from "../state.js";
+import { consumerClause } from "./consumers.js";
+import { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from "./verdict-lines.js";
 export async function planOpenapiContracts(config, gated, plan, say) {
     const { featureDir, deltaServices } = gated;
-    const { writes, planWarns, planGates, openapiRemovals } = plan;
+    const { writes, planGates, openapiRemovals } = plan;
     // OpenAPI merge — fold the feature's openapi deltas into the living service APIs.
     for (const svc of deltaServices) {
         const featOpenapi = featureSpecPaths(featureDir, svc).openapi;
@@ -40,7 +43,7 @@ export async function planOpenapiContracts(config, gated, plan, say) {
         // A document loam cannot read is one it cannot merge, and that is the same
         // answer as any other merge it could not compute: nothing is written.
         if (featDoc.unreadable) {
-            throw new ArchiveFailure("merge-failed", `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? "not a YAML mapping"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
+            throw new CodedFailure("merge-failed", `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? "not a YAML mapping"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
         }
         const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);
         // An `x-loam-remove: true` written at PATH level retires nothing: the marker
@@ -65,20 +68,33 @@ export async function planOpenapiContracts(config, gated, plan, say) {
             // "does the reader see a removal" let exactly that marker through into a
             // living contract, published to every consumer of the fleet.
             const content = stripOpenapiRemovalMarkers(featText, svc);
+            // A contract that describes nothing is not created, on the spec axis's
+            // rule for a delta that leaves no requirements (../specs.ts). A
+            // `paths: {}` stub is what an author wrote to quiet a status that used to
+            // demand a contract from every new service, and copying it in published
+            // "this service exposes nothing" as a living contract the fleet then
+            // joins against — announced as `created ()`. With no file, the service
+            // reads as one with no HTTP surface, which `service.no-openapi` already
+            // grades: silent while nothing calls it, an error once something does.
+            if (describesNothing(content)) {
+                say(`  openapi: ${svc} — nothing to merge (delta defines no paths or components), no living openapi.yaml created`);
+                continue;
+            }
             writes.push(planWrite(livingOpenapi, content));
             say(`  openapi: ${svc} — created (${ops.join(", ")})`);
         }
         else {
+            const livingText = await readUtf8(livingOpenapi);
             let merge;
             try {
-                merge = mergeOpenapiPaths(await readUtf8(livingOpenapi), featText, svc);
+                merge = mergeOpenapiPaths(livingText, featText, svc);
             }
             catch (err) {
                 if (err instanceof OpenapiMergeError)
-                    throw new ArchiveFailure("merge-failed", err.message);
+                    throw new CodedFailure("merge-failed", err.message);
                 throw err;
             }
-            const { text, modified, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale, componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved, } = merge;
+            const { text, modified, modifiedOperationIds, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale, componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved, } = merge;
             if (text !== null) {
                 writes.push(planWrite(livingOpenapi, text));
                 // The parenthesised list names the OPERATIONS the delta merged, and a
@@ -92,58 +108,46 @@ export async function planOpenapiContracts(config, gated, plan, say) {
                 const mergedNames = ops.length > 0 ? ops : componentsAdded.map((comp) => `component ${comp}`);
                 say(`  openapi: ${svc} — merged${mergedNames.length > 0 ? ` (${mergedNames.join(", ")})` : ""}`);
             }
+            // Asked whatever the merge wrote, for the event planner's reason: an
+            // `info`-only delta merges nothing, and archived in silence.
+            warnInfoDrift(plan, say, {
+                svc, code: "openapi.info-not-merged", file: "openapi.yaml", carries: "paths and components",
+                labels: infoDrift(parse(livingText), parse(featText)),
+            });
             if (removed.length > 0) {
                 openapiRemovals.push({ service: svc, operations: removed });
                 for (const label of removed)
                     say(`      - removes ${label}`);
             }
-            // Said out loud, because "the plan wrote less than my delta spells" is
-            // the one thing a reader cannot infer from a merged file. Not a warning:
-            // quoting the contract around your change is correct authoring, and
-            // leaving the quote alone is the correct merge. The path-level and
-            // component quotes get the same sentence for the same reason.
-            for (const label of quoted)
-                say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);
-            for (const label of pathItemQuoted) {
-                say(`      · quotes path-level ${label} — unchanged since it was pinned, left as living has it`);
-            }
-            for (const comp of componentsQuoted) {
-                say(`      · quotes component ${comp} — unchanged since it was pinned, left as living has it`);
-            }
-            // Stale surfaces reaching the merge at all means --approve pushed past
-            // the gate's openapi.baseline-stale — the plan still names what it cost.
-            for (const label of pathItemStale) {
-                say(`      ⚠ stale baseline on path-level ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
-            }
-            for (const comp of componentsStale) {
-                say(`      ⚠ stale baseline on component ${comp} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
-            }
+            // The quote and stale lines (./verdict-lines.ts says why each is said).
+            sayQuoted(say, quoted);
+            sayQuoted(say, pathItemQuoted.map((label) => `path-level ${label}`));
+            sayQuoted(say, componentsQuoted.map((comp) => `component ${comp}`));
+            sayStale(say, pathItemStale.map((label) => `path-level ${label}`));
+            sayStale(say, componentsStale.map((comp) => `component ${comp}`));
             for (const label of modified) {
-                planWarns.push({
-                    severity: "warn",
-                    code: "openapi.op-modified",
-                    subject: svc,
+                // Who the overwrite lands on: the living fleet's consumers of the
+                // operation, through `loam diff`'s own scan (./consumers.ts). An
+                // operation with no operationId on either side has nothing anyone can
+                // name it by, so the warning stays the sentence it always was.
+                const id = modifiedOperationIds.get(label);
+                const named = id === undefined ? null : consumerClause(await config.consumers.op(svc, id));
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.op-modified", label, named,
                     message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,
                 });
-                say(`      ⚠ overwrites ${label} — the living definition differs`);
             }
             for (const label of pathItemModified) {
-                planWarns.push({
-                    severity: "warn",
-                    code: "openapi.path-item-modified",
-                    subject: svc,
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.path-item-modified", label: `path-level ${label}`,
                     message: `${svc}: the delta redefines the path-level key ${label}, which the living OpenAPI already has — the merge overwrites it wholesale, and it applies to EVERY operation on that path, including ones this feature never mentions`,
                 });
-                say(`      ⚠ overwrites path-level ${label} — the living definition differs`);
             }
             for (const comp of componentsModified) {
-                planWarns.push({
-                    severity: "warn",
-                    code: "openapi.component-modified",
-                    subject: svc,
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.component-modified", label: `component ${comp}`,
                     message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,
                 });
-                say(`      ⚠ overwrites component ${comp} — the living definition differs`);
             }
             for (const u of unresolved) {
                 planGates.push({
@@ -156,4 +160,34 @@ export async function planOpenapiContracts(config, gated, plan, say) {
         }
     }
 }
+/**
+ * Does this contract describe no surface at all — no path, no webhook, and no
+ * component in any section? Only the document's frame is left (`openapi`,
+ * `info`, `servers`, `tags`), which is a title and nothing anyone can call.
+ *
+ * Conservative in one direction: anything that is not an empty mapping where a
+ * mapping belongs counts as content, so a document this cannot classify is
+ * created exactly as before. The reader above has already refused one that
+ * does not parse.
+ */
+function describesNothing(text) {
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    catch {
+        // Not a document this can classify, so it is content: created as before.
+        return false;
+    }
+    if (doc === null || doc === undefined)
+        return true;
+    if (!isRecord(doc))
+        return false;
+    const components = doc["components"];
+    const sections = components === undefined || components === null ? [] : isRecord(components) ? Object.values(components) : [components];
+    return [doc["paths"], doc["webhooks"], ...sections].every(isEmptyMapping);
+}
+function isEmptyMapping(value) {
+    return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);
+}
 //# sourceMappingURL=openapi.js.map

package/dist/commands/archive/plan/contracts/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OpenAPI contract merge: the feature's openapi deltas folded into each\n * living service API — the half of the archive plan that answers to the\n * contract axis, split out of ../specs.ts so the requirements merge and the\n * contract merges stop sharing one file.\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 { repoPath } from \"../../../../core/envelope/json.js\";\nimport { planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport { featureSpecPaths } from \"../../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../../core/repo/service-target.js\";\nimport { readOpenapi } from \"../../../../core/openapi/doc.js\";\nimport { OpenapiMergeError } from \"../../../../core/openapi/merge/error.js\";\nimport { stripOpenapiRemovalMarkers } from \"../../../../core/openapi/merge/markers.js\";\nimport { mergeOpenapiPaths, type OpenapiMergeResult } from \"../../../../core/openapi/merge/merge.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 planOpenapiContracts(\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, planWarns, planGates, openapiRemovals } = plan;\n  // OpenAPI merge — fold the feature's openapi deltas into the living service APIs.\n  for (const svc of deltaServices) {\n    const featOpenapi = featureSpecPaths(featureDir, svc).openapi;\n    if (!existsSync(featOpenapi)) continue;\n    const featText = await readUtf8(featOpenapi);\n    // The shared context: this planner runs once per delta service, and a\n    // context-less locate is a full fleet walk per service.\n    const livingOpenapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).openapi;\n    const featDoc = await readOpenapi(featOpenapi);\n    // Every other reader of this flag suspends its own judgement when it is set\n    // — validate grades `openapi.invalid`, show and status print that the file\n    // does not parse. Archive was the only one that never looked, and it is the\n    // command that WRITES: a feature openapi.yaml holding a sequence instead of\n    // a mapping was planned verbatim into services/<svc>/openapi.yaml, `ok:\n    // true`, printing `created ()` because the reader saw no operations in it.\n    // A document loam cannot read is one it cannot merge, and that is the same\n    // answer as any other merge it could not compute: nothing is written.\n    if (featDoc.unreadable) {\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? \"not a YAML mapping\"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`,\n      );\n    }\n    const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);\n    // An `x-loam-remove: true` written at PATH level retires nothing: the marker\n    // addresses one operation, and beside the methods there is no operation for\n    // it to address. The merge now strips it on every branch, so the living\n    // contract is safe either way — but the author asked for a removal that will\n    // not happen, and silence there is how a retired endpoint stayed live.\n    // Gated like the other plan-visible breaches, --approve and all.\n    for (const path of featDoc.pathLevelRemovals) {\n      planGates.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: svc,\n        message: `${svc}: '${path}' carries x-loam-remove at PATH level, beside the methods — a removal marker names ONE operation, so this retires nothing and is not a contract key either. Move it inside the operation you are retiring (with its operationId), or delete it.`,\n      });\n    }\n    if (!existsSync(livingOpenapi)) {\n      // A removal against a non-existent contract is gated by coherence. Keep\n      // the feature-only marker out of living docs even under --approve — and\n      // ask the DOCUMENT, not the operation reader: a marker with no\n      // operationId is invisible to `operations()`, so gating the strip on\n      // \"does the reader see a removal\" let exactly that marker through into a\n      // living contract, published to every consumer of the fleet.\n      const content = stripOpenapiRemovalMarkers(featText, svc);\n      writes.push(planWrite(livingOpenapi, content));\n      say(`  openapi: ${svc} — created (${ops.join(\", \")})`);\n    } else {\n      let merge: OpenapiMergeResult;\n      try {\n        merge = mergeOpenapiPaths(await readUtf8(livingOpenapi), featText, svc);\n      } catch (err) {\n        if (err instanceof OpenapiMergeError) throw new ArchiveFailure(\"merge-failed\", err.message);\n        throw err;\n      }\n      const {\n        text, modified, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale,\n        componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved,\n      } = merge;\n      if (text !== null) {\n        writes.push(planWrite(livingOpenapi, text));\n        // The parenthesised list names the OPERATIONS the delta merged, and a\n        // delta whose whole change is a component has none — so this printed\n        // `merged ()`, the same empty-parenthesis lie the create branch above\n        // is commented for: it reads as \"this merge wrote nothing\" about a\n        // merge that just published a shared schema to every consumer of the\n        // fleet. Name the components it added instead, and drop the\n        // parentheses entirely when there is nothing to put in them — a delta\n        // that only EDITED existing surfaces is named by the lines below.\n        const mergedNames = ops.length > 0 ? ops : componentsAdded.map((comp) => `component ${comp}`);\n        say(`  openapi: ${svc} — merged${mergedNames.length > 0 ? ` (${mergedNames.join(\", \")})` : \"\"}`);\n      }\n      if (removed.length > 0) {\n        openapiRemovals.push({ service: svc, operations: removed });\n        for (const label of removed) say(`      - removes ${label}`);\n      }\n      // Said out loud, because \"the plan wrote less than my delta spells\" is\n      // the one thing a reader cannot infer from a merged file. Not a warning:\n      // quoting the contract around your change is correct authoring, and\n      // leaving the quote alone is the correct merge. The path-level and\n      // component quotes get the same sentence for the same reason.\n      for (const label of quoted) say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);\n      for (const label of pathItemQuoted) {\n        say(`      · quotes path-level ${label} — unchanged since it was pinned, left as living has it`);\n      }\n      for (const comp of componentsQuoted) {\n        say(`      · quotes component ${comp} — unchanged since it was pinned, left as living has it`);\n      }\n      // Stale surfaces reaching the merge at all means --approve pushed past\n      // the gate's openapi.baseline-stale — the plan still names what it cost.\n      for (const label of pathItemStale) {\n        say(`      ⚠ stale baseline on path-level ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const comp of componentsStale) {\n        say(`      ⚠ stale baseline on component ${comp} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const label of modified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.op-modified\",\n          subject: svc,\n          message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,\n        });\n        say(`      ⚠ overwrites ${label} — the living definition differs`);\n      }\n      for (const label of pathItemModified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.path-item-modified\",\n          subject: svc,\n          message: `${svc}: the delta redefines the path-level key ${label}, which the living OpenAPI already has — the merge overwrites it wholesale, and it applies to EVERY operation on that path, including ones this feature never mentions`,\n        });\n        say(`      ⚠ overwrites path-level ${label} — the living definition differs`);\n      }\n      for (const comp of componentsModified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.component-modified\",\n          subject: svc,\n          message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,\n        });\n        say(`      ⚠ overwrites component ${comp} — the living definition differs`);\n      }\n      for (const u of unresolved) {\n        planGates.push({\n          severity: \"error\",\n          code: \"openapi.ref-unresolved\",\n          subject: svc,\n          message: `${svc}: $ref '${u.ref}' (referenced from ${u.from}) resolves in neither the feature's openapi.yaml nor the living one — the merged document would carry a dangling reference`,\n        });\n      }\n    }\n  }\n}\n"]}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OpenAPI contract merge: the feature's openapi deltas folded into each\n * living service API — the half of the archive plan that answers to the\n * contract axis, split out of ../specs.ts so the requirements merge and the\n * contract merges stop sharing one file.\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 { parse } from \"yaml\";\nimport { CodedFailure, repoPath } from \"../../../../core/envelope/json.js\";\nimport { isRecord } from \"../../../../core/kernel/records.js\";\nimport { planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport { featureSpecPaths } from \"../../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../../core/repo/service-target.js\";\nimport { readOpenapi } from \"../../../../core/openapi/doc.js\";\nimport { OpenapiMergeError } from \"../../../../core/openapi/merge/error.js\";\nimport { stripOpenapiRemovalMarkers } from \"../../../../core/openapi/merge/markers.js\";\nimport { mergeOpenapiPaths, type OpenapiMergeResult } from \"../../../../core/openapi/merge/merge.js\";\nimport { type Gated, type Plan } from \"../state.js\";\nimport { consumerClause, type ContractConsumers } from \"./consumers.js\";\nimport { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from \"./verdict-lines.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../../core/fleet-context.js\";\n\nexport async function planOpenapiContracts(\n  config: { docsDir: DocsDir; fleet: FleetContext; consumers: ContractConsumers },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes, planGates, openapiRemovals } = plan;\n  // OpenAPI merge — fold the feature's openapi deltas into the living service APIs.\n  for (const svc of deltaServices) {\n    const featOpenapi = featureSpecPaths(featureDir, svc).openapi;\n    if (!existsSync(featOpenapi)) continue;\n    const featText = await readUtf8(featOpenapi);\n    // The shared context: this planner runs once per delta service, and a\n    // context-less locate is a full fleet walk per service.\n    const livingOpenapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).openapi;\n    const featDoc = await readOpenapi(featOpenapi);\n    // Every other reader of this flag suspends its own judgement when it is set\n    // — validate grades `openapi.invalid`, show and status print that the file\n    // does not parse. Archive was the only one that never looked, and it is the\n    // command that WRITES: a feature openapi.yaml holding a sequence instead of\n    // a mapping was planned verbatim into services/<svc>/openapi.yaml, `ok:\n    // true`, printing `created ()` because the reader saw no operations in it.\n    // A document loam cannot read is one it cannot merge, and that is the same\n    // answer as any other merge it could not compute: nothing is written.\n    if (featDoc.unreadable) {\n      throw new CodedFailure(\n        \"merge-failed\",\n        `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? \"not a YAML mapping\"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`,\n      );\n    }\n    const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);\n    // An `x-loam-remove: true` written at PATH level retires nothing: the marker\n    // addresses one operation, and beside the methods there is no operation for\n    // it to address. The merge now strips it on every branch, so the living\n    // contract is safe either way — but the author asked for a removal that will\n    // not happen, and silence there is how a retired endpoint stayed live.\n    // Gated like the other plan-visible breaches, --approve and all.\n    for (const path of featDoc.pathLevelRemovals) {\n      planGates.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: svc,\n        message: `${svc}: '${path}' carries x-loam-remove at PATH level, beside the methods — a removal marker names ONE operation, so this retires nothing and is not a contract key either. Move it inside the operation you are retiring (with its operationId), or delete it.`,\n      });\n    }\n    if (!existsSync(livingOpenapi)) {\n      // A removal against a non-existent contract is gated by coherence. Keep\n      // the feature-only marker out of living docs even under --approve — and\n      // ask the DOCUMENT, not the operation reader: a marker with no\n      // operationId is invisible to `operations()`, so gating the strip on\n      // \"does the reader see a removal\" let exactly that marker through into a\n      // living contract, published to every consumer of the fleet.\n      const content = stripOpenapiRemovalMarkers(featText, svc);\n      // A contract that describes nothing is not created, on the spec axis's\n      // rule for a delta that leaves no requirements (../specs.ts). A\n      // `paths: {}` stub is what an author wrote to quiet a status that used to\n      // demand a contract from every new service, and copying it in published\n      // \"this service exposes nothing\" as a living contract the fleet then\n      // joins against — announced as `created ()`. With no file, the service\n      // reads as one with no HTTP surface, which `service.no-openapi` already\n      // grades: silent while nothing calls it, an error once something does.\n      if (describesNothing(content)) {\n        say(`  openapi: ${svc} — nothing to merge (delta defines no paths or components), no living openapi.yaml created`);\n        continue;\n      }\n      writes.push(planWrite(livingOpenapi, content));\n      say(`  openapi: ${svc} — created (${ops.join(\", \")})`);\n    } else {\n      const livingText = await readUtf8(livingOpenapi);\n      let merge: OpenapiMergeResult;\n      try {\n        merge = mergeOpenapiPaths(livingText, featText, svc);\n      } catch (err) {\n        if (err instanceof OpenapiMergeError) throw new CodedFailure(\"merge-failed\", err.message);\n        throw err;\n      }\n      const {\n        text, modified, modifiedOperationIds, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale,\n        componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved,\n      } = merge;\n      if (text !== null) {\n        writes.push(planWrite(livingOpenapi, text));\n        // The parenthesised list names the OPERATIONS the delta merged, and a\n        // delta whose whole change is a component has none — so this printed\n        // `merged ()`, the same empty-parenthesis lie the create branch above\n        // is commented for: it reads as \"this merge wrote nothing\" about a\n        // merge that just published a shared schema to every consumer of the\n        // fleet. Name the components it added instead, and drop the\n        // parentheses entirely when there is nothing to put in them — a delta\n        // that only EDITED existing surfaces is named by the lines below.\n        const mergedNames = ops.length > 0 ? ops : componentsAdded.map((comp) => `component ${comp}`);\n        say(`  openapi: ${svc} — merged${mergedNames.length > 0 ? ` (${mergedNames.join(\", \")})` : \"\"}`);\n      }\n      // Asked whatever the merge wrote, for the event planner's reason: an\n      // `info`-only delta merges nothing, and archived in silence.\n      warnInfoDrift(plan, say, {\n        svc, code: \"openapi.info-not-merged\", file: \"openapi.yaml\", carries: \"paths and components\",\n        labels: infoDrift(parse(livingText), parse(featText)),\n      });\n      if (removed.length > 0) {\n        openapiRemovals.push({ service: svc, operations: removed });\n        for (const label of removed) say(`      - removes ${label}`);\n      }\n      // The quote and stale lines (./verdict-lines.ts says why each is said).\n      sayQuoted(say, quoted);\n      sayQuoted(say, pathItemQuoted.map((label) => `path-level ${label}`));\n      sayQuoted(say, componentsQuoted.map((comp) => `component ${comp}`));\n      sayStale(say, pathItemStale.map((label) => `path-level ${label}`));\n      sayStale(say, componentsStale.map((comp) => `component ${comp}`));\n      for (const label of modified) {\n        // Who the overwrite lands on: the living fleet's consumers of the\n        // operation, through `loam diff`'s own scan (./consumers.ts). An\n        // operation with no operationId on either side has nothing anyone can\n        // name it by, so the warning stays the sentence it always was.\n        const id = modifiedOperationIds.get(label);\n        const named = id === undefined ? null : consumerClause(await config.consumers.op(svc, id));\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.op-modified\", label, named,\n          message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,\n        });\n      }\n      for (const label of pathItemModified) {\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.path-item-modified\", label: `path-level ${label}`,\n          message: `${svc}: the delta redefines the path-level key ${label}, which the living OpenAPI already has — the merge overwrites it wholesale, and it applies to EVERY operation on that path, including ones this feature never mentions`,\n        });\n      }\n      for (const comp of componentsModified) {\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.component-modified\", label: `component ${comp}`,\n          message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,\n        });\n      }\n      for (const u of unresolved) {\n        planGates.push({\n          severity: \"error\",\n          code: \"openapi.ref-unresolved\",\n          subject: svc,\n          message: `${svc}: $ref '${u.ref}' (referenced from ${u.from}) resolves in neither the feature's openapi.yaml nor the living one — the merged document would carry a dangling reference`,\n        });\n      }\n    }\n  }\n}\n\n/**\n * Does this contract describe no surface at all — no path, no webhook, and no\n * component in any section? Only the document's frame is left (`openapi`,\n * `info`, `servers`, `tags`), which is a title and nothing anyone can call.\n *\n * Conservative in one direction: anything that is not an empty mapping where a\n * mapping belongs counts as content, so a document this cannot classify is\n * created exactly as before. The reader above has already refused one that\n * does not parse.\n */\nfunction describesNothing(text: string): boolean {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch {\n    // Not a document this can classify, so it is content: created as before.\n    return false;\n  }\n  if (doc === null || doc === undefined) return true;\n  if (!isRecord(doc)) return false;\n  const components = doc[\"components\"];\n  const sections = components === undefined || components === null ? [] : isRecord(components) ? Object.values(components) : [components];\n  return [doc[\"paths\"], doc[\"webhooks\"], ...sections].every(isEmptyMapping);\n}\n\nfunction isEmptyMapping(value: unknown): boolean {\n  return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);\n}\n"]}

package/dist/commands/archive/plan/contracts/verdict-lines.js

@@ -0,0 +1,103 @@
+/**
+ * The plan lines a contract merge's verdicts print — the quote, the stale
+ * baseline, the overwrite and the `info` the merge does not carry — spelled
+ * once for both planners
+ * (./openapi.ts, ./asyncapi.ts), which used to print them in fourteen parallel
+ * loops. Every surface reaches the reader by exactly the same sentence an
+ * operation or a slot does, because it is graded by exactly the same verdict;
+ * one spelling is what keeps the two axes from describing one verdict in two
+ * sentences. The label prefix (`path-level …`, `component …`, `components.…`)
+ * stays at the call site: it is the one part that differs.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { withoutFeatureKeysDeep } from "../../../../core/openapi/digest.js";
+import { isRecord } from "../../../../core/kernel/records.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+/**
+ * Said out loud, because "the plan wrote less than my delta spells" is the one
+ * thing a reader cannot infer from a merged file. Not a warning: quoting the
+ * contract around your change is correct authoring, and leaving the quote
+ * alone is the correct merge. The path-level and component quotes get the
+ * same sentence for the same reason.
+ */
+export function sayQuoted(say, labels) {
+    for (const label of labels)
+        say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);
+}
+/**
+ * Stale surfaces reaching the merge at all means --approve pushed past the
+ * gate's `openapi.baseline-stale` / `asyncapi.baseline-stale` — the plan still
+ * names what it cost.
+ */
+export function sayStale(say, labels) {
+    for (const label of labels) {
+        say(`      ⚠ stale baseline on ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+    }
+}
+/**
+ * Warn about one overwrite and print it. The consumer clause, when there is
+ * one, ends both the warning's message and the printed line, and its evidence
+ * rides as the warning's `details` and as indented lines under it.
+ */
+export function warnOverwrite(plan, say, overwrite) {
+    const named = overwrite.named ?? null;
+    const clause = named === null ? "" : `; ${named.clause}`;
+    plan.planWarns.push({
+        severity: "warn",
+        code: overwrite.code,
+        subject: overwrite.svc,
+        message: overwrite.message + clause,
+        ...(named === null ? {} : { details: named.details }),
+    });
+    say(`      ⚠ overwrites ${overwrite.label} — the living definition differs${clause}`);
+    for (const line of named?.details ?? [])
+        say(`          ${line}`);
+}
+/**
+ * The `info` keys a feature's contract spells differently from the living one,
+ * as `info.<key>` labels, sorted — empty when the delta writes no `info`, or
+ * writes exactly what living has.
+ *
+ * Neither merge carries `info` (nor any root key outside the sections it
+ * merges: `../../../../core/asyncapi/merge/markers.ts` names what those are),
+ * and that is a decision rather than a gap — a delta is a diff of operations
+ * and slots, and its `info` is most often the scaffold's or a copy. But a
+ * delta that DID move it — a new version, a rewritten description — lost the
+ * change with exit 0 and nothing in the plan, so the reader learned it from
+ * the living file weeks later. Only keys the delta declares are compared: a
+ * key living has and the delta leaves out is a key nobody asked to change.
+ * Feature bookkeeping is never compared: an `x-loam-*` key of `info` itself is
+ * skipped, and the merges' own markers are stripped from the values below it
+ * (`withoutFeatureKeysDeep`), so a pin can never read as drift.
+ */
+export function infoDrift(livingPlain, featurePlain) {
+    const feature = isRecord(featurePlain) ? featurePlain.info : undefined;
+    if (!isRecord(feature))
+        return [];
+    const living = isRecord(livingPlain) && isRecord(livingPlain.info) ? livingPlain.info : {};
+    return Object.keys(feature)
+        .filter((key) => !key.startsWith("x-loam-"))
+        .filter((key) => !isDeepStrictEqual(withoutFeatureKeysDeep(feature[key]), living[key]))
+        .map((key) => `info.${key}`)
+        .sort(compareIds);
+}
+/**
+ * Warn about one contract's `info` drift and print it. A warning, not a gate:
+ * keeping the living `info` is the merge working as designed, and the remedy —
+ * edit the living file in the same change — is the author's call. What must
+ * not happen is the silence.
+ */
+export function warnInfoDrift(plan, say, drift) {
+    if (drift.labels.length === 0)
+        return;
+    const which = drift.labels.join(", ");
+    plan.planWarns.push({
+        severity: "warn",
+        code: drift.code,
+        subject: drift.svc,
+        message: `${drift.svc}: the delta's ${which} differ(s) from the living ${drift.file} — the merge carries ${drift.carries} and never ` +
+            `info, so the living contract keeps its own. If it should move, edit the living ${drift.file} in this change.`,
+    });
+    say(`      ⚠ info not merged — the delta's ${which} differ(s) from the living ${drift.file}, which keeps its own`);
+}
+//# sourceMappingURL=verdict-lines.js.map

package/dist/commands/archive/plan/contracts/verdict-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-lines.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/verdict-lines.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The plan lines a contract merge's verdicts print — the quote, the stale\n * baseline, the overwrite and the `info` the merge does not carry — spelled\n * once for both planners\n * (./openapi.ts, ./asyncapi.ts), which used to print them in fourteen parallel\n * loops. Every surface reaches the reader by exactly the same sentence an\n * operation or a slot does, because it is graded by exactly the same verdict;\n * one spelling is what keeps the two axes from describing one verdict in two\n * sentences. The label prefix (`path-level …`, `component …`, `components.…`)\n * stays at the call site: it is the one part that differs.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { withoutFeatureKeysDeep } from \"../../../../core/openapi/digest.js\";\nimport { isRecord } from \"../../../../core/kernel/records.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { IssueCode } from \"../../../../core/vocabulary/issue.js\";\nimport type { Plan } from \"../state.js\";\n\ntype Say = (line?: string) => void;\n\n/**\n * Said out loud, because \"the plan wrote less than my delta spells\" is the one\n * thing a reader cannot infer from a merged file. Not a warning: quoting the\n * contract around your change is correct authoring, and leaving the quote\n * alone is the correct merge. The path-level and component quotes get the\n * same sentence for the same reason.\n */\nexport function sayQuoted(say: Say, labels: readonly string[]): void {\n  for (const label of labels) say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);\n}\n\n/**\n * Stale surfaces reaching the merge at all means --approve pushed past the\n * gate's `openapi.baseline-stale` / `asyncapi.baseline-stale` — the plan still\n * names what it cost.\n */\nexport function sayStale(say: Say, labels: readonly string[]): void {\n  for (const label of labels) {\n    say(`      ⚠ stale baseline on ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n  }\n}\n\n/** One overwrite the plan warns about. The code is spelled literally at each call site. */\nexport interface Overwrite {\n  svc: string;\n  code: IssueCode;\n  /** What the printed line names: the label with its prefix. */\n  label: string;\n  /** The warning's sentence, before any consumer clause. */\n  message: string;\n  /** Who the overwrite lands on (./consumers.ts), or absent where nothing can name it. */\n  named?: { clause: string; details: string[] } | null;\n}\n\n/**\n * Warn about one overwrite and print it. The consumer clause, when there is\n * one, ends both the warning's message and the printed line, and its evidence\n * rides as the warning's `details` and as indented lines under it.\n */\nexport function warnOverwrite(plan: Pick<Plan, \"planWarns\">, say: Say, overwrite: Overwrite): void {\n  const named = overwrite.named ?? null;\n  const clause = named === null ? \"\" : `; ${named.clause}`;\n  plan.planWarns.push({\n    severity: \"warn\",\n    code: overwrite.code,\n    subject: overwrite.svc,\n    message: overwrite.message + clause,\n    ...(named === null ? {} : { details: named.details }),\n  });\n  say(`      ⚠ overwrites ${overwrite.label} — the living definition differs${clause}`);\n  for (const line of named?.details ?? []) say(`          ${line}`);\n}\n\n/**\n * The `info` keys a feature's contract spells differently from the living one,\n * as `info.<key>` labels, sorted — empty when the delta writes no `info`, or\n * writes exactly what living has.\n *\n * Neither merge carries `info` (nor any root key outside the sections it\n * merges: `../../../../core/asyncapi/merge/markers.ts` names what those are),\n * and that is a decision rather than a gap — a delta is a diff of operations\n * and slots, and its `info` is most often the scaffold's or a copy. But a\n * delta that DID move it — a new version, a rewritten description — lost the\n * change with exit 0 and nothing in the plan, so the reader learned it from\n * the living file weeks later. Only keys the delta declares are compared: a\n * key living has and the delta leaves out is a key nobody asked to change.\n * Feature bookkeeping is never compared: an `x-loam-*` key of `info` itself is\n * skipped, and the merges' own markers are stripped from the values below it\n * (`withoutFeatureKeysDeep`), so a pin can never read as drift.\n */\nexport function infoDrift(livingPlain: unknown, featurePlain: unknown): string[] {\n  const feature = isRecord(featurePlain) ? featurePlain.info : undefined;\n  if (!isRecord(feature)) return [];\n  const living = isRecord(livingPlain) && isRecord(livingPlain.info) ? livingPlain.info : {};\n  return Object.keys(feature)\n    .filter((key) => !key.startsWith(\"x-loam-\"))\n    .filter((key) => !isDeepStrictEqual(withoutFeatureKeysDeep(feature[key]), living[key]))\n    .map((key) => `info.${key}`)\n    .sort(compareIds);\n}\n\n/** Which contract the drift is about, the code it is reported under, and what the merge carries instead. */\nexport interface InfoDrift {\n  svc: string;\n  code: IssueCode;\n  /** `openapi.yaml` or `asyncapi.yaml` — the living file the author edits instead. */\n  file: string;\n  /** What the merge DOES carry, in the words the warning prints. */\n  carries: string;\n  labels: readonly string[];\n}\n\n/**\n * Warn about one contract's `info` drift and print it. A warning, not a gate:\n * keeping the living `info` is the merge working as designed, and the remedy —\n * edit the living file in the same change — is the author's call. What must\n * not happen is the silence.\n */\nexport function warnInfoDrift(plan: Pick<Plan, \"planWarns\">, say: Say, drift: InfoDrift): void {\n  if (drift.labels.length === 0) return;\n  const which = drift.labels.join(\", \");\n  plan.planWarns.push({\n    severity: \"warn\",\n    code: drift.code,\n    subject: drift.svc,\n    message:\n      `${drift.svc}: the delta's ${which} differ(s) from the living ${drift.file} — the merge carries ${drift.carries} and never ` +\n      `info, so the living contract keeps its own. If it should move, edit the living ${drift.file} in this change.`,\n  });\n  say(`      ⚠ info not merged — the delta's ${which} differ(s) from the living ${drift.file}, which keeps its own`);\n}\n"]}

package/dist/commands/archive/plan/document/head.js

@@ -0,0 +1,151 @@
+/**
+ * What a living document that `loam archive` CREATES says above
+ * `## Requirements` — the part of a new service spec, architecture spec or
+ * capability document that the requirement algebra has nothing to say about.
+ *
+ * THE DEFECT THIS CLOSES. A created document used to be a fixed header —
+ * `service`, `status: draft`, `# <id>` — and the requirements. Everything else
+ * the delta said was dropped in silence: its title, the narrative a reader
+ * needs before the first requirement, the frontmatter `owner`, any section
+ * written after the last delta section. The requirements arrived byte for byte
+ * and the document arrived unreadable to anyone who had not read the delta.
+ *
+ * WHY NOT CARRY THE WHOLE PREAMBLE. "loam merges requirements, never prose"
+ * (SCHEMA) is not an aversion to prose; it is the observation that a delta's
+ * prose is ABOUT THE CHANGE. The scaffold's own H1 is "<svc> — requirement
+ * delta for <FEAT>" and its intro tells the reviewer what a delta is; carrying
+ * either into the living document would make it describe a pull request that
+ * merged months ago. A machine cannot tell narrative about the service from
+ * narrative about the change, so loam carries only what the author MARKED as
+ * the document's own, and says where the rest is:
+ *
+ * - `owner` from the delta's frontmatter — the one field that describes the
+ *   service rather than the change or a vouch (copying `vouched_by` or a digest
+ *   would forge a review nobody performed). A capability document carries no
+ *   frontmatter by decision (`planCapabilities` says why), so it gets none.
+ * - the delta's H1, unless it is about the change — it names the feature or
+ *   calls itself a delta, which is exactly what the scaffold writes.
+ * - the delta's `## Purpose` section, verbatim — the explicit marker, and the
+ *   one OpenSpec's living specs already use for the document's own narrative.
+ * - a back-link to the archived delta, always, so nothing the merge left behind
+ *   is unreachable from the document it created.
+ *
+ * Only on CREATION. A living document that already exists keeps its own
+ * narrative, edited in place; a `## Purpose` in a delta against it merges as
+ * nothing, and `planSpecs` says so rather than letting it vanish.
+ */
+import { dirname, relative, sep } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { parseFrontmatter, stringField } from "../../../../core/document/frontmatter.js";
+import { serializeRequirements } from "../../../../core/document/spec.js";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { fenceTracker } from "../../../../core/kernel/fences.js";
+/** A level-1 heading line. */
+const H1_RE = /^#\s+(.+?)\s*$/;
+/** The marked section — matched on the whole trimmed line, case-insensitively, like `## Requirements`. */
+const PURPOSE_RE = /^##\s+Purpose\s*$/i;
+/** Where a section ends: the next H1 or H2. Deeper headings are the section's own. */
+const SECTION_END_RE = /^#{1,2}\s/;
+/**
+ * The created document's whole text, and the one line that tells the person
+ * reading the plan what came across from the delta and where the rest is.
+ */
+export function createdDocument(request) {
+    const archived = request.retarget(request.deltaPath);
+    // Percent-escaped spaces, as `rebaseLinks` writes a route it computed: a bare
+    // space would end the link target at the first word.
+    const backLink = relative(dirname(request.livingPath), archived).split(sep).join("/").split(" ").join("%20");
+    const head = createdHead({ ...request, backLink });
+    const where = repoPath(request.docsDir, archived);
+    const note = head.carried.length > 0
+        ? `carried from the delta: ${head.carried.join(", ")} — the rest of its prose stays in ${where}, linked from the new document`
+        : `the delta's prose stays in ${where}, linked from the new document — mark what belongs here '## Purpose' and archive carries it`;
+    return { text: `${head.text}## Requirements\n\n${serializeRequirements(request.requirements)}`, note };
+}
+/** The head of a document archive creates — see the module comment for what goes in it and why. */
+function createdHead(request) {
+    const fm = parseFrontmatter(request.delta);
+    const marked = markedParts(fm.body, request.featureId);
+    const owner = request.service === null ? undefined : stringField(fm, "owner");
+    const carried = [];
+    let text = "";
+    if (request.service !== null) {
+        const fields = {
+            service: request.service,
+            status: "draft",
+            ...(request.adoption === undefined ? {} : { adoption: request.adoption }),
+            ...(owner === undefined ? {} : { owner }),
+        };
+        text += `---\n${stringifyYaml(fields, { lineWidth: 0 })}---\n\n`;
+        if (owner !== undefined)
+            carried.push("owner");
+    }
+    text += `# ${marked.title ?? request.fallbackTitle}\n\n`;
+    if (marked.title !== undefined)
+        carried.push("its title");
+    text += `Created when ${request.featureId} was archived; [its delta](${request.backLink}) keeps the prose written for that change.\n\n`;
+    if (marked.purpose !== undefined) {
+        text += `## Purpose\n\n${marked.purpose}\n\n`;
+        carried.push("its ## Purpose");
+    }
+    return { text, carried };
+}
+/** Does the delta carry a `## Purpose` section at all — the question a merge into an EXISTING document asks. */
+export function hasPurpose(delta) {
+    return markedParts(parseFrontmatter(delta).body, "").purpose !== undefined;
+}
+/**
+ * Is this H1 the CHANGE's title rather than the document's? Two mechanical
+ * signals, both in words loam owns: it names the feature, or it calls itself a
+ * delta — which no living document does, and which every delta title loam
+ * scaffolds does both of ("<svc> — requirement delta for <FEAT>"). Anything
+ * else is a title an author chose for the thing itself, the shape a domain
+ * written into a feature in one go arrives in.
+ */
+function namesTheChange(title, featureId) {
+    const lower = title.toLowerCase();
+    return (featureId !== "" && lower.includes(featureId.toLowerCase())) || /\bdelta\b/.test(lower);
+}
+/**
+ * The delta's title and `## Purpose` body, each only when the author wrote one
+ * that belongs to the living document. Fence-aware, like every heading walk in
+ * loam: a heading inside a fenced block is quoted text, and a fenced block
+ * inside the Purpose is part of it.
+ */
+function markedParts(body, featureId) {
+    const fenced = fenceTracker();
+    let title;
+    let seenSection = false;
+    let purpose = null;
+    let purposeEnded = false;
+    for (const line of body.split(/\r?\n/)) {
+        const quoted = fenced(line);
+        if (purpose !== null && !purposeEnded) {
+            if (quoted || !SECTION_END_RE.test(line)) {
+                purpose.push(line);
+                continue;
+            }
+            purposeEnded = true;
+        }
+        if (quoted)
+            continue;
+        const h1 = H1_RE.exec(line);
+        // The document's title is an H1 above its first section; one further down
+        // is a heading inside the text, not the name of the document.
+        if (h1 !== null && !seenSection && title === undefined)
+            title = h1[1];
+        if (/^##\s/.test(line)) {
+            seenSection = true;
+            if (purpose === null && PURPOSE_RE.test(line.trim()))
+                purpose = [];
+        }
+    }
+    // Blank LINES trimmed, never leading spaces: an indented code block opening
+    // the section is the author's text.
+    const purposeText = purpose?.join("\n").replace(/^(?:[ \t]*\n)+/, "").trimEnd();
+    return {
+        ...(title === undefined || namesTheChange(title, featureId) ? {} : { title }),
+        ...(purposeText === undefined || purposeText === "" ? {} : { purpose: purposeText }),
+    };
+}
+//# sourceMappingURL=head.js.map

package/dist/commands/archive/plan/document/head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/document/head.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a living document that `loam archive` CREATES says above\n * `## Requirements` — the part of a new service spec, architecture spec or\n * capability document that the requirement algebra has nothing to say about.\n *\n * THE DEFECT THIS CLOSES. A created document used to be a fixed header —\n * `service`, `status: draft`, `# <id>` — and the requirements. Everything else\n * the delta said was dropped in silence: its title, the narrative a reader\n * needs before the first requirement, the frontmatter `owner`, any section\n * written after the last delta section. The requirements arrived byte for byte\n * and the document arrived unreadable to anyone who had not read the delta.\n *\n * WHY NOT CARRY THE WHOLE PREAMBLE. \"loam merges requirements, never prose\"\n * (SCHEMA) is not an aversion to prose; it is the observation that a delta's\n * prose is ABOUT THE CHANGE. The scaffold's own H1 is \"<svc> — requirement\n * delta for <FEAT>\" and its intro tells the reviewer what a delta is; carrying\n * either into the living document would make it describe a pull request that\n * merged months ago. A machine cannot tell narrative about the service from\n * narrative about the change, so loam carries only what the author MARKED as\n * the document's own, and says where the rest is:\n *\n * - `owner` from the delta's frontmatter — the one field that describes the\n *   service rather than the change or a vouch (copying `vouched_by` or a digest\n *   would forge a review nobody performed). A capability document carries no\n *   frontmatter by decision (`planCapabilities` says why), so it gets none.\n * - the delta's H1, unless it is about the change — it names the feature or\n *   calls itself a delta, which is exactly what the scaffold writes.\n * - the delta's `## Purpose` section, verbatim — the explicit marker, and the\n *   one OpenSpec's living specs already use for the document's own narrative.\n * - a back-link to the archived delta, always, so nothing the merge left behind\n *   is unreachable from the document it created.\n *\n * Only on CREATION. A living document that already exists keeps its own\n * narrative, edited in place; a `## Purpose` in a delta against it merges as\n * nothing, and `planSpecs` says so rather than letting it vanish.\n */\nimport { dirname, relative, sep } from \"node:path\";\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { parseFrontmatter, stringField } from \"../../../../core/document/frontmatter.js\";\nimport { serializeRequirements, type Requirement } from \"../../../../core/document/spec.js\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { fenceTracker } from \"../../../../core/kernel/fences.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Retarget } from \"./links.js\";\n\n/** A level-1 heading line. */\nconst H1_RE = /^#\\s+(.+?)\\s*$/;\n/** The marked section — matched on the whole trimmed line, case-insensitively, like `## Requirements`. */\nconst PURPOSE_RE = /^##\\s+Purpose\\s*$/i;\n/** Where a section ends: the next H1 or H2. Deeper headings are the section's own. */\nconst SECTION_END_RE = /^#{1,2}\\s/;\n\n/** One living document this archive creates, and the delta it is created from. */\nexport interface CreatedRequest {\n  docsDir: DocsDir;\n  featureId: string;\n  /** The delta's path, where it sits BEFORE the archive moves the feature. */\n  deltaPath: string;\n  /** The delta's text, its links already re-expressed for `livingPath`'s directory. */\n  delta: string;\n  livingPath: string;\n  /** Where each feature file will be after the archive — the back-link's target comes from it. */\n  retarget: Retarget;\n  /** The heading written when the delta carries no title of its own. */\n  fallbackTitle: string;\n  /** The `service:` the created frontmatter names; null for a document that carries no frontmatter. */\n  service: string | null;\n  /**\n   * `partial` when the document is a service's FIRST spec.md and the service\n   * existed before this feature — so what lands is the feature's slice and\n   * not the service. Written to the frontmatter as `adoption: partial`\n   * (SCHEMA.md), which the maturity ladder and `loam status` read as \"not\n   * adopted yet\" until a person deletes the line.\n   */\n  adoption?: \"partial\";\n  requirements: Requirement[];\n}\n\n/**\n * The created document's whole text, and the one line that tells the person\n * reading the plan what came across from the delta and where the rest is.\n */\nexport function createdDocument(request: CreatedRequest): { text: string; note: string } {\n  const archived = request.retarget(request.deltaPath);\n  // Percent-escaped spaces, as `rebaseLinks` writes a route it computed: a bare\n  // space would end the link target at the first word.\n  const backLink = relative(dirname(request.livingPath), archived).split(sep).join(\"/\").split(\" \").join(\"%20\");\n  const head = createdHead({ ...request, backLink });\n  const where = repoPath(request.docsDir, archived);\n  const note =\n    head.carried.length > 0\n      ? `carried from the delta: ${head.carried.join(\", \")} — the rest of its prose stays in ${where}, linked from the new document`\n      : `the delta's prose stays in ${where}, linked from the new document — mark what belongs here '## Purpose' and archive carries it`;\n  return { text: `${head.text}## Requirements\\n\\n${serializeRequirements(request.requirements)}`, note };\n}\n\ninterface HeadRequest {\n  delta: string;\n  featureId: string;\n  fallbackTitle: string;\n  service: string | null;\n  adoption?: \"partial\";\n  /** The created document's relative link to the archived delta. */\n  backLink: string;\n}\n\ninterface CreatedHead {\n  /** Everything above `## Requirements`, ending in a blank line. */\n  text: string;\n  /** What the delta contributed, in the words the per-file note prints. */\n  carried: string[];\n}\n\n/** The head of a document archive creates — see the module comment for what goes in it and why. */\nfunction createdHead(request: HeadRequest): CreatedHead {\n  const fm = parseFrontmatter(request.delta);\n  const marked = markedParts(fm.body, request.featureId);\n  const owner = request.service === null ? undefined : stringField(fm, \"owner\");\n  const carried: string[] = [];\n  let text = \"\";\n  if (request.service !== null) {\n    const fields = {\n      service: request.service,\n      status: \"draft\",\n      ...(request.adoption === undefined ? {} : { adoption: request.adoption }),\n      ...(owner === undefined ? {} : { owner }),\n    };\n    text += `---\\n${stringifyYaml(fields, { lineWidth: 0 })}---\\n\\n`;\n    if (owner !== undefined) carried.push(\"owner\");\n  }\n  text += `# ${marked.title ?? request.fallbackTitle}\\n\\n`;\n  if (marked.title !== undefined) carried.push(\"its title\");\n  text += `Created when ${request.featureId} was archived; [its delta](${request.backLink}) keeps the prose written for that change.\\n\\n`;\n  if (marked.purpose !== undefined) {\n    text += `## Purpose\\n\\n${marked.purpose}\\n\\n`;\n    carried.push(\"its ## Purpose\");\n  }\n  return { text, carried };\n}\n\n/** Does the delta carry a `## Purpose` section at all — the question a merge into an EXISTING document asks. */\nexport function hasPurpose(delta: string): boolean {\n  return markedParts(parseFrontmatter(delta).body, \"\").purpose !== undefined;\n}\n\n/**\n * Is this H1 the CHANGE's title rather than the document's? Two mechanical\n * signals, both in words loam owns: it names the feature, or it calls itself a\n * delta — which no living document does, and which every delta title loam\n * scaffolds does both of (\"<svc> — requirement delta for <FEAT>\"). Anything\n * else is a title an author chose for the thing itself, the shape a domain\n * written into a feature in one go arrives in.\n */\nfunction namesTheChange(title: string, featureId: string): boolean {\n  const lower = title.toLowerCase();\n  return (featureId !== \"\" && lower.includes(featureId.toLowerCase())) || /\\bdelta\\b/.test(lower);\n}\n\n/**\n * The delta's title and `## Purpose` body, each only when the author wrote one\n * that belongs to the living document. Fence-aware, like every heading walk in\n * loam: a heading inside a fenced block is quoted text, and a fenced block\n * inside the Purpose is part of it.\n */\nfunction markedParts(body: string, featureId: string): { title?: string; purpose?: string } {\n  const fenced = fenceTracker();\n  let title: string | undefined;\n  let seenSection = false;\n  let purpose: string[] | null = null;\n  let purposeEnded = false;\n  for (const line of body.split(/\\r?\\n/)) {\n    const quoted = fenced(line);\n    if (purpose !== null && !purposeEnded) {\n      if (quoted || !SECTION_END_RE.test(line)) {\n        purpose.push(line);\n        continue;\n      }\n      purposeEnded = true;\n    }\n    if (quoted) continue;\n    const h1 = H1_RE.exec(line);\n    // The document's title is an H1 above its first section; one further down\n    // is a heading inside the text, not the name of the document.\n    if (h1 !== null && !seenSection && title === undefined) title = h1[1]!;\n    if (/^##\\s/.test(line)) {\n      seenSection = true;\n      if (purpose === null && PURPOSE_RE.test(line.trim())) purpose = [];\n    }\n  }\n  // Blank LINES trimmed, never leading spaces: an indented code block opening\n  // the section is the author's text.\n  const purposeText = purpose?.join(\"\\n\").replace(/^(?:[ \\t]*\\n)+/, \"\").trimEnd();\n  return {\n    ...(title === undefined || namesTheChange(title, featureId) ? {} : { title }),\n    ...(purposeText === undefined || purposeText === \"\" ? {} : { purpose: purposeText }),\n  };\n}\n"]}