KRN-CAP - Handles and Capabilities¶

Documentation revision: 2026-10-14 (ADR-039; M1 amendment log). Existing status dates record original design acceptance, not validation of the revised wording. New implementation obligations remain Proposed until implemented and verified.

Group KRN-CAP. Design: docs/specs/SPEC-009-objects-capabilities-and-storage.md §3, §4. Related groups: KRN-OBJ (generations, lifecycle), KRN-PART (syscall boundary, tables per partition), KRN-NOTIF (NOTIFY, BIND rights), HW (generated initial tables).

KRN-CAP-001 to 005 originate in docs/architecture/03-kernel-architecture.md §7.2. All are restated here as the authoritative copy. New requirements start at 006.

Requirements¶

KRN-CAP-001 One handle type, profile-selected representation¶

Statement. Every public handle shall be a capability whose representation is selected by profile without changing API signatures. Rationale. ADR-014: one API from tiny to isolated. Status. Accepted 2026-10-07 Verification. Analysis: EMB_DECLARE_HANDLE is the same in every profile; the conformance suite compiles unchanged for POINTER, INDEXED, and TABLE. Trace. SPEC-009 §3

KRN-CAP-002 Validation at the boundary¶

Statement. In isolated profiles, every kernel entry from an unprivileged partition shall validate the capability’s type, rights, and generation before use. Rationale. An unprivileged partition can never cause a kernel fault by misusing a handle (SPEC-001 §5.3). Status. Accepted 2026-10-07 Verification. Isolated-profile tests part/bad_handle_* return statuses, never fault; fuzzing of the syscall boundary. Trace. SPEC-009 §3.3; 03 §8.1

KRN-CAP-003 Rights only reduce¶

Statement. Rights shall be reducible on derivation and never increasable. Rationale. The capability discipline. Status. Accepted 2026-10-07 Verification. Test: cap/derive_cannot_add_rights, cap/grant_subset_only. Trace. SPEC-009 §4.1

KRN-CAP-004 Static capability tables¶

Statement. Capability tables shall be statically sized per partition at build time. Rationale. Memory of the isolation mechanism is a visible number (ADR-033). Status. Accepted 2026-10-07 Verification. Analysis: generator output partitions.c; Test: cap/table_exhausted_enomem. Trace. SPEC-009 §3.3

KRN-CAP-005 Zero cost on tiny¶

Statement. In the tiny profile the capability layer shall compile to pointer passing with no runtime cost. Rationale. Footprint target T1. Status. Accepted 2026-10-07 Verification. Footprint and benchmark comparison of the tiny profile with the capability functions present and absent. Trace. SPEC-009 §3.1, §4.3

KRN-CAP-006 Handle models¶

Statement. CONFIG_EMB_HANDLE_MODEL shall select POINTER (object pointer; type and lifecycle checked in checked builds), INDEXED (global registry slot plus 16-bit slot generation), or TABLE (per-partition capability index plus 16-bit slot generation); every lookup shall be O(1). Rationale. A real generation in O(1) where wanted, nothing where not; no tagged pointers. Status. Accepted 2026-10-07 Verification. Test: obj/handle_models runs the handle misuse tests under each model; Benchmark: lookup cost. Trace. SPEC-009 §3

KRN-CAP-007 Capability entry and validation¶

Statement. A capability entry shall hold the object pointer, the object generation at grant time, the slot generation, the type tag, and the rights; validation shall check index range, slot generation, type, rights, object lifecycle, and object generation, returning EMB_EINVAL, EMB_EPERM, EMB_ESTATE, or EMB_ESTALE accordingly. Rationale. Fixes the exact check order and codes so that the generated stubs and the conformance suite agree. Status. Accepted 2026-10-07 Verification. Test: cap/validation_matrix. Trace. SPEC-009 §3.3, §8

KRN-CAP-008 Rights per type¶

Statement. Each object type shall define its rights within eight bits with DESTROY and GRANT as the two universal top bits, as listed in SPEC-009 §4.2; every operation’s explicit @right metadata shall name the right each handle parameter needs, separately from @req requirement identifiers and the generated stubs shall check exactly that right. Rationale. One source of truth for rights, machine-checked. Status. Accepted 2026-10-07 Verification. Analysis: tools/apidoc cross-checks annotations against the stub generator’s table. Trace. SPEC-009 §4.2; SPEC-001 §9

KRN-CAP-009 Grant, derive, delete, revoke, renew¶

Statement. grant shall copy a capability with a subset of rights into another partition’s table and require GRANT on it and GRANT_TO on the target partition; derive shall create a reduced copy in the caller’s table; delete shall free the caller’s slot; revoke (requires DESTROY) shall bump the object’s generation and so invalidate every capability to it; renew shall give the owner a fresh capability afterwards. Rationale. Complete, small capability algebra with coarse revocation. Status. Accepted 2026-10-07 Verification. Test: cap/grant_*, cap/derive_*, cap/revoke_all_stale, cap/renew. Trace. SPEC-009 §4.1

KRN-CAP-010 Build-time grants¶

Statement. The generator shall emit each partition’s initial capability table from the system description, including device and port capabilities granted to driver partitions. Rationale. Static systems need no runtime grant protocol. Status. Accepted 2026-10-07 Verification. Generator test hw/gen_cap_tables; isolated-profile boot test. Trace. SPEC-009 §4.1; 04 §1.3; SPEC-014

KRN-CAP-011 Pointer models keep the API¶

Statement. Under POINTER and INDEXED, the capability functions shall exist: trivial ones return EMB_OK, cross-partition ones EMB_ENOTSUP, so that isolated-profile code compiles and runs unchanged. Rationale. One source tree per application across profiles (C3). Status. Accepted 2026-10-07 Verification. Test: cap/api_present_in_pointer_models. Trace. SPEC-009 §4.3

KRN-CAP-012 Statistics¶

Statement. Registry and table occupancy high-water and stale-handle rejections per partition shall be optional statistics. Rationale. Table sizing and a security signal. Status. Accepted 2026-10-07 Verification. Statistics API test. Trace. SPEC-009 §9

KRN-CAP-013 Incarnation persistence and exhaustion¶

Statement. Slot and object generation state shall retain its incremented value across reinitialization and partition restart. A generation value shall not be reused while a stale reference with that value may survive; exhaustion shall refuse the operation or invoke a reviewed reclamation scheme. Lookup/revocation shall preserve object lifetime for in-flight operations, and renew shall require current trusted recovery authority. Rationale. Resetting or wrapping a generation can revalidate stale authority; a stale DESTROY capability cannot authorize its own renewal. Status. Proposed 2026-10-14; unimplemented. Verification. Planned forced wrap/exhaustion, stale renew, concurrent lookup/revoke and restart tests on INDEXED/TABLE configurations. Trace. SPEC-009 §13; SPEC-010 §7, §17