@sanning/proof 0.10.0 → 0.11.1

package/dist/grading.d.ts

@@ -1,3 +1,5 @@
+import type { DeclarationCheck, DeclarationContentKind, DeclarationDeviationKind, DeclarationVerdict } from "./declaration.js";
+import { type SideContentMap } from "./side-content.js";
 export type PackVerdict = "verified" | "partial" | "pending" | "not_found" | "mixed" | "failed" | "malformed" | "incomplete";
 /**
  * The minimum this module reads out of a verification result.
@@ -54,7 +56,13 @@ export type CompletenessNote = {
     presented: null;
     kind: "unreadable";
 };
-export type PackGradeCauseKind = "records-omitted" | "records-surplus" | "leaf-count-unreadable" | "no-disclosure" | "missing-disclosure" | "unreadable-disclosure" | "unaccounted-disclosure";
+export type PackGradeCauseKind = "records-omitted" | "records-surplus" | "leaf-count-unreadable" | "no-disclosure" | "missing-disclosure" | "unreadable-disclosure" | "unaccounted-disclosure" | "declaration-deviation"
+/**
+ * The pack and the UNSIGNED content handed in beside it do not line up
+ * (proof#147). A cause, so the pack cannot read clean over it and a reader
+ * is told which record; NOT a deviation, so it never reaches `failed`.
+ */
+ | "declaration-content-dependent";
 /**
  * One reason a pack is not `verified`, as data.
  *
@@ -79,6 +87,12 @@ export interface PackGradeCause {
     firstEventId?: string;
     /** Why one supplied disclosure could not be used. */
     reason?: string;
+    /**
+     * Which deviation from the pack's own declaration, for
+     * `declaration-deviation`, or which content-dependent finding, for
+     * `declaration-content-dependent`.
+     */
+    deviation?: DeclarationDeviationKind | DeclarationContentKind;
 }
 export interface PackGrade {
     verdict: PackVerdict;
@@ -87,6 +101,12 @@ export interface PackGrade {
     recordsFailed: number;
     recordsUndetermined: number;
     causes: PackGradeCause[];
+    /**
+     * The declaration check's own verdict, carried so a consumer that reads only
+     * this value can tell a declared pack from an undeclared one. Absent when no
+     * check was passed, which is the pre-§5.4 call.
+     */
+    declaration?: DeclarationVerdict;
 }
 /**
  * Account for the disclosed bytes a pack handed us against the records its
@@ -110,7 +130,7 @@ export interface PackGrade {
  * listing and pass that to `gradePack` — the rule takes an account, never a
  * bundle, precisely so the transport can say things the map cannot.
  */
-export declare function accountDisclosure(bundle: unknown, content: Readonly<Record<string, Uint8Array>> | ReadonlyMap<string, Uint8Array>): DisclosureAccount;
+export declare function accountDisclosure(bundle: unknown, content: SideContentMap): DisclosureAccount;
 /** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
 export declare function signedLeafCount(checkpoint: {
     event_bytes?: unknown;
@@ -132,7 +152,7 @@ export declare function completenessNotes(bundle: unknown): CompletenessNote[];
  * Every reason this pack is not `verified`, in the order a reader should hear
  * them: what is missing from the whole, then what is missing from the parts.
  */
-export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[]): PackGradeCause[];
+export declare function gradeCauses(account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null): PackGradeCause[];
 /**
  * The verdict a surface may print, and the counts it may print beside it.
  *
@@ -145,8 +165,49 @@ export declare function gradeCauses(account: DisclosureAccount, notes: readonly
  * (§5.1: undetermined, not failed), and a proven mismatch is never softened
  * into absence. The last branch passes the kernel's headline through unchanged:
  * this rule DOWNGRADES a verdict, it never invents one.
+ *
+ * ── the declaration (optional fourth argument) ──────────────────────────────
+ *
+ * `declaration` is what `checkDeclaration` in `./declaration.ts` made of the
+ * pack's own signed statement of what it holds (`evidence-bundle.md` §5.4). A
+ * deviation from it is a PROVEN mismatch between what the pack claimed and
+ * what it carries, so it FAILS the pack and each deviation becomes its own
+ * cause. It must never soften into absence: that is how a trimmed hand-over
+ * reads as an innocent gap.
+ *
+ * A check that came back `partial` splits in THREE (proof#147), and the first
+ * of the three is not about the declaration's readability at all. The other
+ * two split on whether the body carried a `declaration` member.
+ *
+ *   content-dependent      the pack and the UNSIGNED content beside it do not
+ *                          line up (proof#147). Each finding is its own cause
+ *                          and the pack is `incomplete`. It must never reach
+ *                          `failed`: whoever assembles a case fills in the
+ *                          side-content map, so an accuser holding an intact
+ *                          pack could otherwise put its holder into `failed`
+ *                          with no key at all, by dropping one file or adding
+ *                          one. `failed` is left to what a signature covers.
+ *   no declaration at all   nothing moves. Every pack built before §5.4 is
+ *                           this case, and re-grading them would move pinned
+ *                           exit codes for artifacts already in customers'
+ *                           hands.
+ *   present and unreadable  the pack is `incomplete`. `declaration_version` is
+ *                           chosen by the same party that assembles the pack
+ *                           and has no accept-set, so a holder who trims a
+ *                           record and then writes one unreadable field can
+ *                           re-seal the pack with its own key and hand a
+ *                           reader a clean verdict over evidence of the trim
+ *                           sitting inside the signed body. UNKNOWN is the
+ *                           only honest answer to a claim the reader cannot
+ *                           read, and it adds no cause: `PackGrade.declaration`
+ *                           says why.
+ *
+ * `verified` adds nothing and moves nothing.
+ *
+ * Omitting the argument entirely is the pre-§5.4 behavior, unchanged, and
+ * `PackGrade.declaration` is then absent.
  */
