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

package/dist/core/status/report.js

@@ -0,0 +1,31 @@
+/** The closed set. The module header says what each value instructs. */
+export const ARTIFACT_STATUSES = ["missing", "blocked", "draft", "ready", "done"];
+/**
+ * The artifact kinds a feature can owe, in the order the cycle authors them.
+ * `spec`, `arch-spec`, `openapi` and `asyncapi` are per-service and repeat
+ * once per service the feature touches; `capabilities` repeats once per
+ * capability document the feature's delta carries; the rest are feature-wide.
+ *
+ * `capabilities` sits where an analyst writes it — the business promise comes
+ * before the services that keep it, and a capability-only feature is a real and
+ * ordinary first commit.
+ */
+export const ARTIFACT_IDS = [
+    "intent",
+    "delta",
+    "capabilities",
+    "spec",
+    "arch-spec",
+    "openapi",
+    "asyncapi",
+    "verification",
+];
+/** Nothing is written down: no living spec at all. Every other absence is partial adoption. */
+export function undocumented(s) {
+    return !s.has.spec;
+}
+/** A person stamped it — `loam vouch`'s exact postcondition, read back off the frontmatter. */
+export function vouched(s) {
+    return s.status === "verified" && s.sources.stamped;
+}
+//# sourceMappingURL=report.js.map

