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

package/dist/core/delta/delta.js

@@ -0,0 +1,296 @@
+/**
+ * Does the diff apply to the thing it claims to change?
+ *
+ * A requirement delta is a diff against a living spec, and nothing used to check
+ * that it lands. Every failure mode here is silent today: MODIFIED of a
+ * requirement that does not exist is merged as a creation, ADDED of one that
+ * does exist REPLACES it (scenarios and all) while the author believes they are
+ * adding, and a heading that nearly matches the delta grammar parses as plain
+ * prose so archive merges nothing at all and says nothing about it.
+ *
+ * The last of those has a legal-looking cousin: a requirement under an ordinary
+ * prose heading (`## Behavior`, `## Error Handling`) is BASE too, and BASE never
+ * merges. Upstream OpenSpec deltas are written that way, so the answer is to name
+ * what will be lost rather than to start merging prose sections.
+ *
+ * These run inside the archive gate, because the merge is where the damage lands.
+ *
+ * TWO CORPORA, ONE ALGEBRA. A feature's delta documents live in two places —
+ * `specs/<svc>/{spec,arch.spec}.md` against the service tree, and
+ * `capabilities/<id>/spec.md` against the authored business tree — and every
+ * grade about a DOCUMENT and its living counterpart applies to both verbatim,
+ * with the capability id in `subject` where a service id would be. That is not
+ * a coincidence to exploit but the reason the business corpus was given deltas
+ * at all: a capability document is a requirements document, so the diff that
+ * changes one has exactly the same ways of not landing. A second implementation
+ * would be a second set of answers to `delta.added-duplicate`.
+ *
+ * The exception is the four CROSS-FEATURE warnings — `delta.added-conflict`,
+ * `delta.modified-conflict`, `delta.modified-pending`, `delta.removed-pending`
+ * — which ask what OTHER features in flight claim. `./claims.ts` indexes the
+ * service corpus only and states why; on the business axis those four are
+ * silent, which is a missing warning and never a wrong answer.
+ *
+ * This module is only the walk: which documents get read, in what order, and how
+ * each is handed a `DeltaScope`. The checks themselves are in `./document.ts`
+ * (a document against itself) and `./select.ts` (the delta against the living
+ * text). Their order is load-bearing and stays here, where it can be read in one
+ * screen.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import {} from "../fleet-context.js";
+import { parseRequirements } from "../document/parse.js";
+import {} from "../document/spec.js";
+import { featureSpecPaths, SPEC_AXES } from "../repo/paths.js";
+import { featureUseCasesDir, livingCapabilityPaths } from "../repo/authored/paths.js";
+import { readCapabilityVocabulary } from "../capabilities/capabilities.js";
+import { flowCoverage } from "../usecases/delta/claims.js";
+import { enumeratedServiceIds, locateServicePaths } from "../repo/service-target.js";
+import { featureSpecServices } from "../repo/repo.js";
+import { capabilityDocIssues } from "../capabilities/delta/doc.js";
+import { featureCapabilityDeltas } from "../capabilities/delta/tree.js";
+import { removedRealizedIssues, uncoveredIssues, } from "../capabilities/delta/uncovered.js";
+import {} from "../vocabulary/issue.js";
+import { claimLookup } from "./claims.js";
+import { deltaDocumentIssues, livingDocumentIssues } from "./document.js";
+import { indexLiving } from "./scope.js";
+import { selectionIssues } from "./select.js";
+/**
+ * The business corpus's ONE axis. A capability document carries the promise and
+ * nothing else — there is no `arch.spec.md` beside it, because "how it is
+ * built" is precisely the altitude a capability requirement may not describe
+ * (`capability.requirement-service-scoped` is that rule). It has no `key`
+ * because it indexes no `ServicePaths`, which is why `DeltaScope.axis` is the
+ * narrower `DeltaAxis` and not `SpecAxis`.
+ */
+const CAPABILITY_AXIS = { file: "spec.md" };
+export async function deltaShapeIssues(docsDir, featureDir, featureId, context) {
+    const issues = [];
+    const services = await featureSpecServices(featureDir, context);
+    // One `existsSync` for a feature that carries no capability delta, which is
+    // every feature in a fleet that has not adopted the business axis.
+    const capabilities = context === undefined ? await featureCapabilityDeltas(featureDir) : await context.featureCapabilityDeltas(featureDir);
+    // The flows this feature brings, and one `existsSync` for a feature that
+    // brings none — which is every feature in a fleet that has not adopted the
+    // axis. The directory, not the documents: what is needed here is whether to
+    // pay for the overlay at all, and the walk that lists them happens once,
+    // inside it.
+    const hasFlows = existsSync(featureUseCasesDir(featureDir));
+    // The early return must ask about EVERY corpus. Asking only about services
+    // meant a capability-only feature — a business change with no service touched
+    // yet, which is exactly what an analyst writes first — was graded by nothing
+    // and archived whatever its delta said; asking only about those two would do
+    // the same to a feature whose whole content is a cross-service flow, which is
+    // the shape an architect answers an analyst with.
+    if (services.length === 0 && capabilities.docs.length === 0 && !hasFlows)
+        return issues;
+    // What OTHER features in flight claim. Only built when a claim has to be
+    // checked — the common case never pays for the scan.
+    const reads = {
+        claims: claimLookup(docsDir, featureId, context),
+        ...(context === undefined ? {} : { context }),
+    };
+    // The two corpora's parsed requirements, kept as the walk produces them so
+    // the `Realizes:` join below can be taken without re-reading a byte. That
+    // join is the one question neither corpus can answer alone — which service
+    // requirement keeps which business promise — and this is the only place in
+    // loam where both sides are already open (`capabilities/delta/uncovered.ts`
+    // holds the rules; nothing here decides anything).
+    const serviceDeltas = [];
+    const capabilityDeltas = [];
+    // Both requirement-carrying files per service run the same checks — one code
+    // path parameterized by filename, the merge's own factoring. `where` names
+    // the arch file in messages so a finding cannot be chased into the wrong
+    // document; spec.md keeps its historical spelling.
+    for (const service of services) {
+        for (const axis of SPEC_AXES) {
+            const specPath = featureSpecPaths(featureDir, service)[axis.key];
+            if (!existsSync(specPath))
+                continue;
+            const scope = {
+                kind: "service",
+                subject: service,
+                axis,
+                featureId,
+                docsDir,
+                specPath,
+                where: axis.key === "spec" ? service : `${service} (arch.spec.md)`,
+                // How the axis's living document is named in messages — spec.md keeps
+                // the historical "living spec", the arch axis says which file it means.
+                livingDoc: axis.key === "spec" ? "living spec" : "living arch.spec.md",
+            };
+            const graded = await gradeDelta(scope, (await locateServicePaths(docsDir, service, context))[axis.key], reads);
+            issues.push(...graded.issues);
+            serviceDeltas.push({ service, file: axis.file, reqs: graded.reqs });
+        }
+    }
+    for (const doc of capabilities.docs) {
+        const scope = {
+            kind: "capability",
+            subject: doc.id,
+            axis: CAPABILITY_AXIS,
+            featureId,
+            docsDir,
+            specPath: doc.spec,
+            // `capability <id>`, not `capabilities/<id>` — the second reads as the
+            // LIVING directory, and every message this labels is about the FEATURE's
+            // delta of it. Sending an author to edit the wrong one of two files with
+            // the same name is the whole reason `where` and `livingDoc` are separate.
+            where: `capability ${doc.id}`,
+            livingDoc: `living capabilities/${doc.id}/spec.md`,
+        };
+        // Absent is a real and ordinary answer on this axis: the first feature to
+        // mention a capability is what creates its living document, so the whole
+        // delta grades against `[]` and every requirement in it is legitimately an
+        // addition.
+        const graded = await gradeDelta(scope, livingCapabilityPaths(docsDir, doc.id).spec, reads);
+        issues.push(...graded.issues);
+        // The document's own three rules, on the requirements this delta would
+        // MERGE — before the merge, where the author can still fix them. See
+        // `capabilities/delta/doc.ts` for why grading only the living copy leaves a
+        // hole straight through the altitude rule.
+        issues.push(...capabilityDocIssues(graded.reqs, {
+            where: relative(docsDir, doc.spec).split(/[\\/]/).join("/"),
+            subject: doc.id,
+        }));
+        capabilityDeltas.push({ id: doc.id, reqs: graded.reqs, living: graded.living.all });
+    }
+    // The other carrier of a promise, read once and only when this feature
+    // actually brings a flow: the `dynamic view`s under `features/<FEAT>/usecases/`,
+    // parsed over the map this feature's own merge would leave behind
+    // (`core/usecases/delta/overlay.ts`).
+    // A feature with no `usecases/` directory is a REAL empty answer, not an
+    // ungraded one: there is no flow, so "no flow keeps this" is true and the
+    // message may say it.
+    const kept = hasFlows
+        ? await flowCoverage({
+            docsDir,
+            featureDir,
+            featureId,
+            capabilities: capabilityDeltas,
+            // Read HERE, through the invocation's index, because this module holds
+            // it and `core/usecases/` does not — every other read in this walk does
+            // the same, and `core/repo/service-target.ts` prices a fleet
+            // enumeration per call at ~13 ms on a 120-service fleet.
+            vocabulary: context === undefined ? await readCapabilityVocabulary(docsDir) : await context.capabilities(docsDir),
+            known: new Set(await enumeratedServiceIds(docsDir, context)),
+            // A function rather than the context itself: one memoised LikeC4 read
+            // does not justify an edge from `core/usecases/` to `fleet-context`, and
+            // the edge would push that package up a DAG level for nothing.
+            ...(context === undefined ? {} : { load: (path) => context.loadLikeC4(path) }),
+        })
+        : { kind: "read", kept: [] };
+    if (kept.kind === "unreadable") {
+        // ERROR, and the archive gate's own `NEVER_OVERRIDABLE` keeps `--approve`
+        // off it. This is the refusal that stops a flow being copied into
+        // `architecture/` and the NEXT reader's `loam validate --all` carrying the
+        // failure — including the case the overlay exists for, a hop naming an
+        // element the merge does not land. Mechanical, so it is not loam's judgement
+        // to override.
+        issues.push({
+            severity: "error",
+            code: "usecase.flow-invalid",
+            subject: featureId,
+            // The opening sentence does NOT say whose file is at fault, and that is
+            // deliberate: the corpus this reads is the feature's flows PLUS the living
+            // `architecture/` documents they are drawn over, so the failing path can
+            // be a living one — a landscape that no longer parses, a use case somebody
+            // else wrote. Every message carries its own path, so a reader can place
+            // it; an opening line that blamed `usecases/` would send them to the wrong
+            // file first.
+            message: `this feature's flows could not be graded against the map its own merge would leave behind, so the archive ` +
+                `would land an architecture/ nothing has checked. The corpus is the feature's usecases/ AND the living ` +
+                `architecture/ documents they are drawn over, so the fault may be in either — each message names its file. ` +
+                `${kept.errors.length} problem(s): ${kept.errors.join("; ")}`,
+        });
+    }
+    // The `Realizes:` join, both directions, over documents this walk has already
+    // parsed. Skipped entirely when the feature carries no capability delta,
+    // which is every feature in a fleet that has not adopted the business axis —
+    // and the removal half asks for the living corpus only when something is
+    // actually retired, so even an adopting fleet pays the fleet-wide read on the
+    // features that earn it.
+    if (capabilityDeltas.length > 0) {
+        // The three arms travel as three, and flattening two of them to `[]` is
+        // the one thing this must not do: `capability.uncovered` says in words that
+        // no flow keeps the promise, so handing it an empty list for a corpus loam
+        // could not read or could not resolve makes it assert a negative it never
+        // evaluated — and gate on it. `claims.ts`'s header states the rule; this is
+        // where a caller could break it.
+        issues.push(...uncoveredIssues(capabilityDeltas, serviceDeltas, kept.kind === "read"
+            ? { graded: true, kept: kept.kept }
+            : { graded: false, why: kept.kind === "ungraded" ? kept.why : kept.errors.join("; ") }));
+        issues.push(...(await removedRealizedIssues({
+            capabilities: capabilityDeltas,
+            deltas: serviceDeltas,
+            living: () => livingRealizers(docsDir, context),
+        })));
+    }
+    return issues;
+}
+/**
+ * Every LIVING service requirements document in the fleet, for the one question
+ * that has to ask about services this feature never mentions: does anything out
+ * there still realize a capability requirement this feature retires?
+ *
+ * The same shape and the same cost `openapi.remove-op-consumed` pays through
+ * `coherence/lookups.ts` one axis over, and for the same reason — the merge
+ * deletes the promise while the `Realizes:` line stays, so the very next
+ * `validate --all` reports a breach on a repository whose author was never in
+ * this feature. Called behind a thunk (`removedRealizedIssues` invokes it only
+ * when something is retired), so a feature that removes nothing never runs it.
+ */
+async function livingRealizers(docsDir, context) {
+    const out = [];
+    for (const service of await enumeratedServiceIds(docsDir, context)) {
+        const paths = await locateServicePaths(docsDir, service, context);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            const reqs = context === undefined ? parseRequirements(await readFile(path, "utf8")) : await context.readRequirements(path);
+            out.push({ service, file: axis.file, reqs });
+        }
+    }
+    return out;
+}
+/**
+ * One delta document against one living document: the three passes, in the
+ * order that makes their messages readable.
+ *
+ * The order is load-bearing. `deltaDocumentIssues` settles what the delta says
+ * about itself, `livingDocumentIssues` settles whether the living text can be
+ * selected in at all, and only then does `selectionIssues` compare them — a pin
+ * the document pass already refused must not also be reported stale, which
+ * would send its author to `loam rebase` for a problem rebase does not fix.
+ *
+ * The parsed delta requirements come back with the issues because the capability
+ * corpus grades them a second way (`capabilityDocIssues`) and re-reading the
+ * file to do it would be a second parse of bytes already in hand — and, without
+ * a context, a second chance for the two passes to disagree about the document.
+ * The LIVING index rides back for the same reason once more: the removal
+ * direction of the `Realizes:` join has to resolve a REMOVED spelled by heading
+ * into the id it retires, and that id is a fact about the living document.
+ */
+async function gradeDelta(scope, livingPath, reads) {
+    const { claims, context } = reads;
+    const raw = context === undefined ? await readFile(scope.specPath, "utf8") : await context.readText(scope.specPath);
+    const reqs = context === undefined ? parseRequirements(raw) : await context.readRequirements(scope.specPath);
+    const living = indexLiving(!existsSync(livingPath)
+        ? []
+        : context === undefined
+            ? parseRequirements(await readFile(livingPath, "utf8"))
+            : await context.readRequirements(livingPath));
+    return {
+        reqs,
+        living,
+        issues: [
+            ...deltaDocumentIssues(scope, raw, reqs),
+            ...livingDocumentIssues(scope, living),
+            ...(await selectionIssues(scope, reqs, living, claims)),
+        ],
+    };
+}
+//# sourceMappingURL=delta.js.map