-export declare function gradePack(result: GradeInput, account: DisclosureAccount, notes: readonly CompletenessNote[]): PackGrade;
+export declare function gradePack(result: GradeInput, account: DisclosureAccount, notes: readonly CompletenessNote[], declaration?: DeclarationCheck | null): PackGrade;
 /**
  * The house wording for one cause.
  *

package/dist/grading.js

@@ -67,7 +67,12 @@
 // copy against it. If an implementation disagrees with the table, the
 // implementation is wrong.
 import { hexToBytes } from "./crypto.js";
+import { renderContentFinding, renderDeviation } from "./declaration.js";
 import { hasSideContent, sideContentKeys } from "./side-content.js";
+// 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 { jcsParse } from "./verifier.js";
 /**
  * The checkpoint's join key, in whichever vocabulary the bundle speaks.
  *
@@ -240,7 +245,12 @@ function unsafeEventIdReason(eventId) {
  * listing and pass that to `gradePack` — the rule takes an account, never a
  * bundle, precisely so the transport can say things the map cannot.
  */
-export function accountDisclosure(bundle, content) {
+export function accountDisclosure(bundle, 
+// `SideContentMap`, which is what `hasSideContent` and `sideContentKeys`
+// below already take: an entry holding a string that is not hex IS an entry,
+// and typing it out of this signature made the one map a caller builds
+// unusable here (proof#147). A widening, so no caller moves.
+content) {
     const expected = [];
     const present = [];
     const missing = [];
@@ -288,7 +298,13 @@ export function signedLeafCount(checkpoint) {
     if (typeof hex !== "string" || hex.length === 0)
         return null;
     try {
-        const record = JSON.parse(new TextDecoder().decode(hexToBytes(hex)));
+        // `jcsParse`, matching `signed_leaf_count` in `src/sanning_proof/grading.py`.
+        // The pair used to agree by pointing two LENIENT decoders at one input, and
+        // that held for invalid UTF-8 and nowhere else: `TextDecoder` EATS a
+        // leading byte-order mark where Python's `errors="replace"` keeps it, so
+        // `BOM + JCS(checkpoint)` yielded a signed leaf count here and unreadable
+        // there, and that count decides a completeness note (proof#140 gate 5).
+        const record = jcsParse(hexToBytes(hex));
         const n = record?.event?.leaf_count;
         return Number.isInteger(n) ? n : null;
     }
@@ -342,8 +358,32 @@ export function completenessNotes(bundle) {
  * Every reason this pack is not `verified`, in the order a reader should hear
  * them: what is missing from the whole, then what is missing from the parts.
  */
-export function gradeCauses(account, notes) {
+export function gradeCauses(account, notes, declaration) {
     const causes = [];
+    // What the pack CLAIMED to hold comes first, because it frames everything
+    // below it: a reader told "four records are missing from what this pack says
+    // it contains" reads the per-record findings differently. Every deviation
+    // gets its own cause (one defect, one line), so a pack that deviates in
+    // four ways can never be reported as one vague shortfall.
+    for (const deviation of declaration?.deviations ?? []) {
+        causes.push({
+            kind: "declaration-deviation",
+            deviation: deviation.kind,
+            ...(deviation.eventId === undefined ? {} : { firstEventId: deviation.eventId }),
+            reason: renderDeviation(deviation),
+        });
+    }
+    // Then what the pack and the UNSIGNED content beside it do not agree on
+    // (proof#147). A cause, so the pack cannot read clean over it; NOT a
+    // deviation, so it never reaches `failed`.
+    for (const finding of declaration?.contentFindings ?? []) {
+        causes.push({
+            kind: "declaration-content-dependent",
+            deviation: finding.kind,
+            ...(finding.eventId === undefined ? {} : { firstEventId: finding.eventId }),
+            reason: renderContentFinding(finding),
+        });
+    }
     for (const note of notes) {
         if (note.kind === "omitted") {
             causes.push({
@@ -434,23 +474,77 @@ function passThrough(status) {
  * (§5.1: undetermined, not failed), and a proven mismatch is never softened
  * into absence. The last branch passes the kernel's headline through unchanged:
  * this rule DOWNGRADES a verdict, it never invents one.
+ *
+ * ── the declaration (optional fourth argument) ──────────────────────────────
+ *
+ * `declaration` is what `checkDeclaration` in `./declaration.ts` made of the
+ * pack's own signed statement of what it holds (`evidence-bundle.md` §5.4). A
+ * deviation from it is a PROVEN mismatch between what the pack claimed and
+ * what it carries, so it FAILS the pack and each deviation becomes its own
+ * cause. It must never soften into absence: that is how a trimmed hand-over
+ * reads as an innocent gap.
+ *
+ * A check that came back `partial` splits in THREE (proof#147), and the first
+ * of the three is not about the declaration's readability at all. The other
+ * two split on whether the body carried a `declaration` member.
+ *
+ *   content-dependent      the pack and the UNSIGNED content beside it do not
+ *                          line up (proof#147). Each finding is its own cause
+ *                          and the pack is `incomplete`. It must never reach
+ *                          `failed`: whoever assembles a case fills in the
+ *                          side-content map, so an accuser holding an intact
+ *                          pack could otherwise put its holder into `failed`
+ *                          with no key at all, by dropping one file or adding
+ *                          one. `failed` is left to what a signature covers.
+ *   no declaration at all   nothing moves. Every pack built before §5.4 is
+ *                           this case, and re-grading them would move pinned
+ *                           exit codes for artifacts already in customers'
+ *                           hands.
+ *   present and unreadable  the pack is `incomplete`. `declaration_version` is
+ *                           chosen by the same party that assembles the pack
+ *                           and has no accept-set, so a holder who trims a
+ *                           record and then writes one unreadable field can
+ *                           re-seal the pack with its own key and hand a
+ *                           reader a clean verdict over evidence of the trim
+ *                           sitting inside the signed body. UNKNOWN is the
+ *                           only honest answer to a claim the reader cannot
+ *                           read, and it adds no cause: `PackGrade.declaration`
+ *                           says why.
+ *
+ * `verified` adds nothing and moves nothing.
+ *
+ * Omitting the argument entirely is the pre-§5.4 behavior, unchanged, and
+ * `PackGrade.declaration` is then absent.
  */
-export function gradePack(result, account, notes) {
+export function gradePack(result, account, notes, declaration) {
     const events = Array.isArray(result?.events) ? result.events : [];
     const recordsVerified = events.filter((e) => e.ok && e.contentOk === true).length;
     const recordsFailed = events.filter((e) => e.ok === false || e.contentOk === false).length;
     const recordsUndetermined = events.length - recordsVerified - recordsFailed;
-    const causes = gradeCauses(account, notes);
+    const causes = gradeCauses(account, notes, declaration);
     let verdict;
     if (result?.status === "malformed")
         verdict = "malformed";
     else if (result?.status === "failed" || recordsFailed > 0)
         verdict = "failed";
+    else if (declaration?.verdict === "failed")
+        verdict = "failed";
     else if (recordsUndetermined > 0 || causes.length > 0)
         verdict = "incomplete";
+    else if (declaration?.present === true && declaration.verdict === "partial")
+        verdict = "incomplete";
     else
         verdict = passThrough(result?.status);
-    return { verdict, recordsVerified, recordsFailed, recordsUndetermined, causes };
+    const grade = {
+        verdict,
+        recordsVerified,
+        recordsFailed,
+        recordsUndetermined,
+        causes,
+    };
+    if (declaration != null)
+        grade.declaration = declaration.verdict;
+    return grade;
 }
 // ---- Presentation (optional) -------------------------------------------------
 /**
@@ -484,5 +578,17 @@ export function renderCause(cause, subject = "this pack") {
         case "unaccounted-disclosure":
             return (`${cause.count} disclosed file(s) are not accounted for by any record in this bundle ` +
                 `(first: ${cause.firstEventId})`);
+        // Rendered once, by `renderDeviation` in `./declaration.ts`, and carried
+        // here on `reason`. Re-deriving the sentence from the cause fields would
+        // put the declaration's wording in two places, and one of the two would be
+        // edited alone.
+        case "declaration-deviation":
+            return `this pack deviates from its own declaration: ${cause.reason}`;
+        case "declaration-content-dependent":
+            // Named as what the reader could not establish, never as what the
+            // holder did: the bytes it turns on are unsigned and whoever assembled
+            // the case chose them (proof#147).
+            return (`${subject} and the unsigned content handed in beside it do not line up: ` +
+                `${cause.reason}`);
     }
 }

package/dist/handoff.d.ts

@@ -0,0 +1,209 @@
+export declare const CANDIDATE_NAMESPACE = "handoff.";
+export declare const DEFINED_EVENT_TYPES: readonly ["handoff.sent", "handoff.received"];
+/**
+ * The finding a record that is not a hand-off record at all reads with.
+ *
+ * A FINDING and not a verdict: the ratified verdict words are closed
+ * (anchor#188) and this reading names an outcome beside one, exactly as
+ * `counterpart_absent`, `counterpart_ambiguous` and `malformed_record` do. It
+ * exists because 4.1 had a SILENT branch, and a rule with a silent branch is a
+ * rule the party being audited steers into (proof#136). A record TRYING to be
+ * a hand-off and getting it wrong reads `malformed`; a record that is not a
+ * hand-off at all reads this. Both are readings. Neither is silence.
+ */
+export declare const NOT_A_HANDOFF_FINDING = "not_a_handoff_record";
+/**
+ * An envelope `public_key` as a KEY rather than as a string: the 32 key bytes
+ * written as lowercase hex, or `null` where the value is not 64 characters of
+ * hex and so names no key this reading can compare.
+ *
+ * Case is the whole point: §2 states lowercase as a PRODUCER convention, the
+ * envelope layer accepts either case in every kernel, and the party being
+ * audited is the producer (proof#133 adversarial gate, ruling 1). Nothing
+ * wider is folded: whitespace inside the value is not stripped, because
+ * Python's `bytes.fromhex` skips ASCII whitespace and this kernel's charset
+ * check does not, a live divergence at the ENVELOPE layer and a separate
+ * founder call (proof#135). A reading rule that silently repaired it would
+ * hide it.
+ */
+export declare function normalizedSigningKey(value: unknown): string | null;
+/**
+ * Whether two envelope keys are the SAME KEY. Two values that name a key are
+ * equal when their key bytes are equal.
+ *
+ * Where either side names no key, the question cannot be answered from key
+ * bytes and the answer is the conservative one: the two are reported as one
+ * key, so the pair reads `failed[self_handoff]` rather than clean. Exact
+ * string equality was the answer here and it was the wrong way round: one key
+ * that signed both ends, spelled `abcd...` on one envelope and `abcd ...` on
+ * the other, is one party, and string equality called it two and read the
+ * self-hand-off `verified` (proof#133 fourth hunt, finding 1). A record whose
+ * own envelope key this reading cannot read is `malformed` under
+ * `recordIsMalformed` and a formed pair reaches `malformed` before it reaches
+ * this line, so the two rules are belt and braces rather than one rule stated
+ * twice.
+ */
+export declare function sameSigningKey(left: unknown, right: unknown): boolean;
+export type HandoffVerdict = "verified" | "failed" | "malformed";
+export interface HandoffRecord {
+    event_type?: unknown;
+    event?: unknown;
+    context?: unknown;
+    metadata?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * One hand-off record as a reader holds it: the committed record, plus the
+ * `public_key` of the envelope that carries it. The key comes from the ENVELOPE
+ * and never from the record, which is the whole point of the amended rule.
+ *
+ * PRECONDITION: THE ENVELOPE MUST ALREADY HAVE VERIFIED. "Unforgeable" is a
+ * property of a VERIFIED envelope and of nothing else. The key on an envelope
+ * whose signature has not been checked is an assertion like any other, and
+ * every reading in this module is then worth exactly as much as that
+ * assertion. A reader builds a `HeldRecord` only from an envelope that
+ * `verifyEnvelope` returned `ok` for, bound to the canonical bytes of this
+ * record. Nothing in this module can check that for itself, which is why it is
+ * stated here (proof#133 adversarial gate, ruling 3), and why candidacy and
+ * the self-hand-off check read `normalizedSigningKey(publicKey)` rather than
+ * the spelling the audited party chose.
+ */
+export interface HeldRecord {
+    publicKey: string;
+    record: HandoffRecord;
+    ref: string;
+}
+/**
+ * Whether a reader reads this record as a hand-off record at all.
+ *
+ * §4.1 says a reader reads EVERY hand-off record it holds, and an exact
+ * `handoff.` prefix did not deliver that: `HANDOFF.RECEIVED`,
+ * `sanning.handoff.received`, `handoff-received` and a non-string `event_type`
+ * all vanished from the reading entirely, not even as malformed, so a receipt
+ * typed one character outside the prefix was never read and, beside a clean decoy,
+ * published `verified` over proven tampering (proof#133 adversarial gate,
+ * ruling 2).
+ *
+ * The rule is checkable rather than a judgement, and it is exactly two
+ * clauses. The FIRST is the one the adversary cannot evade: the record's
+ * `event` carries `counterparty_public_key`, the field §4.1 defines and no
+ * other section does, WHATEVER its `event_type` says. The second keeps a
+ * record that omits the field in scope: an `event_type` that is a string whose
+ * folded form has `handoff` as one of its `.`-separated segments, which leaves
+ * `asset_missing` and the other families alone.
+ *
+ * The order is the fix, not decoration. Every earlier version of this test was
+ * an ALLOW-LIST OVER A NAME THE AUDITED PARTY WRITES, so each repair narrowed
+ * the class and the next spelling walked around it: an exact `handoff.` prefix
+ * fell to `HANDOFF.RECEIVED`, and the ASCII fold that replaced it fell to the
+ * `ff` ligature, full-width letters, a Cyrillic `a`, `hand-off`, `handoffs`, a
+ * zero-width space, a BOM and a non-breaking space, each of which left a
+ * tampered receipt with no reading at all beside a clean decoy (proof#133
+ * fourth hunt, finding 2). The structural field closes all of them in one rule
+ * rather than by chasing Unicode, because the attack needs the field: a
+ * receipt that drops `counterparty_public_key` says nothing about who it came
+ * from.
+ *
+ * Anything in scope that is not exactly `handoff.sent` or `handoff.received`
+ * is `malformed`, so a spelling is never a way out.
+ *
+ * THIS IS NO LONGER A GATE ON BEING READ (proof#136). Both clauses are written
+ * by the party being audited, and one code point on each put a record in scope
+ * by neither, which produced silence. `readHandoffs` reads every record it
+ * holds, and this test now decides only WHICH reading a record gets: in scope
+ * and wrong reads `malformed`, out of scope reads `NOT_A_HANDOFF_FINDING`. A
+ * respelling buys a different line rather than no line.
+ */
+export declare function isHandoffNamespace(held: HeldRecord): boolean;
+/**
+ * What one candidate graded to, kept beside the aggregate. 4.1 requires a
+ * reader to name the record and which check failed, and `malformed` outranks
+ * `failed`, so one junk record signed by the counterparty key would otherwise
+ * turn a named `message_hash` failure into a `malformed` with nothing named
+ * (proof#133 review, ruling 6).
+ */
+export interface CandidateReading {
+    ref: string;
+    verdict: HandoffVerdict;
+    failedChecks: string[];
+}
+export interface HandoffReading {
+    ref: string;
+    /** `null` where no pair formed: there is no verdict to give, and the finding says why. */
+    verdict: HandoffVerdict | null;
+    failedChecks: string[];
+    findings: string[];
+    /** Ordered, never filtered. */
+    candidates: string[];
+    /** One entry per candidate, in the same order, and nothing left out of it. */
+    candidateReadings: CandidateReading[];
+}
+/**
+ * A record missing a REQUIRED field of its own type, or carrying one that is
+ * not the type §4.1 states, is malformed and fails. Stated as a rule because
+ * §4.1 had none: a pair where both sides omitted `message_hash` compared absent
+ * to absent, found them equal, and graded intact (proof#132).
+ *
+ * A record whose ENVELOPE key this reading cannot read is malformed too, and
+ * that one is a repair rather than an omission. The rule used to be "a value
+ * that is not 64 characters of hex names no key and matches nothing", so such a
+ * record dropped out of candidacy in silence and the subject read
+ * `counterpart_absent`, which §4.1 obliges a reader to call innocent. Nine
+ * whitespace spellings of a real key produce a VERIFIED envelope in exactly
+ * that state in the Python kernel, because `bytes.fromhex` skips ASCII
+ * whitespace, which reopened the whole of the first attack through the repair
+ * rather than around it (proof#133 fourth hunt, finding 1). A record a reader
+ * HOLDS, whose own key it cannot read, is a defect in the record and not an
+ * absence of one. This holds whatever the envelope layer decides about its hex
+ * charset (proof#135).
+ */
+export declare function recordIsMalformed(held: HeldRecord): boolean;
+/**
+ * Read ONE record against everything the reader holds.
+ *
+ * Every record gets a reading, and the two findings are how the distinction a
+ * reader needs survives (proof#136): a record that is not a hand-off record at
+ * all reads `NOT_A_HANDOFF_FINDING` with no verdict, and a record 4.1 DOES
+ * govern and that is wrong reads `malformed`. The scope test lives HERE and
+ * not in `readHandoffs`, so the two entry points cannot answer differently
+ * about one record.
+ */
+export declare function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): HandoffReading;
+/**
+ * EVERY record the reader holds gets a reading, in the order given.
+ *
+ * This function does not filter, and the branch that used to decide whether a
+ * record was read at all is gone (proof#136, ratified by Phil 2026-09-22).
+ * Scope was two clauses, an exact test for the key name
+ * `counterparty_public_key` and an ASCII fold of `event_type`, and both
+ * operands are written by the party being audited: one code point on each put
+ * a record in scope by NEITHER route, so it had no reading at all and the pile
+ * read clean. Five repairs narrowed which values reached that silent branch
+ * and five hunts found a value outside it, so the branch is removed rather
+ * than narrowed again.
+ *
+ * The distinction a reader needs survives as two findings rather than as a
+ * reading and a silence: a record TRYING to be a hand-off and getting it wrong
+ * reads `malformed` with `malformed_record`, and a record that is not a
+ * hand-off record at all reads `NOT_A_HANDOFF_FINDING` with no verdict.
+ * `isHandoffNamespace` decides which of the two, in `readHandoff`, and no
+ * longer whether a record is read.
+ *
+ * THE COST, stated rather than left to be found: a reader given a mixed pile
+ * produces a line per record, including for records that have nothing to do
+ * with hand-offs. 4.1 says so too.
+ */
+export declare function readHandoffs(held: readonly HeldRecord[]): HandoffReading[];
+/**
+ * Whether this record is a conformant hand-off record of 4.1: it is read as a
+ * hand-off record at all (`isHandoffNamespace`) and it is not `malformed`
+ * (`recordIsMalformed`), which between them mean it is exactly a
+ * `handoff.sent` or a `handoff.received` carrying every REQUIRED field of its
+ * own type, under an envelope key this reading can read.
+ *
+ * `./declaration.ts` reads this for evidence-bundle.md 5.4: a claimed
+ * `sent_event_id` or `received_event_id` naming a record that is not one of
+ * these is a DEVIATION, so a record cannot be unreadable at the record layer
+ * and usable at the pack layer at the same time (proof#136).
+ */
+export declare function isConformantHandoffRecord(held: HeldRecord): boolean;