@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/core/verify/checklist.js

@@ -28,7 +28,8 @@ import { readFile } from "node:fs/promises";
 import { readAsyncapi } from "../asyncapi/read.js";
 import {} from "../c4/likec4.js";
 import { elementService, serviceResolver } from "../c4/resolve/service.js";
-import { ACTOR_KINDS } from "../vocabulary/maturity.js";
+import { ACTOR_KINDS, INFRA_KINDS } from "../vocabulary/maturity.js";
+import { scenarioGherkin } from "../vocabulary/steps.js";
 import { operationIds, operations } from "../openapi/doc.js";
 import { featurePaths, featureSpecPaths } from "../repo/paths.js";
 import { locateServicePaths } from "../repo/service-target.js";
@@ -78,25 +79,57 @@ export async function featureChecklist(docsDir, featureDir, featureId, fleet) {
         // reports it; inventing claims out of a broken document would only add noise.
         if (res.errors.length === 0) {
             const elements = res.elements;
+            // The enumerated fleet — `services/` plus this feature's own `specs/`
+            // directories, the only place a service the feature INTRODUCES has a
+            // directory at all. Built once, above both readers below, because they
+            // must not disagree: the skip loop asks whether an element STANDS FOR a
+            // service, and the resolver asks WHICH service an endpoint belongs to,
+            // and a set that answered the second question only left the first one
+            // reading a title as unknown that the very next line resolved.
+            const known = new Set([
+                ...(await enumeratedServiceIds(docsDir, ctx)),
+                ...specServices,
+            ]);
             for (const e of elements) {
                 if (!e.tags.includes(featureId))
                     continue;
-                // A dotted id is a container INSIDE a service, and an actor is nobody's
-                // repository. Neither is a service that has to exist.
-                if (e.id.includes(".") || ACTOR_KINDS.has(e.kind.toLowerCase()))
+                // A dotted id is a container INSIDE a service, an actor is nobody's
+                // repository, and the fleet's own infrastructure — a `database`,
+                // `queue`, `topic`, `cache` or `bucket` — has no repository either.
+                // None of the three is a service that has to exist.
+                //
+                // The infra skip closes a claim no repository could ever answer: a
+                // delta that draws a fleet-level `database` minted `service.exists` for
+                // it, and `loam verify` then asked somebody to point at the code that
+                // proves a Postgres has a services/ directory. It is the SAME shape as
+                // the container-and-actor skips beside it — an element that is not a
+                // team's system — not a new kind of exemption.
+                //
+                // STANDING FOR A SERVICE still wins, because that is a claim about
+                // this repo rather than a guess at one, and it is the same predicate
+                // every other surface applies — `commands/validate/fleet/census.ts`'s
+                // `standsForService`, spelled here rather than imported because core
+                // may not reach into commands. Both of its rungs matter: a `database`
+                // carrying `metadata { service '<id>' }` names a directory the author
+                // says exists, and one whose TITLE names a real `services/<id>/` names
+                // a directory the enumeration just read. Testing the binding alone made
+                // an adopted store a service on every other surface and infrastructure
+                // here, so its `service.exists` claim silently went missing from the
+                // checklist that is supposed to hold every promise the feature made.
+                const standsFor = e.service !== undefined || known.has(e.title);
+                const infra = !standsFor && INFRA_KINDS.has(e.kind.toLowerCase());
+                if (e.id.includes(".") || ACTOR_KINDS.has(e.kind.toLowerCase()) || infra)
                     continue;
                 const svc = elementService(e);
                 exists.push(claim("service.exists", svc, [svc], `service '${svc}' exists`));
             }
-            // The enumerated fleet — `services/` plus this feature's own `specs/`
-            // directories, the only place a service the feature INTRODUCES has a
-            // directory at all — rides into the resolver so a claim about an edge
-            // drawn into a modelled container names the service that owns it. A
-            // claim against a service called "api" that has never existed is one no
+            // That same set rides into the resolver so a claim about an edge drawn
+            // into a modelled container names the service that owns it. A claim
+            // against a service called "api" that has never existed is one no
             // evidence in any repository could ever answer, and the fleet half alone
             // still derived exactly that claim for an introduced service's own
             // container. Unenumerable services/ degrades to the feature's names.
-            const svcOf = serviceResolver(elements, new Set([...(await enumeratedServiceIds(docsDir, ctx)), ...specServices]));
+            const svcOf = serviceResolver(elements, known);
             for (const r of res.relationships) {
                 // Untagged edges are context for the diagram; an edge with no operation
                 // names nothing specific enough to look for in the code.
@@ -169,6 +202,7 @@ export async function featureChecklist(docsDir, featureDir, featureId, fleet) {
                     scenarios.push({
                         ...claim("scenario.tested", svc, [svc, r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)], `scenario '${s.name}' of requirement '${r.name}' (${svc}) is covered by a test`),
                         digest: body.slice(0, DIGEST_LENGTH),
+                        steps: scenarioGherkin(s.lines).steps.length,
                     });
                 }
             }
@@ -190,6 +224,7 @@ export async function featureChecklist(docsDir, featureDir, featureId, fleet) {
                     scenarios.push({
                         ...claim("scenario.tested", svc, [svc, "arch.spec.md", r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)], `scenario '${s.name}' of arch requirement '${r.name}' (${svc}, arch.spec.md) is covered by a test`),
                         digest: body.slice(0, DIGEST_LENGTH),
+                        steps: scenarioGherkin(s.lines).steps.length,
                     });
                 }
             }

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