package/dist/core/status/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/status/report.ts"],"names":[],"mappings":"AA8EA,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAG3F;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,cAAc;IACd,MAAM;IACN,WAAW;IACX,SAAS;IACT,UAAU;IACV,cAAc;CACN,CAAC;AAqPX,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,CAAe;IAC1C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,OAAO,CAAC,CAAe;IACrC,OAAO,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Where does this work stand, and what is the next thing to do?\n *\n * Every other command answers a question you already know how to ask: validate\n * grades a target you name, delta briefs a service you name, verify checks a\n * feature you name. The one thing loam could not answer was the question an\n * agent asks FIRST — the one it has when it joins a repository halfway, or\n * comes back after losing its session. That knowledge existed, but only as\n * prose inside the slash commands (\"1. scaffold, 2. author, 3. validate\"),\n * which is to say it existed for whoever had read them recently and for nobody\n * else.\n *\n * The obvious implementation is a state file — a `.loam/state.json` recording\n * which step each feature reached. It is rejected here for the reason core/verify/\n * refuses a second mutable database: the moment a second record of the truth\n * exists, an author who edits a file by hand, a merge, a rebase or a\n * `git checkout` desynchronises it, and the state file's answer is confidently\n * wrong exactly when somebody trusts it. So `status` stores nothing and caches\n * nothing. It is a projection: every invocation re-derives the whole answer\n * from the files, and a file edited in another window is visible on the next\n * run with no invalidation step for anyone to forget.\n *\n * It also grades nothing itself. Every verdict here is somebody else's\n * function: `featureCoherence` (what `loam archive` refuses on) plus\n * `featureProvenance` and `requirementsMissingScenarios` (`loam validate\n * --feature`'s other error sources, as far as they exist as shared functions),\n * and `readVerificationState` + `featureChecklist`, the pair `loam verify`\n * uses. A second opinion about whether a feature holds together would be a\n * second answer to grade a pull request against, and the one a reader consults\n * is never the one the gate obeys (doctor.ts learnt this with its own config\n * validator). A check that lives inline inside `validate` cannot be inherited\n * at all, which is why `stage` never rests on `checks.coherent` alone.\n *\n * Which is why the rule this module is held to is one-directional: **status may\n * be more pessimistic than the gates, never greener.** `validate` and `archive`\n * answer two different questions — is the DOCUMENT valid, is the MERGE safe\n * (issue.ts) — and a projection that reported only one of them told an author\n * \"ship it\" about a feature the other one refuses. So `stage` and `next[]` take\n * the UNION: an error `validate` grades and a warning `archive` gates on both\n * make a feature `draft`, and test/status-agrees-with-gate.test.ts holds the\n * direction on a matrix of deliberately-damaged trees.\n *\n * ## The status vocabulary\n *\n * Five values, closed, and an agent is expected to branch on them:\n *\n *   `missing`  the artifact is owed and is not on disk; nothing stands in the\n *              way of writing it now.\n *   `blocked`  the work is stalled on something that is NOT this artifact — an\n *              artifact it is derived from is absent, or another feature in\n *              flight has to archive first.\n *   `draft`    it is on disk and the shared checks report an error against it:\n *              what exists is wrong.\n *   `ready`    it is on disk and clean, but its obligation is not discharged —\n *              something outside the documents (code, a test run, a recording)\n *              still has to answer it.\n *   `done`     nothing is owed here.\n *\n * The two pairs that look alike are the point of the set. `missing` and\n * `blocked` both mean \"not written\", and they are different instructions: one\n * says write it now, the other says you cannot yet and names what comes first —\n * an agent that cannot tell them apart authors a verification record against a\n * checklist that does not exist. `draft` and `ready` both mean \"on disk\", and\n * they are different instructions too: `draft` says the document is wrong and\n * the fix is in this repository, `ready` says the document is right and the\n * world has not caught up — the code is not built, or the claims are not\n * answered. Collapsing those two would send an agent to re-edit a spec that is\n * already correct.\n *\n * A value unreachable in a scope is simply never emitted there, deliberately:\n * the fleet form never says `draft`, because grading is a per-feature cost it\n * refuses to pay.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\nimport type { UseCaseBlastRadius } from \"../usecases/touch.js\";\nimport type { VerificationVerdict } from \"../verify/record.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\n\n/** The closed set. The module header says what each value instructs. */\nexport const ARTIFACT_STATUSES = [\"missing\", \"blocked\", \"draft\", \"ready\", \"done\"] as const;\nexport type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];\n\n/**\n * The artifact kinds a feature can owe, in the order the cycle authors them.\n * `spec`, `arch-spec`, `openapi` and `asyncapi` are per-service and repeat\n * once per service the feature touches; `capabilities` repeats once per\n * capability document the feature's delta carries; the rest are feature-wide.\n *\n * `capabilities` sits where an analyst writes it — the business promise comes\n * before the services that keep it, and a capability-only feature is a real and\n * ordinary first commit.\n */\nexport const ARTIFACT_IDS = [\n  \"intent\",\n  \"delta\",\n  \"capabilities\",\n  \"spec\",\n  \"arch-spec\",\n  \"openapi\",\n  \"asyncapi\",\n  \"verification\",\n] as const;\nexport type ArtifactId = (typeof ARTIFACT_IDS)[number];\n\nexport interface ArtifactState {\n  id: ArtifactId;\n  /** The service this artifact belongs to, or null for the feature-wide ones. */\n  service: string | null;\n  /**\n   * The capability this artifact belongs to, on `capabilities` rows only.\n   *\n   * A field of its own rather than a capability id put in `service`: the two\n   * are different namespaces — a fleet may hold a service and a capability of\n   * one name — and bending a published field to carry the other kind is how a\n   * consumer grouping by service silently acquires a row that is not one. Absent\n   * on every other row, so nothing that reads `service` today changes.\n   */\n  capability?: string;\n  /** Repo-relative with forward slashes — diffable across machines, like every path in the contract. */\n  path: string;\n  exists: boolean;\n  /**\n   * Whether ABSENCE is a defect. False for the artifacts a feature may\n   * legitimately not have: `delta.likec4` (a requirements-only change deletes\n   * it), `arch.spec.md` and `asyncapi.yaml` (optional everywhere), and\n   * `openapi.yaml` for a service\n   * the living docs already carry. An absent optional artifact is `done` —\n   * nothing is owed — and `exists: false` beside it is how a reader tells that\n   * from a file that is present and fine.\n   */\n  required: boolean;\n  status: ArtifactStatus;\n  /** Artifact ids that must come first. Non-empty only when `status` is `blocked`. */\n  blockedBy: string[];\n}\n\nexport interface NextStep {\n  /** Stable — prose may change, this may not. */\n  code: string;\n  /** One sentence, actionable without reading any other field. */\n  statement: string;\n  /** The literal command to run. */\n  command: string;\n  artifact?: ArtifactId;\n  service?: string;\n  /** The repo-relative file the step is about, when it names one. */\n  path?: string;\n}\n\nexport type NextActionKind = \"command\" | \"edit\" | \"external-repo\" | \"human-review\";\nexport type NextActionCwd = \"configured-repo\" | \"docs-repo\" | \"service-repo\";\n\n/**\n * The machine contract beside the legacy `NextStep.command` string.\n *\n * `command` exists only when every argument is concrete. An edit names the\n * file and puts the old command in `after`, because that command grades the\n * authored work rather than performing it. `needs` is data the caller must\n * obtain; it is never smuggled into a shell-looking placeholder.\n */\nexport interface NextExecution {\n  kind: NextActionKind;\n  runnable: boolean;\n  cwd: NextActionCwd;\n  command?: string;\n  after?: string;\n  needs?: string[];\n}\n\nexport type ExecutableNextStep = NextStep & { execution: NextExecution };\n\n/**\n * What the record beside the feature says, without asking whether anyone should\n * believe the code. `stale` is its own state and not merely \"recorded\": the\n * feature moved after the answers were written, so the record answers questions\n * that are no longer the ones being asked — which is exactly why `loam verify\n * --record` refuses to merge into it.\n */\nexport interface VerificationState {\n  state: \"absent\" | \"unreadable\" | \"stale\" | \"recorded\";\n  /** The day the record was written, when there is a readable one. */\n  recorded: string | null;\n  /**\n   * `verify --json`'s own three-valued verdict, through `verificationVerdict` —\n   * not a fourth opinion computed here. `attested` is the one that matters to a\n   * reader of this command: complete, and resting on somebody's word about a\n   * test rather than on a run.\n   */\n  verdict: VerificationVerdict;\n  /** Every count below is `tallyRecord` — the record's `claims:` array, never its `summary:` block. */\n  claims: number;\n  confirmed: number;\n  unconfirmed: number;\n  /** Federated records only: claims nobody has answered yet. */\n  unanswered: number;\n  /** Of the confirmed, the scenario claims on an agent's word (`attestedClaims`). */\n  attested: number;\n}\n\n/**\n * A `loam archive`/`unarchive` that was killed mid-commit, read off the intent\n * journal `.loam-commit` leaves in the docs repo.\n *\n * It belongs in a projection that grades nothing because it is not a grade: it\n * is the one repository state where every OTHER answer this command gives is\n * about files that may be half-written. `doctor` blocks on it; `status` is what\n * an agent runs first, and it reported `done` over a half-merged repo — so it\n * says so too, from the same journal, and leads its steps with the repair.\n *\n * Read, never repaired: recovery happens under the docs lock inside `archive`\n * and `unarchive`, and `status` writes nothing and takes no lock.\n */\nexport interface InterruptedCommit {\n  /**\n   * Which command was committing, or null when the journal cannot be read at\n   * all. A sentence for a human, never a branch: version-2 journals carry any\n   * writer's name (rebase, vouch, new, gherkin), so an enum here would be a\n   * list this type has to chase.\n   */\n  command: string | null;\n  feature: string | null;\n  /** Who and when, so a human can place it against their own shell history. */\n  host: string | null;\n  pid: number | null;\n  at: string | null;\n  /** Docs-repo-relative paths that may hold half-written bytes. */\n  files: string[];\n  /** `.loam-commit` exists but does not parse — the worst case, because nothing can grade it. */\n  unreadable: boolean;\n  /** The command that recovers, or null when only a human can. */\n  recover: string | null;\n}\n\nexport interface FeatureStatusReport {\n  /**\n   * A killed commit in this docs repo, or null. Present on both forms: it is a\n   * fact about the repository, and every artifact row below it is a fact about\n   * files that repository may have half-written.\n   */\n  interrupted: InterruptedCommit | null;\n  feature: {\n    id: string;\n    dirName: string;\n    path: string;\n    archived: boolean;\n    /** The feature's own rollup, from the same vocabulary as its artifacts. */\n    stage: ArtifactStatus;\n    /** Every service the feature touches, whatever `--service` narrowed the view to. */\n    services: string[];\n    /** Active features that must archive before this one, from the dependency index. */\n    blockedBy: string[];\n  };\n  /** The `--service` narrowing, or null when the whole feature is in view. */\n  service: string | null;\n  artifacts: ArtifactState[];\n  /**\n   * The grade, from the same calls the two gates make: `featureCoherence`\n   * (archive), plus `featureProvenance` and the scenario-coverage check — the\n   * error sources `validate --feature` shares as functions. `ran` is false for\n   * an archived feature: its delta is already merged into the living docs, so\n   * re-grading it would compare a change against a world that has absorbed it.\n   */\n  checks: {\n    ran: boolean;\n    /**\n     * No error among the findings above — `loam validate --feature`'s verdict\n     * for every error source that is a shared function. It is not on its own\n     * what makes a feature shippable: `stage` and `next[]` take the union with\n     * archive's gating set, because a warning that gates is a warning this\n     * field reports as coherent.\n     */\n    coherent: boolean;\n    errors: number;\n    warnings: number;\n    /** How many findings would stop `loam archive` without `--approve`. */\n    gating: number;\n    /**\n     * Findings, not Issues: the set is wider than coherence now, and `gates` is\n     * resolved on every coherence finding so a consumer never re-implements the\n     * severity default. One breach reported by `validate` and by `status` has\n     * to arrive in one shape.\n     */\n    issues: Finding[];\n  };\n  verification: VerificationState;\n  /**\n   * The declared business flows the services IN VIEW are hops of — blast\n   * radius, and the only field here that is a fact about the fleet rather than\n   * about the feature.\n   *\n   * It narrows with `--service` exactly as `artifacts` and `next` do, because\n   * `--service` is a lens on what the reader is being asked to do next. What it\n   * must never do is go silently empty: `unreadable` is how it says that\n   * `architecture/` could not be read, which is a different fact from a fleet\n   * that draws no use cases and produces the identical empty list.\n   *\n   * The FLEET form has no equivalent, deliberately. That form grades nothing and\n   * is coarse by design, and a per-feature flow join over every feature in flight\n   * is exactly the per-feature cost it refuses to pay.\n   */\n  useCases: UseCaseBlastRadius;\n  next: NextStep[];\n}\n\nexport interface FleetFeatureState {\n  id: string;\n  dirName: string;\n  path: string;\n  stage: ArtifactStatus;\n  services: string[];\n  blockedBy: string[];\n  /** Artifacts the feature owes and has not written. Presence only — the fleet form grades nothing. */\n  missing: string[];\n  verification: VerificationState;\n}\n\nexport interface FleetStatusReport {\n  /** See {@link FeatureStatusReport.interrupted}. */\n  interrupted: InterruptedCommit | null;\n  /**\n   * Three disjoint buckets over `services/`, summing to `total`. Deliberately\n   * coarser than `list`'s maturity ladder, and deliberately not the same words:\n   * that ladder grades an adoption campaign rung by rung, this asks only\n   * whether there is anything here to build a feature on.\n   */\n  services: {\n    total: number;\n    /** No `spec.md` — nothing about this service is written down. */\n    undocumented: number;\n    /** Documented, with no vouch stamp behind it. */\n    draft: number;\n    /** `status: verified` with a `sources_digest` — a person stood behind it. */\n    vouched: number;\n    /**\n     * Of `vouched`, the ones read from a recorded SAMPLE rather than in full\n     * (`vouch_scope`, either axis) — a SUBSET: the three above still sum to `total`.\n     */\n    sampledVouched: number;\n  };\n  features: FleetFeatureState[];\n  /** Dependencies before consumers — which feature has to archive first. */\n  order: string[];\n  service: string | null;\n  next: NextStep[];\n}\n\n/** Nothing is written down: no living spec at all. Every other absence is partial adoption. */\nexport function undocumented(s: ServiceEntry): boolean {\n  return !s.has.spec;\n}\n\n/** A person stamped it — `loam vouch`'s exact postcondition, read back off the frontmatter. */\nexport function vouched(s: ServiceEntry): boolean {\n  return s.status === \"verified\" && s.sources.stamped;\n}\n"]}

