@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/forms/index.d.ts

@@ -1,333 +1,59 @@
-import { PDFForm } from 'pdf-lib';
-
 /**
- * The blank a form is filled from — embedded, pinned, and never fetched at
- * fill time.
- *
- * A renderer that downloads its own blank works on a developer laptop and
- * fails in both places these products actually run: a Cloudflare Worker has no
- * business making an outbound call mid-request, and a sandbox container's
- * egress proxy refuses the agencies' own hosts (measured on tax-agent:
- * `www.irs.gov` CONNECT tunnel 403 while pypi and npm returned 200). A
- * form-filler that cannot reach its blank does not fail loudly — it degrades
- * into an agent describing the form in prose, which is the exact behaviour
- * this module exists to end.
- *
- * Pinning the bytes by digest also pins the artifact: a filing made against
- * the 2025 revision is reproducible from the committed bytes, and an agency
- * revision shows up as a diff of the recorded checksum instead of silently
- * changing under a live URL.
- */
-/** A blank form's bytes, base64-encoded, with the provenance to check them. */
-interface FormBlank {
-    /** Base64 of the PDF exactly as the agency published it. */
-    base64: string;
-    /** SHA-256 of the decoded bytes, lowercase hex. */
-    sha256: string;
-    /** Where the bytes came from. Provenance for a reviewer, not a fetch target. */
-    sourceUrl: string;
-    /** Decoded length in bytes. A cheap first check that the base64 is intact. */
-    byteLength: number;
-}
-/**
- * Decode a blank once per isolate.
- *
- * Keyed on the blank OBJECT rather than a module-level singleton, because a
- * product carries several forms and a single cached slot would serve one
- * form's bytes for another's fill — a failure that produces a plausible PDF
- * and no error at all.
- */
-declare function decodeFormBlank(blank: FormBlank): Uint8Array;
-/** Lowercase-hex SHA-256 of a byte range. */
-declare function sha256Hex(bytes: Uint8Array): Promise<string>;
-/**
- * Prove the embedded bytes are the file the registry was derived from.
- *
- * Run this in a test, not on the fill path: a registry is only meaningful
- * against the exact revision it was derived from, and a blank swapped for a
- * newer revision moves every widget without changing a single field name.
- */
-declare function assertFormBlankIntegrity(blank: FormBlank): Promise<void>;
-
-/**
- * The slot → widget registry: the one place a form filler can be wrong
- * invisibly, and the one place a language model is never allowed to write.
- *
- * WHY THE MODEL NEVER NAMES A WIDGET
- *
- * An agency PDF's widget names carry no meaning a reader can check —
- * `topmostSubform[0].Page2[0].f2_06[0]` on an IRS form, `registered2` on a
- * Texas SOS form. A model asked for one produces a plausible string, and the
- * natural audit — read the field back by the name you just wrote — PASSES
- * REGARDLESS, because it re-reads the invention rather than checking it.
- * Measured on tax-agent: three values written to model-chosen widgets landed
- * in "Combat zone" and the date boxes, and the audit reported 3 passed /
- * 0 failed.
- *
- * So the model supplies SEMANTIC SLOTS — a form line, a named box — and the
- * platform owns the slot → widget mapping. A misplaced figure stops being an
- * invention that survives review and becomes something that cannot be
- * expressed at all.
- *
- * WHY A SLOT CARRIES A LABEL, AND WHY THE LABEL DECLARES ITS BASIS
- *
- * A registry is still just a table, and a hand-typed table drifts (tax-agent's
- * form catalog carried wrong page counts for 7 of 17 forms). So every slot
- * states the label it believes it is aiming at, and states where that belief
- * came from:
- *
- *  - `labelBasis: 'widget'` — the label must match the widget's OWN `/TU`
- *    accessibility text inside the PDF. `checkRegistryAgainstBlank` re-checks
- *    it against the bytes, so a mis-aimed slot fails a test rather than
- *    quietly printing in the wrong box. Every one of Texas Form 205's 64
- *    widgets carries `/TU`, so its whole registry can be checked this way.
- *  - `labelBasis: 'derived'` — the label came from somewhere else (an XFA
- *    template, a published instruction sheet, a human reading the form) and
- *    CANNOT be re-checked against the widget. It is evidence for a reviewer,
- *    never proof. Measured on IRS f1040: 0 of 199 widgets carry `/TU` or
- *    `/Alt`, so its labels can only ever be derived.
- *
- * Declaring the basis is the point. A guess presented as truth is how a second
- * self-confirming artifact gets built on top of the first one.
- */
-
-/** What kind of widget a slot writes to. */
-type FormSlotKind = 'text' | 'checkbox';
-/** How a slot's text value is rendered into the box. */
-type FormSlotFormat = 'text' | 'currency';
-/** Where a slot's `label` came from, and therefore what it can prove. */
-type FormLabelBasis = 'widget' | 'derived';
-/** One semantic slot: what a caller supplies, and where the platform puts it. */
-interface FormSlot {
-    /** The name a caller (and a model) uses: `15`, `entity_name`, `agent_is_org`. */
-    slot: string;
-    /**
-     * The AcroForm widget path(s) this slot writes.
-     *
-     * A LIST because one semantic value legitimately occupies several boxes: IRS
-     * Form 1040 states adjusted gross income twice, at the foot of page 1 and
-     * the head of page 2, so page 2's arithmetic stands alone. Writing only one
-     * of them leaves "subtract line 14 from line 11b" pointing at an empty box.
-     */
-    fields: readonly string[];
-    kind: FormSlotKind;
-    /** How the value is rendered. Ignored for `checkbox`. Default `'text'`. */
-    format?: FormSlotFormat;
-    /** What this slot is, in the form's own words. */
-    label: string;
-    /** Whether `label` is checkable against the PDF, or merely recorded. */
-    labelBasis: FormLabelBasis;
-}
-/** A form's complete slot table, pinned to the revision it was derived from. */
-interface FormRegistry {
-    /** Stable id for the form: `us-irs-1040`, `us-tx-sos-205`. */
-    form: string;
-    /** The agency's own revision marker: `2025`, `Rev. 12-21`. */
-    revision: string;
-    slots: readonly FormSlot[];
-}
-/** Why a registry does not match the blank it claims to describe. */
-type RegistryProblemCode = 'no_slots' | 'no_fields' | 'missing_field' | 'wrong_kind' | 'label_mismatch' | 'duplicate_field' | 'duplicate_slot';
-interface RegistryProblem {
-    slot: string;
-    field?: string;
-    code: RegistryProblemCode;
-    detail: string;
-}
-interface RegistryCheckResult {
-    ok: boolean;
-    /** Widgets actually compared against the PDF. Zero means nothing was proven. */
-    checked: number;
-    /** Slots whose label was compared against the widget's own `/TU`. */
-    labelsChecked: number;
-    problems: RegistryProblem[];
-}
-/** The `/TU` accessibility text a widget carries, if any. */
-declare function widgetLabel(form: PDFForm, field: string): Promise<string | undefined>;
-/**
- * Check a registry against the blank it claims to describe.
- *
- * This is the placement check. It runs in a test or in CI, never on the fill
- * path, and it is the ONLY thing that can catch a slot aimed at the wrong box
- * — reading a value back after writing it cannot, because it re-reads the same
- * name it wrote.
- *
- * It fails on ABSENCE, deliberately. tax-agent shipped an audit that silently
- * skipped an expected field the PDF did not expose, so a fill against entirely
- * wrong paths reported `passed=0 failed=0`. Here an empty registry, a slot
- * with no fields, and a field the PDF does not expose are each a problem with
- * a name, and `checked` is reported so a caller can see how much was actually
- * proven rather than trusting a bare `ok: true`.
- */
-declare function checkRegistryAgainstBlank(args: {
-    /** The blank's bytes. Decode a `FormBlank` with `decodeFormBlank` first. */
-    pdf: Uint8Array;
-    registry: FormRegistry;
-}): Promise<RegistryCheckResult>;
-
-/**
- * Fill a real agency PDF from a slot → value map.
- *
- * Mechanically this is `pdf-lib` writing an AcroForm: TypeScript, no
- * container, no Python, no network. That matters because it is the only shape
- * that runs everywhere these products run — a Cloudflare Worker (where 100% of
- * tax-agent's production work products were produced, with no sandbox at all)
- * and a sandbox container whose egress proxy refuses the agency's own host.
- *
- * The invariant it enforces is in `registry.ts`: the caller supplies SEMANTIC
- * SLOTS and never a widget name. Two consequences show up here.
- *
- * NOTHING IS SILENT. Every slot ends in `filled` or in `unfilled` with a code
- * and a reason. A value the caller supplied that never reached the page means
- * the document and the data disagree, which is the one thing a reviewer must
- * not have to discover by eye. That includes a registry naming a widget the
- * PDF does not expose: it is reported per-slot rather than crashing the render
- * or — worse — being skipped, which is how tax-agent once audited a fill
- * against entirely wrong paths as `passed=0 failed=0`.
- *
- * NO ON-STATE IS EVER AUTHORED. A checkbox's "on" name is a property of the
- * PDF and frequently a hex-escaped sentence: Texas Form 205's seven boxes are
- * `is#20an#20organization`, `initially#20has#20#20managers` (note the double
- * space), and four more like them. A caller that types one of those strings is
- * authoring something it cannot check, so a checkbox slot takes a BOOLEAN and
- * the widget's own on-value is read out of the file. The escaped spelling is
- * not handled — it is unrepresentable.
- */
-
-/** One widget the fill actually wrote. */
-interface FilledWidget {
-    slot: string;
-    field: string;
-    kind: FormSlot['kind'];
-    /** The value as the caller supplied it, before formatting. */
-    value: unknown;
-    /** Exactly the text placed in the box. Absent for a checkbox. */
-    text?: string;
-    /** Whether a checkbox was ticked. Absent for a text field. */
-    checked?: boolean;
-    /** The widget's OWN on-state, decoded — read from the PDF, never authored. */
-    onState?: string;
-}
-/** Why a supplied value did not reach the page. */
-type UnfilledCode = 'unknown_slot' | 'missing_field' | 'wrong_kind' | 'not_a_number' | 'not_a_boolean' | 'unformattable';
-interface UnfilledSlot {
-    slot: string;
-    field?: string;
-    value: unknown;
-    code: UnfilledCode;
-    reason: string;
-}
-interface FillFormResult {
-    bytes: Uint8Array;
-    filled: FilledWidget[];
-    unfilled: UnfilledSlot[];
-    form: string;
-    revision: string;
-}
-interface FillFormOptions {
-    /** The blank's bytes. Decode a `FormBlank` with `decodeFormBlank` first. */
-    pdf: Uint8Array;
-    registry: FormRegistry;
-    /** slot name → value. Keys the registry does not know are reported, not dropped. */
-    values: Record<string, unknown>;
-    /**
-     * Override how a text value becomes box text. Return `undefined` to fall
-     * through to the built-in formatting for the slot's `format`.
-     */
-    formatText?: (value: unknown, slot: FormSlot) => string | undefined;
-}
-/**
- * Format a figure the way a US agency form prints it: grouped thousands, two
- * decimals, negatives in parentheses.
- *
- * Two decimals rather than whole dollars because the caller's data carries
- * cents and a reviewer compares the document against that data — rounding here
- * would manufacture a disagreement between the two on every line with cents.
- */
-declare function formatFormCurrency(value: number): string;
-/** A number, or a number written the way a form prints one (`$141,318.74`). */
-declare function parseFormAmount(value: unknown): number | undefined;
-/**
- * A checkbox takes a boolean and nothing else.
- *
- * Strict on purpose. Accepting a truthy string would accept the widget's own
- * escaped on-state (`'is#20an#20organization'`) as "true", which is exactly
- * the authored-on-state this module refuses — and it would accept `'no'` as
- * true, silently ticking a box the caller meant to leave clear.
- */
-declare function parseFormBoolean(value: unknown): boolean | undefined;
-/**
- * Write a value map onto a blank, returning the bytes plus the exact
- * widget-by-widget account of what was and was not placed.
- */
-declare function fillPdfForm(options: FillFormOptions): Promise<FillFormResult>;
-/**
- * What to tell the agent after a fill.
- *
- * Names the values that did NOT reach the page. Those are exactly the cases
- * where the document and the data disagree, and the agent is the only party
- * that can resolve it — returning a bare "done" hands a reviewer a form
- * missing values the data claims are on it.
- */
-declare function describeFormFill(result: FillFormResult): string;
-
-/**
- * Read a filled form back and say, slot by slot, whether the document agrees
- * with the data it was built from.
- *
- * WHAT THIS PROVES, AND WHAT IT CANNOT
- *
- * This proves the WRITE LANDED: the value reached a real widget, that widget
- * exists in the produced file, and it holds the text or tick the data claims.
- * It does NOT prove PLACEMENT — that the widget is the right box on the page —
- * because it resolves the same field names the fill used. Reading a value back
- * by the name you just wrote passes even when the name was invented; measured
- * on tax-agent, an audit of that shape reported 3 passed / 0 failed for three
- * figures sitting in "Combat zone" and the date boxes.
- *
- * Placement is proven by `checkRegistryAgainstBlank`, which compares each
- * slot's claimed label against the widget's own `/TU` text inside the PDF.
- * The two checks are complements, and a product that runs only this one has
- * the audit that already failed once. That is stated here rather than in a
- * commit message because a future caller will otherwise reach for the
- * convenient half.
- *
- * FAILS ON ABSENCE. A registry field the produced PDF does not expose is
- * `missing_field`, and an empty `expected` map is `ok: false` — the
- * `passed=0 failed=0` verdict is the exact shape of the bug this replaces.
- */
-
-type SlotVerdict = 'ok' | 'unknown_slot' | 'missing_field' | 'wrong_kind' | 'not_written' | 'mismatch';
-/** What the slot's `label` is worth, checked against the produced file. */
-type LabelVerdict = 'matches_widget' | 'label_mismatch' | 'derived_unchecked' | 'no_widget_label';
-interface SlotVerification {
-    slot: string;
-    field?: string;
-    verdict: SlotVerdict;
-    /** What the data says the box should hold. */
-    expected?: string;
-    /** What the box actually holds, read out of the produced bytes. */
-    actual?: string;
-    labelVerdict?: LabelVerdict;
-    label?: string;
-}
-interface VerifyFormResult {
-    ok: boolean;
-    /** Widgets actually read back. Zero means nothing was proven. */
-    verified: number;
-    slots: SlotVerification[];
-}
-/**
- * Verify a filled form against the value map it was filled from.
- *
- * `expected` is the SAME shape passed to `fillPdfForm` — deliberately, so a
- * caller cannot verify against a convenient restatement of what it wrote.
- */
-declare function verifyFilledForm(args: {
-    /** The PRODUCED bytes, not the blank. */
-    pdf: Uint8Array;
-    registry: FormRegistry;
-    expected: Record<string, unknown>;
-}): Promise<VerifyFormResult>;
-
-export { type FillFormOptions, type FillFormResult, type FilledWidget, type FormBlank, type FormLabelBasis, type FormRegistry, type FormSlot, type FormSlotFormat, type FormSlotKind, type LabelVerdict, type RegistryCheckResult, type RegistryProblem, type RegistryProblemCode, type SlotVerdict, type SlotVerification, type UnfilledCode, type UnfilledSlot, type VerifyFormResult, assertFormBlankIntegrity, checkRegistryAgainstBlank, decodeFormBlank, describeFormFill, fillPdfForm, formatFormCurrency, parseFormAmount, parseFormBoolean, sha256Hex, verifyFilledForm, widgetLabel };
+ * `/forms` — fill a real agency PDF from semantic slots.
+ *
+ * THE ONE INVARIANT: the model supplies semantic slots (a form line, a named
+ * box); the PLATFORM owns slot → widget. A widget name on an agency PDF
+ * (`topmostSubform[0].Page2[0].f2_06[0]`, `registered2`) carries no meaning a
+ * reader can check, so a model asked for one produces a plausible string — and
+ * the natural audit, reading the field back by the name you wrote, passes
+ * regardless because it re-reads the invention. Measured on tax-agent: three
+ * figures written to model-chosen widgets landed in "Combat zone" and the date
+ * boxes, audited 3 passed / 0 failed. Under this contract a misplaced value is
+ * not merely unlikely — it is unrepresentable.
+ *
+ * Adding a form is a REGISTRY ENTRY, not a code path:
+ *
+ * ```ts
+ * const blank: FormBlank = { base64, sha256, sourceUrl, byteLength }   // generated
+ * const registry: FormRegistry = {
+ *   form: 'us-tx-sos-205',
+ *   revision: 'Rev. 12-21',
+ *   slots: [
+ *     { slot: 'entity_name', fields: ['The name of the entity is:'], kind: 'text',
+ *       label: 'The name of the entity is:', labelBasis: 'widget' },
+ *     { slot: 'agent_is_organization', fields: ['registered'], kind: 'checkbox',
+ *       label: 'If the initial registered agent is an organization, …', labelBasis: 'widget' },
+ *   ],
+ * }
+ *
+ * const pdf = decodeFormBlank(blank)
+ * const filled = await fillPdfForm({ pdf, registry, values: { entity_name: 'BLUE MESA KITCHEN LLC' } })
+ * ```
+ *
+ * Two checks, and a product needs BOTH because they prove different things:
+ *
+ *  - `checkRegistryAgainstBlank` — PLACEMENT. Compares each slot's claimed
+ *    label against the widget's own `/TU` text inside the PDF. This is the
+ *    only check that can catch a slot aimed at the wrong box. Run it in CI.
+ *  - `verifyFilledForm` — TRANSPORT. Reads the produced bytes back and
+ *    confirms each value reached its widget. Fails on absence; an empty
+ *    expectation set is `ok: false`, because `passed=0 failed=0` is the bug.
+ *
+ * A slot whose label CANNOT be re-checked against the file says so
+ * (`labelBasis: 'derived'`) rather than presenting a guess as truth. Measured:
+ * IRS f1040 carries `/TU` on 0 of 199 widgets, so its labels come from the XFA
+ * template and are derived; every one of Texas Form 205's 64 widgets carries
+ * `/TU`, so its whole registry is checkable.
+ *
+ * DERIVING a registry is form-family specific and stays in the product — an
+ * IRS form's labels live in an XFA template, a Texas SOS form's live in `/TU`,
+ * a third agency's may live only on paper. This subpath owns the CONTRACT the
+ * derivation must satisfy, not the derivation.
+ *
+ * Server-only and opt-in: importing this subpath requires the otherwise
+ * optional `pdf-lib` peer, which is why it is isolated behind its own entry.
+ */
+export { assertFormBlankIntegrity, decodeFormBlank, sha256Hex, type FormBlank, } from './blank';
+export { checkRegistryAgainstBlank, widgetLabel, type FormLabelBasis, type FormRegistry, type FormSlot, type FormSlotFormat, type FormSlotKind, type RegistryCheckResult, type RegistryProblem, type RegistryProblemCode, } from './registry';
+export { describeFormFill, fillPdfForm, formatFormCurrency, parseFormAmount, parseFormBoolean, type FilledWidget, type FillFormOptions, type FillFormResult, type UnfilledCode, type UnfilledSlot, } from './fill';
+export { verifyFilledForm, type LabelVerdict, type SlotVerdict, type SlotVerification, type VerifyFormResult, } from './verify';

