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

package/dist/commands/verify/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/commands/verify/verify.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { configOrRefuse, fail, repoPath } from \"../../core/envelope/json.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { type CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow } from \"../../core/staging/recovery/recover.js\";\nimport { docsRepoReady } from \"../policy/gate.js\";\nimport { featureChecklist } from \"../../core/verify/checklist.js\";\nimport { readVerificationState } from \"../../core/verify/read/file.js\";\nimport { report } from \"./report.js\";\nimport { reportFrozen } from \"./frozen.js\";\nimport { record } from \"./record.js\";\nimport { type VerifyOptions } from \"./record.js\";\nimport { diffAnswers, type AnswerFiles } from \"./cross/diff.js\";\n\n\nexport function registerVerify(program: Command): void {\n  program\n    .command(\"verify\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Check a feature against its own promises: derive the claims, record the answers with evidence\")\n    .option(\"--record <file>\", \"record a JSON answer set against the current checklist\")\n    .option(\n      \"--results <file>\",\n      \"answer the scenario.tested claims mechanically from a test report: cucumber JSON, or loam's runner-neutral loamScenarioReport JSON for any other runner\",\n    )\n    .option(\n      \"--contract-results <file>\",\n      \"answer the api.exposes claims mechanically from an API contract-test report (loam's generic contract-results JSON)\",\n    )\n    .option(\n      \"--diff-answers <files...>\",\n      \"cross-examine two independent answer sets against the current checklist (reads only, writes nothing)\",\n    )\n    .option(\n      \"--service <id>\",\n      \"record only this service's claims, bound to the current repository commit\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: VerifyOptions) => {\n      const json = opts.json === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      const recording =\n        opts.record !== undefined || opts.results !== undefined || opts.contractResults !== undefined;\n\n      // --diff-answers is a third READ form (see the WRITING/READING split\n      // below): it validates two answer sets against the same checklist and\n      // writes nothing, so combining it with any recording flag is a\n      // contradiction refused up front — before the binding, before the lock —\n      // rather than a mode silently picked between the two.\n      let diffFiles: AnswerFiles | null = null;\n      if (opts.diffAnswers !== undefined) {\n        if (recording) {\n          return fail(\n            json,\n            \"invalid-option\",\n            \"--diff-answers is a read-only cross-examination: it validates both files and writes nothing, \" +\n              \"so it cannot be combined with --record, --results or --contract-results. \" +\n              \"Diff first, then record the answer set you stand behind.\",\n          );\n        }\n        // Commander's variadic form consumes arguments until the next --flag,\n        // so a featureId placed AFTER the flag arrives here as a third file —\n        // this refusal is what turns that mistake into a sentence instead of a\n        // diff of the wrong files.\n        const [a, b] = opts.diffAnswers;\n        if (opts.diffAnswers.length !== 2 || a === undefined || b === undefined) {\n          return fail(\n            json,\n            \"invalid-option\",\n            \"--diff-answers takes exactly two answer files: --diff-answers a.json b.json\",\n          );\n        }\n        diffFiles = { a, b };\n      }\n\n      // WRITING is bound to the repository; READING is not. An attestation\n      // pins claims to this repo's git HEAD and to file:line evidence inside\n      // it, so writing (--record, --results or --contract-results) with\n      // `--service X` may only run where loam.json says this repo IS X —\n      // vouch's and gherkin's refusal, for vouch's reason: from anywhere\n      // else, that repository is somebody else's. Reading takes\n      // `--service` as a pure lens (which claims are checkout-web's, and what\n      // has it said?) and needs no binding at all, because it writes nothing.\n      if (recording && opts.service !== undefined) {\n        if (config.service === undefined) {\n          return fail(\n            json,\n            \"repository-unavailable\",\n            `Cannot attest for '${opts.service}' from here: this is not a service repo — loam.json declares no \\`service\\`. ` +\n              `A federated attestation binds the answers to this repository's git HEAD and to evidence inside it, so the repository has to say which service it is. ` +\n              `Add \"service\": \"${opts.service}\" to loam.json, or record it from that service's own repo.`,\n          );\n        }\n        if (config.service !== opts.service) {\n          return fail(\n            json,\n            \"service-mismatch\",\n            `This repository is configured as service '${config.service}', so it cannot attest claims for '${opts.service}'.`,\n          );\n        }\n      }\n\n      // Before the lock, because the lock is a file INSIDE the docs repo: a\n      // `docsDir` pointing at nothing used to surface as the lock file's own\n      // ENOENT — an `internal` where the read side of this same command names\n      // the misconfiguration. \"docs\", not \"services\", in BOTH modes — and that\n      // is a pinned contract, not looseness: the legacy all-at-once form\n      // records against a features-only docs repo with no `services/` at all,\n      // and it has always exited 0 there. The cost is real and accepted: a\n      // typo'd `docsDir` pointing at some existing non-docs directory gets a\n      // `.loam-lock` created and removed inside it. The gate above only\n      // guarantees the directory exists.\n      if (!docsRepoReady(json, docsDir, \"docs\")) return;\n\n      // A record is a merge over the docs repo, so recording takes the docs\n      // lock — the same one archive, unarchive and rebase hold — and takes it\n      // HERE, before the feature is even resolved. Behind the lock, an archive\n      // can rename this feature's directory into features/archive/ at any\n      // moment; a feature resolved before the lock could have its record\n      // written into the pre-move path, a file nothing will ever read again.\n      // The waiting form rather than archive's refuse-fast one, because two\n      // recorders for different services of one feature are both supposed to\n      // land: the second waits out the first's sub-second window and merges\n      // over what it left. Reading stays lock-free — it writes nothing.\n      //\n      // A journal under the lock means the last writer never finished. The\n      // record's own authoritative read is about to happen; reading it over\n      // a half-commit would merge against bytes no run ever produced — the\n      // last docs-repo writer that could still silently treat a half-commit\n      // as healthy. That refusal must release the lock like every other path\n      // out, and once did not; `openCommitWindow` releases it before it answers.\n      let releaseLock: (() => Promise<void>) | null = null;\n      let recovered: CommitRecovery | null = null;\n      if (recording) {\n        const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);\n        if (!opened.ok) return fail(json, opened.code, opened.message);\n        releaseLock = opened.release;\n        recovered = opened.recovered;\n      }\n      try {\n        // Archived features resolve too: a shipped feature's verification is worth\n        // reading back, and it travelled into the archive with everything else.\n        const feature = await resolveFeature(docsDir, featureId, \"include\");\n        if (!feature) {\n          // repo.ts's sentence, not a second copy of it. Resolving with \"include\"\n          // means the archived branch inside it cannot fire here — an archived\n          // feature resolves — so the text is exactly what it was; what changes is\n          // that a reworded miss message can no longer leave this one behind.\n          return fail(json, \"unknown-target\", await missingFeatureMessage(docsDir, featureId));\n        }\n\n        // The cross-examination lens leaves BEFORE the record is read below:\n        // it never consumes verification.yaml, and the moment a\n        // cross-examination is most needed is exactly when the record on disk\n        // is too damaged to read and somebody is about to re-record over it —\n        // the record-unreadable refusal must not bar the one command that\n        // would inform that re-recording. The archived refusal still applies,\n        // with the recording branch's code and reason: there is no current\n        // checklist to answer, so the wrong thing is the option, not the\n        // answer sets.\n        if (diffFiles !== null) {\n          if (feature.archived) {\n            return fail(\n              json,\n              \"invalid-option\",\n              `${feature.id} is archived — there is no current checklist to answer, so there is nothing to cross-examine; its record is frozen history. \\`loam unarchive ${feature.id}\\` first if the claims really need re-answering.`,\n            );\n          }\n          await diffAnswers(\n            { docsDir, featureDir: feature.dir, json },\n            await featureChecklist(docsDir, feature.dir, feature.id),\n            diffFiles,\n            { lens: opts.service },\n          );\n          return;\n        }\n\n        // Before anything else: a record file that exists but will not read\n        // is a refusal, not an absence. It holds somebody's answers and — in a\n        // fleet — other repositories' attestations; treating it as \"not verified\"\n        // let the next --record silently overwrite all of it, and made the read\n        // view say \"no record\" about a file sitting right there.\n        //\n        // The path is the one FILE that failed, and the advice is that file's:\n        // the record is several files now, and the recipe that is safe for a\n        // service's own attestation file (delete it, record that service again)\n        // is the one that erases a fleet's evidence when the file is the shared\n        // one-file record — which is what this refusal used to tell everyone,\n        // and what a miscounted record's \"record again\" looped back into.\n        //\n        // An in-flight feature's checklist is derived FIRST, because which of\n        // those files count depends on it: a record kept as per-service files\n        // answers the question being asked now, and only the caller knows what\n        // that is (`core/verify/read/union.ts`). Read without it, a service\n        // that recorded the current checklist could lose a same-day tie to one\n        // that recorded an older one, and this view called the whole record\n        // stale. An archived feature derives nothing — see below.\n        const checklist = feature.archived ? null : await featureChecklist(docsDir, feature.dir, feature.id);\n        const existing = await readVerificationState(feature.dir, checklist?.digest);\n        if (existing.state === \"unreadable\") {\n          return fail(\n            json,\n            \"record-unreadable\",\n            `${repoPath(docsDir, existing.path)} exists but cannot be read as a verification record: ${existing.reason}. ` +\n              `${existing.advice} loam will not overwrite a record it could not read.`,\n          );\n        }\n        const recorded = existing.state === \"ok\" ? existing.verification : null;\n\n        // But an archived feature never gets a re-derived checklist — see the\n        // header. Its record is frozen history, and --record / --results refuse\n        // alike: the code is `invalid-option` rather than `answers-mismatch`\n        // because the answers were never compared to anything — there is no\n        // current checklist to answer, so the wrong thing here is the option,\n        // not the answer set. (`checklist` is null exactly when the feature is\n        // archived — the test is spelled on it so the compiler knows the\n        // in-flight path below has one.)\n        if (checklist === null) {\n          if (recording) {\n            return fail(\n              json,\n              \"invalid-option\",\n              `${feature.id} is archived — its verification is history now. \\`loam unarchive ${feature.id}\\` first if the answers really need to change.`,\n            );\n          }\n          reportFrozen({ docsDir, featureDir: feature.dir, json }, feature.id, recorded);\n          return;\n        }\n\n        if (recording) {\n          // Standing in a service repo, `--service` is what the repo already\n          // says: omitting it must not fall back to the legacy all-at-once form,\n          // which claims the whole fleet's checklist on this one repo's word.\n          //\n          // The repo root, not the cwd — `vouch`'s and `gherkin`'s reason. An\n          // attestation names a commit and rests on evidence resolved inside\n          // \"this repository\", and `config.root` is the directory loam.json was\n          // actually found in. Off `process.cwd()`, running from a subdirectory\n          // silently changed all three: evidence resolved against the\n          // subdirectory, `--results` had to live in it, and `git rev-parse` ran\n          // there — a submodule or nested checkout under it would have named\n          // somebody else's commit on this repository's attestation.\n          //\n          // `config.service` and not `opts.service ?? config.service`, though\n          // the two are the same value: the binding refusal above lets a\n          // recording `--service` through only when it EQUALS the configured\n          // service. Taking the configured one keeps its brand — loam.json's\n          // reader validated it against the id grammar — and that brand is\n          // what `serviceRecordPath` demands before it joins the id into a\n          // file name. The raw flag never reaches the join.\n          await record(\n            { docsDir, featureDir: feature.dir, json, recovered },\n            checklist,\n            {\n              service: config.service,\n              repoDir: config.root ?? process.cwd(),\n              previous: existing.state === \"ok\" ? { verification: existing.verification, files: existing.files } : null,\n            },\n            opts,\n          );\n          return;\n        }\n\n        report({ docsDir, featureDir: feature.dir, json }, checklist, recorded, {\n          lens: opts.service,\n          bound: config.service,\n        });\n      } finally {\n        // Released on every path out — a refusal that kept the lock would turn\n        // one bad answer set into a wedged docs repo for everyone else.\n        if (releaseLock !== null) await releaseLock();\n      }\n    });\n}\n"]}

