RFC-0010 IR serialization proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: proposed first-release decision. Owners: Compiler and Runtime. Nothing is deployed, so the choice requires source and artifact changes rather than a live payload migration.
Conflict and evidence
RFC-0010 §4.6 makes Rust structs in gnomon-ir the normative schema, with
rkyv for persisted bundle bytes and serde_json for TypeScript tooling.
This IR crosses file, runtime, WASM, and language boundaries. The workspace’s
DTO preference is protobuf for those boundaries unless a project schema layer
is already established. A search of the extracted Gnomon repository found no
gnomon-ir crate or implemented canonical IR schema, so the first release can
choose its serialized contract before consumers depend on it. RFC-0010 also
requires byte-for-byte deterministic extraction while placing extracted_at
in the IR without defining how that timestamp is fixed across identical runs.
Recommended first-release contract
Make a versioned .proto schema the canonical contract for serialized IR and
compiled bundle interchange. Generate Rust and TypeScript bindings from it.
Persist a deterministic protobuf envelope with an explicit schema version and
source fingerprint. Keep any rkyv archived representation as a derived,
rebuildable in-process cache for Rust/WASM hot paths; do not make its bytes the
cross-version or cross-language contract. Define extracted_at as external
build provenance in a separate manifest, or derive it from a declared stable
input so identical sources and options yield identical IR bytes. JSON may be
emitted from the protobuf schema for inspection and tooling, with a single
specified JSON mapping.
This would change RFC-0010’s normative source of truth, compiled bundle
format, versioning, and consumer code. It may add a decode or cache-build step
at kernel startup and needs a measured WASM startup/memory budget. The
alternative is to retain normative Rust structs, persisted rkyv, and
derived serde JSON. That matches the current RFC’s zero-copy design but
requires an explicit exception to the workspace protobuf preference and a
tested archive compatibility story across compiler and runtime versions.
Acceptance
- Decide one canonical schema and wire identity before publishing a bundle format. Align RFC-0010 prose, Lean statements, RDF projections, reference catalog, and bundle manifest in RFC-0002.
- Build deterministic encode/decode and version-skew fixtures spanning the compiler, installer, Rust kernel, WASM kernel, and TypeScript tooling. Verify that the same source and declared options produce identical IR bytes; keep non-deterministic build timestamps outside that digest.
- Measure startup decode/cache cost and document the supported schema-version range and failure diagnostic. Refresh source-bound proof and projection reviews after the normative change.