# Resource Governance capOS uses capabilities to decide **what** an actor may use and an unforgeable owner ledger or grant to decide **how much** of a finite resource may be consumed and **when**. Identity, profile names, peer addresses, badges, and session metadata can select policy, but they are not spend authority by themselves. Availability is part of the security contract. A control that bounds retained state but lets an attacker cheaply occupy every slot, verifier, waiter, or accept loop has contained damage without providing availability. It must not be described as authorization, fair admission, or denial-of-service protection. ## Control Taxonomy Every finite-resource control has one of these roles. A design may need several of them at once, but it must not use the names interchangeably. | Control | Role | What it does not prove | | --- | --- | --- | | Isolation invariant | Preserves authority, generation, ownership, lifetime, or wire correctness. | Entitlement, throughput, or fairness. | | Structural safety ceiling | Caps one object's or pool's implementation/physical maximum so corruption or unbounded allocation is impossible. | That the physical cost is charged, or that one owner cannot consume the whole pool. | | Policy quota | Selects an administratively allowed amount below structural capacity. The resource owner translates it into an unforgeable ledger or grant. | Reservation, minimum service, or identity. | | Replenishable budget | Limits work or bytes in a time window and replenishes under a defined clock and burst rule. | A global try-lock, fixed slot count, or retry loop is not a budget. | | Reservation | Precharges capacity held until commit, rollback, expiry, or release. | A quota without aggregate admission is not a reservation. | | Donation | Leases a bounded part of one ledger to a callee for identified work and returns the unused remainder. | It never exposes the donor's unrelated budget or charges work spent before donation existed. | | Admission control | Atomically proves that all requested reservations, pool capacity, and protected housekeeping can coexist before publication. | A local per-object check is not aggregate admission. | | Backpressure | Reports temporary lack of admitted capacity through a bounded wait, partial operation, or typed overload result. | Retrying must not reset the deadline or create an unbounded queue. | | Deadline or lease | Bounds unproductive occupancy from one admission point through retries and partial progress. | A short arbitrary timeout is not resource accounting or fairness. | | Fairness, SLO, or SLA | Arbitrates admitted contention; an SLA additionally requires feasible reservations and accounting for kernel, IRQ, recovery, and background work. | WFQ weight, a hard throttle, or a quota alone is not a minimum-service promise. | | Proof or harness bound | Keeps one feature, manifest, or validation workload finite and reproducible. | It is not production policy unless the production owner enforces the same ledger contract. | For one resource dimension, the effective entitlement is bounded by all applicable sources: ```text effective = min( structural ceiling, admitted pool credit, delegated parent or subtree credit, selected policy quota, ) ``` Replenishable budgets, deadlines, and fairness arbitration then govern how that entitlement is used over time. Each field defines whether zero means invalid, disabled, or explicitly unbounded. Scarce production resources do not silently interpret zero as either one or infinity. ## Required Resource Descriptor Every bound, quota, or budget must name: - the resource dimension and unit, including worst-case physical memory, CPU, I/O, crypto, or continuation cost; - the authoritative owner and ledger, plus whether scope is per object, process, session, service, tenant, subtree, device, CPU, or system pool; - the structural derivation and every policy, delegated-credit, and pool limit that contributes to the effective value; - the authority needed to reserve or donate it, and the generation/lifetime to which that authority is bound; - who pays before identity exists, after authentication, during delegated server work, and during cleanup; - reserve, commit, rollback, cancellation, expiry, and exactly-once release behavior; - overload/backpressure behavior, one absolute deadline, and recovery path; - used, reserved, maximum, high-water, denial, timeout, and mismatch observability from the ledger of record; - manifest/profile configurability, validation, zero semantics, and effective readback; and - attacker cost versus defender cost, including whether one actor can exhaust unrelated progress or force global retries, hashing, logging, or scans. ## Core Invariants 1. Every finite resource has one authoritative owner and ledger. Mirrors may report state but never independently enforce it. 2. Profile and identity metadata select policy; only a generation-bound ledger or grant authorizes spend. Caller-provided strings, badges, peer addresses, account IDs, and cookies never select the charged kernel account directly. 3. Reservation happens before allocation or publication. Commit consumes exactly the reservation; rollback and release return it exactly once. Under-release, over-release, double release, and stale release are detected and audited or recovered, not hidden with saturating arithmetic. 4. A per-object limit is never described as a process, session, tenant, or system quota. Fan-out, fixed backing, and metadata are charged to an aggregate owner before another bounded object is created. 5. A logical queue or message bound reduces physical allocation or prepays the unchanged worst-case backing. Bounding retained records also bounds or charges the CPU and I/O used to reject, scan, format, hash, or log them. 6. Backpressure stays bounded end to end and preserves one absolute deadline across partial progress and retry. Waiting and cleanup remain charged to the responsible producer, service, or donor. 7. Ordinary traffic and diagnostics cannot starve lifecycle, audit, health, recovery, or credential-recovery paths. Protected lanes are themselves bounded and abuse resistant. 8. A quota is not a reservation, and a reservation is not an SLA. Minimum service claims require aggregate feasibility admission and accounting for system work that competes with the workload. 9. Proof-sized global tables are labeled as proof limits until they have aggregate owner admission. One workload must not consume every shared waiter, continuation, or verifier permit while another admitted workload has no progress. 10. Status comes from the ledger of record and exposes the effective-limit sources. A profile field with no resource-owner consumer is reported as policy-only or unwired, not as enforced. ## Role in the OS Resource governance keeps commitments feasible and assigns the cost of finite work; it is not a second identity or method-access system. Apply controls in this order: 1. The component that owns the physical resource enforces a structural safety ceiling derived from hardware, ABI, allocation, or verified implementation constraints. A hard-coded value is acceptable here only with that derivation, or as a clearly labeled proof/bring-up bound. 2. Admission withholds bounded lifecycle, health, audit, recovery, and local administrative reserves before publishing ordinary capacity. These reserves cannot be borrowed by normal traffic merely because the system is busy. A public path or caller-supplied route label is not enough to select a reserve; the protected lane needs distinct authority or non-bypassable listener/ transport provenance. 3. A parent ledger delegates bounded generation-tagged credit to services, processes, sessions, or subtrees. Resource owners accept that credit, not a caller-provided identity or quota number. 4. A work-conserving fair arbiter schedules admitted contention. An idle owner need not strand ordinary capacity, but opportunistic borrowing is revocable and never consumes protected reserves or creates an SLA. 5. Manifest/profile policy chooses administratively useful values below the admitted ceiling and exposes effective readback. Production policy values are calibrated from real workload and hostile-coexistence measurements, not copied from a proof topology or chosen solely to simplify an array. This gives an operator authority to tighten or enlarge a workload's policy within the parent pool without recompiling the kernel. Raising a quota still requires feasible pool credit; lowering it defines what happens to existing reservations rather than retroactively corrupting them. Integrity, authority isolation, secret handling, and memory safety remain non-negotiable. Within those constraints, prefer the design that preserves useful progress and has the better measured attacker/defender cost. If a stronger-looking control makes global denial cheaper, keep the safer usable mechanism and document the residual risk, capacity assumption, observability, and next mitigation. Before identity exists, there may be nothing meaningful to authorize at TCP or TLS level. The service therefore owns a bounded anonymous-ingress pool and fair queue, with progress deadlines and protected control capacity. Source-address signals may add defense in depth, but lack of a stable principal does not justify either unbounded work or one unauthenticated peer monopolizing a global slot. No scheduler can guarantee progress to one particular anonymous remote caller against an unbounded set of indistinguishable Sybil attempts. The honest contract is bounded attacker/defender cost, no privilege for queue-flooding or reconnect churn, randomized or aging-aware work-conserving selection, and observable overload. Deterministic progress needs distinguishable authority, such as the protected local recovery lane or a reviewed upstream admission token. ## Identity and Pre-Authentication Work TCP state, TLS work, request parsing, cookie rejection, login backoff, password hashing, and response bytes are consumed before or while identity is being established. They belong to a service or anonymous-ingress ledger. A successful login cannot retroactively charge already-spent work to the resulting operator session. After authentication, a session may explicitly donate bounded CPU, queue, buffer, or response-byte credit to identified server work. The donation is scoped to that request/session generation and returns on completion, cancellation, timeout, logout, or revocation. Source addresses and CIDRs may restrict network reachability, identify a trusted proxy, or feed one anti-abuse signal. They are not browser identity or resource-account identity. This distinction is mandatory behind a load balancer, where many users share one backend peer and forwarded headers are trustworthy only from an explicitly admitted proxy range. At hard emergency capacity, an L4 implementation may drop or reset before HTTP framing exists. Once HTTP framing is available, ordinary policy overload should return a typed `429` or `503` with bounded retry guidance. Neither outcome is authentication. ## Current Enforcement The repository has useful local ledgers, but it does not yet implement the full system contract. | Area | Current state | Missing contract | | --- | --- | --- | | Capability holds and transfer | Cap-table slots, generations, transfer scope, reservation, and rollback enforce qualitative authority. | Capability possession does not carry a quantitative service entitlement. | | Process profile application | Process construction applies cap and thread limits; ring/reply values influence ring construction. | Service entries do not select a resource profile explicitly; several profile fields have no resource-owner consumer, and unknown profile resolution may fall back to defaults. | | Frame and virtual memory | `ResourceLedger` preflights frame-grant and virtual-reservation pages on current paths. | Manifest memory/frame values are not the enforced maxima, their composition needs an explicit contract, and mismatched release must not be saturated away. | | Outstanding calls and scratch | Counters exist in `ResourceLedger`. | Production reservations are incomplete; per-thread ring scratch and fixed queues multiply outside aggregate scratch accounting. | | Endpoints | Per-endpoint queue and in-flight values bound logical state. | Backing is sized by structural maxima, limits are not aggregate per owner, and one endpoint can preallocate far more than its selected logical queue. | | Shared kernel continuations | Notification, pipe, and promise-pipeline tables have finite proof bounds. | Some bounds are system global without process/session credit or protected cross-owner progress. | | Scheduler | WFQ weight controls relative share; `SchedulingContext` enforces a spendable throttle; CPU isolation controls placement/nohz/exclusivity. | There is no general aggregate CPU feasibility admission that justifies a reservation or SLA claim. | | Logs and audit | Retained records and fields are bounded. | Repeated formatting/UART work is not fully budgeted, aggregated, or separated into protected audit and ordinary diagnostic lanes. | | DMA/device resources | Generation-bound ownership, queue depth, and device budgets provide strong structural/isolation ledgers. | These limits do not by themselves grant a tenant quota or service guarantee. | | Remote-session/WebUI network path | The WebUI's application-slot, backlog, and release-debt capacities each derive from an independent `IngressProfile` field (`min(structural, quota)`), validated fail-closed, instead of one shared literal, with boot readback of the effective values. The policy quotas (slots, backlog, release-debt, in-flight bytes, protected reserve, per-connection bound, retry) are now manifest-selectable: a web-ui manifest authors `ingress_*` inert-Endpoint marker caps (lowered from `#WebUiIngressProfile`) that the service parses in `evaluate_service_capset_policy` and resolves against the code's fixed structural maxima into a validated profile of record, failing the boot closed on a zero quota, zero per-connection bound, or a reserve that swallows the anonymous lane, and clamping an oversized quota to the ceiling; an unauthored manifest inherits the documented safe default. The accounted ledger of record itself (`WebUiIngressLedger`: anonymous vs protected control/health/recovery lanes, per-connection bounds, in-flight byte accounting, fair work-conserving selection, typed `429`/`503` overload, exact reservation/release) is implemented, host-tested, and now the LIVE per-connection source of pre-identity admission and exact-once release in the accept/close serve loop (charged before any identity is read; balanced quiescent evidence asserted by the L4 gate). A second, strictly separate `SessionBudgetLedger` implements the session donation: every authenticated session opens an explicit per-session budget at login and every post-authentication request draws one unit against it, released exactly once on completion/cancel/close; a slow or idle anonymous client holds no session handle and cannot consume session credit, and no pre-identity work is ever retroactively reclassified onto a session. Both ledgers are host-tested and L4-proven live with balanced quiescent evidence. Fixed connection/timeout/request-size bounds still contain the focused demos. | The live ledger enforces the compile-time structural profile; binding the manifest-selected policy-of-record to per-request enforcement is still deferred, the session donation is a service-set, structurally-derived (from the serving-slot capacity) proof-sized per-session unit budget — a bounded local concurrency quota, not authority leased from a generation-bound session-owned resource grant (this demo has no such quantitative session grant to debit; a real donor lease returning the remainder on close is future work) and not a calibrated CPU/byte cost — with no protected-listener lane fed yet, and there is no public multi-user availability proof or concurrency-above-four throughput proof. | The exact current consumers are also summarized in [Configuration](../configuration.md). Transaction and transfer mechanics stay in [Authority Accounting](../authority-accounting-transfer-design.md); memory, IPC, scheduling, manifest startup, and DMA pages own their subsystem details. The [Resource Accounting proposal](../proposals/resource-accounting-proposal.md) records unfinished extensions and rationale rather than overriding this current-state matrix. ## WebUI and Remote-Session Application The current capOS-served WebUI uses four listener slots, four application slots, and a four-entry release-debt table. It also has one global browser session, listener-wide and peer-address login backoff, one nonblocking global password-verifier arena, per-connection helper creation with shared-endpoint quiescence, complete static-response copies, and stable asset URLs with a one-year immutable cache policy. The remote-session CapSet gateway accepts one connection and permits a slow peer to occupy its serial frame loop. These are bounded research/demo mechanisms, not public multi-user admission. The selected public-readiness direction is: - charge TCP, request, failed-cookie, login, crypto-arena, and unauthenticated response work to service/anonymous ingress before identity; - use independent generation-bound browser sessions after authentication and accept explicit per-session donation for subsequent work; - derive concurrency from accounted socket, buffer, heap, and work capacity, while reserving bounded health/lifecycle/recovery progress; - eliminate per-accept global quiescence and stream bodies/TLS records without retaining full plaintext and ciphertext copies; - default route descriptors to denial and keep method, authority, body, and cache policy in one table; - serve non-authority static bytes publicly at content-addressed URLs so browser and explicitly configured shared caches may reuse them, while sizing origin admission for a cold or cache-bypass flood; reject non-canonical query strings on immutable asset routes; serve bootstrap HTML with revalidation or `no-cache`; - charge the ordinary public `/healthz` route to anonymous ingress. If provider health checks receive protected progress, admit them through a distinct listener/port or capability that the public frontend cannot select, rather than trusting the request path; and - use authenticated static delivery only when an explicit confidentiality policy requires it. In that mode, validate the session before ETag/`304` handling and use private revalidation semantics. Keep a minimal public login bootstrap because a browser cannot obtain the session from an entirely protected asset graph. Protected asset requests perform a bounded live-session lookup, never password verification. Authentication is not a default optimization or denial-of-service defense; and - initialize production transport randomization from a generation-bound entropy grant. A deterministic seed belongs only to an explicitly selected proof fixture and production startup must not silently fall back to it. The two background images total about 0.94 MiB and remain part of the real UI. They are useful correctness assets, not a steady-state throughput workload. Performance progress uses a deterministic payload of at least 8 MiB plus the unchanged cold browser graph and reports the same-boot ladder: ```text G_path -> G_stack -> G_ipc -> G_webui -> G_browser ``` Each synthetic rung uses identical bytes, direction, boot, sender/receiver, cache-off posture, connection schedule, and predeclared attempt IDs. `G_path` is the independently measured physical/provider/NIC-path ceiling without the capOS stack/application stages; `G_stack` adds the userspace transport stack; `G_ipc` adds socket-cap IPC; `G_webui` adds HTTP routing/delivery; and `G_browser` is the browser fetch of that proof-only payload. The unchanged real browser graph is a separate correctness/TTFB/load-time workload, not a steady-state goodput substitute. Adjacent-layer ratios, aggregate concurrent goodput, TTFB, CPU/queue occupancy, health latency, fairness, first-attempt refusals, browser failures, and cache hits identify where capacity is lost. Retrying or replacing a refused sample does not turn it into success, and improvement over a pathological historical baseline does not prove the implementation is near the network ceiling. The initial steady-state bands are `G_stack/G_path >= 0.90`, `G_ipc/G_stack >= 0.95`, `G_webui/G_ipc >= 0.95`, `G_webui/G_stack >= 0.90`, `G_browser/G_webui >= 0.95`, and four-flow aggregate goodput at least `0.85 * G_stack`; they are evidence targets, not quotas. Revising them is a separate reviewed decision made before the candidate measurement, never a same-run calibration escape. The synthetic payload is a proof-only route or fixture and must be absent from the default/production/ public route table and shipped bundle. The coexistence gate runs a cold/cache-bypass public-static flood alongside an already authenticated session/API stream, one fresh login stream, and genuine health/lifecycle work. Each class reports charged bytes/CPU, reserved or weighted progress, latency, denials, and starvation. Separate green tests do not prove that those classes coexist on the shared NIC and CPUs. ## Implementation Gaps The Loopyard records below separate the implementation work by owner and proof boundary: - [`resource-profile-service-binding-fail-closed`](https://tasks.cap-os.dev/p/capos/t/resource-profile-service-binding-fail-closed) makes service profile selection and binding explicit, validates supported fields, and makes unknown references fail closed; it does not implement hierarchical child credit. - [`resource-ledger-hierarchical-exact-release`](https://tasks.cap-os.dev/p/capos/t/resource-ledger-hierarchical-exact-release) adds hierarchical credit and exact reservation-token release. - [`kernel-bounded-object-amplification-accounting`](https://tasks.cap-os.dev/p/capos/t/kernel-bounded-object-amplification-accounting) charges fixed backing, fan-out, shared continuations, and diagnostic work. - [`memory-pressure-accounted-reclaim-work`](https://tasks.cap-os.dev/p/capos/t/memory-pressure-accounted-reclaim-work) bounds and charges reclaim scans, CPU, and optional I/O while preserving recovery progress. - [`scheduler-resource-reservation-semantics`](https://tasks.cap-os.dev/p/capos/t/scheduler-resource-reservation-semantics) separates share, throttle, placement, reservation, and SLA claims. - [`remote-session-gateway-concurrent-admission-deadlines`](https://tasks.cap-os.dev/p/capos/t/remote-session-gateway-concurrent-admission-deadlines) removes the serial slow-peer monopoly from the CapSet gateway. - [`credential-verification-fair-anonymous-admission`](https://tasks.cap-os.dev/p/capos/t/credential-verification-fair-anonymous-admission) puts the shared Argon2 arena behind fair bounded admission with a protected local recovery/setup lane. Landed at the executor: `capos-lib`'s `CredentialAdmission` arbiter (protected local reserve, anonymous lane pool, per-connection bound on opaque non-peer tokens, aggregate backstop, non-destructive absolute-deadline handling with owner-driven exact reservation/release, work-conserving aging/randomized cross-connection `select_next`, typed `overloaded` with bounded `retryAfterMs`) fronts the single credential-hash slot in `kernel/src/cap/credential_store.rs`. The kernel enforces admission bounds and a fair *executor handoff*: anonymous callers take the slot non-blocking and defer while a protected local caller waits, so local recovery/setup is never blocked by anonymous *load* and cannot be starved by anonymous occupancy (the executor lock is unfair, so there is no per-waiter bound against *other* local callers, but local recovery/setup is a trusted, effectively serial operator action); the login path charges each connection's `terminalEventId` token. Residual: the kernel's synchronous inline path runs each admitted anonymous hash to completion under the pool/per-connection bounds, so fine cross-connection *selection* fairness (aging/randomized choice among many waiting anonymous connections) is delivered by the arbiter's `select_next` as consumed by the async admission owner (`webui-public-resource-accounting-admission`), which also supplies real per-browser connection tokens and request deadlines; no local scheduler can promise a per-remote-caller SLA against unbounded indistinguishable Sybils. - [`webui-public-resource-accounting-admission`](https://tasks.cap-os.dev/p/capos/t/webui-public-resource-accounting-admission) owns anonymous/session WebUI admission, consumes the credential executor without a global race, and preserves control progress within the current single-session model; it does not own multi-session coexistence. Landed at the ledger: `WebUiIngressLedger` (the pure host-tested accounted ledger of record — lanes, per-connection bound, aggregate backstop, protected reserve, in-flight byte budget, absolute deadline, work-conserving aging/randomized selection, exact reservation/release, typed `429`/`503` overload) plus the decoupling of the WebUI application-slot, backlog, and release-debt capacities onto independent effective profile fields with boot readback, and the manifest ingress/pre-auth profile binding: `ingress_*` marker caps (lowered from the `#WebUiIngressProfile` CUE schema) that the service parses and resolves fail-closed against the fixed structural maxima into a validated profile of record, read back at boot. Residual: wiring the ledger's per-request charge/release through the accept/close serve loop (the resolved profile is delivered and read back but not yet enforced there), explicit authenticated-session donation, and the coexistence proof. - [`webui-independent-browser-sessions`](https://tasks.cap-os.dev/p/capos/t/webui-independent-browser-sessions) replaces the one-session singleton. - [`webui-accepted-socket-lifecycle-no-global-quiesce`](https://tasks.cap-os.dev/p/capos/t/webui-accepted-socket-lifecycle-no-global-quiesce) removes per-accept helper churn and shared endpoint pauses. - [`webui-cache-correct-bounded-http-delivery`](https://tasks.cap-os.dev/p/capos/t/webui-cache-correct-bounded-http-delivery) depends on independent browser sessions, owns streaming, route policy, connection reuse, and cache generations, and runs the integrated static/auth/login/control coexistence gate. - [`webui-network-ceiling-benchmark-ladder`](https://tasks.cap-os.dev/p/capos/t/webui-network-ceiling-benchmark-ladder) establishes the local layered evidence contract. - [`network-stack-production-entropy-seeding`](https://tasks.cap-os.dev/p/capos/t/network-stack-production-entropy-seeding) removes the deterministic proof seed from production network-service startup. - [`webui-network-ceiling-real-gce-proof`](https://tasks.cap-os.dev/p/capos/t/webui-network-ceiling-real-gce-proof) runs the final private-provider proof only after those local dependencies and fresh explicit authorization. - [`cloud-gce-public-webui-readiness-preflight-extension`](https://tasks.cap-os.dev/p/capos/t/cloud-gce-public-webui-readiness-preflight-extension) makes the later public harness reject missing or non-ancestor readiness closeouts before any provider command. Public Internet ingress remains blocked behind the independent-session, real-GCE closeout, and no-spend readiness-preflight tasks. A provider firewall or peer CIDR can narrow transport reachability, but it does not close the application admission, accounting, or multi-user availability gaps.