@@ -1 +1 @@
-{"version":3,"file":"checklist.js","sourceRoot":"","sources":["../../../src/core/verify/checklist.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The questions: what a feature's own artifacts promised, derived mechanically.\n *\n * The original plan was to extract C4 from the built code and diff it against\n * the delta. There is no such extractor and there will not be one — nothing\n * deterministic reads a service and says what its architecture MEANS, and two\n * generated models of the same code disagree in wording every run, so the diff\n * would flap and be switched off inside a week.\n *\n * What survives of the idea is the part that was always deterministic, and it\n * is this module: a feature says this service will exist, it will expose this\n * operation, that service will call it, this scenario will have a test. The\n * list comes from the same files `validate` already reads.\n *\n * The claim ids are a function of the claim and of nothing else — so two runs\n * are diffable, reordering the delta renames nothing, and rewording a scenario\n * DOES rename its claim, because an answer about text nobody wrote must not\n * carry over.\n *\n * `scenarioBodyHash` lives in `core/gherkin/digest.ts` — one recipe shared\n * with `core/gherkin/stamp.ts`, which stamps the same digest as a tag on every\n * generated scenario so `--results` can match a cucumber report back to a\n * claim. A second spelling of the hash would silently stop every scenario\n * claim from being answerable by a run.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { readAsyncapi } from \"../asyncapi/read.js\";\nimport { type Elem } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { ACTOR_KINDS } from \"../vocabulary/maturity.js\";\nimport { operationIds, operations } from \"../openapi/doc.js\";\nimport { featurePaths, featureSpecPaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { featureSpecServices } from \"../repo/repo.js\";\nimport { enumeratedServiceIds } from \"../repo/service-target.js\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { scenarioBodyHash } from \"../gherkin/digest.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n// The kind vocabulary and both hash recipes live in ./claims/identity.ts —\n// one module for everything that decides whether two runs ask the same\n// question, and this one for how the questions are derived.\nimport {\n  checklistDigest,\n  claimId,\n  DIGEST_LENGTH,\n  ID_LENGTH,\n  type ClaimKind,\n} from \"./claims/identity.js\";\n\nexport interface Claim {\n  /** `<kind>-<8 hex>` — stable for the life of the claim. See `claimId`. */\n  id: string;\n  kind: ClaimKind;\n  /** The service whose code answers this. A caller's claim is filed under the caller. */\n  subject: string;\n  /** The claim in one line, answerable without reading the feature's files. */\n  claim: string;\n  /**\n   * `scenario.tested` only: the first {@link DIGEST_LENGTH} hex of the\n   * scenario's body hash — the exact digest `loam gherkin` stamps as\n   * `@loam-digest-…`, which is what a cucumber report scenario carries and\n   * what `--results` matches on. Absent on every other kind.\n   */\n  digest?: string;\n  /**\n   * `api.exposes` only: the operationId the claim asserts, structurally — the\n   * join key `--contract-results` matches a contract report's entries on,\n   * exactly as `digest` is `--results`'s. Never parsed back out of the claim\n   * text, which is prose and may be reworded. Absent on every other kind.\n   */\n  operation?: string;\n  /**\n   * The literal string the claim asserts of the cited artifact — the\n   * operationId for `api.exposes`, the message name for `event.declares`, the\n   * edge's op for `c4.calls` — carried structurally so evidence pins\n   * (`./pins/pin.ts`) can stamp it at record time and the read side never\n   * parses it back out of claim prose. A separate field from `operation` on\n   * purpose: `contestedOperations` filters on `operation !== undefined` and\n   * must not start seeing `c4.calls` claims. Absent where a claim asserts no\n   * literal (`service.exists`, `scenario.tested`).\n   */\n  token?: string;\n}\n\nexport interface Checklist {\n  feature: string;\n  claims: Claim[];\n  /** A digest of the claim id SET — what says a record still answers this feature. */\n  digest: string;\n}\n\n/**\n * Derive the checklist from a feature's own artifacts. No code is read here and\n * none should be: the whole design rests on the questions being computed from\n * documents that do not change between runs.\n */\nexport async function featureChecklist(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  fleet?: FleetContext,\n): Promise<Checklist> {\n  // The per-service loop below resolves living contracts through the\n  // enumeration twice per service; without a shared context each of those is\n  // a full fleet walk, so deriving one checklist cost O(services²) reads. A\n  // caller-supplied context is used when given; otherwise one is created for\n  // this derivation alone — the loop still pays a single walk either way.\n  const ctx = fleet ?? new FleetContext();\n  const seen = new Map<string, number>();\n  const claim = (kind: ClaimKind, subject: string, parts: string[], text: string): Claim => ({\n    id: claimId(featureId, kind, parts, seen),\n    kind,\n    subject,\n    claim: text,\n  });\n\n  const exists: Claim[] = [];\n  const exposes: Claim[] = [];\n  const declares: Claim[] = [];\n  const calls: Claim[] = [];\n  const scenarios: Claim[] = [];\n\n  const specServices = await featureSpecServices(featureDir, ctx);\n\n  // Architecture — what the delta promised the fleet would look like. Loaded\n  // through the context rather than a bare parse, so a caller that derives\n  // several checklists in one invocation (`loam gate`'s verification check,\n  // the fleet forms) shares one parse per delta — and a batch prefetch\n  // (`FleetContext.prefetchLikeC4`) genuinely seeds this load.\n  const deltaPath = featurePaths(featureDir).delta;\n  if (existsSync(deltaPath)) {\n    const res = await ctx.loadLikeC4(deltaPath);\n    // A delta nobody can parse promises nothing checkable. `validate` already\n    // reports it; inventing claims out of a broken document would only add noise.\n    if (res.errors.length === 0) {\n      const elements: Elem[] = res.elements;\n      for (const e of elements) {\n        if (!e.tags.includes(featureId)) continue;\n        // A dotted id is a container INSIDE a service, and an actor is nobody's\n        // repository. Neither is a service that has to exist.\n        if (e.id.includes(\".\") || ACTOR_KINDS.has(e.kind.toLowerCase())) continue;\n        const svc = elementService(e);\n        exists.push(claim(\"service.exists\", svc, [svc], `service '${svc}' exists`));\n      }\n      // The enumerated fleet — `services/` plus this feature's own `specs/`\n      // directories, the only place a service the feature INTRODUCES has a\n      // directory at all — rides into the resolver so a claim about an edge\n      // drawn into a modelled container names the service that owns it. A\n      // claim against a service called \"api\" that has never existed is one no\n      // evidence in any repository could ever answer, and the fleet half alone\n      // still derived exactly that claim for an introduced service's own\n      // container. Unenumerable services/ degrades to the feature's names.\n      const svcOf = serviceResolver(\n        elements,\n        new Set<string>([...(await enumeratedServiceIds(docsDir, ctx)), ...specServices]),\n      );\n      for (const r of res.relationships) {\n        // Untagged edges are context for the diagram; an edge with no operation\n        // names nothing specific enough to look for in the code.\n        if (!r.tags.includes(featureId) || r.op === undefined) continue;\n        const from = svcOf(r.source);\n        const to = svcOf(r.target);\n        calls.push({\n          ...claim(\"c4.calls\", from, [from, to, r.op], `${from} calls '${r.op}' on ${to}`),\n          // The same string as the provider's api.exposes token, scanned in the\n          // CALLER's cited file — a call site plausibly spells the operationId.\n          token: r.op,\n        });\n      }\n    }\n  }\n\n  for (const svc of specServices) {\n    const paths = featureSpecPaths(featureDir, svc);\n\n    // Contract — only what is NEW. A delta's openapi.yaml is a whole document,\n    // not a patch, so authors restate the living API inside it; asking whether a\n    // service still exposes what it already exposed is noise.\n    const featOps = (await operations(paths.openapi))\n      .filter((operation) => !operation.remove)\n      .map((operation) => operation.id);\n    if (featOps.length > 0) {\n      const living = new Set(await operationIds((await locateServicePaths(docsDir, svc, ctx)).openapi));\n      for (const op of featOps) {\n        if (living.has(op)) continue;\n        exposes.push({\n          ...claim(\"api.exposes\", svc, [svc, op], `${svc} exposes operationId '${op}'`),\n          operation: op,\n          token: op,\n        });\n      }\n    }\n\n    // Events — the same NEW-only discipline on the async axis: a delta's\n    // asyncapi.yaml is a complete document too, so what the living contract\n    // already sends or receives is restatement, not a promise. Removals are\n    // not questions either — the reader already keeps marked declarations out\n    // of the sent/received sets — and an unreadable delta promises nothing\n    // checkable, exactly like the broken C4 delta above.\n    const events = await readAsyncapi(paths.asyncapi);\n    if (events.sent.length > 0 || events.received.length > 0) {\n      const living = await readAsyncapi((await locateServicePaths(docsDir, svc, ctx)).asyncapi);\n      const directions = [\n        { direction: \"sends\", feat: events.sent, known: new Set(living.sent) },\n        { direction: \"receives\", feat: events.received, known: new Set(living.received) },\n      ] as const;\n      for (const d of directions) {\n        for (const name of d.feat) {\n          if (d.known.has(name)) continue;\n          declares.push({\n            ...claim(\n              \"event.declares\",\n              svc,\n              [svc, d.direction, name],\n              `${svc} declares it ${d.direction} message '${name}'`,\n            ),\n            token: name,\n          });\n        }\n      }\n    }\n\n    // Behaviour — the scenarios of the requirements this feature CHANGES. A BASE\n    // requirement is the living state quoted inside the delta, and a REMOVED one\n    // is being retired: neither is work anybody has to have done.\n    if (existsSync(paths.spec)) {\n      for (const r of parseRequirements(await readFile(paths.spec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines);\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of requirement '${r.name}' (${svc}) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n          });\n        }\n      }\n    }\n\n    // The architecture spec axis, same walk: an arch scenario is a promise like\n    // any other — the outbox test nobody was going to write IS the point of the\n    // axis. The source file rides in the id tuple AND in the body hash itself\n    // (two axes are two namespaces: identically-worded scenarios must stay two\n    // questions, and the axis-salted digest is what keeps a business-only test\n    // run from answering the arch claim) and in the claim text, so the\n    // answering agent knows it is being asked for an integration/ops test, not\n    // an acceptance test.\n    if (existsSync(paths.archSpec)) {\n      for (const r of parseRequirements(await readFile(paths.archSpec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines, \"arch\");\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, \"arch.spec.md\", r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of arch requirement '${r.name}' (${svc}, arch.spec.md) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n          });\n        }\n      }\n    }\n  }\n\n  const claims = [...exists, ...exposes, ...declares, ...calls, ...scenarios];\n  return { feature: featureId, claims, digest: checklistDigest(claims.map((c) => c.id)) };\n}\n"]}
+{"version":3,"file":"checklist.js","sourceRoot":"","sources":["../../../src/core/verify/checklist.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The questions: what a feature's own artifacts promised, derived mechanically.\n *\n * The original plan was to extract C4 from the built code and diff it against\n * the delta. There is no such extractor and there will not be one — nothing\n * deterministic reads a service and says what its architecture MEANS, and two\n * generated models of the same code disagree in wording every run, so the diff\n * would flap and be switched off inside a week.\n *\n * What survives of the idea is the part that was always deterministic, and it\n * is this module: a feature says this service will exist, it will expose this\n * operation, that service will call it, this scenario will have a test. The\n * list comes from the same files `validate` already reads.\n *\n * The claim ids are a function of the claim and of nothing else — so two runs\n * are diffable, reordering the delta renames nothing, and rewording a scenario\n * DOES rename its claim, because an answer about text nobody wrote must not\n * carry over.\n *\n * `scenarioBodyHash` lives in `core/gherkin/digest.ts` — one recipe shared\n * with `core/gherkin/stamp.ts`, which stamps the same digest as a tag on every\n * generated scenario so `--results` can match a cucumber report back to a\n * claim. A second spelling of the hash would silently stop every scenario\n * claim from being answerable by a run.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { readAsyncapi } from \"../asyncapi/read.js\";\nimport { type Elem } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { ACTOR_KINDS, INFRA_KINDS } from \"../vocabulary/maturity.js\";\nimport { scenarioGherkin } from \"../vocabulary/steps.js\";\nimport { operationIds, operations } from \"../openapi/doc.js\";\nimport { featurePaths, featureSpecPaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { featureSpecServices } from \"../repo/repo.js\";\nimport { enumeratedServiceIds } from \"../repo/service-target.js\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { scenarioBodyHash } from \"../gherkin/digest.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n// The kind vocabulary and both hash recipes live in ./claims/identity.ts —\n// one module for everything that decides whether two runs ask the same\n// question, and this one for how the questions are derived.\nimport {\n  checklistDigest,\n  claimId,\n  DIGEST_LENGTH,\n  ID_LENGTH,\n  type ClaimKind,\n} from \"./claims/identity.js\";\n\nexport interface Claim {\n  /** `<kind>-<8 hex>` — stable for the life of the claim. See `claimId`. */\n  id: string;\n  kind: ClaimKind;\n  /** The service whose code answers this. A caller's claim is filed under the caller. */\n  subject: string;\n  /** The claim in one line, answerable without reading the feature's files. */\n  claim: string;\n  /**\n   * `scenario.tested` only: the first {@link DIGEST_LENGTH} hex of the\n   * scenario's body hash — the exact digest `loam gherkin` stamps as\n   * `@loam-digest-…`, which is what a cucumber report scenario carries and\n   * what `--results` matches on. Absent on every other kind.\n   */\n  digest?: string;\n  /**\n   * `scenario.tested` only: how many steps `loam gherkin` emits for the\n   * scenario — `scenarioGherkin`'s own count, the one the generated `.feature`\n   * carries. `--results` holds a cucumber run to it: the digest says WHICH\n   * scenario a report entry claims to be, and only the step count can say the\n   * entry is that scenario's run rather than a one-step stub tagged by hand\n   * (which confirmed five-step scenarios before this existed). The count, not\n   * the step text: an outline's steps reach the report with their\n   * `<placeholders>` filled in, and dialects disagree about keyword spacing and\n   * localisation, while every one of them reports one entry per step.\n   */\n  steps?: number;\n  /**\n   * `api.exposes` only: the operationId the claim asserts, structurally — the\n   * join key `--contract-results` matches a contract report's entries on,\n   * exactly as `digest` is `--results`'s. Never parsed back out of the claim\n   * text, which is prose and may be reworded. Absent on every other kind.\n   */\n  operation?: string;\n  /**\n   * The literal string the claim asserts of the cited artifact — the\n   * operationId for `api.exposes`, the message name for `event.declares`, the\n   * edge's op for `c4.calls` — carried structurally so evidence pins\n   * (`./pins/pin.ts`) can stamp it at record time and the read side never\n   * parses it back out of claim prose. A separate field from `operation` on\n   * purpose: `contestedOperations` filters on `operation !== undefined` and\n   * must not start seeing `c4.calls` claims. Absent where a claim asserts no\n   * literal (`service.exists`, `scenario.tested`).\n   */\n  token?: string;\n}\n\nexport interface Checklist {\n  feature: string;\n  claims: Claim[];\n  /** A digest of the claim id SET — what says a record still answers this feature. */\n  digest: string;\n}\n\n/**\n * Derive the checklist from a feature's own artifacts. No code is read here and\n * none should be: the whole design rests on the questions being computed from\n * documents that do not change between runs.\n */\nexport async function featureChecklist(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  fleet?: FleetContext,\n): Promise<Checklist> {\n  // The per-service loop below resolves living contracts through the\n  // enumeration twice per service; without a shared context each of those is\n  // a full fleet walk, so deriving one checklist cost O(services²) reads. A\n  // caller-supplied context is used when given; otherwise one is created for\n  // this derivation alone — the loop still pays a single walk either way.\n  const ctx = fleet ?? new FleetContext();\n  const seen = new Map<string, number>();\n  const claim = (kind: ClaimKind, subject: string, parts: string[], text: string): Claim => ({\n    id: claimId(featureId, kind, parts, seen),\n    kind,\n    subject,\n    claim: text,\n  });\n\n  const exists: Claim[] = [];\n  const exposes: Claim[] = [];\n  const declares: Claim[] = [];\n  const calls: Claim[] = [];\n  const scenarios: Claim[] = [];\n\n  const specServices = await featureSpecServices(featureDir, ctx);\n\n  // Architecture — what the delta promised the fleet would look like. Loaded\n  // through the context rather than a bare parse, so a caller that derives\n  // several checklists in one invocation (`loam gate`'s verification check,\n  // the fleet forms) shares one parse per delta — and a batch prefetch\n  // (`FleetContext.prefetchLikeC4`) genuinely seeds this load.\n  const deltaPath = featurePaths(featureDir).delta;\n  if (existsSync(deltaPath)) {\n    const res = await ctx.loadLikeC4(deltaPath);\n    // A delta nobody can parse promises nothing checkable. `validate` already\n    // reports it; inventing claims out of a broken document would only add noise.\n    if (res.errors.length === 0) {\n      const elements: Elem[] = res.elements;\n      // The enumerated fleet — `services/` plus this feature's own `specs/`\n      // directories, the only place a service the feature INTRODUCES has a\n      // directory at all. Built once, above both readers below, because they\n      // must not disagree: the skip loop asks whether an element STANDS FOR a\n      // service, and the resolver asks WHICH service an endpoint belongs to,\n      // and a set that answered the second question only left the first one\n      // reading a title as unknown that the very next line resolved.\n      const known = new Set<string>([\n        ...(await enumeratedServiceIds(docsDir, ctx)),\n        ...specServices,\n      ]);\n      for (const e of elements) {\n        if (!e.tags.includes(featureId)) continue;\n        // A dotted id is a container INSIDE a service, an actor is nobody's\n        // repository, and the fleet's own infrastructure — a `database`,\n        // `queue`, `topic`, `cache` or `bucket` — has no repository either.\n        // None of the three is a service that has to exist.\n        //\n        // The infra skip closes a claim no repository could ever answer: a\n        // delta that draws a fleet-level `database` minted `service.exists` for\n        // it, and `loam verify` then asked somebody to point at the code that\n        // proves a Postgres has a services/ directory. It is the SAME shape as\n        // the container-and-actor skips beside it — an element that is not a\n        // team's system — not a new kind of exemption.\n        //\n        // STANDING FOR A SERVICE still wins, because that is a claim about\n        // this repo rather than a guess at one, and it is the same predicate\n        // every other surface applies — `commands/validate/fleet/census.ts`'s\n        // `standsForService`, spelled here rather than imported because core\n        // may not reach into commands. Both of its rungs matter: a `database`\n        // carrying `metadata { service '<id>' }` names a directory the author\n        // says exists, and one whose TITLE names a real `services/<id>/` names\n        // a directory the enumeration just read. Testing the binding alone made\n        // an adopted store a service on every other surface and infrastructure\n        // here, so its `service.exists` claim silently went missing from the\n        // checklist that is supposed to hold every promise the feature made.\n        const standsFor = e.service !== undefined || known.has(e.title);\n        const infra = !standsFor && INFRA_KINDS.has(e.kind.toLowerCase());\n        if (e.id.includes(\".\") || ACTOR_KINDS.has(e.kind.toLowerCase()) || infra) continue;\n        const svc = elementService(e);\n        exists.push(claim(\"service.exists\", svc, [svc], `service '${svc}' exists`));\n      }\n      // That same set rides into the resolver so a claim about an edge drawn\n      // into a modelled container names the service that owns it. A claim\n      // against a service called \"api\" that has never existed is one no\n      // evidence in any repository could ever answer, and the fleet half alone\n      // still derived exactly that claim for an introduced service's own\n      // container. Unenumerable services/ degrades to the feature's names.\n      const svcOf = serviceResolver(elements, known);\n      for (const r of res.relationships) {\n        // Untagged edges are context for the diagram; an edge with no operation\n        // names nothing specific enough to look for in the code.\n        if (!r.tags.includes(featureId) || r.op === undefined) continue;\n        const from = svcOf(r.source);\n        const to = svcOf(r.target);\n        calls.push({\n          ...claim(\"c4.calls\", from, [from, to, r.op], `${from} calls '${r.op}' on ${to}`),\n          // The same string as the provider's api.exposes token, scanned in the\n          // CALLER's cited file — a call site plausibly spells the operationId.\n          token: r.op,\n        });\n      }\n    }\n  }\n\n  for (const svc of specServices) {\n    const paths = featureSpecPaths(featureDir, svc);\n\n    // Contract — only what is NEW. A delta's openapi.yaml is a whole document,\n    // not a patch, so authors restate the living API inside it; asking whether a\n    // service still exposes what it already exposed is noise.\n    const featOps = (await operations(paths.openapi))\n      .filter((operation) => !operation.remove)\n      .map((operation) => operation.id);\n    if (featOps.length > 0) {\n      const living = new Set(await operationIds((await locateServicePaths(docsDir, svc, ctx)).openapi));\n      for (const op of featOps) {\n        if (living.has(op)) continue;\n        exposes.push({\n          ...claim(\"api.exposes\", svc, [svc, op], `${svc} exposes operationId '${op}'`),\n          operation: op,\n          token: op,\n        });\n      }\n    }\n\n    // Events — the same NEW-only discipline on the async axis: a delta's\n    // asyncapi.yaml is a complete document too, so what the living contract\n    // already sends or receives is restatement, not a promise. Removals are\n    // not questions either — the reader already keeps marked declarations out\n    // of the sent/received sets — and an unreadable delta promises nothing\n    // checkable, exactly like the broken C4 delta above.\n    const events = await readAsyncapi(paths.asyncapi);\n    if (events.sent.length > 0 || events.received.length > 0) {\n      const living = await readAsyncapi((await locateServicePaths(docsDir, svc, ctx)).asyncapi);\n      const directions = [\n        { direction: \"sends\", feat: events.sent, known: new Set(living.sent) },\n        { direction: \"receives\", feat: events.received, known: new Set(living.received) },\n      ] as const;\n      for (const d of directions) {\n        for (const name of d.feat) {\n          if (d.known.has(name)) continue;\n          declares.push({\n            ...claim(\n              \"event.declares\",\n              svc,\n              [svc, d.direction, name],\n              `${svc} declares it ${d.direction} message '${name}'`,\n            ),\n            token: name,\n          });\n        }\n      }\n    }\n\n    // Behaviour — the scenarios of the requirements this feature CHANGES. A BASE\n    // requirement is the living state quoted inside the delta, and a REMOVED one\n    // is being retired: neither is work anybody has to have done.\n    if (existsSync(paths.spec)) {\n      for (const r of parseRequirements(await readFile(paths.spec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines);\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of requirement '${r.name}' (${svc}) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n            steps: scenarioGherkin(s.lines).steps.length,\n          });\n        }\n      }\n    }\n\n    // The architecture spec axis, same walk: an arch scenario is a promise like\n    // any other — the outbox test nobody was going to write IS the point of the\n    // axis. The source file rides in the id tuple AND in the body hash itself\n    // (two axes are two namespaces: identically-worded scenarios must stay two\n    // questions, and the axis-salted digest is what keeps a business-only test\n    // run from answering the arch claim) and in the claim text, so the\n    // answering agent knows it is being asked for an integration/ops test, not\n    // an acceptance test.\n    if (existsSync(paths.archSpec)) {\n      for (const r of parseRequirements(await readFile(paths.archSpec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines, \"arch\");\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, \"arch.spec.md\", r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of arch requirement '${r.name}' (${svc}, arch.spec.md) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n            steps: scenarioGherkin(s.lines).steps.length,\n          });\n        }\n      }\n    }\n  }\n\n  const claims = [...exists, ...exposes, ...declares, ...calls, ...scenarios];\n  return { feature: featureId, claims, digest: checklistDigest(claims.map((c) => c.id)) };\n}\n"]}

