RFC-0010 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0010: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0010.This page is generated from the
lean/Gnomon/Spec/module for RFC-0010. Edit that source and regenerate this catalog.
Title: Canonical IR and Runtime Architecture
Status: draft
Owners: AI Platform, Compiler, Runtime
Extended by: RFC-0048
Proof citations in source: 20 / 20. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Canonical Semantic IR | The normalized intermediate representation produced by extracting semantic facts from existing codebases (TypeScript, OpenAPI, etc.), used for model training and codebase-to-Gnomon migration. |
| Capability (Cap) | An unforgeable zero-sized type with private constructor representing authority to perform a specific action; only the kernel can mint capabilities. |
| Capability attenuation | One-directional narrowing of a capability to a subset of its original authority before passing to a sub-component. |
| Command | A request to change state; cannot commit state. |
| Effect | External I/O initiated from a committed event; cannot commit state directly. |
| Event | A committed fact produced by the kernel; only the kernel may produce events. |
| Knowledge Index | A lazily-computed, cached query structure built over the assembled semantic graph that answers one class of cross-declaration question; compiler-internal and not part of the compiled bundle. |
| Patch | A visual update derived from an event; cannot commit state. |
| Proposal | A model suggestion requiring kernel acceptance via human-confirmed command. |
| Runtime Architecture | The event-sourced, multi-worker architecture for executing Gnomon applications, including kernel, surface, model worker, and capability broker boundaries. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M10040 | Fatal | Kernel bundle fingerprint does not match installed storage manifest fingerprint — startup halted |
M10041 | Error | Kernel rollback crosses breaking schema change boundary without storage migration |
M10042 | Error | Persistence adapter attempted validation — forbidden (kernel domain only) |
M10043 | Error | Kernel artifact references schema object not present in installed storage manifest |
M10044 | Error | Event log entry found with no corresponding storage write — replay required |
M10045 | Fatal | Kernel WASM module missing required export — startup rejected |
M10046 | Error | Kernel ABI version mismatch between runtime expectation and kernel export |
M10047 | Error | gnomon_kernel_submit returned negative code — command rejected; includes KernelError payload |
M10048 | Error | out_capacity insufficient for kernel output; call aborted |
M10050 | Warning | Low-confidence IR-to-Gnomon mapping emitted as draft — requires author confirmation before activation |
M10051 | Warning | IR symbol cannot be mapped to any RFC-0006 type kind — emitted as unclassified |
M10052 | Error | Migration tooling emitted low-confidence declaration without draft comment wrapper (forbidden) |
M10060 | Info | Older canonical IR schema_version loaded; compatibility shim applied |
M10900 | Warning | Symbol extraction failed (TypeChecker error); symbol emitted with reduced confidence |
M10901 | Warning | Framework convention detection produced ambiguous result |
M10902 | Warning | Round-trip consistency score below threshold |
M10910 | Error | Component attempted direct state mutation (forbidden) |
M10911 | Error | Model worker emitted event (not a proposal) — forbidden |
M10912 | Error | Effect attempted to commit state directly |
M10913 | Error | Command failed kernel validation (diagnostic includes violated invariant ID) |
Dependency neighborhood
graph LR
nRFC_0010["RFC-0010"]
nRFC_0048["RFC-0048"]
nRFC_0048 --> nRFC_0010
Invariants
- A kernel WASM module that does not export all required ABI functions must be rejected at startup. (enforced by: boot-time)
- Capability attenuation is one-directional: authority may be reduced, never amplified. (enforced by: compile-time)
- Components must not mutate state directly; all mutations are commands routed to the kernel. (enforced by: runtime)
- Effects must not commit state directly and must be initiated only from committed events. (enforced by: runtime)
- Every command must pass kernel validation before producing a committed event. (enforced by: runtime)
- Every extracted symbol must reference its source span for traceability.
- Installed kernel bundle fingerprint must match installed storage manifest fingerprint at startup. (enforced by: boot-time)
- Kernel ABI function signatures must not change within a schema_version; removing or changing required exports increments schema_version.
- Models must not commit domain facts; they may only emit proposals. (enforced by: runtime)
- Older canonical IR archives with lower schemaVersion must remain loadable by newer tooling via a registered compatibility shim.
- The canonical IR must be deterministic: the same source produces the same IR across runs.
- The canonical IR must store normalized semantic facts, not raw AST nodes.
- The event log must be appended before any storage write so failed storage writes can be replayed. (enforced by: runtime)
- The kernel must be the sole source of committed events. (enforced by: runtime)
- The kernel must not write to storage directly; storage writes belong to the persistence adapter. (enforced by: runtime)
- The persistence adapter must not perform validation; validation is the kernel’s exclusive domain. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Canonical Semantic IR
- SHOULD — Candidate IR extractions SHOULD be scored by round-trip consistency for unsupervised quality filtering.
- MUST — IR concepts MUST be mapped to RFC-0006 type kinds for migration to Gnomon.
- MUST_NOT — Migration tooling MUST NOT emit low-confidence mappings as normative authoring declarations without explicit author confirmation. (proof citation:
rfc0010_b22_grounded; verification pending) - MUST — Migration tooling MUST validate suggested_kind annotations against the normative mapping table and produce a diagnostic when ambiguously classified. (proof citation:
rfc0010_b35_grounded; verification pending) - MUST — Older rkyv archives with lower schemaVersion MUST remain loadable by newer tooling via a registered compatibility shim.
- MUST — TypeScript tooling MUST consume the serde JSON form of the canonical IR; MUST NOT parse rkyv binary directly.
- MUST — schemaVersion MUST be incremented on any breaking change to the IR struct set. (proof citation:
rfc0010_b7_grounded; verification pending)
Compatibility and Migration
- MUST — Canonical IR format changes MUST be versioned; older IR MUST remain parseable by newer tooling.
- MUST — Schema changes produce new kernel versions and MUST go through the install plan diff (RFC-0005). (proof citation:
rfc0010_b19_grounded; verification pending)
Invariants
- MUST — Canonical IR MUST be deterministic: same source produces same IR across runs.
- MUST — Canonical IR MUST store normalized semantic facts, not raw AST nodes.
- MUST_NOT — Components MUST NOT mutate state directly; mutations are routed as commands to the kernel.
- MUST_NOT — Effects MUST NOT commit state directly; they MUST be initiated from committed events. (proof citation:
rfc0010_b15_grounded; verification pending) - MUST — Every command MUST pass kernel validation before producing a committed event. (proof citation:
rfc0010_b50_grounded; verification pending) - MUST — Every extracted symbol MUST reference its source span for traceability. (proof citation:
rfc0010_b37_grounded; verification pending) - MUST_NOT — Models MUST NOT commit domain facts; they may only emit proposals. (proof citation:
rfc0010_b47_grounded; verification pending) - MUST — The kernel MUST be the sole source of committed events.
Knowledge Index
- MUST — An index’s compute function MUST be a pure function of the model and MUST NOT modify the model.
- MUST — Compiler passes and codegen steps MUST obtain derived facts from named knowledge indexes rather than traversing the shape graph ad hoc. (proof citation:
rfc0010_b0_grounded; verification pending)
Runtime Architecture
- MUST_NOT — ABI function signatures MUST NOT change within a schema_version; removing or changing a REQUIRED export is breaking. (proof citation:
rfc0010_b26_grounded; verification pending) - MUST — Any kernel WASM module that does not export all REQUIRED ABI functions MUST be rejected at startup with M10045. (proof citation:
rfc0010_b3_grounded; verification pending) - MUST_NOT — Components MUST NOT mutate state.
- MUST_NOT — Effects MUST NOT commit state directly. (proof citation:
rfc0010_b53_grounded; verification pending) - MUST_NOT — Models MUST NOT mutate state. (proof citation:
rfc0010_b40_grounded; verification pending) - MUST — Only the kernel emits committed events.
- MUST — The caller MUST call gnomon_kernel_free with the original pointer and byte length after every successful kernel output read.
- MUST_NOT — Workers MUST NOT invent domain truth. (proof citation:
rfc0010_b24_grounded; verification pending)
Security and Authorization
- MUST — Effects MUST be declared in gnomon.effects; ad hoc network or filesystem access from workers MUST be blocked. (proof citation:
rfc0010_b29_grounded; verification pending) - MUST — Model proposals MUST be routed through the surface for human confirmation before becoming commands for high-authority actions. (proof citation:
rfc0010_b9_grounded; verification pending) - MUST — The kernel MUST be compiled from the install-plan bundle; runtime-modified kernels MUST NOT be trusted.
- MUST — The kernel MUST enforce all RFC-0005 and RFC-0009 authorization policies before emitting committed events. (proof citation:
rfc0010_b12_grounded; verification pending)
Storage-to-Kernel Integration Contract
- MUST — Bundle fingerprint mismatch between installed kernel and storage manifest MUST be detected and rejected at runtime startup (M10040). (proof citation:
rfc0010_b33_grounded; verification pending) - MUST — Claim evidence writes MUST use the storage strategy declared in the installed storage manifest. (proof citation:
rfc0010_b5_grounded; verification pending) - MUST — Kernel rollback crossing a breaking schema change boundary MUST be accompanied by a corresponding storage migration.
- MUST — The event log MUST be appended before any storage write to allow replay on storage failure.
- MUST — The install pipeline MUST apply schema operations and kernel deployment atomically within the same install plan execution.
- MUST — The kernel artifact MUST be versioned with the same fingerprint as the compiled bundle. (proof citation:
rfc0010_b45_grounded; verification pending) - MUST_NOT — The persistence adapter MUST NOT perform validation; the kernel MUST NOT write to storage directly.
Linked References
| Direction | Target |
|---|---|
| Extended by | RFC-0048 |