package/dist/core/status/scan.js

@@ -0,0 +1,41 @@
+/**
+ * Reading a feature's per-service deltas without grading them. Both status
+ * forms draw on this one scan: it is how the artifact table and the fleet form
+ * decide which services owe a contract, and where the scenario steps come from.
+ */
+import { existsSync } from "node:fs";
+import { requirementsMissingScenarios } from "../document/scenarios.js";
+import {} from "../document/spec.js";
+import { repoPath } from "../envelope/json.js";
+import { featureSpecPaths, SPEC_AXES } from "../repo/paths.js";
+export async function scanDeltas(docsDir, feature, services, context) {
+    const out = [];
+    for (const svc of services) {
+        const p = featureSpecPaths(feature.dir, svc);
+        // SPEC_AXES already carries the prose name of each axis — "requirements"
+        // and "arch requirements" are its `label`s verbatim — so the pair is read
+        // from there rather than spelled again, and a service's status can never
+        // walk a different set of spec files than its validation does.
+        for (const [file, label] of SPEC_AXES.map((axis) => [p[axis.key], `${svc}: ${axis.label}`])) {
+            if (!existsSync(file))
+                continue;
+            const reqs = await context.readRequirements(file);
+            out.push({
+                service: svc,
+                path: repoPath(docsDir, file),
+                label,
+                bare: requirementsMissingScenarios(reqs),
+                scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),
+                operations: file === p.spec
+                    ? reqs.filter((r) => r.kind !== "REMOVED").reduce((n, r) => n + r.operations.length, 0)
+                    : 0,
+            });
+        }
+    }
+    return out;
+}
+/** Services this feature sends at least one operation to — see contracts.ts's `owesContract`. */
+export function governedServices(scans) {
+    return new Set(scans.filter((s) => s.operations > 0).map((s) => s.service));
+}
+//# sourceMappingURL=scan.js.map