package/dist/core/verify/location.js

@@ -0,0 +1,67 @@
+/**
+ * Where the verification record lives on disk — the one-file form, the
+ * per-service directory, and which of the two a reader is pointed at.
+ *
+ * Split out of `./record.ts`, which keeps what gets written down and how a set
+ * of answers counts up to a verdict: the addresses are a different subject from
+ * the shapes and the arithmetic, and the per-service directory pushed that
+ * module over the line limit. The readers (`./read/file.ts`), the writers
+ * (`loam verify`'s record step) and `status`'s artifact row all ask where the
+ * record is; none of them needs the record's shape to ask it.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Where the record lives: inside the feature, so `archive` carries it into
+ * `features/archive/` with everything else and a reviewer finds it next to the
+ * delta it is about. YAML rather than frontmatter or JSON — it is data, it has
+ * to survive without loam, and one claim per block is a diff a person can read.
+ *
+ * This is the ONE-FILE form: what the all-at-once `--record` (no `--service`)
+ * writes, and what every federated record written before the per-service
+ * directory existed still is. It is read forever, active and archived alike.
+ * A federated attestation no longer goes here — see {@link serviceRecordPath}.
+ */
+export function verificationPath(featureDir) {
+    return join(featureDir, "verification.yaml");
+}
+/**
+ * The federated record: one file per attesting service, and the DIRECTORY is
+ * the list — the `glossary/` and `capabilities/` rule.
+ *
+ * One shared file was the wrong shape for a fleet. Every service's attestation
+ * rewrote the same `summary`, `recorded` and checklist-ordered `claims`, so two
+ * docs-repo branches recording two DIFFERENT services always conflicted in git
+ * — add/add from an empty start, content conflicts on the summary once one
+ * attestation had merged — and sorting the attestations did not help, because
+ * two insertions at one anchor are a conflict whatever the order. The lock that
+ * serialises writers covers one checkout; a fleet records from many. With one
+ * file per service, two teams' records touch two different paths and merge
+ * cleanly, and the verdict is computed from the union at read time — which it
+ * always was: nothing ever trusted the stored `summary`.
+ */
+export function verificationDir(featureDir) {
+    return join(featureDir, "verification");
+}
+/**
+ * One service's attestation file. The service id grammar admits no `/`, so this
+ * never leaves the directory — and the parameter type is what makes that a
+ * guarantee rather than a hope: a `PathableService` is a name whose provenance
+ * is the repository (a validated id, or a directory that exists), so a name a
+ * document merely asserts, or a raw flag nobody checked, does not compile here.
+ */
+export function serviceRecordPath(featureDir, service) {
+    return join(verificationDir(featureDir), `${service}.yaml`);
+}
+/**
+ * Where a reader should look: the directory once it exists, the one file
+ * otherwise. A single path is lossy on purpose — a record mid-migration is
+ * both — and what a reader is pointed at is where the next attestation will
+ * land. A legacy file beside the directory is still read (see `./read/file.ts`);
+ * it is simply no longer where anything is written for a service.
+ */
+export function recordLocation(featureDir) {
+    const dir = verificationDir(featureDir);
+    return existsSync(dir) ? dir : verificationPath(featureDir);
+}
+//# sourceMappingURL=location.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../../src/core/verify/location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,OAAwB;IAC5E,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Where the verification record lives on disk — the one-file form, the\n * per-service directory, and which of the two a reader is pointed at.\n *\n * Split out of `./record.ts`, which keeps what gets written down and how a set\n * of answers counts up to a verdict: the addresses are a different subject from\n * the shapes and the arithmetic, and the per-service directory pushed that\n * module over the line limit. The readers (`./read/file.ts`), the writers\n * (`loam verify`'s record step) and `status`'s artifact row all ask where the\n * record is; none of them needs the record's shape to ask it.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\n\n/**\n * Where the record lives: inside the feature, so `archive` carries it into\n * `features/archive/` with everything else and a reviewer finds it next to the\n * delta it is about. YAML rather than frontmatter or JSON — it is data, it has\n * to survive without loam, and one claim per block is a diff a person can read.\n *\n * This is the ONE-FILE form: what the all-at-once `--record` (no `--service`)\n * writes, and what every federated record written before the per-service\n * directory existed still is. It is read forever, active and archived alike.\n * A federated attestation no longer goes here — see {@link serviceRecordPath}.\n */\nexport function verificationPath(featureDir: string): string {\n  return join(featureDir, \"verification.yaml\");\n}\n\n/**\n * The federated record: one file per attesting service, and the DIRECTORY is\n * the list — the `glossary/` and `capabilities/` rule.\n *\n * One shared file was the wrong shape for a fleet. Every service's attestation\n * rewrote the same `summary`, `recorded` and checklist-ordered `claims`, so two\n * docs-repo branches recording two DIFFERENT services always conflicted in git\n * — add/add from an empty start, content conflicts on the summary once one\n * attestation had merged — and sorting the attestations did not help, because\n * two insertions at one anchor are a conflict whatever the order. The lock that\n * serialises writers covers one checkout; a fleet records from many. With one\n * file per service, two teams' records touch two different paths and merge\n * cleanly, and the verdict is computed from the union at read time — which it\n * always was: nothing ever trusted the stored `summary`.\n */\nexport function verificationDir(featureDir: string): string {\n  return join(featureDir, \"verification\");\n}\n\n/**\n * One service's attestation file. The service id grammar admits no `/`, so this\n * never leaves the directory — and the parameter type is what makes that a\n * guarantee rather than a hope: a `PathableService` is a name whose provenance\n * is the repository (a validated id, or a directory that exists), so a name a\n * document merely asserts, or a raw flag nobody checked, does not compile here.\n */\nexport function serviceRecordPath(featureDir: string, service: PathableService): string {\n  return join(verificationDir(featureDir), `${service}.yaml`);\n}\n\n/**\n * Where a reader should look: the directory once it exists, the one file\n * otherwise. A single path is lossy on purpose — a record mid-migration is\n * both — and what a reader is pointed at is where the next attestation will\n * land. A legacy file beside the directory is still read (see `./read/file.ts`);\n * it is simply no longer where anything is written for a service.\n */\nexport function recordLocation(featureDir: string): string {\n  const dir = verificationDir(featureDir);\n  return existsSync(dir) ? dir : verificationPath(featureDir);\n}\n"]}

