RFC-0010 · Design Q&A
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.
Q: What is the minimum viable canonical IR schema? Should it be defined as a JSON Schema, protobuf, or TypeScript type?
A: The canonical IR is specified as TypeScript interfaces exported from @gnomon-sh/ir. JSON serialization is normative; protobuf is optional. JSON Schema artifacts MUST be generated from the TypeScript interfaces in CI. The StatementBlockRecord union covers rule, expr, prompt, and note statement kinds.
Where normative: §4.6 of RFC-0010
Q: At what granularity should round-trip consistency scoring operate — per symbol, per module, or per domain concept?
A: Per declaration (entity, action, flow, policy). Each declaration is the unit of round-trip consistency scoring. A declaration’s score is computed by: (1) serializing to canonical IR, (2) reconstructing source text via formatter, (3) re-parsing the reconstructed source, and (4) comparing the resulting ASTs. A mismatch at the declaration level is a round-trip consistency failure. Module-level scoring aggregates declaration-level scores; per-symbol scoring is reserved as a diagnostic detail when a declaration fails.
Where normative: §4 (canonical IR) of RFC-0010
Q: What mapping exists between extracted IR concepts and RFC-0006 type kinds?
A: Normative mapping table defined in §4.9, including confidence levels and migration tooling requirements.
Where normative: §4.9 of RFC-0010
Q: How does the model worker communicate proposals to the surface?
Status: Open
Issue: RFC-0010 §6.2 draws a model worker beneath the kernel and §6.3 classifies a Proposal as advisory. The older answer specifies request/response transport, statelessness, runtime routing, and a human-confirmation gate, but RFC-0010 has no §7 or normative model-worker wire contract for those details.
Recommendation: Define a versioned protobuf inference request and Proposal response, the routing and correlation rules, and the authorization step that turns a confirmed proposal into a Command. Reconcile RFC-0009 and RFC-0010 before treating the older answer as normative; test worker and surface consumers against the exact envelope.
Where normative: RFC-0010 §§6.2–6.3 — protocol pending owner decision
Q: Should the kernel be entirely generated, or should it have a handwritten extension layer?
A: The kernel is generated from the compiled bundle (§6.6). The artifact set (§6.7) lists gnomon.kernel.rs as “Generated Rust reducers (+ optional hand-authored extensions).” The extension seam is: the compiler generates the full kernel as a Rust library crate; module authors MAY add hand-authored Rust functions in a sibling kernel_ext/ directory that the compiler links against. The generated code MUST NOT be committed alongside hand-authored extensions — the two are merged at compile time. Hand-authored extensions MUST be declared in the module manifest and are subject to the same bundle-fingerprint versioning as generated code (§5.4).
Where normative: §6.6–6.7 of RFC-0010
Q: How does the event log interact with RFC-0005’s install plan? Are structural migrations expressed as events, or as out-of-band DDL operations?
A: DDL migrations are out-of-band operations applied by the install pipeline before kernel startup. The event log is append-only and contains domain events only, not schema operations.
Where normative: §5.5 of RFC-0010
Q: What is the right persistence strategy for the event log in browser-hosted deployments (IndexedDB, OPFS, server sync)?
A: IndexedDB with server sync on reconnect. The browser-hosted event log uses IndexedDB as the local persistence layer. On reconnect, the client synchronizes its buffered events to the server in causal order (via Lamport timestamps on each event). OPFS is reserved as a future alternative for higher-throughput browser deployments; it is not normative in the initial spec. The event log schema in IndexedDB mirrors the server-side gnomon_event_log table structure to simplify sync.
Where normative: §5 (event log) of RFC-0010