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

package/dist/core/tasks/sources.js

@@ -0,0 +1,181 @@
+/**
+ * The feature's own delta documents, read once: the requirement axes, the join
+ * from a scenario claim back to the words it was minted from, and whether the
+ * architecture and contract documents could be read at all.
+ *
+ * Everything here reads; nothing grades. The readability answers travel beside
+ * the counts for `core/projection/api.ts`'s reason, one axis over: a delta that
+ * does not parse yields an EMPTY change list, which is the same answer as a
+ * delta that genuinely changes nothing — and a packet is consumed as "what is
+ * left to do", where an empty answer over a YAML error reads as "nothing to do".
+ */
+import { existsSync } from "node:fs";
+import { errorText } from "../c4/likec4.js";
+import { repoPath } from "../envelope/json.js";
+import { scenarioBodyHash } from "../gherkin/digest.js";
+import { requirementsMissingScenarios } from "../document/scenarios.js";
+import { apiChanges } from "../projection/api.js";
+import { eventChanges } from "../projection/events.js";
+import { featurePaths, featureSpecPaths, SPEC_AXES } from "../repo/paths.js";
+import { claimId, DIGEST_LENGTH, ID_LENGTH } from "../verify/claims/identity.js";
+import { describedUnitId, doneCheck } from "./unit.js";
+/**
+ * Both spec axes of every service the feature carries a delta for, in the order
+ * `core/verify/checklist.ts` walks them — service-major, `spec.md` before
+ * `arch.spec.md`. The order is load-bearing rather than tidy: it is what makes
+ * the recomputed claim ids below land on the same occurrence counters the
+ * checklist minted.
+ */
+export async function readDeltaAxes(docsDir, featureDir, services, context) {
+    const out = [];
+    for (const service of services) {
+        const paths = featureSpecPaths(featureDir, service);
+        for (const axis of SPEC_AXES) {
+            const file = paths[axis.key];
+            if (!existsSync(file))
+                continue;
+            out.push({ service, axis, path: repoPath(docsDir, file), requirements: await context.readRequirements(file) });
+        }
+    }
+    return out;
+}
+/**
+ * Every scenario claim's source, keyed by the claim id it will carry.
+ *
+ * THE ID IS THE JOIN, and that is stronger than matching on the digest alone.
+ * A scenario claim's id is `claimId(featureId, "scenario.tested", tuple, seen)`
+ * over a tuple that already contains the requirement's identity, the scenario
+ * name and a prefix of the body hash — so recomputing it from the same walk, in
+ * the same order, with one shared occurrence map, reproduces the checklist's own
+ * answer rather than approximating it. Two identically-worded scenarios under
+ * one requirement share a digest and are still two questions: `claimId`'s `seen`
+ * counter numbers them in DOCUMENT ORDER, and this walk visits them in document
+ * order too, so the nth scenario pairs with the nth claim exactly.
+ *
+ * The digest is carried alongside and checked by the caller before a source is
+ * attached. That is the belt: if this walk and the checklist's ever disagreed
+ * about what a scenario says, the packet must show the unit with NO source
+ * rather than with somebody else's Given/When/Then.
+ *
+ * Only ADDED and MODIFIED requirements, exactly as the checklist does: a BASE
+ * requirement is the living state quoted inside the delta, and a REMOVED one is
+ * being retired. Neither is work anybody has to have done.
+ */
+export function scenarioSources(featureId, axes) {
+    const out = new Map();
+    const seen = new Map();
+    for (const { service, axis, path, requirements } of axes) {
+        const arch = axis.key === "archSpec";
+        for (const requirement of requirements) {
+            if (requirement.kind === "BASE" || requirement.kind === "REMOVED")
+                continue;
+            const identity = requirement.id ?? requirement.name;
+            for (const scenario of requirement.scenarios) {
+                const body = scenarioBodyHash(service, scenario.lines, arch ? "arch" : "business");
+                // The tuple is `core/verify/checklist.ts`'s, part for part — the arch
+                // axis carries `arch.spec.md` as its second element, which is what keeps
+                // two identically-worded scenarios on the two axes two questions.
+                const parts = arch
+                    ? [service, "arch.spec.md", identity, scenario.name, body.slice(0, ID_LENGTH)]
+                    : [service, identity, scenario.name, body.slice(0, ID_LENGTH)];
+                const id = claimId(featureId, "scenario.tested", parts, seen);
+                out.set(id, {
+                    digest: body.slice(0, DIGEST_LENGTH),
+                    source: {
+                        path,
+                        ...(scenario.line === undefined ? {} : { line: scenario.line }),
+                        requirement: requirement.name,
+                        ...(requirement.id === undefined ? {} : { requirementId: requirement.id }),
+                        scenario: scenario.name,
+                        lines: scenario.lines,
+                    },
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The first BDD act, as units: a requirement nobody has written a scenario for.
+ *
+ * `requirementsMissingScenarios` is the coverage rule every other surface
+ * applies — REMOVED requirements are exempt there and stay exempt here, content
+ * on its way out owes no acceptance criteria — so a packet can never disagree
+ * with `loam validate` about which requirements are bare.
+ */
+export function describeUnits(featureId, axes) {
+    const out = [];
+    for (const { service, axis, path, requirements } of axes) {
+        for (const requirement of requirementsMissingScenarios(requirements)) {
+            const id = describedUnitId(featureId, service, axis.file, requirement.id ?? requirement.name);
+            out.push({
+                id,
+                kind: "requirement.described",
+                subject: service,
+                at: "describe",
+                claim: `requirement '${requirement.name}' (${service}, ${axis.file}) has no scenarios` +
+                    " — write the Given/When/Then first",
+                dependsOn: [],
+                source: {
+                    path,
+                    ...(requirement.line === undefined ? {} : { line: requirement.line }),
+                    requirement: requirement.name,
+                    ...(requirement.id === undefined ? {} : { requirementId: requirement.id }),
+                },
+                done: { check: doneCheck({ kind: "requirement.described" }) },
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The two contract axes and the architecture delta, read for their COUNTS and
+ * for whether they could be read.
+ *
+ * The same readers `loam delta` projects through (`apiChanges`/`eventChanges`),
+ * so a packet can never report an operation the brief does not. The
+ * architecture half is read through the invocation's context, which means the
+ * parse is shared with the checklist derivation that has already loaded the same
+ * document — one LikeC4 workspace per invocation rather than two.
+ */
+export async function readContracts(docsDir, featureDir, services, context) {
+    let operations = 0;
+    let messages = 0;
+    const broken = [];
+    for (const service of services) {
+        const paths = featureSpecPaths(featureDir, service);
+        const api = await apiChanges(paths.openapi);
+        const events = await eventChanges(paths.asyncapi);
+        if (api.unreadable || events.unreadable)
+            broken.push(service);
+        operations += api.changes.filter((change) => !change.remove).length;
+        messages += events.changes.filter((change) => !change.remove).length;
+    }
+    const delta = featurePaths(featureDir).delta;
+    let architecture;
+    if (existsSync(delta)) {
+        const loaded = await context.loadLikeC4(delta);
+        // The first error only: the packet says WHICH document could not be read and
+        // why, and a reader who needs the rest runs `loam validate --feature`, whose
+        // job the whole list is.
+        const first = loaded.errors[0];
+        if (first !== undefined)
+            architecture = errorText(first);
+    }
+    return {
+        operations,
+        messages,
+        unreadable: {
+            ...(architecture === undefined ? {} : { architecture }),
+            ...(broken.length === 0 ? {} : { contracts: broken }),
+        },
+    };
+}
+/** How many requirements and scenarios the delta axes hold, whatever their kind. */
+export function axisSize(axes) {
+    return {
+        requirements: axes.reduce((n, a) => n + a.requirements.length, 0),
+        scenarios: axes.reduce((n, a) => n + a.requirements.reduce((m, r) => m + r.scenarios.length, 0), 0),
+    };
+}
+//# sourceMappingURL=sources.js.map

package/dist/core/tasks/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../../src/core/tasks/sources.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The feature's own delta documents, read once: the requirement axes, the join\n * from a scenario claim back to the words it was minted from, and whether the\n * architecture and contract documents could be read at all.\n *\n * Everything here reads; nothing grades. The readability answers travel beside\n * the counts for `core/projection/api.ts`'s reason, one axis over: a delta that\n * does not parse yields an EMPTY change list, which is the same answer as a\n * delta that genuinely changes nothing — and a packet is consumed as \"what is\n * left to do\", where an empty answer over a YAML error reads as \"nothing to do\".\n */\nimport { existsSync } from \"node:fs\";\nimport { errorText } from \"../c4/likec4.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { scenarioBodyHash } from \"../gherkin/digest.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { requirementsMissingScenarios } from \"../document/scenarios.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport { apiChanges } from \"../projection/api.js\";\nimport { eventChanges } from \"../projection/events.js\";\nimport { featurePaths, featureSpecPaths, SPEC_AXES, type SpecAxis } from \"../repo/paths.js\";\nimport { claimId, DIGEST_LENGTH, ID_LENGTH } from \"../verify/claims/identity.js\";\nimport { describedUnitId, doneCheck, type ScenarioSource, type TaskUnit } from \"./unit.js\";\n\n/** One spec axis of one service's delta, parsed. */\nexport interface DeltaAxis {\n  service: string;\n  axis: SpecAxis;\n  /** Repo-relative, for the payload and for a human opening the file. */\n  path: string;\n  requirements: Requirement[];\n}\n\n/**\n * Both spec axes of every service the feature carries a delta for, in the order\n * `core/verify/checklist.ts` walks them — service-major, `spec.md` before\n * `arch.spec.md`. The order is load-bearing rather than tidy: it is what makes\n * the recomputed claim ids below land on the same occurrence counters the\n * checklist minted.\n */\nexport async function readDeltaAxes(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  services: readonly PathableService[],\n  context: FleetContext,\n): Promise<DeltaAxis[]> {\n  const out: DeltaAxis[] = [];\n  for (const service of services) {\n    const paths = featureSpecPaths(featureDir, service);\n    for (const axis of SPEC_AXES) {\n      const file = paths[axis.key];\n      if (!existsSync(file)) continue;\n      out.push({ service, axis, path: repoPath(docsDir, file), requirements: await context.readRequirements(file) });\n    }\n  }\n  return out;\n}\n\n/**\n * A scenario's words, with the digest the claim that owns them must carry. The\n * digest travels beside the source rather than inside it because it is not part\n * of the source — it is the proof that this walk and the checklist's are talking\n * about the same scenario.\n */\nexport interface MintedSource {\n  digest: string;\n  source: ScenarioSource;\n}\n\n/**\n * Every scenario claim's source, keyed by the claim id it will carry.\n *\n * THE ID IS THE JOIN, and that is stronger than matching on the digest alone.\n * A scenario claim's id is `claimId(featureId, \"scenario.tested\", tuple, seen)`\n * over a tuple that already contains the requirement's identity, the scenario\n * name and a prefix of the body hash — so recomputing it from the same walk, in\n * the same order, with one shared occurrence map, reproduces the checklist's own\n * answer rather than approximating it. Two identically-worded scenarios under\n * one requirement share a digest and are still two questions: `claimId`'s `seen`\n * counter numbers them in DOCUMENT ORDER, and this walk visits them in document\n * order too, so the nth scenario pairs with the nth claim exactly.\n *\n * The digest is carried alongside and checked by the caller before a source is\n * attached. That is the belt: if this walk and the checklist's ever disagreed\n * about what a scenario says, the packet must show the unit with NO source\n * rather than with somebody else's Given/When/Then.\n *\n * Only ADDED and MODIFIED requirements, exactly as the checklist does: a BASE\n * requirement is the living state quoted inside the delta, and a REMOVED one is\n * being retired. Neither is work anybody has to have done.\n */\nexport function scenarioSources(featureId: string, axes: readonly DeltaAxis[]): Map<string, MintedSource> {\n  const out = new Map<string, MintedSource>();\n  const seen = new Map<string, number>();\n  for (const { service, axis, path, requirements } of axes) {\n    const arch = axis.key === \"archSpec\";\n    for (const requirement of requirements) {\n      if (requirement.kind === \"BASE\" || requirement.kind === \"REMOVED\") continue;\n      const identity = requirement.id ?? requirement.name;\n      for (const scenario of requirement.scenarios) {\n        const body = scenarioBodyHash(service, scenario.lines, arch ? \"arch\" : \"business\");\n        // The tuple is `core/verify/checklist.ts`'s, part for part — the arch\n        // axis carries `arch.spec.md` as its second element, which is what keeps\n        // two identically-worded scenarios on the two axes two questions.\n        const parts = arch\n          ? [service, \"arch.spec.md\", identity, scenario.name, body.slice(0, ID_LENGTH)]\n          : [service, identity, scenario.name, body.slice(0, ID_LENGTH)];\n        const id = claimId(featureId, \"scenario.tested\", parts, seen);\n        out.set(id, {\n          digest: body.slice(0, DIGEST_LENGTH),\n          source: {\n            path,\n            ...(scenario.line === undefined ? {} : { line: scenario.line }),\n            requirement: requirement.name,\n            ...(requirement.id === undefined ? {} : { requirementId: requirement.id }),\n            scenario: scenario.name,\n            lines: scenario.lines,\n          },\n        });\n      }\n    }\n  }\n  return out;\n}\n\n/**\n * The first BDD act, as units: a requirement nobody has written a scenario for.\n *\n * `requirementsMissingScenarios` is the coverage rule every other surface\n * applies — REMOVED requirements are exempt there and stay exempt here, content\n * on its way out owes no acceptance criteria — so a packet can never disagree\n * with `loam validate` about which requirements are bare.\n */\nexport function describeUnits(featureId: string, axes: readonly DeltaAxis[]): TaskUnit[] {\n  const out: TaskUnit[] = [];\n  for (const { service, axis, path, requirements } of axes) {\n    for (const requirement of requirementsMissingScenarios(requirements)) {\n      const id = describedUnitId(featureId, service, axis.file, requirement.id ?? requirement.name);\n      out.push({\n        id,\n        kind: \"requirement.described\",\n        subject: service,\n        at: \"describe\",\n        claim:\n          `requirement '${requirement.name}' (${service}, ${axis.file}) has no scenarios` +\n          \" — write the Given/When/Then first\",\n        dependsOn: [],\n        source: {\n          path,\n          ...(requirement.line === undefined ? {} : { line: requirement.line }),\n          requirement: requirement.name,\n          ...(requirement.id === undefined ? {} : { requirementId: requirement.id }),\n        },\n        done: { check: doneCheck({ kind: \"requirement.described\" }) },\n      });\n    }\n  }\n  return out;\n}\n\n/** What could not be read. Keys are omitted when clean, so `{}` never means \"checked and fine\". */\nexport interface Unreadable {\n  architecture?: string;\n  contracts?: string[];\n}\n\n/** The delta's size, as documents rather than as open work — see `WorkPacket.size`. */\nexport interface DeltaSize {\n  requirements: number;\n  scenarios: number;\n  operations: number;\n  messages: number;\n  calls: number;\n}\n\n/**\n * The two contract axes and the architecture delta, read for their COUNTS and\n * for whether they could be read.\n *\n * The same readers `loam delta` projects through (`apiChanges`/`eventChanges`),\n * so a packet can never report an operation the brief does not. The\n * architecture half is read through the invocation's context, which means the\n * parse is shared with the checklist derivation that has already loaded the same\n * document — one LikeC4 workspace per invocation rather than two.\n */\nexport async function readContracts(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  services: readonly PathableService[],\n  context: FleetContext,\n): Promise<{ operations: number; messages: number; unreadable: Unreadable }> {\n  let operations = 0;\n  let messages = 0;\n  const broken: string[] = [];\n  for (const service of services) {\n    const paths = featureSpecPaths(featureDir, service);\n    const api = await apiChanges(paths.openapi);\n    const events = await eventChanges(paths.asyncapi);\n    if (api.unreadable || events.unreadable) broken.push(service);\n    operations += api.changes.filter((change) => !change.remove).length;\n    messages += events.changes.filter((change) => !change.remove).length;\n  }\n  const delta = featurePaths(featureDir).delta;\n  let architecture: string | undefined;\n  if (existsSync(delta)) {\n    const loaded = await context.loadLikeC4(delta);\n    // The first error only: the packet says WHICH document could not be read and\n    // why, and a reader who needs the rest runs `loam validate --feature`, whose\n    // job the whole list is.\n    const first = loaded.errors[0];\n    if (first !== undefined) architecture = errorText(first);\n  }\n  return {\n    operations,\n    messages,\n    unreadable: {\n      ...(architecture === undefined ? {} : { architecture }),\n      ...(broken.length === 0 ? {} : { contracts: broken }),\n    },\n  };\n}\n\n/** How many requirements and scenarios the delta axes hold, whatever their kind. */\nexport function axisSize(axes: readonly DeltaAxis[]): { requirements: number; scenarios: number } {\n  return {\n    requirements: axes.reduce((n, a) => n + a.requirements.length, 0),\n    scenarios: axes.reduce((n, a) => n + a.requirements.reduce((m, r) => m + r.scenarios.length, 0), 0),\n  };\n}\n"]}

package/dist/core/tasks/stamps.js

@@ -0,0 +1,76 @@
+/**
+ * What the generated suite in THIS repository already carries — read-only, and
+ * never written.
+ *
+ * `loam gherkin` stamps every scenario it emits with `@loam-digest-<16hex>`,
+ * the same hex a `scenario.tested` claim carries (`core/gherkin/digest.ts` owns
+ * the one recipe). So the presence of a stamp answers exactly one question: has
+ * a test skeleton for THESE words been generated yet? That is the difference
+ * between a unit waiting at `generate` and one waiting at `implement`, and it is
+ * the only reason a packet looks at the service repository at all.
+ *
+ * The resolution is `loam gherkin`'s own — `gherkinRoot` for the directory,
+ * `parseStampedFeature` for the bytes — because a second spelling of either
+ * would let the packet grade a suite the emitter does not own, or miss one it
+ * does.
+ *
+ * TWO ABSENCES, KEPT APART. A root directory that is not there means the suite
+ * has not been generated: the stamps ARE readable and the set is empty, so every
+ * scenario unit honestly reads `generate`. No binding, an unreadable repository,
+ * or an output directory that escapes it means loam COULD NOT LOOK, which is
+ * reported as "unknown" and never as an empty set — "nothing is wrong" and "I
+ * could not look" are opposite facts, and only one of them is a task list.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseStampedFeature } from "../gherkin/read.js";
+import { gherkinRoot } from "../gherkin/stamp.js";
+export async function readStamps(binding) {
+    const unknown = { state: "unknown", digests: new Set(), service: null };
+    if (binding.service === undefined)
+        return unknown;
+    let root;
+    try {
+        root = gherkinRoot(binding.repoDir, binding.gherkinDir);
+    }
+    catch {
+        // An output directory that escapes the repo is a configuration loam refuses
+        // to write through (`core/kernel/path-safety.ts`), so it is also one this
+        // must not read through — and it is a could-not-look, not an empty suite.
+        return unknown;
+    }
+    if (!existsSync(root))
+        return { state: "read", digests: new Set(), service: binding.service };
+    const digests = new Set();
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        // The directory is there and will not open. Unreadable is not empty.
+        return unknown;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() || !entry.name.endsWith(".feature"))
+            continue;
+        let text;
+        try {
+            text = await readFile(join(root, entry.name), "utf8");
+        }
+        catch {
+            // One unreadable file under a readable root: the rest of the suite still
+            // answers, and a file loam cannot read carries no stamps it may credit.
+            continue;
+        }
+        const stamped = parseStampedFeature(text);
+        // Null means line 1 is not loam's stamp — the file is not loam's writing,
+        // and no staleness judgment may be built on it.
+        if (stamped === null)
+            continue;
+        for (const scenario of stamped.scenarios)
+            digests.add(scenario.digest);
+    }
+    return { state: "read", digests, service: binding.service };
+}
+//# sourceMappingURL=stamps.js.map

package/dist/core/tasks/stamps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamps.js","sourceRoot":"","sources":["../../../src/core/tasks/stamps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAoBlD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAuB;IACtD,MAAM,OAAO,GAAiB,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACtF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAClD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,0EAA0E;QAC1E,0EAA0E;QAC1E,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC9F,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,SAAS;QACtE,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,wEAAwE;YACxE,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC1C,0EAA0E;QAC1E,gDAAgD;QAChD,IAAI,OAAO,KAAK,IAAI;YAAE,SAAS;QAC/B,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * What the generated suite in THIS repository already carries — read-only, and\n * never written.\n *\n * `loam gherkin` stamps every scenario it emits with `@loam-digest-<16hex>`,\n * the same hex a `scenario.tested` claim carries (`core/gherkin/digest.ts` owns\n * the one recipe). So the presence of a stamp answers exactly one question: has\n * a test skeleton for THESE words been generated yet? That is the difference\n * between a unit waiting at `generate` and one waiting at `implement`, and it is\n * the only reason a packet looks at the service repository at all.\n *\n * The resolution is `loam gherkin`'s own — `gherkinRoot` for the directory,\n * `parseStampedFeature` for the bytes — because a second spelling of either\n * would let the packet grade a suite the emitter does not own, or miss one it\n * does.\n *\n * TWO ABSENCES, KEPT APART. A root directory that is not there means the suite\n * has not been generated: the stamps ARE readable and the set is empty, so every\n * scenario unit honestly reads `generate`. No binding, an unreadable repository,\n * or an output directory that escapes it means loam COULD NOT LOOK, which is\n * reported as \"unknown\" and never as an empty set — \"nothing is wrong\" and \"I\n * could not look\" are opposite facts, and only one of them is a task list.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { parseStampedFeature } from \"../gherkin/read.js\";\nimport { gherkinRoot } from \"../gherkin/stamp.js\";\n\n/** Which repository's suite to read, as loam.json describes it. */\nexport interface GherkinBinding {\n  /** The repo root loam.json was found in — never the cwd, which may be any subdirectory. */\n  repoDir: string;\n  /** The service this repository says it is; absent in a docs repo or an unbound checkout. */\n  service?: string;\n  /** `gherkinDir` from loam.json, when it names one. */\n  gherkinDir?: string;\n}\n\nexport interface StampReading {\n  state: \"read\" | \"unknown\";\n  /** The `@loam-digest-…` values found. Meaningful only when `state` is \"read\". */\n  digests: ReadonlySet<string>;\n  /** The service the stamps belong to — nothing may be said about any other repository's suite. */\n  service: string | null;\n}\n\nexport async function readStamps(binding: GherkinBinding): Promise<StampReading> {\n  const unknown: StampReading = { state: \"unknown\", digests: new Set(), service: null };\n  if (binding.service === undefined) return unknown;\n  let root: string;\n  try {\n    root = gherkinRoot(binding.repoDir, binding.gherkinDir);\n  } catch {\n    // An output directory that escapes the repo is a configuration loam refuses\n    // to write through (`core/kernel/path-safety.ts`), so it is also one this\n    // must not read through — and it is a could-not-look, not an empty suite.\n    return unknown;\n  }\n  if (!existsSync(root)) return { state: \"read\", digests: new Set(), service: binding.service };\n  const digests = new Set<string>();\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch {\n    // The directory is there and will not open. Unreadable is not empty.\n    return unknown;\n  }\n  for (const entry of entries) {\n    if (entry.isDirectory() || !entry.name.endsWith(\".feature\")) continue;\n    let text: string;\n    try {\n      text = await readFile(join(root, entry.name), \"utf8\");\n    } catch {\n      // One unreadable file under a readable root: the rest of the suite still\n      // answers, and a file loam cannot read carries no stamps it may credit.\n      continue;\n    }\n    const stamped = parseStampedFeature(text);\n    // Null means line 1 is not loam's stamp — the file is not loam's writing,\n    // and no staleness judgment may be built on it.\n    if (stamped === null) continue;\n    for (const scenario of stamped.scenarios) digests.add(scenario.digest);\n  }\n  return { state: \"read\", digests, service: binding.service };\n}\n"]}

package/dist/core/tasks/unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit.js","sourceRoot":"","sources":["../../../src/core/tasks/unit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAwDhD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,OAAe,EACf,QAAgB,EAChB,WAAmB;IAEnB,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjG,OAAO,GAAG,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;AACrG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAA2D;IACnF,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,qDAAqD,CAAC;IAC/F,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;QACpC,mEAAmE;QACnE,mEAAmE;QACnE,sDAAsD;QACtD,OAAO,CACL,yBAAyB,IAAI,CAAC,MAAM,IAAI,EAAE,kDAAkD;YAC5F,wGAAwG,CACzG,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QAChC,OAAO,gBAAgB,IAAI,CAAC,SAAS,IAAI,EAAE,mEAAmE,CAAC;IACjH,CAAC;IACD,OAAO,mEAAmE,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,SAAS;QAC1E,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAChD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,SAAS;QACnE,IAAI,CAAC,SAAS,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,CAAC,IAAc,EAAU,EAAE;QAC1C,MAAM,KAAK,GAAI,WAAiC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,2EAA2E;QAC3E,4EAA4E;QAC5E,0DAA0D;QAC1D,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IACnD,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,IAAc,EAAU,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,MAAM,CAAC,gBAAgB,CAAC;IACxF,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CACpB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC;QACzD,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;QACzB,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3D,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QACrB,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CACzB,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,mGAAmG;AACnG,MAAM,UAAU,MAAM,CAAC,IAAc;IACnC,OAAO,IAAI,CAAC,EAAE,KAAK,UAAU,CAAC;AAChC,CAAC","sourcesContent":["/**\r\n * What a unit of work IS, and the total order they are read in.\r\n *\r\n * A unit is the third rendering of one ledger. `loam verify` answers \"answered\r\n * by whom\"; this answers \"what is still open, at which step, and what closes\r\n * it\". Nothing here is a second definition of a claim: for a claim-backed unit\r\n * the id, kind, subject, claim text, digest, operation and token are the\r\n * `Claim`'s own fields verbatim (`core/verify/checklist.ts`) — the task id IS\r\n * the claim id, which is what lets an agent hand a unit id straight to\r\n * `loam verify` and lets two runs be diffed.\r\n *\r\n * `at` is the step the unit is waiting at, and it is deliberately NOT spelled\r\n * `stage` or `verdict`: `stage` is the published `ArtifactStatus` key\r\n * (`core/status/report.ts`) and `verdict` is `VerificationVerdict`\r\n * (`core/verify/record.ts`). A third meaning for either word on a payload an\r\n * agent reads beside the other two is how a consumer comes to branch on the\r\n * wrong field.\r\n */\r\nimport { createHash } from \"node:crypto\";\r\nimport { CLAIM_KINDS, ID_LENGTH } from \"../verify/claims/identity.js\";\r\nimport { compareIds } from \"../repo/entries.js\";\r\n\r\n/**\r\n * Where a unit is waiting.\r\n *\r\n * `describe` is the first BDD act — a requirement with no scenario at all, so\r\n * there is nothing to generate a test from and nothing to claim. `generate`\r\n * means the scenario exists and this repository's generated suite does not\r\n * carry its stamp yet. `implement` is everything else that is open.\r\n * `attested` is the one step that is not work: the claim is confirmed on an\r\n * agent's word rather than on a run, so the unit never vanishes — it stays\r\n * visible, and closing it means a cucumber report, not an edit.\r\n */\r\nexport type TaskStep = \"describe\" | \"generate\" | \"implement\" | \"attested\";\r\n\r\n/** Where the words a unit is about are written down, so a reader can open the file. */\r\nexport interface RequirementSource {\r\n  /** Repo-relative, like every path in the envelope. */\r\n  path: string;\r\n  /** 1-based heading line, when the parser recorded one. */\r\n  line?: number;\r\n  requirement: string;\r\n  requirementId?: string;\r\n}\r\n\r\n/**\r\n * A scenario's source — the requirement's, plus the scenario's own words.\r\n *\r\n * A variant rather than four more optional fields on the shape above: `scenario`\r\n * and `lines` are only ever set together, and only for `scenario.tested`. The\r\n * body rides VERBATIM because it is the acceptance criterion the implementer is\r\n * meant to satisfy and the exact text the digest was taken over — paraphrasing\r\n * it here would be the one thing the whole digest chain exists to prevent.\r\n */\r\nexport interface ScenarioSource extends RequirementSource {\r\n  scenario: string;\r\n  lines: string[];\r\n}\r\n\r\nexport type TaskSource = RequirementSource | ScenarioSource;\r\n\r\nexport interface TaskUnit {\r\n  /** The claim id verbatim, or a `requirement.described-…` id from `describedUnitId`. */\r\n  id: string;\r\n  kind: string;\r\n  subject: string;\r\n  at: TaskStep;\r\n  claim: string;\r\n  digest?: string;\r\n  operation?: string;\r\n  token?: string;\r\n  dependsOn: string[];\r\n  source?: TaskSource;\r\n  done: { check: string };\r\n}\r\n\r\n/**\r\n * The one kind that is NOT a claim kind.\r\n *\r\n * `CLAIM_KINDS` is frozen: a member added to it re-hashes nothing, but it\r\n * changes the checklist's question set, and every `verification.yaml` in the\r\n * fleet would read as stale on upgrade. A requirement with no scenarios is also\r\n * not a promise anybody can answer with evidence — there is no text to test —\r\n * so it lives in a namespace of its own, with an id recipe of its own.\r\n */\r\nexport const DESCRIBED_KIND = \"requirement.described\";\r\n\r\n/**\r\n * The id of a `requirement.described` unit: content-derived, like a claim id\r\n * and for a claim id's reason — rename the requirement and the unit retires\r\n * itself rather than following a heading around.\r\n *\r\n * `\"loam.task\"` leads the tuple so this namespace can never collide with\r\n * `claimId`'s, whose tuples start with the feature id. NUL-joined for\r\n * `claimId`'s reason: no part's own text can spell the separator, so\r\n * [\"a b\",\"c\"] and [\"a\",\"b c\"] stay two units. `axisFile` is `spec.md` or\r\n * `arch.spec.md` — the two axes are two namespaces everywhere else in loam\r\n * (`core/gherkin/digest.ts` salts the scenario hash with it), and one\r\n * requirement name may legitimately appear on both.\r\n */\r\nexport function describedUnitId(\r\n  featureId: string,\r\n  service: string,\r\n  axisFile: string,\r\n  requirement: string,\r\n): string {\r\n  const tuple = [\"loam.task\", featureId, DESCRIBED_KIND, service, axisFile, requirement].join(\"\u0000\");\r\n  return `${DESCRIBED_KIND}-${createHash(\"sha256\").update(tuple).digest(\"hex\").slice(0, ID_LENGTH)}`;\r\n}\r\n\r\n/**\r\n * What closes this unit, in one sentence a reader can act on without opening\r\n * another document. Every arm names the mechanical channel that may answer it,\r\n * because the channels are not interchangeable: a scenario claim confirmed\r\n * without a run is `attested` and not `verified` (core/verify/record.ts), and an\r\n * api.exposes claim is answered by a contract report rather than by a cucumber\r\n * one.\r\n */\r\nexport function doneCheck(unit: { kind: string; digest?: string; operation?: string }): string {\r\n  if (unit.kind === DESCRIBED_KIND) return \"the requirement carries at least one #### Scenario:\";\r\n  if (unit.kind === \"scenario.tested\") {\r\n    // Both report shapes by name: a fleet whose runner has no cucumber\r\n    // formatter otherwise reads this as \"cucumber or nothing\", and the\r\n    // runner-neutral shape exists precisely so it is not.\r\n    return (\r\n      `scenario @loam-digest-${unit.digest ?? \"\"} passes in a test run — a cucumber JSON report, ` +\r\n      \"or a loamScenarioReport entry carrying that digest — and is recorded confirmed (loam verify --results)\"\r\n    );\r\n  }\r\n  if (unit.kind === \"api.exposes\") {\r\n    return `operationId '${unit.operation ?? \"\"}' reported passed via loam verify --contract-results and recorded`;\r\n  }\r\n  return \"recorded confirmed with file:line evidence (loam verify --record)\";\r\n}\r\n\r\n/**\r\n * The one edge v1 draws: a `c4.calls` unit depends on the `api.exposes` units\r\n * that promise the operation it calls.\r\n *\r\n * The join is EXACT and cross-kind on purpose — a call edge's `token` against a\r\n * provider claim's `operation`, never token against token. An AsyncAPI message\r\n * name and an operationId are different namespaces that routinely spell the\r\n * same word (`payment.Authorized` is not an operationId, but `createSplit` is a\r\n * perfectly plausible message name), and `event.declares` carries a `token`\r\n * too: joining on token equality would wire a consumer's call to an unrelated\r\n * message declaration and then order the whole packet by that fiction.\r\n * `operation` is set on `api.exposes` and nothing else — `core/verify/checklist.ts`\r\n * says so in the field's own docblock, and `contestedOperations` already\r\n * depends on it.\r\n *\r\n * Ordering is ADVICE, never a lock. The frontier does not exclude a unit for\r\n * having open dependencies; the sort merely puts providers first. An\r\n * implementer who starts at the consumer is not doing anything wrong, and a\r\n * packet that refused to show them the work would be a scheduler.\r\n */\r\nexport function linkDependencies(units: TaskUnit[]): void {\r\n  const providers = new Map<string, string[]>();\r\n  for (const unit of units) {\r\n    if (unit.kind !== \"api.exposes\" || unit.operation === undefined) continue;\r\n    const ids = providers.get(unit.operation) ?? [];\r\n    ids.push(unit.id);\r\n    providers.set(unit.operation, ids);\r\n  }\r\n  for (const unit of units) {\r\n    if (unit.kind !== \"c4.calls\" || unit.token === undefined) continue;\r\n    unit.dependsOn = [...(providers.get(unit.token) ?? [])].sort();\r\n  }\r\n}\r\n\r\n/**\r\n * The reading order, total and deterministic — `--json` consumers diff it.\r\n *\r\n * Describe first, because a requirement with no scenario blocks the whole BDD\r\n * chain under it: there is nothing to generate and nothing to test. Then the\r\n * claim kinds in `CLAIM_KINDS` order, which is read off the vocabulary rather\r\n * than respelled here — that order already reads as the story of a feature (the\r\n * service exists, it exposes its operations, it declares its messages, the calls\r\n * into it are wired, the behaviour is tested), and a second copy of it would be\r\n * free to disagree.\r\n *\r\n * Within a kind a unit somebody depends on sorts before one nobody does, so the\r\n * provider of a shared operation leads its own kind. Then the subject by\r\n * `compareIds` (the fleet's one id ordering), then the source line so a service's\r\n * units read in document order, then the id as the final tiebreak — a unit with\r\n * no source must still land somewhere stable.\r\n */\r\nexport function sortUnits(units: TaskUnit[]): TaskUnit[] {\r\n  const dependedOn = new Set(units.flatMap((unit) => unit.dependsOn));\r\n  const kindRank = (unit: TaskUnit): number => {\r\n    const index = (CLAIM_KINDS as readonly string[]).indexOf(unit.kind);\r\n    // A kind outside the vocabulary sorts last rather than first: -1 would put\r\n    // an unknown kind ahead of `service.exists`, which is the one position that\r\n    // silently reorders every packet the day a kind is added.\r\n    return index === -1 ? CLAIM_KINDS.length : index;\r\n  };\r\n  const lineOf = (unit: TaskUnit): number => unit.source?.line ?? Number.MAX_SAFE_INTEGER;\r\n  return [...units].sort(\r\n    (a, b) =>\r\n      Number(a.at !== \"describe\") - Number(b.at !== \"describe\") ||\r\n      kindRank(a) - kindRank(b) ||\r\n      Number(dependedOn.has(b.id)) - Number(dependedOn.has(a.id)) ||\r\n      compareIds(a.subject, b.subject) ||\r\n      lineOf(a) - lineOf(b) ||\r\n      compareIds(a.id, b.id),\r\n  );\r\n}\r\n\r\n/** How many unit ids the frontier carries before it starts eliding. */\r\nexport const FRONTIER_LIMIT = 10;\r\n\r\n/** An open unit is one that is still work: `attested` is complete work resting on an assertion. */\r\nexport function isOpen(unit: TaskUnit): boolean {\r\n  return unit.at !== \"attested\";\r\n}\r\n"]}

package/dist/core/usecases/capability.js

@@ -0,0 +1,166 @@
+/**
+ * The capability half of the use-case axis: which flows CLAIM a declared
+ * capability, and which services those flows run through.
+ *
+ * `core/capabilities/usecase-join.ts` owns the tag grammar and the resolution
+ * ladder — it answers "what does this tag name?", including the `many` arm the
+ * slug's non-injectivity forces. This module asks the question the other way
+ * round: given a capability id somebody already has, which views carry its tag?
+ * That direction needs no ladder, because the id is not in doubt; it needs only
+ * the slug, so it takes the slug and stops.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not grade the tag. A view tagged `#cap-payments-refunds` matches BOTH
+ * `payments/refunds` and `payments-refunds` when a fleet declares both, and this
+ * module reports it under both — because that is what the tag says, and the tag
+ * is what the author wrote. `usecase.capability-unresolved` is already an ERROR
+ * over exactly that collision (`validate`'s use-case package), so a second
+ * verdict here would be a second answer to a question the gate has already
+ * settled. The same stance `PackPermission` takes on an undeclared permission:
+ * carry the claim, let validate convict it.
+ */
+import { tagSlug, CAP_TAG_PREFIX, resolveCapabilityTags, resolveRequirementTags, } from "../capabilities/usecase-join.js";
+import { capabilityRequirementIndex } from "../capabilities/findings.js";
+import { compareIds } from "../repo/entries.js";
+import { readUseCases } from "./fleet.js";
+import { viewFile } from "./place.js";
+import { participantsOf } from "./suites/participants.js";
+/** The tag spelling a declared capability id would carry — `identity/tokens` → `cap-identity-tokens`. */
+function tagFor(capability) {
+    return `${CAP_TAG_PREFIX}${tagSlug(capability)}`;
+}
+/** Does this view claim the capability? Exact tag match, case included, as `resolveCapabilityTags` matches. */
+function claims(view, tag) {
+    return view.tags.includes(tag);
+}
+/**
+ * The flows claiming one declared capability, sorted by (file, id).
+ *
+ * Sorted rather than reported in LikeC4's record order for the reason every
+ * other list in this axis is: nothing has measured that the parse preserves
+ * declaration order, and a payload ordered by an unmeasured upstream detail
+ * reorders under a dependency bump.
+ */
+export function flowsClaiming(scan, capability) {
+    if (scan.kind !== "read")
+        return [];
+    const tag = tagFor(capability);
+    return scan.views
+        .filter((view) => claims(view, tag))
+        .map((view) => ({ id: view.id, ...(view.title === undefined ? {} : { title: view.title }), file: viewFile(view) }))
+        .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id));
+}
+/**
+ * Every ENUMERATED service the flows claiming these capabilities run through.
+ *
+ * The restriction to the enumerated fleet is this function's own contract, not
+ * a guard somebody downstream is relying on: a step's endpoints resolve to
+ * whatever the element stands for, and a sequence diagram is full of endpoints
+ * that own no directory — the actor who starts the flow, the topic in the
+ * middle, the database at the end. A function called `servicesInFlows…` that
+ * answered `Customer` would be lying in its own name. `loam explore`, today's
+ * only caller, filters the result against its enumeration again for a different
+ * reason (it needs `ServiceEntry`s, in enumeration order), so removing the
+ * filter here would not currently change what that command prints — which is
+ * exactly why it is written down that the reason it exists is the return type,
+ * not the call site.
+ *
+ * The walk itself is `./suites/participants.ts`' `participantsOf`, which
+ * this function used to spell for itself: a suite asks the same question of a
+ * different set of views and needs the participants that resolve to NO service
+ * as well. The restriction now lives here as a choice — this function reads
+ * `services` and drops `unresolved` — rather than as a filter inside the walk,
+ * so the one union a test stand is provisioned from and the one `explore` seeds
+ * from cannot resolve an element two ways.
+ *
+ * The cost of the restriction, stated so the next reader can weigh it: a flow
+ * drawn through a service the fleet has not adopted yet contributes no seed.
+ * That service has no documentation to explore, so what is lost is a name in a
+ * list, and `usecase.step-unlinked` / `landscape.service-undocumented` are where
+ * the fleet is told about it.
+ */
+export function servicesInFlowsClaiming(scan, capabilities) {
+    if (scan.kind !== "read")
+        return [];
+    const tags = new Set(capabilities.map(tagFor));
+    const claiming = scan.views.filter((view) => [...tags].some((tag) => claims(view, tag)));
+    return participantsOf(scan, claiming).services;
+}
+/**
+ * The `<capability>#<Requirement-ID>` pairs a fleet's flows RESOLVE to — the
+ * business promises a use case claims to keep.
+ *
+ * Lives in core rather than beside the grade that reports a broken tag, because
+ * two very different callers need the same answer and they must not compute it
+ * twice: `validate --all` subtracts these from
+ * `capability.requirement-unrealized` (a promise a flow keeps is not unkept),
+ * and `loam list capabilities` reports them beside the service requirements
+ * that realize the same promise. Two implementations of "which promises does
+ * this fleet keep" is two answers to the question the axis exists to settle.
+ *
+ * A MAP RATHER THAN A SET, because the two callers need different depths of the
+ * same answer and one of them needs names. `validate` only asks whether a
+ * promise is kept (`.has`, which a Map answers identically); a listing that said
+ * "kept" without saying by WHAT would leave a reader unable to open the flow, go
+ * look at its hops and judge whether the promise really is kept — which is the
+ * whole reason the listing carries the realizing service requirements by name
+ * rather than as a count. Widening the return type was cheaper than a second
+ * function, and a second function is how the two corpora start disagreeing.
+ *
+ * ONLY RESOLVED CLAIMS COUNT, and both halves must resolve: the `#cap-` tag to
+ * exactly one declared capability, and the `#req-` tag to exactly one of its
+ * requirements. A broken tag of either kind is already an ERROR
+ * (`usecase.capability-unresolved`, `usecase.requirement-unresolved`) and must
+ * never also mark a promise kept — a typo that silenced the unrealized warning
+ * would turn a mistake into a green fleet.
+ *
+ * `declared` carries the vocabulary ladder: `null` means there is nothing to
+ * grade against, and the honest answer is then an empty map — no flow can be
+ * said to keep a promise loam cannot see declared.
+ *
+ * Diff-stable by construction: the view ids under each promise are DEDUPLICATED
+ * and sorted with compareIds, so nothing here depends on LikeC4's view order,
+ * on how many tags one view carried, or on the readdir order the project was
+ * staged in. The map's own key order reaches no output — both callers look
+ * promises up by key — but the values are printed, so they are sorted.
+ */
+export function useCaseRequirementClaims(views, declared, requirementsOf) {
+    const claimed = new Map();
+    if (declared !== null) {
+        for (const view of views) {
+            const scope = resolveCapabilityTags(view.tags, declared).flatMap((claim) => claim.kind === "resolved" ? [claim.id] : []);
+            for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {
+                if (claim.kind !== "resolved")
+                    continue;
+                const key = `${claim.capability}#${claim.id}`;
+                const flows = claimed.get(key) ?? new Set();
+                flows.add(view.id);
+                claimed.set(key, flows);
+            }
+        }
+    }
+    return new Map([...claimed].map(([key, flows]) => [key, [...flows].sort(compareIds)]));
+}
+export async function promisesKeptByFlows(req) {
+    const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });
+    if (scan.kind !== "read")
+        return { kind: "unreadable", errors: scan.errors };
+    // No flow, no claim — and no capability document is opened to prove it.
+    // `readUseCases`' byte gate answers a fleet with no use cases without starting
+    // LikeC4 at all, and reading every `capabilities/<id>/spec.md` here to resolve
+    // a tag set that is empty would put back the cost the gate exists to remove.
+    // The `read` arm is still what travels: the fleet WAS looked at.
+    if (scan.views.length === 0)
+        return { kind: "read", kept: new Map() };
+    const index = await capabilityRequirementIndex(req.vocab, req.read);
+    // `index.declared` rather than a second call to `gradableCapabilityIds`: the
+    // index applied the ladder when it was built, and two applications of one rule
+    // is where the two halves of this join start disagreeing about whether the
+    // vocabulary is gradable at all.
+    return {
+        kind: "read",
+        kept: useCaseRequirementClaims(scan.views, index.declared, (c) => index.byCapability.get(c)),
+    };
+}
+//# sourceMappingURL=capability.js.map

package/dist/core/usecases/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/core/usecases/capability.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The capability half of the use-case axis: which flows CLAIM a declared\n * capability, and which services those flows run through.\n *\n * `core/capabilities/usecase-join.ts` owns the tag grammar and the resolution\n * ladder — it answers \"what does this tag name?\", including the `many` arm the\n * slug's non-injectivity forces. This module asks the question the other way\n * round: given a capability id somebody already has, which views carry its tag?\n * That direction needs no ladder, because the id is not in doubt; it needs only\n * the slug, so it takes the slug and stops.\n *\n * ## What this deliberately does NOT do\n *\n * It does not grade the tag. A view tagged `#cap-payments-refunds` matches BOTH\n * `payments/refunds` and `payments-refunds` when a fleet declares both, and this\n * module reports it under both — because that is what the tag says, and the tag\n * is what the author wrote. `usecase.capability-unresolved` is already an ERROR\n * over exactly that collision (`validate`'s use-case package), so a second\n * verdict here would be a second answer to a question the gate has already\n * settled. The same stance `PackPermission` takes on an undeclared permission:\n * carry the claim, let validate convict it.\n */\nimport {\n  tagSlug,\n  CAP_TAG_PREFIX,\n  resolveCapabilityTags,\n  resolveRequirementTags,\n} from \"../capabilities/usecase-join.js\";\nimport { capabilityRequirementIndex } from \"../capabilities/findings.js\";\nimport type { CapabilityVocabulary } from \"../capabilities/capabilities.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport { compareIds } from \"../repo/entries.js\";\nimport type { ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { readUseCases, type UseCaseScan } from \"./fleet.js\";\nimport { viewFile } from \"./place.js\";\nimport { participantsOf } from \"./suites/participants.js\";\n\n/** One flow claiming a capability: enough to name it and to open the file it lives in. */\nexport interface ClaimingFlow {\n  id: string;\n  title?: string;\n  /** Repo-relative document the view is written in. */\n  file: string;\n}\n\n/** The tag spelling a declared capability id would carry — `identity/tokens` → `cap-identity-tokens`. */\nfunction tagFor(capability: string): string {\n  return `${CAP_TAG_PREFIX}${tagSlug(capability)}`;\n}\n\n/** Does this view claim the capability? Exact tag match, case included, as `resolveCapabilityTags` matches. */\nfunction claims(view: ParsedView, tag: string): boolean {\n  return view.tags.includes(tag);\n}\n\n/**\n * The flows claiming one declared capability, sorted by (file, id).\n *\n * Sorted rather than reported in LikeC4's record order for the reason every\n * other list in this axis is: nothing has measured that the parse preserves\n * declaration order, and a payload ordered by an unmeasured upstream detail\n * reorders under a dependency bump.\n */\nexport function flowsClaiming(scan: UseCaseScan, capability: string): ClaimingFlow[] {\n  if (scan.kind !== \"read\") return [];\n  const tag = tagFor(capability);\n  return scan.views\n    .filter((view) => claims(view, tag))\n    .map((view) => ({ id: view.id, ...(view.title === undefined ? {} : { title: view.title }), file: viewFile(view) }))\n    .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id));\n}\n\n/**\n * Every ENUMERATED service the flows claiming these capabilities run through.\n *\n * The restriction to the enumerated fleet is this function's own contract, not\n * a guard somebody downstream is relying on: a step's endpoints resolve to\n * whatever the element stands for, and a sequence diagram is full of endpoints\n * that own no directory — the actor who starts the flow, the topic in the\n * middle, the database at the end. A function called `servicesInFlows…` that\n * answered `Customer` would be lying in its own name. `loam explore`, today's\n * only caller, filters the result against its enumeration again for a different\n * reason (it needs `ServiceEntry`s, in enumeration order), so removing the\n * filter here would not currently change what that command prints — which is\n * exactly why it is written down that the reason it exists is the return type,\n * not the call site.\n *\n * The walk itself is `./suites/participants.ts`' `participantsOf`, which\n * this function used to spell for itself: a suite asks the same question of a\n * different set of views and needs the participants that resolve to NO service\n * as well. The restriction now lives here as a choice — this function reads\n * `services` and drops `unresolved` — rather than as a filter inside the walk,\n * so the one union a test stand is provisioned from and the one `explore` seeds\n * from cannot resolve an element two ways.\n *\n * The cost of the restriction, stated so the next reader can weigh it: a flow\n * drawn through a service the fleet has not adopted yet contributes no seed.\n * That service has no documentation to explore, so what is lost is a name in a\n * list, and `usecase.step-unlinked` / `landscape.service-undocumented` are where\n * the fleet is told about it.\n */\nexport function servicesInFlowsClaiming(scan: UseCaseScan, capabilities: readonly string[]): string[] {\n  if (scan.kind !== \"read\") return [];\n  const tags = new Set(capabilities.map(tagFor));\n  const claiming = scan.views.filter((view) => [...tags].some((tag) => claims(view, tag)));\n  return participantsOf(scan, claiming).services;\n}\n\n/**\n * The `<capability>#<Requirement-ID>` pairs a fleet's flows RESOLVE to — the\n * business promises a use case claims to keep.\n *\n * Lives in core rather than beside the grade that reports a broken tag, because\n * two very different callers need the same answer and they must not compute it\n * twice: `validate --all` subtracts these from\n * `capability.requirement-unrealized` (a promise a flow keeps is not unkept),\n * and `loam list capabilities` reports them beside the service requirements\n * that realize the same promise. Two implementations of \"which promises does\n * this fleet keep\" is two answers to the question the axis exists to settle.\n *\n * A MAP RATHER THAN A SET, because the two callers need different depths of the\n * same answer and one of them needs names. `validate` only asks whether a\n * promise is kept (`.has`, which a Map answers identically); a listing that said\n * \"kept\" without saying by WHAT would leave a reader unable to open the flow, go\n * look at its hops and judge whether the promise really is kept — which is the\n * whole reason the listing carries the realizing service requirements by name\n * rather than as a count. Widening the return type was cheaper than a second\n * function, and a second function is how the two corpora start disagreeing.\n *\n * ONLY RESOLVED CLAIMS COUNT, and both halves must resolve: the `#cap-` tag to\n * exactly one declared capability, and the `#req-` tag to exactly one of its\n * requirements. A broken tag of either kind is already an ERROR\n * (`usecase.capability-unresolved`, `usecase.requirement-unresolved`) and must\n * never also mark a promise kept — a typo that silenced the unrealized warning\n * would turn a mistake into a green fleet.\n *\n * `declared` carries the vocabulary ladder: `null` means there is nothing to\n * grade against, and the honest answer is then an empty map — no flow can be\n * said to keep a promise loam cannot see declared.\n *\n * Diff-stable by construction: the view ids under each promise are DEDUPLICATED\n * and sorted with compareIds, so nothing here depends on LikeC4's view order,\n * on how many tags one view carried, or on the readdir order the project was\n * staged in. The map's own key order reaches no output — both callers look\n * promises up by key — but the values are printed, so they are sorted.\n */\nexport function useCaseRequirementClaims(\n  views: readonly ParsedView[],\n  declared: readonly string[] | null,\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined,\n): ReadonlyMap<string, string[]> {\n  const claimed = new Map<string, Set<string>>();\n  if (declared !== null) {\n    for (const view of views) {\n      const scope = resolveCapabilityTags(view.tags, declared).flatMap((claim) =>\n        claim.kind === \"resolved\" ? [claim.id] : [],\n      );\n      for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {\n        if (claim.kind !== \"resolved\") continue;\n        const key = `${claim.capability}#${claim.id}`;\n        const flows = claimed.get(key) ?? new Set<string>();\n        flows.add(view.id);\n        claimed.set(key, flows);\n      }\n    }\n  }\n  return new Map([...claimed].map(([key, flows]) => [key, [...flows].sort(compareIds)]));\n}\n\n/**\n * The same answer as `useCaseRequirementClaims`, read from disk — or the honest\n * refusal to give one.\n *\n * `validate --all` already holds the parsed project and has already applied the\n * vocabulary ladder by the time it grades, so it calls the pure function above\n * with what it has. `loam list capabilities` holds neither, and the three steps\n * between a docsDir and that answer — read the flows, take the ladder, index the\n * documents' requirement ids — are three chances to get the suppression rules\n * wrong. They live here rather than in the command for that reason and not for\n * brevity: a command that spelled `[...vocab.byId.keys()]` in place of the\n * ladder would report a flow's promise as kept against a vocabulary nobody could\n * read.\n *\n * THE `unreadable` ARM MUST TRAVEL. An `architecture/` that did not parse yields\n * no views, and an empty map is indistinguishable from \"no flow keeps\n * anything\" — which is the single wrong answer this axis exists to prevent, and\n * the reason `readUseCases` is a tagged union rather than a list.\n */\nexport type PromisesKept =\n  | { kind: \"read\"; kept: ReadonlyMap<string, readonly string[]> }\n  | { kind: \"unreadable\"; errors: string[] };\n\nexport interface PromisesKeptRequest {\n  docsDir: DocsDir;\n  vocab: CapabilityVocabulary;\n  /** The enumerated fleet — `readUseCases`' own requirement, for its own reason. */\n  known: ReadonlySet<string>;\n  /** The requirement reader — pass a FleetContext's readRequirements, bound. */\n  read: (path: string) => Promise<Requirement[]>;\n}\n\nexport async function promisesKeptByFlows(req: PromisesKeptRequest): Promise<PromisesKept> {\n  const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });\n  if (scan.kind !== \"read\") return { kind: \"unreadable\", errors: scan.errors };\n  // No flow, no claim — and no capability document is opened to prove it.\n  // `readUseCases`' byte gate answers a fleet with no use cases without starting\n  // LikeC4 at all, and reading every `capabilities/<id>/spec.md` here to resolve\n  // a tag set that is empty would put back the cost the gate exists to remove.\n  // The `read` arm is still what travels: the fleet WAS looked at.\n  if (scan.views.length === 0) return { kind: \"read\", kept: new Map() };\n  const index = await capabilityRequirementIndex(req.vocab, req.read);\n  // `index.declared` rather than a second call to `gradableCapabilityIds`: the\n  // index applied the ladder when it was built, and two applications of one rule\n  // is where the two halves of this join start disagreeing about whether the\n  // vocabulary is gradable at all.\n  return {\n    kind: \"read\",\n    kept: useCaseRequirementClaims(scan.views, index.declared, (c) => index.byCapability.get(c)),\n  };\n}\n"]}