package/dist/commands/vouch/contract.js

@@ -0,0 +1,11 @@
+/**
+ * What a vouch IS: the request, the stamp it writes, and every way it can
+ * refuse.
+ *
+ * The outcome is a union rather than a result plus an error field because the
+ * command prints a different shape for each arm, and the stamp only exists on
+ * the arm that wrote one. A flat record would have every reader assert what the
+ * writer already knew.
+ */
+import {} from "../../core/envelope/json.js";
+//# sourceMappingURL=contract.js.map

package/dist/commands/vouch/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/commands/vouch/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAkB,MAAM,6BAA6B,CAAC","sourcesContent":["/**\n * What a vouch IS: the request, the stamp it writes, and every way it can\n * refuse.\n *\n * The outcome is a union rather than a result plus an error field because the\n * command prints a different shape for each arm, and the stamp only exists on\n * the arm that wrote one. A flat record would have every reader assert what the\n * writer already knew.\n */\nimport { type ErrorCode } from \"../../core/envelope/json.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../core/kernel/ids/service.js\";\nimport type { CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport type { VouchScope } from \"../../core/provenance/sample/scope.js\";\nimport type { SkippedSource } from \"../../core/provenance/walk.js\";\n// The plan's shapes live with the pass that derives them (`sample/plan.ts`),\n// the way pack's `SectionDelta` lives with `pack/sections.ts`. The import\n// direction is parent-from-child, which is the only one the package graph\n// allows here: a sub-package that reached back up into this file would close\n// the cycle `vet/verify.ts` was moved down to avoid.\nimport type { SamplePlan } from \"./sample/plan.js\";\n\nexport interface VouchRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what `sources` resolve against. */\n  repoDir: string;\n  /** The date to stamp. Injected rather than read off the clock, so it can be pinned. */\n  today: string;\n  /**\n   * Who is vouching, as `vouched_by` is stamped — git's identity for `repoDir`.\n   * Injected for the same reason `today` is: this function must be reproducible\n   * from its arguments, and the resolution (and its refusal) belongs to the\n   * command that can talk to a person about it.\n   */\n  vouchedBy: string;\n  /**\n   * The sample a person was shown before they answered, under `--sample <n>`.\n   * Absent for an ordinary vouch — and its absence is what CLEARS a prior\n   * sampled stamp, since a full run deletes `vouch_scope` from every file it\n   * writes.\n   */\n  sample?: SamplePlan;\n}\n\n/** One spec-axis file's share of a successful vouch. */\nexport interface StampedSpec {\n  /** Absolute path of the file that was stamped. */\n  path: string;\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". */\n  file: string;\n  /** Digest of the sources, as stamped into `sources_digest`. */\n  digest: string;\n  /** Digest of the document's own body, as stamped into `content_digest`. */\n  contentDigest: string;\n  /** The `sources` entries, as written in the frontmatter. */\n  sources: string[];\n  /** How many files those entries expanded to. */\n  files: number;\n  /**\n   * Paths under those entries the digest would not hash. A vouch over a spec\n   * with a skipped path is still a vouch — the person read what they read — but\n   * they are told, because the stamp cannot go stale over bytes it never saw.\n   */\n  skipped: SkippedSource[];\n  /**\n   * What was written into `vouch_scope`, or null when the file was read in\n   * full and the field was deleted. The report describes what the stamp\n   * ACTUALLY says rather than what the plan asked for: a file whose section\n   * count was at or under `--sample <n>` is stamped as a full vouch, and the\n   * screen the person is looking at has to say so.\n   */\n  vouchScope: VouchScope | null;\n}\n\nexport type VouchOutcome =\n  | {\n      ok: true;\n      status: \"verified\";\n      lastVerified: string;\n      /** The identity stamped into every file this vouch touched. */\n      vouchedBy: string;\n      /**\n       * Non-null when this run first rolled a predecessor's interrupted\n       * commit forward — the caller reports it, because docs changing beyond\n       * the stamp would otherwise read as this vouch's doing.\n       */\n      recovered: CommitRecovery | null;\n      /**\n       * Every spec-axis file stamped. Named, not ordered: spec.md is required\n       * for a vouch to happen at all, and arch.spec.md is the only other file\n       * one can touch, so the type is what says which is which. An array said it\n       * in a comment instead, and every reader had to assert non-emptiness to\n       * reach the file that comment promised was there.\n       */\n      stamped: { spec: StampedSpec; archSpec: StampedSpec | null };\n    }\n  | {\n      ok: false;\n      // The last three are the commit phase failing: `vouch-raced` says the\n      // document moved under the run and nothing was written at all,\n      // `merge-failed` says the rollback held (nothing was stamped, re-running\n      // can work), `rollback-incomplete` says it did not and the message lists\n      // the files.\n      code: Extract<\n        ErrorCode,\n        | \"unknown-target\"\n        | \"sources-absent\"\n        | \"sources-path-missing\"\n        // The spec is there but is not UTF-8 text: a diagnosable state, not the\n        // unexpected throw `internal` is for.\n        | \"repository-unavailable\"\n        | \"vouch-raced\"\n        | \"merge-failed\"\n        | \"rollback-incomplete\"\n        // The commit window now takes the docs lock and reads the journal:\n        // another writer can hold the one, a predecessor's crash can leave\n        // the other. Both are the codes every other journaled writer answers.\n        | \"docs-busy\"\n        | \"commit-interrupted\"\n      >;\n      message: string;\n    };\n"]}

