@sanning/proof 0.5.0 → 0.6.0

package/dist/side-content.d.ts

@@ -0,0 +1,36 @@
+/** A caller-built map of disclosed bytes, in either shape it can take. */
+export type SideContentMap = Readonly<Record<string, Uint8Array | string | undefined>> | ReadonlyMap<string, Uint8Array | string | undefined>;
+/** One event's entry, and — separately — whether an entry existed at all. */
+export interface SideEntry {
+    /** An entry EXISTS for this id. Never inferred from the value. */
+    offered: boolean;
+    /** What it held, read without ever invoking an accessor. */
+    value: Uint8Array | string | undefined;
+}
+/** Look up one event's out-of-band disclosure. The rule, stated once. */
+export declare function sideContentEntry(content: SideContentMap | null | undefined, eventId: string): SideEntry;
+/** Whether the map carries a usable entry for this id. The same rule. */
+export declare function hasSideContent(content: SideContentMap | null | undefined, eventId: string): boolean;
+/**
+ * The ids the map actually carries — the same rule applied to every key, so a
+ * key that is not an entry cannot be reported as surplus disclosure either.
+ */
+export declare function sideContentKeys(content: SideContentMap | null | undefined): string[];
+/**
+ * Whether an event's IN-BODY `events[].content` field is a disclosure.
+ *
+ * The other half of the same question, and it broke the same way. `content`
+ * is an OPTIONAL field, so `null` is how a producer's serializer spells its
+ * absence — Go's `json.Marshal` on a nil pointer without `omitempty`, Python's
+ * `json.dumps(None)`. A bare `!== undefined` marks such an event OFFERED while
+ * no bytes are selected (only a `string` decodes), and the kernel then splits
+ * against itself: `verifyEvidenceBundle` reports `contentOk: null` and rolls up
+ * VERIFIED, while `disclosedContent` reports FAILED — "content was disclosed
+ * for this event but is not a decodable lowercase-hex string". One kernel, one
+ * bundle, two verdicts, reachable from any conforming producer.
+ *
+ * Non-nullish and not a string — a number, an object, a hex string that is not
+ * hex — remains a real, unusable disclosure and stays a finding, exactly as on
+ * the side-input path.
+ */
+export declare function inBodyContentOffered(content: unknown): boolean;

package/dist/side-content.js