package/dist/forms/registry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The slot → widget registry: the one place a form filler can be wrong
+ * invisibly, and the one place a language model is never allowed to write.
+ *
+ * WHY THE MODEL NEVER NAMES A WIDGET
+ *
+ * An agency PDF's widget names carry no meaning a reader can check —
+ * `topmostSubform[0].Page2[0].f2_06[0]` on an IRS form, `registered2` on a
+ * Texas SOS form. A model asked for one produces a plausible string, and the
+ * natural audit — read the field back by the name you just wrote — PASSES
+ * REGARDLESS, because it re-reads the invention rather than checking it.
+ * Measured on tax-agent: three values written to model-chosen widgets landed
+ * in "Combat zone" and the date boxes, and the audit reported 3 passed /
+ * 0 failed.
+ *
+ * So the model supplies SEMANTIC SLOTS — a form line, a named box — and the
+ * platform owns the slot → widget mapping. A misplaced figure stops being an
+ * invention that survives review and becomes something that cannot be
+ * expressed at all.
+ *
+ * WHY A SLOT CARRIES A LABEL, AND WHY THE LABEL DECLARES ITS BASIS
+ *
+ * A registry is still just a table, and a hand-typed table drifts (tax-agent's
+ * form catalog carried wrong page counts for 7 of 17 forms). So every slot
+ * states the label it believes it is aiming at, and states where that belief
+ * came from:
+ *
+ *  - `labelBasis: 'widget'` — the label must match the widget's OWN `/TU`
+ *    accessibility text inside the PDF. `checkRegistryAgainstBlank` re-checks
+ *    it against the bytes, so a mis-aimed slot fails a test rather than
+ *    quietly printing in the wrong box. Every one of Texas Form 205's 64
+ *    widgets carries `/TU`, so its whole registry can be checked this way.
+ *  - `labelBasis: 'derived'` — the label came from somewhere else (an XFA
+ *    template, a published instruction sheet, a human reading the form) and
+ *    CANNOT be re-checked against the widget. It is evidence for a reviewer,
+ *    never proof. Measured on IRS f1040: 0 of 199 widgets carry `/TU` or
+ *    `/Alt`, so its labels can only ever be derived.
+ *
+ * Declaring the basis is the point. A guess presented as truth is how a second
+ * self-confirming artifact gets built on top of the first one.
+ */
+import type { PDFForm } from 'pdf-lib';
+/** What kind of widget a slot writes to. */
+export type FormSlotKind = 'text' | 'checkbox';
+/** How a slot's text value is rendered into the box. */
+export type FormSlotFormat = 'text' | 'currency';
+/** Where a slot's `label` came from, and therefore what it can prove. */
+export type FormLabelBasis = 'widget' | 'derived';
+/** One semantic slot: what a caller supplies, and where the platform puts it. */
+export interface FormSlot {
+    /** The name a caller (and a model) uses: `15`, `entity_name`, `agent_is_org`. */
+    slot: string;
+    /**
+     * The AcroForm widget path(s) this slot writes.
+     *
+     * A LIST because one semantic value legitimately occupies several boxes: IRS
+     * Form 1040 states adjusted gross income twice, at the foot of page 1 and
+     * the head of page 2, so page 2's arithmetic stands alone. Writing only one
+     * of them leaves "subtract line 14 from line 11b" pointing at an empty box.
+     */
+    fields: readonly string[];
+    kind: FormSlotKind;
+    /** How the value is rendered. Ignored for `checkbox`. Default `'text'`. */
+    format?: FormSlotFormat;
+    /** What this slot is, in the form's own words. */
+    label: string;
+    /** Whether `label` is checkable against the PDF, or merely recorded. */
+    labelBasis: FormLabelBasis;
+}
+/** A form's complete slot table, pinned to the revision it was derived from. */
+export interface FormRegistry {
+    /** Stable id for the form: `us-irs-1040`, `us-tx-sos-205`. */
+    form: string;
+    /** The agency's own revision marker: `2025`, `Rev. 12-21`. */
+    revision: string;
+    slots: readonly FormSlot[];
+}
+/** Why a registry does not match the blank it claims to describe. */
+export type RegistryProblemCode = 'no_slots' | 'no_fields' | 'missing_field' | 'wrong_kind' | 'label_mismatch' | 'duplicate_field' | 'duplicate_slot';
+export interface RegistryProblem {
+    slot: string;
+    field?: string;
+    code: RegistryProblemCode;
+    detail: string;
+}
+export interface RegistryCheckResult {
+    ok: boolean;
+    /** Widgets actually compared against the PDF. Zero means nothing was proven. */
+    checked: number;
+    /** Slots whose label was compared against the widget's own `/TU`. */
+    labelsChecked: number;
+    problems: RegistryProblem[];
+}
+/** The `/TU` accessibility text a widget carries, if any. */
+export declare function widgetLabel(form: PDFForm, field: string): Promise<string | undefined>;
+/**
+ * Check a registry against the blank it claims to describe.
+ *
+ * This is the placement check. It runs in a test or in CI, never on the fill
+ * path, and it is the ONLY thing that can catch a slot aimed at the wrong box
+ * — reading a value back after writing it cannot, because it re-reads the same
+ * name it wrote.
+ *
+ * It fails on ABSENCE, deliberately. tax-agent shipped an audit that silently
+ * skipped an expected field the PDF did not expose, so a fill against entirely
+ * wrong paths reported `passed=0 failed=0`. Here an empty registry, a slot
+ * with no fields, and a field the PDF does not expose are each a problem with
+ * a name, and `checked` is reported so a caller can see how much was actually
+ * proven rather than trusting a bare `ok: true`.
+ */
+export declare function checkRegistryAgainstBlank(args: {
+    /** The blank's bytes. Decode a `FormBlank` with `decodeFormBlank` first. */
+    pdf: Uint8Array;
+    registry: FormRegistry;
+}): Promise<RegistryCheckResult>;

