@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/documents/zip.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The slice of PKZIP an OOXML package needs: read the central directory, then
+ * inflate one named entry.
+ *
+ * Why not a zip library: DOCX text extraction is the only reason this module
+ * needs a zip, and the runtime already supplies the hard part —
+ * `DecompressionStream('deflate-raw')` is a standard API present in workerd
+ * and in Node, so the whole reader is header arithmetic plus a stream. Pulling
+ * a zip package in would put ten transitive Node-shaped dependencies into every
+ * consumer's Worker bundle to avoid ~120 lines.
+ *
+ * The CENTRAL DIRECTORY is the source of truth, not the local headers: an
+ * archive written with data descriptors (streamed output) carries zeros for
+ * the sizes in its local headers, and reading those is the classic way a
+ * hand-rolled zip reader silently returns nothing.
+ */
+export type ZipOutcome<T> = {
+    succeeded: true;
+    value: T;
+} | {
+    succeeded: false;
+    error: string;
+};
+export interface ZipEntry {
+    readonly name: string;
+    readonly compressionMethod: number;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly localHeaderOffset: number;
+    readonly encrypted: boolean;
+}
+/** Read every central-directory entry. Names are decoded as UTF-8, which is
+ *  what OOXML producers write (general-purpose bit 11). */
+export declare function readZipDirectory(bytes: Uint8Array): ZipOutcome<ZipEntry[]>;
+/**
+ * Ceiling on what ONE entry may expand to. A deflate stream reaches ~1000:1 on
+ * repetitive input, so an archive small enough to pass any upload gate can ask
+ * for gigabytes: measured here, a 305,893-byte archive declared a single entry
+ * expanding to 314,572,800 bytes. A Cloudflare Worker isolate has 128 MB, so
+ * that is an out-of-memory crash, not a slow path — and a crash is not a typed
+ * error a product can report. 32 MB is far past any real Office part (the main
+ * document of a 400-page contract is single-digit MB) and far under the
+ * isolate's budget.
+ */
+export declare const DEFAULT_MAX_ZIP_ENTRY_BYTES: number;
+/** Options for {@link readZipEntry}. */
+export interface ReadZipEntryOptions {
+    /** Ceiling on the entry's UNCOMPRESSED size. Defaults to
+     *  {@link DEFAULT_MAX_ZIP_ENTRY_BYTES}. Checked against the directory's
+     *  declared size before any inflate runs, and again against the real output
+     *  as it streams, because the declared size is the archive's claim. */
+    readonly maxUncompressedBytes?: number;
+}
+/** Inflate one entry's bytes. The local header supplies only the variable-length
+ *  field sizes needed to find the payload; sizes come from the directory. */
+export declare function readZipEntry(bytes: Uint8Array, entry: ZipEntry, options?: ReadZipEntryOptions): Promise<ZipOutcome<Uint8Array>>;

