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

package/dist/core/coherence/living.js

@@ -0,0 +1,198 @@
+/**
+ * What the merge would do to the LIVING documents.
+ *
+ * The refusals `loam archive` makes about the world a feature is about to be
+ * merged INTO — as opposed to the feature's own three axes agreeing, which is
+ * coherence.ts's question: a per-service delta addressed to a service that
+ * exists nowhere, a `specs/<svc>/` directory whose NAME could never be a
+ * service id, and git conflict markers in a living document the merge would
+ * rewrite. `validate` and `status` read the same functions, so the gates
+ * cannot drift into disagreeing about what they refuse.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { loadFile } from "../c4/likec4.js";
+import { elementService } from "../c4/resolve/service.js";
+import { closeIds } from "../c4/arch.js";
+import { serviceIdProblem } from "../kernel/ids/service.js";
+import { repoPath } from "../envelope/json.js";
+import { featurePaths, landscapePath, SPEC_AXES } from "../repo/paths.js";
+import { livingCapabilityPaths } from "../repo/authored/paths.js";
+import { docsRepoState } from "../repo/state.js";
+import { featureSpecServices, listServices } from "../repo/repo.js";
+import { enumeratedServices, locateServicePaths } from "../repo/service-target.js";
+import { documentConflictFinding, landscapeConflictFinding } from "../conflict-markers.js";
+/* ------------------------------------------------------------------ */
+/* What the merge would do to the LIVING documents                     */
+/* ------------------------------------------------------------------ */
+/**
+ * Per-service deltas addressed to a service that exists nowhere: no
+ * `services/<svc>/`, and nothing in this feature's own tagged delta introducing
+ * one.
+ *
+ * `validate` grades this (`delta.service-unknown`); `archive` is where it costs
+ * something, because `specs/<svc>/` is what the merge MATERIALISES
+ * `services/<svc>/` from — one wrong character in `--touches` and the fleet
+ * acquires a living service nobody meant to adopt, under a banner saying the
+ * living docs are complete. Both gates read this function so they cannot drift
+ * into disagreeing about which service ids are real; the `code:` literal lives
+ * here, once, where the drift collector sees it.
+ *
+ * A delta that did not parse proves nothing either way — whether it introduces
+ * the service is exactly what nobody can read — so the question is suspended
+ * there rather than answered by guessing. `delta.invalid` is that file's
+ * finding, and coherence already makes it.
+ *
+ * `services/<svc>/` is asked for directly rather than through the enumeration:
+ * a feature may be graded in a docs repo with no `services/` at all (repo.ts
+ * takes the same position), where enumerating is a refusal, not an answer.
+ */
+export async function unknownDeltaServices(docsDir, featureDir, featureId, loaded = {}) {
+    const { preloadedDelta, context } = loaded;
+    const deltaPath = featurePaths(featureDir).delta;
+    let delta;
+    if (existsSync(deltaPath)) {
+        delta = preloadedDelta ?? (context === undefined ? await loadFile(deltaPath) : await context.loadLikeC4(deltaPath));
+    }
+    if (delta !== undefined && delta.errors.length > 0)
+        return [];
+    const introduces = new Set((delta?.elements ?? []).filter((e) => e.tags.includes(featureId)).map(elementService));
+    // Enumeration MEMBERSHIP, not an existsSync of services/<svc>/ at the root:
+    // a service filed into a subsystem exists wherever the tree walk found it,
+    // and the root probe would grade it unknown. `enumeratedServices` swallows
+    // an unenumerable services/ to [] on purpose — this also runs under archive
+    // in repos validate --feature tolerates (no services/ at all), where every
+    // probe would have found nothing there anyway.
+    const known = new Set((await enumeratedServices(docsDir, context)).map((s) => s.id));
+    const unknown = (await featureSpecServices(featureDir, context)).filter((svc) => !known.has(svc) && !introduces.has(svc));
+    if (unknown.length === 0)
+        return [];
+    // The near-miss hint, on the same rule `service.unknown` uses — a typo is
+    // only diagnosable against the ids that DO exist.
+    const closeTo = docsRepoState(docsDir).kind === "ok" ? (await listServices(docsDir, context)).map((s) => s.id) : [];
+    return unknown.map((svc) => deltaServiceUnknownFinding(svc, closeTo));
+}
+/**
+ * The finding itself, for the two gates that reach this conclusion by different
+ * routes.
+ *
+ * `archive` gets there through `unknownDeltaServices` above; `validate` gets
+ * there through its own enumeration, because it suspends the question on an
+ * unreadable delta rather than returning early on it, and that difference is
+ * deliberate. What must NOT differ is the sentence: the two were spelled out
+ * word for word in two files, so a reworded hint in one of them would have made
+ * `loam validate` and `loam archive` describe the same typo differently, on the
+ * same code, in the same repo.
+ *
+ * `knownIds` is the fleet's real service ids — already enumerated by the caller,
+ * which is also the caller's chance to skip the enumeration entirely when there
+ * is nothing to diagnose.
+ */
+export function deltaServiceUnknownFinding(svc, knownIds) {
+    const close = closeIds(svc, knownIds);
+    return {
+        severity: "error",
+        code: "delta.service-unknown",
+        subject: svc,
+        message: `specs/${svc}/ addresses a service that does not exist: there is no services/${svc}/ and this feature's ` +
+            `delta.likec4 does not introduce one — archiving would create it out of the typo.` +
+            (close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : " `loam list services` shows what exists."),
+    };
+}
+/**
+ * Per-service deltas whose DIRECTORY NAME is not a legal service id at all.
+ *
+ * `specs/<svc>/` is caller-controlled path input exactly as `--service` is:
+ * `featureSpecServices` returns whatever `readdir` found, and nothing between
+ * that readdir and the archive merge ever asked the id grammar about it. So
+ * `specs/Payment Service/` validated green — "requirements covered", even,
+ * because a tagged element whose TITLE matched the directory counted as
+ * introducing the service — and `loam archive` then materialised
+ * `services/Payment Service/`: a directory `service.id-invalid` calls an error
+ * on the very next `validate --all`, and one no loam command can address or
+ * re-create. Both gates read this function for `unknownDeltaServices`' reason:
+ * validate and archive must refuse the same directory with the same sentence.
+ *
+ * NOT suppressed by what the delta introduces, and NOT suspended on
+ * `delta.invalid`: the name is illegal whatever the architecture axis says,
+ * because the name itself is what becomes the path.
+ */
+export async function invalidSpecServiceFindings(featureDir, context) {
+    const out = [];
+    for (const svc of await featureSpecServices(featureDir, context)) {
+        const problem = serviceIdProblem(svc, "specs/ directory name");
+        if (problem === null)
+            continue;
+        out.push({
+            severity: "error",
+            code: "delta.service-id-invalid",
+            subject: svc,
+            message: `specs/${svc}/ — ${problem} ` +
+                `\`loam archive\` materialises services/${svc}/ from this directory name, and that directory is one ` +
+                `no loam command can address afterwards (\`service.id-invalid\`). Rename the specs/ directory to a legal id.`,
+        });
+    }
+    return out;
+}
+/**
+ * Git conflict markers in the LIVING documents a merge of this feature would
+ * rewrite: each touched service's requirement files, and the fleet map.
+ *
+ * The rule and the sentence are conflict-markers's — one spelling of the breach,
+ * wherever it is found. What this adds is the SET: the documents `archive`
+ * rewrites. A conflicted `services/<svc>/spec.md` parses as prose, so every
+ * check upstream of the merge reads it as a valid document with some odd
+ * headings in it; the rewrite then drops whichever marker lines fall inside the
+ * requirements run it owns, and a conflict anyone could see becomes a file
+ * nobody can tell is wrong. For a shared docs repo that a fleet lands in
+ * through PRs, that is the default failure and not an edge.
+ *
+ * `openapi.yaml` is deliberately absent: markers make it unparseable, so the
+ * YAML reader already refuses it by name and a second finding would only say
+ * the same thing later.
+ *
+ * `capabilities` is the same question on the business corpus, and it is not
+ * optional politeness: a living `capabilities/<id>/spec.md` the feature's
+ * capability delta merges into is rewritten by exactly the same
+ * `rewriteRequirementsRun`, so a conflicted one loses its marker lines exactly
+ * the same way. Passed in rather than walked here because the caller has
+ * already read the feature's delta tree and this function must not decide which
+ * documents a merge touches.
+ *
+ * IDS, not the `CapabilityDoc` records the caller holds, and that is a guard
+ * rather than a preference: a `CapabilityDoc` from a feature's delta walk
+ * carries `spec` and `dir` pointing at the FEATURE'S copy, and the document
+ * this function is about is the LIVING one. Taking the whole record would leave
+ * `doc.spec` in scope here — the wrong file, one property access away.
+ */
+export async function livingMergeConflicts(docsDir, services, capabilities, context) {
+    const out = [];
+    const read = async (path) => context === undefined ? readFile(path, "utf8") : context.readText(path);
+    for (const svc of services) {
+        const paths = await locateServicePaths(docsDir, svc, context);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            const finding = documentConflictFinding(repoPath(docsDir, path), svc, await read(path));
+            if (finding !== null)
+                out.push(finding);
+        }
+    }
+    for (const id of capabilities) {
+        const path = livingCapabilityPaths(docsDir, id).spec;
+        if (!existsSync(path))
+            continue;
+        const finding = documentConflictFinding(repoPath(docsDir, path), id, await read(path));
+        if (finding !== null)
+            out.push(finding);
+    }
+    const landscape = landscapePath(docsDir);
+    if (existsSync(landscape)) {
+        const finding = landscapeConflictFinding(repoPath(docsDir, landscape), await read(landscape));
+        if (finding !== null)
+            out.push(finding);
+    }
+    return out;
+}
+//# sourceMappingURL=living.js.map