package/dist/forms/verify.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Read a filled form back and say, slot by slot, whether the document agrees
+ * with the data it was built from.
+ *
+ * WHAT THIS PROVES, AND WHAT IT CANNOT
+ *
+ * This proves the WRITE LANDED: the value reached a real widget, that widget
+ * exists in the produced file, and it holds the text or tick the data claims.
+ * It does NOT prove PLACEMENT — that the widget is the right box on the page —
+ * because it resolves the same field names the fill used. Reading a value back
+ * by the name you just wrote passes even when the name was invented; measured
+ * on tax-agent, an audit of that shape reported 3 passed / 0 failed for three
+ * figures sitting in "Combat zone" and the date boxes.
+ *
+ * Placement is proven by `checkRegistryAgainstBlank`, which compares each
+ * slot's claimed label against the widget's own `/TU` text inside the PDF.
+ * The two checks are complements, and a product that runs only this one has
+ * the audit that already failed once. That is stated here rather than in a
+ * commit message because a future caller will otherwise reach for the
+ * convenient half.
+ *
+ * FAILS ON ABSENCE. A registry field the produced PDF does not expose is
+ * `missing_field`, and an empty `expected` map is `ok: false` — the
+ * `passed=0 failed=0` verdict is the exact shape of the bug this replaces.
+ */
+import { type FormRegistry } from './registry';
+export type SlotVerdict = 'ok' | 'unknown_slot' | 'missing_field' | 'wrong_kind' | 'not_written' | 'mismatch';
+/** What the slot's `label` is worth, checked against the produced file. */
+export type LabelVerdict = 'matches_widget' | 'label_mismatch' | 'derived_unchecked' | 'no_widget_label';
+export interface SlotVerification {
+    slot: string;
+    field?: string;
+    verdict: SlotVerdict;
+    /** What the data says the box should hold. */
+    expected?: string;
+    /** What the box actually holds, read out of the produced bytes. */
+    actual?: string;
+    labelVerdict?: LabelVerdict;
+    label?: string;
+}
+export interface VerifyFormResult {
+    ok: boolean;
+    /** Widgets actually read back. Zero means nothing was proven. */
+    verified: number;
+    slots: SlotVerification[];
+}
+/**
+ * Verify a filled form against the value map it was filled from.
+ *
+ * `expected` is the SAME shape passed to `fillPdfForm` — deliberately, so a
+ * caller cannot verify against a convenient restatement of what it wrote.
+ */
+export declare function verifyFilledForm(args: {
+    /** The PRODUCED bytes, not the blank. */
+    pdf: Uint8Array;
+    registry: FormRegistry;
+    expected: Record<string, unknown>;
+}): Promise<VerifyFormResult>;