package/dist/commands/vouch/pack/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/commands/vouch/pack/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/commands/vouch/pack/contract.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * What a reading pack IS: the request, the per-axis verdicts, and the one way\n * it can refuse. The same seam as `../contract.ts` one level up — the shapes\n * live apart from the derivation so the printer can name what it renders\n * without importing how it was computed.\n *\n * Every verdict is a discriminated union rather than optional-field soup, and\n * the arms are exactly the honest answers: a body is unchanged, or diffable\n * from a NAMED ancestor, or a full read with the reason — never a guessed\n * diff; sources are unchanged, a named delta, a counted-but-nameless move, a\n * state the re-vouch itself would refuse over, or simply unvouched.\n */\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport type { SkippedSource } from \"../../../core/provenance/walk.js\";\nimport type { LandscapeEdge } from \"../../../core/vocabulary/maturity.js\";\nimport type { PackSample, PackVouchScope, SectionDelta } from \"./sections.js\";\n\nexport interface PackRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what the source delta resolves `sources` against. */\n  repoDir: string;\n  /**\n   * `--sample <n>`, when the pack is being read as the reading list for a\n   * SAMPLED vouch. The pack then prescribes exactly the sections that\n   * `loam vouch --sample <n>` will stamp for, through the same seeded\n   * derivation — a pack and a stamp that disagreed about which sections were\n   * read would make the record worse than no record.\n   */\n  sample?: number;\n}\n\n/** The body half of one axis's pack: what to read of the document itself. */\nexport type PackBody =\n  | { kind: \"unchanged\" }\n  | { kind: \"diff\"; ancestorCommit: string; diff: string; sections: SectionDelta }\n  | { kind: \"full-read\"; reason: string };\n\n/** The source half: what moved under the code the document was written from. */\nexport type PackSources =\n  | { kind: \"unchanged\" }\n  | { kind: \"delta\"; added: string[]; changed: string[]; removed: string[] }\n  /**\n   * The digest moved but the stamp cannot name the paths — the count-only\n   * >100-file fallback (`countThen` known) or an index that contradicts its\n   * own digest (`countThen` null when even the count is unreadable).\n   */\n  | { kind: \"uncounted\"; countThen: number | null; countNow: number }\n  /** The re-vouch itself would refuse over these sources; the reason IS the worklist. */\n  | { kind: \"unavailable\"; reason: string }\n  /** Sources resolve but carry no stamp — nothing to diff against yet. */\n  | { kind: \"unvouched\" };\n\nexport interface PackAxis {\n  /** Docs-relative, `/`-separated — the contract's path spelling. */\n  path: string;\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". */\n  file: string;\n  /** The stamp's own fields, read back for the \"already covered\" listing. */\n  vouchedBy?: string;\n  lastVerified?: string;\n  body: PackBody;\n  sources: PackSources;\n  /**\n   * Paths under the listed sources the digest recompute would not hash —\n   * walk.ts's skip record, carried on the axis because it is orthogonal to\n   * the sources verdict (it can accompany unchanged, delta and unvouched\n   * alike). Never dropped: these are the parts of the tree the re-vouch's\n   * promise will NOT cover, and the pack is now the screen a person reads\n   * BEFORE staking that promise. Empty when the vetting itself refused —\n   * nobody walked, so nobody can name what a walk would skip.\n   */\n  skipped: SkippedSource[];\n  /**\n   * Every H2 heading of the current body — set whenever the whole file is the\n   * read (`body.kind === \"full-read\"`: a first vouch, a never-vouched axis, a\n   * body whose vouched ancestor cannot be reached), because a full read is\n   * exactly where the listing IS the reading plan. Per axis, not per mode:\n   * an arch.spec.md created after the last vouch gets its plan inside a\n   * re-vouch pack.\n   */\n  headings?: string[];\n  /**\n   * The LAST vouch's scope, when that vouch was sampled — present-but-\n   * undecodable included, because an unreadable scope on a verified document\n   * must never read as a full vouch. Its presence withdraws the \"already\n   * covered\" licence for this axis: `unchanged` says the text did not move,\n   * and after a sampled vouch that is not the same fact as \"somebody read it\".\n   */\n  vouchScope?: PackVouchScope;\n  /**\n   * What a `--sample <n>` vouch would cover, under `--pack --sample <n>`. The\n   * forward direction, where `vouchScope` above is the backward one: one says\n   * what the next stamp will claim, the other what the last one did.\n   */\n  sample?: PackSample;\n}\n\n/** What the fleet map says about the service — the first read of a first vouch. */\nexport type PackLandscape =\n  | { kind: \"edges\"; inbound: LandscapeEdge[]; outbound: LandscapeEdge[] }\n  | { kind: \"silent\"; reason: string };\n\nexport interface PackReport {\n  service: string;\n  /** \"first-vouch\" when spec.md carries neither digest — nothing exists to diff against. */\n  packMode: \"re-vouch\" | \"first-vouch\";\n  /**\n   * A predecessor's interrupted docs-repo commit journal exists, so what is\n   * on disk may predate the write it was killed inside — including the very\n   * stamps this pack read. The pack cannot roll the journal forward (recovery\n   * is itself a write, and this command may not write), so it says so instead\n   * of silently describing a state the next journaled writer will replace.\n   */\n  pendingCommit: boolean;\n  spec: PackAxis;\n  archSpec: PackAxis | null;\n  /** First-vouch only (null otherwise): landscape claims come first in the reading order. */\n  landscape: PackLandscape | null;\n}\n\nexport type PackOutcome =\n  | { ok: true; report: PackReport }\n  | { ok: false; code: \"unknown-target\"; message: string };\n"]}

