gnomonlearn
Docs/RFC-0010 IR serialization proposal

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.

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

  1. 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.
  2. 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.
  3. 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.