gnomonlearn
Docs/RFC-0010/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Canonical Semantic IRThe 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 attenuationOne-directional narrowing of a capability to a subset of its original authority before passing to a sub-component.
CommandA request to change state; cannot commit state.
EffectExternal I/O initiated from a committed event; cannot commit state directly.
EventA committed fact produced by the kernel; only the kernel may produce events.
Knowledge IndexA 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.
PatchA visual update derived from an event; cannot commit state.
ProposalA model suggestion requiring kernel acceptance via human-confirmed command.
Runtime ArchitectureThe event-sourced, multi-worker architecture for executing Gnomon applications, including kernel, surface, model worker, and capability broker boundaries.

Diagnostics

CodeSeverityDescription
M10040FatalKernel bundle fingerprint does not match installed storage manifest fingerprint — startup halted
M10041ErrorKernel rollback crosses breaking schema change boundary without storage migration
M10042ErrorPersistence adapter attempted validation — forbidden (kernel domain only)
M10043ErrorKernel artifact references schema object not present in installed storage manifest
M10044ErrorEvent log entry found with no corresponding storage write — replay required
M10045FatalKernel WASM module missing required export — startup rejected
M10046ErrorKernel ABI version mismatch between runtime expectation and kernel export
M10047Errorgnomon_kernel_submit returned negative code — command rejected; includes KernelError payload
M10048Errorout_capacity insufficient for kernel output; call aborted
M10050WarningLow-confidence IR-to-Gnomon mapping emitted as draft — requires author confirmation before activation
M10051WarningIR symbol cannot be mapped to any RFC-0006 type kind — emitted as unclassified
M10052ErrorMigration tooling emitted low-confidence declaration without draft comment wrapper (forbidden)
M10060InfoOlder canonical IR schema_version loaded; compatibility shim applied
M10900WarningSymbol extraction failed (TypeChecker error); symbol emitted with reduced confidence
M10901WarningFramework convention detection produced ambiguous result
M10902WarningRound-trip consistency score below threshold
M10910ErrorComponent attempted direct state mutation (forbidden)
M10911ErrorModel worker emitted event (not a proposal) — forbidden
M10912ErrorEffect attempted to commit state directly
M10913ErrorCommand 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

  1. A kernel WASM module that does not export all required ABI functions must be rejected at startup. (enforced by: boot-time)
  2. Capability attenuation is one-directional: authority may be reduced, never amplified. (enforced by: compile-time)
  3. Components must not mutate state directly; all mutations are commands routed to the kernel. (enforced by: runtime)
  4. Effects must not commit state directly and must be initiated only from committed events. (enforced by: runtime)
  5. Every command must pass kernel validation before producing a committed event. (enforced by: runtime)
  6. Every extracted symbol must reference its source span for traceability.
  7. Installed kernel bundle fingerprint must match installed storage manifest fingerprint at startup. (enforced by: boot-time)
  8. Kernel ABI function signatures must not change within a schema_version; removing or changing required exports increments schema_version.
  9. Models must not commit domain facts; they may only emit proposals. (enforced by: runtime)
  10. Older canonical IR archives with lower schemaVersion must remain loadable by newer tooling via a registered compatibility shim.
  11. The canonical IR must be deterministic: the same source produces the same IR across runs.
  12. The canonical IR must store normalized semantic facts, not raw AST nodes.
  13. The event log must be appended before any storage write so failed storage writes can be replayed. (enforced by: runtime)
  14. The kernel must be the sole source of committed events. (enforced by: runtime)
  15. The kernel must not write to storage directly; storage writes belong to the persistence adapter. (enforced by: runtime)
  16. 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

  1. SHOULD — Candidate IR extractions SHOULD be scored by round-trip consistency for unsupervised quality filtering.
  2. MUST — IR concepts MUST be mapped to RFC-0006 type kinds for migration to Gnomon.
  3. 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)
  4. 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)
  5. MUST — Older rkyv archives with lower schemaVersion MUST remain loadable by newer tooling via a registered compatibility shim.
  6. MUST — TypeScript tooling MUST consume the serde JSON form of the canonical IR; MUST NOT parse rkyv binary directly.
  7. MUST — schemaVersion MUST be incremented on any breaking change to the IR struct set. (proof citation: rfc0010_b7_grounded; verification pending)

Compatibility and Migration

  1. MUST — Canonical IR format changes MUST be versioned; older IR MUST remain parseable by newer tooling.
  2. 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

  1. MUST — Canonical IR MUST be deterministic: same source produces same IR across runs.
  2. MUST — Canonical IR MUST store normalized semantic facts, not raw AST nodes.
  3. MUST_NOT — Components MUST NOT mutate state directly; mutations are routed as commands to the kernel.
  4. MUST_NOT — Effects MUST NOT commit state directly; they MUST be initiated from committed events. (proof citation: rfc0010_b15_grounded; verification pending)
  5. MUST — Every command MUST pass kernel validation before producing a committed event. (proof citation: rfc0010_b50_grounded; verification pending)
  6. MUST — Every extracted symbol MUST reference its source span for traceability. (proof citation: rfc0010_b37_grounded; verification pending)
  7. MUST_NOT — Models MUST NOT commit domain facts; they may only emit proposals. (proof citation: rfc0010_b47_grounded; verification pending)
  8. MUST — The kernel MUST be the sole source of committed events.

Knowledge Index

  1. MUST — An index’s compute function MUST be a pure function of the model and MUST NOT modify the model.
  2. 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

  1. 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)
  2. 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)
  3. MUST_NOT — Components MUST NOT mutate state.
  4. MUST_NOT — Effects MUST NOT commit state directly. (proof citation: rfc0010_b53_grounded; verification pending)
  5. MUST_NOT — Models MUST NOT mutate state. (proof citation: rfc0010_b40_grounded; verification pending)
  6. MUST — Only the kernel emits committed events.
  7. MUST — The caller MUST call gnomon_kernel_free with the original pointer and byte length after every successful kernel output read.
  8. MUST_NOT — Workers MUST NOT invent domain truth. (proof citation: rfc0010_b24_grounded; verification pending)

Security and Authorization

  1. 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)
  2. 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)
  3. MUST — The kernel MUST be compiled from the install-plan bundle; runtime-modified kernels MUST NOT be trusted.
  4. 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

  1. 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)
  2. MUST — Claim evidence writes MUST use the storage strategy declared in the installed storage manifest. (proof citation: rfc0010_b5_grounded; verification pending)
  3. MUST — Kernel rollback crossing a breaking schema change boundary MUST be accompanied by a corresponding storage migration.
  4. MUST — The event log MUST be appended before any storage write to allow replay on storage failure.
  5. MUST — The install pipeline MUST apply schema operations and kernel deployment atomically within the same install plan execution.
  6. MUST — The kernel artifact MUST be versioned with the same fingerprint as the compiled bundle. (proof citation: rfc0010_b45_grounded; verification pending)
  7. MUST_NOT — The persistence adapter MUST NOT perform validation; the kernel MUST NOT write to storage directly.

Linked References

DirectionTarget
Extended byRFC-0048