package/dist/core/status/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/core/status/scan.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAyB/D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAgB,EAChB,OAAqB,EACrB,QAA2B,EAC3B,OAAqB;IAErB,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7C,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,+DAA+D;QAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CACvC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC,KAAK,EAAE,CAAU,CAC1D,EAAE,CAAC;YACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,SAAS;YAChC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC;gBACP,OAAO,EAAE,GAAG;gBACZ,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;gBAC7B,KAAK;gBACL,IAAI,EAAE,4BAA4B,CAAC,IAAI,CAAC;gBACxC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC3D,UAAU,EACR,IAAI,KAAK,CAAC,CAAC,IAAI;oBACb,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;oBACvF,CAAC,CAAC,CAAC;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC","sourcesContent":["/**\n * Reading a feature's per-service deltas without grading them. Both status\n * forms draw on this one scan: it is how the artifact table and the fleet form\n * decide which services owe a contract, and where the scenario steps come from.\n */\nimport { existsSync } from \"node:fs\";\nimport { requirementsMissingScenarios } from \"../document/scenarios.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { FeatureEntry } from \"../repo/entries.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../repo/paths.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\n\n/**\n * One read of each per-service delta, answering the three questions the two\n * status forms ask of it: which requirements carry no scenario (via the same\n * `requirementsMissingScenarios` every coverage check calls — REMOVED\n * requirements are exempt there and stay exempt here, content on its way out\n * owes no acceptance criteria), how many scenarios there are to generate a\n * suite from, and whether the delta governs any operation at all — which is\n * what decides whether the service is owed a contract.\n */\nexport interface DeltaScan {\n  service: string;\n  /** Repo-relative, and the file the steps point at. */\n  path: string;\n  /** validate's own label for this axis: `<svc>: requirements` / `<svc>: arch requirements`. */\n  label: string;\n  bare: Requirement[];\n  scenarios: number;\n  /** Operations the non-REMOVED requirements govern. `spec.md` only, like coherence's own `reqOps`. */\n  operations: number;\n}\n\nexport async function scanDeltas(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  services: PathableService[],\n  context: FleetContext,\n): Promise<DeltaScan[]> {\n  const out: DeltaScan[] = [];\n  for (const svc of services) {\n    const p = featureSpecPaths(feature.dir, svc);\n    // SPEC_AXES already carries the prose name of each axis — \"requirements\"\n    // and \"arch requirements\" are its `label`s verbatim — so the pair is read\n    // from there rather than spelled again, and a service's status can never\n    // walk a different set of spec files than its validation does.\n    for (const [file, label] of SPEC_AXES.map(\n      (axis) => [p[axis.key], `${svc}: ${axis.label}`] as const,\n    )) {\n      if (!existsSync(file)) continue;\n      const reqs = await context.readRequirements(file);\n      out.push({\n        service: svc,\n        path: repoPath(docsDir, file),\n        label,\n        bare: requirementsMissingScenarios(reqs),\n        scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),\n        operations:\n          file === p.spec\n            ? reqs.filter((r) => r.kind !== \"REMOVED\").reduce((n, r) => n + r.operations.length, 0)\n            : 0,\n      });\n    }\n  }\n  return out;\n}\n\n/** Services this feature sends at least one operation to — see contracts.ts's `owesContract`. */\nexport function governedServices(scans: DeltaScan[]): ReadonlySet<string> {\n  return new Set(scans.filter((s) => s.operations > 0).map((s) => s.service));\n}\n"]}

