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

package/dist/commands/vouch/report.js

@@ -0,0 +1,101 @@
+/**
+ * What a successful vouch prints: the machine envelope, and the screen the
+ * person who just vouched is looking at.
+ *
+ * Split out of `vouch.ts` when `--sample` arrived and that file reached its
+ * line limit, on the phase seam the command already had: everything above it
+ * decides whether to write, everything here describes what was written. The
+ * two renderings stay in one module because they report the SAME stamp, and
+ * the one failure this file exists to prevent is a text screen and a payload
+ * that disagree about what a document now says.
+ */
+import { emitJson, repoPath } from "../../core/envelope/json.js";
+import { plural, sayRecovered } from "../policy/format.js";
+import { scopeJson } from "./sample/print.js";
+/**
+ * The plan entry for one stamped file, joined by FILENAME — never by position.
+ * The two axes are stamped by two separate calls, and pairing them by index
+ * would hang one file's headings off the other file's scope.
+ */
+function plannedAxis(report, spec) {
+    return report.sample?.axes.find((axis) => axis.file === spec.file);
+}
+export function emitStampJson(report) {
+    const { spec, archSpec: arch } = report.outcome.stamped;
+    emitJson({
+        command: "vouch",
+        service: report.service,
+        path: repoPath(report.docsDir, spec.path),
+        ...(report.outcome.recovered === null ? {} : { recovered: report.outcome.recovered }),
+        status: report.outcome.status,
+        last_verified: report.outcome.lastVerified,
+        vouched_by: report.outcome.vouchedBy,
+        sources: spec.sources,
+        sources_digest: spec.digest,
+        content_digest: spec.contentDigest,
+        files: spec.files,
+        skipped: spec.skipped,
+        // Additive, and beside `status` rather than inside it: `verified` is a
+        // frozen string and a sampled read is a qualification of it, not a fourth
+        // status. Null — never omitted — for a file read in full, so a consumer
+        // can tell "this loam says it was full" from "this loam has never heard
+        // of scopes".
+        vouchScope: scopeJson(spec.vouchScope, plannedAxis(report, spec)),
+        // The architecture axis, same keys: null when the service has no
+        // arch.spec.md, so a consumer can tell "none present" from an older
+        // loam that never reported the axis. status/last_verified are not
+        // repeated — the vouch is one act, and they hold for every file in it.
+        archSpec: arch === null
+            ? null
+            : {
+                path: repoPath(report.docsDir, arch.path),
+                sources: arch.sources,
+                sources_digest: arch.digest,
+                content_digest: arch.contentDigest,
+                files: arch.files,
+                skipped: arch.skipped,
+                // Per file, because the sample is per file: one `--sample 3` run
+                // can stamp a sampled spec.md beside a fully-read arch.spec.md,
+                // and one scope for the pair would be false about one of them.
+                vouchScope: scopeJson(arch.vouchScope, plannedAxis(report, arch)),
+            },
+    });
+}
+export function printStamp(report) {
+    const { outcome, service } = report;
+    const { spec, archSpec: arch } = outcome.stamped;
+    // spec.md first, arch.spec.md behind it when present — the order the
+    // person who vouched reads them in, and the order the axes are declared.
+    if (outcome.recovered !== null)
+        console.log(`${sayRecovered(outcome.recovered)}\n`);
+    for (const [i, s] of [spec, ...(arch === null ? [] : [arch])].entries()) {
+        console.log(`${i > 0 ? "\n" : ""}${service} vouched — ${repoPath(report.docsDir, s.path)}\n`);
+        console.log(`  status          ${outcome.status}`);
+        console.log(`  last_verified   ${outcome.lastVerified}`);
+        console.log(`  vouched_by      ${outcome.vouchedBy}`);
+        console.log(`  sources_digest  ${s.digest}  (${plural(s.files, "file")} from ${plural(s.sources.length, "source")})`);
+        console.log(`  content_digest  ${s.contentDigest}`);
+        // On the same screen as the digests, in the same column, because this is
+        // the field that says the promise beside it is partial. A reader who scans
+        // the stamp and stops must not be able to miss it.
+        if (s.vouchScope !== null) {
+            console.log(`  vouch_scope     sampled ${s.vouchScope.sections}/${s.vouchScope.of} seed=${s.vouchScope.seed}  ` +
+                `(${plural(s.vouchScope.of - s.vouchScope.sections, "section")} unread)`);
+        }
+        // Said at the moment of stamping, not only later by `loam validate`:
+        // this is the one screen the person who vouched is actually looking at,
+        // and what it lists is the part of the tree their promise does not cover.
+        if (s.skipped.length > 0) {
+            console.log(`\n  ⚠ ${plural(s.skipped.length, "path")} under those sources went unhashed:`);
+            for (const skip of s.skipped)
+                console.log(`      ${skip.path} — ${skip.reason}`);
+        }
+    }
+    const sampled = [spec, arch].some((s) => s !== null && s.vouchScope !== null);
+    console.log(`\n\`loam validate\` will now say when that code moves out from under the spec — or when the spec moves under its own stamp.`);
+    if (sampled) {
+        console.log(`It will also report \`sources.sampled-vouch\` for '${service}' until a person vouches for the whole document ` +
+            `(\`loam vouch --service ${service}\`, no --sample), which clears the scope.`);
+    }
+}
+//# sourceMappingURL=report.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/vouch/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a successful vouch prints: the machine envelope, and the screen the\n * person who just vouched is looking at.\n *\n * Split out of `vouch.ts` when `--sample` arrived and that file reached its\n * line limit, on the phase seam the command already had: everything above it\n * decides whether to write, everything here describes what was written. The\n * two renderings stay in one module because they report the SAME stamp, and\n * the one failure this file exists to prevent is a text screen and a payload\n * that disagree about what a document now says.\n */\nimport { emitJson, repoPath } from \"../../core/envelope/json.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { plural, sayRecovered } from \"../policy/format.js\";\nimport type { StampedSpec, VouchOutcome } from \"./contract.js\";\nimport type { PlannedAxis, SamplePlan } from \"./sample/plan.js\";\nimport { scopeJson } from \"./sample/print.js\";\n\nexport interface StampReport {\n  service: string;\n  docsDir: DocsDir;\n  /** The successful arm — the only one that has a stamp to describe. */\n  outcome: Extract<VouchOutcome, { ok: true }>;\n  /** The reading list this run was answered against, when it was a sampled one. */\n  sample?: SamplePlan;\n}\n\n/**\n * The plan entry for one stamped file, joined by FILENAME — never by position.\n * The two axes are stamped by two separate calls, and pairing them by index\n * would hang one file's headings off the other file's scope.\n */\nfunction plannedAxis(report: StampReport, spec: StampedSpec): PlannedAxis | undefined {\n  return report.sample?.axes.find((axis) => axis.file === spec.file);\n}\n\nexport function emitStampJson(report: StampReport): void {\n  const { spec, archSpec: arch } = report.outcome.stamped;\n  emitJson({\n    command: \"vouch\",\n    service: report.service,\n    path: repoPath(report.docsDir, spec.path),\n    ...(report.outcome.recovered === null ? {} : { recovered: report.outcome.recovered }),\n    status: report.outcome.status,\n    last_verified: report.outcome.lastVerified,\n    vouched_by: report.outcome.vouchedBy,\n    sources: spec.sources,\n    sources_digest: spec.digest,\n    content_digest: spec.contentDigest,\n    files: spec.files,\n    skipped: spec.skipped,\n    // Additive, and beside `status` rather than inside it: `verified` is a\n    // frozen string and a sampled read is a qualification of it, not a fourth\n    // status. Null — never omitted — for a file read in full, so a consumer\n    // can tell \"this loam says it was full\" from \"this loam has never heard\n    // of scopes\".\n    vouchScope: scopeJson(spec.vouchScope, plannedAxis(report, spec)),\n    // The architecture axis, same keys: null when the service has no\n    // arch.spec.md, so a consumer can tell \"none present\" from an older\n    // loam that never reported the axis. status/last_verified are not\n    // repeated — the vouch is one act, and they hold for every file in it.\n    archSpec:\n      arch === null\n        ? null\n        : {\n            path: repoPath(report.docsDir, arch.path),\n            sources: arch.sources,\n            sources_digest: arch.digest,\n            content_digest: arch.contentDigest,\n            files: arch.files,\n            skipped: arch.skipped,\n            // Per file, because the sample is per file: one `--sample 3` run\n            // can stamp a sampled spec.md beside a fully-read arch.spec.md,\n            // and one scope for the pair would be false about one of them.\n            vouchScope: scopeJson(arch.vouchScope, plannedAxis(report, arch)),\n          },\n  });\n}\n\nexport function printStamp(report: StampReport): void {\n  const { outcome, service } = report;\n  const { spec, archSpec: arch } = outcome.stamped;\n  // spec.md first, arch.spec.md behind it when present — the order the\n  // person who vouched reads them in, and the order the axes are declared.\n  if (outcome.recovered !== null) console.log(`${sayRecovered(outcome.recovered)}\\n`);\n  for (const [i, s] of [spec, ...(arch === null ? [] : [arch])].entries()) {\n    console.log(`${i > 0 ? \"\\n\" : \"\"}${service} vouched — ${repoPath(report.docsDir, s.path)}\\n`);\n    console.log(`  status          ${outcome.status}`);\n    console.log(`  last_verified   ${outcome.lastVerified}`);\n    console.log(`  vouched_by      ${outcome.vouchedBy}`);\n    console.log(\n      `  sources_digest  ${s.digest}  (${plural(s.files, \"file\")} from ${plural(s.sources.length, \"source\")})`,\n    );\n    console.log(`  content_digest  ${s.contentDigest}`);\n    // On the same screen as the digests, in the same column, because this is\n    // the field that says the promise beside it is partial. A reader who scans\n    // the stamp and stops must not be able to miss it.\n    if (s.vouchScope !== null) {\n      console.log(\n        `  vouch_scope     sampled ${s.vouchScope.sections}/${s.vouchScope.of} seed=${s.vouchScope.seed}  ` +\n          `(${plural(s.vouchScope.of - s.vouchScope.sections, \"section\")} unread)`,\n      );\n    }\n    // Said at the moment of stamping, not only later by `loam validate`:\n    // this is the one screen the person who vouched is actually looking at,\n    // and what it lists is the part of the tree their promise does not cover.\n    if (s.skipped.length > 0) {\n      console.log(`\\n  ⚠ ${plural(s.skipped.length, \"path\")} under those sources went unhashed:`);\n      for (const skip of s.skipped) console.log(`      ${skip.path} — ${skip.reason}`);\n    }\n  }\n  const sampled = [spec, arch].some((s) => s !== null && s.vouchScope !== null);\n  console.log(\n    `\\n\\`loam validate\\` will now say when that code moves out from under the spec — or when the spec moves under its own stamp.`,\n  );\n  if (sampled) {\n    console.log(\n      `It will also report \\`sources.sampled-vouch\\` for '${service}' until a person vouches for the whole document ` +\n        `(\\`loam vouch --service ${service}\\`, no --sample), which clears the scope.`,\n    );\n  }\n}\n"]}