package/dist/core/delta/delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../../src/core/delta/delta.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Does the diff apply to the thing it claims to change?\n *\n * A requirement delta is a diff against a living spec, and nothing used to check\n * that it lands. Every failure mode here is silent today: MODIFIED of a\n * requirement that does not exist is merged as a creation, ADDED of one that\n * does exist REPLACES it (scenarios and all) while the author believes they are\n * adding, and a heading that nearly matches the delta grammar parses as plain\n * prose so archive merges nothing at all and says nothing about it.\n *\n * The last of those has a legal-looking cousin: a requirement under an ordinary\n * prose heading (`## Behavior`, `## Error Handling`) is BASE too, and BASE never\n * merges. Upstream OpenSpec deltas are written that way, so the answer is to name\n * what will be lost rather than to start merging prose sections.\n *\n * These run inside the archive gate, because the merge is where the damage lands.\n *\n * TWO CORPORA, ONE ALGEBRA. A feature's delta documents live in two places —\n * `specs/<svc>/{spec,arch.spec}.md` against the service tree, and\n * `capabilities/<id>/spec.md` against the authored business tree — and every\n * grade about a DOCUMENT and its living counterpart applies to both verbatim,\n * with the capability id in `subject` where a service id would be. That is not\n * a coincidence to exploit but the reason the business corpus was given deltas\n * at all: a capability document is a requirements document, so the diff that\n * changes one has exactly the same ways of not landing. A second implementation\n * would be a second set of answers to `delta.added-duplicate`.\n *\n * The exception is the four CROSS-FEATURE warnings — `delta.added-conflict`,\n * `delta.modified-conflict`, `delta.modified-pending`, `delta.removed-pending`\n * — which ask what OTHER features in flight claim. `./claims.ts` indexes the\n * service corpus only and states why; on the business axis those four are\n * silent, which is a missing warning and never a wrong answer.\n *\n * This module is only the walk: which documents get read, in what order, and how\n * each is handed a `DeltaScope`. The checks themselves are in `./document.ts`\n * (a document against itself) and `./select.ts` (the delta against the living\n * text). Their order is load-bearing and stays here, where it can be read in one\n * screen.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { type FleetContext } from \"../fleet-context.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../repo/paths.js\";\nimport { featureUseCasesDir, livingCapabilityPaths } from \"../repo/authored/paths.js\";\nimport { readCapabilityVocabulary } from \"../capabilities/capabilities.js\";\n\nimport { flowCoverage, type FlowPromises } from \"../usecases/delta/claims.js\";\nimport { enumeratedServiceIds, locateServicePaths } from \"../repo/service-target.js\";\nimport { featureSpecServices } from \"../repo/repo.js\";\nimport { capabilityDocIssues } from \"../capabilities/delta/doc.js\";\nimport { featureCapabilityDeltas } from \"../capabilities/delta/tree.js\";\nimport {\n  removedRealizedIssues,\n  uncoveredIssues,\n  type CapabilityDeltaDoc,\n  type RealizingDoc,\n} from \"../capabilities/delta/uncovered.js\";\nimport { type Issue } from \"../vocabulary/issue.js\";\nimport { claimLookup, type ClaimLookup } from \"./claims.js\";\nimport { deltaDocumentIssues, livingDocumentIssues } from \"./document.js\";\nimport { indexLiving, type DeltaScope, type LivingIndex } from \"./scope.js\";\nimport { selectionIssues } from \"./select.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The business corpus's ONE axis. A capability document carries the promise and\n * nothing else — there is no `arch.spec.md` beside it, because \"how it is\n * built\" is precisely the altitude a capability requirement may not describe\n * (`capability.requirement-service-scoped` is that rule). It has no `key`\n * because it indexes no `ServicePaths`, which is why `DeltaScope.axis` is the\n * narrower `DeltaAxis` and not `SpecAxis`.\n */\nconst CAPABILITY_AXIS = { file: \"spec.md\" };\n\n/**\n * What every document in one feature's walk shares.\n *\n * A record rather than two more parameters because both values are about the\n * WALK and not about the document being graded — `gradeDelta` would otherwise\n * read as a four-argument function whose last two arguments never vary within\n * a run, which is how the next value gets added as a fifth.\n */\ninterface DeltaReads {\n  /** What OTHER features in flight claim — lazy, so the common case never scans. */\n  claims: ClaimLookup;\n  /** The invocation's read index, when the caller threaded one. */\n  context?: FleetContext;\n}\n\nexport async function deltaShapeIssues(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  context?: FleetContext,\n): Promise<Issue[]> {\n  const issues: Issue[] = [];\n  const services = await featureSpecServices(featureDir, context);\n  // One `existsSync` for a feature that carries no capability delta, which is\n  // every feature in a fleet that has not adopted the business axis.\n  const capabilities =\n    context === undefined ? await featureCapabilityDeltas(featureDir) : await context.featureCapabilityDeltas(featureDir);\n  // The flows this feature brings, and one `existsSync` for a feature that\n  // brings none — which is every feature in a fleet that has not adopted the\n  // axis. The directory, not the documents: what is needed here is whether to\n  // pay for the overlay at all, and the walk that lists them happens once,\n  // inside it.\n  const hasFlows = existsSync(featureUseCasesDir(featureDir));\n  // The early return must ask about EVERY corpus. Asking only about services\n  // meant a capability-only feature — a business change with no service touched\n  // yet, which is exactly what an analyst writes first — was graded by nothing\n  // and archived whatever its delta said; asking only about those two would do\n  // the same to a feature whose whole content is a cross-service flow, which is\n  // the shape an architect answers an analyst with.\n  if (services.length === 0 && capabilities.docs.length === 0 && !hasFlows) return issues;\n\n  // What OTHER features in flight claim. Only built when a claim has to be\n  // checked — the common case never pays for the scan.\n  const reads: DeltaReads = {\n    claims: claimLookup(docsDir, featureId, context),\n    ...(context === undefined ? {} : { context }),\n  };\n\n  // The two corpora's parsed requirements, kept as the walk produces them so\n  // the `Realizes:` join below can be taken without re-reading a byte. That\n  // join is the one question neither corpus can answer alone — which service\n  // requirement keeps which business promise — and this is the only place in\n  // loam where both sides are already open (`capabilities/delta/uncovered.ts`\n  // holds the rules; nothing here decides anything).\n  const serviceDeltas: RealizingDoc[] = [];\n  const capabilityDeltas: CapabilityDeltaDoc[] = [];\n\n  // Both requirement-carrying files per service run the same checks — one code\n  // path parameterized by filename, the merge's own factoring. `where` names\n  // the arch file in messages so a finding cannot be chased into the wrong\n  // document; spec.md keeps its historical spelling.\n  for (const service of services) {\n    for (const axis of SPEC_AXES) {\n      const specPath = featureSpecPaths(featureDir, service)[axis.key];\n      if (!existsSync(specPath)) continue;\n      const scope: DeltaScope = {\n        kind: \"service\",\n        subject: service,\n        axis,\n        featureId,\n        docsDir,\n        specPath,\n        where: axis.key === \"spec\" ? service : `${service} (arch.spec.md)`,\n        // How the axis's living document is named in messages — spec.md keeps\n        // the historical \"living spec\", the arch axis says which file it means.\n        livingDoc: axis.key === \"spec\" ? \"living spec\" : \"living arch.spec.md\",\n      };\n      const graded = await gradeDelta(scope, (await locateServicePaths(docsDir, service, context))[axis.key], reads);\n      issues.push(...graded.issues);\n      serviceDeltas.push({ service, file: axis.file, reqs: graded.reqs });\n    }\n  }\n\n  for (const doc of capabilities.docs) {\n    const scope: DeltaScope = {\n      kind: \"capability\",\n      subject: doc.id,\n      axis: CAPABILITY_AXIS,\n      featureId,\n      docsDir,\n      specPath: doc.spec,\n      // `capability <id>`, not `capabilities/<id>` — the second reads as the\n      // LIVING directory, and every message this labels is about the FEATURE's\n      // delta of it. Sending an author to edit the wrong one of two files with\n      // the same name is the whole reason `where` and `livingDoc` are separate.\n      where: `capability ${doc.id}`,\n      livingDoc: `living capabilities/${doc.id}/spec.md`,\n    };\n    // Absent is a real and ordinary answer on this axis: the first feature to\n    // mention a capability is what creates its living document, so the whole\n    // delta grades against `[]` and every requirement in it is legitimately an\n    // addition.\n    const graded = await gradeDelta(scope, livingCapabilityPaths(docsDir, doc.id).spec, reads);\n    issues.push(...graded.issues);\n    // The document's own three rules, on the requirements this delta would\n    // MERGE — before the merge, where the author can still fix them. See\n    // `capabilities/delta/doc.ts` for why grading only the living copy leaves a\n    // hole straight through the altitude rule.\n    issues.push(\n      ...capabilityDocIssues(graded.reqs, {\n        where: relative(docsDir, doc.spec).split(/[\\\\/]/).join(\"/\"),\n        subject: doc.id,\n      }),\n    );\n    capabilityDeltas.push({ id: doc.id, reqs: graded.reqs, living: graded.living.all });\n  }\n\n  // The other carrier of a promise, read once and only when this feature\n  // actually brings a flow: the `dynamic view`s under `features/<FEAT>/usecases/`,\n  // parsed over the map this feature's own merge would leave behind\n  // (`core/usecases/delta/overlay.ts`).\n  // A feature with no `usecases/` directory is a REAL empty answer, not an\n  // ungraded one: there is no flow, so \"no flow keeps this\" is true and the\n  // message may say it.\n  const kept: FlowPromises = hasFlows\n    ? await flowCoverage({\n        docsDir,\n        featureDir,\n        featureId,\n        capabilities: capabilityDeltas,\n        // Read HERE, through the invocation's index, because this module holds\n        // it and `core/usecases/` does not — every other read in this walk does\n        // the same, and `core/repo/service-target.ts` prices a fleet\n        // enumeration per call at ~13 ms on a 120-service fleet.\n        vocabulary: context === undefined ? await readCapabilityVocabulary(docsDir) : await context.capabilities(docsDir),\n        known: new Set(await enumeratedServiceIds(docsDir, context)),\n        // A function rather than the context itself: one memoised LikeC4 read\n        // does not justify an edge from `core/usecases/` to `fleet-context`, and\n        // the edge would push that package up a DAG level for nothing.\n        ...(context === undefined ? {} : { load: (path: string) => context.loadLikeC4(path) }),\n      })\n    : { kind: \"read\", kept: [] };\n  if (kept.kind === \"unreadable\") {\n    // ERROR, and the archive gate's own `NEVER_OVERRIDABLE` keeps `--approve`\n    // off it. This is the refusal that stops a flow being copied into\n    // `architecture/` and the NEXT reader's `loam validate --all` carrying the\n    // failure — including the case the overlay exists for, a hop naming an\n    // element the merge does not land. Mechanical, so it is not loam's judgement\n    // to override.\n    issues.push({\n      severity: \"error\",\n      code: \"usecase.flow-invalid\",\n      subject: featureId,\n      // The opening sentence does NOT say whose file is at fault, and that is\n      // deliberate: the corpus this reads is the feature's flows PLUS the living\n      // `architecture/` documents they are drawn over, so the failing path can\n      // be a living one — a landscape that no longer parses, a use case somebody\n      // else wrote. Every message carries its own path, so a reader can place\n      // it; an opening line that blamed `usecases/` would send them to the wrong\n      // file first.\n      message:\n        `this feature's flows could not be graded against the map its own merge would leave behind, so the archive ` +\n        `would land an architecture/ nothing has checked. The corpus is the feature's usecases/ AND the living ` +\n        `architecture/ documents they are drawn over, so the fault may be in either — each message names its file. ` +\n        `${kept.errors.length} problem(s): ${kept.errors.join(\"; \")}`,\n    });\n  }\n\n  // The `Realizes:` join, both directions, over documents this walk has already\n  // parsed. Skipped entirely when the feature carries no capability delta,\n  // which is every feature in a fleet that has not adopted the business axis —\n  // and the removal half asks for the living corpus only when something is\n  // actually retired, so even an adopting fleet pays the fleet-wide read on the\n  // features that earn it.\n  if (capabilityDeltas.length > 0) {\n    // The three arms travel as three, and flattening two of them to `[]` is\n    // the one thing this must not do: `capability.uncovered` says in words that\n    // no flow keeps the promise, so handing it an empty list for a corpus loam\n    // could not read or could not resolve makes it assert a negative it never\n    // evaluated — and gate on it. `claims.ts`'s header states the rule; this is\n    // where a caller could break it.\n    issues.push(\n      ...uncoveredIssues(\n        capabilityDeltas,\n        serviceDeltas,\n        kept.kind === \"read\"\n          ? { graded: true, kept: kept.kept }\n          : { graded: false, why: kept.kind === \"ungraded\" ? kept.why : kept.errors.join(\"; \") },\n      ),\n    );\n    issues.push(\n      ...(await removedRealizedIssues({\n        capabilities: capabilityDeltas,\n        deltas: serviceDeltas,\n        living: () => livingRealizers(docsDir, context),\n      })),\n    );\n  }\n\n  return issues;\n}\n\n/**\n * Every LIVING service requirements document in the fleet, for the one question\n * that has to ask about services this feature never mentions: does anything out\n * there still realize a capability requirement this feature retires?\n *\n * The same shape and the same cost `openapi.remove-op-consumed` pays through\n * `coherence/lookups.ts` one axis over, and for the same reason — the merge\n * deletes the promise while the `Realizes:` line stays, so the very next\n * `validate --all` reports a breach on a repository whose author was never in\n * this feature. Called behind a thunk (`removedRealizedIssues` invokes it only\n * when something is retired), so a feature that removes nothing never runs it.\n */\nasync function livingRealizers(docsDir: DocsDir, context?: FleetContext): Promise<RealizingDoc[]> {\n  const out: RealizingDoc[] = [];\n  for (const service of await enumeratedServiceIds(docsDir, context)) {\n    const paths = await locateServicePaths(docsDir, service, context);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      const reqs =\n        context === undefined ? parseRequirements(await readFile(path, \"utf8\")) : await context.readRequirements(path);\n      out.push({ service, file: axis.file, reqs });\n    }\n  }\n  return out;\n}\n\n/**\n * One delta document against one living document: the three passes, in the\n * order that makes their messages readable.\n *\n * The order is load-bearing. `deltaDocumentIssues` settles what the delta says\n * about itself, `livingDocumentIssues` settles whether the living text can be\n * selected in at all, and only then does `selectionIssues` compare them — a pin\n * the document pass already refused must not also be reported stale, which\n * would send its author to `loam rebase` for a problem rebase does not fix.\n *\n * The parsed delta requirements come back with the issues because the capability\n * corpus grades them a second way (`capabilityDocIssues`) and re-reading the\n * file to do it would be a second parse of bytes already in hand — and, without\n * a context, a second chance for the two passes to disagree about the document.\n * The LIVING index rides back for the same reason once more: the removal\n * direction of the `Realizes:` join has to resolve a REMOVED spelled by heading\n * into the id it retires, and that id is a fact about the living document.\n */\nasync function gradeDelta(\n  scope: DeltaScope,\n  livingPath: string,\n  reads: DeltaReads,\n): Promise<{ issues: Issue[]; reqs: Requirement[]; living: LivingIndex }> {\n  const { claims, context } = reads;\n  const raw = context === undefined ? await readFile(scope.specPath, \"utf8\") : await context.readText(scope.specPath);\n  const reqs = context === undefined ? parseRequirements(raw) : await context.readRequirements(scope.specPath);\n  const living = indexLiving(\n    !existsSync(livingPath)\n      ? []\n      : context === undefined\n        ? parseRequirements(await readFile(livingPath, \"utf8\"))\n        : await context.readRequirements(livingPath),\n  );\n  return {\n    reqs,\n    living,\n    issues: [\n      ...deltaDocumentIssues(scope, raw, reqs),\n      ...livingDocumentIssues(scope, living),\n      ...(await selectionIssues(scope, reqs, living, claims)),\n    ],\n  };\n}\n"]}

