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

package/dist/core/usecases/operations.js

@@ -0,0 +1,111 @@
+/**
+ * Which hops of which business flows a contract removal breaks.
+ *
+ * `loam diff --base` already answers "who still depends on this operation" with
+ * landscape edges and other services' living requirements. Both are true and
+ * neither is the sentence a reviewer wants: an edge is a line in a diagram and a
+ * requirement is a heading in somebody else's spec, while "step 4 of Checkout
+ * stops working" is the fact a human weighs a pull request against. This module
+ * is the join that produces that sentence, and it produces NOTHING ELSE — no
+ * finding, no code, no severity. `core/diff/victims.ts` folds its answers into
+ * the `details[]` of the two codes that already exist.
+ *
+ * ## Attributed is a victim; contested is a suspension
+ *
+ * The distinction is the whole reason this module is careful rather than a
+ * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op
+ * count across the relationships backing it:
+ *
+ *  - `attributed` with `op === X` means every relationship behind the hop agrees
+ *    the hop exercises X. Remove X and the flow breaks at that hop. That is
+ *    positive evidence, and it is a victim.
+ *  - `contested` means the relationships DISAGREE, so loam does not know which
+ *    operation the hop exercises. It must not claim the flow breaks — a guessed
+ *    victim reads exactly like a real one and turns a warn into an error on
+ *    somebody's PR — and it must not go silent either, because silence here is
+ *    the fail-open shape `ConsumerScan.suspended` exists to forbid. It is a
+ *    suspension: loam says it could not answer.
+ *
+ * A contested hop is suspended only when X is among its candidate operations.
+ * That is not a noise trade, it is the honest boundary: the candidates ARE the
+ * relationships backing the hop, so an operation none of them names is an
+ * operation the hop cannot be exercising under any reading of the disagreement.
+ * Suspending every contested hop in the fleet on every removal would report
+ * doubt loam does not actually have.
+ *
+ * An `unbacked` hop is neither. Nothing in the model backs it, so it names no
+ * operation of anybody's contract — `usecase.step-unbacked` is already the error
+ * that convicts it, and repeating that here would file a modelling defect
+ * against whoever happened to remove an endpoint.
+ */
+import { attributeStep } from "../c4/resolve/steps.js";
+import { hopPlace } from "./place.js";
+const EMPTY = { breaks: [], unsure: [] };
+/** Every hop of every graded use case, view order preserved, so output is stable. */
+function hops(scan) {
+    return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));
+}
+/**
+ * The flows one removed operation breaks, and the ones loam cannot answer for.
+ *
+ * An `unreadable` scan contributes NOTHING — neither break nor suspension — and
+ * that is `core/diff/victims.ts`'s own landscape doctrine applied one axis over:
+ * an unreadable fleet map proves nothing either way, `landscape.invalid` is
+ * validate's finding to make, and inventing doubt out of a parse error would
+ * point the reviewer at a file their change never touched. The caller reports
+ * the hole; this join stays quiet about it.
+ */
+export function hopsExercising(scan, removed) {
+    if (scan.kind !== "read")
+        return EMPTY;
+    const out = { breaks: [], unsure: [] };
+    for (const { view, step } of hops(scan)) {
+        const attribution = attributeStep(step, scan.model);
+        if (attribution.verdict === "unbacked")
+            continue;
+        // The callee, through the SAME resolver every other join in this run uses,
+        // so a hop drawn into a modelled container `payment.api` is filed against
+        // payment-service rather than against a service called "api".
+        if (scan.resolve(attribution.to) !== removed.provider)
+            continue;
+        if (attribution.verdict === "attributed") {
+            if (attribution.op === removed.op)
+                out.breaks.push(hopPlace(view, step));
+            continue;
+        }
+        if (!attribution.ops.includes(removed.op))
+            continue;
+        out.unsure.push(`${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +
+            `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +
+            `exercises '${removed.op}' could not be answered`);
+    }
+    return out;
+}
+/**
+ * The flows one removed message breaks.
+ *
+ * No suspension arm, and the asymmetry is a fact about the model rather than an
+ * omission: `attributeStep` contests OPERATIONS, because that is where two
+ * relationships between one pair of endpoints can disagree. A `consumes` edge
+ * names a message outright, so a hop either is backed by one or is not — there
+ * is no disagreement for loam to refuse to resolve.
+ *
+ * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the
+ * provider is the provider's own consumption, which leaves with the same change,
+ * so a hop backed only by that edge is not a victim of it.
+ */
+export function hopsConsuming(scan, removed) {
+    if (scan.kind !== "read")
+        return [];
+    const out = [];
+    for (const { view, step } of hops(scan)) {
+        const attribution = attributeStep(step, scan.model);
+        if (attribution.verdict === "unbacked")
+            continue;
+        const consumes = attribution.rels.some((rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider);
+        if (consumes)
+            out.push(hopPlace(view, step));
+    }
+    return out;
+}
+//# sourceMappingURL=operations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/core/usecases/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which hops of which business flows a contract removal breaks.\n *\n * `loam diff --base` already answers \"who still depends on this operation\" with\n * landscape edges and other services' living requirements. Both are true and\n * neither is the sentence a reviewer wants: an edge is a line in a diagram and a\n * requirement is a heading in somebody else's spec, while \"step 4 of Checkout\n * stops working\" is the fact a human weighs a pull request against. This module\n * is the join that produces that sentence, and it produces NOTHING ELSE — no\n * finding, no code, no severity. `core/diff/victims.ts` folds its answers into\n * the `details[]` of the two codes that already exist.\n *\n * ## Attributed is a victim; contested is a suspension\n *\n * The distinction is the whole reason this module is careful rather than a\n * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op\n * count across the relationships backing it:\n *\n *  - `attributed` with `op === X` means every relationship behind the hop agrees\n *    the hop exercises X. Remove X and the flow breaks at that hop. That is\n *    positive evidence, and it is a victim.\n *  - `contested` means the relationships DISAGREE, so loam does not know which\n *    operation the hop exercises. It must not claim the flow breaks — a guessed\n *    victim reads exactly like a real one and turns a warn into an error on\n *    somebody's PR — and it must not go silent either, because silence here is\n *    the fail-open shape `ConsumerScan.suspended` exists to forbid. It is a\n *    suspension: loam says it could not answer.\n *\n * A contested hop is suspended only when X is among its candidate operations.\n * That is not a noise trade, it is the honest boundary: the candidates ARE the\n * relationships backing the hop, so an operation none of them names is an\n * operation the hop cannot be exercising under any reading of the disagreement.\n * Suspending every contested hop in the fleet on every removal would report\n * doubt loam does not actually have.\n *\n * An `unbacked` hop is neither. Nothing in the model backs it, so it names no\n * operation of anybody's contract — `usecase.step-unbacked` is already the error\n * that convicts it, and repeating that here would file a modelling defect\n * against whoever happened to remove an endpoint.\n */\nimport { attributeStep } from \"../c4/resolve/steps.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { hopPlace } from \"./place.js\";\nimport type { UseCaseScan } from \"./fleet.js\";\n\n/**\n * What one contract removal does to the fleet's use cases.\n *\n * Two lists rather than `victims`/`suspended` — the vocabulary\n * `core/diff/victims.ts` uses — because this module answers about FLOWS and that\n * one answers about consumers. The caller does the folding, and naming the two\n * differently is what stops a reader taking this for a second implementation of\n * `ConsumerScan` (it is not: it never scans a document, and it cannot be\n * unreadable — the scan it runs over was already graded).\n */\nexport interface UseCaseHits {\n  /** Hops the removal breaks, each spelled by `hopPlace`. */\n  breaks: string[];\n  /** Hops loam refuses to grade, each saying why in its own sentence. */\n  unsure: string[];\n}\n\n/** The one removal a scan is being asked about. */\nexport interface RemovedOperation {\n  /** The service dropping it — the same id the diff files its findings under. */\n  provider: string;\n  /** The operationId leaving the contract. */\n  op: string;\n}\n\nconst EMPTY: UseCaseHits = { breaks: [], unsure: [] };\n\n/** Every hop of every graded use case, view order preserved, so output is stable. */\nfunction hops(scan: Extract<UseCaseScan, { kind: \"read\" }>): Array<{ view: ParsedView; step: ParsedStep }> {\n  return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));\n}\n\n/**\n * The flows one removed operation breaks, and the ones loam cannot answer for.\n *\n * An `unreadable` scan contributes NOTHING — neither break nor suspension — and\n * that is `core/diff/victims.ts`'s own landscape doctrine applied one axis over:\n * an unreadable fleet map proves nothing either way, `landscape.invalid` is\n * validate's finding to make, and inventing doubt out of a parse error would\n * point the reviewer at a file their change never touched. The caller reports\n * the hole; this join stays quiet about it.\n */\nexport function hopsExercising(scan: UseCaseScan, removed: RemovedOperation): UseCaseHits {\n  if (scan.kind !== \"read\") return EMPTY;\n  const out: UseCaseHits = { breaks: [], unsure: [] };\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    // The callee, through the SAME resolver every other join in this run uses,\n    // so a hop drawn into a modelled container `payment.api` is filed against\n    // payment-service rather than against a service called \"api\".\n    if (scan.resolve(attribution.to) !== removed.provider) continue;\n    if (attribution.verdict === \"attributed\") {\n      if (attribution.op === removed.op) out.breaks.push(hopPlace(view, step));\n      continue;\n    }\n    if (!attribution.ops.includes(removed.op)) continue;\n    out.unsure.push(\n      `${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +\n        `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +\n        `exercises '${removed.op}' could not be answered`,\n    );\n  }\n  return out;\n}\n\n/** The one message removal a scan is being asked about. */\nexport interface RemovedMessage {\n  /** The service dropping the declaration — the diff's own subject. */\n  provider: string;\n  /** The AsyncAPI message name leaving the contract. */\n  name: string;\n}\n\n/**\n * The flows one removed message breaks.\n *\n * No suspension arm, and the asymmetry is a fact about the model rather than an\n * omission: `attributeStep` contests OPERATIONS, because that is where two\n * relationships between one pair of endpoints can disagree. A `consumes` edge\n * names a message outright, so a hop either is backed by one or is not — there\n * is no disagreement for loam to refuse to resolve.\n *\n * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the\n * provider is the provider's own consumption, which leaves with the same change,\n * so a hop backed only by that edge is not a victim of it.\n */\nexport function hopsConsuming(scan: UseCaseScan, removed: RemovedMessage): string[] {\n  if (scan.kind !== \"read\") return [];\n  const out: string[] = [];\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    const consumes = attribution.rels.some(\n      (rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider,\n    );\n    if (consumes) out.push(hopPlace(view, step));\n  }\n  return out;\n}\n"]}

package/dist/core/usecases/place.js

@@ -0,0 +1,44 @@
+/**
+ * The document the view was written in, spelled repo-relative.
+ *
+ * `sourcePath` is relative to the LikeC4 PROJECT root, which for
+ * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere
+ * else. The caller owes one thing in exchange: only views that came from
+ * `loadProject` may be spelled with this, because the single-file loaders name
+ * every document after themselves (`source.c4`) and this function would then
+ * spell a path that has never existed.
+ *
+ * An ABSENT `sourcePath` names the directory rather than guessing a file.
+ * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so
+ * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting
+ * the field, falling back to `architecture/landscape.likec4` would put a false
+ * cross-reference in a message.
+ */
+export function viewFile(view) {
+    return view.sourcePath === undefined ? "architecture/" : `architecture/${view.sourcePath}`;
+}
+/**
+ * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.
+ *
+ * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which
+ * skips group brackets — so it counts what the author sees on the diagram, and
+ * a message naming step 4 is naming the fourth arrow.
+ */
+export function stepPlace(step) {
+    return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;
+}
+/**
+ * A use case and one of its hops, named the way a reader outside `validate`
+ * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'
+ * (architecture/usecases/checkout.likec4)`.
+ *
+ * The file goes LAST here and first in validate's `viewPlace`, and that is not
+ * an inconsistency to tidy away. A validate finding is a line in a report about
+ * documents, so it leads with the document; a diff victim is one entry in a
+ * `details[]` list whose other entries name edges and requirements, so it has to
+ * lead with the thing that broke and carry the file as the place to go fix it.
+ */
+export function hopPlace(view, step) {
+    return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;
+}
+//# sourceMappingURL=place.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/core/usecases/place.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACvC,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC;AACpG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,IAAgB;IACzD,OAAO,aAAa,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Where a use case lives and where one of its hops sits — the two spellings\n * every surface that mentions a use case has to agree on.\n *\n * They began in `commands/validate/fleet/usecases/place.ts`, beside the four\n * `usecase.*` graders that were their only reader. `loam diff` naming the flow a\n * removal breaks is the second reader and `loam delta`/`loam context` are the\n * third and fourth, and `core/` may not import from `commands/` (AGENTS.md), so\n * the alternative was a second spelling of `architecture/<sourcePath>` in core.\n * The two would drift silently and in the worst possible direction: a file path\n * in a message that no longer names the file the view is in is how the next\n * reader stops looking (docs/CODE-STYLE.md).\n *\n * What did NOT move is `viewPlace`, the `landscape: …` opening the validate\n * findings carry. That prefix is the name of a validate TARGET, so it is command\n * vocabulary — a `loam diff` finding is filed against a service, not against the\n * fleet map, and borrowing validate's prefix there would claim a target that run\n * does not have.\n */\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\n\n/**\n * The document the view was written in, spelled repo-relative.\n *\n * `sourcePath` is relative to the LikeC4 PROJECT root, which for\n * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere\n * else. The caller owes one thing in exchange: only views that came from\n * `loadProject` may be spelled with this, because the single-file loaders name\n * every document after themselves (`source.c4`) and this function would then\n * spell a path that has never existed.\n *\n * An ABSENT `sourcePath` names the directory rather than guessing a file.\n * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so\n * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting\n * the field, falling back to `architecture/landscape.likec4` would put a false\n * cross-reference in a message.\n */\nexport function viewFile(view: ParsedView): string {\n  return view.sourcePath === undefined ? \"architecture/\" : `architecture/${view.sourcePath}`;\n}\n\n/**\n * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.\n *\n * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which\n * skips group brackets — so it counts what the author sees on the diagram, and\n * a message naming step 4 is naming the fourth arrow.\n */\nexport function stepPlace(step: ParsedStep): string {\n  return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;\n}\n\n/**\n * A use case and one of its hops, named the way a reader outside `validate`\n * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'\n * (architecture/usecases/checkout.likec4)`.\n *\n * The file goes LAST here and first in validate's `viewPlace`, and that is not\n * an inconsistency to tidy away. A validate finding is a line in a report about\n * documents, so it leads with the document; a diff victim is one entry in a\n * `details[]` list whose other entries name edges and requirements, so it has to\n * lead with the thing that broke and carry the file as the place to go fix it.\n */\nexport function hopPlace(view: ParsedView, step: ParsedStep): string {\n  return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;\n}\n"]}

package/dist/core/usecases/touch.js

@@ -0,0 +1,101 @@
+/**
+ * Which business flows run through a service — the blast radius `loam delta`
+ * and `loam status` report beside the requirements and contracts a feature
+ * changes.
+ *
+ * ## The join is on ENDPOINTS, never on relationships
+ *
+ * `core/usecases/operations.ts` asks what a hop EXERCISES, which needs the
+ * relationship behind it. This asks something weaker and more useful early:
+ * does this hop mention the service at all? So it resolves the step's own two
+ * endpoints and stops — no `attributeStep`, no candidate scan.
+ *
+ * That is the difference between answering and not answering for the service a
+ * feature is about to INTRODUCE. A flow drawn for work that has not happened yet
+ * has hops nothing in the model backs — `usecase.step-unbacked` is validate's
+ * finding about exactly that, and it is an ERROR precisely because the fleet map
+ * has not caught up — and a relationship join reports such a flow as touching
+ * nobody. The endpoints are still there; the arrow is what is missing. An
+ * implementer reading a delta brief needs to know the flow exists most of all in
+ * that state, because that is the state their change is supposed to end.
+ *
+ * ## Everything a caller sees, it sees per HOP
+ *
+ * A view is reported only when at least one of its hops touches the addressed
+ * services, and only those hops travel. "Checkout touches you" is not actionable;
+ * "Checkout touches you at step 4" is where the reader goes to look.
+ */
+import { compareIds } from "../repo/entries.js";
+import { readUseCases } from "./fleet.js";
+import { viewFile } from "./place.js";
+/** The addressed services one hop mentions, source and target both, sorted and de-duplicated. */
+function touched(step, scan, services) {
+    const hit = [step.source, step.target].map((id) => scan.resolve(id)).filter((id) => services.has(id));
+    return [...new Set(hit)].sort(compareIds);
+}
+/** One view's touching hops, in the author's own step order — the order the diagram reads in. */
+function touchedView(view, scan, services) {
+    const steps = [];
+    for (const step of view.steps) {
+        const hit = touched(step, scan, services);
+        if (hit.length === 0)
+            continue;
+        steps.push({
+            ordinal: step.ordinal,
+            ...(step.title === undefined ? {} : { title: step.title }),
+            source: step.source,
+            target: step.target,
+            services: hit,
+        });
+    }
+    if (steps.length === 0)
+        return null;
+    return {
+        id: view.id,
+        ...(view.title === undefined ? {} : { title: view.title }),
+        file: viewFile(view),
+        tags: [...view.tags].sort(compareIds),
+        steps,
+    };
+}
+/**
+ * The flows touching a set of services, over a scan somebody already has.
+ *
+ * Separate from `useCaseBlastRadius` below because `core/pack/joins.ts` reads
+ * the scan ONCE and asks two different questions of it — this one and the
+ * capability claim join — and a second read there would be a second LikeC4
+ * project load inside a single `loam context`.
+ *
+ * An `unreadable` scan answers with nothing. Every caller pairs this with the
+ * scan's own health, because an empty list means "no flow mentions these
+ * services" and "nobody could look" only when read together.
+ */
+export function flowsTouching(scan, services) {
+    if (scan.kind !== "read")
+        return [];
+    return (scan.views
+        .map((view) => touchedView(view, scan, services))
+        .filter((flow) => flow !== null)
+        // Sorted by (file, view id) rather than reported in LikeC4's own record
+        // order: nothing in loam has measured that the parse preserves declaration
+        // order, so a payload ordered by it would reorder under a dependency bump.
+        .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id)));
+}
+/**
+ * The flows touching a set of services, read and joined in one call.
+ *
+ * The load underneath is `readUseCases`, which carries its own cheap gate: a
+ * fleet whose `architecture/` documents never mention the reserved tag prefix
+ * answers `{ flows: [] }` without starting LikeC4 at all. That gate is what
+ * makes this callable from `loam delta`, which sits in `/loam-implement`'s inner
+ * loop and would otherwise pay a Langium workspace spin-up on every iteration of
+ * somebody's afternoon.
+ */
+export async function useCaseBlastRadius(req) {
+    const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });
+    if (scan.kind !== "read") {
+        return { unreadable: true, ...(scan.errors[0] === undefined ? {} : { error: scan.errors[0] }), flows: [] };
+    }
+    return { unreadable: false, flows: flowsTouching(scan, req.services) };
+}
+//# sourceMappingURL=touch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"touch.js","sourceRoot":"","sources":["../../../src/core/usecases/touch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which business flows run through a service — the blast radius `loam delta`\n * and `loam status` report beside the requirements and contracts a feature\n * changes.\n *\n * ## The join is on ENDPOINTS, never on relationships\n *\n * `core/usecases/operations.ts` asks what a hop EXERCISES, which needs the\n * relationship behind it. This asks something weaker and more useful early:\n * does this hop mention the service at all? So it resolves the step's own two\n * endpoints and stops — no `attributeStep`, no candidate scan.\n *\n * That is the difference between answering and not answering for the service a\n * feature is about to INTRODUCE. A flow drawn for work that has not happened yet\n * has hops nothing in the model backs — `usecase.step-unbacked` is validate's\n * finding about exactly that, and it is an ERROR precisely because the fleet map\n * has not caught up — and a relationship join reports such a flow as touching\n * nobody. The endpoints are still there; the arrow is what is missing. An\n * implementer reading a delta brief needs to know the flow exists most of all in\n * that state, because that is the state their change is supposed to end.\n *\n * ## Everything a caller sees, it sees per HOP\n *\n * A view is reported only when at least one of its hops touches the addressed\n * services, and only those hops travel. \"Checkout touches you\" is not actionable;\n * \"Checkout touches you at step 4\" is where the reader goes to look.\n */\nimport { compareIds } from \"../repo/entries.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { readUseCases, type UseCaseScan } from \"./fleet.js\";\nimport { viewFile } from \"./place.js\";\n\n/** One hop of a flow that mentions a service the caller asked about. */\nexport interface TouchedStep {\n  /** The view's own leaf numbering — what the author sees on the diagram. */\n  ordinal: number;\n  title?: string;\n  /** The step's endpoints as the view declares them: element ids, already oriented. */\n  source: string;\n  target: string;\n  /**\n   * Which of the ADDRESSED services this hop mentions, sorted. Both, when a flow\n   * calls a service and it answers within the same addressed set.\n   */\n  services: string[];\n}\n\n/** One flow that touches the addressed services, with only the hops that do. */\nexport interface TouchedUseCase {\n  id: string;\n  title?: string;\n  /** Repo-relative document the view is written in — where the reader goes to change it. */\n  file: string;\n  /**\n   * The `#cap-` tags the view carries, verbatim and unresolved.\n   *\n   * Verbatim because resolving them means reading\n   * `architecture/capabilities.yaml`, and a slug is not injective — the join can\n   * legitimately answer \"two capabilities\" (core/capabilities/usecase-join.ts).\n   * A blast-radius list is not the place to make that call: `loam validate --all`\n   * already grades every tag with `usecase.capability-unresolved`, and a second\n   * resolution here would be a second answer to the same question.\n   */\n  tags: string[];\n  steps: TouchedStep[];\n}\n\n/**\n * The flows over a set of services, and whether loam could look at all.\n *\n * `unreadable` is a HOLE, in the sense `core/pack/pack.ts` uses the word: `flows`\n * is empty because `architecture/` did not parse, not because the fleet draws no\n * use cases. A consumer that cannot tell those apart reads \"no business flow\n * depends on this\" off a directory nobody could open, which is the vacuously\n * green answer every surface in loam is built to refuse.\n */\nexport interface UseCaseBlastRadius {\n  unreadable: boolean;\n  /** LikeC4's first message, so a reader knows which document to open. */\n  error?: string;\n  flows: TouchedUseCase[];\n}\n\nexport interface BlastRadiusRequest {\n  docsDir: DocsDir;\n  /**\n   * The fleet the element→service resolver is built with. Wider than `services`\n   * on purpose: it should be every service the resolver could legitimately land\n   * on, so a hop into a modelled container resolves to its owner rather than to\n   * the container's own title.\n   */\n  known: ReadonlySet<string>;\n  /** The services being asked about. */\n  services: ReadonlySet<string>;\n}\n\n/** The addressed services one hop mentions, source and target both, sorted and de-duplicated. */\nfunction touched(step: ParsedStep, scan: Extract<UseCaseScan, { kind: \"read\" }>, services: ReadonlySet<string>): string[] {\n  const hit = [step.source, step.target].map((id) => scan.resolve(id)).filter((id) => services.has(id));\n  return [...new Set(hit)].sort(compareIds);\n}\n\n/** One view's touching hops, in the author's own step order — the order the diagram reads in. */\nfunction touchedView(view: ParsedView, scan: Extract<UseCaseScan, { kind: \"read\" }>, services: ReadonlySet<string>): TouchedUseCase | null {\n  const steps: TouchedStep[] = [];\n  for (const step of view.steps) {\n    const hit = touched(step, scan, services);\n    if (hit.length === 0) continue;\n    steps.push({\n      ordinal: step.ordinal,\n      ...(step.title === undefined ? {} : { title: step.title }),\n      source: step.source,\n      target: step.target,\n      services: hit,\n    });\n  }\n  if (steps.length === 0) return null;\n  return {\n    id: view.id,\n    ...(view.title === undefined ? {} : { title: view.title }),\n    file: viewFile(view),\n    tags: [...view.tags].sort(compareIds),\n    steps,\n  };\n}\n\n/**\n * The flows touching a set of services, over a scan somebody already has.\n *\n * Separate from `useCaseBlastRadius` below because `core/pack/joins.ts` reads\n * the scan ONCE and asks two different questions of it — this one and the\n * capability claim join — and a second read there would be a second LikeC4\n * project load inside a single `loam context`.\n *\n * An `unreadable` scan answers with nothing. Every caller pairs this with the\n * scan's own health, because an empty list means \"no flow mentions these\n * services\" and \"nobody could look\" only when read together.\n */\nexport function flowsTouching(scan: UseCaseScan, services: ReadonlySet<string>): TouchedUseCase[] {\n  if (scan.kind !== \"read\") return [];\n  return (\n    scan.views\n      .map((view) => touchedView(view, scan, services))\n      .filter((flow): flow is TouchedUseCase => flow !== null)\n      // Sorted by (file, view id) rather than reported in LikeC4's own record\n      // order: nothing in loam has measured that the parse preserves declaration\n      // order, so a payload ordered by it would reorder under a dependency bump.\n      .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id))\n  );\n}\n\n/**\n * The flows touching a set of services, read and joined in one call.\n *\n * The load underneath is `readUseCases`, which carries its own cheap gate: a\n * fleet whose `architecture/` documents never mention the reserved tag prefix\n * answers `{ flows: [] }` without starting LikeC4 at all. That gate is what\n * makes this callable from `loam delta`, which sits in `/loam-implement`'s inner\n * loop and would otherwise pay a Langium workspace spin-up on every iteration of\n * somebody's afternoon.\n */\nexport async function useCaseBlastRadius(req: BlastRadiusRequest): Promise<UseCaseBlastRadius> {\n  const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });\n  if (scan.kind !== \"read\") {\n    return { unreadable: true, ...(scan.errors[0] === undefined ? {} : { error: scan.errors[0] }), flows: [] };\n  }\n  return { unreadable: false, flows: flowsTouching(scan, req.services) };\n}\n"]}

