laterite 0.5.1 → 0.6.0

package/dist/index.mjs

@@ -5,10 +5,12 @@ var __export = (target, all) => {
 };
 
 // ts/index.ts
+import { readFileSync as readFileSync2 } from "fs";
 import { tableFromArrays, tableToIPC } from "apache-arrow";
 
 // ts/ags4-file.ts
-import { writeFileSync } from "fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "fs";
+import { resolve } from "path";
 import { tableFromIPC as tableFromIPC2 } from "apache-arrow";
 
 // ts/duckdb.ts
@@ -48,6 +50,12 @@ var BadDictError = class extends Ags4Error {
     this.name = "BadDictError";
   }
 };
+var StaleCertError = class extends Ags4Error {
+  constructor(message, exitCode = 4) {
+    super(message, exitCode);
+    this.name = "StaleCertError";
+  }
+};
 function makeError(kind, exitCode, message) {
   switch (kind) {
     case "not_found":
@@ -83,6 +91,10 @@ function fromNativeError(e) {
 function quoteId(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
+function stripSynthKeys(table) {
+  const dataCols = table.schema.fields.filter((f) => !f.name.startsWith("_")).map((f) => f.name);
+  return dataCols.length === table.numCols ? table : table.select(dataCols);
+}
 var DUCK_PACKAGE = "@duckdb/node-api";
 var duckMod = null;
 function loadDuck() {
@@ -122,11 +134,19 @@ var DuckEngine = class _DuckEngine {
    * rows appended from the born-typed arrow-js Table). Idempotent per code. */
   async register(code, meta, table) {
     if (this.registered.has(code)) return;
-    const cols = meta.headings.map((h, i) => `${quoteId(h)} ${meta.sqlTypes[i]}`).join(", ");
+    const keyCols = table.schema.fields.some((f) => f.name === "_id") ? ["_id", "_parent_id"] : [];
+    const cols = [
+      ...keyCols.map((k) => `${quoteId(k)} VARCHAR`),
+      ...meta.headings.map((h, i) => `${quoteId(h)} ${meta.sqlTypes[i]}`)
+    ].join(", ");
     await this.#con.run(`CREATE TABLE ${quoteId(code)} (${cols})`);
     const appender = await this.#con.createAppender(code);
+    const keyVectors = keyCols.map((k) => table.getChild(k));
     const vectors = meta.headings.map((h) => table.getChild(h));
     for (let r = 0; r < table.numRows; r++) {
+      for (let c = 0; c < keyCols.length; c++) {
+        this.#appendCell(appender, "VARCHAR", keyVectors[c]?.get(r));
+      }
       for (let c = 0; c < meta.headings.length; c++) {
         this.#appendCell(appender, meta.sqlTypes[c] ?? "VARCHAR", vectors[c]?.get(r));
       }
@@ -196,6 +216,100 @@ function toMicros(value) {
   return BigInt(Math.round(ms * 1e3));
 }
 
+// ts/native.ts
+import {
+  version,
+  parseArrow,
+  runCheck,
+  fixFile,
+  listRules,
+  registryDictionaryJson,
+  diff,
+  emitAgs4FromIpc,
+  Reading,
+  Sidecar,
+  canonicalType,
+  displayHint,
+  parseValue,
+  transportPack,
+  transportUnpack,
+  transportLock,
+  transportUnlock,
+  ags4ToExcel,
+  excelToAgs4
+} from "#native";
+
+// ts/report.ts
+var Report = class _Report {
+  #r;
+  constructor(r) {
+    this.#r = r;
+  }
+  /** 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, label) {
+    return new _Report({
+      ok: true,
+      exitCode: 0,
+      file: label,
+      dictVersion: cert.edition,
+      resolution: "certified",
+      count: 0,
+      findings: [],
+      json: JSON.stringify({ file: label, findings: {} }),
+      ndjson: ""
+    });
+  }
+  get file() {
+    return this.#r.file;
+  }
+  get dictVersion() {
+    return this.#r.dictVersion;
+  }
+  get resolution() {
+    return this.#r.resolution;
+  }
+  get count() {
+    return this.#r.count;
+  }
+  /** `true` iff there are zero findings (distinct from the native `ok`, which
+   * only means "validatable"). */
+  get isValid() {
+    return this.#r.count === 0;
+  }
+  get exitCode() {
+    return this.#r.exitCode;
+  }
+  /** All findings, in `lat-check` order: `{rule, line?, group, desc, severity?}`. */
+  get findings() {
+    return this.#r.findings;
+  }
+  /** `{ "AGS Format Rule N": [{line?, group, desc, …}] }` — the spec-rule
+   * grouping (mirrors `Report.by_rule`). */
+  byRule() {
+    const out = {};
+    for (const f of this.#r.findings) {
+      const { rule, ...rest } = f;
+      (out[rule] ??= []).push(rest);
+    }
+    return out;
+  }
+  /** `{file, findings:{…}}` pretty-JSON — byte-identical to `lat-check --json`. */
+  toJson() {
+    return this.#r.json;
+  }
+  /** One flat `{rule, …}` per line — byte-identical to `lat-check --ndjson`. */
+  toNdjson() {
+    return this.#r.ndjson;
+  }
+  toString() {
+    const v = this.isValid ? "valid" : `${this.count} finding(s)`;
+    return `<Report ${JSON.stringify(this.file)} ${v} dict=${this.dictVersion}>`;
+  }
+};
+
 // ts/subset.ts
 var AgsSubset = class _AgsSubset {
   #parent;
@@ -204,7 +318,16 @@ var AgsSubset = class _AgsSubset {
     this.#parent = parent;
     this.#filters = filters;
   }
-  /** 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, values) {
     return new _AgsSubset(this.#parent, [...this.#filters, [`${group}_ID`, [...values]]]);
   }
@@ -226,17 +349,38 @@ var AgsSubset = class _AgsSubset {
 };
 
 // ts/ags4-file.ts
-var Ags4File = class {
+var Ags4File = class _Ags4File {
   #reading;
-  // One arrow-js Table per group, decoded once on first `table(code)`.
+  // One RAW keyed arrow-js Table per group, decoded once (with _id/_parent_id
+  // for known groups). The relational `#register` reads these.
   #tables = /* @__PURE__ */ new Map();
+  // The key-stripped frame VIEW per group (a zero-copy projection of the raw
+  // Table), memoised so `table(code)` keeps returning the same instance.
+  #stripped = /* @__PURE__ */ new Map();
   // The DuckDB engine — created lazily on first sql()/at()/connection.
   #engine = null;
   // Memoised AGS4 re-emit (the `text`/`bytes` getters; the emit is O(size)).
   #text;
   #bytes;
-  constructor(reading) {
+  // The retained read source (for faithful chained re-runs) + the last verb
+  // outcomes: `#report` from `.validate()`, `#fixReport` on a `.fix()` result.
+  #src;
+  #report;
+  #fixReport;
+  // The `.ags.idx` certificate carried from `read(..., { index })`, and the check
+  // profile of the last `.validate()` engine run — so a following `.certify()`
+  // stamps what was actually checked (#294 Batch E / #14).
+  #cert;
+  #lastCheckFiles = false;
+  #lastForced = false;
+  constructor(reading, src) {
     this.#reading = reading;
+    this.#src = src;
+  }
+  /** @internal — `read(..., { index })` attaches a freshness-checked certificate
+   * so a later errors-only `.validate()` can skip the rule engine. */
+  _attachCert(cert) {
+    this.#cert = cert;
   }
   // --- metadata (no Arrow decode) ------------------------------------------
   /** Group codes in file order. */
@@ -252,12 +396,15 @@ var Ags4File = class {
     if (m === null) throw new Error(`group ${JSON.stringify(code)} not in file`);
     return m;
   }
+  /** The HEADING-row codes of `code`, in file order. Throws if `code` isn't in the file. */
   headings(code) {
     return this.#meta(code).headings;
   }
+  /** The UNIT row of `code`, one per heading. Throws if `code` isn't in the file. */
   units(code) {
     return this.#meta(code).units;
   }
+  /** The TYPE row of `code` (the AGS data types), one per heading. Throws if `code` isn't in the file. */
   types(code) {
     return this.#meta(code).types;
   }
@@ -269,15 +416,15 @@ var Ags4File = class {
   lineNumbers(code) {
     return this.#meta(code).lineNumbers;
   }
+  /** Whether `code` is one of the file's groups — the cheap membership check `headings`/`table` would otherwise throw on. */
   has(code) {
     return this.#reading.meta(code) !== null;
   }
   // --- born-typed data (Arrow-direct) --------------------------------------
-  /** 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) {
+  /** The raw keyed Table straight from IPC — a KNOWN group carries the two
+   * content-addressed key columns `_id`/`_parent_id` first (#303). Cached; both
+   * the frame accessor and the relational `#register` read it. */
+  #rawTable(code) {
     const cached = this.#tables.get(code);
     if (cached !== void 0) return cached;
     const ipc = this.#reading.tableIpc(code);
@@ -286,6 +433,24 @@ var Ags4File = class {
     this.#tables.set(code, table);
     return table;
   }
+  /** 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.
+   *
+   * 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, opts) {
+    const raw = this.#rawTable(code);
+    if (opts?.keys) return raw;
+    let stripped = this.#stripped.get(code);
+    if (stripped === void 0) {
+      stripped = stripSynthKeys(raw);
+      this.#stripped.set(code, stripped);
+    }
+    return stripped;
+  }
   // --- emit / save ---------------------------------------------------------
   /** Spec-correct AGS4 as text — byte-faithful to the source DATA values
    * (re-emitted native-side from the retained parse). Memoised. */
@@ -296,19 +461,165 @@ var Ags4File = class {
   get bytes() {
     return this.#bytes ??= Buffer.from(this.text, "utf8");
   }
-  /** 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) {
     writeFileSync(path, this.bytes);
     return path;
   }
+  // --- fluent verbs (validate / fix / diff) --------------------------------
+  /** Resolve this handle to the `(source, opts)` the free fns take: the retained
+   * read source (so line numbers match the original), or the re-emit for a
+   * synthesised handle. `text` is not re-encoded; a path/bytes source carries its
+   * read `encoding`. */
+  #freeSource() {
+    const s = this.#src;
+    if (s?.path !== void 0) return [s.path, { encoding: s.encoding }];
+    if (s?.text !== void 0) return [void 0, { text: s.text }];
+    if (s?.data !== void 0) return [s.data, { encoding: s.encoding }];
+    return [this.bytes, {}];
+  }
+  /** The last `.validate()` outcome (`undefined` until validated). */
+  get report() {
+    return this.#report;
+  }
+  /** The `FixResult` on a handle returned by `.fix()` (`undefined` otherwise). */
+  get fixReport() {
+    return this.#fixReport;
+  }
+  /** 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 = {}) {
+    const warnings = opts.warnings ?? true;
+    const fyi = opts.fyi ?? false;
+    const checkFiles = opts.checkFiles ?? false;
+    if (this.#cert !== void 0 && !warnings && !fyi && this.#cert.matchesNativeValidator() && this.#cert.profileCovers(checkFiles, opts.dictVersion)) {
+      this.#report = Report.fromCert(this.#cert, this.#srcLabel());
+      return this;
+    }
+    this.#lastCheckFiles = checkFiles;
+    this.#lastForced = opts.dictVersion !== void 0;
+    const [source, base] = this.#freeSource();
+    this.#report = validate(source, {
+      ...base,
+      ...opts,
+      encoding: opts.encoding ?? base.encoding
+    });
+    return 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 = {}) {
+    const [source, base] = this.#freeSource();
+    const result = fix(source, { ...base, ...opts, encoding: opts.encoding ?? base.encoding });
+    const repaired = new _Ags4File(parseArrow(void 0, void 0, result.bytes, void 0), {
+      data: result.bytes
+    });
+    repaired.#fixReport = result;
+    return repaired;
+  }
+  /** 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, opts = {}) {
+    return diff2(this, other, { ...opts, encoding: opts.encoding ?? this.#src?.encoding });
+  }
+  // --- certificate (.ags.idx) ----------------------------------------------
+  /** The ORIGINAL source bytes — what a certificate indexes + fingerprints, NOT
+   * the spec-correct re-emit (which can differ from a non-canonically-formatted
+   * on-disk file). A path is re-read, raw bytes returned as-is, text UTF-8-encoded;
+   * a synthesised handle falls back to the re-emit. Mirrors `_source_bytes`. */
+  #sourceBytes() {
+    const s = this.#src;
+    if (s?.path !== void 0) return readFileSync(s.path);
+    if (s?.data !== void 0) return s.data;
+    if (s?.text !== void 0) return Buffer.from(s.text, "utf8");
+    return this.bytes;
+  }
+  /** The `Report.fromCert` label for a certified verdict: the path, or a bytes/
+   * text sentinel. */
+  #srcLabel() {
+    const s = this.#src;
+    if (s?.path !== void 0) return s.path;
+    if (s?.data !== void 0) return "<bytes>";
+    return "<text>";
+  }
+  /** 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) {
+    if (this.#report === void 0) {
+      throw new Ags4Error(
+        "call .validate() before .certify() \u2014 certify records a passed validation, it does not run one"
+      );
+    }
+    if (!this.#report.isValid) {
+      throw new Ags4Error(
+        `cannot certify a file with ${this.#report.count} finding(s); fix them and re-validate clean first`
+      );
+    }
+    const srcPath = this.#src?.path;
+    const out = path ?? (srcPath !== void 0 ? `${srcPath}.idx` : void 0);
+    if (out === void 0) {
+      throw new Ags4Error(
+        "no source path to derive the .ags.idx location from; pass certify(path) for a handle read from text/bytes"
+      );
+    }
+    if (srcPath !== void 0 && resolve(out) === resolve(srcPath)) {
+      throw new Ags4Error(
+        `certify(path) is the .ags.idx OUTPUT location, not the file to certify \u2014 refusing to overwrite the source ${out}`
+      );
+    }
+    if (existsSync(out) && statSync(out).size > 0) {
+      const head = readFileSync(out).subarray(0, 64).toString("utf8").trimStart();
+      if (!head.startsWith("{")) {
+        throw new Ags4Error(
+          `refusing to overwrite ${out}: it is not a laterite certificate (certify writes or replaces an .ags.idx)`
+        );
+      }
+    }
+    const cert = Sidecar.assemble(
+      this.#sourceBytes(),
+      this.#report.dictVersion,
+      (/* @__PURE__ */ new Date()).toISOString(),
+      void 0,
+      void 0,
+      void 0,
+      this.#lastCheckFiles,
+      this.#lastForced
+    );
+    writeFileSync(out, cert.toJson());
+    return out;
+  }
   // --- optional DuckDB engine (sql / at / connection) ----------------------
   async #getEngine() {
     if (this.#engine === null) this.#engine = await DuckEngine.create();
     return this.#engine;
   }
-  /** Load one group into the engine on demand (CTAS from its born-typed Table). */
+  /** Load one group into the engine on demand (CTAS from its born-typed Table).
+   * Uses the RAW keyed Table so the relational layer carries `_id`/`_parent_id`
+   * (the accessor strips them; the engine keeps them for joins). */
   async #register(code, engine) {
-    await engine.register(code, this.#meta(code), this.table(code));
+    await engine.register(code, this.#meta(code), this.#rawTable(code));
   }
   async #registerAll(engine) {
     for (const code of this.groups) await this.#register(code, engine);
@@ -322,7 +633,11 @@ var Ags4File = class {
    * 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, values) {
     return new AgsSubset(this, [[`${group}_ID`, [...values]]]);
   }
@@ -353,7 +668,9 @@ var Ags4File = class {
       }
     }
     const where = clauses.length > 0 ? clauses.join(" AND ") : "TRUE";
-    const sql = `SELECT * FROM ${quoteId(code)} WHERE ${where}`;
+    const keyed = this.#rawTable(code).schema.fields.some((f) => f.name === "_id");
+    const select = keyed ? "* EXCLUDE (_id, _parent_id)" : "*";
+    const sql = `SELECT ${select} FROM ${quoteId(code)} WHERE ${where}`;
     return opts.arrow ? engine.queryArrow(sql, params) : engine.query(sql, params);
   }
   // --- lifecycle -----------------------------------------------------------
@@ -366,9 +683,11 @@ var Ags4File = class {
       this.#engine = null;
     }
   }
+  /** `using f = read(…)` disposal hook — delegates to `close()`. */
   [Symbol.dispose]() {
     this.close();
   }
+  /** A compact one-line summary — group count and `TRAN_AGS` — for logs and the REPL. */
   toString() {
     return `<Ags4File groups=${this.groups.length} tranAgs=${JSON.stringify(this.tranAgs)}>`;
   }
@@ -377,13 +696,15 @@ var Ags4File = class {
 // ts/build-result.ts
 import { writeFileSync as writeFileSync2 } from "fs";
 var BuildResult = class {
-  constructor(bytes, findings, fixesApplied) {
+  constructor(bytes, findings, applied, fixesApplied) {
     this.bytes = bytes;
     this.findings = findings;
+    this.applied = applied;
     this.fixesApplied = fixesApplied;
   }
   bytes;
   findings;
+  applied;
   fixesApplied;
   /** The AGS4 document decoded as text. */
   get text() {
@@ -430,24 +751,6 @@ var FixResult = class {
   }
 };
 
-// ts/native.ts
-import {
-  version,
-  parseArrow,
-  runCheck,
-  fixFile,
-  listRules,
-  emitAgs4FromIpc,
-  Reading,
-  canonicalType,
-  displayHint,
-  parseValue,
-  transportPack,
-  transportUnpack,
-  transportLock,
-  transportUnlock
-} from "#native";
-
 // ts/registry.ts
 var registry_exports = {};
 __export(registry_exports, {
@@ -455,6 +758,7 @@ __export(registry_exports, {
   GroupDescriptor: () => GroupDescriptor,
   ancestorChain: () => ancestorChain,
   childGroups: () => childGroups,
+  dictionary: () => dictionary,
   get: () => get,
   inheritedKeyNames: () => inheritedKeyNames,
   isKeyStatus: () => isKeyStatus
@@ -26226,9 +26530,13 @@ var GroupDescriptor = class {
   get view() {
     return `v_${this.code.toLowerCase()}`;
   }
+  /** This group's KEY headings (status part-matched via {@link isKeyStatus}), in
+   * declaration order. */
   get keyHeadings() {
     return this.headings.filter((h) => isKeyStatus(h.status));
   }
+  /** This group's non-KEY headings — the complement of {@link keyHeadings} — in
+   * declaration order. */
   get nonKeyHeadings() {
     return this.headings.filter((h) => !isKeyStatus(h.status));
   }
@@ -26239,6 +26547,9 @@ var GROUPS = Object.freeze(
 function get(code) {
   return GROUPS[code];
 }
+function dictionary(edition) {
+  return JSON.parse(registryDictionaryJson(edition));
+}
 function childGroups(parentCode) {
   return Object.values(GROUPS).filter((g) => g.parent === parentCode).sort((a, b) => a.code.localeCompare(b.code));
 }
@@ -26255,67 +26566,21 @@ function ancestorChain(code) {
   return chain;
 }
 function inheritedKeyNames(code) {
+  const g = GROUPS[code];
+  if (g === void 0) {
+    throw new Ags4Error(`unknown group code: ${JSON.stringify(code)}`);
+  }
   const names = /* @__PURE__ */ new Set();
-  for (const ancestor of ancestorChain(code).slice(1)) {
-    for (const h of GROUPS[ancestor].keyHeadings) names.add(h.name);
+  if (g.parent === null) return names;
+  const parent = GROUPS[g.parent];
+  if (parent === void 0) return names;
+  const parentKeys = new Set(parent.keyHeadings.map((h) => h.name));
+  for (const h of g.keyHeadings) {
+    if (parentKeys.has(h.name)) names.add(h.name);
   }
   return names;
 }
 
-// ts/report.ts
-var Report = class {
-  #r;
-  constructor(r) {
-    this.#r = r;
-  }
-  get file() {
-    return this.#r.file;
-  }
-  get dictVersion() {
-    return this.#r.dictVersion;
-  }
-  get resolution() {
-    return this.#r.resolution;
-  }
-  get count() {
-    return this.#r.count;
-  }
-  /** `true` iff there are zero findings (distinct from the native `ok`, which
-   * only means "validatable"). */
-  get isValid() {
-    return this.#r.count === 0;
-  }
-  get exitCode() {
-    return this.#r.exitCode;
-  }
-  /** All findings, in `lat-check` order: `{rule, line?, group, desc, severity?}`. */
-  get findings() {
-    return this.#r.findings;
-  }
-  /** `{ "AGS Format Rule N": [{line?, group, desc, …}] }` — the spec-rule
-   * grouping (mirrors `Report.by_rule`). */
-  byRule() {
-    const out = {};
-    for (const f of this.#r.findings) {
-      const { rule, ...rest } = f;
-      (out[rule] ??= []).push(rest);
-    }
-    return out;
-  }
-  /** `{file, findings:{…}}` pretty-JSON — byte-identical to `lat-check --json`. */
-  toJson() {
-    return this.#r.json;
-  }
-  /** One flat `{rule, …}` per line — byte-identical to `lat-check --ndjson`. */
-  toNdjson() {
-    return this.#r.ndjson;
-  }
-  toString() {
-    const v = this.isValid ? "valid" : `${this.count} finding(s)`;
-    return `<Report ${JSON.stringify(this.file)} ${v} dict=${this.dictVersion}>`;
-  }
-};
-
 // ts/ags-group.ts
 var AgsGroup = class {
 };
@@ -31249,11 +31514,28 @@ function unlock(src, dest, password) {
 function read(source, opts = {}) {
   const path = typeof source === "string" ? source : void 0;
   const data = typeof source === "string" || source == null ? void 0 : source;
+  let handle;
   try {
-    return new Ags4File(parseArrow(path, opts.text, data, opts.encoding));
+    handle = new Ags4File(parseArrow(path, opts.text, data, opts.encoding), {
+      path,
+      text: opts.text,
+      data,
+      encoding: opts.encoding
+    });
   } catch (e) {
     throw fromNativeError(e);
   }
+  if (opts.index !== void 0) {
+    const cert = Sidecar.fromJson(readFileSync2(opts.index));
+    const srcBytes = data ?? (path !== void 0 ? readFileSync2(path) : Buffer.from(opts.text ?? "", "utf8"));
+    if (!cert.isFreshFor(srcBytes)) {
+      throw new StaleCertError(
+        `certificate ${opts.index} is stale for this file \u2014 its size / SHA-256 differ; rebuild it with read(...).validate().certify()`
+      );
+    }
+    handle._attachCert(cert);
+  }
+  return handle;
 }
 function validate(source, opts = {}) {
   const path = typeof source === "string" ? source : void 0;
@@ -31303,20 +31585,50 @@ function walkTree(root) {
     }
   };
   visit(root);
+  for (const [code, rows] of buckets) {
+    const desc = get(code);
+    for (const h of desc.headings) {
+      if (isKeyStatus(h.status)) continue;
+      if (rows.every((r) => r[h.name] == null)) {
+        for (const r of rows) delete r[h.name];
+      }
+    }
+  }
   return [...buckets];
 }
+function checkMeta(meta, name, columns) {
+  if (meta === void 0) return;
+  for (const [code, hmap] of Object.entries(meta)) {
+    const known = columns.get(code);
+    if (known === void 0) {
+      throw new Ags4Error(`buildAgs4 ${name}: unknown group ${JSON.stringify(code)}`);
+    }
+    for (const heading of Object.keys(hmap)) {
+      if (!known.has(heading)) {
+        throw new Ags4Error(
+          `buildAgs4 ${name}: group ${JSON.stringify(code)} has no heading ${JSON.stringify(heading)}`
+        );
+      }
+    }
+  }
+}
 function buildAgs4(groups, opts = {}) {
   const items = groups instanceof AgsGroup ? walkTree(groups) : groups instanceof Map ? [...groups] : groups;
-  const ipcGroups = items.map(([code, data]) => {
-    const table = Array.isArray(data) ? rowsToTable(data) : data;
-    return { code, ipc: Buffer.from(tableToIPC(table, "stream")) };
-  });
-  const res = emitAgs4FromIpc(ipcGroups, opts.dictVersion, opts.mode);
+  const ipcGroups = [];
+  const columns = /* @__PURE__ */ new Map();
+  for (const [code, data] of items) {
+    const table = stripSynthKeys(Array.isArray(data) ? rowsToTable(data) : data);
+    columns.set(code, new Set(table.schema.fields.map((f) => f.name)));
+    ipcGroups.push({ code, ipc: Buffer.from(tableToIPC(table, "stream")) });
+  }
+  checkMeta(opts.units, "units", columns);
+  checkMeta(opts.types, "types", columns);
+  const res = emitAgs4FromIpc(ipcGroups, opts.dictVersion, opts.mode, opts.units, opts.types);
   const byRule = JSON.parse(res.findingsJson);
   const findings = Object.entries(byRule).flatMap(
     ([rule, list]) => list.map((f) => ({ rule, ...f }))
   );
-  return new BuildResult(res.bytes, findings, res.fixesApplied);
+  return new BuildResult(res.bytes, findings, res.applied, res.fixesApplied);
 }
 function listRules2() {
   return JSON.parse(listRules()).rules;
@@ -31328,6 +31640,33 @@ function fix(source, opts = {}) {
   if (!r.ok) throw makeError(r.errorKind ?? "", r.exitCode, r.error ?? "unknown error");
   return new FixResult(r.fixed, r.residual, r.applied, r.dictVersion);
 }
+function diffBytes(x) {
+  if (x instanceof Ags4File) return x.bytes;
+  if (typeof x !== "string") return x;
+  try {
+    return readFileSync2(x);
+  } catch (e) {
+    if (e && typeof e === "object" && e.code === "ENOENT") {
+      throw new FileNotFoundError(`No such file or directory: ${x}`, 3);
+    }
+    throw e;
+  }
+}
+function diff2(a, b, opts = {}) {
+  const aBytes = diffBytes(a);
+  const bBytes = diffBytes(b);
+  try {
+    return JSON.parse(diff(aBytes, bBytes, opts.dictVersion, opts.encoding));
+  } catch (e) {
+    throw fromNativeError(e);
+  }
+}
+function toExcel(agsPath, xlsxPath, opts = {}) {
+  return ags4ToExcel(agsPath, xlsxPath, opts.groups);
+}
+function fromExcel(xlsxPath, agsPath, opts = {}) {
+  return excelToAgs4(xlsxPath, agsPath, opts.formatNumericColumns);
+}
 export {
   AAVT,
   ABBR,
@@ -31498,6 +31837,7 @@ export {
   SHBT,
   STND,
   SUCT,
+  StaleCertError,
   TNPC,
   TRAN,
   TREG,
@@ -31517,10 +31857,13 @@ export {
   WSTG,
   ags_types_exports as agsTypes,
   buildAgs4,
+  diff2 as diff,
   fix,
+  fromExcel,
   listRules2 as listRules,
   read,
   registry_exports as registry,
+  toExcel,
   transport_exports as transport,
   validate,
   version