laterite 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Table } from 'apache-arrow';
-import { Reading, Finding, AppliedFix, ValidationReport, displayHint, PackStats, UnpackStats } from '#native';
-export { AppliedFix, Finding, GroupMeta, version } from '#native';
+import { Finding, AppliedFix, ValidationReport, Sidecar, Reading, displayHint, PackStats, UnpackStats, ExcelStats } from '#native';
+export { AppliedFix, ExcelStats, Finding, GroupMeta, Sidecar, version } from '#native';
 
 /** One query result row — JS-native values (`getRowObjectsJS`: Dates, numbers,
  * nulls; 64-bit ints stay `bigint`). */
@@ -12,25 +12,161 @@ interface QueryOptions {
     arrow?: boolean;
 }
 
+/**
+ * The product of {@link fix} — the Node port of laterite-py's `FixResult`.
+ *
+ * `fix()` mechanically repairs an AGS4 document — always the *safe* set (CRLF /
+ * BOM / embedded-CR normalisation, short-row padding, numeric reformatting, the
+ * TRAN delimiter+concatenator rows), plus the intent-guessing *risky* set when
+ * asked — then re-validates the repaired bytes. This object is what that pass
+ * hands back: the fixed document, an account of what was changed, and an honest
+ * record of what it could not touch. Construction is internal; you receive one
+ * from `fix()`, you don't build it.
+ *
+ * The repair is non-destructive — nothing is written to disk by the fixer. The
+ * repaired document rides home on `.bytes`, decoded on demand via the `.text`
+ * getter (UTF-8), and persisted only when you choose to with `.save(path)`
+ * (which writes the bytes and returns the path). `applied` enumerates each fix
+ * that landed (`{kind, label, rule, line?, risk}` — serde snake_case, identical
+ * across Python / CLI / Node), with `.fixesApplied` as its count for a quick
+ * "did anything change?". Crucially, `findings` is *not* the input's problems —
+ * it is the residual after re-validation: the rule violations that survived the
+ * repair and still need a human. `dictVersion` records the AGS4 edition the fix
+ * resolved against. `toString()` gives a one-line summary (byte count, fixes
+ * applied, residual findings).
+ */
+declare class FixResult {
+    readonly bytes: Buffer;
+    /** Findings that remain after the fixes — what could NOT be mechanically fixed. */
+    readonly findings: Finding[];
+    /** The fixes that were applied (`{kind, label, rule, line?, risk}`). */
+    readonly applied: AppliedFix[];
+    readonly dictVersion: string;
+    constructor(bytes: Buffer, 
+    /** Findings that remain after the fixes — what could NOT be mechanically fixed. */
+    findings: Finding[], 
+    /** The fixes that were applied (`{kind, label, rule, line?, risk}`). */
+    applied: AppliedFix[], dictVersion: string);
+    /** How many fixes were applied. */
+    get fixesApplied(): number;
+    /** The repaired AGS4 document decoded as text. */
+    get text(): string;
+    /** Save the repaired bytes to `path`; returns `path`. */
+    save(path: string): string;
+    toString(): string;
+}
+
+/** One finding without its `rule` key — the value shape `byRule()` groups. */
+type RuleFinding = Omit<Finding, "rule">;
+/**
+ * The verdict from {@link validate} — the Node port of laterite-py's `Report`.
+ *
+ * `validate()` runs the numbered-rule engine over an AGS4 source and hands back
+ * one of these: an immutable wrapper over the native `ValidationReport`. It is a
+ * pure *result* object (it does not carry the file's bytes — that is what the
+ * read/build outputs are for); what it carries is the answer to "is this file
+ * conformant, and if not, why".
+ *
+ * Start with the headline getters. `isValid` is the one most callers branch on —
+ * it is `true` iff there are zero findings, which is deliberately *distinct* from
+ * the native `ok` flag (`ok` only means the source was parseable enough to
+ * validate). `count` is the number of findings, and `exitCode` mirrors what the
+ * `lat-check` binary would return for the same file, so a CLI wrapper can pass it
+ * straight through. The provenance getters — `file`, `dictVersion` (the AGS
+ * edition the rules were drawn from), and `resolution` — say *what* was checked
+ * and *against which dictionary*.
+ *
+ * The findings themselves come three ways. `findings` is the flat array in
+ * `lat-check` order (each `{rule, line?, group, desc, severity?}`). `byRule()`
+ * regroups them into the spec-rule map `{ "AGS Format Rule N": [...] }` for
+ * rule-oriented reporting. For machine output, `toJson()` and `toNdjson()` return
+ * strings byte-identical to `lat-check --json` / `--ndjson` (minted native-side),
+ * and `toString()` gives a one-line human summary.
+ *
+ * @see {@link validate} — the verb that produces a `Report`.
+ */
+declare class Report {
+    #private;
+    constructor(r: ValidationReport);
+    /** Synthesise a clean report from a fresh certificate — the engine-skipped
+     * outcome of `Ags4File.validate()` on an `index=`-certified file. `resolution`
+     * is the sentinel `"certified"` (the engine never emits it), `count` is 0, and
+     * the edition is the cert's. Mirrors laterite-py's `Report.from_cert`. */
+    static fromCert(cert: Sidecar, label: string): Report;
+    get file(): string;
+    get dictVersion(): string;
+    get resolution(): string;
+    get count(): number;
+    /** `true` iff there are zero findings (distinct from the native `ok`, which
+     * only means "validatable"). */
+    get isValid(): boolean;
+    get exitCode(): number;
+    /** All findings, in `lat-check` order: `{rule, line?, group, desc, severity?}`. */
+    get findings(): Finding[];
+    /** `{ "AGS Format Rule N": [{line?, group, desc, …}] }` — the spec-rule
+     * grouping (mirrors `Report.by_rule`). */
+    byRule(): Record<string, RuleFinding[]>;
+    /** `{file, findings:{…}}` pretty-JSON — byte-identical to `lat-check --json`. */
+    toJson(): string;
+    /** One flat `{rule, …}` per line — byte-identical to `lat-check --ndjson`. */
+    toNdjson(): string;
+    toString(): string;
+}
+
 /** A `(keyColumn, values)` filter, e.g. `["LOCA_ID", ["BH01", "BH02"]]`. */
 type Filter = [key: string, values: unknown[]];
