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

True exact

.certify() runs the validation itself, with every severity tier on, and records what the rules actually returned — no prior .validate() is needed. 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. Two separate fields tell you what happened: .report.certified is True when the cert matched the file's current bytes and the rule engine was skipped, and .report.resolution reports how the dictionary edition was resolved ("exact" or a fallback — 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 });

true 4.1.1

The same lifecycle, the same file format: certify() validates and mints <path>.ags.idx in one step, and read(path, { index }) + validate() resolves from it with report.certified === true. 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 certificate written to site.ags.idx line reports where; point it elsewhere with --out). A file with error-severity findings gets no cert: a single error: line explains why and points you at lat validate <file> for the findings table, and the exit code is 1.

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.