@@ -0,0 +1,98 @@
+// ONE answer to "did the holder actually supply bytes for this event_id?"
+//
+// WHY THIS IS A MODULE AND NOT TWO PRIVATE HELPERS.
+// The kernel asks that question in two places — the verifier, deciding whether
+// an event's content was offered at all (`evidence.ts`), and the grader,
+// accounting which records a pack disclosed (`grading.ts`). It had two answers.
+// On one and the same content map the grader said PRESENT while the verifier
+// said nothing was offered, so `gradePack` returned `incomplete` with ZERO
+// causes: a surface saying "incomplete" and unable to say why. That is exactly
+// the outcome `grading.ts`'s own comment claims was removed, reappearing
+// because the fix landed on one of the two definitions.
+//
+// Two implementations of one verification rule is the defect `grading.ts` was
+// extracted into the kernel to end. A rule stated once cannot drift; a rule
+// stated twice already has.
+//
+// ── THE RULE ────────────────────────────────────────────────────────────────
+//
+// An entry exists for `eventId` when the map carries an OWN, ENUMERABLE, DATA
+// property (or `Map` key) holding something other than `null`/`undefined`.
+// This is the STRICTER of the two definitions that were in the kernel — the
+// verifier's — and it is stricter on purpose. Every clause was paid for:
+//
+//   own         — an `event_id` is PRODUCER-CHOSEN, and every key on
+//                 `Object.prototype` is a legal one: `constructor`,
+//                 `toString`, `valueOf`, `hasOwnProperty`, `isPrototypeOf`,
+//                 `propertyIsEnumerable`, `toLocaleString`, `__proto__`. An
+//                 indexed lookup walks the prototype chain and resolves every
+//                 one of them, so absent evidence read as good evidence.
+//   enumerable  — what a caller means by "the map I built" is what
+//                 `Object.keys` shows; nothing hidden behind it counts.
+//   data        — an accessor is NEVER invoked. A getter can throw, and this
+//                 kernel's standing rule is that a verifier does not raise on
+//                 adversarial input. Not hypothetical: a plain-object map that
+//                 has taken a `__proto__` write carries `Uint8Array.prototype`
+//                 as its prototype, and reading `byteLength`, `length`,
+//                 `buffer` or `byteOffset` off a plain object through it throws
+//                 a TypeError. Reading a descriptor cannot.
+//   non-nullish — `{ [id]: undefined }` is how `Object.fromEntries` and friends
+//                 spell "no entry", and `new Map([[id, undefined]])` is the
+//                 same statement in the other shape. Anything else non-nullish
+//                 — a number, an object, a string that is not hex — IS a real,
+//                 unusable disclosure and stays a finding.
+//
+// `offered` is what separates "nothing was disclosed" (undetermined) from
+// "something was disclosed and is unusable" (a finding), and absent disclosure
+// is undetermined, not failed (evidence-bundle.md §5.1). So it is returned
+// SEPARATELY from the value and is never inferred from it: `value !== undefined`
+// is the conflation this module exists to remove, in both directions.
+const ABSENT = { offered: false, value: undefined };
+/** Look up one event's out-of-band disclosure. The rule, stated once. */
+export function sideContentEntry(content, eventId) {
+    if (content === undefined || content === null)
+        return ABSENT;
+    if (content instanceof Map) {
+        const value = content.get(eventId);
+        return value === undefined || value === null ? ABSENT : { offered: true, value };
+    }
+    const desc = Object.getOwnPropertyDescriptor(content, eventId);
+    if (desc === undefined || !desc.enumerable || !("value" in desc))
+        return ABSENT;
+    const value = desc.value;
+    return value === undefined || value === null ? ABSENT : { offered: true, value };
+}
+/** Whether the map carries a usable entry for this id. The same rule. */
+export function hasSideContent(content, eventId) {
+    return sideContentEntry(content, eventId).offered;
+}
+/**
+ * The ids the map actually carries — the same rule applied to every key, so a
+ * key that is not an entry cannot be reported as surplus disclosure either.
+ */
+export function sideContentKeys(content) {
+    if (content === undefined || content === null)
+        return [];
+    const keys = content instanceof Map ? [...content.keys()] : Object.keys(content);
+    return keys.filter((id) => hasSideContent(content, id));
+}
+/**
+ * Whether an event's IN-BODY `events[].content` field is a disclosure.
+ *
+ * The other half of the same question, and it broke the same way. `content`
+ * is an OPTIONAL field, so `null` is how a producer's serializer spells its
+ * absence — Go's `json.Marshal` on a nil pointer without `omitempty`, Python's
+ * `json.dumps(None)`. A bare `!== undefined` marks such an event OFFERED while
+ * no bytes are selected (only a `string` decodes), and the kernel then splits
+ * against itself: `verifyEvidenceBundle` reports `contentOk: null` and rolls up
+ * VERIFIED, while `disclosedContent` reports FAILED — "content was disclosed
+ * for this event but is not a decodable lowercase-hex string". One kernel, one
+ * bundle, two verdicts, reachable from any conforming producer.
+ *
+ * Non-nullish and not a string — a number, an object, a hex string that is not
+ * hex — remains a real, unusable disclosure and stays a finding, exactly as on
+ * the side-input path.
+ */
+export function inBodyContentOffered(content) {
+    return content !== undefined && content !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "dist",
+    "vectors",
     "README.md",
     "LICENSE"
   ],

package/src/cli.ts

@@ -14,8 +14,9 @@
 // `payloadHashOk === null` (a withheld record) is semantics-undetermined and
 // surfaces as a per-event note — it does NOT fail the run.
 
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
@@ -84,7 +85,7 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     return EXIT_MALFORMED;
   }
 
-  // Pull the optional `--logs <file>` flag out of the args; the rest are
+  // Pull the optional `--logs <path>` flag out of the args; the rest are
   // positional (<bundle> [gateways]). --logs feeds disclosed raw-log bytes for
   // content verification (the evidence-bundle path only).
   let logsPath: string | undefined;