package/dist/eval/calibration.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Calibration — prove a gate can FAIL before believing that it PASSED, and
+ * prove a probe can SEE before believing the zero it reported.
+ *
+ * Every expensive failure this package has shipped was a check that verified
+ * its own input instead of the world, and reported green:
+ *
+ *   - `quote_verification 16/16` passed a work product whose nine citations
+ *     claimed a figure the cited document never mentions.
+ *   - `audit_form passed=3 failed=0` passed a form fill whose values landed in
+ *     "Combat zone" — the audit re-read the field paths the writer had just
+ *     invented, so a wrong path could not be wrong.
+ *   - `evidence_coverage 0/0` passed vacuously because the artifact it was
+ *     counting targets from was null.
+ *   - A benchmark reported 6/8 for the product while a bare
+ *     "You are a helpful assistant." scored 8/8 on the same cases.
+ *
+ * A gate is only evidence if it REJECTS something. A metric is only evidence
+ * if a worse system scores worse on it. Neither property is implied by a
+ * green run, and neither is visible in the output — which is why both have to
+ * be asserted separately, in code, next to the gate.
+ *
+ * This module is deliberately domain-free: a "gate" is any predicate over any
+ * input. Products supply the known-good and known-bad cases, because only the
+ * product knows what bad looks like in its domain.
+ */
+/** A case whose verdict is known in advance, used to calibrate a gate. */
+export interface CalibrationCase<TInput> {
+    /** What this case represents, e.g. `'quote that does not occur in the source'`. */
+    readonly label: string;
+    readonly input: TInput;
+    /** `'reject'` — the gate MUST refuse this. `'accept'` — it MUST allow it. */
+    readonly expect: 'accept' | 'reject';
+}
+export interface CalibrationOutcome {
+    readonly label: string;
+    readonly expected: 'accept' | 'reject';
+    readonly actual: 'accept' | 'reject';
+    readonly ok: boolean;
+    /** Set when the gate threw; a throw counts as `'reject'`. */
+    readonly threw?: string;
+}
+export interface CalibrationReport {
+    /** True only when every case matched AND both controls were present. */
+    readonly discriminates: boolean;
+    readonly outcomes: readonly CalibrationOutcome[];
+    readonly failures: readonly CalibrationOutcome[];
+    /** Why the gate is not trustworthy. Absent when `discriminates` is true. */
+    readonly reason?: string;
+}
+/**
+ * A gate under calibration. Returning `false` OR throwing both count as a
+ * rejection — a fail-loud gate (`ToolInputError`) and a boolean gate calibrate
+ * through the same path.
+ */
+export type GateFn<TInput> = (input: TInput) => boolean | Promise<boolean>;
+/**
+ * Run a gate against cases whose verdicts are known, and report whether it
+ * actually discriminates.
+ *
+ * Requires BOTH controls:
+ *   - at least one `'reject'` case — without it a gate that returns `true`
+ *     unconditionally is indistinguishable from a working one. This is the
+ *     control that all four failures above were missing.
+ *   - at least one `'accept'` case — without it a gate that refuses everything
+ *     scores perfectly, and an unsatisfiable gate does not stop bad work, it
+ *     selects for invented work (measured: 38 fabricated citations written to
+ *     clear a coverage gate no honest answer could satisfy).
+ */
+export declare function calibrateGate<TInput>(gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
+/**
+ * `calibrateGate`, but throws instead of reporting. Use in a test or at wiring
+ * time so an uncalibrated gate cannot ship silently.
+ */
+export declare function assertGateDiscriminates<TInput>(name: string, gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
+export interface ProbeReport<TValue> {
+    /** True when the positive control registered something, so a zero is real. */
+    readonly canSee: boolean;
+    readonly measured: number;
+    readonly control: number;
+    readonly value: TValue;
+    readonly reason?: string;
+}
+/**
+ * Measure something, but only after proving the instrument can register a
+ * non-zero — because an absence is a claim about the measurement first.
+ *
+ * Six blind probes were mistaken for real zeros in a single day: a SQL `LIKE`
+ * over a column the product encrypts (which equally returned 0 for `"text"`
+ * across every row — the tell), a `grep` run against worktrees on stale
+ * branches, a status-code comparison that never read the response bodies, a
+ * live event count taken from a run that was never dispatched, `rg --hidden`
+ * silently exiting 2 because `rg` was aliased to `grep`, and an intercepted
+ * `git show` returning an empty diff. Each nearly caused a wrong fix.
+ *
+ * `control` must count something that MUST exist. If it counts zero, the
+ * measurement is unusable regardless of what `measure` returned.
+ */
+export declare function measureWithControl<TValue>(opts: {
+    readonly measure: () => TValue | Promise<TValue>;
+    /** Must return a value whose count is non-zero, or the probe is blind. */
+    readonly control: () => TValue | Promise<TValue>;
+    readonly count: (value: TValue) => number;
+    /** Describes what the control counts, for the failure message. */
+    readonly controlLabel: string;
+}): Promise<ProbeReport<TValue>>;

package/dist/eval/index.d.ts

@@ -1,114 +1,3 @@
-import { CompletionRequirement, RuntimeEventLike } from '@tangle-network/agent-eval';
-export { CompletionRequirement, CompletionVerdict, CorrectnessChecker, ProducedState, RuntimeEventLike, SatisfiedBy, TaskGold, createLlmCorrectnessChecker, extractProducedState, verifyCompletion, weightedComposite } from '@tangle-network/agent-eval';
-import { c as AppToolProducedEvent } from '../types-B25Mib1r.js';
-
-/**
- * Calibration — prove a gate can FAIL before believing that it PASSED, and
- * prove a probe can SEE before believing the zero it reported.
- *
- * Every expensive failure this package has shipped was a check that verified
- * its own input instead of the world, and reported green:
- *
- *   - `quote_verification 16/16` passed a work product whose nine citations
- *     claimed a figure the cited document never mentions.
- *   - `audit_form passed=3 failed=0` passed a form fill whose values landed in
- *     "Combat zone" — the audit re-read the field paths the writer had just
- *     invented, so a wrong path could not be wrong.
- *   - `evidence_coverage 0/0` passed vacuously because the artifact it was
- *     counting targets from was null.
- *   - A benchmark reported 6/8 for the product while a bare
- *     "You are a helpful assistant." scored 8/8 on the same cases.
- *
- * A gate is only evidence if it REJECTS something. A metric is only evidence
- * if a worse system scores worse on it. Neither property is implied by a
- * green run, and neither is visible in the output — which is why both have to
- * be asserted separately, in code, next to the gate.
- *
- * This module is deliberately domain-free: a "gate" is any predicate over any
- * input. Products supply the known-good and known-bad cases, because only the
- * product knows what bad looks like in its domain.
- */
-/** A case whose verdict is known in advance, used to calibrate a gate. */
-interface CalibrationCase<TInput> {
-    /** What this case represents, e.g. `'quote that does not occur in the source'`. */
-    readonly label: string;
-    readonly input: TInput;
-    /** `'reject'` — the gate MUST refuse this. `'accept'` — it MUST allow it. */
-    readonly expect: 'accept' | 'reject';
-}
-interface CalibrationOutcome {
-    readonly label: string;
-    readonly expected: 'accept' | 'reject';
-    readonly actual: 'accept' | 'reject';
-    readonly ok: boolean;
-    /** Set when the gate threw; a throw counts as `'reject'`. */
-    readonly threw?: string;
-}
-interface CalibrationReport {
-    /** True only when every case matched AND both controls were present. */
-    readonly discriminates: boolean;
-    readonly outcomes: readonly CalibrationOutcome[];
-    readonly failures: readonly CalibrationOutcome[];
-    /** Why the gate is not trustworthy. Absent when `discriminates` is true. */
-    readonly reason?: string;
-}
-/**
- * A gate under calibration. Returning `false` OR throwing both count as a
- * rejection — a fail-loud gate (`ToolInputError`) and a boolean gate calibrate
- * through the same path.
- */
-type GateFn<TInput> = (input: TInput) => boolean | Promise<boolean>;
-/**
- * Run a gate against cases whose verdicts are known, and report whether it
- * actually discriminates.
- *
- * Requires BOTH controls:
- *   - at least one `'reject'` case — without it a gate that returns `true`
- *     unconditionally is indistinguishable from a working one. This is the
- *     control that all four failures above were missing.
- *   - at least one `'accept'` case — without it a gate that refuses everything
- *     scores perfectly, and an unsatisfiable gate does not stop bad work, it
- *     selects for invented work (measured: 38 fabricated citations written to
- *     clear a coverage gate no honest answer could satisfy).
- */
-declare function calibrateGate<TInput>(gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
-/**
- * `calibrateGate`, but throws instead of reporting. Use in a test or at wiring
- * time so an uncalibrated gate cannot ship silently.
- */
-declare function assertGateDiscriminates<TInput>(name: string, gate: GateFn<TInput>, cases: readonly CalibrationCase<TInput>[]): Promise<CalibrationReport>;
-interface ProbeReport<TValue> {
-    /** True when the positive control registered something, so a zero is real. */
-    readonly canSee: boolean;
-    readonly measured: number;
-    readonly control: number;
-    readonly value: TValue;
-    readonly reason?: string;
-}
-/**
- * Measure something, but only after proving the instrument can register a
- * non-zero — because an absence is a claim about the measurement first.
- *
- * Six blind probes were mistaken for real zeros in a single day: a SQL `LIKE`
- * over a column the product encrypts (which equally returned 0 for `"text"`
- * across every row — the tell), a `grep` run against worktrees on stale
- * branches, a status-code comparison that never read the response bodies, a
- * live event count taken from a run that was never dispatched, `rg --hidden`
- * silently exiting 2 because `rg` was aliased to `grep`, and an intercepted
- * `git show` returning an empty diff. Each nearly caused a wrong fix.
- *
- * `control` must count something that MUST exist. If it counts zero, the
- * measurement is unusable regardless of what `measure` returned.
- */
-declare function measureWithControl<TValue>(opts: {
-    readonly measure: () => TValue | Promise<TValue>;
-    /** Must return a value whose count is non-zero, or the probe is blind. */
-    readonly control: () => TValue | Promise<TValue>;
-    readonly count: (value: TValue) => number;
-    /** Describes what the control counts, for the failure message. */
-    readonly controlLabel: string;
-}): Promise<ProbeReport<TValue>>;
-
 /**
  * Eval — the app-shell BRIDGE to `@tangle-network/agent-eval`, not a reimpl.
  *
@@ -132,13 +21,18 @@ declare function measureWithControl<TValue>(opts: {
  * agent-eval's `runEvalCampaign` / `AgentDriver` / `BenchmarkRunner` — use them
  * directly; this module composes with them.
  */
-
+import type { RuntimeEventLike, CompletionRequirement } from '@tangle-network/agent-eval';
+import type { AppToolProducedEvent } from '../tools/types';
+export { verifyCompletion, extractProducedState, weightedComposite, createLlmCorrectnessChecker } from '@tangle-network/agent-eval';
+export { calibrateGate, assertGateDiscriminates, measureWithControl } from './calibration';
+export type { CalibrationCase, CalibrationOutcome, CalibrationReport, GateFn, ProbeReport } from './calibration';
+export type { CompletionRequirement, TaskGold, ProducedState, SatisfiedBy, CompletionVerdict, CorrectnessChecker, RuntimeEventLike, } from '@tangle-network/agent-eval';
 /**
  * Bridge the app-tool side channel's produced events into the runtime-event
  * shape agent-eval's `extractProducedState` reads. Pipe it:
  *   `verifyCompletion(taskGold, extractProducedState(producedFromToolEvents(events)), checker)`
  */
-declare function producedFromToolEvents(events: readonly AppToolProducedEvent[]): RuntimeEventLike[];
+export declare function producedFromToolEvents(events: readonly AppToolProducedEvent[]): RuntimeEventLike[];
 /**
  * A deterministic `CorrectnessChecker` (agent-eval exports only
  * `createLlmCorrectnessChecker`). A produced item fulfils a requirement when
@@ -146,12 +40,10 @@ declare function producedFromToolEvents(events: readonly AppToolProducedEvent[])
  * title's significant tokens. No network — the default gate for apps/tests
  * without an LLM judge. Pass to `verifyCompletion` as the checker.
  */
-declare function createTokenRecallChecker(opts?: {
+export declare function createTokenRecallChecker(opts?: {
     minRecall?: number;
     minContentLength?: number;
 }): (requirement: CompletionRequirement, content: string) => Promise<{
     correct: boolean;
     reason: string;
 }>;
-
-export { type CalibrationCase, type CalibrationOutcome, type CalibrationReport, type GateFn, type ProbeReport, assertGateDiscriminates, calibrateGate, createTokenRecallChecker, measureWithControl, producedFromToolEvents };

package/dist/eval-campaign/index.d.ts

@@ -1,10 +1,3 @@
-import { JudgeVerdict } from '@tangle-network/agent-eval';
-export { EnsembleAggregate, JudgeVerdict, RunRecord, aggregateJudgeVerdicts } from '@tangle-network/agent-eval';
-import { Scenario, JudgeConfig } from '@tangle-network/agent-eval/campaign';
-export { CampaignResult, CompareOptimizationMethodsOptions, DispatchContext, ExternalTextOptimizationMethodConfig, Gate, GepaOptimizationMethodConfig, JudgeConfig, JudgeDimension, JudgeScore, LabeledScenarioStore, MutableSurface, OptimizationMethod, OptimizationMethodResult, Scenario, SkillOptOptimizationMethodConfig, SurfaceProposer, compareOptimizationMethods, defaultProductionGate, externalTextOptimizationMethod, gepaOptimizationMethod, paretoSignificanceGate, runCampaign, skillOptOptimizationMethod } from '@tangle-network/agent-eval/campaign';
-export { T as TrustItem, a as TrustThresholds, b as TrustVerdict, t as trustVerdicts } from '../trust-gate-Dcm5xSva.js';
-export { SelfImproveBudget, SelfImproveOptions, SelfImproveResult, selfImprove } from '@tangle-network/agent-eval/contract';
-
 /**
  * Eval-campaign — the app-shell's curated surface for a product's
  * self-improvement loop, NOT a reimplementation.
@@ -28,9 +21,10 @@ export { SelfImproveBudget, SelfImproveOptions, SelfImproveResult, selfImprove }
  * `selfImprove` + release policies + optimization methods + their types. See
  * `.claude/skills/eval-campaign/SKILL.md` for the wiring contract.
  */
-
+import { type JudgeVerdict } from '@tangle-network/agent-eval';
+import type { JudgeConfig, Scenario } from '@tangle-network/agent-eval/campaign';
 /** Config for {@link buildEnsembleJudge}. `D` = the rubric's dimension union. */
-interface EnsembleJudgeConfig<TArtifact, TScenario extends Scenario, D extends string> {
+export interface EnsembleJudgeConfig<TArtifact, TScenario extends Scenario, D extends string> {
     /** Judge name — appears in traces and scorecards. */
     name: string;
     /** Stable-ordered rubric dimensions. Drives the `JudgeDimension` list AND the
@@ -69,6 +63,11 @@ interface EnsembleJudgeConfig<TArtifact, TScenario extends Scenario, D extends s
  *
  * Pass the result straight to `selfImprove({ judge })` (or `runCampaign`).
  */
-declare function buildEnsembleJudge<TArtifact, TScenario extends Scenario, D extends string>(cfg: EnsembleJudgeConfig<TArtifact, TScenario, D>): JudgeConfig<TArtifact, TScenario>;
-
-export { type EnsembleJudgeConfig, buildEnsembleJudge };
+export declare function buildEnsembleJudge<TArtifact, TScenario extends Scenario, D extends string>(cfg: EnsembleJudgeConfig<TArtifact, TScenario, D>): JudgeConfig<TArtifact, TScenario>;
+export { trustVerdicts, type TrustItem, type TrustThresholds, type TrustVerdict, } from './trust-gate';
+export { aggregateJudgeVerdicts } from '@tangle-network/agent-eval';
+export type { EnsembleAggregate, JudgeVerdict, RunRecord, } from '@tangle-network/agent-eval';
+export { compareOptimizationMethods, defaultProductionGate, externalTextOptimizationMethod, gepaOptimizationMethod, paretoSignificanceGate, runCampaign, skillOptOptimizationMethod, } from '@tangle-network/agent-eval/campaign';
+export type { CampaignResult, CompareOptimizationMethodsOptions, DispatchContext, ExternalTextOptimizationMethodConfig, Gate, GepaOptimizationMethodConfig, JudgeConfig, JudgeDimension, JudgeScore, LabeledScenarioStore, MutableSurface, OptimizationMethod, OptimizationMethodResult, Scenario, SkillOptOptimizationMethodConfig, SurfaceProposer, } from '@tangle-network/agent-eval/campaign';
+export { selfImprove } from '@tangle-network/agent-eval/contract';
+export type { SelfImproveBudget, SelfImproveOptions, SelfImproveResult, } from '@tangle-network/agent-eval/contract';

package/dist/{trust-gate-Dcm5xSva.d.ts → eval-campaign/trust-gate.d.ts}

@@ -1,5 +1,3 @@
-import { JudgeVerdict } from '@tangle-network/agent-eval';
-
 /**
  * Trust gate — decides whether an ensemble's scores are allowed to be BELIEVED,
  * one level up from {@link aggregateJudgeVerdicts} (which only reduces ONE
@@ -26,10 +24,10 @@ import { JudgeVerdict } from '@tangle-network/agent-eval';
  * denominator already pools across items, so genuine item-to-item variation
  * RAISES reliability rather than lowering it.
  */
-
+import { type JudgeVerdict } from '@tangle-network/agent-eval';
 /** One item's raters: the per-judge verdicts {@link aggregateJudgeVerdicts}
  *  reduces, tagged with the item they scored so spread stays within-item. */
-interface TrustItem<D extends string = string> {
+export interface TrustItem<D extends string = string> {
     /** Stable item identifier — surfaces in `perItemSpread` and `trustReasons`. */
     itemId: string;
     /** The raters' verdicts for THIS item (one per judge call). A failed judge
@@ -38,7 +36,7 @@ interface TrustItem<D extends string = string> {
 }
 /** Thresholds for {@link trustVerdicts}. All overridable; defaults are the
  *  conservative after-gate bar. */
-interface TrustThresholds {
+export interface TrustThresholds {
     /** Minimum corpus inter-rater reliability (Krippendorff-style α). Below this
      *  the raters agree no better than chance. Default 0.2. */
     irrFloor?: number;
@@ -51,7 +49,7 @@ interface TrustThresholds {
 }
 /** Result of the trust gate. `trustworthy` iff every check passed; `trustReasons`
  *  is empty iff `trustworthy`. */
-interface TrustVerdict {
+export interface TrustVerdict {
     /** True iff IRR ≥ floor AND every item's spread ≤ ceiling AND every item has
      *  ≥ `minSurvivors` surviving raters. */
     trustworthy: boolean;
@@ -78,6 +76,4 @@ interface TrustVerdict {
  *   silent `trustworthy: true` over zero evidence is the exact lie the gate
  *   exists to refuse.
  */
-declare function trustVerdicts<D extends string>(items: readonly TrustItem<D>[], thresholds?: TrustThresholds): TrustVerdict;
-
-export { type TrustItem as T, type TrustThresholds as a, type TrustVerdict as b, trustVerdicts as t };
+export declare function trustVerdicts<D extends string>(items: readonly TrustItem<D>[], thresholds?: TrustThresholds): TrustVerdict;

package/dist/forms/blank.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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. */
+export 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.
+ */
+export declare function decodeFormBlank(blank: FormBlank): Uint8Array;
+/** Lowercase-hex SHA-256 of a byte range. */
+export 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.
+ */
+export declare function assertFormBlankIntegrity(blank: FormBlank): Promise<void>;

package/dist/forms/fill.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import type { FormRegistry, FormSlot } from './registry';
+/** One widget the fill actually wrote. */
+export 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. */
+export type UnfilledCode = 'unknown_slot' | 'missing_field' | 'wrong_kind' | 'not_a_number' | 'not_a_boolean' | 'unformattable';
+export interface UnfilledSlot {
+    slot: string;
+    field?: string;
+    value: unknown;
+    code: UnfilledCode;
+    reason: string;
+}
+export interface FillFormResult {
+    bytes: Uint8Array;
+    filled: FilledWidget[];
+    unfilled: UnfilledSlot[];
+    form: string;
+    revision: string;
+}
+export 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.
+ */
+export declare function formatFormCurrency(value: number): string;
+/** A number, or a number written the way a form prints one (`$141,318.74`). */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function describeFormFill(result: FillFormResult): string;