package/dist/core/coherence/living.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"living.js","sourceRoot":"","sources":["../../../src/core/coherence/living.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAkB,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAwB,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAI3F,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAgB,EAChB,UAAsB,EACtB,SAAiB,EACjB,MAAM,GAA2D,EAAE;IAEnE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC3C,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC;IACjD,IAAI,KAA4B,CAAC;IACjC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,KAAK,GAAG,cAAc,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACtH,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9D,MAAM,UAAU,GAAwB,IAAI,GAAG,CAC7C,CAAC,KAAK,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CACtF,CAAC;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,+CAA+C;IAC/C,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1G,MAAM,OAAO,GAAG,CAAC,MAAM,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CACrE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CACjD,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,0EAA0E;IAC1E,kDAAkD;IAClD,MAAM,OAAO,GACX,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtG,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,0BAA0B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW,EAAE,QAAkB;IACxE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,GAAG;QACZ,OAAO,EACL,SAAS,GAAG,mEAAmE,GAAG,uBAAuB;YACzG,kFAAkF;YAClF,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,0CAA0C,CAAC;KAC1G,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,UAAsB,EACtB,OAAsB;IAEtB,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,MAAM,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;QACjE,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;QAC/D,IAAI,OAAO,KAAK,IAAI;YAAE,SAAS;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,0BAA0B;YAChC,OAAO,EAAE,GAAG;YACZ,OAAO,EACL,SAAS,GAAG,OAAO,OAAO,GAAG;gBAC7B,0CAA0C,GAAG,wDAAwD;gBACrG,6GAA6G;SAChH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAgB,EAChB,QAAoC,EACpC,YAA+B,EAC/B,OAAsB;IAEtB,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,KAAK,EAAE,IAAY,EAAmB,EAAE,CACnD,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE1E,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,SAAS;YAChC,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YACxF,IAAI,OAAO,KAAK,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC;QACrD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACvF,IAAI,OAAO,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,wBAAwB,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC9F,IAAI,OAAO,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * What the merge would do to the LIVING documents.\n *\n * The refusals `loam archive` makes about the world a feature is about to be\n * merged INTO — as opposed to the feature's own three axes agreeing, which is\n * coherence.ts's question: a per-service delta addressed to a service that\n * exists nowhere, a `specs/<svc>/` directory whose NAME could never be a\n * service id, and git conflict markers in a living document the merge would\n * rewrite. `validate` and `status` read the same functions, so the gates\n * cannot drift into disagreeing about what they refuse.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { loadFile, type LoadedDoc } from \"../c4/likec4.js\";\nimport { elementService } from \"../c4/resolve/service.js\";\nimport { closeIds } from \"../c4/arch.js\";\nimport { serviceIdProblem, type PathableService } from \"../kernel/ids/service.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { featurePaths, landscapePath, SPEC_AXES } from \"../repo/paths.js\";\nimport { livingCapabilityPaths } from \"../repo/authored/paths.js\";\nimport { docsRepoState } from \"../repo/state.js\";\nimport { featureSpecServices, listServices } from \"../repo/repo.js\";\nimport { enumeratedServices, locateServicePaths } from \"../repo/service-target.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { documentConflictFinding, landscapeConflictFinding } from \"../conflict-markers.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\n\n\n/* ------------------------------------------------------------------ */\n/* What the merge would do to the LIVING documents                     */\n/* ------------------------------------------------------------------ */\n\n/**\n * Per-service deltas addressed to a service that exists nowhere: no\n * `services/<svc>/`, and nothing in this feature's own tagged delta introducing\n * one.\n *\n * `validate` grades this (`delta.service-unknown`); `archive` is where it costs\n * something, because `specs/<svc>/` is what the merge MATERIALISES\n * `services/<svc>/` from — one wrong character in `--touches` and the fleet\n * acquires a living service nobody meant to adopt, under a banner saying the\n * living docs are complete. Both gates read this function so they cannot drift\n * into disagreeing about which service ids are real; the `code:` literal lives\n * here, once, where the drift collector sees it.\n *\n * A delta that did not parse proves nothing either way — whether it introduces\n * the service is exactly what nobody can read — so the question is suspended\n * there rather than answered by guessing. `delta.invalid` is that file's\n * finding, and coherence already makes it.\n *\n * `services/<svc>/` is asked for directly rather than through the enumeration:\n * a feature may be graded in a docs repo with no `services/` at all (repo.ts\n * takes the same position), where enumerating is a refusal, not an answer.\n */\nexport async function unknownDeltaServices(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  loaded: { preloadedDelta?: LoadedDoc; context?: FleetContext } = {},\n): Promise<Finding[]> {\n  const { preloadedDelta, context } = loaded;\n  const deltaPath = featurePaths(featureDir).delta;\n  let delta: LoadedDoc | undefined;\n  if (existsSync(deltaPath)) {\n    delta = preloadedDelta ?? (context === undefined ? await loadFile(deltaPath) : await context.loadLikeC4(deltaPath));\n  }\n  if (delta !== undefined && delta.errors.length > 0) return [];\n\n  const introduces: ReadonlySet<string> = new Set(\n    (delta?.elements ?? []).filter((e) => e.tags.includes(featureId)).map(elementService),\n  );\n  // Enumeration MEMBERSHIP, not an existsSync of services/<svc>/ at the root:\n  // a service filed into a subsystem exists wherever the tree walk found it,\n  // and the root probe would grade it unknown. `enumeratedServices` swallows\n  // an unenumerable services/ to [] on purpose — this also runs under archive\n  // in repos validate --feature tolerates (no services/ at all), where every\n  // probe would have found nothing there anyway.\n  const known: ReadonlySet<string> = new Set((await enumeratedServices(docsDir, context)).map((s) => s.id));\n  const unknown = (await featureSpecServices(featureDir, context)).filter(\n    (svc) => !known.has(svc) && !introduces.has(svc),\n  );\n  if (unknown.length === 0) return [];\n\n  // The near-miss hint, on the same rule `service.unknown` uses — a typo is\n  // only diagnosable against the ids that DO exist.\n  const closeTo =\n    docsRepoState(docsDir).kind === \"ok\" ? (await listServices(docsDir, context)).map((s) => s.id) : [];\n  return unknown.map((svc) => deltaServiceUnknownFinding(svc, closeTo));\n}\n\n/**\n * The finding itself, for the two gates that reach this conclusion by different\n * routes.\n *\n * `archive` gets there through `unknownDeltaServices` above; `validate` gets\n * there through its own enumeration, because it suspends the question on an\n * unreadable delta rather than returning early on it, and that difference is\n * deliberate. What must NOT differ is the sentence: the two were spelled out\n * word for word in two files, so a reworded hint in one of them would have made\n * `loam validate` and `loam archive` describe the same typo differently, on the\n * same code, in the same repo.\n *\n * `knownIds` is the fleet's real service ids — already enumerated by the caller,\n * which is also the caller's chance to skip the enumeration entirely when there\n * is nothing to diagnose.\n */\nexport function deltaServiceUnknownFinding(svc: string, knownIds: string[]): Finding {\n  const close = closeIds(svc, knownIds);\n  return {\n    severity: \"error\",\n    code: \"delta.service-unknown\",\n    subject: svc,\n    message:\n      `specs/${svc}/ addresses a service that does not exist: there is no services/${svc}/ and this feature's ` +\n      `delta.likec4 does not introduce one — archiving would create it out of the typo.` +\n      (close.length > 0 ? ` Did you mean: ${close.join(\", \")}?` : \" `loam list services` shows what exists.\"),\n  };\n}\n\n/**\n * Per-service deltas whose DIRECTORY NAME is not a legal service id at all.\n *\n * `specs/<svc>/` is caller-controlled path input exactly as `--service` is:\n * `featureSpecServices` returns whatever `readdir` found, and nothing between\n * that readdir and the archive merge ever asked the id grammar about it. So\n * `specs/Payment Service/` validated green — \"requirements covered\", even,\n * because a tagged element whose TITLE matched the directory counted as\n * introducing the service — and `loam archive` then materialised\n * `services/Payment Service/`: a directory `service.id-invalid` calls an error\n * on the very next `validate --all`, and one no loam command can address or\n * re-create. Both gates read this function for `unknownDeltaServices`' reason:\n * validate and archive must refuse the same directory with the same sentence.\n *\n * NOT suppressed by what the delta introduces, and NOT suspended on\n * `delta.invalid`: the name is illegal whatever the architecture axis says,\n * because the name itself is what becomes the path.\n */\nexport async function invalidSpecServiceFindings(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<Finding[]> {\n  const out: Finding[] = [];\n  for (const svc of await featureSpecServices(featureDir, context)) {\n    const problem = serviceIdProblem(svc, \"specs/ directory name\");\n    if (problem === null) continue;\n    out.push({\n      severity: \"error\",\n      code: \"delta.service-id-invalid\",\n      subject: svc,\n      message:\n        `specs/${svc}/ — ${problem} ` +\n        `\\`loam archive\\` materialises services/${svc}/ from this directory name, and that directory is one ` +\n        `no loam command can address afterwards (\\`service.id-invalid\\`). Rename the specs/ directory to a legal id.`,\n    });\n  }\n  return out;\n}\n\n/**\n * Git conflict markers in the LIVING documents a merge of this feature would\n * rewrite: each touched service's requirement files, and the fleet map.\n *\n * The rule and the sentence are conflict-markers's — one spelling of the breach,\n * wherever it is found. What this adds is the SET: the documents `archive`\n * rewrites. A conflicted `services/<svc>/spec.md` parses as prose, so every\n * check upstream of the merge reads it as a valid document with some odd\n * headings in it; the rewrite then drops whichever marker lines fall inside the\n * requirements run it owns, and a conflict anyone could see becomes a file\n * nobody can tell is wrong. For a shared docs repo that a fleet lands in\n * through PRs, that is the default failure and not an edge.\n *\n * `openapi.yaml` is deliberately absent: markers make it unparseable, so the\n * YAML reader already refuses it by name and a second finding would only say\n * the same thing later.\n *\n * `capabilities` is the same question on the business corpus, and it is not\n * optional politeness: a living `capabilities/<id>/spec.md` the feature's\n * capability delta merges into is rewritten by exactly the same\n * `rewriteRequirementsRun`, so a conflicted one loses its marker lines exactly\n * the same way. Passed in rather than walked here because the caller has\n * already read the feature's delta tree and this function must not decide which\n * documents a merge touches.\n *\n * IDS, not the `CapabilityDoc` records the caller holds, and that is a guard\n * rather than a preference: a `CapabilityDoc` from a feature's delta walk\n * carries `spec` and `dir` pointing at the FEATURE'S copy, and the document\n * this function is about is the LIVING one. Taking the whole record would leave\n * `doc.spec` in scope here — the wrong file, one property access away.\n */\nexport async function livingMergeConflicts(\n  docsDir: DocsDir,\n  services: readonly PathableService[],\n  capabilities: readonly string[],\n  context?: FleetContext,\n): Promise<Finding[]> {\n  const out: Finding[] = [];\n  const read = async (path: string): Promise<string> =>\n    context === undefined ? readFile(path, \"utf8\") : context.readText(path);\n\n  for (const svc of services) {\n    const paths = await locateServicePaths(docsDir, svc, context);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      const finding = documentConflictFinding(repoPath(docsDir, path), svc, await read(path));\n      if (finding !== null) out.push(finding);\n    }\n  }\n\n  for (const id of capabilities) {\n    const path = livingCapabilityPaths(docsDir, id).spec;\n    if (!existsSync(path)) continue;\n    const finding = documentConflictFinding(repoPath(docsDir, path), id, await read(path));\n    if (finding !== null) out.push(finding);\n  }\n\n  const landscape = landscapePath(docsDir);\n  if (existsSync(landscape)) {\n    const finding = landscapeConflictFinding(repoPath(docsDir, landscape), await read(landscape));\n    if (finding !== null) out.push(finding);\n  }\n  return out;\n}\n"]}