@@ -94,7 +95,7 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     if (a === "--logs") {
       const next = rest[i + 1];
       if (next === undefined) {
-        io.err("verify: --logs requires a file path");
+        io.err("verify: --logs requires a path (a logs directory, or a JSON map file)");
         printUsage(io);
         return EXIT_MALFORMED;
       }
@@ -116,31 +117,13 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     .map((g) => g.trim())
     .filter((g) => g.length > 0);
 
-  let content: Record<string, Uint8Array | string> | undefined;
+  let logs: LoadedLogs | undefined;
   if (logsPath !== undefined) {
-    let logsRaw: string;
-    try {
-      logsRaw = await readFile(logsPath, "utf8");
-    } catch (e) {
-      io.err(`cannot read --logs ${logsPath}: ${e instanceof Error ? e.message : String(e)}`);
-      return EXIT_MALFORMED;
-    }
-    let logsParsed: unknown;
-    try {
-      logsParsed = JSON.parse(logsRaw);
-    } catch (e) {
-      io.err(`--logs ${logsPath} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
-      return EXIT_MALFORMED;
-    }
-    if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
-      io.err(`--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes`);
-      return EXIT_MALFORMED;
-    }
-    content = {};
-    for (const [k, v] of Object.entries(logsParsed as Record<string, unknown>)) {
-      if (typeof v === "string") content[k] = decodeLogValue(v);
-    }
+    logs = await loadLogs(logsPath, io);
+    if (logs === undefined) return EXIT_MALFORMED;
+    for (const n of logs.notes) io.err(`note: ${n}`);
   }
+  const content = logs?.content;
 
   let raw: string;
   try {
@@ -184,7 +167,11 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     ...(content ? { content } : {}),
     ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
   });
-  return reportEvidence(result, bundlePath, gateways, io);
+  const exit = reportEvidence(result, bundlePath, gateways, io);
+  // Coverage is reported only once the bundle parsed far enough to have events
+  // to compare against; over a MALFORMED bundle there is nothing to say.
+  if (logs && result.status !== "malformed") reportLogsCoverage(logs, result, io);
+  return exit;
 }
 
 // `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
@@ -390,10 +377,252 @@ async function readExporterKey(path: string, io: Cli): Promise<string | undefine
   return seed.toLowerCase();
 }
 
-// The --logs side-input lane decides each disclosed value's encoding: a clean,
+// ─── the `--logs` side input ────────────────────────────────────────────────
+//
+// Two shapes, one flag (proof#27):
+//
+//   DIRECTORY  `logs/<event_id>.json`, each file's RAW BYTES being the
+//              disclosure. This is the layout `materializeBundle` writes
+//              (bundle.json + logs/) and the layout the verify page hashes,
+//              so a pack verifies with NO side-input construction step.
+//   JSON MAP   `{ event_id: <even-length lowercase hex | utf8 text> }`, the
+//              original form. Unchanged.
+//
+// **Why the directory form exists at all.** Handing a pack to the CLI used to
+// require the caller to read `logs/` and hex-encode it into a map, and that
+// read-and-encode step has been got wrong twice in shipped code: claims-demo#9
+// wrote the hex TEXT into the log files (SHA-256 of hex text is not SHA-256 of
+// the bytes it encodes, so genuine evidence failed), and a runbook handed the
+// directory straight to `--logs` and got EISDIR, exit 2. The directory form
+// removes the encoding decision from the caller entirely — bytes in, bytes
+// hashed — so that whole class stops being reachable from this direction.
+//
+// **Nothing is re-encoded, re-parsed or re-serialised on the way in.** A log
+// file's bytes are passed to the verifier as a `Uint8Array`, which the verifier
+// uses as-is; only the map form's *strings* go through `decodeLogValue`. That
+// is the invariant this feature exists to hold, and it is what makes the CLI
+// and the verify page agree about one pack.
+interface LoadedLogs {
+  // Keyed by event id. A `Uint8Array` is raw bytes (directory form); a `string`
+  // is lowercase hex (map form). Those are exactly the two the verifier
+  // distinguishes.
+  //
+  // A `Map`, NOT a plain object, and that is load-bearing rather than stylistic.
+  // An event id is producer-chosen — here it arrives as a FILE NAME or a JSON
+  // key — and `content["__proto__"] = <bytes>` on an object literal does not
+  // store anything: it REPLACES the map's prototype with the Uint8Array. The
+  // disclosed bytes are then silently lost (the holder disclosed them and we
+  // report the record undisclosed), and every later lookup on that map resolves
+  // through `Uint8Array.prototype`, so an event named `slice` or `set` finds an
+  // inherited function and an event named `byteLength` or `buffer` THROWS a
+  // TypeError out of the verifier. A Map keys on the string itself and has none
+  // of that.
+  content: Map<string, Uint8Array | string>;
+  // Event ids the side input actually supplied — for the post-verify coverage
+  // cross-check, which needs to know what was offered, not just what bound.
+  suppliedIds: string[];
+  // Advisory lines about the INPUT ITSELF (skipped entries, a directory that
+  // disclosed nothing). None of them moves a verdict or an exit code.
+  notes: string[];
+}
+
+// The suffix the directory form reads, matched exactly — lowercase, which is
+// what `materializeBundle` writes. Anything else is skipped and NAMED rather
+// than guessed at, so a `.JSON` or extensionless file shows up as a note
+// instead of a mysteriously undisclosed event.
+const LOG_SUFFIX = ".json";
+
+// Which shape was passed is decided by `stat`, never by the extension: a pack's
+// log directory can be called anything, and `logs.json` is a legal directory
+// name. `stat` follows symlinks, so a symlinked logs directory works.
+async function loadLogs(logsPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let isDirectory: boolean;
+  try {
+    isDirectory = (await stat(logsPath)).isDirectory();
+  } catch (e) {
+    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+  return isDirectory ? loadLogsDirectory(logsPath, io) : loadLogsMap(logsPath, io);
+}
+
+// The JSON-map form, unchanged: `{ event_id: <hex | utf8 text> }`.
+async function loadLogsMap(logsPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let logsRaw: string;
+  try {
+    logsRaw = await readFile(logsPath, "utf8");
+  } catch (e) {
+    io.err(`cannot read --logs ${logsPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+  let logsParsed: unknown;
+  try {
+    logsParsed = JSON.parse(logsRaw);
+  } catch (e) {
+    io.err(`--logs ${logsPath} is not valid JSON: ${errMsg(e)}`);
+    return undefined;
+  }
+  if (logsParsed === null || typeof logsParsed !== "object" || Array.isArray(logsParsed)) {
+    io.err(
+      `--logs ${logsPath} must be a JSON object mapping event_id → disclosed bytes, ` +
+        `or a directory of <event_id>${LOG_SUFFIX} files`,
+    );
+    return undefined;
+  }
+  const content = new Map<string, Uint8Array | string>();
+  const suppliedIds: string[] = [];
+  for (const [k, v] of Object.entries(logsParsed as Record<string, unknown>)) {
+    if (typeof v !== "string") continue;
+    content.set(k, decodeLogValue(v));
+    suppliedIds.push(k);
+  }
+  return { content, suppliedIds, notes: [] };
+}
+
+// The directory form. Flat, one file per event, `<event_id>.json`.
+//
+// The decisions this pins, none of which is a verification failure — an absent
+// or unusable disclosure is UNDISCLOSED, and absence is not evidence of
+// tampering (evidence-bundle.md §5.1):
+//
+//   - a file whose name is not a known event id  → loaded, binds to nothing,
+//     named in a post-verify note (silence is how a typo'd filename becomes a
+//     mysteriously undisclosed event)
+//   - an event with no corresponding file        → undetermined (`~`), noted
+//   - an empty directory                         → valid; discloses nothing,
+//     noted, exit code unchanged
+//   - a subdirectory                             → skipped, never recursed,
+//     noted (this is the "you pointed at the pack root, not its logs/" case)
+//   - anything not named `<event_id>.json`, and anything that is not a regular
+//     file                                       → skipped, noted
+//
+// The one hard stop is a file we SELECTED but cannot read: we were pointed at
+// it, so a permissions error must not read as minimal disclosure. That exits 2.
+async function loadLogsDirectory(dirPath: string, io: Cli): Promise<LoadedLogs | undefined> {
+  let names: string[];
+  try {
+    names = await readdir(dirPath);
+  } catch (e) {
+    io.err(`cannot read --logs directory ${dirPath}: ${errMsg(e)}`);
+    return undefined;
+  }
+
+  const content = new Map<string, Uint8Array | string>();
+  const suppliedIds: string[] = [];
+  const skippedDirs: string[] = [];
+  const skippedNames: string[] = [];
+
+  for (const name of [...names].sort()) {
+    const p = join(dirPath, name);
+    let isDirectory: boolean;
+    let isFile: boolean;
+    try {
+      // `stat`, not the dirent kind: a symlinked log file is a log file, and a
+      // symlink to a directory is a directory.
+      const s = await stat(p);
+      isDirectory = s.isDirectory();
+      isFile = s.isFile();
+    } catch (e) {
+      io.err(`cannot read --logs entry ${p}: ${errMsg(e)}`);
+      return undefined;
+    }
+    if (isDirectory) {
+      skippedDirs.push(name);
+      continue;
+    }
+    // Not a regular file (device, fifo, socket), or not named
+    // `<event_id>.json` — including a file named exactly `.json`, whose event
+    // id would be the empty string.
+    if (!isFile || !name.endsWith(LOG_SUFFIX) || name.length === LOG_SUFFIX.length) {
+      skippedNames.push(name);
+      continue;
+    }
+    const eventId = name.slice(0, -LOG_SUFFIX.length);
+    try {
+      // No encoding argument: bytes, exactly as they sit on disk. Copied out of
+      // Buffer's shared pool so the array handed to the verifier owns its own
+      // memory rather than a window onto a reused block.
+      content.set(eventId, new Uint8Array(await readFile(p)));
+    } catch (e) {
+      io.err(`cannot read --logs file ${p}: ${errMsg(e)}`);
+      return undefined;
+    }
+    suppliedIds.push(eventId);
+  }
+
+  const notes: string[] = [];
+  if (skippedDirs.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ${count(skippedDirs.length, "subdirectory", "subdirectories")} ` +
+        `(${sample(skippedDirs)}) — the directory form reads <event_id>${LOG_SUFFIX} files ` +
+        `and does not recurse`,
+    );
+  }
+  if (skippedNames.length > 0) {
+    notes.push(
+      `--logs ${dirPath}: skipped ${count(skippedNames.length, "entry", "entries")} ` +
+        `not named <event_id>${LOG_SUFFIX} (${sample(skippedNames)})`,
+    );
+  }
+  if (suppliedIds.length === 0) {
+    notes.push(
+      `--logs ${dirPath} disclosed nothing (no <event_id>${LOG_SUFFIX} files) — every event ` +
+        `stays undisclosed, which is undetermined, not failed`,
+    );
+  }
+  return { content, suppliedIds, notes };
+}
+
+// What the side input covered, reported once the bundle's own event ids are
+// known. Both directions are ADVISORY — neither moves the verdict or the exit
+// code — and both exist because the silent version of each has already cost
+// somebody an afternoon:
+//
+//   - an entry matching no event binds to nothing. A typo'd id, or a directory
+//     scoped to a different bundle, otherwise looks identical to minimal
+//     disclosure.
+//   - an event whose content stayed undetermined disclosed no usable bytes.
+//     That is UNDISCLOSED, never a failure (evidence-bundle.md §5.1): absence
+//     of a disclosure is not evidence of tampering.
+function reportLogsCoverage(logs: LoadedLogs, result: EvidenceBundleResult, io: Cli): void {
+  const eventIds = new Set(result.events.map((e) => e.eventId));
+  const unmatched = logs.suppliedIds.filter((id) => !eventIds.has(id));
+  if (unmatched.length > 0) {
+    io.err(
+      `note: --logs supplied ${count(unmatched.length, "entry", "entries")} matching no event ` +
+        `in the bundle, ignored: ${sample(unmatched)}`,
+    );
+  }
+  const undetermined = result.events.filter((e) => e.contentOk === null);
+  if (undetermined.length > 0) {
+    io.err(
+      `note: ${undetermined.length} of ${result.events.length} event(s) have undetermined ` +
+        `content — no bytes disclosed, or no committed content_hash to bind them to. ` +
+        `Undisclosed, not failed: ${sample(undetermined.map((e) => e.eventId))}`,
+    );
+  }
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function count(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+// First few names, quoted, with a tail count — enough to recognise the mistake
+// without pasting a whole directory into the terminal.
+function sample(names: string[], max = 3): string {
+  const shown = names.slice(0, max).map((n) => JSON.stringify(n)).join(", ");
+  return names.length > max ? `${shown}, +${names.length - max} more` : shown;
+}
+
+// The --logs MAP lane decides each disclosed value's encoding: a clean,
 // even-length, lowercase-hex string is hex bytes; anything else is utf8 text.
 // (The verifier itself only distinguishes "string ⇒ hex" from "Uint8Array ⇒
-// raw bytes" — the human-facing encoding choice is made here.)
+// raw bytes" — the human-facing encoding choice is made here. The DIRECTORY
+// lane never reaches this: its bytes are already bytes.)
 function decodeLogValue(v: string): Uint8Array | string {
   if (v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v)) return v; // hex passthrough
   return utf8(v); // raw utf8 bytes
@@ -403,7 +632,7 @@ function printUsage(io: Cli): void {
   io.out("Usage: npx @sanning/proof <command> [args]");
   io.out("");
   io.out("Commands:");
-  io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle");
+  io.out("  verify <bundle.json> [gateways] [--logs <path>]        Verify a bundle");
   io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
   io.out("");
   io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
@@ -411,10 +640,21 @@ function printUsage(io: Cli): void {
   io.out("inclusion bundle, fully offline. Supply a comma-separated gateway list");
   io.out("to also re-fetch each checkpoint on-chain.");
   io.out("");
-  io.out("--logs <logs.json>  Bind disclosed raw logs to each event's committed");
-  io.out("                    content_hash. JSON object mapping event_id → bytes");
-  io.out("                    (even-length lowercase hex ⇒ hex, else utf8 text).");
-  io.out("                    In-body events[].content is verified automatically.");
+  io.out("--logs <path>       Bind disclosed raw logs to each event's committed");
+  io.out("                    content_hash. Either shape works, and which one you");
+  io.out("                    passed is decided by stat(), not by the extension:");
+  io.out("");
+  io.out("                      a DIRECTORY of <event_id>.json files — the file's");
+  io.out("                      raw bytes ARE the content, nothing is decoded.");
+  io.out("                      This is a materialized pack's logs/ directory:");
+  io.out("                        proof verify <pack>/bundle.json --logs <pack>/logs");
+  io.out("");
+  io.out("                      a JSON FILE mapping event_id → bytes (an");
+  io.out("                      even-length lowercase-hex value ⇒ hex, else utf8).");
+  io.out("");
+  io.out("                    In-body events[].content is verified automatically");
+  io.out("                    and takes precedence. An event with no disclosed");
+  io.out("                    bytes is undetermined (~), never a failure.");
   io.out("");
   io.out("Exit codes: 0 verified · 1 failed · 2 malformed · 3 gateway-unavailable");
 }
@@ -443,7 +683,7 @@ function reportEvidence(
     for (const cp of result.checkpoints) {
       const onChain = cp.onChainOk === null ? "" : `  on-chain ${mark(cp.onChainOk)}`;
       io.out(
-        `    ${mark(cp.ok)} ${shortTx(cp.txId)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`,
+        `    ${mark(cp.ok)} ${shortTx(cp.checkpointRef)}  envelope ${mark(cp.envelopeOk)}  root ${mark(cp.merkleRootOk)}${onChain}`,
       );
       for (const e of cp.errors) io.out(paint(`        - ${e}`, R));
     }

package/src/compose.ts

@@ -94,7 +94,7 @@ export function attestationSignatureToHex(signature: string): string {
 
 // Normalize one attestation record for embedding: deep-clone (never mutate the
 // caller's input) and transcode its signature to lowercase hex. Everything else
-// — payload, public_key, signature_alg, checkpoint_tx_id — rides verbatim so the
+// — payload, public_key, signature_alg, checkpoint_ref — rides verbatim so the
 // operator's RSA-PSS signature over JCS(payload) remains valid.
 function normalizeAttestation(rec: AttestationRecord): AttestationRecord {
   const cloned = JSON.parse(JSON.stringify(rec)) as AttestationRecord;