package/dist/core/verify/answers.js

@@ -0,0 +1,173 @@
+/**
+ * The answers, and the one thing loam checks about them.
+ *
+ * loam does not judge an answer. It cannot: it never read the code. What it
+ * guarantees is that every question was asked and that every answer sits next
+ * to the question it answers — so an answer set that does not correspond to the
+ * current checklist is refused rather than merged. An unchecked claim must
+ * never be able to masquerade as checked, and that refusal is `checkAnswers`.
+ *
+ * A scenario claim is answered mechanically wherever it can be: `--results`
+ * reads a cucumber JSON report and matches it by the digest tag `loam gherkin`
+ * stamped, and only a green run confirms one (`core/results.ts`). Where it
+ * cannot — a legacy service whose suite is months away, which is the fleet loam
+ * exists for — `--record` may still take an agent's word for it, and
+ * `./record.ts` marks that answer attested rather than run.
+ */
+import { isRecord } from "../kernel/records.js";
+import {} from "./checklist.js";
+import {} from "./pins/pin.js";
+/**
+ * Two verdicts, deliberately. Anything an agent cannot show evidence for is
+ * unconfirmed — a third value for "not applicable" would absorb every claim
+ * nobody wanted to answer.
+ */
+export const VERDICTS = ["confirmed", "unconfirmed"];
+/**
+ * Who answered a claim: the `runner` (a cucumber report's digest-tagged
+ * scenarios, matched mechanically by `--results`), the `external-runner` (an
+ * API contract-test report's operationId-matched entries, matched mechanically
+ * by `--contract-results` — external because loam did not generate the suite
+ * the way it generates the gherkin, so the join key is the operationId the
+ * claim asserts rather than a digest loam stamped), or an `agent` (somebody's
+ * word about the code, taken back by `--record`). On the record so a reviewer
+ * can tell a green run from an assertion. `external-runner` never answers a
+ * `scenario.tested` claim, which is what keeps the attested boundary —
+ * `attestedClaims` in `./record.ts` — exactly where it was.
+ */
+export const ANSWERED_BY = ["runner", "external-runner", "agent"];
+/**
+ * Accept an answer set only if it answers THIS checklist: every claim once, no
+ * claim twice, nothing extra, and no "confirmed" that shows nothing.
+ *
+ * The refusals are the point of the command. If a stale or partial answer file
+ * could be recorded, `verification.yaml` would say a claim was checked when
+ * nobody ever asked it — and a record that can lie is worse than no record,
+ * because it looks like evidence.
+ *
+ * `runnerOwned` is the composition rule under `--results` and
+ * `--contract-results`: ids a mechanical report answers — scenario claims under
+ * the first flag, api.exposes claims under the second — which an answers file
+ * must therefore not touch. An entry naming one refuses with its own diagnosis
+ * — the id IS on the feature's checklist, so calling it unknown would send the
+ * caller hunting a staleness that is not there. `--diff-answers`
+ * (commands/verify/cross/diff.ts) calls this with it UNSET on purpose: under a
+ * diff both agents answer everything in scope, scenario claims included,
+ * because the diff consults no report — so making scenario claims runner-only
+ * even without `--results` would break that lens.
+ *
+ * `context` is what turns the last line from a circle into an instruction. In a
+ * fleet the commonest way to "miss" a claim is that it is not yours: the
+ * checklist spans ten repositories and this one can only answer its own. Told
+ * only to "answer the claims it lists", an agent in the payment-service repo
+ * re-runs verify, sees the same checkout-web claims it cannot speak for, and
+ * either loops or invents evidence. So when every unanswered claim belongs to
+ * another service, say THAT, and name the command that records them.
+ */
+export function checkAnswers(claims, raw, runnerOwned, context) {
+    const refuse = (code, message) => ({ ok: false, code, message });
+    const list = Array.isArray(raw)
+        ? raw
+        : isRecord(raw) && Array.isArray(raw["answers"])
+            ? raw["answers"]
+            : null;
+    if (list === null) {
+        return refuse("answers-unreadable", "Expected a JSON array of answers, or an object with an `answers` array: " +
+            `[{ "id": "...", "verdict": "confirmed", "evidence": ["file:line"] }]`);
+    }
+    const answers = [];
+    for (const [i, entry] of list.entries()) {
+        const where = `answer ${i + 1}`;
+        if (!isRecord(entry))
+            return refuse("answers-unreadable", `${where} is not an object`);
+        const id = entry["id"];
+        if (typeof id !== "string" || id.length === 0) {
+            return refuse("answers-unreadable", `${where} has no claim id`);
+        }
+        const verdict = entry["verdict"];
+        if (typeof verdict !== "string" || !VERDICTS.includes(verdict)) {
+            return refuse("answers-unreadable", `${where} ('${id}') has verdict ${JSON.stringify(verdict)} — expected one of ${VERDICTS.join(", ")}`);
+        }
+        const note = typeof entry["note"] === "string" ? entry["note"].trim() : "";
+        answers.push({
+            id,
+            verdict: verdict,
+            evidence: stringList(entry["evidence"]),
+            ...(note.length > 0 ? { note } : {}),
+            answered_by: "agent",
+        });
+    }
+    const byId = new Map();
+    const twice = [];
+    for (const a of answers) {
+        if (byId.has(a.id))
+            twice.push(a.id);
+        else
+            byId.set(a.id, a);
+    }
+    const known = new Set(claims.map((c) => c.id));
+    const strayIds = [...new Set(answers.map((a) => a.id).filter((id) => !known.has(id)))];
+    const runnerHit = strayIds.filter((id) => runnerOwned?.has(id) === true);
+    const unknown = strayIds.filter((id) => runnerOwned?.has(id) !== true);
+    const missingClaims = claims.filter((c) => !byId.has(c.id));
+    const missing = missingClaims.map((c) => c.id);
+    if (runnerHit.length + unknown.length + missing.length + twice.length > 0) {
+        const parts = [
+            runnerHit.length > 0
+                ? `${runnerHit.length} answer(s) name claim(s) a report owns under --results or --contract-results: ${runnerHit.join(", ")} — the report answers those; take them out of the answers file`
+                : "",
+            unknown.length > 0 ? `${unknown.length} answer(s) name a claim that is not on the checklist: ${unknown.join(", ")}` : "",
+            missing.length > 0 ? `${missing.length} claim(s) have no answer: ${missing.join(", ")}` : "",
+            twice.length > 0 ? `${twice.length} claim(s) answered more than once: ${[...new Set(twice)].join(", ")}` : "",
+        ].filter((s) => s.length > 0);
+        return refuse("answers-mismatch", `These answers do not match the checklist — ${parts.join("; ")}. ` +
+            missingAdvice(missingClaims, claims.filter((c) => byId.has(c.id)), context));
+    }
+    const unevidenced = claims
+        .map((c) => byId.get(c.id))
+        .filter((a) => a.verdict === "confirmed" && a.evidence.length === 0)
+        .map((a) => a.id);
+    if (unevidenced.length > 0) {
+        return refuse("answers-unevidenced", `${unevidenced.length} claim(s) are confirmed with no evidence: ${unevidenced.join(", ")}. A confirmation with nothing behind it is an assertion — give a file:line, or answer 'unconfirmed'.`);
+    }
+    // Checklist order, not the order they were written in: the record reads in the
+    // order the questions were asked, whatever the agent did.
+    return { ok: true, answers: claims.map((c) => byId.get(c.id)) };
+}
+/**
+ * The last sentence of an `answers-mismatch`. "Re-run and answer the claims it
+ * lists" is sound advice only when the caller CAN answer them. In a fleet the
+ * checklist is federated — a feature's claims are filed under the service whose
+ * code answers them — so the honest diagnosis for a repo that answered
+ * everything it owns is "the rest is not yours", together with the form that
+ * records the rest. Anything else sends the caller round the same loop.
+ */
+function missingAdvice(missing, answered, context) {
+    const generic = "Re-run `loam verify` and answer the claims it lists.";
+    if (context === undefined || missing.length === 0 || answered.length === 0)
+        return generic;
+    // The signature of "I answered mine and the rest is not mine": the services
+    // that own the unanswered claims and the services that own the answered ones
+    // do not overlap. A single-service checklist with one claim forgotten fails
+    // this test and keeps the generic advice, which is the right advice there —
+    // that claim really is the caller's to answer.
+    const owners = [...new Set(missing.map((c) => c.subject))].sort();
+    const covered = new Set(answered.map((c) => c.subject));
+    if (owners.some((s) => covered.has(s)))
+        return generic;
+    const form = `\`loam verify ${context.feature} --record answers.json --service <svc>\``;
+    const mine = context.service;
+    return mine === undefined
+        ? `Those claims are owned by ${owners.join(", ")} — each service attests its own from its own repository (${form}); ` +
+            "this all-at-once form has to answer the whole checklist in one file."
+        : `Every unanswered claim belongs to a different service (${owners.join(", ")}) and this repository can only attest '${mine}' — ` +
+            `run ${form} in each of those repositories instead.`;
+}
+function stringList(v) {
+    if (typeof v === "string")
+        return v.trim().length > 0 ? [v.trim()] : [];
+    if (!Array.isArray(v))
+        return [];
+    return v.map((x) => String(x).trim()).filter((s) => s.length > 0);
+}
+//# sourceMappingURL=answers.js.map

