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

package/dist/core/coherence/events/grades.js

@@ -0,0 +1,166 @@
+import { ASYNCAPI_BASELINES_KEY } from "../../asyncapi/digest.js";
+import {} from "../../asyncapi/model.js";
+import { asyncapiSurfaces } from "../../asyncapi/baseline/surfaces.js";
+import { entryFor, readBaselineRecord, surfaceIn } from "../../openapi/baseline/record.js";
+import { classifyBaselineDigests, OPERATION_DIGEST_LENGTH, OPERATION_DIGEST_RE, valueDigest, } from "../../openapi/digest.js";
+/**
+ * One service's baselines against the living contract — openapi/baseline/gate.ts's
+ * verdicts, over BOTH halves of this axis: the slot pins in-value, and the
+ * component surfaces the root `x-loam-baselines` record pins. One function
+ * because the unpinned count is shared (see below), and because a delta is
+ * graded once or the two halves drift into different ideas of what it restates.
+ */
+export function gradeBaselines(input, issues) {
+    const { featSlots, livingSlots, svc, featureId } = input;
+    let unpinned = 0;
+    for (const slot of featSlots) {
+        // A removal marker is not a restatement of anything; its own exactness
+        // checks guard the slot.
+        if (slot.remove)
+            continue;
+        const label = `${slot.section}.${slot.key}`;
+        const living = livingSlots.get(`${slot.section}\0${slot.key}`);
+        if (slot.basedOn !== undefined && !OPERATION_DIGEST_RE.test(slot.basedOn)) {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.baseline-invalid",
+                subject: svc,
+                message: `${svc}: ${label} has invalid x-loam-based-on '${slot.basedOn}' — expected ${OPERATION_DIGEST_LENGTH} lowercase hex characters, as \`loam rebase\` writes them`,
+            });
+            continue;
+        }
+        const verdict = classifyBaselineDigests(slot.basedOn, slot.digest, living?.digest);
+        if (verdict === "unfounded") {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.baseline-invalid",
+                subject: svc,
+                message: `${svc}: ${label} carries x-loam-based-on, but the living contract has no slot there — a new channel, operation or message has no living version to be based on; drop the marker`,
+            });
+        }
+        else if (verdict === "stale") {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.baseline-stale",
+                subject: svc,
+                message: `${svc}: ${label} was written against living version ${slot.basedOn}, but the living contract now holds ${living.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living slot, fold in what you still mean, then run \`loam rebase ${featureId}\`.`,
+            });
+        }
+        else if (verdict === "unpinned" && living !== undefined) {
+            // Counted, not listed — a delta quotes most of the contract it
+            // restates, and one warning per quote teaches people to filter the
+            // code out (openapi.baseline-missing's doctrine, verbatim).
+            unpinned += 1;
+        }
+    }
+    // The surface half's unpinned count folds into the SAME counter, not a
+    // second warning: "counted, not listed" is the doctrine above, and one
+    // warning per axis-half would have a delta over a schema-heavy contract
+    // print two findings naming the same one command.
+    unpinned += gradeSurfaces(input, issues);
+    if (unpinned > 0) {
+        issues.push({
+            severity: "warn",
+            gates: true,
+            code: "asyncapi.baseline-missing",
+            subject: svc,
+            message: `${svc}: ${unpinned} slot(s) and component surface(s) in this feature's asyncapi.yaml carry no baseline pin (x-loam-based-on / ${ASYNCAPI_BASELINES_KEY}), so the merge cannot tell which ones this delta EDITS from the ones it merely restates — it will upsert all of them, reverting anything that landed on the restated ones. Run \`loam rebase ${featureId} --service ${svc}\`, or archive with --approve to merge unpinned deliberately.`,
+        });
+    }
+}
+/**
+ * The surface half: every `components/<kind>/<name>` outside `messages`,
+ * graded from the root `x-loam-baselines` record by the same classifier the
+ * slots go through. Returns the unpinned count so the caller can fold it into
+ * the one per-service warning rather than emitting a second.
+ *
+ * The codes are REUSED rather than multiplied — `asyncapi.baseline-invalid`
+ * and `asyncapi.baseline-stale` say exactly the same thing about a surface as
+ * about a slot, and a caller that branches on them wants one branch.
+ */
+function gradeSurfaces(input, issues) {
+    const { featPlain, livingPlain, svc, featureId } = input;
+    const invalid = (message) => {
+        issues.push({ severity: "error", code: "asyncapi.baseline-invalid", subject: svc, message: `${svc}: ${message}` });
+    };
+    const { record, problems } = readBaselineRecord(featPlain);
+    for (const problem of problems) {
+        invalid(`${problem} — the record is \`loam rebase\`'s bookkeeping and cannot be graded as it stands; re-run \`loam rebase ${featureId}\` to rebuild it`);
+    }
+    const surfaces = asyncapiSurfaces(featPlain);
+    // An entry pinning a surface the delta does not declare is a claim about
+    // nothing — usually one the author deleted after rebasing. Distinct from
+    // `unfounded` below, where the surface IS declared and the LIVING side is
+    // what vanished. A `pathItems` section is the same fault at the axis level:
+    // an AsyncAPI document has no path items, so the whole section pins nothing,
+    // and rebase's wholesale rebuild would drop it without a word.
+    const declared = new Set(surfaces.map((s) => s.id));
+    for (const id of Object.keys(record.components)) {
+        if (declared.has(id))
+            continue;
+        invalid(`${ASYNCAPI_BASELINES_KEY} pins component '${id}', but this feature's asyncapi.yaml does not declare it — re-run \`loam rebase ${featureId}\` to rebuild the record`);
+    }
+    for (const path of Object.keys(record.pathItems)) {
+        invalid(`${ASYNCAPI_BASELINES_KEY} pins path item '${path}', but an AsyncAPI document has no path items — the section pins nothing; re-run \`loam rebase ${featureId}\` to rebuild the record`);
+    }
+    let unpinned = 0;
+    for (const s of surfaces) {
+        const entry = entryFor(record, s);
+        const living = surfaceIn(livingPlain, s);
+        const verdict = classifyBaselineDigests(entry, valueDigest(s.value), living.found ? valueDigest(living.value) : undefined);
+        if (verdict === "unpinned") {
+            // Only a surface the living contract ALREADY has can be reverted by an
+            // unpinned merge; a genuinely new schema never trips the counter.
+            if (living.found)
+                unpinned += 1;
+        }
+        else if (verdict === "stale") {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.baseline-stale",
+                subject: svc,
+                message: `${svc}: component '${s.id}' was pinned to living version ${entry}, but the living contract now holds ${valueDigest(living.value)} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living value, fold in what you still mean, then run \`loam rebase ${featureId}\`.`,
+            });
+        }
+        else if (verdict === "unfounded") {
+            invalid(`component '${s.id}' is pinned to ${entry}, but the living contract no longer has that surface — the pin is structurally unresolvable; re-read the living contract, then run \`loam rebase ${featureId}\``);
+        }
+    }
+    return unpinned;
+}
+/** Marker exactness: the slot must exist, and a message marker must name the living declaration. */
+export function gradeMarkers(input, svc, issues) {
+    const { featDoc, livingDoc, featSlots, livingSlots } = input;
+    for (const slot of featSlots) {
+        if (!slot.remove)
+            continue;
+        const label = `${slot.section}.${slot.key}`;
+        const living = livingSlots.get(`${slot.section}\0${slot.key}`);
+        if (living === undefined) {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.remove-target-missing",
+                subject: svc,
+                message: `${svc}: removal marker at ${label} addresses no living slot — the contract has nothing there to retire; update the stale marker to the current key, or drop it if the slot is already gone`,
+            });
+            continue;
+        }
+        if (slot.section !== "components.messages")
+            continue;
+        // Removal is exact for messages the way it is for operations: the
+        // marker names both the key and the message identity it expects to
+        // delete, so a slot whose NAME moved under the delta is caught here
+        // rather than deleting somebody else's message.
+        const markerName = featDoc.messages.find((m) => m.remove === true && m.slot === label)?.name ?? slot.key;
+        const livingName = livingDoc.messages.find((m) => m.slot === label)?.name ?? slot.key;
+        if (markerName !== livingName) {
+            issues.push({
+                severity: "error",
+                code: "asyncapi.remove-target-mismatch",
+                subject: svc,
+                message: `${svc}: removal marker at ${label} names message '${markerName}', but the living declaration there is '${livingName}' — loam never deletes a different message occupying the slot`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=grades.js.map

package/dist/core/coherence/events/grades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grades.js","sourceRoot":"","sources":["../../../../src/core/coherence/events/grades.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The per-slot grades of one service's pair of event contracts: baseline\n * pins and removal-marker exactness. Split from ./declared.ts along the\n * subject seam — that module owns the WALK (which files, which services,\n * which sets), these functions own the verdict each slot gets once both\n * sides are in hand — when the walk grew past the line limit; the split\n * moved them verbatim.\n */\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport { ASYNCAPI_BASELINES_KEY, type AsyncapiSlot } from \"../../asyncapi/digest.js\";\nimport { type AsyncapiDoc } from \"../../asyncapi/model.js\";\nimport { asyncapiSurfaces } from \"../../asyncapi/baseline/surfaces.js\";\nimport { entryFor, readBaselineRecord, surfaceIn } from \"../../openapi/baseline/record.js\";\nimport {\n  classifyBaselineDigests,\n  OPERATION_DIGEST_LENGTH,\n  OPERATION_DIGEST_RE,\n  valueDigest,\n} from \"../../openapi/digest.js\";\n\n/** Everything the two baseline graders need about one service's pair of contracts. */\nexport interface AsyncapiBaselineInput {\n  featSlots: AsyncapiSlot[];\n  livingSlots: Map<string, AsyncapiSlot>;\n  /** The FEATURE document's resolved parse — where the record and the surfaces are read from. */\n  featPlain: unknown;\n  /** The LIVING document's resolved parse; `{}` where no living contract exists. */\n  livingPlain: unknown;\n  svc: string;\n  featureId: string;\n}\n\n/**\n * One service's baselines against the living contract — openapi/baseline/gate.ts's\n * verdicts, over BOTH halves of this axis: the slot pins in-value, and the\n * component surfaces the root `x-loam-baselines` record pins. One function\n * because the unpinned count is shared (see below), and because a delta is\n * graded once or the two halves drift into different ideas of what it restates.\n */\nexport function gradeBaselines(input: AsyncapiBaselineInput, issues: Issue[]): void {\n  const { featSlots, livingSlots, svc, featureId } = input;\n  let unpinned = 0;\n  for (const slot of featSlots) {\n    // A removal marker is not a restatement of anything; its own exactness\n    // checks guard the slot.\n    if (slot.remove) continue;\n    const label = `${slot.section}.${slot.key}`;\n    const living = livingSlots.get(`${slot.section}\\0${slot.key}`);\n    if (slot.basedOn !== undefined && !OPERATION_DIGEST_RE.test(slot.basedOn)) {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.baseline-invalid\",\n        subject: svc,\n        message: `${svc}: ${label} has invalid x-loam-based-on '${slot.basedOn}' — expected ${OPERATION_DIGEST_LENGTH} lowercase hex characters, as \\`loam rebase\\` writes them`,\n      });\n      continue;\n    }\n    const verdict = classifyBaselineDigests(slot.basedOn, slot.digest, living?.digest);\n    if (verdict === \"unfounded\") {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.baseline-invalid\",\n        subject: svc,\n        message: `${svc}: ${label} carries x-loam-based-on, but the living contract has no slot there — a new channel, operation or message has no living version to be based on; drop the marker`,\n      });\n    } else if (verdict === \"stale\") {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.baseline-stale\",\n        subject: svc,\n        message: `${svc}: ${label} was written against living version ${slot.basedOn}, but the living contract now holds ${living!.digest} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living slot, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n      });\n    } else if (verdict === \"unpinned\" && living !== undefined) {\n      // Counted, not listed — a delta quotes most of the contract it\n      // restates, and one warning per quote teaches people to filter the\n      // code out (openapi.baseline-missing's doctrine, verbatim).\n      unpinned += 1;\n    }\n  }\n  // The surface half's unpinned count folds into the SAME counter, not a\n  // second warning: \"counted, not listed\" is the doctrine above, and one\n  // warning per axis-half would have a delta over a schema-heavy contract\n  // print two findings naming the same one command.\n  unpinned += gradeSurfaces(input, issues);\n  if (unpinned > 0) {\n    issues.push({\n      severity: \"warn\",\n      gates: true,\n      code: \"asyncapi.baseline-missing\",\n      subject: svc,\n      message: `${svc}: ${unpinned} slot(s) and component surface(s) in this feature's asyncapi.yaml carry no baseline pin (x-loam-based-on / ${ASYNCAPI_BASELINES_KEY}), so the merge cannot tell which ones this delta EDITS from the ones it merely restates — it will upsert all of them, reverting anything that landed on the restated ones. Run \\`loam rebase ${featureId} --service ${svc}\\`, or archive with --approve to merge unpinned deliberately.`,\n    });\n  }\n}\n\n/**\n * The surface half: every `components/<kind>/<name>` outside `messages`,\n * graded from the root `x-loam-baselines` record by the same classifier the\n * slots go through. Returns the unpinned count so the caller can fold it into\n * the one per-service warning rather than emitting a second.\n *\n * The codes are REUSED rather than multiplied — `asyncapi.baseline-invalid`\n * and `asyncapi.baseline-stale` say exactly the same thing about a surface as\n * about a slot, and a caller that branches on them wants one branch.\n */\nfunction gradeSurfaces(input: AsyncapiBaselineInput, issues: Issue[]): number {\n  const { featPlain, livingPlain, svc, featureId } = input;\n  const invalid = (message: string): void => {\n    issues.push({ severity: \"error\", code: \"asyncapi.baseline-invalid\", subject: svc, message: `${svc}: ${message}` });\n  };\n  const { record, problems } = readBaselineRecord(featPlain);\n  for (const problem of problems) {\n    invalid(`${problem} — the record is \\`loam rebase\\`'s bookkeeping and cannot be graded as it stands; re-run \\`loam rebase ${featureId}\\` to rebuild it`);\n  }\n  const surfaces = asyncapiSurfaces(featPlain);\n  // An entry pinning a surface the delta does not declare is a claim about\n  // nothing — usually one the author deleted after rebasing. Distinct from\n  // `unfounded` below, where the surface IS declared and the LIVING side is\n  // what vanished. A `pathItems` section is the same fault at the axis level:\n  // an AsyncAPI document has no path items, so the whole section pins nothing,\n  // and rebase's wholesale rebuild would drop it without a word.\n  const declared = new Set(surfaces.map((s) => s.id));\n  for (const id of Object.keys(record.components)) {\n    if (declared.has(id)) continue;\n    invalid(`${ASYNCAPI_BASELINES_KEY} pins component '${id}', but this feature's asyncapi.yaml does not declare it — re-run \\`loam rebase ${featureId}\\` to rebuild the record`);\n  }\n  for (const path of Object.keys(record.pathItems)) {\n    invalid(`${ASYNCAPI_BASELINES_KEY} pins path item '${path}', but an AsyncAPI document has no path items — the section pins nothing; re-run \\`loam rebase ${featureId}\\` to rebuild the record`);\n  }\n\n  let unpinned = 0;\n  for (const s of surfaces) {\n    const entry = entryFor(record, s);\n    const living = surfaceIn(livingPlain, s);\n    const verdict = classifyBaselineDigests(\n      entry,\n      valueDigest(s.value),\n      living.found ? valueDigest(living.value) : undefined,\n    );\n    if (verdict === \"unpinned\") {\n      // Only a surface the living contract ALREADY has can be reverted by an\n      // unpinned merge; a genuinely new schema never trips the counter.\n      if (living.found) unpinned += 1;\n    } else if (verdict === \"stale\") {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.baseline-stale\",\n        subject: svc,\n        message: `${svc}: component '${s.id}' was pinned to living version ${entry}, but the living contract now holds ${valueDigest(living.value)} — somebody landed a change to it in between, and merging this would replace theirs outright. Re-read the living value, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n      });\n    } else if (verdict === \"unfounded\") {\n      invalid(`component '${s.id}' is pinned to ${entry}, but the living contract no longer has that surface — the pin is structurally unresolvable; re-read the living contract, then run \\`loam rebase ${featureId}\\``);\n    }\n  }\n  return unpinned;\n}\n\n/** Marker exactness: the slot must exist, and a message marker must name the living declaration. */\nexport function gradeMarkers(\n  input: { featDoc: AsyncapiDoc; livingDoc: AsyncapiDoc; featSlots: AsyncapiSlot[]; livingSlots: Map<string, AsyncapiSlot> },\n  svc: string,\n  issues: Issue[],\n): void {\n  const { featDoc, livingDoc, featSlots, livingSlots } = input;\n  for (const slot of featSlots) {\n    if (!slot.remove) continue;\n    const label = `${slot.section}.${slot.key}`;\n    const living = livingSlots.get(`${slot.section}\\0${slot.key}`);\n    if (living === undefined) {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.remove-target-missing\",\n        subject: svc,\n        message: `${svc}: removal marker at ${label} addresses no living slot — the contract has nothing there to retire; update the stale marker to the current key, or drop it if the slot is already gone`,\n      });\n      continue;\n    }\n    if (slot.section !== \"components.messages\") continue;\n    // Removal is exact for messages the way it is for operations: the\n    // marker names both the key and the message identity it expects to\n    // delete, so a slot whose NAME moved under the delta is caught here\n    // rather than deleting somebody else's message.\n    const markerName = featDoc.messages.find((m) => m.remove === true && m.slot === label)?.name ?? slot.key;\n    const livingName = livingDoc.messages.find((m) => m.slot === label)?.name ?? slot.key;\n    if (markerName !== livingName) {\n      issues.push({\n        severity: \"error\",\n        code: \"asyncapi.remove-target-mismatch\",\n        subject: svc,\n        message: `${svc}: removal marker at ${label} names message '${markerName}', but the living declaration there is '${livingName}' — loam never deletes a different message occupying the slot`,\n      });\n    }\n  }\n}\n"]}

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

@@ -0,0 +1,122 @@
+/**
+ * The event axis's fleet questions, each read lazily — ../lookups.ts's
+ * pattern on the message join.
+ *
+ * Both reach outside the delta: the consumer scan is a landscape spin-up
+ * plus a walk of every other service's living requirements, and the
+ * in-flight scan reads every active feature's asyncapi delta. Closures over
+ * a cache rather than arguments computed up front, so each is paid only
+ * when its question is first asked — but the two prices differ, and the
+ * difference is deliberate: the consumer scan is paid only by a feature
+ * that actually retires production, while the in-flight scan is paid by ANY
+ * feature that declares a message at all, because
+ * `asyncapi.message-conflict`'s question ("does an in-flight feature define
+ * this elsewhere?") is asked of every healthy declaration — unlike the
+ * OpenAPI mirror, whose `definedElsewhere` is reached only inside a breach
+ * branch. That standing cost matters most on `archive`'s gate, which runs
+ * without a FleetContext, so each read here is a real parse.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { loadFile } from "../../c4/likec4.js";
+import { serviceResolver } from "../../c4/resolve/service.js";
+import {} from "../../kernel/ids/service.js";
+import { featureSpecPaths, landscapePath, SPEC_AXES } from "../../repo/paths.js";
+import { enumeratedServiceIds, locateServicePaths } from "../../repo/service-target.js";
+import { listFeatures } from "../../repo/repo.js";
+import { readAsyncapi } from "../../asyncapi/read.js";
+import { parseRequirements } from "../../document/parse.js";
+import {} from "../../document/spec.js";
+export function eventLookups(scope, context) {
+    const { docsDir, featureId } = scope;
+    // The enumerated fleet, read once and shared by both halves of the
+    // consumer scan — ../lookups.ts's discipline, verbatim.
+    let serviceIds;
+    const enumeratedServices = async () => (serviceIds ??= await enumeratedServiceIds(docsDir, context));
+    // Living requirements per service, BOTH axes: `Publishes:`/`Consumes:`
+    // live in arch.spec.md at least as often as in spec.md (the outbox
+    // requirement), so a scan of spec.md alone would answer "nobody consumes
+    // it" over the file most authors use.
+    const livingReqs = new Map();
+    const livingRequirements = async (service) => {
+        let reqs = livingReqs.get(service);
+        if (reqs === undefined) {
+            reqs = [];
+            for (const axis of SPEC_AXES) {
+                const p = (await locateServicePaths(docsDir, service, context))[axis.key];
+                if (!existsSync(p))
+                    continue;
+                reqs.push(...(context === undefined
+                    ? parseRequirements(await readFile(p, "utf8"))
+                    : await context.readRequirements(p)));
+            }
+            livingReqs.set(service, reqs);
+        }
+        return reqs;
+    };
+    // The landscape half: a `consumes` edge is a consumer somebody drew. The
+    // message join is fleet-global (names are not service-scoped), so every
+    // edge naming the message counts, whoever its producer is — resolved
+    // through the enumerated fleet so a landscape that models CONTAINERS
+    // stays visible, ../lookups.ts's edgeConsumers lesson.
+    // (`core/diff/victims.ts` mirrors this scan over an already-read fleet —
+    // change the rules or the victim strings here and that module owes the
+    // same change; a third copy forces the shared extraction, rule 13.)
+    let livingLandscape;
+    const messageConsumers = async (service, message) => {
+        if (livingLandscape === undefined) {
+            const path = landscapePath(docsDir);
+            livingLandscape = existsSync(path)
+                ? context === undefined
+                    ? await loadFile(path)
+                    : await context.loadLikeC4(path)
+                : null;
+        }
+        const out = [];
+        // An unreadable landscape proves nothing either way; `landscape.invalid`
+        // is validate's finding to make.
+        if (livingLandscape !== null && livingLandscape.errors.length === 0) {
+            const resolve = serviceResolver(livingLandscape.elements, new Set(await enumeratedServices()));
+            for (const r of livingLandscape.relationships) {
+                if (r.consumes !== message || resolve(r.target) === service)
+                    continue;
+                out.push(`edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? "" : ` ("${r.title}")`}`);
+            }
+        }
+        for (const other of (await enumeratedServices()).filter((id) => id !== service)) {
+            for (const r of await livingRequirements(other)) {
+                if (r.consumes.includes(message))
+                    out.push(`${other}'s living requirement '${r.name}'`);
+            }
+        }
+        return out;
+    };
+    // What OTHER features in flight declare, per (service, message) — the
+    // asyncapi mirror of pending.ts's activeOpAdditions, living HERE because
+    // it shares this module's laziness and its consumers. Removal markers do
+    // not count: a feature retiring a message is not adding it. First feature
+    // wins a clash — one name to archive first is enough to make progress.
+    let inFlight = null;
+    const messageDefinedElsewhere = async (service, message) => {
+        if (inFlight === null) {
+            inFlight = new Map();
+            for (const feature of await listFeatures(docsDir, {}, context)) {
+                if (feature.id === featureId)
+                    continue;
+                for (const svc of feature.services) {
+                    const doc = await readAsyncapi(featureSpecPaths(feature.dir, svc).asyncapi, context);
+                    for (const m of doc.messages) {
+                        if (m.remove === true)
+                            continue;
+                        const k = `${svc} ${m.name}`;
+                        if (!inFlight.has(k))
+                            inFlight.set(k, feature.id);
+                    }
+                }
+            }
+        }
+        return inFlight.get(`${service} ${message}`);
+    };
+    return { messageConsumers, messageDefinedElsewhere };
+}
+//# sourceMappingURL=lookups.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lookups.js","sourceRoot":"","sources":["../../../../src/core/coherence/events/lookups.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The event axis's fleet questions, each read lazily — ../lookups.ts's\n * pattern on the message join.\n *\n * Both reach outside the delta: the consumer scan is a landscape spin-up\n * plus a walk of every other service's living requirements, and the\n * in-flight scan reads every active feature's asyncapi delta. Closures over\n * a cache rather than arguments computed up front, so each is paid only\n * when its question is first asked — but the two prices differ, and the\n * difference is deliberate: the consumer scan is paid only by a feature\n * that actually retires production, while the in-flight scan is paid by ANY\n * feature that declares a message at all, because\n * `asyncapi.message-conflict`'s question (\"does an in-flight feature define\n * this elsewhere?\") is asked of every healthy declaration — unlike the\n * OpenAPI mirror, whose `definedElsewhere` is reached only inside a breach\n * branch. That standing cost matters most on `archive`'s gate, which runs\n * without a FleetContext, so each read here is a real parse.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { loadFile, type LoadedDoc } from \"../../c4/likec4.js\";\nimport { serviceResolver } from \"../../c4/resolve/service.js\";\nimport { type PathableService } from \"../../kernel/ids/service.js\";\nimport { featureSpecPaths, landscapePath, SPEC_AXES } from \"../../repo/paths.js\";\nimport { enumeratedServiceIds, locateServicePaths } from \"../../repo/service-target.js\";\nimport { listFeatures } from \"../../repo/repo.js\";\nimport { readAsyncapi } from \"../../asyncapi/read.js\";\nimport { parseRequirements } from \"../../document/parse.js\";\nimport { type Requirement } from \"../../document/spec.js\";\nimport type { FleetContext } from \"../../fleet-context.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\n\n/** What the event checks may ask about the world outside this feature's own files. */\nexport interface EventLookups {\n  /**\n   * Living consumers of one message a `service` is retiring: landscape\n   * `consumes` edges, and other services' living requirements' `Consumes:`\n   * lines (spec.md and arch.spec.md both — the outbox file is the canonical\n   * home of an event line). The retiring service itself is excluded from\n   * both: its own consumption leaves in the same feature, and counting it\n   * would gate every self-consuming producer on its own retirement.\n   */\n  messageConsumers(service: string, message: string): Promise<string[]>;\n  /** The in-flight feature (if any) whose asyncapi delta adds or edits (service, message). */\n  messageDefinedElsewhere(service: string, message: string): Promise<string | undefined>;\n}\n\n/** The identity of the feature being graded — what the lazy scans exclude. */\nexport interface EventScope {\n  docsDir: DocsDir;\n  featureId: string;\n}\n\nexport function eventLookups(scope: EventScope, context?: FleetContext): EventLookups {\n  const { docsDir, featureId } = scope;\n\n  // The enumerated fleet, read once and shared by both halves of the\n  // consumer scan — ../lookups.ts's discipline, verbatim.\n  let serviceIds: PathableService[] | undefined;\n  const enumeratedServices = async (): Promise<PathableService[]> =>\n    (serviceIds ??= await enumeratedServiceIds(docsDir, context));\n\n  // Living requirements per service, BOTH axes: `Publishes:`/`Consumes:`\n  // live in arch.spec.md at least as often as in spec.md (the outbox\n  // requirement), so a scan of spec.md alone would answer \"nobody consumes\n  // it\" over the file most authors use.\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      reqs = [];\n      for (const axis of SPEC_AXES) {\n        const p = (await locateServicePaths(docsDir, service, context))[axis.key];\n        if (!existsSync(p)) continue;\n        reqs.push(\n          ...(context === undefined\n            ? parseRequirements(await readFile(p, \"utf8\"))\n            : await context.readRequirements(p)),\n        );\n      }\n      livingReqs.set(service, reqs);\n    }\n    return reqs;\n  };\n\n  // The landscape half: a `consumes` edge is a consumer somebody drew. The\n  // message join is fleet-global (names are not service-scoped), so every\n  // edge naming the message counts, whoever its producer is — resolved\n  // through the enumerated fleet so a landscape that models CONTAINERS\n  // stays visible, ../lookups.ts's edgeConsumers lesson.\n  // (`core/diff/victims.ts` mirrors this scan over an already-read fleet —\n  // change the rules or the victim strings here and that module owes the\n  // same change; a third copy forces the shared extraction, rule 13.)\n  let livingLandscape: LoadedDoc | null | undefined;\n  const messageConsumers = async (service: string, message: string): Promise<string[]> => {\n    if (livingLandscape === undefined) {\n      const path = landscapePath(docsDir);\n      livingLandscape = existsSync(path)\n        ? context === undefined\n          ? await loadFile(path)\n          : await context.loadLikeC4(path)\n        : null;\n    }\n    const out: string[] = [];\n    // An unreadable landscape proves nothing either way; `landscape.invalid`\n    // is validate's finding to make.\n    if (livingLandscape !== null && livingLandscape.errors.length === 0) {\n      const resolve = serviceResolver(livingLandscape.elements, new Set(await enumeratedServices()));\n      for (const r of livingLandscape.relationships) {\n        if (r.consumes !== message || resolve(r.target) === service) continue;\n        out.push(`edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? \"\" : ` (\"${r.title}\")`}`);\n      }\n    }\n    for (const other of (await enumeratedServices()).filter((id) => id !== service)) {\n      for (const r of await livingRequirements(other)) {\n        if (r.consumes.includes(message)) out.push(`${other}'s living requirement '${r.name}'`);\n      }\n    }\n    return out;\n  };\n\n  // What OTHER features in flight declare, per (service, message) — the\n  // asyncapi mirror of pending.ts's activeOpAdditions, living HERE because\n  // it shares this module's laziness and its consumers. Removal markers do\n  // not count: a feature retiring a message is not adding it. First feature\n  // wins a clash — one name to archive first is enough to make progress.\n  let inFlight: Map<string, string> | null = null;\n  const messageDefinedElsewhere = async (service: string, message: string): Promise<string | undefined> => {\n    if (inFlight === null) {\n      inFlight = new Map<string, string>();\n      for (const feature of await listFeatures(docsDir, {}, context)) {\n        if (feature.id === featureId) continue;\n        for (const svc of feature.services) {\n          const doc = await readAsyncapi(featureSpecPaths(feature.dir, svc).asyncapi, context);\n          for (const m of doc.messages) {\n            if (m.remove === true) continue;\n            const k = `${svc} ${m.name}`;\n            if (!inFlight.has(k)) inFlight.set(k, feature.id);\n          }\n        }\n      }\n    }\n    return inFlight.get(`${service} ${message}`);\n  };\n\n  return { messageConsumers, messageDefinedElsewhere };\n}\n"]}

package/dist/core/coherence/events/merged.js

@@ -0,0 +1,40 @@
+/**
+ * The contract as the feature would leave it: the REAL merge
+ * (core/asyncapi/merge/merge.ts) run over the two texts and read back,
+ * nothing written. One simulation feeds two gate questions — the
+ * `declares()` join in ./events.ts (a retired or edited-away send must stop
+ * answering "the service declares this" BEFORE archive, or a leftover
+ * `Publishes:` line passes the gate and breaks the post-archive fleet) and
+ * the consumer gate's wire half (a channel or operation removal that stops
+ * the service SENDING a message the fleet still consumes).
+ *
+ * Calling the merge rather than re-deriving its verdicts is the point: a
+ * second spelling of quote/edit/removal here would eventually disagree with
+ * the merge about what archive actually writes, and the gate would be
+ * promising a contract the archive does not produce.
+ */
+import { parse } from "yaml";
+import { asyncapiDocOf } from "../../asyncapi/read.js";
+import { AsyncapiMergeError } from "../../asyncapi/merge/error.js";
+import { mergeAsyncapiSlots } from "../../asyncapi/merge/merge.js";
+/**
+ * Simulate the archive-time merge, or stand down. Both documents are known
+ * readable here (the walk in ./declared.ts checked), so the only refusals
+ * left are the merge's own judgement calls — an aliased section, a section
+ * spelling one slot key twice. `undefined` on those rather than a throw: the
+ * caller falls back to the feature ∪ living union view, which can only be
+ * too lenient, and the archive's own plan will surface the refusal by name.
+ */
+export function mergedAsyncapiDoc(input) {
+    const { livingText, livingDoc, featureText, service } = input;
+    try {
+        const out = mergeAsyncapiSlots(livingText, featureText, service);
+        return out.text === null ? livingDoc : asyncapiDocOf(parse(out.text));
+    }
+    catch (error) {
+        if (error instanceof AsyncapiMergeError)
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=merged.js.map

package/dist/core/coherence/events/merged.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merged.js","sourceRoot":"","sources":["../../../../src/core/coherence/events/merged.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAWnE;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA2B;IAC3D,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,kBAAkB;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * The contract as the feature would leave it: the REAL merge\n * (core/asyncapi/merge/merge.ts) run over the two texts and read back,\n * nothing written. One simulation feeds two gate questions — the\n * `declares()` join in ./events.ts (a retired or edited-away send must stop\n * answering \"the service declares this\" BEFORE archive, or a leftover\n * `Publishes:` line passes the gate and breaks the post-archive fleet) and\n * the consumer gate's wire half (a channel or operation removal that stops\n * the service SENDING a message the fleet still consumes).\n *\n * Calling the merge rather than re-deriving its verdicts is the point: a\n * second spelling of quote/edit/removal here would eventually disagree with\n * the merge about what archive actually writes, and the gate would be\n * promising a contract the archive does not produce.\n */\nimport { parse } from \"yaml\";\nimport { asyncapiDocOf } from \"../../asyncapi/read.js\";\nimport type { AsyncapiDoc } from \"../../asyncapi/model.js\";\nimport { AsyncapiMergeError } from \"../../asyncapi/merge/error.js\";\nimport { mergeAsyncapiSlots } from \"../../asyncapi/merge/merge.js\";\n\n/** The two texts the simulation merges, plus the living side's existing parse. */\nexport interface MergeSimulationInput {\n  livingText: string;\n  /** `readAsyncapi` of livingText — reused verbatim when the merge writes nothing. */\n  livingDoc: AsyncapiDoc;\n  featureText: string;\n  service: string;\n}\n\n/**\n * Simulate the archive-time merge, or stand down. Both documents are known\n * readable here (the walk in ./declared.ts checked), so the only refusals\n * left are the merge's own judgement calls — an aliased section, a section\n * spelling one slot key twice. `undefined` on those rather than a throw: the\n * caller falls back to the feature ∪ living union view, which can only be\n * too lenient, and the archive's own plan will surface the refusal by name.\n */\nexport function mergedAsyncapiDoc(input: MergeSimulationInput): AsyncapiDoc | undefined {\n  const { livingText, livingDoc, featureText, service } = input;\n  try {\n    const out = mergeAsyncapiSlots(livingText, featureText, service);\n    return out.text === null ? livingDoc : asyncapiDocOf(parse(out.text));\n  } catch (error) {\n    if (error instanceof AsyncapiMergeError) return undefined;\n    throw error;\n  }\n}\n"]}

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