# KRN-CAP requirements ::::{req} One handle type, profile-selected representation :id: KRN-CAP-001 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Validation at the boundary :id: KRN-CAP-002 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Rights only reduce :id: KRN-CAP-003 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Static capability tables :id: KRN-CAP-004 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Zero cost on tiny :id: KRN-CAP-005 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Handle models :id: KRN-CAP-006 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md `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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Capability entry and validation :id: KRN-CAP-007 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Rights per type :id: KRN-CAP-008 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Grant, derive, delete, revoke, renew :id: KRN-CAP-009 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md `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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Build-time grants :id: KRN-CAP-010 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Pointer models keep the API :id: KRN-CAP-011 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Statistics :id: KRN-CAP-012 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). :::: ::::{req} Incarnation persistence and exhaustion :id: KRN-CAP-013 :status: Proposed :evidence: not evaluated :design_source: requirements/KRN-CAP.md 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 [Normative source](../../requirements/KRN-CAP.md). ::::