gnomonlearn
Docs/RFC-0010 kernel ABI and authority proposal

RFC-0010 kernel ABI and authority 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. No kernel ABI or installed bundle exists yet, so this is a source contract choice.

Conflicts in the authored contract

RFC-0010 §6.9 gives submit, validate, query, and fingerprint a caller supplied out_ptr and out_capacity, with bytes written into that buffer. The same section says the kernel owns all output buffers and the caller MUST release each through gnomon_kernel_free. Those two ownership rules cannot both hold. The ABI also overloads the i32 return: submit returns byte count on success and a negative error code on failure, while validate returns zero on success, despite an output buffer and a shared encoding description. The contract does not specify how to discover the needed capacity or distinguish an output buffer too small from a command failure.

RFC-0010 §5.2 says the runtime layer enforces procedure authorization before kernel invocation; §5.3 places policy authorization in the kernel; §§6.6 and 8.1 make the kernel responsible for authorization. §5.2 generates reducers per mutation, while §5.1 depicts reducers per ActionType. §6.6 says the kernel is generated rather than hand authored, but §6.7 allows optional hand authored extensions in gnomon.kernel.rs. These affect the trust boundary and codegen unit. They need one first-release contract before implementation.

Choose caller owned output buffers for ABI v1. Remove the mandatory free export and its output-buffer rule. Use a two-call length query, or an explicit BUFFER_TOO_SMALL result carrying the required size. Specify one envelope with status, byte count, and error details for every output-producing call. Define the behavior of null pointer, zero capacity, partial writes, and overflow. Document ownership of the input bundle memory retained by init. If the canonical IR decision selects protobuf, align the ABI encoding with that schema or explicitly retain JSON as a separate, versioned runtime boundary. The owner may instead choose kernel allocated outputs, but that requires an output pointer-to-pointer or equivalent allocation handle and a matching free contract.

Keep authorization enforcement in the kernel before any committed Event; the runtime may preflight but cannot be the sole authority. Generate reducers per mutation, with ActionType dispatch mapped to the appropriate reducer. Permit hand authored logic only as declared, reviewed extension inputs to codegen, never as mutable patches to the compiled kernel artifact.

Acceptance

  1. Align §5, §6, §8, Lean statements, RDF projections, and diagnostics on reducer unit, authorization authority, and extension trust boundary.
  2. Publish a precise ABI v1 signature table and ownership rules. Test success, command rejection, insufficient buffer, null pointers, repeated calls, and lifetime of the retained init bundle in native and WASM hosts.
  3. Add a runtime startup check for fingerprint and ABI version, and run the same behavioral fixtures against generated native and WASM kernels.
  4. Refresh source-bound reviews after normative edits. Nothing deployed needs migration.