+/**
+ * A key-filtered view over an `Ags4File`'s engine — the Node port of laterite-py's
+ * `_AgsSubset`, returned by `Ags4File.at()`. Filters ACCUMULATE by chaining
+ * (`at("LOCA", […]).at("SAMP", […])` keeps both): `table(code)` applies every
+ * filter whose key column is present in `code` (others ignored), so groups
+ * carrying none of the keys pass through unfiltered. Async, because the engine
+ * is promise-based (`@duckdb/node-api`).
+ */
 declare class AgsSubset {
     #private;
     constructor(parent: Ags4File, filters: Filter[]);
-    /** Narrow further by another entity's id (e.g. add a SAMP filter). */
+    /**
+     * Narrow further by another entity's id (e.g. add a SAMP filter on top of a
+     * LOCA one). Returns a fresh subset — filters accumulate, they never mutate.
+     *
+     * @param group - The group code whose `_ID` key to filter on (`"SAMP"` becomes
+     *   the `SAMP_ID` key column).
+     * @param values - The ids to keep; a row survives when its `<group>_ID` is one
+     *   of these.
+     * @returns A new `AgsSubset` carrying this filter plus all the existing ones.
+     */
     at(group: string, values: Iterable<unknown>): AgsSubset;
     /** The related groups — those carrying at least one filter's key column. */
     get groups(): string[];
-    /** `code` filtered by every applicable key (groups carrying none pass
-     * through), as JS-native row objects (or an arrow-js `Table` with
-     * `{ arrow: true }`). */
+    /**
+     * `code` filtered by every applicable key (groups carrying none of the keys
+     * pass through unfiltered), as JS-native row objects by default — or a
+     * born-typed arrow-js `Table` with `{ arrow: true }`.
+     *
+     * @param code - The group to read (its clean name).
+     * @param opts - Query options; `{ arrow: true }` switches the return to an
+     *   arrow-js `Table`.
+     * @returns The filtered rows as `Row[]`, or a `Table` when arrow output is
+     *   requested.
+     * @throws If `{ arrow: true }` is set but DuckDB's `arrow` community extension
+     *   can't be installed/loaded (offline or air-gapped).
+     */
     table(code: string): Promise<Row[]>;
     table(code: string, opts: {
         arrow: true;
     }): Promise<Table>;
     table(code: string, opts?: QueryOptions): Promise<Row[] | Table>;
-    /** `{group: rows}` for every related group, each filtered — a location's whole
-     * related record set in one call (arrow-js Tables with `{ arrow: true }`). */
+    /**
+     * `{group: rows}` for every related group, each filtered — a location's whole
+     * related record set in one call. Returns arrow-js `Table`s with
+     * `{ arrow: true }`, JS-native row objects otherwise.
+     *
+     * @param opts - Query options; `{ arrow: true }` makes each value a `Table`.
+     * @returns A map from group code to its filtered rows (or `Table`).
+     * @throws If `{ arrow: true }` is set but DuckDB's `arrow` community extension
+     *   can't be installed/loaded (offline or air-gapped).
+     */
     frames(): Promise<Record<string, Row[]>>;
     frames(opts: {
         arrow: true;
@@ -38,39 +174,114 @@ declare class AgsSubset {
     frames(opts?: QueryOptions): Promise<Record<string, Row[] | Table>>;
 }
 
+/** The source a handle was read from — retained so the chained `validate`/`fix`/
+ * `diff` verbs re-run against the TRUE bytes (matching original line numbers),
+ * not the byte-faithful `.bytes` re-emit. A synthesised handle has none. */
+interface Ags4Source {
+    path?: string;
+    text?: string;
+    data?: Uint8Array;
+    encoding?: string;
+}
+/**
+ * A parsed AGS4 file — the Node port of laterite-py's `Ags4File`. The read
+ * surface is **Arrow-direct**: `table(code)` decodes the native typed Arrow IPC
+ * straight to an arrow-js Table (no DuckDB round-trip). Python routes reads
+ * through DuckDB only because its pandas path is otherwise pyarrow-bound; Node
+ * has no such reason, so the base read surface needs no engine at all.
+ *
+ * The OPTIONAL DuckDB layer — `sql()` / `at()` / `connection` — is lazy: the
+ * engine spins up only on first use, and `@duckdb/node-api` is an optional peer
+ * (absent → a helpful install error). These are async (the Neo client is
+ * promise-based); everything else stays sync.
+ */
 declare class Ags4File {
     #private;
-    constructor(reading: Reading);
+    constructor(reading: Reading, src?: Ags4Source);
+    /** @internal — `read(..., { index })` attaches a freshness-checked certificate
+     * so a later errors-only `.validate()` can skip the rule engine. */
+    _attachCert(cert: Sidecar): void;
     /** Group codes in file order. */
     get groups(): string[];
     /** The file's `TRAN_AGS` edition string, if present. */
     get tranAgs(): string | null;
+    /** The HEADING-row codes of `code`, in file order. Throws if `code` isn't in the file. */
     headings(code: string): string[];
+    /** The UNIT row of `code`, one per heading. Throws if `code` isn't in the file. */
     units(code: string): string[];
+    /** The TYPE row of `code` (the AGS data types), one per heading. Throws if `code` isn't in the file. */
     types(code: string): string[];
     /** AGS TYPE → the DuckDB column type each heading lands as (for the P3 engine). */
     sqlTypes(code: string): string[];
     /** 1-indexed source line of each DATA row. */
     lineNumbers(code: string): number[];
+    /** Whether `code` is one of the file's groups — the cheap membership check `headings`/`table` would otherwise throw on. */
     has(code: string): boolean;
     /** One group as a born-typed arrow-js `Table` (a 2DP heading is Float64, an ID
      * Utf8, a DT a Timestamp) — the SAME typing the Python/wasm hosts produce,
      * byte-identical by construction (one shared `build_record_batch`). Cached per
-     * group. Throws if `code` isn't in the file. */
-    table(code: string): Table;
+     * group. Throws if `code` isn't in the file.
+     *
+     * By default the synthetic `_id`/`_parent_id` key columns are **dropped**; pass
+     * `{ keys: true }` to include them (the relational `sql()`/`at()` layer always
+     * carries them regardless — that's what makes cross-group joins work). */
+    table(code: string, opts?: {
+        keys?: boolean;
+    }): Table;
     /** Spec-correct AGS4 as text — byte-faithful to the source DATA values
      * (re-emitted native-side from the retained parse). Memoised. */
     get text(): string;
     /** `text` encoded UTF-8 — the bytes `save()` writes. Memoised. */
     get bytes(): Buffer;
-    /** Write the AGS4 to `path` (UTF-8); returns `path`. The inverse of `read`. */
+    /** Write the AGS4 to `path` (UTF-8) — the inverse of `read`. The bytes are
+     * byte-faithful to the source DATA values, re-emitted from the retained parse.
+     *
+     * @param path Filesystem path to write the UTF-8 AGS4 to.
+     * @returns The same `path`, for chaining. */
     save(path: string): string;
+    /** The last `.validate()` outcome (`undefined` until validated). */
+    get report(): Report | undefined;
+    /** The `FixResult` on a handle returned by `.fix()` (`undefined` otherwise). */
+    get fixReport(): FixResult | undefined;
+    /** Validate this file against the AGS4 rules and return `this` (chainable —
+     * `read(p).validate().sql(...)`); the outcome lands on `.report`. Same engine as
+     * the free `validate()`, run on the source this handle was read from so line
+     * numbers match the original. Errors + WARNINGs by default (`warnings`); `fyi`
+     * adds the low-signal tier. `encoding` defaults to the one this handle was read
+     * with. Mirrors `laterite.Ags4File.validate()`. */
+    validate(opts?: Omit<ValidateOptions, "text">): this;
+    /** Mechanically repair this file and return a NEW, repaired `Ags4File` — the
+     * fluent transform, so `read(p).fix().validate().save(out)` reads as one chain.
+     * The `FixResult` (what was applied + residual findings) rides on the returned
+     * handle's `.fixReport`. Safe fixes always apply; `risky` adds the intent-
+     * guessing set. `encoding` defaults to this handle's read encoding. Non-
+     * destructive — the source on disk is untouched. Mirrors
+     * `laterite.Ags4File.fix()`. */
+    fix(opts?: Omit<FixOptions, "text">): Ags4File;
+    /** Compare this file (the baseline) against `other` (the revision) — the
+     * `RevisionDelta` the free `diff()` returns. `other` is a path, bytes, or another
+     * `Ags4File`. `encoding` defaults to this handle's read encoding. Mirrors
+     * `laterite.Ags4File.diff()`. */
+    diff(other: DiffSource, opts?: DiffOptions): RevisionDelta;
+    /** Mint this file's `.ags.idx` validity certificate — a clean-validation proof
+     * plus a byte-offset index — and write it beside the file. REQUIRES a prior
+     * clean `.validate()`: certify *vouches for* a passed validation, it does not run
+     * one. `path` is the certificate's OUTPUT location (default `<source>.idx`), not
+     * a file to certify — it refuses to overwrite the source or any existing
+     * non-certificate file. Returns the written path. The cert is byte-identical to
+     * Python's / `lat-check --emit-index`'s, so `lat-check` reads it, and a later
+     * `read(f, { index })` consumes it to skip re-validation. Mirrors
+     * `laterite.Ags4File.certify()`. */
+    certify(path?: string): string;
     /** Run SQL over the file's groups by their clean names — e.g.
      * `await ags.sql("SELECT * FROM SAMP JOIN LOCA USING (LOCA_ID) WHERE …")`.
-     * Returns JS-native row objects by default, or a born-typed arrow-js `Table`
-     * with `{ arrow: true }` (loads the `arrow` community extension on first use).
-     * Any group may be referenced, so this loads them all. Needs the optional
-     * `@duckdb/node-api` peer. */
+     * Any group may be referenced, so this loads them all into the engine.
+     *
+     * @param query SQL referencing groups by their bare AGS code as table names.
+     * @param opts `{ arrow: true }` returns a born-typed arrow-js `Table` (loads the
+     *   `arrow` community extension on first use) instead of JS-native rows.
+     * @returns JS-native row objects by default, or a `Table` when `arrow` is set.
+     * @throws If the optional `@duckdb/node-api` peer is absent. */
     sql(query: string): Promise<Row[]>;
     sql(query: string, opts: {
         arrow: true;
@@ -80,7 +291,11 @@ declare class Ags4File {
      * returns a view whose `table(code)` yields only the rows whose `{group}_ID`
      * is in `values`. Chain to narrow (`.at("SAMP", […])`); `sub.groups` is the
      * related groups, `sub.frames()` pulls them all. Groups carrying none of the
-     * keys pass through. For any other predicate, use `sql("… WHERE …")`. */
+     * keys pass through. For any other predicate, use `sql("… WHERE …")`.
+     *
+     * @param group The parent group whose `{group}_ID` key drives the filter.
+     * @param values The id values to keep (empty matches nothing).
+     * @returns An `AgsSubset` view; further `.at()` calls accumulate filters. */
     at(group: string, values: Iterable<unknown>): AgsSubset;
     /** The raw `@duckdb/node-api` connection — every engine feature — seeded with
      * all of this file's groups under their clean names. */
@@ -91,7 +306,9 @@ declare class Ags4File {
     /** Drop the decoded-Table cache and close the DuckDB engine (if any).
      * `using f = read(…)` runs this automatically. */
     close(): void;
+    /** `using f = read(…)` disposal hook — delegates to `close()`. */
     [Symbol.dispose](): void;
+    /** A compact one-line summary — group count and `TRAN_AGS` — for logs and the REPL. */
     toString(): string;
 }
 
@@ -103,11 +320,38 @@ interface BuildFinding {
     desc?: string;
     [key: string]: unknown;
 }
+/**
+ * The product of {@link buildAgs4} — the data→AGS4 door's return value, and the
+ * Node port of laterite-py's `BuildResult`. Where `read` hands you an *existing*
+ * file, `buildAgs4` *constructs* one from your data and then runs the output back
+ * through the validator; this object is what falls out of that round trip. It is
+ * a plain, inert carrier — no DuckDB, no native handle to hold open — so you can
+ * keep it, pass it around, or persist it at leisure.
+ *
+ * It carries three things. {@link BuildResult.bytes | `bytes`} is the AGS4
+ * document as the validator emitted it (UTF-8); reach for {@link BuildResult.text
+ * | `text`} when you want it decoded as a string, or {@link BuildResult.save |
+ * `save(path)`} to write the bytes straight to disk (it returns the path).
+ * {@link BuildResult.findings | `findings`} is the *residual* set of validator
+ * findings — what the build could **not** clear given the `mode` it ran under
+ * (e.g. `"autofix"` applies the safe fixes and leaves only what it can't touch,
+ * `"report"` records everything); each is a flat {@link BuildFinding} of `rule`
+ * plus whatever rich keys the validator set. {@link BuildResult.fixesApplied |
+ * `fixesApplied`} counts how many safe fixes were applied along the way, and
+ * {@link BuildResult.applied | `applied`} is the ledger of those fixes (each a
+ * `{kind, label, rule, line?, risk}` record, the same shape `fix()`'s
+ * `FixResult.applied` carries). A clean build is an empty `findings` array; a
+ * non-empty one tells you exactly what the emitted document still trips on.
+ */
 declare class BuildResult {
     readonly bytes: Buffer;
     readonly findings: BuildFinding[];
+    /** The safe fixes AutoFix applied (`{kind, label, rule, line?, risk}`); empty outside `"autofix"`. */
+    readonly applied: AppliedFix[];
     readonly fixesApplied: number;
-    constructor(bytes: Buffer, findings: BuildFinding[], fixesApplied: number);
+    constructor(bytes: Buffer, findings: BuildFinding[], 
+    /** The safe fixes AutoFix applied (`{kind, label, rule, line?, risk}`); empty outside `"autofix"`. */
+    applied: AppliedFix[], fixesApplied: number);
     /** The AGS4 document decoded as text. */
     get text(): string;
     /** Save the bytes to `path`; returns `path`. */
@@ -115,52 +359,6 @@ declare class BuildResult {
     toString(): string;
 }
 
-declare class FixResult {
-    readonly bytes: Buffer;
-    /** Findings that remain after the fixes — what could NOT be mechanically fixed. */
-    readonly findings: Finding[];
-    /** The fixes that were applied (`{kind, label, rule, line?, risk}`). */
-    readonly applied: AppliedFix[];
-    readonly dictVersion: string;
-    constructor(bytes: Buffer, 
-    /** Findings that remain after the fixes — what could NOT be mechanically fixed. */
-    findings: Finding[], 
-    /** The fixes that were applied (`{kind, label, rule, line?, risk}`). */
-    applied: AppliedFix[], dictVersion: string);
-    /** How many fixes were applied. */
-    get fixesApplied(): number;
-    /** The repaired AGS4 document decoded as text. */
-    get text(): string;
-    /** Save the repaired bytes to `path`; returns `path`. */
-    save(path: string): string;
-    toString(): string;
-}
-
-/** One finding without its `rule` key — the value shape `byRule()` groups. */
-type RuleFinding = Omit<Finding, "rule">;
-declare class Report {
-    #private;
-    constructor(r: ValidationReport);
-    get file(): string;
-    get dictVersion(): string;
-    get resolution(): string;
-    get count(): number;
-    /** `true` iff there are zero findings (distinct from the native `ok`, which
-     * only means "validatable"). */
-    get isValid(): boolean;
-    get exitCode(): number;
-    /** All findings, in `lat-check` order: `{rule, line?, group, desc, severity?}`. */
-    get findings(): Finding[];
-    /** `{ "AGS Format Rule N": [{line?, group, desc, …}] }` — the spec-rule
-     * grouping (mirrors `Report.by_rule`). */
-    byRule(): Record<string, RuleFinding[]>;
-    /** `{file, findings:{…}}` pretty-JSON — byte-identical to `lat-check --json`. */
-    toJson(): string;
-    /** One flat `{rule, …}` per line — byte-identical to `lat-check --ndjson`. */
-    toNdjson(): string;
-    toString(): string;
-}
-
 declare abstract class AgsGroup {
 }
 
@@ -4550,20 +4748,41 @@ declare class UnsupportedEditionError extends Ags4Error {
 declare class BadDictError extends Ags4Error {
     constructor(message: string, exitCode?: number);
 }
+/** A passed `index=` certificate (`.ags.idx`) does not match the file it was read
+ * for — its size / SHA-256 differ, so its byte offsets and clean verdict are now
+ * lies. Raised at `read` time (fail-fast): an explicit `index=` asserts "this cert
+ * is for this file", so a mismatch is an error, never a silent fall-back. Rebuild
+ * it (`read(p).validate().certify()`). (#294 Batch E / #14) */
+declare class StaleCertError extends Ags4Error {
+    constructor(message: string, exitCode?: number);
+}
 
 /** Cross-system target categories — the lowercase labels the engine returns. */
 type CanonicalType = "string" | "integer" | "decimal" | "datetime" | "date" | "time" | "bool" | "enum";
 /** A parsed AGS value: number (integer/decimal), boolean (YN), string
  * (text/enum **and** the canonical datetime/date/time strings), or null. */
 type AgsValue = string | number | boolean | null;
-/** AGS spec type code → canonical category. Throws for unknown codes (mirrors
- * Python's `ValueError`). */
+/**
+ * AGS spec type code → canonical category. Throws for unknown codes (mirrors
+ * Python's `ValueError`), so the engine's permissive `null` never leaks into
+ * caller code as a silent miss.
+ *
+ * @param agsType - An AGS4 spec type code (e.g. `"2DP"`, `"ID"`, `"YN"`, `"DT"`).
+ * @returns The lowercase canonical category the engine maps that code to.
+ * @throws {Ags4Error} If the code is not a recognised AGS type.
+ */
 declare function canonicalType(agsType: string): CanonicalType;
 
-/** Parse an AGS4-shaped raw value into its canonical JS value (empty /
+/**
+ * Parse an AGS4-shaped raw value into its canonical JS value (empty /
  * unparseable → null). datetime/date/time come back as the canonical **string**
  * (engine shape; `new Date(s)` if you want a Date). Non-string input is
- * stringified first (matches the Python wrapper). */
+ * stringified first (matches the Python wrapper).
+ *
+ * @param raw - The raw cell value; non-string input is coerced via `String(...)`, and `null`/`undefined` short-circuit to `null`.
+ * @param agsType - The AGS4 spec type code governing how `raw` is interpreted.
+ * @returns The canonical value: a number (integer/decimal), boolean (YN), string (text/enum and the datetime/date/time strings), or `null`.
+ */
 declare function parseValue(raw: unknown, agsType: string): AgsValue;
 
 type agsTypes_AgsValue = AgsValue;
@@ -4596,6 +4815,10 @@ type Heading = GeneratedHeading;
  * dictionary carries combined statuses like `KEY+REQUIRED`, so a bare
  * `status === "KEY"` would wrongly miss them (matches the Rust/Python check). */
 declare function isKeyStatus(status: string): boolean;
+/** A typed, immutable view onto one standard AGS group: its 4-letter `code`,
+ * human `contents` description, `parent` code (or `null` for a root group), and
+ * its ordered `headings`. Wraps a single entry from the generated dictionary so
+ * the registry never hands out mutable raw rows. */
 declare class GroupDescriptor {
     readonly code: string;
     readonly contents: string;
@@ -4606,21 +4829,71 @@ declare class GroupDescriptor {
     get table(): string;
     /** DuckDB view name (`v_<code>`). */
     get view(): string;
+    /** This group's KEY headings (status part-matched via {@link isKeyStatus}), in
+     * declaration order. */
     get keyHeadings(): readonly Heading[];
+    /** This group's non-KEY headings — the complement of {@link keyHeadings} — in
+     * declaration order. */
     get nonKeyHeadings(): readonly Heading[];
 }
 /** Every standard AGS group, keyed by 4-letter code. */
 declare const GROUPS: Readonly<Record<string, GroupDescriptor>>;
 /** Single-group lookup; `undefined` for unknown codes. */
 declare function get(code: string): GroupDescriptor | undefined;
+/** One heading in a {@link DictionarySnapshot} group (`type` is the AGS data type). */
+interface DictHeading {
+    name: string;
+    status: string;
+    type: string;
+    unit?: string;
+    description: string;
+}
+/** One group in a {@link DictionarySnapshot}. */
+interface DictGroup {
+    code: string;
+    contents: string;
+    parent?: string;
+    headings: DictHeading[];
+}
+/** The bundled standard dictionary for one edition. */
+interface DictionarySnapshot {
+    ags_edition: string;
+    groups: DictGroup[];
+}
+/**
+ * The bundled STANDARD dictionary for one AGS `edition` — the per-edition view
+ * of the official dictionary (canonical group + heading names, descriptions,
+ * UNIT/TYPE, status). Where {@link GROUPS} is the *union* registry across all
+ * editions (the default), this is a single edition's standard dictionary — the
+ * same content the browser and `laterite.registry.dictionary()` render, from
+ * one shared Rust builder (#294 F#6).
+ *
+ * @param edition `"4.0.3" | "4.0.4" | "4.1" | "4.1.1" | "4.2"`; omit (or
+ *   `"auto"`) for the fallback edition.
+ * @throws {Error} if `edition` is not a recognised edition.
+ */
+declare function dictionary(edition?: string): DictionarySnapshot;
 /** Every direct child group of `parentCode`, alphabetically. */
 declare function childGroups(parentCode: string): GroupDescriptor[];
 /** Parent chain from `code` to root: `[code, parent, …, root]`. Throws for an
  * unknown code (so root groups — `[code]` — are distinguishable). */
 declare function ancestorChain(code: string): string[];
-/** KEY heading names a group inherits from its ancestors. */
+/** KEY heading names a group inherits from its **direct parent** — the
+ * intersection of this group's KEY headings with its immediate parent's. This
+ * matches the Rust/Python `inherited_key_names` (NOT the whole ancestor chain):
+ * because AGS re-declares inherited keys at every level, the direct-parent
+ * intersection already captures every key a group carries from above, so an
+ * ancestor-chain union would only add ancestor keys the group doesn't have
+ * (e.g. `PROJ_ID` on `SAMP`).
+ *
+ * @param code The group whose inherited KEY names to gather.
+ * @returns The set of KEY heading names shared with the direct parent (empty for a root).
+ * @throws {Ags4Error} If `code` isn't in the registry. */
 declare function inheritedKeyNames(code: string): Set<string>;
 
+type registry_DictGroup = DictGroup;
+type registry_DictHeading = DictHeading;
+type registry_DictionarySnapshot = DictionarySnapshot;
 declare const registry_GROUPS: typeof GROUPS;
 type registry_GroupDescriptor = GroupDescriptor;
 declare const registry_GroupDescriptor: typeof GroupDescriptor;
@@ -4628,21 +4901,56 @@ type registry_Heading = Heading;
 type registry_HeadingStatus = HeadingStatus;
 declare const registry_ancestorChain: typeof ancestorChain;
 declare const registry_childGroups: typeof childGroups;
+declare const registry_dictionary: typeof dictionary;
 declare const registry_get: typeof get;
 declare const registry_inheritedKeyNames: typeof inheritedKeyNames;
 declare const registry_isKeyStatus: typeof isKeyStatus;
 declare namespace registry {
-  export { registry_GROUPS as GROUPS, registry_GroupDescriptor as GroupDescriptor, type registry_Heading as Heading, type registry_HeadingStatus as HeadingStatus, registry_ancestorChain as ancestorChain, registry_childGroups as childGroups, registry_get as get, registry_inheritedKeyNames as inheritedKeyNames, registry_isKeyStatus as isKeyStatus };
+  export { type registry_DictGroup as DictGroup, type registry_DictHeading as DictHeading, type registry_DictionarySnapshot as DictionarySnapshot, registry_GROUPS as GROUPS, registry_GroupDescriptor as GroupDescriptor, type registry_Heading as Heading, type registry_HeadingStatus as HeadingStatus, registry_ancestorChain as ancestorChain, registry_childGroups as childGroups, registry_dictionary as dictionary, registry_get as get, registry_inheritedKeyNames as inheritedKeyNames, registry_isKeyStatus as isKeyStatus };
 }
 
-/** zstd-compress `src` → `dest`. `level` 1–22 (default 9). */
+/**
+ * zstd-compress `src` → `dest` for transport — content-agnostic, so it works on
+ * any file (an `.ags` transfer, an `.ags5db`, anything), not just AGS data.
+ *
+ * @param src - Path to the file to compress.
+ * @param dest - Path the compressed output is written to.
+ * @param level - zstd level 1–22 (default 9, the empirical sweet spot on AGS
+ * data — higher levels buy minutes, not bytes).
+ * @returns The output size, compression ratio vs source, and elapsed seconds.
+ */
 declare function pack(src: string, dest: string, level?: number): PackStats;
-/** zstd-decompress `src` → `dest`. */
+/**
+ * zstd-decompress a `.zst` produced by {@link pack} back to its original bytes.
+ *
+ * @param src - Path to the compressed `.zst` file.
+ * @param dest - Path the decompressed output is written to.
+ * @returns The output size and elapsed seconds.
+ */
 declare function unpack(src: string, dest: string): UnpackStats;
-/** zstd-compress + age-passphrase-encrypt `src` → `dest`. */
+/**
+ * zstd-compress, then age-passphrase-encrypt `src` → `dest`. Compress-then-
+ * encrypt is load-bearing: zstd needs low-entropy input, and ciphertext is
+ * random — so the order can't flip. The age envelope is interoperable with the
+ * Python side (pyrage) and `lat-db lock`, all linking the same Rust `age` crate.
+ *
+ * @param src - Path to the file to compress and encrypt.
+ * @param dest - Path the encrypted output is written to.
+ * @param password - Passphrase for the age envelope (scrypt + ChaCha20-Poly1305).
+ * @param level - zstd level 1–22 (default 9).
+ * @returns The output size, compression ratio vs source, and elapsed seconds.
+ */
 declare function lock(src: string, dest: string, password: string, level?: number): PackStats;
-/** age-passphrase-decrypt + zstd-decompress `src` → `dest`. Throws on a wrong
- * passphrase / non-passphrase envelope. */
+/**
+ * age-passphrase-decrypt, then zstd-decompress a `.zst.age` produced by
+ * {@link lock} back to its original bytes.
+ *
+ * @param src - Path to the encrypted `.zst.age` file.
+ * @param dest - Path the recovered output is written to.
+ * @param password - Passphrase the envelope was sealed with.
+ * @returns The output size and elapsed seconds.
+ * @throws If the passphrase is wrong or the input is not a passphrase envelope.
+ */
 declare function unlock(src: string, dest: string, password: string): UnpackStats;
 
 declare const transport_PackStats: typeof PackStats;
@@ -4660,12 +4968,37 @@ interface ReadOptions {
     text?: string;
     /** Source encoding label (`"utf-8"` default, `"windows-1252"`, …). */
     encoding?: string;
-}
-/** Parse AGS4 — a file `source` path, raw `Uint8Array`/`Buffer` bytes, or
- * in-memory `text` — into an `Ags4File`. Pass bytes (not a string) for large
- * inputs: V8 caps strings at ~512 MB, but a `Uint8Array` does not, so a web
- * backend can hand a multi-hundred-MB upload straight in. Throws `NotAgs4Error`
- * / `FileNotFoundError` / `UnsupportedEditionError` for un-parseable input. */
+    /** Path to this file's `.ags.idx` certificate (minted by `Ags4File.certify()`).
+     * Opt-in, no autodiscovery — naming it asserts the cert is for THIS file. A
+     * fresh cert is carried so a later errors-only `.validate()` skips the rule
+     * engine; a size/SHA mismatch throws {@link StaleCertError}. (#294 Batch E / #14) */
+    index?: string;
+}
+/**
+ * Parse AGS4 into an `Ags4File`. Where the data→AGS4 door (`buildAgs4`)
+ * *constructs* a file, `read` *loads* one that already exists — from a file
+ * `source` path, raw `Uint8Array`/`Buffer` bytes, or in-memory `opts.text`.
+ *
+ * Prefer bytes over a string for large inputs: V8 caps a single string at
+ * ~512 MB, but a `Uint8Array` does not, so a web backend can hand a
+ * multi-hundred-MB upload straight in without first stringifying it. A string
+ * `source` is the file path; non-string bytes are the raw content; an absent
+ * `source` means the input came in as `opts.text`.
+ *
+ * The engine never returns a soft failure for un-parseable input — it throws a
+ * typed error (the same exit-code identity as `lat-check`) so callers branch on
+ * the class, not a brittle message match.
+ *
+ * @param source - File path (string), raw `Uint8Array`/`Buffer` bytes, or
+ *   omitted when the input is supplied via `opts.text`.
+ * @param opts - Read options ({@link ReadOptions}): in-memory `text` and the
+ *   source `encoding` label (default `"utf-8"`).
+ * @returns An {@link Ags4File} wrapping the parsed groups.
+ * @throws {FileNotFoundError} The path could not be opened.
+ * @throws {NotAgs4Error} The input has no GROUP rows / is not decodable as AGS4.
+ * @throws {UnsupportedEditionError} A recognised but unsupported edition (e.g. AGS3).
+ * @throws {Ags4Error} Any other native parse failure (the fallback mapping).
+ */
 declare function read(source?: string | Uint8Array, opts?: ReadOptions): Ags4File;
 interface ValidateOptions extends ReadOptions {
     /** Force an edition (`"4.0.3"`…`"4.2"`); default auto-detects from `TRAN_AGS`. */
@@ -4678,9 +5011,29 @@ interface ValidateOptions extends ReadOptions {
     checkFiles?: boolean;
 }
 /** Validate AGS4 — a file `source` path, raw `Uint8Array`/`Buffer` bytes, or
- * in-memory `text` — against the AGS4 rules. Throws for un-validatable input;
- * rule *violations* come back in the `Report`. (Bytes avoid V8's ~512 MB string
- * cap, the same as `read`.) */
+ * in-memory `text` (via `opts.text`) — against the numbered AGS4 rules, returning
+ * a `Report`. The crucial distinction: rule *violations* are data, not errors —
+ * they come back inside the `Report` (`.findings`, `.byRule()`, `.isValid`); only
+ * *un-validatable* input (missing file, not AGS4, AGS3, bad dictionary) throws.
+ * By default the report is the error-tier findings; opt warnings and FYIs in with
+ * `opts.warnings` / `opts.fyi`. The edition auto-detects from `TRAN_AGS` unless
+ * pinned with `opts.dictVersion`. Pass bytes (not a string) for large inputs:
+ * V8 caps strings at ~512 MB but a `Uint8Array` does not, so a web backend can
+ * hand a multi-hundred-MB upload straight in — the same byte door as `read`.
+ * Mirrors `laterite.validate()` / the `lat-check` binary.
+ *
+ * @param source File path (string), or raw bytes (`Uint8Array`/`Buffer`); omit to
+ *   validate `opts.text` instead.
+ * @param opts Validation knobs (`ValidateOptions`) — the dictionary-version pin
+ *   (`dictVersion`), severity gates, in-memory text/encoding, and the on-disk
+ *   Rule-20 toggle; see the interface for each field.
+ * @returns A `Report` carrying the findings, the resolved `dictVersion`, the
+ *   finding `count`, `isValid`, and `lat-check`-faithful `toJson()` / `toNdjson()`.
+ * @throws {FileNotFoundError} the path could not be opened.
+ * @throws {NotAgs4Error} the input has no GROUP rows / is not decodable AGS4.
+ * @throws {UnsupportedEditionError} a recognised-but-unsupported edition (AGS3).
+ * @throws {BadDictError} an invalid `opts.dictVersion` / unimplemented dictionary.
+ */
 declare function validate(source?: string | Uint8Array, opts?: ValidateOptions): Report;
 /** Row-oriented group data: an array of `{HEADING: value}` objects. */
 type GroupRows = Array<Record<string, unknown>>;
@@ -4691,14 +5044,42 @@ interface EmitOptions {
     dictVersion?: string;
     /** `"autofix"` (default) | `"report"` | `"strict"`. */
     mode?: "autofix" | "report" | "strict";
-}
-/** Build valid AGS4 from your own data — the data→AGS4 door. Where `read` loads
- * an *existing* file, `buildAgs4` *constructs* a new one (and autofixes +
- * validates it). `groups` is either a **typed-graph root** (`new PROJ({…})`,
- * walked depth-first) OR a Map/array mapping each AGS group code to an arrow-js
- * `Table` or row objects whose **keys are the AGS headings** (`LOCA_ID`, …).
- * UNIT/TYPE are filled from the chosen `dictVersion`; order is preserved (put `PROJ`
- * first). Needs no DuckDB. Persist the result with `BuildResult.save`. */
+    /** Per-heading UNIT overrides, keyed `{ code: { heading: unit } }` (#294 F#9)
+     *  — e.g. `{ LOCA: { LOCA_XTRA: "kPa" } }`. Name only the headings you want to
+     *  set; the rest fill from the dictionary. Throws on an unknown code/heading. */
+    units?: Record<string, Record<string, string>>;
+    /** Per-heading AGS data-TYPE overrides, same `{ code: { heading: type } }` shape. */
+    types?: Record<string, Record<string, string>>;
+}
+/**
+ * Build valid AGS4 from your own data — the data→AGS4 door. Where `read` loads
+ * an *existing* file, `buildAgs4` *constructs* a new one: it lays the groups out
+ * in order, fills UNIT/TYPE from the chosen `dictVersion`, then runs the output
+ * through the validator (the `mode` knob on `opts` decides what happens to the
+ * findings — `"autofix"` applies the safe fixes *and* synthesizes any missing
+ * UNIT/TYPE/TRAN/ABBR metadata group so a data-only build is valid; `"report"` merely
+ * records them). The returned `BuildResult` carries the bytes, the residual `findings`,
+ * and a `fixesApplied` count; persist it with `BuildResult.save`. Needs no DuckDB.
+ *
+ * `groups` accepts two shapes. A **typed-graph root** (`new PROJ({…, locas:[new
+ * LOCA({…})]})`) is walked depth-first via the registry's parent→child links,
+ * only the headings you set becoming columns (entirely-unset ones are dropped,
+ * except KEY). The walk covers only
+ * PROJ's subtree (the root-metadata groups have no parent), but under `"autofix"`
+ * the missing UNIT/TYPE/TRAN (and ABBR for PA codes) are synthesized, so a
+ * typed-graph build is valid out of the box. Or pass a **Map / array of `[code,
+ * data]`** entries where `data` is
+ * an arrow-js `Table` or row objects whose **keys are the AGS headings**
+ * (`LOCA_ID`, …). Either way group order is preserved, so put `PROJ` first.
+ *
+ * @param groups The data to emit — a typed-graph root (`new PROJ({…})`), or a
+ *   `Map`/array of `[groupCode, Table | rowObjects]` entries (headings as keys).
+ * @param opts Emit options (`dictVersion`, `mode`); see {@link EmitOptions}.
+ * @returns A {@link BuildResult} — `.bytes`/`.text` of the AGS4 document, the
+ *   `findings` it could not fix, the `fixesApplied` count, and `.save(path)`.
+ * @throws {Ags4Error} If a typed-graph node is not a registered AGS group.
+ * @throws If the native emitter rejects the input (e.g. an unknown `dictVersion`).
+ */
 declare function buildAgs4(groups: AgsGroup | Map<string, GroupData> | Array<[string, GroupData]>, opts?: EmitOptions): BuildResult;
 /** One cited divergence observation on a rule (`{id, note}`). */
 interface RuleObservation {
@@ -4714,9 +5095,20 @@ interface RuleMeta {
     fixable: boolean;
     observations: RuleObservation[];
 }
-/** The AGS4 rule catalogue — one entry per rule (title, severity, whether `fix`
- * can repair it, cited `O-N` notes). Mirrors `laterite.list_rules()` /
- * `lat-check --list-rules`; backed by the gated `rules_meta.json`. No input. */
+/**
+ * The AGS4 rule catalogue — one `RuleMeta` per numbered rule, surfaced so a
+ * caller can show *which* rules exist and how each behaves before (or instead
+ * of) running `validate`/`fix` over a file. Each entry carries the rule id and
+ * title, a one-line `checks` summary, its `severity`, whether `fix` can
+ * mechanically repair it (`fixable`), and any cited `O-N` divergence
+ * observations. Mirrors `laterite.list_rules()` / `lat-check --list-rules`;
+ * backed by the gated `rules_meta.json` (the catalogue is static, so this takes
+ * no input and reads no file).
+ *
+ * @returns The full rule catalogue as a `RuleMeta[]` — see `RuleMeta` for the
+ *   per-entry shape (`rule`, `title`, `checks`, `severity`, `fixable`,
+ *   `observations`).
+ */
 declare function listRules(): RuleMeta[];
 interface FixOptions {
     /** Repair in-memory `text` instead of a file path. */
@@ -4728,11 +5120,122 @@ interface FixOptions {
     /** Also apply the intent-guessing (risky) fixes, not just the safe set. */
     risky?: boolean;
 }
-/** Mechanically repair AGS4 — a file `source` path, raw `Uint8Array`/`Buffer`
- * bytes, or in-memory `text`. Applies the safe fixes (plus the risky set when
- * `risky`), re-validates, and returns a `FixResult` (`.bytes` / `.text` /
- * `.save(path)`); `findings` are what could NOT be mechanically fixed. Mirrors
- * `laterite.fix()` / `lat-check --fix`. Throws for un-fixable input. */
+/** Mechanically repair AGS4 — the headless twin of the browser's Fix engine.
+ * `source` is a file path, raw `Uint8Array`/`Buffer` bytes, or (via `opts.text`)
+ * in-memory text. The *safe* fixes — CRLF / BOM / embedded-CR normalisation,
+ * short-row padding, numeric reformatting, and the TRAN delimiter+concatenator
+ * rows — are always applied; pass `risky` to also run the intent-guessing set
+ * (duplicate-heading rename, `dd/mm` datetime canonicalisation, smart-quote→ASCII
+ * typography). The repaired bytes are re-validated, so `FixResult.findings` is
+ * what could NOT be mechanically fixed.
+ *
+ * Non-destructive: nothing is written here — the repaired bytes come back on the
+ * result (`.bytes` / `.text` / `.save(path)`), already UTF-8 with no BOM, so
+ * fixing a non-UTF-8 file also normalises its encoding. Mirrors `laterite.fix()`
+ * / `lat-check --fix`.
+ *
+ * @param source - The AGS4 input: a filesystem path (`string`) or raw bytes
+ *   (`Uint8Array`/`Buffer`). Omit to repair `opts.text` instead.
+ * @param opts - {@link FixOptions} — `text` source, `risky` fixes, `dictVersion`
+ *   override, and source `encoding`.
+ * @returns A {@link FixResult} carrying the repaired `bytes` (and `.text` /
+ *   `.save`), the `applied` fixes (with `fixesApplied` count), the residual
+ *   `findings` left after re-validation, and the resolved `dictVersion`.
+ * @throws {Ags4Error} (or a subclass — {@link FileNotFoundError},
+ *   {@link NotAgs4Error}, {@link UnsupportedEditionError}, {@link BadDictError})
+ *   for un-fixable input, carrying the matching `lat-check` exit code.
+ */
 declare function fix(source?: string | Uint8Array, opts?: FixOptions): FixResult;
+/** One changed cell of a matched row (`kind === "changed"`). `type` is the AGS
+ * data type; `a`/`b` are the raw values on each side (`null` if that side's row
+ * is shorter than the heading list). Snake_case fields mirror the wire shape the
+ * shared `laterite-ags4-diff` leaf serialises — identical to Python's dict. */
+interface CellDelta {
+    heading: string;
+    type: string;
+    a: string | null;
+    b: string | null;
+}
+/** One row's verdict: `added` (only in `b`), `removed` (only in `a`), or
+ * `changed` (matched by KEY, ≥1 typed cell differs). `key` is the KEY values (or
+ * whole-row tuple when unkeyed); `cells` is populated only for `changed`. */
+interface RowDelta {
+    kind: "added" | "removed" | "changed";
+    key: string[];
+    line_a: number | null;
+    line_b: number | null;
+    cells: CellDelta[];
+}
+/** A group's deltas. `added`/`removed`/`changed` are true totals; `keyed` is
+ * false when matched on the whole-row tuple (no dictionary KEY headings). */
+interface GroupDelta {
+    code: string;
+    added: number;
+    removed: number;
+    changed: number;
+    headings_added: string[];
+    headings_removed: string[];
+    keyed: boolean;
+    key_headings: string[];
+    rows: RowDelta[];
+}
+/** The revision diff — the shape `diff()` returns (parsed from the shared
+ * `laterite-ags4-diff` leaf's JSON; byte-identical to Python / wasm / `lat-check
+ * --diff`). */
+interface RevisionDelta {
+    groups: GroupDelta[];
+    groups_added: string[];
+    groups_removed: string[];
+    total_added: number;
+    total_removed: number;
+    total_changed: number;
+}
+interface DiffOptions {
+    /** Force the edition used to resolve each group's KEY headings (`"4.0.3"`…
+     * `"4.2"`); default takes it from the revision's `TRAN_AGS`. */
+    dictVersion?: string;
+    /** Source encoding label for path / bytes inputs (default `"utf-8"`). */
+    encoding?: string;
+}
+/** A diff input: a file path (`string`), raw bytes, or an already-read `Ags4File`. */
+type DiffSource = string | Uint8Array | Ags4File;
+/** Compare two AGS4 documents and return their **revision diff** — the Node port
+ * of `laterite.diff()` and the browser's revision-diff tool, over the SAME shared
+ * `laterite-ags4-diff` engine `lat-check --diff` uses.
+ *
+ * `a` (baseline) and `b` (revision) are each a path, raw `Uint8Array`/`Buffer`
+ * bytes, or an already-read `Ags4File`. Two choices make the diff meaningful
+ * rather than noisy: rows are matched by the group's dictionary **KEY** headings
+ * (not line order — re-sorted boreholes still pair up), and cells are compared
+ * through the **typed** value (a formatting-only edit like `"1.0"` → `"1.00"` is
+ * not a diff). The KEY-heading edition is the revision's `TRAN_AGS` unless pinned
+ * with `opts.dictVersion`.
+ *
+ * @param a - The baseline document (path / bytes / `Ags4File`).
+ * @param b - The revision document, in any of the same forms.
+ * @param opts - {@link DiffOptions} — the `dictVersion` pin and source `encoding`.
+ * @returns A {@link RevisionDelta}: per-group row/heading deltas, `groups_added`/
+ *   `groups_removed`, and the `total_added`/`total_removed`/`total_changed` counts.
+ * @throws {FileNotFoundError} a path input could not be opened.
+ * @throws {NotAgs4Error} either side is not decodable AGS4.
+ * @throws {BadDictError} an invalid `opts.dictVersion`.
+ */
+declare function diff(a: DiffSource, b: DiffSource, opts?: DiffOptions): RevisionDelta;
+/**
+ * Write an AGS4 file's groups to an `.xlsx` — one worksheet per group (the
+ * Node analog of Python's `to_excel`). `groups` forces the worksheet order;
+ * otherwise AGS4 source order is preserved. Returns the conversion stats.
+ */
+declare function toExcel(agsPath: string, xlsxPath: string, opts?: {
+    groups?: string[];
+}): ExcelStats;
+/**
+ * Read an `.xlsx` back into an AGS4 file (the Node analog of `from_excel`).
+ * `formatNumericColumns` (default true) re-applies AGS4 numeric formatting to
+ * numeric-looking columns. Returns the conversion stats.
+ */
+declare function fromExcel(xlsxPath: string, agsPath: string, opts?: {
+    formatNumericColumns?: boolean;
+}): ExcelStats;
 
-export { AAVT, ABBR, ACVT, AELO, AFLK, AIVT, ALOS, APSV, ARTW, ASDI, ASNS, AWAD, Ags4Error, Ags4File, AgsGroup, AgsSubset, type AgsValue, BKFL, BadDictError, type BuildFinding, BuildResult, CBRG, CBRP, CBRT, CDIA, CHIS, CHOC, CMPG, CMPT, CONG, CONS, CORE, CPDG, CPDT, CPTG, CPTM, CPTP, CPTT, CPTY, CPTZ, CTRC, CTRD, CTRG, CTRP, CTRS, type CanonicalType, DCPG, DCPT, DETL, DICT, DISC, DLOG, DMDG, DMDT, DMTG, DMTP, DMTT, DMTZ, DOBS, DPRB, DPRG, DREM, ECTN, ELRG, ERES, ESCG, ESCT, type EmitOptions, FGHG, FGHI, FGHS, FGHT, FILE, FLSH, FRAC, FRST, FileNotFoundError, type Filter, type FixOptions, FixResult, GCHM, GEOL, GRAG, GRAT, type GroupData, GroupDescriptor, type GroupRows, HDIA, HDPH, HORN, type Heading, type HeadingStatus, ICBR, IDEN, IFID, IPEN, IPID, IPRG, IPRT, IRDX, IRES, ISAG, ISAT, ISPT, ISTA, ISTG, ISTR, ISTS, ITCH, IVAN, LBSG, LBST, LDEN, LDYN, LFCN, LLIN, LLPL, LNMC, LOCA, LPDN, LPEN, LRES, LSLT, LSTG, LSTT, LSWL, LTCH, LUCT, LVAN, MCVG, MCVT, MOND, MONG, MONS, NotAgs4Error, PIPE, PLTG, PLTT, PMMC, PMMD, PMMG, PMTD, PMTG, PMTL, PMTP, PMTZ, PREM, PROJ, PTIM, PTST, PUMG, PUMT, type QueryOptions, RCAG, RCAT, RCCV, RDEN, RELD, RESC, RESD, RESG, RESP, RESS, RPLT, RSCH, RSHR, RTEN, RUCS, RWCO, type ReadOptions, Report, type Row, type RuleFinding, type RuleMeta, type RuleObservation, SAMP, SCDG, SCDT, SCPG, SCPP, SCPT, SHBG, SHBT, STND, SUCT, TNPC, TRAN, TREG, TREM, TRET, TRIG, TRIT, TYPE, UNIT, UnsupportedEditionError, type ValidateOptions, WADD, WETH, WGPG, WGPT, WINS, WSTD, WSTG, agsTypes, buildAgs4, fix, listRules, read, registry, transport, validate };
+export { AAVT, ABBR, ACVT, AELO, AFLK, AIVT, ALOS, APSV, ARTW, ASDI, ASNS, AWAD, Ags4Error, Ags4File, AgsGroup, AgsSubset, type AgsValue, BKFL, BadDictError, type BuildFinding, BuildResult, CBRG, CBRP, CBRT, CDIA, CHIS, CHOC, CMPG, CMPT, CONG, CONS, CORE, CPDG, CPDT, CPTG, CPTM, CPTP, CPTT, CPTY, CPTZ, CTRC, CTRD, CTRG, CTRP, CTRS, type CanonicalType, type CellDelta, DCPG, DCPT, DETL, DICT, DISC, DLOG, DMDG, DMDT, DMTG, DMTP, DMTT, DMTZ, DOBS, DPRB, DPRG, DREM, type DiffOptions, type DiffSource, ECTN, ELRG, ERES, ESCG, ESCT, type EmitOptions, FGHG, FGHI, FGHS, FGHT, FILE, FLSH, FRAC, FRST, FileNotFoundError, type Filter, type FixOptions, FixResult, GCHM, GEOL, GRAG, GRAT, type GroupData, type GroupDelta, GroupDescriptor, type GroupRows, HDIA, HDPH, HORN, type Heading, type HeadingStatus, ICBR, IDEN, IFID, IPEN, IPID, IPRG, IPRT, IRDX, IRES, ISAG, ISAT, ISPT, ISTA, ISTG, ISTR, ISTS, ITCH, IVAN, LBSG, LBST, LDEN, LDYN, LFCN, LLIN, LLPL, LNMC, LOCA, LPDN, LPEN, LRES, LSLT, LSTG, LSTT, LSWL, LTCH, LUCT, LVAN, MCVG, MCVT, MOND, MONG, MONS, NotAgs4Error, PIPE, PLTG, PLTT, PMMC, PMMD, PMMG, PMTD, PMTG, PMTL, PMTP, PMTZ, PREM, PROJ, PTIM, PTST, PUMG, PUMT, type QueryOptions, RCAG, RCAT, RCCV, RDEN, RELD, RESC, RESD, RESG, RESP, RESS, RPLT, RSCH, RSHR, RTEN, RUCS, RWCO, type ReadOptions, Report, type RevisionDelta, type Row, type RowDelta, type RuleFinding, type RuleMeta, type RuleObservation, SAMP, SCDG, SCDT, SCPG, SCPP, SCPT, SHBG, SHBT, STND, SUCT, StaleCertError, TNPC, TRAN, TREG, TREM, TRET, TRIG, TRIT, TYPE, UNIT, UnsupportedEditionError, type ValidateOptions, WADD, WETH, WGPG, WGPT, WINS, WSTD, WSTG, agsTypes, buildAgs4, diff, fix, fromExcel, listRules, read, registry, toExcel, transport, validate };