package/dist/core/verify/pins/lint.js

@@ -6,8 +6,9 @@
  *
  * The claim shape is structural rather than an import of `../record.js`'s
  * `RecordedClaim`, and not only for the smallest-parameter rule: this package
- * is imported BY `core/verify` (`../file.ts` asks `./pin.ts` for the read
- * guard, `../answers.ts` for the shape), so importing the parent back would
+ * is imported BY `core/verify` and its `read/` sibling (`../read/shape.ts` asks
+ * `./pin.ts` for the read guard, `../answers.ts` for the shape), so importing
+ * the parent back would
  * put a cycle in the package graph that `import/no-cycle` cannot see.
  */
 import { readFile, stat } from "node:fs/promises";

package/dist/core/verify/pins/lint.js.map

@@ -1 +1 @@
-{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/lint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Re-checking evidence pins against a working tree: pure data out, one grade\n * per pin, and no verdict anywhere in the result on purpose — the lint demotes\n * reviewer confidence, it never promotes or demotes a claim. Prints nothing;\n * the validate command turns the grades into findings.\n *\n * The claim shape is structural rather than an import of `../record.js`'s\n * `RecordedClaim`, and not only for the smallest-parameter rule: this package\n * is imported BY `core/verify` (`../file.ts` asks `./pin.ts` for the read\n * guard, `../answers.ts` for the shape), so importing the parent back would\n * put a cycle in the package graph that `import/no-cycle` cannot see.\n */\nimport { readFile, stat } from \"node:fs/promises\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { resolvePortableFileInside, UnsafePathError } from \"../../kernel/path-safety.js\";\nimport { pinnedDigest, pinnedText, sourceLines, type EvidencePin } from \"./pin.js\";\n\n/** What the lint reads off a recorded claim — structurally, see the header. */\nexport interface PinnedClaim {\n  id: string;\n  /** Present in federated (schema 2) records — the service whose code answers it. */\n  subject?: string;\n  verdict: string;\n  /** Absent counts as agent — the `attestedClaims` rule for records that predate `--results`. */\n  answered_by?: string;\n  evidence: string[];\n  evidence_pins?: EvidencePin[];\n}\n\n/** One pin's disagreement with the working tree. `grade` is what a finding code is made from. */\nexport interface PinDrift {\n  claim: string;\n  /** The `path:line` citation the pin belongs to. */\n  evidence: string;\n  grade: \"unresolved\" | \"moved\" | \"line-changed\" | \"token-missing\";\n  /** What changed, in one clause — rendered into a finding's detail line. */\n  what: string;\n}\n\nexport interface PinLint {\n  /** Pins that resolved clean: file digest unchanged against the working tree. */\n  checked: number;\n  /** In record order — claim by claim, citation by citation — so two runs diff. */\n  drifts: PinDrift[];\n  /** Agent-confirmed citations carrying no pin, plus claims with no pins at all. */\n  unpinned: number;\n}\n\n/** What one cited file turned out to be, read and hashed once per lint call. */\ntype FileState =\n  | { state: \"unreadable\"; what: string }\n  | { state: \"ok\"; digest: string; lines: string[]; text: string };\n\n/**\n * Grade one record's pins for one service against that service's working tree.\n *\n * Only agent-confirmed claims of `service` are graded: a runner's or contract\n * runner's evidence names a report entry, not a file, so there is nothing to\n * re-check, and an unconfirmed claim pinned nothing. Absent `answered_by`\n * counts as agent — the `attestedClaims` rule.\n *\n * Containment is per citation: one unreadable cited file degrades exactly the\n * pins that cite it (graded `unresolved`), never the sibling pins and never\n * the whole record. And \"could not look\" is never \"looks fine\": every failure\n * to read is a drift entry, not a skip — fail closed at the validator.\n */\nexport async function lintEvidencePins(\n  claims: readonly PinnedClaim[],\n  service: string,\n  repoDir: string,\n): Promise<PinLint> {\n  // The closed side of the answerer test, on purpose: `answered_by` is an open\n  // string here (a record is hand-editable YAML, and a newer loam may add\n  // answerers), so excluding the known mechanical values would sweep every\n  // FUTURE mechanical answerer's report-entry citations into the `unpinned`\n  // tally with false \"recorded before pins existed\" advice. Only what is\n  // positively an agent's word is graded; absent counts as agent — the\n  // `attestedClaims` rule for records that predate `--results`.\n  const mine = claims.filter(\n    (c) =>\n      c.subject === service &&\n      c.verdict === \"confirmed\" &&\n      (c.answered_by === undefined || c.answered_by === \"agent\"),\n  );\n\n  // Join pins to evidence entries by the `path:line` key, never by position:\n  // a record is hand-editable YAML, and a positional join would let a deleted\n  // evidence line silently shift every later pin onto the wrong citation.\n  const joined: Array<{ claim: string; evidence: string; pin: EvidencePin }> = [];\n  let unpinned = 0;\n  for (const claim of mine) {\n    const pins = new Map((claim.evidence_pins ?? []).map((pin) => [`${pin.path}:${pin.line}`, pin]));\n    // A pin no evidence entry names pins nothing this claim cites (a hand\n    // edit); grading it would report drift about a citation the claim does not\n    // make, so only the joined pairs are graded. The reverse direction — a\n    // citation without a pin — is the `unpinned` tally.\n    for (const evidence of claim.evidence) {\n      const pin = pins.get(evidence);\n      if (pin === undefined) unpinned += 1;\n      else joined.push({ claim: claim.id, evidence, pin });\n    }\n  }\n\n  // Each distinct cited file is read and hashed once per call — a local map,\n  // per invocation, because module-level state leaks across tests and hosts.\n  // The reads are independent, so they go through the bounded pool; grading\n  // stays sequential below so `drifts` keeps record order.\n  const paths = [...new Set(joined.map((j) => j.pin.path))];\n  const states = new Map(\n    await inOrder(paths, async (path): Promise<[string, FileState]> => [path, await readCited(repoDir, path)]),\n  );\n\n  let checked = 0;\n  const drifts: PinDrift[] = [];\n  for (const { claim, evidence, pin } of joined) {\n    const file = states.get(pin.path);\n    if (file === undefined || file.state === \"unreadable\") {\n      drifts.push({ claim, evidence, grade: \"unresolved\", what: file?.what ?? \"the cited file was not read\" });\n      continue;\n    }\n    const cited = file.lines[pin.line - 1];\n    if (cited === undefined) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"unresolved\",\n        // `continue`, like the unreadable-file arm: an unresolvable CITATION\n        // is one finding, and a token scan on top would report the same\n        // damaged citation twice under two codes.\n        what: `the cited line is past the end — the file now has ${file.lines.length} line(s)`,\n      });\n      continue;\n    }\n    if (file.digest === pin.file_sha256) {\n      checked += 1;\n    } else if (pinnedText(cited) === pin.text) {\n      // The mildest drift: the file changed around the cited line, which\n      // still reads as pinned — \"reads as\", not \"is\": both sides of the\n      // comparison are capped at PIN_TEXT_CAP, so a change past the cap on a\n      // pathological line is invisible to this grade (and visible to the\n      // digest, which is why this is a drift and not a clean pin).\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"moved\",\n        what: \"the file changed around the cited line, which still reads as pinned\",\n      });\n    } else {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"line-changed\",\n        what: `the cited line now reads '${pinnedText(cited)}' where the record pinned '${pin.text}'`,\n      });\n    }\n    // Independent of the grades above, clean pins included — a digest match\n    // must not read as \"the token is still there\", because content identical\n    // to record time says nothing once the file drifts back. \"No longer\" is\n    // the honest word here: the write side stamps `token` only when the\n    // attested blob contained it (EvidencePin.token), so this grade always\n    // convicts a disappearance, never re-litigates an absence the record-time\n    // notice already reported.\n    if (pin.token !== undefined && !file.text.includes(pin.token)) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"token-missing\",\n        what: `the cited file no longer contains '${pin.token}' — the literal string the claim asserts`,\n      });\n    }\n  }\n  return { checked, drifts, unpinned };\n}\n\n/** One cited file against the working tree, every failure named rather than thrown. */\nasync function readCited(repoDir: string, path: string): Promise<FileState> {\n  let absolute: string;\n  try {\n    absolute = resolvePortableFileInside(repoDir, path, \"pinned evidence\");\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return { state: \"unreadable\", what: `the pinned path is unsafe: ${err.message}` };\n  }\n  try {\n    const info = await stat(absolute);\n    if (!info.isFile()) return { state: \"unreadable\", what: \"the cited path is not a regular file\" };\n    const text = await readFile(absolute, \"utf8\");\n    return { state: \"ok\", digest: pinnedDigest(text), lines: sourceLines(text), text };\n  } catch (err) {\n    // ENOENT is the common drift — the cited file is gone from the tree; any\n    // other errno (EACCES, EISDIR racing the stat) is named as itself, because\n    // \"could not read\" and \"does not exist\" call for different repairs.\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return { state: \"unreadable\", what: \"the cited file does not exist in this working tree\" };\n    }\n    return { state: \"unreadable\", what: err instanceof Error ? err.message : String(err) };\n  }\n}\n"]}
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/lint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Re-checking evidence pins against a working tree: pure data out, one grade\n * per pin, and no verdict anywhere in the result on purpose — the lint demotes\n * reviewer confidence, it never promotes or demotes a claim. Prints nothing;\n * the validate command turns the grades into findings.\n *\n * The claim shape is structural rather than an import of `../record.js`'s\n * `RecordedClaim`, and not only for the smallest-parameter rule: this package\n * is imported BY `core/verify` and its `read/` sibling (`../read/shape.ts` asks\n * `./pin.ts` for the read guard, `../answers.ts` for the shape), so importing\n * the parent back would\n * put a cycle in the package graph that `import/no-cycle` cannot see.\n */\nimport { readFile, stat } from \"node:fs/promises\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { resolvePortableFileInside, UnsafePathError } from \"../../kernel/path-safety.js\";\nimport { pinnedDigest, pinnedText, sourceLines, type EvidencePin } from \"./pin.js\";\n\n/** What the lint reads off a recorded claim — structurally, see the header. */\nexport interface PinnedClaim {\n  id: string;\n  /** Present in federated (schema 2) records — the service whose code answers it. */\n  subject?: string;\n  verdict: string;\n  /** Absent counts as agent — the `attestedClaims` rule for records that predate `--results`. */\n  answered_by?: string;\n  evidence: string[];\n  evidence_pins?: EvidencePin[];\n}\n\n/** One pin's disagreement with the working tree. `grade` is what a finding code is made from. */\nexport interface PinDrift {\n  claim: string;\n  /** The `path:line` citation the pin belongs to. */\n  evidence: string;\n  grade: \"unresolved\" | \"moved\" | \"line-changed\" | \"token-missing\";\n  /** What changed, in one clause — rendered into a finding's detail line. */\n  what: string;\n}\n\nexport interface PinLint {\n  /** Pins that resolved clean: file digest unchanged against the working tree. */\n  checked: number;\n  /** In record order — claim by claim, citation by citation — so two runs diff. */\n  drifts: PinDrift[];\n  /** Agent-confirmed citations carrying no pin, plus claims with no pins at all. */\n  unpinned: number;\n}\n\n/** What one cited file turned out to be, read and hashed once per lint call. */\ntype FileState =\n  | { state: \"unreadable\"; what: string }\n  | { state: \"ok\"; digest: string; lines: string[]; text: string };\n\n/**\n * Grade one record's pins for one service against that service's working tree.\n *\n * Only agent-confirmed claims of `service` are graded: a runner's or contract\n * runner's evidence names a report entry, not a file, so there is nothing to\n * re-check, and an unconfirmed claim pinned nothing. Absent `answered_by`\n * counts as agent — the `attestedClaims` rule.\n *\n * Containment is per citation: one unreadable cited file degrades exactly the\n * pins that cite it (graded `unresolved`), never the sibling pins and never\n * the whole record. And \"could not look\" is never \"looks fine\": every failure\n * to read is a drift entry, not a skip — fail closed at the validator.\n */\nexport async function lintEvidencePins(\n  claims: readonly PinnedClaim[],\n  service: string,\n  repoDir: string,\n): Promise<PinLint> {\n  // The closed side of the answerer test, on purpose: `answered_by` is an open\n  // string here (a record is hand-editable YAML, and a newer loam may add\n  // answerers), so excluding the known mechanical values would sweep every\n  // FUTURE mechanical answerer's report-entry citations into the `unpinned`\n  // tally with false \"recorded before pins existed\" advice. Only what is\n  // positively an agent's word is graded; absent counts as agent — the\n  // `attestedClaims` rule for records that predate `--results`.\n  const mine = claims.filter(\n    (c) =>\n      c.subject === service &&\n      c.verdict === \"confirmed\" &&\n      (c.answered_by === undefined || c.answered_by === \"agent\"),\n  );\n\n  // Join pins to evidence entries by the `path:line` key, never by position:\n  // a record is hand-editable YAML, and a positional join would let a deleted\n  // evidence line silently shift every later pin onto the wrong citation.\n  const joined: Array<{ claim: string; evidence: string; pin: EvidencePin }> = [];\n  let unpinned = 0;\n  for (const claim of mine) {\n    const pins = new Map((claim.evidence_pins ?? []).map((pin) => [`${pin.path}:${pin.line}`, pin]));\n    // A pin no evidence entry names pins nothing this claim cites (a hand\n    // edit); grading it would report drift about a citation the claim does not\n    // make, so only the joined pairs are graded. The reverse direction — a\n    // citation without a pin — is the `unpinned` tally.\n    for (const evidence of claim.evidence) {\n      const pin = pins.get(evidence);\n      if (pin === undefined) unpinned += 1;\n      else joined.push({ claim: claim.id, evidence, pin });\n    }\n  }\n\n  // Each distinct cited file is read and hashed once per call — a local map,\n  // per invocation, because module-level state leaks across tests and hosts.\n  // The reads are independent, so they go through the bounded pool; grading\n  // stays sequential below so `drifts` keeps record order.\n  const paths = [...new Set(joined.map((j) => j.pin.path))];\n  const states = new Map(\n    await inOrder(paths, async (path): Promise<[string, FileState]> => [path, await readCited(repoDir, path)]),\n  );\n\n  let checked = 0;\n  const drifts: PinDrift[] = [];\n  for (const { claim, evidence, pin } of joined) {\n    const file = states.get(pin.path);\n    if (file === undefined || file.state === \"unreadable\") {\n      drifts.push({ claim, evidence, grade: \"unresolved\", what: file?.what ?? \"the cited file was not read\" });\n      continue;\n    }\n    const cited = file.lines[pin.line - 1];\n    if (cited === undefined) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"unresolved\",\n        // `continue`, like the unreadable-file arm: an unresolvable CITATION\n        // is one finding, and a token scan on top would report the same\n        // damaged citation twice under two codes.\n        what: `the cited line is past the end — the file now has ${file.lines.length} line(s)`,\n      });\n      continue;\n    }\n    if (file.digest === pin.file_sha256) {\n      checked += 1;\n    } else if (pinnedText(cited) === pin.text) {\n      // The mildest drift: the file changed around the cited line, which\n      // still reads as pinned — \"reads as\", not \"is\": both sides of the\n      // comparison are capped at PIN_TEXT_CAP, so a change past the cap on a\n      // pathological line is invisible to this grade (and visible to the\n      // digest, which is why this is a drift and not a clean pin).\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"moved\",\n        what: \"the file changed around the cited line, which still reads as pinned\",\n      });\n    } else {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"line-changed\",\n        what: `the cited line now reads '${pinnedText(cited)}' where the record pinned '${pin.text}'`,\n      });\n    }\n    // Independent of the grades above, clean pins included — a digest match\n    // must not read as \"the token is still there\", because content identical\n    // to record time says nothing once the file drifts back. \"No longer\" is\n    // the honest word here: the write side stamps `token` only when the\n    // attested blob contained it (EvidencePin.token), so this grade always\n    // convicts a disappearance, never re-litigates an absence the record-time\n    // notice already reported.\n    if (pin.token !== undefined && !file.text.includes(pin.token)) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"token-missing\",\n        what: `the cited file no longer contains '${pin.token}' — the literal string the claim asserts`,\n      });\n    }\n  }\n  return { checked, drifts, unpinned };\n}\n\n/** One cited file against the working tree, every failure named rather than thrown. */\nasync function readCited(repoDir: string, path: string): Promise<FileState> {\n  let absolute: string;\n  try {\n    absolute = resolvePortableFileInside(repoDir, path, \"pinned evidence\");\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return { state: \"unreadable\", what: `the pinned path is unsafe: ${err.message}` };\n  }\n  try {\n    const info = await stat(absolute);\n    if (!info.isFile()) return { state: \"unreadable\", what: \"the cited path is not a regular file\" };\n    const text = await readFile(absolute, \"utf8\");\n    return { state: \"ok\", digest: pinnedDigest(text), lines: sourceLines(text), text };\n  } catch (err) {\n    // ENOENT is the common drift — the cited file is gone from the tree; any\n    // other errno (EACCES, EISDIR racing the stat) is named as itself, because\n    // \"could not read\" and \"does not exist\" call for different repairs.\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return { state: \"unreadable\", what: \"the cited file does not exist in this working tree\" };\n    }\n    return { state: \"unreadable\", what: err instanceof Error ? err.message : String(err) };\n  }\n}\n"]}

