canon

Overview ¶

ast.go — the internal canonicalization AST and its builder.

The canonicalizer is deliberately schema-agnostic (spec §8: "it doesn't care about semantic meaning, just structure"). It therefore works on a generic tree mirroring arbitrary TOML structure, NOT on the typed pod.Spec — it must, for example, reject hand-authored `_`-prefixed keys that no typed struct would even surface.

The tree is built from BurntSushi/toml's decode into a generic map. That decode is faithful enough for canonicalization because:

• integers arrive as int64, floats as float64, datetimes as time.Time — type identity is preserved;
• inline tables and `[table]` headers both decode to a map, which is exactly what R11 wants (inline tables are expanded to tables);
• array-of-tables (`[[x]]`) decodes to []map[string]interface{}, while every other array — including an array of inline-table literals — decodes to []interface{}. That type split is the sole, reliable signal distinguishing R13 array-of-tables from the R-less array-of-inline-tables construct v1 rejects.

Package canon implements konareef-toml/v1: the canonical TOML serializer and the pod-hash construction it feeds.

A pod's pod.toml may be authored in any of TOML's many equivalent spellings — key order, comments, whitespace, integer bases, string quoting, datetime precision. canon collapses all of them to one byte-exact form so that two semantically identical pods always produce the same SHA-256 pod_hash, and any later tampering changes it. This package is the Go reference implementation of the canonical TOML rule set used for pod hashing.

Public surface:

• Canonicalize — pod.toml bytes + pod directory → canonical bytes
• CanonicalizeWithWarnings — same, plus non-fatal advisories
• PodHash — the SHA-256 of the canonical bytes
• Error / Code — the stable, machine-readable failure codes
• Warning — a non-fatal advisory

Every failure is fatal and total: on any rejection the canonicalizer returns a *canon.Error and no output. There is no partial or best-effort result — a pod either has one canonical form or none.

commitparse.go — verifier-side parser for the konareef-toml/v2 `[_commit]` trailer's `fields_root` commitment.

This is the reverse of fieldsroot.go's producer: where FieldsRoot COMPUTES the Poseidon commitment from the four manifest fields, this file READS the already-committed value straight out of a canonical-v2 manifest's final `[_commit]` section. The CL-5(a) verifier needs it to bind `[_commit].fields_root` to the proof's carried genesis lane (genesis_fields_root) without recomputing canon.FieldsRoot — the disclosed manifest is h_manifest-bound, so its committed fields_root is itself bound to the proven computation.

errors.go — fatal canonicalization failures.

Every canonicalizer rejection is fatal: no partial output is ever produced. An Error carries a stable, machine-readable Code (the strings frozen in konareef-toml/v1 spec §7) plus a human-readable Message that callers may surface but MUST NOT pattern-match on — only Code is contractually stable.

fieldsroot.go — the konareef-toml/v2 manifest field-commitment (`fields_root`), issue #3 item #4 slice 4a. The canonicalizer commits the four manifest fields the pod-step circuit consumes (declared_models, declared_tools, c_max, r_init) into a Poseidon `fields_root` the circuit can prove inclusion against (PRD 1 §5.3 Approach B), instead of parsing canonical TOML text in-circuit. The construction is byte-identical to the in-circuit inclusion gadget (4b) and reuses internal/poseidon throughout.

files.go — the synthetic `[_files]` manifest section (R15).

After the author tree, the canonicalizer appends a `[_files]` section binding the manifest hash to every other file in the pod directory. This is what defeats the swap-after-signing attack: an adversary cannot alter prompts/system.md without changing pod_hash.

The walk is intentionally strict. Symlinks are a hard failure, never a silent skip — a symlink can escape the pod directory and pull an arbitrary host file into the signed set. `.gitignore` is NOT honored: a hidden input that two publishers configure differently would let identical content produce different hashes, the exact non-determinism the canonicalizer exists to eliminate. The 1 MiB size cap is the tripwire for accidental bloat instead.

serialize.go — the deterministic byte emitter (rules R3–R14).

Serialization is a total function on the AST: given an admissible tree it produces exactly one byte sequence. Every formatting choice the spec leaves to "one canonical form" is resolved here.

Table headers are emitted in one global order: ascending over the UTF-8 byte encoding of each table's full dotted key path (R5). The emitter flattens the whole plain-table forest into that single sort rather than walking it depth-first — the two differ whenever a sibling key sorts between a parent and the parent's children (`-`, 0x2D, sorts before the `.`, 0x2E, that joins a child path), and the global sort is the canonical one.

Array-of-tables are the exception: their entries are positional, and a table nested inside an entry stays contiguous with that entry. Each entry is therefore its own emission scope with its own local sort.

Within any table, scalar (and array) fields are emitted before any sub-table header: TOML attaches every `key = value` line after a `[header]` to that header, so scalars must precede the first sub-table. A parent's dotted path is always a proper prefix of its children's, so the global sort always emits a parent header before the children that depend on it.

validate.go — the domain-rejection gates of konareef-toml/v1.

These run after TOML parsing and AST construction, before any serialization (spec §4 step 3). Each gate corresponds to a row in the spec §7 failure table. The first violation found aborts the whole canonicalization — there is no partial output and no issue list, unlike pod.Validate.

Integer range is not gated here: BurntSushi/toml decodes integers into int64 and rejects an out-of-i64-range literal at parse time, so an over-range integer surfaces as TOML_PARSE_ERROR before this file runs. The spec §7 documents that behavior; there is no separate INT_OVERFLOW code.