@sanning/proof 0.15.0 → 0.17.0

package/dist/compose.js

@@ -51,6 +51,27 @@ function normalizeAttestation(rec) {
     cloned.signature = attestationSignatureToHex(cloned.signature);
     return cloned;
 }
+// True when `value` holds a number that is NaN or +-Infinity. Iterative, so a
+// deeply nested input cannot overflow the stack before `jcs` bounds it.
+function hasNonFiniteNumber(value) {
+    const stack = [value];
+    while (stack.length > 0) {
+        const v = stack.pop();
+        if (typeof v === "number") {
+            if (!Number.isFinite(v))
+                return true;
+        }
+        else if (Array.isArray(v)) {
+            for (const x of v)
+                stack.push(x);
+        }
+        else if (v !== null && typeof v === "object") {
+            for (const x of Object.values(v))
+                stack.push(x);
+        }
+    }
+    return false;
+}
 // Compose an attested evidence export (evidence-export.md §5).
 //
 // 1. Normalize + transcode the attestation records (boundary hex, above).
@@ -73,6 +94,17 @@ export async function composeExport(sourceBundle, attestations, exporterKey, opt
     if (typeof exporterKey?.privateKey !== "string" || exporterKey.privateKey.length === 0) {
         throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
     }
+    // An over-long integer reads as Infinity (proof#217), which `jcs` refuses in
+    // the runtime's own words. Say it once, in the kernel's, before any
+    // verification: both kernels write this sentence, with no function-name prefix, so the CLI line is byte-identical.
+    if (hasNonFiniteNumber(sourceBundle)) {
+        throw new Error("the source bundle carries a number that is not a finite JSON number " +
+            "(an integer past the 1.8e308 range, or too long to read)");
+    }
+    if (hasNonFiniteNumber(attestations)) {
+        throw new Error("the attestations carry a number that is not a finite JSON number " +
+            "(an integer past the 1.8e308 range, or too long to read)");
+    }
     if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
         // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
         // A31), so composing one would sign an export this kernel rejects.

package/dist/declaration.d.ts

@@ -60,7 +60,7 @@ export interface DeclarationContentFinding {
     eventId?: string;
 }
 /** Everything this check reports that is NOT a deviation, as a closed set. */
-export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld"];
+export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld"];
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 /**
  * One named non-deviation finding, as data.

package/dist/declaration.js

@@ -130,10 +130,10 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
-import { hexToBytes } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { hexToBytes, utf8 } from "./crypto.js";
+import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered } from "./side-content.js";
+import { hasSideContent, inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
 /**
@@ -255,6 +255,23 @@ export const DECLARATION_NOTE_KINDS = [
      * because its payload binding is undetermined.
      */
     "role_step_withheld",
+    /**
+     * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
+     * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
+     * declaration object of a version this reader knows, carrying exactly that
+     * version's keys, and not this pack's own. The note names the content handed
+     * in, never the record: whether those bytes bind to the record's
+     * `content_hash` is the bundle verifier's check, and an accuser can hand in
+     * declaration-shaped bytes for an honest record. What the pack holds is what
+     * the declaration in its body says, so this moves no verdict.
+     */
+    "other_declaration_held",
+    /**
+     * Rule 10. A record whose signed `event_type` is `declaration` and whose
+     * content did not reach this reader from either channel, so whether it is a
+     * declaration other than this pack's own is UNKNOWN.
+     */
+    "other_declaration_withheld",
 ];
 /**
  * The record committed inside one `events[]` entry, or `null`.
@@ -500,6 +517,155 @@ function roleReading(p, role, claimed) {
     }
     return null;
 }
+/**
+ * The `event_type` a declaration record is signed under: a reserved
+ * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
+ * declaration as.
+ */
+const DECLARATION_EVENT_TYPE = "declaration";
+/**
+ * The keys a declaration object carries, under every version this reader
+ * knows: exactly these, no more and no fewer (5.4.1).
+ */
+const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
+function hasExactKeys(value, keys) {
+    if (!isObject(value))
+        return false;
+    const have = Object.keys(value);
+    return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+/**
+ * Whether `obj` is shaped like a declaration this reader knows: one of
+ * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
+ * defines, and the value types this module reads.
+ *
+ * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
+ * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
+ * declaration is somebody else's claim, and this reader does not grade it, it
+ * names it.
+ */
+function isDeclarationShape(obj) {
+    if (!isObject(obj))
+        return false;
+    const version = obj["declaration_version"];
+    if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2)
+        return false;
+    if (!hasExactKeys(obj, DECLARATION_KEYS))
+        return false;
+    if (!isId(obj["case_id"]))
+        return false;
+    const agents = obj["agents"];
+    if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string"))
+        return false;
+    const period = obj["period"];
+    if (!hasExactKeys(period, ["start", "end"]))
+        return false;
+    if (typeof period["start"] !== "string" || typeof period["end"] !== "string")
+        return false;
+    const recordKeys = version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+    const records = obj["records"];
+    if (!Array.isArray(records))
+        return false;
+    for (const r of records) {
+        if (!hasExactKeys(r, recordKeys) || typeof r["event_id"] !== "string")
+            return false;
+    }
+    const handoffs = obj["handoffs"];
+    if (!Array.isArray(handoffs))
+        return false;
+    return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+}
+/**
+ * The content bytes disclosed for one record, or `null` where none are usable:
+ * `events[].content` first, then the side-content map, chosen the way the
+ * bundle verifier chooses the bytes it binds.
+ */
+function disclosedBytes(ev, p, content) {
+    const inBody = isObject(ev) ? ev["content"] : undefined;
+    if (typeof inBody === "string") {
+        try {
+            return hexToBytes(inBody);
+        }
+        catch {
+            // falls through to the side channel, as the bundle verifier does
+        }
+    }
+    if (!p.nameable)
+        return null;
+    const side = sideContentEntry(content, p.eventId).value;
+    if (side instanceof Uint8Array)
+        return side;
+    if (typeof side === "string") {
+        try {
+            return hexToBytes(side);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
+ * Canonical bytes, not merely parseable ones: a declaration is anchored as
+ * `JCS(declaration)`, and nothing an agent writes by accident.
+ */
+function isDeclarationBytes(raw) {
+    try {
+        const obj = jcsParse(raw);
+        return isDeclarationShape(obj) && sameBytes(utf8(jcs(obj)), raw);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Rule 10: every record that is a declaration other than the pack's own, in
+ * bundle order.
+ *
+ * The record's `event_type` is read from its signed `event_bytes`, so a record
+ * whose bytes the pack withholds is not named: the reader cannot see what it
+ * was signed as. Its content is read from either channel; a record whose
+ * content is byte for byte `JCS` of the pack's own declaration is the pack's
+ * own and is never named.
+ */
+function otherDeclarationNotes(bundle, pack, declaration, content) {
+    const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+    let own = null;
+    try {
+        own = utf8(jcs(declaration));
+    }
+    catch {
+        own = null;
+    }
+    const notes = [];
+    pack.forEach((p, i) => {
+        if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE)
+            return;
+        const raw = disclosedBytes(events[i], p, content);
+        if (raw === null) {
+            // Offered and unusable is not withheld: something arrived, it is not a
+            // declaration, and the bundle verifier names what is wrong with it.
+            // Nothing arrived is the reading the reader cannot settle.
+            if (!p.disclosed)
+                notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
+            return;
+        }
+        if (own !== null && sameBytes(raw, own))
+            return;
+        if (isDeclarationBytes(raw))
+            notes.push({ kind: "other_declaration_held", eventId: p.eventId });
+    });
+    return notes;
+}
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -719,6 +885,11 @@ export function checkDeclaration(bundle, content) {
                 deviations.push({ kind, eventId });
         }
     }
+    // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
+    // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
+    // never a deviation: the pack holds what its own declaration says whatever
+    // one of its records says.
+    notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
     // A proven deviation wins: it is a mismatch between what the pack claimed
     // and what its own signed body carries, and a failing check always wins.
     // With no deviation and a content-dependent finding, the pack lines up with
@@ -838,6 +1009,14 @@ export function renderNote(note) {
         case "role_step_withheld":
             return (`${note.eventId} is signed as a step and this pack withholds its ` +
                 "record bytes, so whether it is one is UNKNOWN");
+        case "other_declaration_held":
+            return (`the content handed in for ${note.eventId} is a declaration that is ` +
+                "not this pack's own: it says what some pack holds, and what this " +
+                "pack holds is what the declaration in its body says");
+        case "other_declaration_withheld":
+            return (`${note.eventId} is signed as a declaration and no content for it ` +
+                "reached this verifier, so whether it is a declaration other than " +
+                "this pack's own is UNKNOWN");
     }
 }
 /**

package/dist/evidence.js

@@ -21,6 +21,7 @@ import { deriveOperatorAddress, ed25519Verify, hexToBytes,
 // body: two copies of one rule is how two kernels drift apart one edit at a
 // time, which is the whole defect class this fix is about.
 isHexField, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
+import { safeInteger, signedLeafCount } from "./grading.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { leafHash, verifyInclusion } from "./merkle.js";
 import { DuplicateKeyError, MAX_CANONICAL_DEPTH, contentHashes, exceedsDepth, isRfc3339UtcInstant, jcs, jcsParse, verifyEnvelope, } from "./verifier.js";
@@ -683,6 +684,7 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
         const cpErrors = [];
         let envelopeOk = false;
         let merkleRootOk = false;
+        let leafCountOk = false;
         // Decode event_bytes first: in v2 the join key is DERIVED from it, so it
         // is an input to identity, not just to the payload binding below.
         let eventBytes;
@@ -770,6 +772,15 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
                     cpErrors.push(`checkpoint merkle_root mismatch: claimed=${jsonStr(cp.merkle_root)} ` +
                         `committed=${jsonStr(committedRoot)}`);
                 }
+                // §5.1, A38 (proof#197), decided by Phil 2026-10-06: fail closed. The
+                // count the record signs is what every inclusion bound to this
+                // checkpoint is held to, so a record that signs no integer count fails
+                // the checkpoint, as a record that signs no merkle_root does. Read by
+                // value through the one reader the inclusion compare and the
+                // completeness notes share, so `3.0` and `3e0` are 3.
+                leafCountOk = signedLeafCount(cp) !== null;
+                if (!leafCountOk)
+                    cpErrors.push("checkpoint record leaf_count is not an integer");
             }
             catch (e) {
                 cpErrors.push(`checkpoint record is not JSON${thrownDetail(e)}`);
@@ -788,7 +799,7 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
             // standing rule is that malformed is a failure while absent is
             // undetermined (the same rule disclosed `content` follows). Without
             // this term the vector `trace-v2-malformed-anchor-ref` verified GREEN.
-            ok: envelopeOk && merkleRootOk && keyed.errors.length === 0 && !duplicateKey,
+            ok: envelopeOk && merkleRootOk && leafCountOk && keyed.errors.length === 0 && !duplicateKey,
             errors: cpErrors,
         });
         if (keyed.anchorRefMalformed) {
@@ -919,30 +930,61 @@ async function verifyAnchorTrace(b, specVersionOk, assertedStatus, errors, optio
         }
         const checkpointBound = cp !== undefined;
         let inclusionOk = false;
+        // §5.1, A38 (proof#197): the tree walked must be the tree the checkpoint
+        // record signed, the same rule and the same sentence as the stamp path's
+        // rule 3. RFC 9162's walk reads one audit path as valid at more than one
+        // (leaf_index, leaf_count), so without this a real proof at (2, 3) also
+        // verified as (1, 2) or (4, 5). A signed count that cannot be read is not
+        // compared here: it has already failed its checkpoint (above), so the
+        // bundle cannot verify. One reader of the signed count, shared with the
+        // completeness notes, so the verdict and the grade never read two
+        // different numbers.
+        //
+        // Every number here is read BY VALUE (`Number.isSafeInteger`), the model
+        // JCS signs, and the Python kernel reads the same way (`_safe_integer`):
+        // JCS writes `3.0` as `3`, so a stated `3.0` is the integer 3 under the
+        // same wrapper signature. A value that is not a safe integer is malformed,
+        // with one sentence that prints no value, because the two kernels cannot
+        // print `2.5`, `1e400` or `9007199254740993` the same way.
+        const signedCount = cp ? signedLeafCount(cp) : null;
         if (incl && checkpointBound && cp) {
-            try {
-                inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), 
-                // No `?? ""` fallback. A checkpoint that claims NO root must not be
-                // handed an invented empty one: the Python kernel refuses the same
-                // value and reports the decode failure, so substituting "" here had
-                // the two kernels say different things about one bundle (TS: "the
-                // proof did not reconstruct the checkpoint root", which is not what
-                // happened: there was no claimed root to reconstruct).
-                hexToBytes(cp.merkle_root));
-                if (!inclusionOk)
-                    evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
-                // Defense in depth: the claimed leaf_hash MUST be the hash of the
-                // event's own signed envelope bytes (profile §6) — otherwise a valid
-                // inclusion proof for an UNRELATED leaf could be smuggled in.
-                const expectedLeaf = await leafHash(utf8(jcs(ev.envelope)));
-                const expectedLeafHex = toHex(expectedLeaf);
-                if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
-                    inclusionOk = false;
-                    evErrors.push(`inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))`);
-                }
+            const statedCount = safeInteger(incl.leaf_count);
+            const statedIndex = safeInteger(incl.leaf_index);
+            if (statedCount === null) {
+                evErrors.push("inclusion leaf_count is not an integer");
             }
-            catch (e) {
-                evErrors.push(`inclusion verify error${thrownDetail(e)}`);
+            else if (statedIndex === null) {
+                evErrors.push("inclusion leaf_index is not an integer");
+            }
+            else if (signedCount !== null && statedCount !== signedCount) {
+                evErrors.push(`inclusion leaf_count ${statedCount} does not equal ` +
+                    `the checkpoint's committed leaf_count ${signedCount}`);
+            }
+            else {
+                try {
+                    inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), statedIndex, statedCount, (incl.audit_path ?? []).map((h) => hexToBytes(h)), 
+                    // No `?? ""` fallback. A checkpoint that claims NO root must not be
+                    // handed an invented empty one: the Python kernel refuses the same
+                    // value and reports the decode failure, so substituting "" here had
+                    // the two kernels say different things about one bundle (TS: "the
+                    // proof did not reconstruct the checkpoint root", which is not what
+                    // happened: there was no claimed root to reconstruct).
+                    hexToBytes(cp.merkle_root));
+                    if (!inclusionOk)
+                        evErrors.push("RFC 9162 inclusion proof did not reconstruct the checkpoint root");
+                    // Defense in depth: the claimed leaf_hash MUST be the hash of the
+                    // event's own signed envelope bytes (profile §6) — otherwise a valid
+                    // inclusion proof for an UNRELATED leaf could be smuggled in.
+                    const expectedLeaf = await leafHash(utf8(jcs(ev.envelope)));
+                    const expectedLeafHex = toHex(expectedLeaf);
+                    if (expectedLeafHex !== (incl.leaf_hash ?? "").toLowerCase()) {
+                        inclusionOk = false;
+                        evErrors.push(`inclusion leaf_hash does not match SHA-256(0x00 || JCS(event envelope))`);
+                    }
+                }
+                catch (e) {
+                    evErrors.push(`inclusion verify error${thrownDetail(e)}`);
+                }
             }
         }
         // Content (raw-log) binding — shared with every other event-carrying body.
@@ -1143,8 +1185,16 @@ function isLowerHex(s, nibbles) {
         return false;
     return /^[0-9a-f]+$/.test(s);
 }
-function isNonNegInt(n) {
-    return typeof n === "number" && Number.isInteger(n) && n >= 0;
+/**
+ * A JSON number read BY VALUE as a non-negative safe integer, or null.
+ * `safeInteger`, the reader every leaf count and leaf index in this kernel
+ * goes through (A38), mirrored by `_non_neg_integer` in
+ * `src/sanning_proof/evidence.py`. `Number.isInteger` alone accepted `1e+21`,
+ * JCS's own spelling of a count past 2**53 - 1, which Python refused.
+ */
+function nonNegInteger(n) {
+    const v = safeInteger(n);
+    return v !== null && v >= 0 ? v : null;
 }
 /**
  * Parse and check one stamp's witnessed bytes.
@@ -1382,12 +1432,13 @@ async function verifyStampEntry(raw, seen) {
     else {
         base.merkleRoot = body.merkle_root;
     }
-    if (!isNonNegInt(body.leaf_count)) {
+    const stampCount = nonNegInteger(body.leaf_count);
+    if (stampCount === null) {
         errors.push("stamp body leaf_count is not a non-negative integer");
         base.bodyOk = false;
     }
     else {
-        base.leafCount = body.leaf_count;
+        base.leafCount = stampCount;
     }
     // --- the sub-tree ranges --------------------------------------------------
     base.subtreesOk = checkSubtrees(body, base, errors);
@@ -1426,14 +1477,16 @@ function checkSubtrees(body, out, errors) {
             continue;
         }
         const s = v;
-        if (!isNonNegInt(s.first_leaf)) {
+        const firstLeaf = nonNegInteger(s.first_leaf);
+        const subCount = nonNegInteger(s.leaf_count);
+        if (firstLeaf === null) {
             errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
             shapeOk = false;
         }
         // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
         // an arbitrary number of empty ranges sit inside a tiling that still adds
         // up.
-        if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+        if (subCount === null || subCount === 0) {
             errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
             shapeOk = false;
         }
@@ -1445,8 +1498,8 @@ function checkSubtrees(body, out, errors) {
             continue;
         subtrees.push({
             ref,
-            firstLeaf: s.first_leaf,
-            leafCount: s.leaf_count,
+            firstLeaf: firstLeaf,
+            leafCount: subCount,
             root: s.root,
         });
     }
@@ -1454,11 +1507,14 @@ function checkSubtrees(body, out, errors) {
     out.subtrees = subtrees;
     if (!shapeOk)
         return false;
-    const total = body.leaf_count;
-    if (!isNonNegInt(total))
+    const total = out.leafCount;
+    if (total === null)
         return false; // already reported by the caller
-    const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
-    if (sum !== total) {
+    // Summed exactly. Each count is a safe integer but their sum need not be,
+    // and a float sum past 2**53 prints a different number than Python's
+    // unbounded one in the sentence below.
+    const sum = subtrees.reduce((n, s) => n + BigInt(s.leafCount), 0n);
+    if (sum !== BigInt(total)) {
         errors.push(`sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`);
         return false;
     }
@@ -1715,13 +1771,27 @@ async function verifyStampEvidence(b, specVersionOk, assertedStatus, errors, opt
             // Rule 3: the tree walked must be the tree the stamp committed to. A
             // proof walked against a different leaf_count is a proof about a
             // different tree, and RFC 9162's path shape depends on the size.
-            if (st.leafCount !== null && incl.leaf_count !== st.leafCount) {
-                evErrors.push(`inclusion leaf_count ${incl.leaf_count} does not equal the stamp's committed ` +
+            //
+            // Read BY VALUE, as the anchor-trace path reads them (A38), and as the
+            // Python kernel does (`_safe_integer`): the wrapper signs JCS(body),
+            // which writes `3.0` as `3`, so a stated `3.0` is 3 under the same
+            // signature. Anything that is not a safe integer is malformed, with a
+            // sentence that prints no value.
+            const statedCount = safeInteger(incl.leaf_count);
+            const statedIndex = safeInteger(incl.leaf_index);
+            if (statedCount === null) {
+                evErrors.push("inclusion leaf_count is not an integer");
+            }
+            else if (statedIndex === null) {
+                evErrors.push("inclusion leaf_index is not an integer");
+            }
+            else if (st.leafCount !== null && statedCount !== st.leafCount) {
+                evErrors.push(`inclusion leaf_count ${statedCount} does not equal the stamp's committed ` +
                     `leaf_count ${st.leafCount}`);
             }
             else {
                 try {
-                    inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), incl.leaf_index, incl.leaf_count, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(st.merkleRoot ?? ""));
+                    inclusionOk = await verifyInclusion(hexToBytes(incl.leaf_hash), statedIndex, statedCount, (incl.audit_path ?? []).map((h) => hexToBytes(h)), hexToBytes(st.merkleRoot ?? ""));
                     if (!inclusionOk) {
                         evErrors.push("RFC 9162 inclusion proof did not reconstruct the stamp root");
                     }

package/dist/file-match.d.ts

@@ -47,6 +47,13 @@ export declare const FILE_MATCH_SCOPE: string;
 /** Why a record's commitments could not be read, in the order they are tested. */
 export declare const NOT_READ_REASONS: readonly ["no_records", "record_unreadable", "record_not_verified", "record_withheld", "no_content_hash", "handoff_record_malformed", "message_withheld"];
 export type NotReadReason = (typeof NOT_READ_REASONS)[number];
+/**
+ * Why a file was named in the report and never hashed (5.7.5). A skipped file
+ * is listed, never dropped: every file a command found is matched, unmatched or
+ * skipped, so "no match" is never read as "no file was there".
+ */
+export declare const SKIPPED_REASONS: readonly ["symbolic_link", "not_regular", "unreadable", "too_large", "refused"];
+export type SkippedReason = (typeof SKIPPED_REASONS)[number];
 /** One commitment a signed record makes to a file's bytes. */
 export interface FileCommitment {
     packRef: string | null;
@@ -56,6 +63,14 @@ export interface FileCommitment {
     contentHash: string;
     signer: string;
     signedAt: string | null;
+    /**
+     * The pack, by its position in the packs `matchCaseFiles` was handed (the
+     * same position the case reading's `packIndex` names), or `null` from
+     * `matchFiles`, which reads one pack (A43).
+     */
+    packIndex: number | null;
+    /** The record, by its position in the events the pack presents (A43). */
+    recordIndex: number;
 }
 export interface MatchedFile {
     name: string;
@@ -66,10 +81,24 @@ export interface UnmatchedFile {
     name: string;
     sha256: string;
 }
+/** A file a command found and did not hash, named with the reason. */
+export interface SkippedFile {
+    name: string;
+    reason: SkippedReason;
+    /** The reader's own words, for a `.zip` entry it refused (`refused`). */
+    detail?: string;
+}
 export interface NotRead {
     packRef: string | null;
     eventId: string | null;
     reason: NotReadReason;
+    /** As on `FileCommitment` (A43). */
+    packIndex: number | null;
+    /**
+     * As on `FileCommitment`, or `null` where the pack presents no events at all
+     * (`no_records`).
+     */
+    recordIndex: number | null;
 }
 export interface FileMatchReading {
     offered: number;
@@ -78,12 +107,27 @@ export interface FileMatchReading {
     notOffered: FileCommitment[];
     notRead: NotRead[];
     scope: string;
+    /**
+     * Files found and not hashed. The matching functions leave it empty: it is
+     * the caller's, because only a caller that reads a folder knows a link.
+     */
+    skipped?: SkippedFile[];
 }
-/** A file handed in beside a pack. `name` is a label and is never compared. */
-export interface OfferedFile {
+/**
+ * A file handed in beside a pack. `name` is a label and is never compared. The
+ * file is its `bytes`, or its `sha256` (64 lowercase hex characters) where the
+ * caller has already hashed it: a command streams a file of any size rather
+ * than hold it.
+ */
+export type OfferedFile = {
     name: string;
     bytes: Uint8Array;
-}
+    sha256?: undefined;
+} | {
+    name: string;
+    sha256: string;
+    bytes?: undefined;
+};
 /** One pack of a case, for `matchCaseFiles`. */
 export interface FileMatchPack {
     ref: string;
@@ -101,5 +145,20 @@ export declare function matchFiles(bundle: unknown, files: readonly OfferedFile[
 export declare function matchCaseFiles(packs: readonly FileMatchPack[], files: readonly OfferedFile[]): Promise<FileMatchReading>;
 /** The reading as the `files` member of `--json`, identical in both kernels. */
 export declare function fileMatchToJson(reading: FileMatchReading): Record<string, unknown>;
-/** The text report's lines for the reading, identical in both kernels. */
-export declare function renderFileMatch(reading: FileMatchReading): string[];
+/**
+ * The commitments no offered file matched and no disclosed log answers.
+ *
+ * `contents` is each pack's side content by `pack_ref`. A record whose own pack
+ * discloses bytes that hash to its `content_hash` is accounted for by the pack,
+ * and is not returned. Only the text report's count reads this; the reading, and
+ * `--json`, still list every commitment no file matched.
+ */
+export declare function notAccountedFor(reading: FileMatchReading, contents: ReadonlyMap<string, SideContentMap | null | undefined>): Promise<FileCommitment[]>;
+/**
+ * The text report's lines for the reading, identical in both kernels.
+ *
+ * By default every commitment no file matched is a line. `notAmong` is the case
+ * command's report when no `--files` was given: one count line for the recorded
+ * files no loose file matched, and no line for each (A41).
+ */
+export declare function renderFileMatch(reading: FileMatchReading, notAmong?: number): string[];