Add the capability table itself: Capability, CapabilityTable, ObjectRef

[MatejGomboc]

What

RFC-0003's second code increment: the setonix-capability crate grows from value types into the working mechanism.

• Capability<O> — owned, deliberately neither Clone nor Copy (§6). Transfer between tables is a Rust move; the sole duplication is derive: explicit, rights-checked, subset-only (O-2). A compile_fail doctest pinned to E0277 — instantiated with a real ObjectRef type, so it guards the instantiation the kernel will actually use — keeps the absence of Clone checked on every test run. The type is #[must_use]: dropping a capability is a close and must never happen by accident. Minting reads the generation from the object itself, so a capability can never be back-dated.
• CapabilityTable<O, N> — the flat per-process table of §4 Option B. Fixed capacity (the kernel has no allocator; bounded by construction), free-list recycling, O(1) resolution: one index plus two generation checks — slot vs handle (the ABA defence, O-1) and object vs capability (the destruction half of O-3). Slot generations bump at vacate time, so a closed handle dies the instant it is closed; a slot whose generation cannot advance is retired outright — capacity is the price of failing closed. A full table hands the capability back in the error instead of dropping it: silently destroying in-flight authority would turn a resource limit into revocation.
• ObjectRef — one method: what generation is the object at now. Everything the table asks of a kernel object; the kernel implements it when kernel objects exist, a test double implements it today, and that is what keeps the security spine host-testable. The trait bounds carry the design: insert/remove are object-blind slot mechanics (transfer plumbing), resolve/derive are the authority checks.
• All three of the RFC amendment's load-bearing invariants are stated where they bind — including the third: a resolve's borrow is held across the caller's whole check→act window, the property any future multi-core synchronisation story must preserve (a correctness dependency of the generation scheme, not a later addition).

How it was hardened

An adversarial multi-lens review (RFC conformance, security attack, Rust quality, test coverage — 23 agents), every finding independently re-verified against the code, several by mutation testing. All fifteen confirmed findings were documentation precision or test gaps — no behavioural defect survived — and every one is folded in. Notably, the verifiers proved by mutation that remove's ABA guard and its error-path state restoration were untested; both now have tests that kill those mutants.

Verification

• 39 host unit tests + the lifecycle doctest + the compile_fail no-Clone guard — all green
• Among them: exhaustive forged-handle sweep (resolve and remove honour only the exact minted handle); object destruction making parent and derived child inert with no list of holders; a removed parent leaving its derived sibling untouched (no parent link — pinned so RFC-0003a cannot regress it silently); retirement alone and amid live neighbours; free-list LIFO order; both defensive fail-closed branches; an 8192-operation churn test against a shadow model interleaving inserts, subset-random derivations, object destructions, object-blind cleanup and removals
• cargo clippy -D warnings: clean on host and both Tier-1 bare-metal targets (proving the crate stays no_std)
• fmt, British spelling, toolchain pins, markdown: clean
• No unsafe anywhere in the crate

What follows (§5.3: small, reviewable increments)

Wiring into the kernel's syscall surface once there are kernel objects to reference; selective revocation once RFC-0003a decides it.

🤖 Generated with Claude Code