package/dist/core/verify/pins/pin.js

@@ -62,7 +62,7 @@ export function pinnedDigest(source) {
     return createHash("sha256").update(source.replace(/\r\n|\r/g, "\n")).digest("hex");
 }
 /**
- * The read-shape guard `asVerification` (../file.ts) asks per claim, on the
+ * The read-shape guard `asVerification` (../read/shape.ts) asks per claim, on the
  * `isConsumedContractReport` model to the letter: absent is fine — every
  * record written before pins existed, and every runner-answered claim, has
  * none — but present must be whole for the four fields the lint dereferences.

package/dist/core/verify/pins/pin.js.map

@@ -1 +1 @@
-{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4BnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAClF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,IAAY;IACpD,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClD,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvG,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5F,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The evidence pin's identity: what `verify --service --record` stamps beside a\n * confirmed agent answer so a later `loam validate`, standing in the same\n * service repository, can re-check the citation against the working tree.\n *\n * Be precise about what a pin proves, because the record travels without loam:\n * a pin identifies WHAT was cited at the attested commit — the cited file's\n * normalized sha256, the cited line's text, the literal token the claim\n * asserts. It does not prove the claim true; an agent that cited the wrong\n * line gets a faithful pin of the wrong line. That is why the read side\n * (`./lint.ts`) only ever demotes reviewer confidence: no pin state moves a\n * verdict in either direction.\n */\nimport { createHash } from \"node:crypto\";\nimport { isRecord } from \"../../kernel/records.js\";\n\nexport interface EvidencePin {\n  /** The cited file, repo-relative in the portable spelling evidence entries use. */\n  path: string;\n  /** The cited line, 1-based — the `:N` of the evidence entry this pins. */\n  line: number;\n  /** sha256 hex of the whole file at the attested commit, normalized — see {@link pinnedDigest}. */\n  file_sha256: string;\n  /** The cited line at the attested commit, trimmed and capped — see {@link pinnedText}. */\n  text: string;\n  /**\n   * The literal string the claim asserts of the cited artifact — the\n   * operationId for `api.exposes`, the message name for `event.declares`, the\n   * edge's op for `c4.calls` (`Claim.token`, stamped at record time). Carried\n   * on the pin so the read side scans the file for it and never has to\n   * re-derive a checklist or parse claim prose. Absent for the kinds that\n   * assert no token (`service.exists`, `scenario.tested`) — and absent when\n   * the attested blob did not CONTAIN the token: that fact is warned once, at\n   * record time, where the answerer can still act on it; a pin carrying it\n   * would make `loam validate` repeat \"no longer contains\" forever about a\n   * file that never did, with a re-record that re-derives the same state as\n   * the only offered repair. `token-missing` therefore always means \"was\n   * there at the attested commit and is gone\".\n   */\n  token?: string;\n}\n\n/**\n * How much of the cited line a pin carries. Enough to recognize a line of\n * source by eye and by equality; a cap because evidence may cite a line of a\n * generated client or a minified bundle, and the record is a YAML file people\n * read and diff — one pathological line must not turn it into one.\n */\nexport const PIN_TEXT_CAP = 200;\n\n/** The pin's line recipe: trimmed (indentation is formatting), capped at {@link PIN_TEXT_CAP}. */\nexport function pinnedText(line: string): string {\n  const trimmed = line.trim();\n  return trimmed.length > PIN_TEXT_CAP ? trimmed.slice(0, PIN_TEXT_CAP) : trimmed;\n}\n\n/**\n * The one spelling of where lines fall. Both sides of the pin — the write\n * side's bounds checks and the read side's re-grade — must number lines\n * identically, or a pin recorded at line 12 gets graded against a different\n * line 12; four call sites each spelling the regex themselves is how that\n * divergence would arrive, so the recipe has exactly one home.\n */\nexport function sourceLines(source: string): string[] {\n  return source.split(/\\r\\n|\\n|\\r/);\n}\n\n/**\n * The cited line of a source text, through the pin recipe — or undefined when\n * the line is past the end, which the caller grades (a refusal on the write\n * side, `unresolved` on the read side).\n */\nexport function citedLine(source: string, line: number): string | undefined {\n  const raw = sourceLines(source)[line - 1];\n  return raw === undefined ? undefined : pinnedText(raw);\n}\n\n/**\n * The pin's file digest: sha256 hex over the text with CRLF/CR normalized to\n * LF.\n *\n * Normalized because git's eol config makes blob bytes and working-tree bytes\n * legally differ: on a Windows checkout with `core.autocrlf=true`, the blob\n * the attested commit holds is LF while every file on disk is CRLF, so an\n * unnormalized digest would grade every pin `evidence.moved` forever on the\n * checkout config alone. The pin must convict content change, never checkout\n * config. The recipe is over TEXT by construction — the write side digests\n * `git show` output already decoded as utf8 — and the symmetric cost is\n * accepted and documented in SCHEMA.md: a pure line-ending change is invisible\n * to the lint.\n */\nexport function pinnedDigest(source: string): string {\n  return createHash(\"sha256\").update(source.replace(/\\r\\n|\\r/g, \"\\n\")).digest(\"hex\");\n}\n\n/**\n * The read-shape guard `asVerification` (../file.ts) asks per claim, on the\n * `isConsumedContractReport` model to the letter: absent is fine — every\n * record written before pins existed, and every runner-answered claim, has\n * none — but present must be whole for the four fields the lint dereferences.\n * A broken pins block makes the WHOLE record unreadable and therefore never\n * overwritten, exactly the contract-report rule: it is somebody's record, and\n * a lint that silently skipped a malformed pin would read a hand-damaged\n * record as drift-free. `token` stays optional-and-any-string for `format`'s\n * reason — a field a newer loam learned to stamp must not brick the record\n * here.\n */\nexport function isEvidencePinList(v: unknown): boolean {\n  if (v === undefined) return true;\n  if (!Array.isArray(v)) return false;\n  for (const pin of v) {\n    if (!isRecord(pin)) return false;\n    if (typeof pin[\"path\"] !== \"string\") return false;\n    if (typeof pin[\"line\"] !== \"number\" || !Number.isInteger(pin[\"line\"]) || pin[\"line\"] < 1) return false;\n    if (typeof pin[\"file_sha256\"] !== \"string\" || typeof pin[\"text\"] !== \"string\") return false;\n    if (pin[\"token\"] !== undefined && typeof pin[\"token\"] !== \"string\") return false;\n  }\n  return true;\n}\n"]}
+{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4BnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAClF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,IAAY;IACpD,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClD,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvG,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5F,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The evidence pin's identity: what `verify --service --record` stamps beside a\n * confirmed agent answer so a later `loam validate`, standing in the same\n * service repository, can re-check the citation against the working tree.\n *\n * Be precise about what a pin proves, because the record travels without loam:\n * a pin identifies WHAT was cited at the attested commit — the cited file's\n * normalized sha256, the cited line's text, the literal token the claim\n * asserts. It does not prove the claim true; an agent that cited the wrong\n * line gets a faithful pin of the wrong line. That is why the read side\n * (`./lint.ts`) only ever demotes reviewer confidence: no pin state moves a\n * verdict in either direction.\n */\nimport { createHash } from \"node:crypto\";\nimport { isRecord } from \"../../kernel/records.js\";\n\nexport interface EvidencePin {\n  /** The cited file, repo-relative in the portable spelling evidence entries use. */\n  path: string;\n  /** The cited line, 1-based — the `:N` of the evidence entry this pins. */\n  line: number;\n  /** sha256 hex of the whole file at the attested commit, normalized — see {@link pinnedDigest}. */\n  file_sha256: string;\n  /** The cited line at the attested commit, trimmed and capped — see {@link pinnedText}. */\n  text: string;\n  /**\n   * The literal string the claim asserts of the cited artifact — the\n   * operationId for `api.exposes`, the message name for `event.declares`, the\n   * edge's op for `c4.calls` (`Claim.token`, stamped at record time). Carried\n   * on the pin so the read side scans the file for it and never has to\n   * re-derive a checklist or parse claim prose. Absent for the kinds that\n   * assert no token (`service.exists`, `scenario.tested`) — and absent when\n   * the attested blob did not CONTAIN the token: that fact is warned once, at\n   * record time, where the answerer can still act on it; a pin carrying it\n   * would make `loam validate` repeat \"no longer contains\" forever about a\n   * file that never did, with a re-record that re-derives the same state as\n   * the only offered repair. `token-missing` therefore always means \"was\n   * there at the attested commit and is gone\".\n   */\n  token?: string;\n}\n\n/**\n * How much of the cited line a pin carries. Enough to recognize a line of\n * source by eye and by equality; a cap because evidence may cite a line of a\n * generated client or a minified bundle, and the record is a YAML file people\n * read and diff — one pathological line must not turn it into one.\n */\nexport const PIN_TEXT_CAP = 200;\n\n/** The pin's line recipe: trimmed (indentation is formatting), capped at {@link PIN_TEXT_CAP}. */\nexport function pinnedText(line: string): string {\n  const trimmed = line.trim();\n  return trimmed.length > PIN_TEXT_CAP ? trimmed.slice(0, PIN_TEXT_CAP) : trimmed;\n}\n\n/**\n * The one spelling of where lines fall. Both sides of the pin — the write\n * side's bounds checks and the read side's re-grade — must number lines\n * identically, or a pin recorded at line 12 gets graded against a different\n * line 12; four call sites each spelling the regex themselves is how that\n * divergence would arrive, so the recipe has exactly one home.\n */\nexport function sourceLines(source: string): string[] {\n  return source.split(/\\r\\n|\\n|\\r/);\n}\n\n/**\n * The cited line of a source text, through the pin recipe — or undefined when\n * the line is past the end, which the caller grades (a refusal on the write\n * side, `unresolved` on the read side).\n */\nexport function citedLine(source: string, line: number): string | undefined {\n  const raw = sourceLines(source)[line - 1];\n  return raw === undefined ? undefined : pinnedText(raw);\n}\n\n/**\n * The pin's file digest: sha256 hex over the text with CRLF/CR normalized to\n * LF.\n *\n * Normalized because git's eol config makes blob bytes and working-tree bytes\n * legally differ: on a Windows checkout with `core.autocrlf=true`, the blob\n * the attested commit holds is LF while every file on disk is CRLF, so an\n * unnormalized digest would grade every pin `evidence.moved` forever on the\n * checkout config alone. The pin must convict content change, never checkout\n * config. The recipe is over TEXT by construction — the write side digests\n * `git show` output already decoded as utf8 — and the symmetric cost is\n * accepted and documented in SCHEMA.md: a pure line-ending change is invisible\n * to the lint.\n */\nexport function pinnedDigest(source: string): string {\n  return createHash(\"sha256\").update(source.replace(/\\r\\n|\\r/g, \"\\n\")).digest(\"hex\");\n}\n\n/**\n * The read-shape guard `asVerification` (../read/shape.ts) asks per claim, on the\n * `isConsumedContractReport` model to the letter: absent is fine — every\n * record written before pins existed, and every runner-answered claim, has\n * none — but present must be whole for the four fields the lint dereferences.\n * A broken pins block makes the WHOLE record unreadable and therefore never\n * overwritten, exactly the contract-report rule: it is somebody's record, and\n * a lint that silently skipped a malformed pin would read a hand-damaged\n * record as drift-free. `token` stays optional-and-any-string for `format`'s\n * reason — a field a newer loam learned to stamp must not brick the record\n * here.\n */\nexport function isEvidencePinList(v: unknown): boolean {\n  if (v === undefined) return true;\n  if (!Array.isArray(v)) return false;\n  for (const pin of v) {\n    if (!isRecord(pin)) return false;\n    if (typeof pin[\"path\"] !== \"string\") return false;\n    if (typeof pin[\"line\"] !== \"number\" || !Number.isInteger(pin[\"line\"]) || pin[\"line\"] < 1) return false;\n    if (typeof pin[\"file_sha256\"] !== \"string\" || typeof pin[\"text\"] !== \"string\") return false;\n    if (pin[\"token\"] !== undefined && typeof pin[\"token\"] !== \"string\") return false;\n  }\n  return true;\n}\n"]}