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.
Recommended first-release contract
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
- Align §5, §6, §8, Lean statements, RDF projections, and diagnostics on reducer unit, authorization authority, and extension trust boundary.
- 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.
- Add a runtime startup check for fingerprint and ABI version, and run the same behavioral fixtures against generated native and WASM kernels.
- Refresh source-bound reviews after normative edits. Nothing deployed needs migration.