Skip to content

Certify a clean file & skip re-validation

Available in: Python · Node · CLI · Browser

Mint an .ags.idx certificate from a clean validation, then reopen with it to skip the rule engine.

# what this shows: the certify fast-path — a fresh .ags.idx cert lets validate() skip the rule engine.
import shutil
import tempfile
from pathlib import Path

import laterite

with tempfile.TemporaryDirectory() as tmp:
    tmp_path = str(Path(tmp) / "site.ags")
    shutil.copy("examples/sample_site.ags", tmp_path)

    # certify() runs the validation itself and mints <path>.ags.idx for an error-clean file.
    idx = laterite.read(tmp_path).certify()

    # re-reading with the fresh cert lets validate() answer without running the rule engine.
    ags = laterite.read(tmp_path, index=str(idx)).validate(warnings=False)

    print(ags.report.certified, ags.report.resolution)
    # `certified` says the ENGINE was skipped; `resolution` still says which dictionary judged it.
    assert ags.report.certified

certified

.certify() needs a prior clean .validate() on the same handle — a passing verdict is the precondition for issuing a cert. It writes <path>.ags.idx next to the file: a validity certificate (the verdict plus a hash of the bytes it vouches for) and a byte-offset index of every group.

Reopen with read(path, index=...) and the next .validate() resolves from the cert instead of running the numbered rules. You can see it took the fast path on .report.resolution: "certified" means the cert matched the file's current bytes, so the rule engine was skipped entirely. (A normal validate reports "exact" or a fallback edition — see Validate.)

// what this shows: the certify fast-path — a fresh .ags.idx cert lets validate() skip the rule engine.
import { read } from "laterite";
import assert from "node:assert/strict";
import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const tmp = mkdtempSync(join(tmpdir(), "laterite-docs-"));
const site = join(tmp, "site.ags");
copyFileSync("examples/sample_site.ags", site);

// certify() runs the validation itself and mints <path>.ags.idx for an error-clean file.
const idx = read(site).certify();

// Re-reading with the fresh cert lets validate() answer without running the rule engine.
const ags = read(site, { index: idx }).validate({ warnings: false });
// `certified` says the ENGINE was skipped; `dictVersion` still says which dictionary judged it.
console.log(ags.report.certified, ags.report.dictVersion);

assert.equal(ags.report.certified, true);
rmSync(tmp, { recursive: true, force: true });

certified

The same lifecycle, the same file format: certify() after a clean validate() mints <path>.ags.idx, and read(path, { index }) + validate() resolves from it with report.resolution === "certified". The cert wraps the one core Sidecar, so a Node-minted .ags.idx is byte-compatible with the ones Python, DuckDB and lat mint — any surface can consume any surface's cert.

The laterite_ags4 DuckDB extension is a read-only reader — it doesn't mint certificates. Certify with lat certify or the library (the tabs above); read_ags then consumes the resulting <path>.ags.idx beside the file to range-read a single group's bytes instead of parsing the whole file. See the DuckDB function reference.

lat certify site.ags

certificate written to site.ags.idx

certify mints the certificate after the check comes back clean (a note: certificate written to site.ags.idx line reports where; point it elsewhere with --out). A dirty file gets no cert — the findings table and exit 1 come back instead.

Validate a clean file in the web app and it offers the .ags.idx certificate as a download — minted by the same wasm engine, byte-compatible with every other surface, so a file certified in the browser opens on the fast path in Python, Node, or DuckDB.

The cert is content-bound: if the file changes by a single byte, the hash no longer matches and laterite silently falls back to a full validation — a stale cert never yields a false "clean". So certify is a cache, not a trust override: fast when the file is untouched, correct when it isn't.

See also: Certificate lifecycle · Validate.