package/dist/core/delta/document.js

@@ -0,0 +1,177 @@
+/**
+ * What a requirements document says about ITSELF — graded before anything is
+ * compared against another document.
+ *
+ * Both the delta and the living spec come through here, because the failures are
+ * the same class: a heading that nearly matches the delta grammar, an identity
+ * declared twice or shared by two requirements, a `Based-On:` nobody can
+ * evaluate. Settling them first is what lets `./select.ts` assume the two
+ * documents are at least internally answerable — a pin the document pass already
+ * refused must not also be reported stale, which would send its author to
+ * `loam rebase` for a problem rebase does not fix.
+ */
+import { relative } from "node:path";
+import {} from "../vocabulary/issue.js";
+import { sectionHeadings } from "../document/parse.js";
+import { basedOnDeclarations, KIND_RE, REQUIREMENT_DIGEST_LENGTH, REQUIREMENT_DIGEST_RE, requirementIdProblems, } from "../document/spec.js";
+import {} from "./scope.js";
+/**
+ * `## <word> Requirement(s)` — the shape an author reaches for. Anything matching
+ * this but not the real grammar is a near miss: `## ADDED Requirement` (singular),
+ * `## NEW Requirements`, `## ADDED Requirements:`. A bare `## Requirements` is not
+ * a near miss — quoting the living state inside a delta is legal.
+ */
+const NEAR_SECTION_RE = /^##\s+[A-Za-z]+\s+Requirements?\s*:?\s*$/i;
+/**
+ * OpenSpec's fourth delta operation. NEAR_SECTION_RE already catches it, but the
+ * generic advice would mislead: a RENAMED body is FROM/TO backtick bullets, not
+ * `### Requirement:` headings, so it parses to zero requirements and even the
+ * whole-file check below has nothing to count — the heading is the only place to
+ * stop it. Rename semantics stay unimplemented (the corpus never uses them); the
+ * error says what to write instead.
+ */
+const RENAMED_SECTION_RE = /^##\s+RENAMED\s+Requirements?\s*:?\s*$/i;
+// The one non-delta heading whose requirements are SUPPOSED not to merge — a
+// delta quoting the living state for context — is `## Requirements`, matched by
+// the shared isRequirementsHeading (spec.ts): the same definition that fixes
+// archive's rewrite boundary, so "legal to quote" and "where the merge writes"
+// cannot drift apart. Every other heading — `## Behavior`, `## Error Handling`,
+// `## Notes` — leaves its requirements as BASE, which the merge skips, so the
+// author wrote a change that will never land.
+/** Everything wrong with the DELTA document on its own terms. */
+export function deltaDocumentIssues(scope, raw, reqs) {
+    const { docsDir, subject, specPath, where } = scope;
+    const issues = [];
+    for (const heading of sectionHeadings(raw)) {
+        if (KIND_RE.test(heading.text) || !NEAR_SECTION_RE.test(heading.text))
+            continue;
+        issues.push({
+            severity: "error",
+            code: "delta.unknown-section",
+            subject,
+            message: RENAMED_SECTION_RE.test(heading.text)
+                ? `${where}: '${heading.text}' (line ${heading.line}) is OpenSpec rename syntax, which loam does not merge — carry one stable Requirement-ID through a MODIFIED requirement, or express a legacy rename as a REMOVED requirement plus an ADDED one; otherwise the rename happens to nothing`
+                : `${where}: '${heading.text}' (line ${heading.line}) is not a delta section — use '## ADDED Requirements', '## MODIFIED Requirements' or '## REMOVED Requirements', or everything under it merges as nothing`,
+        });
+    }
+    for (const problem of requirementIdProblems(reqs)) {
+        if (problem.kind === "invalid") {
+            issues.push({
+                severity: "error",
+                code: "delta.requirement-id-invalid",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}' — use 1-128 characters matching [A-Za-z][A-Za-z0-9._-]*`,
+            });
+        }
+        else if (problem.kind === "repeated") {
+            issues.push({
+                severity: "error",
+                code: "delta.requirement-id-repeated",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' declares Requirement-ID ${problem.values.length} times — identity must be declared exactly once`,
+            });
+        }
+        else {
+            issues.push({
+                severity: "error",
+                code: "delta.requirement-id-duplicate",
+                subject,
+                message: `${where}: Requirement-ID '${problem.id}' is shared by ${problem.requirements.map((name) => `'${name}'`).join(", ")} — one ID may identify only one requirement`,
+            });
+        }
+    }
+    // The `Based-On:` pin as a DOCUMENT question, settled before anything is
+    // compared against the living spec: a value that is not a digest, or two
+    // of them on one requirement, is a pin nobody can evaluate — and a pin
+    // that silently protects nothing is worse than no pin at all, because its
+    // author believes they are covered. ADDED is refused for the same reason
+    // rather than ignored: a requirement with no living version cannot have
+    // been written against one, so the line is a misunderstanding today and a
+    // digest-shaped lie on the day someone turns it into a MODIFIED.
+    for (const r of reqs) {
+        const declared = basedOnDeclarations(r);
+        if (declared.length > 1) {
+            issues.push({
+                severity: "error",
+                code: "delta.baseline-invalid",
+                subject,
+                message: `${where}: requirement '${r.name}' declares Based-On ${declared.length} times — a delta is written against exactly one living version`,
+            });
+            continue;
+        }
+        const pin = declared[0];
+        if (pin === undefined)
+            continue;
+        if (!REQUIREMENT_DIGEST_RE.test(pin)) {
+            issues.push({
+                severity: "error",
+                code: "delta.baseline-invalid",
+                subject,
+                message: `${where}: requirement '${r.name}' has invalid Based-On '${pin}' — expected ${REQUIREMENT_DIGEST_LENGTH} lowercase hex characters, as \`loam rebase\` writes them`,
+            });
+        }
+        else if (r.kind === "ADDED") {
+            issues.push({
+                severity: "error",
+                code: "delta.baseline-invalid",
+                subject,
+                message: `${where}: ADDED requirement '${r.name}' carries Based-On '${pin}', but an added requirement has no living version to be based on — drop the line, or make it MODIFIED`,
+            });
+        }
+    }
+    // The whole-file version of the near-miss check, and the one that cannot be
+    // dodged: NEAR_SECTION_RE only recognizes single-word misses (`## NEW
+    // Requirements`), so `## NEWLY ADDED Requirements` — or requirements under a
+    // prose heading, or under no heading at all — still parses everything as BASE
+    // and archive merges nothing, silently. Same failure class as the BOM incident
+    // (see spec.ts). A file that MIXES delta sections with quoted BASE requirements
+    // is legal authoring; a file with requirements and no delta kind anywhere is a
+    // delta that would do nothing, which cannot be what its author meant.
+    if (reqs.length > 0 && reqs.every((r) => r.kind === "BASE")) {
+        const rel = relative(docsDir, specPath).split(/[\\/]/).join("/");
+        issues.push({
+            severity: "error",
+            code: "delta.no-delta-sections",
+            subject,
+            message: `${subject}: ${rel} contains ${reqs.length} requirement(s) but no '## ADDED|MODIFIED|REMOVED Requirements' section — this delta would merge nothing`,
+        });
+    }
+    return issues;
+}
+/** Everything wrong with the LIVING document that stops a delta selecting in it. */
+export function livingDocumentIssues(scope, living) {
+    const { subject, where, livingDoc } = scope;
+    const issues = [];
+    for (const problem of requirementIdProblems(living.all)) {
+        issues.push({
+            severity: "error",
+            code: "delta.living-requirement-id-invalid",
+            subject,
+            message: problem.kind === "invalid"
+                ? `${where}: the ${livingDoc} requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}', so this delta cannot select it safely`
+                : problem.kind === "repeated"
+                    ? `${where}: the ${livingDoc} requirement '${problem.requirement}' declares Requirement-ID more than once, so this delta cannot select it safely`
+                    : `${where}: the ${livingDoc} shares Requirement-ID '${problem.id}' across ${problem.requirements.map((name) => `'${name}'`).join(", ")}, so this delta cannot select one safely`,
+        });
+    }
+    // Two living requirements under one heading make the delta algebra
+    // disagree with itself on the SAME input: MODIFIED replaces the first
+    // match (findIndex) while REMOVED deletes every match (filter). So one
+    // delta edits one of the twins and leaves the other, and the next one
+    // deletes both — and neither outcome is what an author reading the
+    // living document could have predicted. Gating rather than advisory,
+    // because there is no reading of the delta that makes the merge correct;
+    // the fix is in the living document, and it is one rename.
+    for (const [name, twins] of living.byName) {
+        if (twins.length < 2)
+            continue;
+        issues.push({
+            severity: "error",
+            code: "delta.living-duplicate-requirement",
+            subject,
+            message: `${where}: the ${livingDoc} declares ${twins.length} requirements named '${name}' — MODIFIED would rewrite only the first and REMOVED would delete both, so no delta applies to it predictably. Give them distinct names (or distinct Requirement-IDs and headings) first.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=document.js.map

package/dist/core/delta/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../../src/core/delta/document.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a requirements document says about ITSELF — graded before anything is\n * compared against another document.\n *\n * Both the delta and the living spec come through here, because the failures are\n * the same class: a heading that nearly matches the delta grammar, an identity\n * declared twice or shared by two requirements, a `Based-On:` nobody can\n * evaluate. Settling them first is what lets `./select.ts` assume the two\n * documents are at least internally answerable — a pin the document pass already\n * refused must not also be reported stale, which would send its author to\n * `loam rebase` for a problem rebase does not fix.\n */\nimport { relative } from \"node:path\";\nimport { type Issue } from \"../vocabulary/issue.js\";\nimport { sectionHeadings } from \"../document/parse.js\";\nimport {\n  basedOnDeclarations,\n  KIND_RE,\n  REQUIREMENT_DIGEST_LENGTH,\n  REQUIREMENT_DIGEST_RE,\n  requirementIdProblems,\n  type Requirement,\n} from \"../document/spec.js\";\nimport { type DeltaScope, type LivingIndex } from \"./scope.js\";\n\n/**\n * `## <word> Requirement(s)` — the shape an author reaches for. Anything matching\n * this but not the real grammar is a near miss: `## ADDED Requirement` (singular),\n * `## NEW Requirements`, `## ADDED Requirements:`. A bare `## Requirements` is not\n * a near miss — quoting the living state inside a delta is legal.\n */\nconst NEAR_SECTION_RE = /^##\\s+[A-Za-z]+\\s+Requirements?\\s*:?\\s*$/i;\n\n/**\n * OpenSpec's fourth delta operation. NEAR_SECTION_RE already catches it, but the\n * generic advice would mislead: a RENAMED body is FROM/TO backtick bullets, not\n * `### Requirement:` headings, so it parses to zero requirements and even the\n * whole-file check below has nothing to count — the heading is the only place to\n * stop it. Rename semantics stay unimplemented (the corpus never uses them); the\n * error says what to write instead.\n */\nconst RENAMED_SECTION_RE = /^##\\s+RENAMED\\s+Requirements?\\s*:?\\s*$/i;\n\n// The one non-delta heading whose requirements are SUPPOSED not to merge — a\n// delta quoting the living state for context — is `## Requirements`, matched by\n// the shared isRequirementsHeading (spec.ts): the same definition that fixes\n// archive's rewrite boundary, so \"legal to quote\" and \"where the merge writes\"\n// cannot drift apart. Every other heading — `## Behavior`, `## Error Handling`,\n// `## Notes` — leaves its requirements as BASE, which the merge skips, so the\n// author wrote a change that will never land.\n\n/** Everything wrong with the DELTA document on its own terms. */\nexport function deltaDocumentIssues(scope: DeltaScope, raw: string, reqs: Requirement[]): Issue[] {\n  const { docsDir, subject, specPath, where } = scope;\n  const issues: Issue[] = [];\n  for (const heading of sectionHeadings(raw)) {\n    if (KIND_RE.test(heading.text) || !NEAR_SECTION_RE.test(heading.text)) continue;\n    issues.push({\n      severity: \"error\",\n      code: \"delta.unknown-section\",\n      subject,\n      message: RENAMED_SECTION_RE.test(heading.text)\n        ? `${where}: '${heading.text}' (line ${heading.line}) is OpenSpec rename syntax, which loam does not merge — carry one stable Requirement-ID through a MODIFIED requirement, or express a legacy rename as a REMOVED requirement plus an ADDED one; otherwise the rename happens to nothing`\n        : `${where}: '${heading.text}' (line ${heading.line}) is not a delta section — use '## ADDED Requirements', '## MODIFIED Requirements' or '## REMOVED Requirements', or everything under it merges as nothing`,\n    });\n  }\n\n  for (const problem of requirementIdProblems(reqs)) {\n    if (problem.kind === \"invalid\") {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.requirement-id-invalid\",\n        subject,\n        message: `${where}: requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}' — use 1-128 characters matching [A-Za-z][A-Za-z0-9._-]*`,\n      });\n    } else if (problem.kind === \"repeated\") {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.requirement-id-repeated\",\n        subject,\n        message: `${where}: requirement '${problem.requirement}' declares Requirement-ID ${problem.values.length} times — identity must be declared exactly once`,\n      });\n    } else {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.requirement-id-duplicate\",\n        subject,\n        message: `${where}: Requirement-ID '${problem.id}' is shared by ${problem.requirements.map((name) => `'${name}'`).join(\", \")} — one ID may identify only one requirement`,\n      });\n    }\n  }\n\n  // The `Based-On:` pin as a DOCUMENT question, settled before anything is\n  // compared against the living spec: a value that is not a digest, or two\n  // of them on one requirement, is a pin nobody can evaluate — and a pin\n  // that silently protects nothing is worse than no pin at all, because its\n  // author believes they are covered. ADDED is refused for the same reason\n  // rather than ignored: a requirement with no living version cannot have\n  // been written against one, so the line is a misunderstanding today and a\n  // digest-shaped lie on the day someone turns it into a MODIFIED.\n  for (const r of reqs) {\n    const declared = basedOnDeclarations(r);\n    if (declared.length > 1) {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.baseline-invalid\",\n        subject,\n        message: `${where}: requirement '${r.name}' declares Based-On ${declared.length} times — a delta is written against exactly one living version`,\n      });\n      continue;\n    }\n    const pin = declared[0];\n    if (pin === undefined) continue;\n    if (!REQUIREMENT_DIGEST_RE.test(pin)) {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.baseline-invalid\",\n        subject,\n        message: `${where}: requirement '${r.name}' has invalid Based-On '${pin}' — expected ${REQUIREMENT_DIGEST_LENGTH} lowercase hex characters, as \\`loam rebase\\` writes them`,\n      });\n    } else if (r.kind === \"ADDED\") {\n      issues.push({\n        severity: \"error\",\n        code: \"delta.baseline-invalid\",\n        subject,\n        message: `${where}: ADDED requirement '${r.name}' carries Based-On '${pin}', but an added requirement has no living version to be based on — drop the line, or make it MODIFIED`,\n      });\n    }\n  }\n\n  // The whole-file version of the near-miss check, and the one that cannot be\n  // dodged: NEAR_SECTION_RE only recognizes single-word misses (`## NEW\n  // Requirements`), so `## NEWLY ADDED Requirements` — or requirements under a\n  // prose heading, or under no heading at all — still parses everything as BASE\n  // and archive merges nothing, silently. Same failure class as the BOM incident\n  // (see spec.ts). A file that MIXES delta sections with quoted BASE requirements\n  // is legal authoring; a file with requirements and no delta kind anywhere is a\n  // delta that would do nothing, which cannot be what its author meant.\n  if (reqs.length > 0 && reqs.every((r) => r.kind === \"BASE\")) {\n    const rel = relative(docsDir, specPath).split(/[\\\\/]/).join(\"/\");\n    issues.push({\n      severity: \"error\",\n      code: \"delta.no-delta-sections\",\n      subject,\n      message: `${subject}: ${rel} contains ${reqs.length} requirement(s) but no '## ADDED|MODIFIED|REMOVED Requirements' section — this delta would merge nothing`,\n    });\n  }\n  return issues;\n}\n\n/** Everything wrong with the LIVING document that stops a delta selecting in it. */\nexport function livingDocumentIssues(scope: DeltaScope, living: LivingIndex): Issue[] {\n  const { subject, where, livingDoc } = scope;\n  const issues: Issue[] = [];\n  for (const problem of requirementIdProblems(living.all)) {\n    issues.push({\n      severity: \"error\",\n      code: \"delta.living-requirement-id-invalid\",\n      subject,\n      message:\n        problem.kind === \"invalid\"\n          ? `${where}: the ${livingDoc} requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}', so this delta cannot select it safely`\n          : problem.kind === \"repeated\"\n            ? `${where}: the ${livingDoc} requirement '${problem.requirement}' declares Requirement-ID more than once, so this delta cannot select it safely`\n            : `${where}: the ${livingDoc} shares Requirement-ID '${problem.id}' across ${problem.requirements.map((name) => `'${name}'`).join(\", \")}, so this delta cannot select one safely`,\n    });\n  }\n\n  // Two living requirements under one heading make the delta algebra\n  // disagree with itself on the SAME input: MODIFIED replaces the first\n  // match (findIndex) while REMOVED deletes every match (filter). So one\n  // delta edits one of the twins and leaves the other, and the next one\n  // deletes both — and neither outcome is what an author reading the\n  // living document could have predicted. Gating rather than advisory,\n  // because there is no reading of the delta that makes the merge correct;\n  // the fix is in the living document, and it is one rename.\n  for (const [name, twins] of living.byName) {\n    if (twins.length < 2) continue;\n    issues.push({\n      severity: \"error\",\n      code: \"delta.living-duplicate-requirement\",\n      subject,\n      message: `${where}: the ${livingDoc} declares ${twins.length} requirements named '${name}' — MODIFIED would rewrite only the first and REMOVED would delete both, so no delta applies to it predictably. Give them distinct names (or distinct Requirement-IDs and headings) first.`,\n    });\n  }\n  return issues;\n}\n"]}

package/dist/core/delta/scope.js

@@ -0,0 +1,48 @@
+/**
+ * The one (subject, axis) pass every delta check runs inside, and the living
+ * document indexed the way those checks ask about it.
+ *
+ * The scope exists because the checks that used to be one 400-line function all
+ * need the same five facts and none of them may take five parameters. It is a
+ * record of what is being graded, never of what was found — `Issue[]` stays a
+ * return value, so no check can quietly append to another's output.
+ *
+ * `indexLiving` builds all four lookups in one walk. Two of them answer the same
+ * question by different keys (heading, Requirement-ID) and the delta algebra
+ * requires them to agree; building one lazily beside the other is how they would
+ * eventually be built from different arrays.
+ */
+import {} from "../document/spec.js";
+export function indexLiving(living) {
+    const byName = new Map();
+    const byId = new Map();
+    for (const requirement of living) {
+        const named = byName.get(requirement.name) ?? [];
+        named.push(requirement);
+        byName.set(requirement.name, named);
+        if (requirement.id !== undefined) {
+            const identified = byId.get(requirement.id) ?? [];
+            identified.push(requirement);
+            byId.set(requirement.id, identified);
+        }
+    }
+    return {
+        names: new Set(living.map((r) => r.name)),
+        byName,
+        byId,
+        folded: new Map(living.map((r) => [r.name.toLowerCase(), r.name])),
+        all: living,
+    };
+}
+/** Key for the (kind, subject, axis, requirement) tuple a feature claims. The
+ * axes are separate namespaces on purpose — an arch requirement cannot conflict
+ * with a business requirement of the same name, they merge into different files
+ * — and so are the kinds, for the reason `ClaimSubject` states above. */
+export function key(claim, identity) {
+    return `${claim.kind}\0${claim.subject}\0${claim.axis.file}\0${identity}`;
+}
+/** Stable ID when present; exact heading for a legacy requirement. */
+export function requirementKey(requirement) {
+    return requirement.id === undefined ? `name:${requirement.name}` : `id:${requirement.id}`;
+}
+//# sourceMappingURL=scope.js.map

package/dist/core/delta/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../src/core/delta/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AA2DvD,MAAM,UAAU,WAAW,CAAC,MAAqB;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC9C,KAAK,MAAM,WAAW,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACpC,IAAI,WAAW,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YAClD,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM;QACN,IAAI;QACJ,MAAM,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,CAAU,CAAC,CAAC;QAC3E,GAAG,EAAE,MAAM;KACZ,CAAC;AACJ,CAAC;AAED;;;yEAGyE;AACzE,MAAM,UAAU,GAAG,CAAC,KAAmB,EAAE,QAAgB;IACvD,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;AAC5E,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,cAAc,CAAC,WAA6C;IAC1E,OAAO,WAAW,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,EAAE,EAAE,CAAC;AAC5F,CAAC","sourcesContent":["/**\n * The one (subject, axis) pass every delta check runs inside, and the living\n * document indexed the way those checks ask about it.\n *\n * The scope exists because the checks that used to be one 400-line function all\n * need the same five facts and none of them may take five parameters. It is a\n * record of what is being graded, never of what was found — `Issue[]` stays a\n * return value, so no check can quietly append to another's output.\n *\n * `indexLiving` builds all four lookups in one walk. Two of them answer the same\n * question by different keys (heading, Requirement-ID) and the delta algebra\n * requires them to agree; building one lazily beside the other is how they would\n * eventually be built from different arrays.\n */\nimport { type Requirement } from \"../document/spec.js\";\n\n/**\n * Which file an axis is, at the grain the delta checks need — the filename and\n * nothing else, because that is all any of them read (`key` below is the only\n * consumer). Structurally a `SPEC_AXES` entry with its other fields dropped, so\n * the two service axes keep travelling exactly as before while the CAPABILITY\n * axis — which indexes no `ServicePaths` and therefore has no `key` — travels\n * too. `label` is deliberately NOT carried: nothing here reads it, and a field\n * that exists only to look like the record it came from is a field the next\n * reader tries to use in a message.\n */\nexport interface DeltaAxis {\n  file: string;\n}\n\n/**\n * WHAT a delta claims, at the grain the claim registry is keyed by: the kind of\n * document, its identity, and which of its axes.\n *\n * `kind` is not decoration. A fleet may hold a service called `billing` and a\n * capability called `billing`, and both write requirements into a `spec.md`; a\n * key built from the name and the filename alone would let one feature's\n * service claim answer another feature's capability question — reporting\n * `delta.added-conflict` against a document it has nothing to do with.\n */\nexport interface ClaimSubject {\n  kind: \"service\" | \"capability\";\n  /** The service id, or the capability id — whichever `kind` says. */\n  subject: string;\n  axis: DeltaAxis;\n}\n\nexport interface DeltaScope extends ClaimSubject {\n  /** The feature being graded — named in the `loam rebase <FEAT>` advice. */\n  featureId: string;\n  docsDir: string;\n  /** The delta document this pass reads, for the one message that names a path. */\n  specPath: string;\n  /**\n   * How this axis's file is named in messages. The arch file says which document\n   * it means so a finding cannot be chased into the wrong one; spec.md keeps its\n   * historical spelling.\n   */\n  where: string;\n  /** How the axis's LIVING document is named in messages, same reasoning. */\n  livingDoc: string;\n}\n\n/** The living requirements, keyed every way a delta may select one. */\nexport interface LivingIndex {\n  names: Set<string>;\n  byName: Map<string, Requirement[]>;\n  byId: Map<string, Requirement[]>;\n  /** Lowercased living name -> its exact spelling, for the near-duplicate warning. */\n  folded: Map<string, string>;\n  all: Requirement[];\n}\n\nexport function indexLiving(living: Requirement[]): LivingIndex {\n  const byName = new Map<string, Requirement[]>();\n  const byId = new Map<string, Requirement[]>();\n  for (const requirement of living) {\n    const named = byName.get(requirement.name) ?? [];\n    named.push(requirement);\n    byName.set(requirement.name, named);\n    if (requirement.id !== undefined) {\n      const identified = byId.get(requirement.id) ?? [];\n      identified.push(requirement);\n      byId.set(requirement.id, identified);\n    }\n  }\n  return {\n    names: new Set(living.map((r) => r.name)),\n    byName,\n    byId,\n    folded: new Map(living.map((r) => [r.name.toLowerCase(), r.name] as const)),\n    all: living,\n  };\n}\n\n/** Key for the (kind, subject, axis, requirement) tuple a feature claims. The\n * axes are separate namespaces on purpose — an arch requirement cannot conflict\n * with a business requirement of the same name, they merge into different files\n * — and so are the kinds, for the reason `ClaimSubject` states above. */\nexport function key(claim: ClaimSubject, identity: string): string {\n  return `${claim.kind}\\0${claim.subject}\\0${claim.axis.file}\\0${identity}`;\n}\n\n/** Stable ID when present; exact heading for a legacy requirement. */\nexport function requirementKey(requirement: Pick<Requirement, \"id\" | \"name\">): string {\n  return requirement.id === undefined ? `name:${requirement.name}` : `id:${requirement.id}`;\n}\n"]}