The .ags.idx certificate lifecycle

Validating a delivery runs the full rule engine. When you'll reopen the same file, a certificate lets you skip that work: a clean validate mints an .ags.idx sidecar recording a content hash + a byte index of every group. Reopen with a fresh, matching cert and .validate() resolves without re-running a single rule.

# 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 — it writes <path>.ags.idx next to the file. Re-reading with index= hands that cert back; because the file's content hash still matches the one baked into the cert, validate() returns immediately and report.resolution == "certified" instead of re-deriving the verdict from the rules.

The check is exact: the cert vouches for those bytes only. Edit one character and the hash no longer matches, so the cert is ignored and the rule engine runs as normal — a stale cert can never pass a changed file.

It vouches error-clean only

A certificate is minted from an error-clean validate (note warnings=False above). It says "this file has no rule errors" — it does not capture warnings or fyi-tier findings, which bypass it entirely. If you need to surface warnings, run a normal .validate(); the fast-path is for confirming error-cleanliness on a file you've already cleared.

The cert is also the same byte index that powers sliced reads (pull one group's rows without parsing the whole file) — one sidecar, two payoffs.

See also: Certify a clean file · Validate a delivery