KRN-CAP requirements

Requirement: One handle type, profile-selected representation KRN-CAP-001

status: Accepted evidence: not evaluated design_source: requirements/KRN-CAP.md links incoming: API-005, API-018

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.

Requirement: Validation at the boundary KRN-CAP-002

status: Accepted evidence: not evaluated design_source: requirements/KRN-CAP.md links incoming: API-016, KRN-NOTIF-010, KRN-PART-013, KRN-THR-027

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.

Requirement: Rights only reduce 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.

Requirement: Static capability tables 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.

Requirement: Zero cost on tiny 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.

Requirement: Handle models 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.

Requirement: Capability entry and validation 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.

Requirement: Rights per type 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.

Requirement: Grant, derive, delete, revoke, renew 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.

Requirement: Build-time grants 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.

Requirement: Pointer models keep the API 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.

Requirement: Statistics 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.

Requirement: Incarnation persistence and exhaustion KRN-CAP-013

status: Proposed evidence: not evaluated design_source: requirements/KRN-CAP.md links incoming: KRN-PART-027

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.