laterite 0.5.1 → 0.6.1

package/dist/index.cjs

@@ -189,6 +189,7 @@ __export(index_exports, {
   SHBT: () => SHBT,
   STND: () => STND,
   SUCT: () => SUCT,
+  StaleCertError: () => StaleCertError,
   TNPC: () => TNPC,
   TRAN: () => TRAN,
   TREG: () => TREG,
@@ -208,19 +209,24 @@ __export(index_exports, {
   WSTG: () => WSTG,
   agsTypes: () => ags_types_exports,
   buildAgs4: () => buildAgs4,
+  diff: () => diff2,
   fix: () => fix,
+  fromExcel: () => fromExcel,
   listRules: () => listRules2,
   read: () => read,
   registry: () => registry_exports,
+  toExcel: () => toExcel,
   transport: () => transport_exports,
   validate: () => validate,
   version: () => import_native.version
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_fs4 = require("fs");
 var import_apache_arrow3 = require("apache-arrow");
 
 // ts/ags4-file.ts
 var import_node_fs = require("fs");
+var import_node_path = require("path");
 var import_apache_arrow2 = require("apache-arrow");
 
 // ts/duckdb.ts
@@ -260,6 +266,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":
@@ -295,6 +307,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() {
@@ -334,11 +350,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));
       }
@@ -408,6 +432,80 @@ function toMicros(value) {
   return BigInt(Math.round(ms * 1e3));
 }
 
+// ts/native.ts
+var import_native = require("#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;
@@ -416,7 +514,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]]]);
   }
@@ -438,17 +545,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. */
@@ -464,12 +592,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;
   }
@@ -481,15 +612,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);
@@ -498,6 +629,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. */
@@ -508,19 +657,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) {
     (0, import_node_fs.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((0, import_native.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 (0, import_node_fs.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 && (0, import_node_path.resolve)(out) === (0, import_node_path.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 ((0, import_node_fs.existsSync)(out) && (0, import_node_fs.statSync)(out).size > 0) {
+      const head = (0, import_node_fs.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 = import_native.Sidecar.assemble(
+      this.#sourceBytes(),
+      this.#report.dictVersion,
+      (/* @__PURE__ */ new Date()).toISOString(),
+      void 0,
+      void 0,
+      void 0,
+      this.#lastCheckFiles,
+      this.#lastForced
+    );
+    (0, import_node_fs.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);
@@ -534,7 +829,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]]]);
   }
@@ -565,7 +864,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 -----------------------------------------------------------
@@ -578,9 +879,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)}>`;
   }
@@ -589,13 +892,15 @@ var Ags4File = class {
 // ts/build-result.ts
 var import_node_fs2 = require("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() {
@@ -642,9 +947,6 @@ var FixResult = class {
   }
 };
 
-// ts/native.ts
-var import_native = require("#native");
-
 // ts/registry.ts
 var registry_exports = {};
 __export(registry_exports, {
@@ -652,6 +954,7 @@ __export(registry_exports, {
   GroupDescriptor: () => GroupDescriptor,
   ancestorChain: () => ancestorChain,
   childGroups: () => childGroups,
+  dictionary: () => dictionary,
   get: () => get,
   inheritedKeyNames: () => inheritedKeyNames,
   isKeyStatus: () => isKeyStatus
@@ -26423,9 +26726,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));
   }
@@ -26436,6 +26743,9 @@ var GROUPS = Object.freeze(
 function get(code) {
   return GROUPS[code];
 }
+function dictionary(edition) {
+  return JSON.parse((0, import_native.registryDictionaryJson)(edition));
+}
 function childGroups(parentCode) {
   return Object.values(GROUPS).filter((g) => g.parent === parentCode).sort((a, b) => a.code.localeCompare(b.code));
 }
@@ -26452,67 +26762,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 {
 };
@@ -31446,11 +31710,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((0, import_native.parseArrow)(path, opts.text, data, opts.encoding));
+    handle = new Ags4File((0, import_native.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 = import_native.Sidecar.fromJson((0, import_node_fs4.readFileSync)(opts.index));
+    const srcBytes = data ?? (path !== void 0 ? (0, import_node_fs4.readFileSync)(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;
@@ -31500,20 +31781,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((0, import_apache_arrow3.tableToIPC)(table, "stream")) };
-  });
-  const res = (0, import_native.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((0, import_apache_arrow3.tableToIPC)(table, "stream")) });
+  }
+  checkMeta(opts.units, "units", columns);
+  checkMeta(opts.types, "types", columns);
+  const res = (0, import_native.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((0, import_native.listRules)()).rules;
@@ -31525,6 +31836,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 (0, import_node_fs4.readFileSync)(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((0, import_native.diff)(aBytes, bBytes, opts.dictVersion, opts.encoding));
+  } catch (e) {
+    throw fromNativeError(e);
+  }
+}
+function toExcel(agsPath, xlsxPath, opts = {}) {
+  return (0, import_native.ags4ToExcel)(agsPath, xlsxPath, opts.groups);
+}
+function fromExcel(xlsxPath, agsPath, opts = {}) {
+  return (0, import_native.excelToAgs4)(xlsxPath, agsPath, opts.formatNumericColumns);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AAVT,
@@ -31696,6 +32034,7 @@ function fix(source, opts = {}) {
   SHBT,
   STND,
   SUCT,
+  StaleCertError,
   TNPC,
   TRAN,
   TREG,
@@ -31715,10 +32054,13 @@ function fix(source, opts = {}) {
   WSTG,
   agsTypes,
   buildAgs4,
+  diff,
   fix,
+  fromExcel,
   listRules,
   read,
   registry,
+  toExcel,
   transport,
   validate,
   version