package/dist/commands/vouch/run.js

@@ -0,0 +1,230 @@
+/**
+ * The stamp itself: verify every spec, then write them all or none.
+ *
+ * Separate from the command because this half has nothing to say to a terminal.
+ * It refuses on any spec it cannot verify and stamps none of them — a vouch is
+ * a person's claim that the documents match the code, and a partial one would
+ * put that claim on files nobody checked.
+ *
+ * What lands in each file: `status`, `last_verified`, `vouched_by`,
+ * `sources_digest`, the `sources_files` index, `content_digest` — and
+ * `vouch_scope` when the person read a sample rather than the document — with
+ * every byte below the frontmatter left identical. Nothing is written unless
+ * all of it can be stamped truthfully for EVERY file: a half-stamp (verified
+ * with no digest behind it, or one file stamped and its sibling not) is
+ * exactly the claim this command exists to stop being possible, so every
+ * present file is verified before any is written, and the writing itself is
+ * staged and swapped in like archive's merge, so a failure between the pair's
+ * two writes rolls the first back instead of leaving it. The two digests are
+ * the two halves of one promise — `sources_digest` pins the code that was
+ * read, `content_digest` pins the words it was read against — so
+ * `loam validate` can see either side move. (This paragraph came from a
+ * docblock stranded at the foot of `vouch.ts` when the stamp moved down here.)
+ */
+import { contentDigest, withFrontmatterFields } from "../../core/document/frontmatter.js";
+import { encodeVouchScope } from "../../core/provenance/sample/scope.js";
+import { encodeSourceIndex } from "../../core/provenance/stamp.js";
+import { rollbackStaged, stageWrites } from "../../core/staging/commit.js";
+import {} from "../../core/staging/interrupted.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow, recoverIfJournaled } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import {} from "../../core/staging/writes.js";
+import {} from "./contract.js";
+import { axisScope, sampleDrift } from "./sample/plan.js";
+import { verifyAxes } from "./vet/verify.js";
+export async function vouch(req) {
+    // A predecessor's journal is rolled forward BEFORE verification reads a
+    // byte. Recovery under the commit lock alone was tried first and kept as
+    // the backstop, but it changes files verification has already read, so the
+    // run's own raced check then refused a sound stamp and the fix doctor
+    // prints took two runs instead of one. Cheap when there is nothing to do:
+    // one existsSync.
+    const early = await recoverIfJournaled(req.docsDir);
+    if (!early.ok)
+        return early;
+    // Verify first, stamp after: spec.md is required (a missing one is
+    // `unknown-target`), arch.spec.md rides when it exists, and one file that
+    // cannot be verified refuses the run before anything is written. The walk is
+    // `verifyAxes` (vet/verify.ts), shared with the reading list, and it hands
+    // the two files back by name — vet/verify.ts says why not a loop.
+    const axes = await verifyAxes(req);
+    if (!axes.ok)
+        return axes;
+    const { spec: specVerified, arch: archVerified } = axes;
+    const verified = [specVerified, ...(archVerified === null ? [] : [archVerified])];
+    // The READING window's race, which the commit window's byte compare cannot
+    // see. Under `--sample` a person spends minutes on the list before they
+    // answer, and the sample they were shown was chosen from digests taken
+    // before that. If either digest moved — or a second axis file appeared —
+    // the sections they read are not the sections this stamp would claim, and
+    // `vouch_scope` would record a read that did not happen. Nothing is written.
+    const raced = req.sample === undefined ? null : sampleDrift(req.sample, verified, req.service);
+    if (raced !== null)
+        return { ok: false, code: "vouch-raced", message: raced };
+    const specPlan = planStamp(specVerified, req);
+    const archPlan = archVerified === null ? null : planStamp(archVerified, req);
+    const writes = [specPlan.write, ...(archPlan === null ? [] : [archPlan.write])];
+    // The slow half — reading specs, hashing sources, composing stamps — ran
+    // UNLOCKED above, so vouches for independent services do not serialise
+    // behind one repo-wide mutex. Only the commit window takes the docs lock:
+    // the same one archive, rebase and verify --record hold, in the waiting
+    // form, because two vouches for different services are both supposed to
+    // land. This is the lock the roadmap called missing: without it a vouch
+    // could stage against bytes an archive was mid-swap over, and the byte
+    // compare below would refuse a perfectly sound stamp — or worse, an
+    // interrupted commit's journal would be silently written over.
+    //
+    // A journal under the lock means the last writer never finished; the window
+    // recovers or refuses before reading the pre-images this commit will compare.
+    const opened = await openCommitWindow(req.docsDir, LOCK_WAIT_MS);
+    if (!opened.ok)
+        return opened;
+    try {
+        return await commitStamp(req, { writes, specPlan, archPlan, verified }, opened.recovered ?? early.recovered);
+    }
+    finally {
+        await opened.release();
+    }
+}
+/**
+ * The commit window: stage, compare against what verification read, journal,
+ * swap. Split from `vouch` so the lock's extent is visible in the code shape —
+ * everything in here holds it, nothing above does.
+ */
+async function commitStamp(req, plan, recovered) {
+    const { writes, specPlan, archPlan, verified } = plan;
+    const staged = await stageWrites(writes);
+    // One shared docs repo, ten service repos, and nothing stopping two of them
+    // from vouching at once. Between reading a spec and swapping the stamp in
+    // there is a window in which somebody else's vouch (or an editor, or a merge)
+    // can land in the same file — and because the new bytes were computed from
+    // the OLD ones, swapping them in would take that stamp back out without a
+    // word. `stageWrites` has already read what is on disk right now, so the
+    // check is a comparison, not another read: if the file is not what was
+    // verified, this run is describing a document that no longer exists.
+    // Bytes, not text: `stageWrites` reads the file as a Buffer (a string
+    // comparison against it is never equal, which made every vouch report
+    // `vouch-raced` and stamp nothing). A file that is GONE is still a race —
+    // `null` is not "empty", it is "the document this run described is not
+    // there any more".
+    // Joined by path, not by index: pairing the two lists positionally assumed
+    // `stageWrites` returns one entry per planned write in order — true today,
+    // promised nowhere, and a compare-and-set that silently compares the wrong
+    // pair would stamp over somebody else's vouch. A staged write no verified
+    // file claims has nothing to be compared against, so it counts as raced;
+    // fail-closed is the only safe direction here.
+    const verifiedByPath = new Map(verified.map((v) => [v.path, v]));
+    const raced = staged.filter((s) => {
+        const v = verifiedByPath.get(s.write.path);
+        return v === undefined || s.before === null || !s.before.equals(Buffer.from(v.raw, "utf8"));
+    });
+    if (raced.length > 0) {
+        // Nothing has swapped yet, so the rollback is only the temp files going
+        // away — the other writer's stamp is left exactly as it landed.
+        await rollbackStaged(staged);
+        return {
+            ok: false,
+            code: "vouch-raced",
+            message: `${req.service}: ${raced.map((s) => s.write.path).join(", ")} changed while this vouch was running — ` +
+                `another vouch or an edit landed first. Nothing was stamped: re-read the document and re-run.`,
+        };
+    }
+    // The journaled commit: intent fsynced before the first rename, so a kill
+    // between the pair's two swaps is recoverable instead of invisible — the
+    // exact half-stamped state the all-or-nothing verification exists to rule
+    // out used to be reachable through that one window. The codes are archive's,
+    // reused rather than minted: rolled back → nothing changed, re-running can
+    // work; incomplete → the files listed need a human.
+    const committed = await commitStaged({
+        root: req.docsDir,
+        command: "vouch",
+        // Runnable where vouch runs — the SERVICE repo, with --yes because the
+        // journal's reader may be unattended. Any other journaled docs-repo
+        // writer recovers this journal on its next run too.
+        rerun: `loam vouch --service ${req.service} --yes`,
+        target: req.service,
+    }, staged, "stamped");
+    if (!committed.ok) {
+        return committed.raced
+            ? {
+                ok: false,
+                code: "vouch-raced",
+                message: `${req.service}: a document changed while this vouch was committing — ` +
+                    `another writer landed first. Nothing was stamped: re-read and re-run.`,
+            }
+            : { ok: false, code: committed.code, message: committed.message };
+    }
+    return {
+        ok: true,
+        status: "verified",
+        lastVerified: req.today,
+        vouchedBy: req.vouchedBy,
+        recovered,
+        stamped: { spec: specPlan.stamped, archSpec: archPlan === null ? null : archPlan.stamped },
+    };
+}
+/**
+ * One verified file's share of the commit: the bytes to write, and the record
+ * of what was stamped into them. Kept beside each other because they are the
+ * same computation — the report must describe the file that was actually
+ * written, not a second guess at it.
+ */
+export function planStamp(v, req) {
+    // Two passes on purpose: `content_digest` hashes the body BELOW the
+    // frontmatter, and withFrontmatterFields promises that body byte-identical —
+    // so hashing after the first stamp and writing the hash in a second one
+    // yields a digest that is true of the file exactly as written. A re-vouch
+    // takes the same road and refreshes every field, this one included.
+    //
+    // The scope this file's stamp will carry — null both when the run is an
+    // ordinary vouch and when a sampled run's `--sample <n>` covered the whole
+    // file. Joined to the plan by FILENAME rather than taken positionally: the
+    // two axes are stamped by two separate calls, and a scope written onto the
+    // wrong file would claim a person read four sections of a document they
+    // never opened.
+    const planned = req.sample?.axes.find((axis) => axis.file === v.file);
+    // A verified file with no planned axis is unreachable — `sampleDrift`
+    // refuses that run before this line — and null is the safe direction if it
+    // ever were: a full stamp that CLEARS any prior scope, never one claiming a
+    // sample nobody was shown.
+    const scope = planned === undefined ? null : axisScope(planned);
+    const restamped = withFrontmatterFields(v.raw, {
+        status: "verified",
+        last_verified: req.today,
+        // WHO, beside when. Without it `status: verified` recorded that the word
+        // had been written and nothing about who wrote it, so a vouch and an
+        // agent's own draft left the same trace in the document — the one
+        // distinction this command exists to make.
+        vouched_by: req.vouchedBy,
+        sources_digest: v.digest,
+        // Beside the digest, what it was taken over. `sources_digest` alone can
+        // only ever say THAT the code moved; the next `loam validate` reads this
+        // back to say which files did.
+        sources_files: encodeSourceIndex(v.index),
+        // Beside `vouched_by`, never inside `status`: the rung string `vouched`
+        // and the status `verified` are a published contract, and a sampled read
+        // is not a fourth status — it is a qualification of this one.
+        ...(scope === null ? {} : { vouch_scope: encodeVouchScope(scope) }),
+    }, 
+    // A full vouch CLEARS any scope a previous sampled one left, rather than
+    // stranding a claim that would keep a fully-read document reading as
+    // partial forever. Removing a key that was never there is a no-op, so
+    // this rides on every run that is not itself sampling.
+    scope === null ? ["vouch_scope"] : []);
+    const bodyDigest = contentDigest(restamped);
+    return {
+        write: { path: v.path, content: withFrontmatterFields(restamped, { content_digest: bodyDigest }) },
+        stamped: {
+            path: v.path,
+            file: v.file,
+            digest: v.digest,
+            contentDigest: bodyDigest,
+            sources: v.sources,
+            files: v.index.length,
+            skipped: v.skipped,
+            vouchScope: scope,
+        },
+    };
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/vouch/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAuB,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC9F,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAA0D,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAEhE,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAiB;IAC3C,wEAAwE;IACxE,yEAAyE;IACzE,2EAA2E;IAC3E,sEAAsE;IACtE,0EAA0E;IAC1E,kBAAkB;IAClB,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IAC5B,mEAAmE;IACnE,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,kEAAkE;IAClE,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IACxD,MAAM,QAAQ,GAAmB,CAAC,YAAY,EAAE,GAAG,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAElG,2EAA2E;IAC3E,wEAAwE;IACxE,uEAAuE;IACvE,yEAAyE;IACzE,0EAA0E;IAC1E,6EAA6E;IAC7E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC/F,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAE9E,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC7E,MAAM,MAAM,GAAmB,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEhG,yEAAyE;IACzE,uEAAuE;IACvE,0EAA0E;IAC1E,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,uEAAuE;IACvE,oEAAoE;IACpE,+DAA+D;IAC/D,EAAE;IACF,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,WAAW,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/G,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CACxB,GAAiB,EACjB,IAKC,EACD,SAAgC;IAEhC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzC,4EAA4E;IAC5E,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,uEAAuE;IACvE,qEAAqE;IACrE,sEAAsE;IACtE,sEAAsE;IACtE,0EAA0E;IAC1E,uEAAuE;IACvE,mBAAmB;IACnB,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,+CAA+C;IAC/C,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAChC,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,wEAAwE;QACxE,gEAAgE;QAChE,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,aAAa;YACnB,OAAO,EACL,GAAG,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,0CAA0C;gBACtG,8FAA8F;SACjG,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,SAAS,GAAG,MAAM,YAAY,CAClC;QACE,IAAI,EAAE,GAAG,CAAC,OAAO;QACjB,OAAO,EAAE,OAAO;QAChB,uEAAuE;QACvE,oEAAoE;QACpE,oDAAoD;QACpD,KAAK,EAAE,wBAAwB,GAAG,CAAC,OAAO,QAAQ;QAClD,MAAM,EAAE,GAAG,CAAC,OAAO;KACpB,EACD,MAAM,EACN,SAAS,CACV,CAAC;IACF,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC,KAAK;YACpB,CAAC,CAAC;gBACE,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,aAAa;gBACnB,OAAO,EACL,GAAG,GAAG,CAAC,OAAO,yDAAyD;oBACvE,uEAAuE;aAC1E;YACH,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;IACtE,CAAC;IACD,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,UAAU;QAClB,YAAY,EAAE,GAAG,CAAC,KAAK;QACvB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS;QACT,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE;KAC3F,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,CAAe,EAAE,GAAiB;IAC1D,oEAAoE;IACpE,6EAA6E;IAC7E,wEAAwE;IACxE,0EAA0E;IAC1E,oEAAoE;IACpE,EAAE;IACF,wEAAwE;IACxE,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,gBAAgB;IAChB,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;IACtE,sEAAsE;IACtE,2EAA2E;IAC3E,4EAA4E;IAC5E,2BAA2B;IAC3B,MAAM,KAAK,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,qBAAqB,CACrC,CAAC,CAAC,GAAG,EACL;QACE,MAAM,EAAE,UAAU;QAClB,aAAa,EAAE,GAAG,CAAC,KAAK;QACxB,yEAAyE;QACzE,qEAAqE;QACrE,kEAAkE;QAClE,2CAA2C;QAC3C,UAAU,EAAE,GAAG,CAAC,SAAS;QACzB,cAAc,EAAE,CAAC,CAAC,MAAM;QACxB,wEAAwE;QACxE,yEAAyE;QACzE,+BAA+B;QAC/B,aAAa,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC;QACzC,wEAAwE;QACxE,yEAAyE;QACzE,8DAA8D;QAC9D,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;KACpE;IACD,yEAAyE;IACzE,qEAAqE;IACrE,sEAAsE;IACtE,uDAAuD;IACvD,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CACtC,CAAC;IACF,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO;QACL,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,qBAAqB,CAAC,SAAS,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,EAAE;QAClG,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,aAAa,EAAE,UAAU;YACzB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM;YACrB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,UAAU,EAAE,KAAK;SAClB;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The stamp itself: verify every spec, then write them all or none.\n *\n * Separate from the command because this half has nothing to say to a terminal.\n * It refuses on any spec it cannot verify and stamps none of them — a vouch is\n * a person's claim that the documents match the code, and a partial one would\n * put that claim on files nobody checked.\n *\n * What lands in each file: `status`, `last_verified`, `vouched_by`,\n * `sources_digest`, the `sources_files` index, `content_digest` — and\n * `vouch_scope` when the person read a sample rather than the document — with\n * every byte below the frontmatter left identical. Nothing is written unless\n * all of it can be stamped truthfully for EVERY file: a half-stamp (verified\n * with no digest behind it, or one file stamped and its sibling not) is\n * exactly the claim this command exists to stop being possible, so every\n * present file is verified before any is written, and the writing itself is\n * staged and swapped in like archive's merge, so a failure between the pair's\n * two writes rolls the first back instead of leaving it. The two digests are\n * the two halves of one promise — `sources_digest` pins the code that was\n * read, `content_digest` pins the words it was read against — so\n * `loam validate` can see either side move. (This paragraph came from a\n * docblock stranded at the foot of `vouch.ts` when the stamp moved down here.)\n */\nimport { contentDigest, withFrontmatterFields } from \"../../core/document/frontmatter.js\";\nimport { encodeVouchScope } from \"../../core/provenance/sample/scope.js\";\nimport { encodeSourceIndex } from \"../../core/provenance/stamp.js\";\nimport { rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow, recoverIfJournaled } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type StampedSpec, type VouchOutcome, type VouchRequest } from \"./contract.js\";\nimport { axisScope, sampleDrift } from \"./sample/plan.js\";\nimport { verifyAxes, type VerifiedSpec } from \"./vet/verify.js\";\n\nexport async function vouch(req: VouchRequest): Promise<VouchOutcome> {\n  // A predecessor's journal is rolled forward BEFORE verification reads a\n  // byte. Recovery under the commit lock alone was tried first and kept as\n  // the backstop, but it changes files verification has already read, so the\n  // run's own raced check then refused a sound stamp and the fix doctor\n  // prints took two runs instead of one. Cheap when there is nothing to do:\n  // one existsSync.\n  const early = await recoverIfJournaled(req.docsDir);\n  if (!early.ok) return early;\n  // Verify first, stamp after: spec.md is required (a missing one is\n  // `unknown-target`), arch.spec.md rides when it exists, and one file that\n  // cannot be verified refuses the run before anything is written. The walk is\n  // `verifyAxes` (vet/verify.ts), shared with the reading list, and it hands\n  // the two files back by name — vet/verify.ts says why not a loop.\n  const axes = await verifyAxes(req);\n  if (!axes.ok) return axes;\n  const { spec: specVerified, arch: archVerified } = axes;\n  const verified: VerifiedSpec[] = [specVerified, ...(archVerified === null ? [] : [archVerified])];\n\n  // The READING window's race, which the commit window's byte compare cannot\n  // see. Under `--sample` a person spends minutes on the list before they\n  // answer, and the sample they were shown was chosen from digests taken\n  // before that. If either digest moved — or a second axis file appeared —\n  // the sections they read are not the sections this stamp would claim, and\n  // `vouch_scope` would record a read that did not happen. Nothing is written.\n  const raced = req.sample === undefined ? null : sampleDrift(req.sample, verified, req.service);\n  if (raced !== null) return { ok: false, code: \"vouch-raced\", message: raced };\n\n  const specPlan = planStamp(specVerified, req);\n  const archPlan = archVerified === null ? null : planStamp(archVerified, req);\n  const writes: PlannedWrite[] = [specPlan.write, ...(archPlan === null ? [] : [archPlan.write])];\n\n  // The slow half — reading specs, hashing sources, composing stamps — ran\n  // UNLOCKED above, so vouches for independent services do not serialise\n  // behind one repo-wide mutex. Only the commit window takes the docs lock:\n  // the same one archive, rebase and verify --record hold, in the waiting\n  // form, because two vouches for different services are both supposed to\n  // land. This is the lock the roadmap called missing: without it a vouch\n  // could stage against bytes an archive was mid-swap over, and the byte\n  // compare below would refuse a perfectly sound stamp — or worse, an\n  // interrupted commit's journal would be silently written over.\n  //\n  // A journal under the lock means the last writer never finished; the window\n  // recovers or refuses before reading the pre-images this commit will compare.\n  const opened = await openCommitWindow(req.docsDir, LOCK_WAIT_MS);\n  if (!opened.ok) return opened;\n  try {\n    return await commitStamp(req, { writes, specPlan, archPlan, verified }, opened.recovered ?? early.recovered);\n  } finally {\n    await opened.release();\n  }\n}\n\n/**\n * The commit window: stage, compare against what verification read, journal,\n * swap. Split from `vouch` so the lock's extent is visible in the code shape —\n * everything in here holds it, nothing above does.\n */\nasync function commitStamp(\n  req: VouchRequest,\n  plan: {\n    writes: PlannedWrite[];\n    specPlan: { write: PlannedWrite; stamped: StampedSpec };\n    archPlan: { write: PlannedWrite; stamped: StampedSpec } | null;\n    verified: VerifiedSpec[];\n  },\n  recovered: CommitRecovery | null,\n): Promise<VouchOutcome> {\n  const { writes, specPlan, archPlan, verified } = plan;\n  const staged = await stageWrites(writes);\n\n  // One shared docs repo, ten service repos, and nothing stopping two of them\n  // from vouching at once. Between reading a spec and swapping the stamp in\n  // there is a window in which somebody else's vouch (or an editor, or a merge)\n  // can land in the same file — and because the new bytes were computed from\n  // the OLD ones, swapping them in would take that stamp back out without a\n  // word. `stageWrites` has already read what is on disk right now, so the\n  // check is a comparison, not another read: if the file is not what was\n  // verified, this run is describing a document that no longer exists.\n  // Bytes, not text: `stageWrites` reads the file as a Buffer (a string\n  // comparison against it is never equal, which made every vouch report\n  // `vouch-raced` and stamp nothing). A file that is GONE is still a race —\n  // `null` is not \"empty\", it is \"the document this run described is not\n  // there any more\".\n  // Joined by path, not by index: pairing the two lists positionally assumed\n  // `stageWrites` returns one entry per planned write in order — true today,\n  // promised nowhere, and a compare-and-set that silently compares the wrong\n  // pair would stamp over somebody else's vouch. A staged write no verified\n  // file claims has nothing to be compared against, so it counts as raced;\n  // fail-closed is the only safe direction here.\n  const verifiedByPath = new Map(verified.map((v) => [v.path, v] as const));\n  const raced = staged.filter((s) => {\n    const v = verifiedByPath.get(s.write.path);\n    return v === undefined || s.before === null || !s.before.equals(Buffer.from(v.raw, \"utf8\"));\n  });\n  if (raced.length > 0) {\n    // Nothing has swapped yet, so the rollback is only the temp files going\n    // away — the other writer's stamp is left exactly as it landed.\n    await rollbackStaged(staged);\n    return {\n      ok: false,\n      code: \"vouch-raced\",\n      message:\n        `${req.service}: ${raced.map((s) => s.write.path).join(\", \")} changed while this vouch was running — ` +\n        `another vouch or an edit landed first. Nothing was stamped: re-read the document and re-run.`,\n    };\n  }\n\n  // The journaled commit: intent fsynced before the first rename, so a kill\n  // between the pair's two swaps is recoverable instead of invisible — the\n  // exact half-stamped state the all-or-nothing verification exists to rule\n  // out used to be reachable through that one window. The codes are archive's,\n  // reused rather than minted: rolled back → nothing changed, re-running can\n  // work; incomplete → the files listed need a human.\n  const committed = await commitStaged(\n    {\n      root: req.docsDir,\n      command: \"vouch\",\n      // Runnable where vouch runs — the SERVICE repo, with --yes because the\n      // journal's reader may be unattended. Any other journaled docs-repo\n      // writer recovers this journal on its next run too.\n      rerun: `loam vouch --service ${req.service} --yes`,\n      target: req.service,\n    },\n    staged,\n    \"stamped\",\n  );\n  if (!committed.ok) {\n    return committed.raced\n      ? {\n          ok: false,\n          code: \"vouch-raced\",\n          message:\n            `${req.service}: a document changed while this vouch was committing — ` +\n            `another writer landed first. Nothing was stamped: re-read and re-run.`,\n        }\n      : { ok: false, code: committed.code, message: committed.message };\n  }\n  return {\n    ok: true,\n    status: \"verified\",\n    lastVerified: req.today,\n    vouchedBy: req.vouchedBy,\n    recovered,\n    stamped: { spec: specPlan.stamped, archSpec: archPlan === null ? null : archPlan.stamped },\n  };\n}\n\n/**\n * One verified file's share of the commit: the bytes to write, and the record\n * of what was stamped into them. Kept beside each other because they are the\n * same computation — the report must describe the file that was actually\n * written, not a second guess at it.\n */\nexport function planStamp(v: VerifiedSpec, req: VouchRequest): { write: PlannedWrite; stamped: StampedSpec } {\n  // Two passes on purpose: `content_digest` hashes the body BELOW the\n  // frontmatter, and withFrontmatterFields promises that body byte-identical —\n  // so hashing after the first stamp and writing the hash in a second one\n  // yields a digest that is true of the file exactly as written. A re-vouch\n  // takes the same road and refreshes every field, this one included.\n  //\n  // The scope this file's stamp will carry — null both when the run is an\n  // ordinary vouch and when a sampled run's `--sample <n>` covered the whole\n  // file. Joined to the plan by FILENAME rather than taken positionally: the\n  // two axes are stamped by two separate calls, and a scope written onto the\n  // wrong file would claim a person read four sections of a document they\n  // never opened.\n  const planned = req.sample?.axes.find((axis) => axis.file === v.file);\n  // A verified file with no planned axis is unreachable — `sampleDrift`\n  // refuses that run before this line — and null is the safe direction if it\n  // ever were: a full stamp that CLEARS any prior scope, never one claiming a\n  // sample nobody was shown.\n  const scope = planned === undefined ? null : axisScope(planned);\n  const restamped = withFrontmatterFields(\n    v.raw,\n    {\n      status: \"verified\",\n      last_verified: req.today,\n      // WHO, beside when. Without it `status: verified` recorded that the word\n      // had been written and nothing about who wrote it, so a vouch and an\n      // agent's own draft left the same trace in the document — the one\n      // distinction this command exists to make.\n      vouched_by: req.vouchedBy,\n      sources_digest: v.digest,\n      // Beside the digest, what it was taken over. `sources_digest` alone can\n      // only ever say THAT the code moved; the next `loam validate` reads this\n      // back to say which files did.\n      sources_files: encodeSourceIndex(v.index),\n      // Beside `vouched_by`, never inside `status`: the rung string `vouched`\n      // and the status `verified` are a published contract, and a sampled read\n      // is not a fourth status — it is a qualification of this one.\n      ...(scope === null ? {} : { vouch_scope: encodeVouchScope(scope) }),\n    },\n    // A full vouch CLEARS any scope a previous sampled one left, rather than\n    // stranding a claim that would keep a fully-read document reading as\n    // partial forever. Removing a key that was never there is a no-op, so\n    // this rides on every run that is not itself sampling.\n    scope === null ? [\"vouch_scope\"] : [],\n  );\n  const bodyDigest = contentDigest(restamped);\n  return {\n    write: { path: v.path, content: withFrontmatterFields(restamped, { content_digest: bodyDigest }) },\n    stamped: {\n      path: v.path,\n      file: v.file,\n      digest: v.digest,\n      contentDigest: bodyDigest,\n      sources: v.sources,\n      files: v.index.length,\n      skipped: v.skipped,\n      vouchScope: scope,\n    },\n  };\n}\n"]}

package/dist/commands/vouch/sample/plan.js

@@ -0,0 +1,111 @@
+/**
+ * The pre-pass behind `loam vouch --sample <n>`: decide, before anyone is
+ * asked anything, which sections of which files this vouch will actually
+ * cover.
+ *
+ * It has to happen before the confirmation because a sampled vouch's question
+ * is different in kind — "have you read THESE four sections", not "have you
+ * read the code" — and a question that names nothing is the reflex this
+ * command exists to interrupt. So the reading list is computed first, printed,
+ * and only then is the person asked.
+ *
+ * It runs the vouch's own vetting (`../vet/verify.ts`: the same axis walk
+ * `run.ts` makes, over the call the reading pack makes), which means every
+ * refusal a vouch can raise about a document — an unreadable header, no
+ * `sources`, a glob pattern, a source that is gone, an expansion covering no
+ * files — fires HERE, before the prompt, with the same code and the same
+ * words. A person should not read four sections and then be told the run was
+ * never going to stamp.
+ *
+ * The cost is that the sources are walked and hashed twice: once to seed the
+ * sample, once at the stamp. That is the honesty price of the seed being
+ * content-derived, and `run.ts` spends the second walk anyway — what the
+ * second walk buys is the drift check, which refuses a stamp whose sample was
+ * chosen from a document that has since moved.
+ */
+import { contentDigest, rawBody } from "../../../core/document/frontmatter.js";
+import { planSample } from "../../../core/provenance/sample/scope.js";
+import { verifyAxes } from "../vet/verify.js";
+/** The scope a planned axis will stamp, or null for one that was read in full. */
+export function axisScope(axis) {
+    return axis.mode === "full" ? null : { sections: axis.picked.length, of: axis.of, seed: axis.seed };
+}
+/**
+ * What moved between the reading list and the stamp, as a phrase for the
+ * refusal — or null when the plan and the fresh verification describe the same
+ * documents.
+ *
+ * Joined by FILENAME both ways, and both directions matter: a plan entry with
+ * no verified file means an axis vanished mid-read, a verified file with no
+ * plan entry means one appeared and nobody was shown it. Comparing counts, or
+ * zipping the two lists, would call the second case fine.
+ *
+ * The digests, not the bytes: `content_digest` and `sources_digest` are the
+ * seed's own inputs, so a change in either is exactly a change in which
+ * sections a sample would pick. It lives here rather than in `run.ts` because
+ * it is a question about the PLAN — whether the reading list still describes
+ * these files — and the answer has to be computed the same way the plan was.
+ */
+export function sampleDrift(plan, verified, service) {
+    const now = new Map(verified.map((v) => [v.file, v]));
+    const moved = plan.axes
+        .filter((axis) => {
+        const v = now.get(axis.file);
+        return v === undefined || contentDigest(v.raw) !== axis.contentDigest || v.digest !== axis.sourcesDigest;
+    })
+        .map((axis) => axis.file);
+    const planned = new Set(plan.axes.map((axis) => axis.file));
+    const appeared = verified.filter((v) => !planned.has(v.file)).map((v) => v.file);
+    const files = [...moved, ...appeared];
+    if (files.length === 0)
+        return null;
+    // The whole sentence, not the file list: `run.ts` returns it verbatim under
+    // `vouch-raced`, and the diagnosis — which is about a READING window nothing
+    // locks — belongs beside the check that can explain it.
+    return (`${service}: ${files.join(", ")} changed while you were reading the sample — the sections you were shown are ` +
+        `not the sections a stamp would now cover. Nothing was stamped: re-run for a fresh reading list.`);
+}
+/**
+ * Build the reading list. The axis walk is `run.ts`'s own — `verifyAxes`, which
+ * refuses a missing spec.md in vet/verify.ts's one sentence (the same absence
+ * and the same fix; three spellings would read as three different problems) —
+ * and so is the all-or-nothing discipline: one file that cannot be verified
+ * refuses the run before a person is asked to read anything.
+ */
+export async function buildSamplePlan(req) {
+    const verified = await verifyAxes(req);
+    if (!verified.ok)
+        return verified;
+    const axes = [];
+    for (const vetted of verified.arch === null ? [verified.spec] : [verified.spec, verified.arch]) {
+        const digest = contentDigest(vetted.raw);
+        // The BODY, so no frontmatter line can be picked as a section — and the
+        // same slice `content_digest` is taken over, which is what makes the
+        // seed's inputs and the sampled text describe one document.
+        const body = rawBody(vetted.raw);
+        const sample = planSample({
+            service: req.service,
+            contentDigest: digest,
+            sourcesDigest: vetted.digest,
+            body,
+            n: req.n,
+        });
+        const base = {
+            file: vetted.file,
+            path: vetted.path,
+            contentDigest: digest,
+            sourcesDigest: vetted.digest,
+            of: sample.of,
+            // The header's line count, by subtraction rather than a second parse:
+            // `rawBody` is the one definition of where the body starts, and asking
+            // it twice is how the two answers drift.
+            lineOffset: vetted.raw.slice(0, vetted.raw.length - body.length).split("\n").length - 1,
+            sources: { entries: vetted.sources, files: vetted.index.length },
+        };
+        axes.push(sample.picked.length >= sample.of
+            ? { ...base, mode: "full" }
+            : { ...base, mode: "sampled", seed: sample.seed, picked: sample.picked });
+    }
+    return { ok: true, plan: { n: req.n, axes } };
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/vouch/sample/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/commands/vouch/sample/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pre-pass behind `loam vouch --sample <n>`: decide, before anyone is\n * asked anything, which sections of which files this vouch will actually\n * cover.\n *\n * It has to happen before the confirmation because a sampled vouch's question\n * is different in kind — \"have you read THESE four sections\", not \"have you\n * read the code\" — and a question that names nothing is the reflex this\n * command exists to interrupt. So the reading list is computed first, printed,\n * and only then is the person asked.\n *\n * It runs the vouch's own vetting (`../vet/verify.ts`: the same axis walk\n * `run.ts` makes, over the call the reading pack makes), which means every\n * refusal a vouch can raise about a document — an unreadable header, no\n * `sources`, a glob pattern, a source that is gone, an expansion covering no\n * files — fires HERE, before the prompt, with the same code and the same\n * words. A person should not read four sections and then be told the run was\n * never going to stamp.\n *\n * The cost is that the sources are walked and hashed twice: once to seed the\n * sample, once at the stamp. That is the honesty price of the seed being\n * content-derived, and `run.ts` spends the second walk anyway — what the\n * second walk buys is the drift check, which refuses a stamp whose sample was\n * chosen from a document that has since moved.\n */\nimport { contentDigest, rawBody } from \"../../../core/document/frontmatter.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport type { DocSection } from \"../../../core/provenance/sample/sections.js\";\nimport { planSample, type VouchScope } from \"../../../core/provenance/sample/scope.js\";\nimport { verifyAxes, type AxesRefusal, type VerifiedSpec } from \"../vet/verify.js\";\n\n/**\n * One spec-axis file's share of a `--sample <n>` run, as the pre-pass decided\n * it and the stamp must honour it.\n *\n * A variant rather than an optional `picked?:`, because \"read in full\" and\n * \"sampled\" are two different claims and the difference decides whether the\n * file gets a `vouch_scope` at all. The two digests ride on both arms: they\n * are what the seed was derived from, and the stamp re-checks them against a\n * fresh verification, because a person reads for minutes and nothing locks\n * the document while they do.\n */\ninterface PlannedAxisBase {\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". The key the stamp joins on. */\n  file: string;\n  /** Absolute path, for the reading list's own line. */\n  path: string;\n  /** `contentDigest(raw)` when the reading list was built. */\n  contentDigest: string;\n  /** The sources digest when the reading list was built. */\n  sourcesDigest: string;\n  /** Every section the body had. */\n  of: number;\n  /**\n   * How many lines of frontmatter sit above the body. `DocSection.line` is\n   * counted within the BODY — that is what the splitter can promise, since it\n   * is handed a body — and a reading list that printed those numbers as file\n   * lines would send a person to the wrong place in every stamped document.\n   * Added once, at the display edge.\n   */\n  lineOffset: number;\n  /** The `sources` entries as the frontmatter spells them, and how many files they expanded to. */\n  sources: { entries: string[]; files: number };\n}\n\nexport type PlannedAxis =\n  /** `of <= n`: the sample covers the whole file, so this axis is an ordinary full vouch. */\n  | (PlannedAxisBase & { mode: \"full\" })\n  | (PlannedAxisBase & { mode: \"sampled\"; seed: string; picked: readonly DocSection[] });\n\nexport interface SamplePlan {\n  /** `--sample <n>` as the person typed it — carried so the output can say what was asked for. */\n  n: number;\n  /**\n   * Every spec-axis file the pre-pass verified, sampled or not. Complete on\n   * purpose: the stamp compares this roster against what it re-verifies, so an\n   * arch.spec.md that appeared while the person was reading refuses the run\n   * instead of riding along unread.\n   */\n  axes: PlannedAxis[];\n}\n\n/** The scope a planned axis will stamp, or null for one that was read in full. */\nexport function axisScope(axis: PlannedAxis): VouchScope | null {\n  return axis.mode === \"full\" ? null : { sections: axis.picked.length, of: axis.of, seed: axis.seed };\n}\n\n/**\n * What moved between the reading list and the stamp, as a phrase for the\n * refusal — or null when the plan and the fresh verification describe the same\n * documents.\n *\n * Joined by FILENAME both ways, and both directions matter: a plan entry with\n * no verified file means an axis vanished mid-read, a verified file with no\n * plan entry means one appeared and nobody was shown it. Comparing counts, or\n * zipping the two lists, would call the second case fine.\n *\n * The digests, not the bytes: `content_digest` and `sources_digest` are the\n * seed's own inputs, so a change in either is exactly a change in which\n * sections a sample would pick. It lives here rather than in `run.ts` because\n * it is a question about the PLAN — whether the reading list still describes\n * these files — and the answer has to be computed the same way the plan was.\n */\nexport function sampleDrift(\n  plan: SamplePlan,\n  verified: readonly VerifiedSpec[],\n  service: string,\n): string | null {\n  const now = new Map(verified.map((v) => [v.file, v] as const));\n  const moved = plan.axes\n    .filter((axis) => {\n      const v = now.get(axis.file);\n      return v === undefined || contentDigest(v.raw) !== axis.contentDigest || v.digest !== axis.sourcesDigest;\n    })\n    .map((axis) => axis.file);\n  const planned = new Set(plan.axes.map((axis) => axis.file));\n  const appeared = verified.filter((v) => !planned.has(v.file)).map((v) => v.file);\n  const files = [...moved, ...appeared];\n  if (files.length === 0) return null;\n  // The whole sentence, not the file list: `run.ts` returns it verbatim under\n  // `vouch-raced`, and the diagnosis — which is about a READING window nothing\n  // locks — belongs beside the check that can explain it.\n  return (\n    `${service}: ${files.join(\", \")} changed while you were reading the sample — the sections you were shown are ` +\n    `not the sections a stamp would now cover. Nothing was stamped: re-run for a fresh reading list.`\n  );\n}\n\nexport interface SampleRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what `sources` resolve against. */\n  repoDir: string;\n  /** How many sections to read per spec-axis file. A whole number of at least 1; the caller validates. */\n  n: number;\n}\n\nexport type SampleOutcome = { ok: true; plan: SamplePlan } | AxesRefusal;\n\n/**\n * Build the reading list. The axis walk is `run.ts`'s own — `verifyAxes`, which\n * refuses a missing spec.md in vet/verify.ts's one sentence (the same absence\n * and the same fix; three spellings would read as three different problems) —\n * and so is the all-or-nothing discipline: one file that cannot be verified\n * refuses the run before a person is asked to read anything.\n */\nexport async function buildSamplePlan(req: SampleRequest): Promise<SampleOutcome> {\n  const verified = await verifyAxes(req);\n  if (!verified.ok) return verified;\n  const axes: PlannedAxis[] = [];\n  for (const vetted of verified.arch === null ? [verified.spec] : [verified.spec, verified.arch]) {\n    const digest = contentDigest(vetted.raw);\n    // The BODY, so no frontmatter line can be picked as a section — and the\n    // same slice `content_digest` is taken over, which is what makes the\n    // seed's inputs and the sampled text describe one document.\n    const body = rawBody(vetted.raw);\n    const sample = planSample({\n      service: req.service,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      body,\n      n: req.n,\n    });\n    const base = {\n      file: vetted.file,\n      path: vetted.path,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      of: sample.of,\n      // The header's line count, by subtraction rather than a second parse:\n      // `rawBody` is the one definition of where the body starts, and asking\n      // it twice is how the two answers drift.\n      lineOffset: vetted.raw.slice(0, vetted.raw.length - body.length).split(\"\\n\").length - 1,\n      sources: { entries: vetted.sources, files: vetted.index.length },\n    };\n    axes.push(\n      sample.picked.length >= sample.of\n        ? { ...base, mode: \"full\" }\n        : { ...base, mode: \"sampled\", seed: sample.seed, picked: sample.picked },\n    );\n  }\n  return { ok: true, plan: { n: req.n, axes } };\n}\n"]}