package/dist/core/status/verification.js

@@ -0,0 +1,201 @@
+import { featureChecklist } from "../verify/checklist.js";
+import { readVerificationState } from "../verify/file.js";
+import { attestedNotice, tallyRecord, verificationVerdict } from "../verify/record.js";
+/**
+ * Is the done-check discharged? `verificationVerdict`'s answer and nobody
+ * else's — status re-deriving it would be a fourth place the words "verified"
+ * are defined, and the day one of them changed (a scenario claim on an agent's
+ * word stopped counting) the reader's copy would be the one still saying yes.
+ * `attested` is deliberately NOT `done` here: it is complete work resting on an
+ * assertion, which is what `ready` has always meant — the document is right and
+ * the world has not caught up.
+ */
+export function fullyVerified(v) {
+    return v.verdict === "verified";
+}
+/**
+ * The record's own rung. `stale` and `unreadable` are `draft` because both mean
+ * the file on disk is the thing to fix; unconfirmed claims are `ready` because
+ * the file is fine and the answer lives in the code.
+ *
+ * All four states are spelled, `recorded` included, so the `never` below fails
+ * the build rather than the reader: a fifth record state added to
+ * {@link VerificationState} would otherwise fall through into the last branch
+ * and be graded by `fullyVerified` alone — silently answering `ready` about a
+ * record whose new state nobody here has decided a rung for.
+ */
+export function verificationStatus(v) {
+    if (v.state === "absent")
+        return "missing";
+    if (v.state === "unreadable" || v.state === "stale")
+        return "draft";
+    if (v.state === "recorded")
+        return fullyVerified(v) ? "done" : "ready";
+    const unreachable = v.state;
+    throw new Error(`verificationStatus: no rung for verification state '${String(unreachable)}'`);
+}
+/**
+ * Read the record and, only when there is one, ask whether it still answers
+ * this feature. The checklist is derived on demand and never speculatively: it
+ * loads the delta into a LikeC4 workspace, and paying that in order to print
+ * "no record" is the cost `list` refused for its verification column.
+ *
+ * An archived feature's record is frozen history — archive merged its
+ * operations into the living contract, so a re-derived checklist can only
+ * mismatch, and calling it stale would slander every feature that shipped.
+ */
+export async function verificationState(docsDir, feature, 
+// The invocation's read index, when the caller holds one. It reaches the
+// checklist derivation, whose enumerations and delta parse are memo hits
+// through it — the difference between one fleet walk per invocation and one
+// per feature for a caller grading several (`loam gate`'s check 3).
+fleet) {
+    const empty = {
+        recorded: null,
+        verdict: "unverified",
+        claims: 0,
+        confirmed: 0,
+        unconfirmed: 0,
+        unanswered: 0,
+        attested: 0,
+    };
+    const read = await readVerificationState(feature.dir);
+    if (read.state === "absent")
+        return { state: { state: "absent", ...empty }, notice: null };
+    // A record whose summary contradicts its own claims is refused by the reader
+    // itself (`verify.record-miscounted`), so this branch reports zeros rather
+    // than salvaging counts from a file nobody can say which half of was edited.
+    // Where there ARE counts they are `tallyRecord`'s, never the summary's — the
+    // block used to be copied out verbatim, and a record `verify --json` calls
+    // unverified read here as "11 of 11 confirmed".
+    if (read.state === "unreadable")
+        return { state: { state: "unreadable", ...empty }, notice: null };
+    const v = read.verification;
+    const stale = feature.archived
+        ? false
+        : (await featureChecklist(docsDir, feature.dir, feature.id, fleet)).digest !== v.checklist;
+    const tally = tallyRecord(v);
+    return {
+        state: {
+            state: stale ? "stale" : "recorded",
+            recorded: v.recorded,
+            verdict: verificationVerdict(tally, stale),
+            claims: tally.claims,
+            confirmed: tally.confirmed,
+            unconfirmed: tally.unconfirmed,
+            unanswered: tally.unanswered,
+            attested: tally.attested,
+        },
+        notice: attestedNotice(v.claims, feature.id),
+    };
+}
+export function verifyStep(id, verification, view) {
+    const { artifacts = [], services, boundService } = view;
+    const record = artifacts.find((a) => a.id === "verification");
+    const open = verification.unconfirmed + verification.unanswered;
+    // The code is spelled at each call site as a `code:` property rather than
+    // passed positionally, and the helper takes the whole pair: test/codes-drift.ts
+    // collects the vocabulary by reading the source for that exact shape, so a
+    // factory with a `code` PARAMETER would hide every code it emits from the one
+    // guard that checks they are documented. Same DRY-ness, visible to the guard.
+    const step = (s) => [
+        { ...s, command: `loam verify ${id} --json`, artifact: "verification", path: record.path },
+    ];
+    if (record.status === "blocked") {
+        return step({
+            code: "next.verify",
+            statement: `${id} has nothing to derive a checklist from yet — write the delta and the requirement deltas first.`,
+        });
+    }
+    if (verification.state === "absent") {
+        return step({
+            code: "next.verify",
+            statement: `Nothing has been verified for ${id} — derive the checklist and answer every claim with evidence.`,
+        });
+    }
+    if (verification.state === "unreadable") {
+        return step({
+            code: "next.verify",
+            statement: `${record.path} exists but does not read as a record — repair or delete it; nothing will overwrite it while it is unreadable.`,
+        });
+    }
+    if (verification.state === "stale") {
+        return step({
+            code: "next.verify",
+            statement: `${id} moved after ${record.path} was written — the record answers a checklist that is no longer the one being asked.`,
+        });
+    }
+    if (open > 0) {
+        // The recording form only when this repository is one of the services that
+        // owes an answer: `verify --record --service` binds the answers to THIS
+        // repo's HEAD and refuses anywhere else, so handing a docs-repo reader that
+        // command would name a step it cannot take.
+        return boundService !== undefined && services.includes(boundService)
+            ? [
+                {
+                    code: "next.attest-service",
+                    statement: `${open} of ${verification.claims} claim(s) on ${id} are open, and this repository is '${boundService}' — ` +
+                        `answer the ones filed under it, bound to this commit; the rest belong to their own repositories.`,
+                    command: `loam verify ${id} --record answers.json --service ${boundService}`,
+                    artifact: "verification",
+                    service: boundService,
+                    path: record.path,
+                },
+            ]
+            : step({
+                code: "next.verify-unconfirmed",
+                statement: `${open} of ${verification.claims} claim(s) on ${id} are not confirmed — close them from each affected service's own repository.`,
+            });
+    }
+    if (verification.claims === 0) {
+        return step({
+            code: "next.verify",
+            statement: `${record.path} answers no claims at all — nothing was asked, so nothing was checked; re-derive the checklist and see what this feature actually promises.`,
+        });
+    }
+    if (verification.verdict === "attested") {
+        return [
+            {
+                code: "next.verify-attested",
+                statement: `${verification.attested} of ${id}'s scenario claim(s) are confirmed on an agent's word, not on a test run ` +
+                    `(verify.scenario-attested) — answer them from a cucumber report, and the record stops resting on an assertion.`,
+                command: `loam verify ${id} --results <cucumber-report.json>`,
+                artifact: "verification",
+                path: record.path,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Where a test comes from. `loam gherkin` writes the .feature files whose green
+ * run is the only thing that may answer a `scenario.tested` claim, and it runs
+ * from the service's own repository — so the step exists wherever there are
+ * scenarios to generate from, and names the repository to run it in when that
+ * is not this one.
+ */
+export function testStep(id, verification, view) {
+    const { services, scans, boundService } = view;
+    if (fullyVerified(verification))
+        return [];
+    const withScenarios = [
+        ...new Set(scans.filter((s) => s.scenarios > 0 && services.includes(s.service)).map((s) => s.service)),
+    ];
+    if (withScenarios.length === 0)
+        return [];
+    const svc = boundService !== undefined && withScenarios.includes(boundService) ? boundService : withScenarios[0];
+    const here = svc === boundService;
+    return [
+        {
+            code: "next.generate-tests",
+            statement: `${id}'s delta for ${svc} carries scenarios that no test run has answered yet — generate the suite, then implement against it` +
+                (here
+                    ? "."
+                    : `. \`loam gherkin\` writes into the service's own repository, so run it from ${svc}'s${withScenarios.length > 1 ? ` (and likewise for ${withScenarios.slice(1).join(", ")})` : ""}.`),
+            command: `loam gherkin ${id} --service ${svc}`,
+            artifact: "spec",
+            service: svc,
+        },
+    ];
+}
+//# sourceMappingURL=verification.js.map

package/dist/core/status/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../../src/core/status/verification.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The verification record as `status` reads it: the rung the record stands on,\n * the projection of what it says, and the two `next[]` steps that discharge it\n * — where a test comes from, and what `loam verify` still wants answered.\n * Every verdict here is `core/verify/`'s own, re-read; nothing in this module is\n * a second definition of \"verified\".\n */\nimport type { FeatureEntry } from \"../repo/entries.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureChecklist } from \"../verify/checklist.js\";\nimport { readVerificationState } from \"../verify/file.js\";\nimport { attestedNotice, tallyRecord, type VerificationVerdict, type VerifyNotice, verificationVerdict } from \"../verify/record.js\";\nimport type { ArtifactState, ArtifactStatus, NextStep, VerificationState } from \"./report.js\";\nimport type { DeltaScan } from \"./scan.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * Is the done-check discharged? `verificationVerdict`'s answer and nobody\n * else's — status re-deriving it would be a fourth place the words \"verified\"\n * are defined, and the day one of them changed (a scenario claim on an agent's\n * word stopped counting) the reader's copy would be the one still saying yes.\n * `attested` is deliberately NOT `done` here: it is complete work resting on an\n * assertion, which is what `ready` has always meant — the document is right and\n * the world has not caught up.\n */\nexport function fullyVerified(v: VerificationState): boolean {\n  return v.verdict === \"verified\";\n}\n\n/**\n * The record's own rung. `stale` and `unreadable` are `draft` because both mean\n * the file on disk is the thing to fix; unconfirmed claims are `ready` because\n * the file is fine and the answer lives in the code.\n *\n * All four states are spelled, `recorded` included, so the `never` below fails\n * the build rather than the reader: a fifth record state added to\n * {@link VerificationState} would otherwise fall through into the last branch\n * and be graded by `fullyVerified` alone — silently answering `ready` about a\n * record whose new state nobody here has decided a rung for.\n */\nexport function verificationStatus(v: VerificationState): ArtifactStatus {\n  if (v.state === \"absent\") return \"missing\";\n  if (v.state === \"unreadable\" || v.state === \"stale\") return \"draft\";\n  if (v.state === \"recorded\") return fullyVerified(v) ? \"done\" : \"ready\";\n  const unreachable: never = v.state;\n  throw new Error(`verificationStatus: no rung for verification state '${String(unreachable)}'`);\n}\n\n/**\n * Read the record and, only when there is one, ask whether it still answers\n * this feature. The checklist is derived on demand and never speculatively: it\n * loads the delta into a LikeC4 workspace, and paying that in order to print\n * \"no record\" is the cost `list` refused for its verification column.\n *\n * An archived feature's record is frozen history — archive merged its\n * operations into the living contract, so a re-derived checklist can only\n * mismatch, and calling it stale would slander every feature that shipped.\n */\nexport async function verificationState(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  // The invocation's read index, when the caller holds one. It reaches the\n  // checklist derivation, whose enumerations and delta parse are memo hits\n  // through it — the difference between one fleet walk per invocation and one\n  // per feature for a caller grading several (`loam gate`'s check 3).\n  fleet?: FleetContext,\n): Promise<{ state: VerificationState; notice: VerifyNotice | null }> {\n  const empty = {\n    recorded: null,\n    verdict: \"unverified\" as VerificationVerdict,\n    claims: 0,\n    confirmed: 0,\n    unconfirmed: 0,\n    unanswered: 0,\n    attested: 0,\n  };\n  const read = await readVerificationState(feature.dir);\n  if (read.state === \"absent\") return { state: { state: \"absent\", ...empty }, notice: null };\n  // A record whose summary contradicts its own claims is refused by the reader\n  // itself (`verify.record-miscounted`), so this branch reports zeros rather\n  // than salvaging counts from a file nobody can say which half of was edited.\n  // Where there ARE counts they are `tallyRecord`'s, never the summary's — the\n  // block used to be copied out verbatim, and a record `verify --json` calls\n  // unverified read here as \"11 of 11 confirmed\".\n  if (read.state === \"unreadable\") return { state: { state: \"unreadable\", ...empty }, notice: null };\n\n  const v = read.verification;\n  const stale = feature.archived\n    ? false\n    : (await featureChecklist(docsDir, feature.dir, feature.id, fleet)).digest !== v.checklist;\n  const tally = tallyRecord(v);\n  return {\n    state: {\n      state: stale ? \"stale\" : \"recorded\",\n      recorded: v.recorded,\n      verdict: verificationVerdict(tally, stale),\n      claims: tally.claims,\n      confirmed: tally.confirmed,\n      unconfirmed: tally.unconfirmed,\n      unanswered: tally.unanswered,\n      attested: tally.attested,\n    },\n    notice: attestedNotice(v.claims, feature.id),\n  };\n}\n\n/**\n * The done-check step, or none. Four different situations reach `loam verify`\n * and they are not the same work — nothing recorded, a file that will not read,\n * a record the feature has moved out from under, and claims still open — so the\n * statement says which. The code splits only where the WORK splits: starting a\n * verification and finishing one are different jobs, and an agent that treats a\n * stale record as a finished one ships a feature nobody checked.\n */\n/** The narrowed view a step is written for: what to name, and to whom. */\nexport interface StepView {\n  artifacts?: ArtifactState[];\n  services: string[];\n  /** The service this repository is bound to, when a command is standing in one. */\n  boundService: string | undefined;\n}\n\nexport function verifyStep(id: string, verification: VerificationState, view: StepView): NextStep[] {\n  const { artifacts = [], services, boundService } = view;\n  const record = artifacts.find((a) => a.id === \"verification\")!;\n  const open = verification.unconfirmed + verification.unanswered;\n  // The code is spelled at each call site as a `code:` property rather than\n  // passed positionally, and the helper takes the whole pair: test/codes-drift.ts\n  // collects the vocabulary by reading the source for that exact shape, so a\n  // factory with a `code` PARAMETER would hide every code it emits from the one\n  // guard that checks they are documented. Same DRY-ness, visible to the guard.\n  const step = (s: { code: string; statement: string }): NextStep[] => [\n    { ...s, command: `loam verify ${id} --json`, artifact: \"verification\", path: record.path },\n  ];\n\n  if (record.status === \"blocked\") {\n    return step({\n      code: \"next.verify\",\n      statement: `${id} has nothing to derive a checklist from yet — write the delta and the requirement deltas first.`,\n    });\n  }\n  if (verification.state === \"absent\") {\n    return step({\n      code: \"next.verify\",\n      statement: `Nothing has been verified for ${id} — derive the checklist and answer every claim with evidence.`,\n    });\n  }\n  if (verification.state === \"unreadable\") {\n    return step({\n      code: \"next.verify\",\n      statement: `${record.path} exists but does not read as a record — repair or delete it; nothing will overwrite it while it is unreadable.`,\n    });\n  }\n  if (verification.state === \"stale\") {\n    return step({\n      code: \"next.verify\",\n      statement: `${id} moved after ${record.path} was written — the record answers a checklist that is no longer the one being asked.`,\n    });\n  }\n  if (open > 0) {\n    // The recording form only when this repository is one of the services that\n    // owes an answer: `verify --record --service` binds the answers to THIS\n    // repo's HEAD and refuses anywhere else, so handing a docs-repo reader that\n    // command would name a step it cannot take.\n    return boundService !== undefined && services.includes(boundService)\n      ? [\n          {\n            code: \"next.attest-service\",\n            statement:\n              `${open} of ${verification.claims} claim(s) on ${id} are open, and this repository is '${boundService}' — ` +\n              `answer the ones filed under it, bound to this commit; the rest belong to their own repositories.`,\n            command: `loam verify ${id} --record answers.json --service ${boundService}`,\n            artifact: \"verification\",\n            service: boundService,\n            path: record.path,\n          },\n        ]\n      : step({\n          code: \"next.verify-unconfirmed\",\n          statement: `${open} of ${verification.claims} claim(s) on ${id} are not confirmed — close them from each affected service's own repository.`,\n        });\n  }\n  if (verification.claims === 0) {\n    return step({\n      code: \"next.verify\",\n      statement: `${record.path} answers no claims at all — nothing was asked, so nothing was checked; re-derive the checklist and see what this feature actually promises.`,\n    });\n  }\n  if (verification.verdict === \"attested\") {\n    return [\n      {\n        code: \"next.verify-attested\",\n        statement:\n          `${verification.attested} of ${id}'s scenario claim(s) are confirmed on an agent's word, not on a test run ` +\n          `(verify.scenario-attested) — answer them from a cucumber report, and the record stops resting on an assertion.`,\n        command: `loam verify ${id} --results <cucumber-report.json>`,\n        artifact: \"verification\",\n        path: record.path,\n      },\n    ];\n  }\n  return [];\n}\n\n/**\n * Where a test comes from. `loam gherkin` writes the .feature files whose green\n * run is the only thing that may answer a `scenario.tested` claim, and it runs\n * from the service's own repository — so the step exists wherever there are\n * scenarios to generate from, and names the repository to run it in when that\n * is not this one.\n */\nexport function testStep(\n  id: string,\n  verification: VerificationState,\n  view: { services: string[]; scans: DeltaScan[]; boundService: string | undefined },\n): NextStep[] {\n  const { services, scans, boundService } = view;\n  if (fullyVerified(verification)) return [];\n  const withScenarios = [\n    ...new Set(scans.filter((s) => s.scenarios > 0 && services.includes(s.service)).map((s) => s.service)),\n  ];\n  if (withScenarios.length === 0) return [];\n  const svc = boundService !== undefined && withScenarios.includes(boundService) ? boundService : withScenarios[0]!;\n  const here = svc === boundService;\n  return [\n    {\n      code: \"next.generate-tests\",\n      statement:\n        `${id}'s delta for ${svc} carries scenarios that no test run has answered yet — generate the suite, then implement against it` +\n        (here\n          ? \".\"\n          : `. \\`loam gherkin\\` writes into the service's own repository, so run it from ${svc}'s${\n              withScenarios.length > 1 ? ` (and likewise for ${withScenarios.slice(1).join(\", \")})` : \"\"\n            }.`),\n      command: `loam gherkin ${id} --service ${svc}`,\n      artifact: \"spec\",\n      service: svc,\n    },\n  ];\n}\n"]}

package/dist/core/usecases/capability.js

@@ -0,0 +1,169 @@
+/**
+ * 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";
+/** 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 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 known = scan.model.known;
+    const out = new Set();
+    for (const view of scan.views) {
+        if (![...tags].some((tag) => claims(view, tag)))
+            continue;
+        for (const step of view.steps) {
+            for (const id of [step.source, step.target]) {
+                const service = scan.resolve(id);
+                if (known.has(service))
+                    out.add(service);
+            }
+        }
+    }
+    return [...out].sort(compareIds);
+}
+/**
+ * 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\";\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 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 known = scan.model.known;\n  const out = new Set<string>();\n  for (const view of scan.views) {\n    if (![...tags].some((tag) => claims(view, tag))) continue;\n    for (const step of view.steps) {\n      for (const id of [step.source, step.target]) {\n        const service = scan.resolve(id);\n        if (known.has(service)) out.add(service);\n      }\n    }\n  }\n  return [...out].sort(compareIds);\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"]}