Skip to content

Intermediate Representation

When a schema is compiled, it is lowered to an Intermediate Representation (IR): a flat, structured, language-neutral form of everything the schema declares. The IR is the thing every later stage works on — it is what gets stored, versioned, diffed and fed to code generators. Nothing downstream ever looks at .ids source again.

What it contains

A compiled schema becomes a sequence of frozen units — one per declaration:

  • Namespace and Import: where the schema sits, and what it brings in
  • Struct, Enum, Error, TypeAlias, Constant: the data shapes, with their fields or variants, structured types, defaults and annotations
  • Protocol: its functions, with typed arguments, returns and the errors each raises
  • Validator, Settings: checks, and the schema's settings blocks

The package manifest lowers to units too (SpecificationVersion, Dependency, CodeGeneration, PublishRegistry), so a frozen version carries both the schema API and the declarations around it.

"Frozen" is literal: a unit is immutable once written, and it is addressed by the hash of its content. What's stored has the exact layout.

Where it goes

comline build writes the frozen units into the project's content-addressable store under .comline/, as one commit in an append-only chain. Each commit records a root tree (the schemas' units plus the package's config, docs and facts), its parent (two after a reconciled merge), an author, a timestamp, a generated message and the package version, and a release adds its release record. The CAS guide has every field.

Because the store is content-addressed and never rewritten, any past version stays reproducible, and two versions can be compared unit-by-unit at any time — that comparison is what drives Comline's automatic versioning and comline diff.