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

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 { 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 { contentDigest, 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 { 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 { contentDigest, 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"]}

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

@@ -0,0 +1,271 @@
+/**
+ * The reading pack's two renderings — the human view in the proposal's order
+ * (per axis: the body diff, then the source worklist, then the sections
+ * already covered; first vouch: the fleet map's claims, then everything), and
+ * the `--json` envelope. `runPack` is the whole command surface of
+ * `--pack`: vouch.ts hands over here as soon as the flag combination is
+ * legal, so the write path's machinery — identity, prompt, lock, journal —
+ * never loads for a run that cannot write. Exit 0 covers every computed pack
+ * INCLUDING full-read fallbacks ("read everything" is an answer, not a
+ * failure); only refusals exit 1.
+ */
+import { emitJson, fail } from "../../../core/envelope/json.js";
+import { plural } from "../../policy/format.js";
+import { buildPack } from "./pack.js";
+export async function runPack(req) {
+    const outcome = await buildPack({
+        docsDir: req.docsDir,
+        service: req.service,
+        repoDir: req.repoDir,
+        ...(req.sample === undefined ? {} : { sample: req.sample }),
+    });
+    if (!outcome.ok)
+        return fail(req.json, outcome.code, outcome.message);
+    if (req.json) {
+        emitJson(packPayload(outcome.report));
+        return;
+    }
+    printPack(outcome.report);
+}
+/** The additive `--json` shape: `mode: "pack"` beside the write path's stamp payload. */
+function packPayload(report) {
+    return {
+        command: "vouch",
+        mode: "pack",
+        service: report.service,
+        packMode: report.packMode,
+        pendingCommit: report.pendingCommit,
+        spec: axisPayload(report.spec),
+        archSpec: report.archSpec === null ? null : axisPayload(report.archSpec),
+        ...(report.landscape === null ? {} : { landscape: report.landscape }),
+    };
+}
+/** One axis, stamp fields under their frontmatter spellings. */
+function axisPayload(axis) {
+    return {
+        path: axis.path,
+        file: axis.file,
+        ...(axis.vouchedBy === undefined ? {} : { vouched_by: axis.vouchedBy }),
+        ...(axis.lastVerified === undefined ? {} : { last_verified: axis.lastVerified }),
+        body: axis.body,
+        sources: axis.sources,
+        skipped: axis.skipped,
+        ...(axis.headings === undefined ? {} : { headings: axis.headings }),
+        ...(axis.vouchScope === undefined ? {} : { vouchScope: axis.vouchScope }),
+        ...(axis.sample === undefined ? {} : { sample: axis.sample }),
+    };
+}
+function printPack(report) {
+    // Before anything else: a pack computed over a half-committed docs repo may
+    // be describing bytes the next journaled writer will replace, and a person
+    // must know that before they spend a read on it.
+    if (report.pendingCommit) {
+        console.log("⚠ an interrupted docs-repo commit is pending — what is on disk (this pack included) may " +
+            "predate it. Any journaled docs-repo writer (`loam vouch`, `loam archive`) rolls it " +
+            "forward on its next run; re-run --pack after.\n");
+    }
+    if (report.packMode === "first-vouch") {
+        console.log(`${report.service} first-vouch reading pack — the whole document is the read\n`);
+        printLandscape(report);
+    }
+    else {
+        console.log(`${report.service} re-vouch reading pack\n`);
+    }
+    for (const axis of [report.spec, ...(report.archSpec === null ? [] : [report.archSpec])]) {
+        printAxis(axis);
+    }
+    console.log(`\nWhen the read is done, a person runs \`loam vouch --service ${report.service}\` in the service's own repo — the pack stamps nothing.`);
+}
+/** The fleet map's claims — first, because the spec's author did not write them. */
+function printLandscape(report) {
+    if (report.landscape === null)
+        return;
+    if (report.landscape.kind === "silent") {
+        console.log(`  ${report.landscape.reason}\n`);
+        return;
+    }
+    const { inbound, outbound } = report.landscape;
+    if (inbound.length === 0 && outbound.length === 0) {
+        console.log(`  the fleet map draws no edge touching ${report.service}\n`);
+        return;
+    }
+    console.log("  what the fleet map says:");
+    for (const edge of inbound)
+        console.log(`      ${edgeLine(edge.service, report.service, edge)}`);
+    for (const edge of outbound)
+        console.log(`      ${edgeLine(report.service, edge.service, edge)}`);
+    console.log("");
+}
+function edgeLine(from, to, edge) {
+    const label = edge.op !== null ? ` (${edge.op})` : edge.title !== null ? ` — ${edge.title}` : "";
+    return `${from} -> ${to}${label}`;
+}
+/** One axis in the proposal's order: (a) body, (b) source worklist, (c) already covered. */
+function printAxis(axis) {
+    console.log(`${axis.path}\n`);
+    printBody(axis);
+    printSources(axis);
+    printSkipped(axis);
+    printSampledStamp(axis);
+    printCovered(axis);
+    // Under `--sample` the sampled list REPLACES the full heading listing —
+    // printing both would make the list a person must not skip look like the
+    // one they may. The diff above is never filtered: a sample narrows what the
+    // stamp CLAIMS, never what a reader is shown.
+    if (axis.sample !== undefined) {
+        printSample(axis.sample);
+    }
+    else if (axis.headings !== undefined) {
+        console.log(`  sections to read (${axis.headings.length}):`);
+        for (const heading of axis.headings)
+            console.log(`      ${heading}`);
+        console.log("");
+    }
+}
+/**
+ * The forward sample: exactly what the `--sample <n>` vouch after this pack
+ * will stand behind. The consequences are named in one line rather than
+ * restated at length — `sample/print.ts` says them in full at the prompt,
+ * which is the screen where somebody is about to commit to them.
+ */
+function printSample(sample) {
+    if (sample.covers) {
+        console.log(`  sampled read: the sample reaches all ${sample.of} section(s) — the vouch after it is an ordinary full one.\n`);
+        return;
+    }
+    console.log(`  sampled read — ${sample.headings.length} of ${sample.of} section(s), seed=${sample.seed}:`);
+    console.log("      the preamble above the first heading — always read, never part of the count");
+    for (const heading of sample.headings)
+        console.log(`      ${heading}`);
+    console.log(`\n  Reading only these is what --sample means, and the stamp will say so: \`vouch_scope: sampled ` +
+        `${sample.headings.length}/${sample.of}\`, then \`sources.sampled-vouch\` until somebody reads the whole document.\n`);
+}
+/**
+ * The last vouch's own scope, printed BEFORE the covered list it disqualifies
+ * — which sections that person actually read (`sections.ts`'s `priorScope`
+ * recomputes them from the stamped seed), and which have now survived a vouch
+ * without anybody looking. Where the read set cannot be recomputed, no
+ * covered set is named at all: an unreproducible sample licenses nothing.
+ */
+function printSampledStamp(axis) {
+    const scope = axis.vouchScope;
+    if (scope === undefined)
+        return;
+    const whose = `${axis.vouchedBy === undefined ? "" : ` by ${axis.vouchedBy}`}${axis.lastVerified === undefined ? "" : ` on ${axis.lastVerified}`}`;
+    console.log(scope.scope === null
+        ? `  ⚠ the last vouch${whose} carries a vouch_scope this loam cannot read (\`${scope.stamped}\`) — graded as ` +
+            "SAMPLED, because an unreadable scope must never be taken for a full read."
+        : `  ⚠ the last vouch${whose} was SAMPLED: ${scope.scope.sections} of ${scope.scope.of} section(s), ` +
+            `seed=${scope.scope.seed}. "Unchanged since then" does not mean anybody read it.`);
+    if (scope.read === null) {
+        console.log("      which sections it read cannot be recomputed (the body moved, or the scope does not decode), so nothing here is covered.\n");
+        return;
+    }
+    console.log(`      read at that vouch (${scope.read.length}): ${scope.read.join(" · ")}`);
+    if (scope.unread !== null && scope.unread.length > 0) {
+        console.log(`      NEVER read by anyone (${scope.unread.length}) — this is the read:`);
+        for (const heading of scope.unread)
+            console.log(`          ${heading}`);
+    }
+    console.log("");
+}
+function printBody(axis) {
+    const since = axis.lastVerified === undefined ? "the stamp" : axis.lastVerified;
+    switch (axis.body.kind) {
+        case "unchanged":
+            // The qualification is the whole point after a sampled vouch: the text
+            // did not move, and most of it was still never read. Saying "nothing to
+            // re-read" over that would be this feature's worst failure — a partial
+            // read reported as a finished one — so the sentence stops at what it
+            // can actually claim and hands off to the scope block below.
+            console.log(axis.vouchScope === undefined
+                ? `  body unchanged since ${since} — nothing of the document itself to re-read\n`
+                : `  body unchanged since ${since} — but that vouch was sampled, so "unchanged" is not "read"\n`);
+            return;
+        case "full-read":
+            console.log(`  full read: ${axis.body.reason}\n`);
+            return;
+        case "diff": {
+            // "The file's diff", not "the body's": a hand edit to the header after
+            // the vouch rides along in git's hunks, and promising body-only would
+            // make truthful noise read as a bug.
+            console.log(`  body changed since ${since} — the file's diff from its last vouched state (${axis.body.ancestorCommit.slice(0, 12)}):\n`);
+            console.log(axis.body.diff.trimEnd());
+            const { changed, added, removed } = axis.body.sections;
+            const summary = [
+                ...(changed.length > 0 ? [`changed: ${changed.join(", ")}`] : []),
+                ...(added.length > 0 ? [`added: ${added.join(", ")}`] : []),
+                ...(removed.length > 0 ? [`removed: ${removed.join(", ")}`] : []),
+            ];
+            if (summary.length > 0)
+                console.log(`\n  sections ${summary.join("; ")}`);
+            console.log("");
+            return;
+        }
+    }
+}
+function printSources(axis) {
+    switch (axis.sources.kind) {
+        case "unchanged":
+            console.log("  sources unchanged since the stamp\n");
+            return;
+        case "unvouched":
+            console.log("  sources carry no sources_digest yet — the vouch will stamp one\n");
+            return;
+        case "unavailable":
+            console.log(`  sources — the re-vouch will refuse until this is fixed:\n      ${axis.sources.reason}\n`);
+            return;
+        case "uncounted":
+            console.log(`  sources changed — ${axis.sources.countThen === null ? "an unknown number of" : axis.sources.countThen} file(s) at the stamp, ` +
+                `${axis.sources.countNow} now, and the stamp cannot name which moved: re-read the sources\n`);
+            return;
+        case "delta": {
+            const { added, changed, removed } = axis.sources;
+            const moved = added.length + changed.length + removed.length;
+            // movedSources' one-column annotated layout, so a reader who knows the
+            // stale finding's shape reads this without learning a second one.
+            console.log(`  sources — ${moved} path(s) moved since the stamp:`);
+            for (const path of added)
+                console.log(`      added    ${path}`);
+            for (const path of changed)
+                console.log(`      changed  ${path}`);
+            for (const path of removed)
+                console.log(`      removed  ${path}`);
+            console.log("");
+            return;
+        }
+    }
+}
+/**
+ * The hole in the promise, said BEFORE the stamp rather than only on
+ * vouch.ts's post-stamp screen: paths under the listed sources the digest
+ * will not hash. Same sentence as that screen, so the pre-vouch and
+ * post-vouch descriptions of one hole cannot drift apart.
+ */
+function printSkipped(axis) {
+    if (axis.skipped.length === 0)
+        return;
+    console.log(`  ⚠ ${plural(axis.skipped.length, "path")} under those sources went unhashed — the vouch's digest says nothing about what is behind them:`);
+    for (const skip of axis.skipped)
+        console.log(`      ${skip.path} — ${skip.reason}`);
+    console.log("");
+}
+/** (c): what the previous vouch already covers, so the read can stop where it should. */
+function printCovered(axis) {
+    if (axis.body.kind !== "diff" || axis.body.sections.unchanged.length === 0)
+        return;
+    const by = axis.vouchedBy === undefined ? "" : ` by ${axis.vouchedBy}`;
+    const on = axis.lastVerified === undefined ? "" : ` on ${axis.lastVerified}`;
+    // The licence to skip rests entirely on somebody having read the section
+    // before. A sampled vouch did not read most of them, so after one this list
+    // is only "text that did not move" — it is still worth printing (a reader
+    // wants to know what is stable), but it must not be printed under a heading
+    // that says a person covered it.
+    console.log(axis.vouchScope === undefined
+        ? `  unchanged — previously vouched${by}${on}:`
+        : `  unchanged since the sampled vouch${by}${on} — text that did not move, NOT a covered list:`);
+    for (const heading of axis.body.sections.unchanged)
+        console.log(`      ${heading}`);
+    console.log("");
+}
+//# sourceMappingURL=print.js.map