package/dist/core/verify/answers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answers.js","sourceRoot":"","sources":["../../../src/core/verify/answers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The answers, and the one thing loam checks about them.\n *\n * loam does not judge an answer. It cannot: it never read the code. What it\n * guarantees is that every question was asked and that every answer sits next\n * to the question it answers — so an answer set that does not correspond to the\n * current checklist is refused rather than merged. An unchecked claim must\n * never be able to masquerade as checked, and that refusal is `checkAnswers`.\n *\n * A scenario claim is answered mechanically wherever it can be: `--results`\n * reads a cucumber JSON report and matches it by the digest tag `loam gherkin`\n * stamped, and only a green run confirms one (`core/results.ts`). Where it\n * cannot — a legacy service whose suite is months away, which is the fleet loam\n * exists for — `--record` may still take an agent's word for it, and\n * `./record.ts` marks that answer attested rather than run.\n */\nimport { isRecord } from \"../kernel/records.js\";\nimport { type Claim } from \"./checklist.js\";\nimport { type EvidencePin } from \"./pins/pin.js\";\n\n/**\n * Two verdicts, deliberately. Anything an agent cannot show evidence for is\n * unconfirmed — a third value for \"not applicable\" would absorb every claim\n * nobody wanted to answer.\n */\nexport const VERDICTS = [\"confirmed\", \"unconfirmed\"] as const;\nexport type Verdict = (typeof VERDICTS)[number];\n\n/**\n * Who answered a claim: the `runner` (a cucumber report's digest-tagged\n * scenarios, matched mechanically by `--results`), the `external-runner` (an\n * API contract-test report's operationId-matched entries, matched mechanically\n * by `--contract-results` — external because loam did not generate the suite\n * the way it generates the gherkin, so the join key is the operationId the\n * claim asserts rather than a digest loam stamped), or an `agent` (somebody's\n * word about the code, taken back by `--record`). On the record so a reviewer\n * can tell a green run from an assertion. `external-runner` never answers a\n * `scenario.tested` claim, which is what keeps the attested boundary —\n * `attestedClaims` in `./record.ts` — exactly where it was.\n */\nexport const ANSWERED_BY = [\"runner\", \"external-runner\", \"agent\"] as const;\nexport type AnsweredBy = (typeof ANSWERED_BY)[number];\n\nexport interface Answer {\n  id: string;\n  verdict: Verdict;\n  /** Where it can be seen — `file:line`, or a report scenario for the runner. Required for `confirmed`. */\n  evidence: string[];\n  note?: string;\n  answered_by: AnsweredBy;\n  /**\n   * loam's own stamp, never caller input: `validateServiceEvidence` computes\n   * these from the attested commit's blobs and the record path attaches them.\n   * `checkAnswers` below deliberately never reads the field, so an\n   * `evidence_pins` key in an answers FILE is ignored, not honored — an agent\n   * must not be able to hand loam a pin loam did not derive.\n   */\n  evidence_pins?: EvidencePin[];\n}\n\n/** Why an answer set was refused. Each names a different way it fails to answer. */\nexport type AnswerRefusal = \"answers-unreadable\" | \"answers-mismatch\" | \"answers-unevidenced\";\n\nexport type AnswerCheck =\n  /** The answers, re-ordered to the checklist, one per claim. */\n  | { ok: true; answers: Answer[] }\n  | { ok: false; code: AnswerRefusal; message: string };\n\n/**\n * Accept an answer set only if it answers THIS checklist: every claim once, no\n * claim twice, nothing extra, and no \"confirmed\" that shows nothing.\n *\n * The refusals are the point of the command. If a stale or partial answer file\n * could be recorded, `verification.yaml` would say a claim was checked when\n * nobody ever asked it — and a record that can lie is worse than no record,\n * because it looks like evidence.\n *\n * `runnerOwned` is the composition rule under `--results` and\n * `--contract-results`: ids a mechanical report answers — scenario claims under\n * the first flag, api.exposes claims under the second — which an answers file\n * must therefore not touch. An entry naming one refuses with its own diagnosis\n * — the id IS on the feature's checklist, so calling it unknown would send the\n * caller hunting a staleness that is not there. `--diff-answers`\n * (commands/verify/cross/diff.ts) calls this with it UNSET on purpose: under a\n * diff both agents answer everything in scope, scenario claims included,\n * because the diff consults no report — so making scenario claims runner-only\n * even without `--results` would break that lens.\n *\n * `context` is what turns the last line from a circle into an instruction. In a\n * fleet the commonest way to \"miss\" a claim is that it is not yours: the\n * checklist spans ten repositories and this one can only answer its own. Told\n * only to \"answer the claims it lists\", an agent in the payment-service repo\n * re-runs verify, sees the same checkout-web claims it cannot speak for, and\n * either loops or invents evidence. So when every unanswered claim belongs to\n * another service, say THAT, and name the command that records them.\n */\nexport function checkAnswers(\n  claims: Claim[],\n  raw: unknown,\n  runnerOwned?: ReadonlySet<string>,\n  context?: { feature: string; service?: string },\n): AnswerCheck {\n  const refuse = (code: AnswerRefusal, message: string): AnswerCheck => ({ ok: false, code, message });\n\n  const list = Array.isArray(raw)\n    ? raw\n    : isRecord(raw) && Array.isArray(raw[\"answers\"])\n      ? (raw[\"answers\"] as unknown[])\n      : null;\n  if (list === null) {\n    return refuse(\n      \"answers-unreadable\",\n      \"Expected a JSON array of answers, or an object with an `answers` array: \" +\n        `[{ \"id\": \"...\", \"verdict\": \"confirmed\", \"evidence\": [\"file:line\"] }]`,\n    );\n  }\n\n  const answers: Answer[] = [];\n  for (const [i, entry] of list.entries()) {\n    const where = `answer ${i + 1}`;\n    if (!isRecord(entry)) return refuse(\"answers-unreadable\", `${where} is not an object`);\n    const id = entry[\"id\"];\n    if (typeof id !== \"string\" || id.length === 0) {\n      return refuse(\"answers-unreadable\", `${where} has no claim id`);\n    }\n    const verdict = entry[\"verdict\"];\n    if (typeof verdict !== \"string\" || !(VERDICTS as readonly string[]).includes(verdict)) {\n      return refuse(\n        \"answers-unreadable\",\n        `${where} ('${id}') has verdict ${JSON.stringify(verdict)} — expected one of ${VERDICTS.join(\", \")}`,\n      );\n    }\n    const note = typeof entry[\"note\"] === \"string\" ? entry[\"note\"].trim() : \"\";\n    answers.push({\n      id,\n      verdict: verdict as Verdict,\n      evidence: stringList(entry[\"evidence\"]),\n      ...(note.length > 0 ? { note } : {}),\n      answered_by: \"agent\",\n    });\n  }\n\n  const byId = new Map<string, Answer>();\n  const twice: string[] = [];\n  for (const a of answers) {\n    if (byId.has(a.id)) twice.push(a.id);\n    else byId.set(a.id, a);\n  }\n  const known = new Set(claims.map((c) => c.id));\n  const strayIds = [...new Set(answers.map((a) => a.id).filter((id) => !known.has(id)))];\n  const runnerHit = strayIds.filter((id) => runnerOwned?.has(id) === true);\n  const unknown = strayIds.filter((id) => runnerOwned?.has(id) !== true);\n  const missingClaims = claims.filter((c) => !byId.has(c.id));\n  const missing = missingClaims.map((c) => c.id);\n  if (runnerHit.length + unknown.length + missing.length + twice.length > 0) {\n    const parts = [\n      runnerHit.length > 0\n        ? `${runnerHit.length} answer(s) name claim(s) a report owns under --results or --contract-results: ${runnerHit.join(\", \")} — the report answers those; take them out of the answers file`\n        : \"\",\n      unknown.length > 0 ? `${unknown.length} answer(s) name a claim that is not on the checklist: ${unknown.join(\", \")}` : \"\",\n      missing.length > 0 ? `${missing.length} claim(s) have no answer: ${missing.join(\", \")}` : \"\",\n      twice.length > 0 ? `${twice.length} claim(s) answered more than once: ${[...new Set(twice)].join(\", \")}` : \"\",\n    ].filter((s) => s.length > 0);\n    return refuse(\n      \"answers-mismatch\",\n      `These answers do not match the checklist — ${parts.join(\"; \")}. ` +\n        missingAdvice(missingClaims, claims.filter((c) => byId.has(c.id)), context),\n    );\n  }\n\n  const unevidenced = claims\n    .map((c) => byId.get(c.id)!)\n    .filter((a) => a.verdict === \"confirmed\" && a.evidence.length === 0)\n    .map((a) => a.id);\n  if (unevidenced.length > 0) {\n    return refuse(\n      \"answers-unevidenced\",\n      `${unevidenced.length} claim(s) are confirmed with no evidence: ${unevidenced.join(\", \")}. A confirmation with nothing behind it is an assertion — give a file:line, or answer 'unconfirmed'.`,\n    );\n  }\n\n  // Checklist order, not the order they were written in: the record reads in the\n  // order the questions were asked, whatever the agent did.\n  return { ok: true, answers: claims.map((c) => byId.get(c.id)!) };\n}\n\n/**\n * The last sentence of an `answers-mismatch`. \"Re-run and answer the claims it\n * lists\" is sound advice only when the caller CAN answer them. In a fleet the\n * checklist is federated — a feature's claims are filed under the service whose\n * code answers them — so the honest diagnosis for a repo that answered\n * everything it owns is \"the rest is not yours\", together with the form that\n * records the rest. Anything else sends the caller round the same loop.\n */\nfunction missingAdvice(\n  missing: Claim[],\n  answered: Claim[],\n  context?: { feature: string; service?: string },\n): string {\n  const generic = \"Re-run `loam verify` and answer the claims it lists.\";\n  if (context === undefined || missing.length === 0 || answered.length === 0) return generic;\n  // The signature of \"I answered mine and the rest is not mine\": the services\n  // that own the unanswered claims and the services that own the answered ones\n  // do not overlap. A single-service checklist with one claim forgotten fails\n  // this test and keeps the generic advice, which is the right advice there —\n  // that claim really is the caller's to answer.\n  const owners = [...new Set(missing.map((c) => c.subject))].sort();\n  const covered = new Set(answered.map((c) => c.subject));\n  if (owners.some((s) => covered.has(s))) return generic;\n  const form = `\\`loam verify ${context.feature} --record answers.json --service <svc>\\``;\n  const mine = context.service;\n  return mine === undefined\n    ? `Those claims are owned by ${owners.join(\", \")} — each service attests its own from its own repository (${form}); ` +\n        \"this all-at-once form has to answer the whole checklist in one file.\"\n    : `Every unanswered claim belongs to a different service (${owners.join(\", \")}) and this repository can only attest '${mine}' — ` +\n        `run ${form} in each of those repositories instead.`;\n}\n\nfunction stringList(v: unknown): string[] {\n  if (typeof v === \"string\") return v.trim().length > 0 ? [v.trim()] : [];\n  if (!Array.isArray(v)) return [];\n  return v.map((x) => String(x).trim()).filter((s) => s.length > 0);\n}\n\n"]}