package/dist/core/coherence/lookups.js

@@ -0,0 +1,95 @@
+/**
+ * The questions the coherence checks ask lazily, each behind a per-service or
+ * per-repo cache.
+ *
+ * All but one reach outside the delta — into a living spec, a living
+ * contract, or another feature in flight — and the cross-feature scan is a
+ * walk of every active delta. The exception is `undeprecatedByFeature`, which
+ * reads the FEATURE's own openapi delta: it lives here anyway because it is the
+ * second half of the one question `deprecatedInLiving` opens — "is this op
+ * dying, and is this feature the resurrection?" — and splitting the pair across
+ * modules would leave each half's cache discipline unexplained by the other. A
+ * feature whose checks never need a lookup must not pay for it, which is why
+ * these are closures over a cache rather than arguments computed up front.
+ *
+ * The one question that used to live here and does not — who still CONSUMES an
+ * operation the feature takes out (`edgeConsumers`, `requirementConsumers`,
+ * `governorsAfterMerge`) — is the consumer index's now (`core/consumers/`),
+ * because `loam diff` and the archive planner ask it too and the three copies
+ * had drifted apart in which documents they read.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import {} from "../kernel/ids/service.js";
+import { featureSpecPaths } from "../repo/paths.js";
+import { operations } from "../openapi/doc.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { activeOpAdditions } from "./pending.js";
+import { parseRequirements } from "../document/parse.js";
+import {} from "../document/spec.js";
+import {} from "./declared.js";
+export function coherenceLookups(scope, context) {
+    const { docsDir, featureDir, featureId } = scope;
+    const livingReqs = new Map();
+    const livingRequirements = async (service) => {
+        let reqs = livingReqs.get(service);
+        if (reqs === undefined) {
+            const p = (await locateServicePaths(docsDir, service, context)).spec;
+            reqs = existsSync(p)
+                ? context === undefined
+                    ? parseRequirements(await readFile(p, "utf8"))
+                    : await context.readRequirements(p)
+                : [];
+            livingReqs.set(service, reqs);
+        }
+        return reqs;
+    };
+    const governedByLivingSpec = async (service, op) => {
+        return (await livingRequirements(service)).some((r) => r.operations.includes(op));
+    };
+    // What OTHER features in flight define, per (service, op). Cross-service work
+    // normally lands as feature A calling an op that in-flight feature B introduces;
+    // that is an ordering dependency, not a broken contract, and the requirements
+    // axis already grades the same shape as a warn (delta.modified-pending). Lazy
+    // like delta.ts's activeAdditions — the common case (op resolves) never pays
+    // for the fleet scan.
+    let inFlightOps = null;
+    const definedElsewhere = async (service, op) => {
+        inFlightOps ??= await activeOpAdditions(docsDir, featureId, context);
+        return inFlightOps.get(`${service} ${op}`);
+    };
+    // What the LIVING provider contracts mark `deprecated: true`, read lazily
+    // per service. Living only, on purpose: the feature's own openapi delta
+    // restates the full API, and the question here is whether the fleet as
+    // shipped is already retiring the op this feature starts leaning on.
+    const livingDeprecated = new Map();
+    const deprecatedInLiving = async (service, op) => {
+        let set = livingDeprecated.get(service);
+        if (!set) {
+            const list = await operations((await locateServicePaths(docsDir, service, context)).openapi, context);
+            set = new Set(list.filter((o) => o.deprecated).map((o) => o.id));
+            livingDeprecated.set(service, set);
+        }
+        return set.has(op);
+    };
+    // ...unless this feature IS the un-deprecation: an openapi delta that
+    // restates the op WITHOUT `deprecated: true` retires the flag on archive
+    // (the path-item overwrite is wholesale), so "prefer the replacement
+    // operation" would point the author away from the exact change they are
+    // shipping. A delta that restates the op still deprecated — or has no
+    // delta for the service at all — keeps the warning. The one lookup here
+    // that reads the delta's own files rather than the world outside it (the
+    // header says why it lives beside its living twin regardless).
+    const featureUndeprecated = new Map();
+    const undeprecatedByFeature = async (service, op) => {
+        let set = featureUndeprecated.get(service);
+        if (!set) {
+            const list = await operations(featureSpecPaths(featureDir, service).openapi, context);
+            set = new Set(list.filter((o) => !o.deprecated).map((o) => o.id));
+            featureUndeprecated.set(service, set);
+        }
+        return set.has(op);
+    };
+    return { governedByLivingSpec, definedElsewhere, deprecatedInLiving, undeprecatedByFeature };
+}
+//# sourceMappingURL=lookups.js.map

package/dist/core/coherence/lookups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookups.js","sourceRoot":"","sources":["../../../src/core/coherence/lookups.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The questions the coherence checks ask lazily, each behind a per-service or\n * per-repo cache.\n *\n * All but one reach outside the delta — into a living spec, a living\n * contract, or another feature in flight — and the cross-feature scan is a\n * walk of every active delta. The exception is `undeprecatedByFeature`, which\n * reads the FEATURE's own openapi delta: it lives here anyway because it is the\n * second half of the one question `deprecatedInLiving` opens — \"is this op\n * dying, and is this feature the resurrection?\" — and splitting the pair across\n * modules would leave each half's cache discipline unexplained by the other. A\n * feature whose checks never need a lookup must not pay for it, which is why\n * these are closures over a cache rather than arguments computed up front.\n *\n * The one question that used to live here and does not — who still CONSUMES an\n * operation the feature takes out (`edgeConsumers`, `requirementConsumers`,\n * `governorsAfterMerge`) — is the consumer index's now (`core/consumers/`),\n * because `loam diff` and the archive planner ask it too and the three copies\n * had drifted apart in which documents they read.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { type PathableService } from \"../kernel/ids/service.js\";\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport { operations } from \"../openapi/doc.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { activeOpAdditions } from \"./pending.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { type DeltaScope } from \"./declared.js\";\n\n/** What the checks may ask lazily — fleet questions, plus the deprecation pair. */\nexport interface Lookups {\n  governedByLivingSpec(service: PathableService, op: string): Promise<boolean>;\n  definedElsewhere(service: string, op: string): Promise<string | undefined>;\n  deprecatedInLiving(service: PathableService, op: string): Promise<boolean>;\n  undeprecatedByFeature(service: PathableService, op: string): Promise<boolean>;\n}\n\nexport function coherenceLookups(scope: DeltaScope, context?: FleetContext): Lookups {\n  const { docsDir, featureDir, featureId } = scope;\n    const livingReqs = new Map<string, Requirement[]>();\n    const livingRequirements = async (service: PathableService): Promise<Requirement[]> => {\n      let reqs = livingReqs.get(service);\n      if (reqs === undefined) {\n        const p = (await locateServicePaths(docsDir, service, context)).spec;\n        reqs = existsSync(p)\n          ? context === undefined\n            ? parseRequirements(await readFile(p, \"utf8\"))\n            : await context.readRequirements(p)\n          : [];\n        livingReqs.set(service, reqs);\n      }\n      return reqs;\n    };\n    const governedByLivingSpec = async (service: PathableService, op: string): Promise<boolean> => {\n      return (await livingRequirements(service)).some((r) => r.operations.includes(op));\n    };\n\n    // What OTHER features in flight define, per (service, op). Cross-service work\n    // normally lands as feature A calling an op that in-flight feature B introduces;\n    // that is an ordering dependency, not a broken contract, and the requirements\n    // axis already grades the same shape as a warn (delta.modified-pending). Lazy\n    // like delta.ts's activeAdditions — the common case (op resolves) never pays\n    // for the fleet scan.\n    let inFlightOps: Map<string, string> | null = null;\n    const definedElsewhere = async (service: string, op: string): Promise<string | undefined> => {\n      inFlightOps ??= await activeOpAdditions(docsDir, featureId, context);\n      return inFlightOps.get(`${service} ${op}`);\n    };\n\n    // What the LIVING provider contracts mark `deprecated: true`, read lazily\n    // per service. Living only, on purpose: the feature's own openapi delta\n    // restates the full API, and the question here is whether the fleet as\n    // shipped is already retiring the op this feature starts leaning on.\n    const livingDeprecated = new Map<string, Set<string>>();\n    const deprecatedInLiving = async (service: PathableService, op: string): Promise<boolean> => {\n      let set = livingDeprecated.get(service);\n      if (!set) {\n        const list = await operations((await locateServicePaths(docsDir, service, context)).openapi, context);\n        set = new Set(list.filter((o) => o.deprecated).map((o) => o.id));\n        livingDeprecated.set(service, set);\n      }\n      return set.has(op);\n    };\n\n    // ...unless this feature IS the un-deprecation: an openapi delta that\n    // restates the op WITHOUT `deprecated: true` retires the flag on archive\n    // (the path-item overwrite is wholesale), so \"prefer the replacement\n    // operation\" would point the author away from the exact change they are\n    // shipping. A delta that restates the op still deprecated — or has no\n    // delta for the service at all — keeps the warning. The one lookup here\n    // that reads the delta's own files rather than the world outside it (the\n    // header says why it lives beside its living twin regardless).\n    const featureUndeprecated = new Map<string, Set<string>>();\n    const undeprecatedByFeature = async (service: PathableService, op: string): Promise<boolean> => {\n      let set = featureUndeprecated.get(service);\n      if (!set) {\n        const list = await operations(featureSpecPaths(featureDir, service).openapi, context);\n        set = new Set(list.filter((o) => !o.deprecated).map((o) => o.id));\n        featureUndeprecated.set(service, set);\n      }\n      return set.has(op);\n    };\n  return { governedByLivingSpec, definedElsewhere, deprecatedInLiving, undeprecatedByFeature };\n}\n"]}

package/dist/core/coherence/pending.js

@@ -0,0 +1,39 @@
+/**
+ * What OTHER features in flight already define — the answer that turns "broken
+ * contract" into "ordering dependency".
+ *
+ * Cross-service work normally lands as feature A consuming an operation that
+ * in-flight feature B introduces; grading that as `op-undefined` tells the
+ * author to fix a contract that is merely queued. coherence.ts downgrades to
+ * the `*-pending` warnings on this module's answer. It is the openapi mirror
+ * of delta.ts's `activeAdditions`, and lives beside its caller rather than in
+ * delta.ts only because that module is at its size ceiling and the two
+ * mirrors never share code — each reads a different axis's documents.
+ */
+import { featureSpecPaths } from "../repo/paths.js";
+import { listFeatures } from "../repo/repo.js";
+import { operations } from "../openapi/doc.js";
+/**
+ * (service, operationId) pairs other ACTIVE features' openapi deltas define,
+ * mapped to the feature id. Archived features are excluded: their ops are in
+ * the living openapi already or gone for good, and neither is "pending". First
+ * feature wins a clash — one name to archive first is enough to make progress.
+ */
+export async function activeOpAdditions(docsDir, exclude, context) {
+    const map = new Map();
+    for (const feature of await listFeatures(docsDir, {}, context)) {
+        if (feature.id === exclude)
+            continue;
+        for (const service of feature.services) {
+            for (const op of await operations(featureSpecPaths(feature.dir, service).openapi, context)) {
+                if (op.remove)
+                    continue;
+                const k = `${service} ${op.id}`;
+                if (!map.has(k))
+                    map.set(k, feature.id);
+            }
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=pending.js.map

package/dist/core/coherence/pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/core/coherence/pending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,OAAe,EACf,OAAsB;IAEtB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;QAC/D,IAAI,OAAO,CAAC,EAAE,KAAK,OAAO;YAAE,SAAS;QACrC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACvC,KAAK,MAAM,EAAE,IAAI,MAAM,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC3F,IAAI,EAAE,CAAC,MAAM;oBAAE,SAAS;gBACxB,MAAM,CAAC,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * What OTHER features in flight already define — the answer that turns \"broken\n * contract\" into \"ordering dependency\".\n *\n * Cross-service work normally lands as feature A consuming an operation that\n * in-flight feature B introduces; grading that as `op-undefined` tells the\n * author to fix a contract that is merely queued. coherence.ts downgrades to\n * the `*-pending` warnings on this module's answer. It is the openapi mirror\n * of delta.ts's `activeAdditions`, and lives beside its caller rather than in\n * delta.ts only because that module is at its size ceiling and the two\n * mirrors never share code — each reads a different axis's documents.\n */\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { operations } from \"../openapi/doc.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * (service, operationId) pairs other ACTIVE features' openapi deltas define,\n * mapped to the feature id. Archived features are excluded: their ops are in\n * the living openapi already or gone for good, and neither is \"pending\". First\n * feature wins a clash — one name to archive first is enough to make progress.\n */\nexport async function activeOpAdditions(\n  docsDir: DocsDir,\n  exclude: string,\n  context?: FleetContext,\n): Promise<Map<string, string>> {\n  const map = new Map<string, string>();\n  for (const feature of await listFeatures(docsDir, {}, context)) {\n    if (feature.id === exclude) continue;\n    for (const service of feature.services) {\n      for (const op of await operations(featureSpecPaths(feature.dir, service).openapi, context)) {\n        if (op.remove) continue;\n        const k = `${service} ${op.id}`;\n        if (!map.has(k)) map.set(k, feature.id);\n      }\n    }\n  }\n  return map;\n}\n"]}