Quota and Reservation

1. Owned problem

Quota, reservation, and admission are different control objects. Quota is an entitlement ceiling, reservation is a time-bounded capacity commitment, and admission is the decision for one request at one time. ARC-004 owns only this boundary; Resource Broker Metadata and Chargeback remain adjacent lessons.

2. Deliverable

Build Quota, Reservation & Admission Ledger v1. Every decision must be reproducible from visible fields: quota_limit, quota_used, quota_remaining, reservation lifecycle, capacity_allocatable, request_quantity, contention_state, admission_state, override_authority, and evidence_ref.

3. Three-ledger mental model

Quota records entitlement, Reservation records commitment, and Admission evaluates the current request. Collapsing them into one counter either oversells scarce capacity or blocks healthy requests without evidence.

4. Evidence contract

Each row names scope and resource type and keeps Quota, Reservation, Capacity, and Request separate. A reservation without expiry or a release condition cannot support a positive decision. Unknown allocatable capacity cannot be turned into AVAILABLE by positive quota headroom.

5. What quota proves—and does not prove

Kubernetes ResourceQuota constrains aggregate namespace consumption, but quotas are independent of physical cluster capacity. quota_remaining=6 proves six entitlement units remain; it does not prove six GPU units are physically allocatable now.

6. Reservation is not historical deletion

A reservation has owner, quantity, start, expiry, and release condition. When it expires, its active commitment becomes zero, while the historical record remains. Rewriting history destroys the evidence needed to explain previous scarcity windows.

7. Admission algorithm

Evaluate in order: evidence validity; quota headroom; active reservations; remaining allocatable capacity; and exception authority. Results can be ADMITTED, ADMITTED_OVERRIDE, QUEUED, REJECTED, or typed evidence states such as HOLD/UNKNOWN/DISPUTED/STALE/BLOCKED.

8. Worked baseline

Two ventures each have quota for eight GPU units, but only ten units are allocatable. Venture A reserves four units until 23:00. Venture B has already used two quota units and requests six. B has quota_remaining=6; capacity after A's active reservation is also 10-4=6, so the request is ADMITTED. Aggregate quota is 16 against physical capacity 10, so contention_state=ENTITLEMENT_OVERBOOKED remains visible.

9. Raising quota does not create capacity

If B's quota increases from 8 to 12 while capacity stays 10 and A still reserves 4, B may have ten quota units of headroom but only six units of unreserved physical capacity. An eight-unit request must be queued or rejected. Quota expansion did not create capacity.

10. Expiry and release

Active commitment is evaluated at decision time. If a reservation expired at 19:00 and the request arrives at 20:00, it must not remain committed. If the reported reservation total still counts it, the ledger is DISPUTED until lifecycle evidence is reconciled.

11. Emergency override

Override is not an invisible bypass. Scope, exception quantity, time, reason, and override_authority must be recorded, and real capacity must still support the request. Urgency never manufactures authority; an override without authority is BLOCKED.

12. Incomplete and negative evidence

capacity_allocatable=None produces UNKNOWN, not availability. Missing reservation expiry/release evidence produces HOLD. Old decisive evidence produces STALE. A reservation total inconsistent with lifecycle evidence produces DISPUTED. These states stop overclaiming.

13. Transfer: early expiry plus a third venture

In the transfer case, A's reservation expires early. Venture C has normal quota 4, requests 6, and receives an explicit two-unit emergency override from the named authority. Active reservation is now zero, free capacity is 10, effective quota is 6, and the result is ADMITTED_OVERRIDE. Historical reservation records remain intact.

14. Lab execution

Open lab/ARC-004-LAB1/learner/ and run python run_checks.py offline. Eight fixtures cover baseline, quota-only false confidence, expired-reservation mismatch, unknown capacity, unauthorized override, stale evidence, missing expiry, and transfer. Explain the failed gate instead of memorizing outputs.

15. Assessment, freshness, and claim boundary

Assessment covers boundary retrieval, baseline construction, mutation diagnosis, and transfer. Kubernetes sources bound FACT semantics for quotas and scheduling. The state machine, reservation lifecycle policy, and override gate remain MAKNOW DESIGN. Material source changes require a new qualified package version rather than silent mutation of this Golden.