Numeric Assumptions

CambiOS Numeric Assumptions

The rule: every arbitrary numeric bound in kernel code must be a conscious bound. Not “this is what fit when I wrote it.” Not “this looked big enough.” Conscious means: I picked this number, I know why I picked it, I know what category it belongs to, and I know what would make me change it.

Unconscious bounds are how production-ready software accrues weakness. CambiOS catches them while it’s still early enough to fix them painlessly.

Why this document exists

The microkernel was deliberately written to be small and verifiable. Verification rewards fixed-size arrays, bounded loops, and statically-knowable limits. Many numeric bounds in the codebase were chosen to make verification ergonomic, not because the number itself is meaningful — MAX_TASKS = 256, MAX_VMAS = 64, [Option<Capability>; 32]. These are scaffolding, and scaffolding that nobody marks as scaffolding becomes load-bearing assumption.

Phase 3.2a (ADR-008) removed one of the most prominent scaffolding bounds — MAX_PROCESSES = 32 — by replacing it with a runtime-computed num_slots derived from the tier policy and available RAM. That’s the template for how the other SCAFFOLDING bounds here should eventually move: pure-function sizing from a policy + hardware measurement, clamped so the verifier can still reason about the result symbolically.

This document catalogs every such bound and forces a category on each: which ones are scaffolding (will change), which are architectural invariants (won’t change), which are hardware/ABI facts, and which are tuning knobs that need workload data rather than opinion. The point is not to grow the numbers — most of the small ones are correct for now. The point is that future-you can tell at a glance which bounds are deliberate forever versus deliberate for now, and what would trigger revisiting them.

Categories

How to mark a bound in code

Every fixed numeric const, fixed-size array, and MAX_* value in kernel code carries a doc comment that names its category. The format mirrors the existing // SAFETY: convention.

SCAFFOLDING — full template, three required fields:

/// SCAFFOLDING: <one-line statement of the constraint>
/// Why: <verification ergonomics or early-development reason>
/// Replace when: <observable trigger that should make a future maintainer revisit>
const MAX_FOO: usize = 32;

ARCHITECTURAL — single line, no replacement criteria (because the answer is “never”):

/// ARCHITECTURAL: <statement of the invariant the constant encodes>
const NUM_PRIORITY_BANDS: usize = 4;

HARDWARE — single line, cite the spec or chip:

/// HARDWARE: <ABI/spec reference that fixes this number>
const MAX_GSI_PINS: usize = 24;

TUNING — single line, name the workload variable:

/// TUNING: <what workload property this number trades off>
const CACHE_CAPACITY: usize = 32;

When you add a new bound or change one of these, also update the table below. CLAUDE.md’s Post-Change Review Step 8 lists this as an explicit checklist item.

Catalog

This is the full table. Bounds are grouped by category, and the most-likely-to-bite ones come first within each section.

SCAFFOLDING — verification or early-development bounds

These are the ones that will need to grow as the system matures. They are correct for the current shape of the kernel but encode no real invariant.

ARCHITECTURAL — real invariants

These are not arbitrary. Each one encodes a design decision. They should not change unless the design changes.

HARDWARE — fixed by external ABI/spec

These are facts about the world. CambiOS has no leverage to change them.

TUNING — needs benchmarks, not opinion

These are performance knobs. Picking a number without measurements is guessing. They should change in response to observed workload, not architectural changes.

Tier policies

These three rows capture the default TableSizingPolicy per deployment tier introduced by ADR-008 and ADR-009. Each policy is a 5-field struct — min_slots, max_slots, ram_budget_ppm, ram_budget_floor, ram_budget_ceiling — that drives the boot-time num_slots computation in config::num_slots_from. They are TUNING because the defaults are starting points chosen from estimated workload density; the right values depend on what each tier’s deployments actually run, and will shift as real workload data arrives. The kernel binary is identical across tiers per ADR-009; what differs is which policy is selected by the CAMBIOS_TIER build environment variable (default: tier3), wired in via build.rs.

Current binding observation (tier3, QEMU 128 MiB): after the BuddyAllocator-to-per-heap move, SLOT_OVERHEAD dropped from ~22 KB to ~2 KB. On QEMU 128 MiB, num_slots is capped by the contiguous-region fitting heuristic (half of free frames). At 1 TiB, Tier 3 hits max_slots = 65536 (slot-bound) — the binding flip the ADR originally predicted. Tier 1 is also slot-bound; Tier 2 transitions from budget-bound to slot-bound at ~8 GiB of RAM.

Revisit when: ADR-008 § “Post-Change Review Protocol” note — changes to per-process kernel state (new fields in ProcessDescriptor, ProcessCapabilities, etc.) shift SLOT_OVERHEAD, which changes how many slots fit in a given budget. When that happens, the tier defaults may need to move so the binding constraint (slot count vs. budget) stays where the policy intended. A SLOT_OVERHEAD reduction (e.g. moving BuddyAllocator state out of ProcessDescriptor onto the heap it manages) would flip Tier 2/3 back to slot-bound and is a natural follow-up to Phase 3.2a. The first real workload data from bare-metal Tier 3 deployment is also a revisit trigger.

Adding or changing a bound

When you add a const numeric or fixed-size array to kernel code:

1. Pick the category. SCAFFOLDING, ARCHITECTURAL, HARDWARE, or TUNING. If you cannot pick one, that is the signal that you have not thought about the bound enough — that is what this whole document is for.
2. Add the doc comment. Use the templates above. SCAFFOLDING requires the three fields (constraint, why, replace-when); the others require one line.
3. Add a row to the matching table here. Same level of detail as the other rows.
4. Bump the last_synced_to_code: date in the frontmatter.
5. CLAUDE.md Post-Change Review Step 8 lists this as an explicit checklist item — it shows up in the same place that asks you to update STATUS.md.

When you remove a bound or remove a constant entirely, delete its row from this document in the same change.

What is not in this document

• Memory addresses (HHDM bases, page table layouts, MMIO bases) — those are documented in CLAUDE.md’s Memory Layout section because they’re tied to the bootloader and architecture, not arbitrary numeric choices.
• Syscall numbers — those are an interface, not a bound.
• Lock ordering numbers (the 1-8 hierarchy) — that’s an ordering, not a bound.

Cross-references

• CLAUDE.md § Numeric bounds: tagging convention — the rule, the templates, the post-change checklist
• STATUS.md — current implementation status (where this catalog’s bounds actually live in the build)
• SCHEDULER.md — scheduler implementation reference
• docs/adr/ — architectural decisions that are referenced by this catalog (especially ADR-005 for the 256-byte payload, ADR-007 for the audit channel pressure on the message queues)