package/dist/commands/vouch/pack/pack.js

@@ -0,0 +1,266 @@
+/**
+ * The re-vouch reading pack: everything `loam vouch --pack` computes and
+ * nothing it prints. Three derivations per spec-axis file, all read-only and
+ * all from stamps `loam vouch` already writes — (a) the body's diff from the
+ * last commit whose version of the file hashes to the stamped
+ * `content_digest`, (b) the source files that moved against the stamped
+ * per-file index, (c) the sections whose text is identical to the vouched
+ * ancestor's, which the person need not re-read. Nothing here writes, locks
+ * or stamps; a "pack" in vouch's vocabulary is always the READING pack — the
+ * context pack (`core/pack/`) is a different artifact for a different reader.
+ *
+ * Why this mode may relax vouch's unattended refusal: the vouch gates
+ * (identity, TTY, `--yes`, the docs lock) all defend the WRITE — a
+ * `status: verified` no person stood behind. The pack writes nothing and can
+ * stamp nothing, so refusing it unattended would only stop agents from doing
+ * the one thing they are supposed to do here: prepare the exact reading list
+ * a HUMAN then works through before running the vouch itself, which keeps
+ * every one of its gates. That is also why `--pack --yes` is refused at the
+ * flag boundary (vouch.ts): the two flags point at opposite halves of the
+ * act, and a pack that stamped would defeat the read it just prescribed.
+ * Journal recovery is different in kind: it is not a gate but a read-side
+ * NEED (run.ts rolls it forward "before verification reads a byte" precisely
+ * because it changes files a reader has already read), and the pack cannot
+ * perform it because recovery is itself a write — so `buildPack` detects the
+ * pending journal and reports it instead. What survives unchanged is the
+ * wrong-repo gate — the source delta resolves `sources` against the
+ * service's own repo, so from anywhere else the paths are someone else's.
+ *
+ * The fail-closed doctrine, stated once for all three parts: when git cannot
+ * answer — no repository, no history, the walk's cap passed, a decline
+ * mid-walk — the body degrades to "full read", never to a guessed diff; and
+ * an unanswerable question never shrinks the list, because "nobody could
+ * look" is not "nothing changed". Only the axis's UNCHANGED list may licence
+ * skipping a section, and it is only ever computed from a found ancestor or
+ * a digest-equal body.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadFile } from "../../../core/c4/likec4.js";
+import { serviceResolver } from "../../../core/c4/resolve/service.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { contentDigest, parseFrontmatter, rawBody, stringField } from "../../../core/document/frontmatter.js";
+import { sectionHeadings } from "../../../core/document/parse.js";
+import { bodyDiffText, findVouchedAncestor } from "../../../core/provenance/gitq/vouched-ancestor.js";
+import { decodeSourceIndex, sourceDelta } from "../../../core/provenance/stamp.js";
+import { landscapePath, servicePathsAt, SPEC_AXES, unfiledServicePaths } from "../../../core/repo/paths.js";
+import { enumeratedServices } from "../../../core/repo/service-target.js";
+import { COMMIT_INTENT } from "../../../core/staging/interrupted.js";
+import { NotUtf8Error, readUtf8 } from "../../../core/staging/writes.js";
+import { landscapeEvidence } from "../../../core/vocabulary/maturity.js";
+import { noLivingSpecMessage, verifySpec } from "../vet/verify.js";
+import { forwardSample, priorScope, sectionDelta } from "./sections.js";
+async function readAxis(path) {
+    try {
+        const raw = await readUtf8(path);
+        return { kind: "read", raw, fm: parseFrontmatter(raw) };
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8Error))
+            throw err;
+        return { kind: "unreadable", reason: err.message };
+    }
+}
+export async function buildPack(req) {
+    // One enumeration answers both questions this function has: where the
+    // service's files live (a filed service is not at the root join), and which
+    // ids the landscape's resolver may bind to (the same `known` set every
+    // other landscape reader passes). The two-line resolution below is
+    // `locateServicePaths` (core/repo/service-target.ts) inlined — that helper
+    // enumerates internally, and calling it here would walk the tree twice.
+    const entries = await enumeratedServices(req.docsDir);
+    const entry = entries.find((s) => s.id === req.service);
+    const paths = entry === undefined ? unfiledServicePaths(req.docsDir, req.service) : servicePathsAt(entry.dir);
+    if (!existsSync(paths.spec)) {
+        // One sentence, from `vet/verify.ts`: these commands must not describe the
+        // same absence differently, and the fix — adopt first — is the same fix.
+        return { ok: false, code: "unknown-target", message: noLivingSpecMessage(paths.spec, req.service) };
+    }
+    const [specAxis, archAxis] = SPEC_AXES;
+    const specRead = await readAxis(paths[specAxis.key]);
+    // First vouch is a property of the REQUIRED axis: with neither digest
+    // stamped on spec.md there is no prior read to diff against, so the pack is
+    // the whole document, landscape claims first. A malformed or unreadable
+    // header deliberately does NOT count as first-vouch — it cannot prove the
+    // stamps absent, and claiming "first vouch" over a document that may carry
+    // one would order the read around a guess.
+    const firstVouch = specRead.kind === "read" &&
+        !specRead.fm.malformed &&
+        stringField(specRead.fm, "content_digest") === undefined &&
+        stringField(specRead.fm, "sources_digest") === undefined;
+    const spec = await packAxis(req, { path: paths[specAxis.key], file: specAxis.file, read: specRead });
+    let archSpec = null;
+    if (existsSync(paths[archAxis.key])) {
+        const archRead = await readAxis(paths[archAxis.key]);
+        archSpec = await packAxis(req, { path: paths[archAxis.key], file: archAxis.file, read: archRead });
+    }
+    const knownIds = new Set(entries.map((s) => s.id));
+    return {
+        ok: true,
+        report: {
+            service: req.service,
+            packMode: firstVouch ? "first-vouch" : "re-vouch",
+            // One existsSync, the same one run.ts pays before verification reads a
+            // byte: a predecessor's journal means the stamps just read may predate
+            // the write it was killed inside. The pack cannot recover (a write) —
+            // it warns, and the next journaled writer rolls the journal forward.
+            pendingCommit: existsSync(join(req.docsDir, COMMIT_INTENT)),
+            spec,
+            archSpec,
+            landscape: firstVouch ? await landscapeSlice(req.docsDir, req.service, knownIds) : null,
+        },
+    };
+}
+/** One spec-axis file's full share of the pack: body verdict, source verdict, stamp fields. */
+async function packAxis(req, axis) {
+    const rel = repoPath(req.docsDir, axis.path);
+    // The source half rides on verifySpec — the vouch's own vetting, message
+    // for message. The pack never refuses over sources: "your re-vouch will
+    // refuse, fix this first" IS the worklist, so the refusal sentence travels
+    // as the `unavailable` reason instead of an exit code.
+    const vetted = await verifySpec({ service: req.service, repoDir: req.repoDir }, axis.path, axis.file);
+    // What the digest recompute would NOT hash. Empty on a refusal because
+    // nobody walked — never because there is nothing to say.
+    const skipped = vetted.ok ? vetted.skipped : [];
+    if (axis.read.kind === "unreadable") {
+        // Per-axis containment: an undecodable file suspends THIS axis with the
+        // decode error as both reasons — the sibling axis still gets its pack.
+        return {
+            path: rel,
+            file: axis.file,
+            body: { kind: "full-read", reason: axis.read.reason },
+            sources: { kind: "unavailable", reason: vetted.ok ? axis.read.reason : vetted.message },
+            skipped,
+        };
+    }
+    const { raw, fm } = axis.read;
+    const vouchedBy = stringField(fm, "vouched_by");
+    const lastVerified = stringField(fm, "last_verified");
+    const body = await bodyArm(req, { rel, raw, fm });
+    const sources = sourcesArm(vetted, fm);
+    const stampedScope = priorScope(fm, body.kind === "unchanged" ? rawBody(raw) : null);
+    return {
+        path: rel,
+        file: axis.file,
+        ...(vouchedBy === undefined ? {} : { vouchedBy }),
+        ...(lastVerified === undefined ? {} : { lastVerified }),
+        body,
+        sources,
+        skipped,
+        // A full read is exactly where the heading listing IS the reading plan —
+        // per axis, not per mode, so an arch.spec.md created after the last vouch
+        // gets its plan inside a re-vouch pack. `rawBody` first so no frontmatter
+        // line can ever masquerade as a section.
+        ...(body.kind === "full-read" ? { headings: sectionHeadings(rawBody(raw)).map((h) => h.text) } : {}),
+        // Only an UNCHANGED body can license naming what the last sampled vouch
+        // read: the recompute needs the bytes that vouch was taken over, and a
+        // digest-equal body is exactly those bytes. When the body has moved the
+        // scope is still reported — it still means the document was not read in
+        // full — with no covered list behind it. Reaching back to the vouched
+        // ancestor for the older body would be more information; it would also
+        // put a git walk behind a claim about what a person read, and the answer
+        // when git cannot speak would have to be this same one.
+        ...(stampedScope === null ? {} : { vouchScope: stampedScope }),
+        ...(req.sample === undefined || !vetted.ok
+            ? {}
+            : { sample: forwardSample({ service: req.service, raw, sourcesDigest: vetted.digest, n: req.sample }) }),
+    };
+}
+/** The body verdict: unchanged, a diff from the vouched ancestor, or an honest full read. */
+async function bodyArm(req, doc) {
+    // Deliberately NOT branched on the report-level first-vouch mode: the mode
+    // orders the read (landscape first), but each axis answers from its OWN
+    // stamps. In the one corpus where they disagree — spec.md hand-reverted to
+    // draft while arch.spec.md still carries a stamp — the stamped axis gets
+    // its real diff rather than a false "nobody has read this yet".
+    if (doc.fm.malformed) {
+        return {
+            kind: "full-read",
+            reason: "the frontmatter cannot be read as YAML, so whatever content_digest it carries is unreachable — fix the header, then read the whole file",
+        };
+    }
+    const stamped = stringField(doc.fm, "content_digest");
+    if (stamped === undefined) {
+        return {
+            kind: "full-read",
+            reason: stringField(doc.fm, "sources_digest") === undefined
+                ? "this file has never been vouched, so the whole of it is the read"
+                : "the last vouch predates content_digest, so no vouched body exists to diff from — read the whole file",
+        };
+    }
+    // The cheap answer first, and without git: the digest recipe is byte-exact
+    // over the working-tree file, so equality here IS "no byte of the body
+    // moved since the stamp".
+    if (contentDigest(doc.raw) === stamped)
+        return { kind: "unchanged" };
+    const ancestor = await findVouchedAncestor(req.docsDir, doc.rel, stamped);
+    if (ancestor.kind !== "found") {
+        return { kind: "full-read", reason: ancestor.kind === "none" ? ancestor.reason : ancestor.detail };
+    }
+    const diff = await bodyDiffText(req.docsDir, ancestor.commit, doc.rel);
+    // An ancestor without a printable diff could still licence a section delta,
+    // but a pack that says "these sections changed, no diff shown" invites
+    // skipping the rest on this run's partial word — degrade the whole arm to
+    // the full read instead; read more, never less.
+    if (diff.kind === "failed")
+        return { kind: "full-read", reason: diff.reason };
+    return {
+        kind: "diff",
+        ancestorCommit: ancestor.commit,
+        diff: diff.diff,
+        sections: sectionDelta(rawBody(ancestor.text), rawBody(doc.raw)),
+    };
+}
+/** The source verdict, from the vouch's own vetting plus the stamped digests. */
+function sourcesArm(vetted, fm) {
+    if (!vetted.ok)
+        return { kind: "unavailable", reason: vetted.message };
+    const stamped = stringField(fm, "sources_digest");
+    if (stamped === undefined)
+        return { kind: "unvouched" };
+    if (vetted.digest === stamped)
+        return { kind: "unchanged" };
+    const index = decodeSourceIndex(stringField(fm, "sources_files"));
+    const delta = sourceDelta(index, vetted.index);
+    if (delta === null)
+        return { kind: "uncounted", countThen: index.count ?? null, countNow: vetted.index.length };
+    return { kind: "delta", ...delta };
+}
+/**
+ * The fleet map's claims about the service — a first vouch reads these before
+ * the spec, because the landscape is the one document making claims ABOUT the
+ * service that the person is not the author of. Absence and unparseability
+ * both come back as `silent`: per landscapeEvidence's own rule they prove
+ * nothing about who calls the service, and the pack says so rather than
+ * printing an empty edge list that reads as "nobody does".
+ */
+async function landscapeSlice(docsDir, service, known) {
+    const silent = {
+        kind: "silent",
+        reason: `the fleet map says nothing about ${service} (absent or unparseable)`,
+    };
+    const path = landscapePath(docsDir);
+    if (!existsSync(path))
+        return silent;
+    let land;
+    try {
+        land = await loadFile(path);
+    }
+    catch {
+        // Unreadable is not "no claims" — but for a reading list both collapse to
+        // the same honest sentence: the map cannot brief this read.
+        return silent;
+    }
+    if (land.errors.length > 0)
+        return silent;
+    const svcOf = serviceResolver(land.elements, known);
+    const evidence = landscapeEvidence({
+        id: service,
+        parses: true,
+        relationships: land.relationships,
+        elementIds: land.elements.map((e) => e.id),
+        svcOf,
+    });
+    return { kind: "edges", inbound: evidence.inbound, outbound: evidence.outbound };
+}
+//# sourceMappingURL=pack.js.map

package/dist/commands/vouch/pack/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../../../src/commands/vouch/pack/pack.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The re-vouch reading pack: everything `loam vouch --pack` computes and\n * nothing it prints. Three derivations per spec-axis file, all read-only and\n * all from stamps `loam vouch` already writes — (a) the body's diff from the\n * last commit whose version of the file hashes to the stamped\n * `content_digest`, (b) the source files that moved against the stamped\n * per-file index, (c) the sections whose text is identical to the vouched\n * ancestor's, which the person need not re-read. Nothing here writes, locks\n * or stamps; a \"pack\" in vouch's vocabulary is always the READING pack — the\n * context pack (`core/pack/`) is a different artifact for a different reader.\n *\n * Why this mode may relax vouch's unattended refusal: the vouch gates\n * (identity, TTY, `--yes`, the docs lock) all defend the WRITE — a\n * `status: verified` no person stood behind. The pack writes nothing and can\n * stamp nothing, so refusing it unattended would only stop agents from doing\n * the one thing they are supposed to do here: prepare the exact reading list\n * a HUMAN then works through before running the vouch itself, which keeps\n * every one of its gates. That is also why `--pack --yes` is refused at the\n * flag boundary (vouch.ts): the two flags point at opposite halves of the\n * act, and a pack that stamped would defeat the read it just prescribed.\n * Journal recovery is different in kind: it is not a gate but a read-side\n * NEED (run.ts rolls it forward \"before verification reads a byte\" precisely\n * because it changes files a reader has already read), and the pack cannot\n * perform it because recovery is itself a write — so `buildPack` detects the\n * pending journal and reports it instead. What survives unchanged is the\n * wrong-repo gate — the source delta resolves `sources` against the\n * service's own repo, so from anywhere else the paths are someone else's.\n *\n * The fail-closed doctrine, stated once for all three parts: when git cannot\n * answer — no repository, no history, the walk's cap passed, a decline\n * mid-walk — the body degrades to \"full read\", never to a guessed diff; and\n * an unanswerable question never shrinks the list, because \"nobody could\n * look\" is not \"nothing changed\". Only the axis's UNCHANGED list may licence\n * skipping a section, and it is only ever computed from a found ancestor or\n * a digest-equal body.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { loadFile } from \"../../../core/c4/likec4.js\";\nimport { serviceResolver } from \"../../../core/c4/resolve/service.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { contentDigest, parseFrontmatter, rawBody, stringField, type Frontmatter } from \"../../../core/document/frontmatter.js\";\nimport { sectionHeadings } from \"../../../core/document/parse.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { bodyDiffText, findVouchedAncestor } from \"../../../core/provenance/gitq/vouched-ancestor.js\";\nimport { decodeSourceIndex, sourceDelta } from \"../../../core/provenance/stamp.js\";\nimport { landscapePath, servicePathsAt, SPEC_AXES, unfiledServicePaths } from \"../../../core/repo/paths.js\";\nimport { enumeratedServices } from \"../../../core/repo/service-target.js\";\nimport { COMMIT_INTENT } from \"../../../core/staging/interrupted.js\";\nimport { NotUtf8Error, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { landscapeEvidence } from \"../../../core/vocabulary/maturity.js\";\nimport { noLivingSpecMessage, verifySpec } from \"../vet/verify.js\";\nimport type { PackAxis, PackBody, PackLandscape, PackOutcome, PackRequest, PackSources } from \"./contract.js\";\nimport { forwardSample, priorScope, sectionDelta } from \"./sections.js\";\n\n/** One axis file off disk: its text and header, or the reason nobody could read it. */\ntype AxisRead =\n  | { kind: \"read\"; raw: string; fm: Frontmatter }\n  | { kind: \"unreadable\"; reason: string };\n\nasync function readAxis(path: string): Promise<AxisRead> {\n  try {\n    const raw = await readUtf8(path);\n    return { kind: \"read\", raw, fm: parseFrontmatter(raw) };\n  } catch (err) {\n    if (!(err instanceof NotUtf8Error)) throw err;\n    return { kind: \"unreadable\", reason: err.message };\n  }\n}\n\nexport async function buildPack(req: PackRequest): Promise<PackOutcome> {\n  // One enumeration answers both questions this function has: where the\n  // service's files live (a filed service is not at the root join), and which\n  // ids the landscape's resolver may bind to (the same `known` set every\n  // other landscape reader passes). The two-line resolution below is\n  // `locateServicePaths` (core/repo/service-target.ts) inlined — that helper\n  // enumerates internally, and calling it here would walk the tree twice.\n  const entries = await enumeratedServices(req.docsDir);\n  const entry = entries.find((s) => s.id === req.service);\n  const paths = entry === undefined ? unfiledServicePaths(req.docsDir, req.service) : servicePathsAt(entry.dir);\n  if (!existsSync(paths.spec)) {\n    // One sentence, from `vet/verify.ts`: these commands must not describe the\n    // same absence differently, and the fix — adopt first — is the same fix.\n    return { ok: false, code: \"unknown-target\", message: noLivingSpecMessage(paths.spec, req.service) };\n  }\n  const [specAxis, archAxis] = SPEC_AXES;\n  const specRead = await readAxis(paths[specAxis.key]);\n\n  // First vouch is a property of the REQUIRED axis: with neither digest\n  // stamped on spec.md there is no prior read to diff against, so the pack is\n  // the whole document, landscape claims first. A malformed or unreadable\n  // header deliberately does NOT count as first-vouch — it cannot prove the\n  // stamps absent, and claiming \"first vouch\" over a document that may carry\n  // one would order the read around a guess.\n  const firstVouch =\n    specRead.kind === \"read\" &&\n    !specRead.fm.malformed &&\n    stringField(specRead.fm, \"content_digest\") === undefined &&\n    stringField(specRead.fm, \"sources_digest\") === undefined;\n\n  const spec = await packAxis(req, { path: paths[specAxis.key], file: specAxis.file, read: specRead });\n  let archSpec: PackAxis | null = null;\n  if (existsSync(paths[archAxis.key])) {\n    const archRead = await readAxis(paths[archAxis.key]);\n    archSpec = await packAxis(req, { path: paths[archAxis.key], file: archAxis.file, read: archRead });\n  }\n  const knownIds = new Set<string>(entries.map((s) => s.id));\n  return {\n    ok: true,\n    report: {\n      service: req.service,\n      packMode: firstVouch ? \"first-vouch\" : \"re-vouch\",\n      // One existsSync, the same one run.ts pays before verification reads a\n      // byte: a predecessor's journal means the stamps just read may predate\n      // the write it was killed inside. The pack cannot recover (a write) —\n      // it warns, and the next journaled writer rolls the journal forward.\n      pendingCommit: existsSync(join(req.docsDir, COMMIT_INTENT)),\n      spec,\n      archSpec,\n      landscape: firstVouch ? await landscapeSlice(req.docsDir, req.service, knownIds) : null,\n    },\n  };\n}\n\n/** One spec-axis file's full share of the pack: body verdict, source verdict, stamp fields. */\nasync function packAxis(\n  req: PackRequest,\n  axis: { path: string; file: string; read: AxisRead },\n): Promise<PackAxis> {\n  const rel = repoPath(req.docsDir, axis.path);\n  // The source half rides on verifySpec — the vouch's own vetting, message\n  // for message. The pack never refuses over sources: \"your re-vouch will\n  // refuse, fix this first\" IS the worklist, so the refusal sentence travels\n  // as the `unavailable` reason instead of an exit code.\n  const vetted = await verifySpec({ service: req.service, repoDir: req.repoDir }, axis.path, axis.file);\n  // What the digest recompute would NOT hash. Empty on a refusal because\n  // nobody walked — never because there is nothing to say.\n  const skipped = vetted.ok ? vetted.skipped : [];\n\n  if (axis.read.kind === \"unreadable\") {\n    // Per-axis containment: an undecodable file suspends THIS axis with the\n    // decode error as both reasons — the sibling axis still gets its pack.\n    return {\n      path: rel,\n      file: axis.file,\n      body: { kind: \"full-read\", reason: axis.read.reason },\n      sources: { kind: \"unavailable\", reason: vetted.ok ? axis.read.reason : vetted.message },\n      skipped,\n    };\n  }\n  const { raw, fm } = axis.read;\n  const vouchedBy = stringField(fm, \"vouched_by\");\n  const lastVerified = stringField(fm, \"last_verified\");\n  const body = await bodyArm(req, { rel, raw, fm });\n  const sources = sourcesArm(vetted, fm);\n  const stampedScope = priorScope(fm, body.kind === \"unchanged\" ? rawBody(raw) : null);\n  return {\n    path: rel,\n    file: axis.file,\n    ...(vouchedBy === undefined ? {} : { vouchedBy }),\n    ...(lastVerified === undefined ? {} : { lastVerified }),\n    body,\n    sources,\n    skipped,\n    // A full read is exactly where the heading listing IS the reading plan —\n    // per axis, not per mode, so an arch.spec.md created after the last vouch\n    // gets its plan inside a re-vouch pack. `rawBody` first so no frontmatter\n    // line can ever masquerade as a section.\n    ...(body.kind === \"full-read\" ? { headings: sectionHeadings(rawBody(raw)).map((h) => h.text) } : {}),\n    // Only an UNCHANGED body can license naming what the last sampled vouch\n    // read: the recompute needs the bytes that vouch was taken over, and a\n    // digest-equal body is exactly those bytes. When the body has moved the\n    // scope is still reported — it still means the document was not read in\n    // full — with no covered list behind it. Reaching back to the vouched\n    // ancestor for the older body would be more information; it would also\n    // put a git walk behind a claim about what a person read, and the answer\n    // when git cannot speak would have to be this same one.\n    ...(stampedScope === null ? {} : { vouchScope: stampedScope }),\n    ...(req.sample === undefined || !vetted.ok\n      ? {}\n      : { sample: forwardSample({ service: req.service, raw, sourcesDigest: vetted.digest, n: req.sample }) }),\n  };\n}\n\n/** The body verdict: unchanged, a diff from the vouched ancestor, or an honest full read. */\nasync function bodyArm(\n  req: PackRequest,\n  doc: { rel: string; raw: string; fm: Frontmatter },\n): Promise<PackBody> {\n  // Deliberately NOT branched on the report-level first-vouch mode: the mode\n  // orders the read (landscape first), but each axis answers from its OWN\n  // stamps. In the one corpus where they disagree — spec.md hand-reverted to\n  // draft while arch.spec.md still carries a stamp — the stamped axis gets\n  // its real diff rather than a false \"nobody has read this yet\".\n  if (doc.fm.malformed) {\n    return {\n      kind: \"full-read\",\n      reason: \"the frontmatter cannot be read as YAML, so whatever content_digest it carries is unreachable — fix the header, then read the whole file\",\n    };\n  }\n  const stamped = stringField(doc.fm, \"content_digest\");\n  if (stamped === undefined) {\n    return {\n      kind: \"full-read\",\n      reason:\n        stringField(doc.fm, \"sources_digest\") === undefined\n          ? \"this file has never been vouched, so the whole of it is the read\"\n          : \"the last vouch predates content_digest, so no vouched body exists to diff from — read the whole file\",\n    };\n  }\n  // The cheap answer first, and without git: the digest recipe is byte-exact\n  // over the working-tree file, so equality here IS \"no byte of the body\n  // moved since the stamp\".\n  if (contentDigest(doc.raw) === stamped) return { kind: \"unchanged\" };\n\n  const ancestor = await findVouchedAncestor(req.docsDir, doc.rel, stamped);\n  if (ancestor.kind !== \"found\") {\n    return { kind: \"full-read\", reason: ancestor.kind === \"none\" ? ancestor.reason : ancestor.detail };\n  }\n  const diff = await bodyDiffText(req.docsDir, ancestor.commit, doc.rel);\n  // An ancestor without a printable diff could still licence a section delta,\n  // but a pack that says \"these sections changed, no diff shown\" invites\n  // skipping the rest on this run's partial word — degrade the whole arm to\n  // the full read instead; read more, never less.\n  if (diff.kind === \"failed\") return { kind: \"full-read\", reason: diff.reason };\n  return {\n    kind: \"diff\",\n    ancestorCommit: ancestor.commit,\n    diff: diff.diff,\n    sections: sectionDelta(rawBody(ancestor.text), rawBody(doc.raw)),\n  };\n}\n\n/** The source verdict, from the vouch's own vetting plus the stamped digests. */\nfunction sourcesArm(vetted: Awaited<ReturnType<typeof verifySpec>>, fm: Frontmatter): PackSources {\n  if (!vetted.ok) return { kind: \"unavailable\", reason: vetted.message };\n  const stamped = stringField(fm, \"sources_digest\");\n  if (stamped === undefined) return { kind: \"unvouched\" };\n  if (vetted.digest === stamped) return { kind: \"unchanged\" };\n  const index = decodeSourceIndex(stringField(fm, \"sources_files\"));\n  const delta = sourceDelta(index, vetted.index);\n  if (delta === null) return { kind: \"uncounted\", countThen: index.count ?? null, countNow: vetted.index.length };\n  return { kind: \"delta\", ...delta };\n}\n\n/**\n * The fleet map's claims about the service — a first vouch reads these before\n * the spec, because the landscape is the one document making claims ABOUT the\n * service that the person is not the author of. Absence and unparseability\n * both come back as `silent`: per landscapeEvidence's own rule they prove\n * nothing about who calls the service, and the pack says so rather than\n * printing an empty edge list that reads as \"nobody does\".\n */\nasync function landscapeSlice(docsDir: DocsDir, service: string, known: Set<string>): Promise<PackLandscape> {\n  const silent: PackLandscape = {\n    kind: \"silent\",\n    reason: `the fleet map says nothing about ${service} (absent or unparseable)`,\n  };\n  const path = landscapePath(docsDir);\n  if (!existsSync(path)) return silent;\n  let land: Awaited<ReturnType<typeof loadFile>>;\n  try {\n    land = await loadFile(path);\n  } catch {\n    // Unreadable is not \"no claims\" — but for a reading list both collapse to\n    // the same honest sentence: the map cannot brief this read.\n    return silent;\n  }\n  if (land.errors.length > 0) return silent;\n  const svcOf = serviceResolver(land.elements, known);\n  const evidence = landscapeEvidence({\n    id: service,\n    parses: true,\n    relationships: land.relationships,\n    elementIds: land.elements.map((e) => e.id),\n    svcOf,\n  });\n  return { kind: \"edges\", inbound: evidence.inbound, outbound: evidence.outbound };\n}\n"]}