Resource Envelope and Protected Primary

1. A correct worker can still harm the primary workload

A background worker may be functionally correct while consuming CPU, memory, or I/O in a way that degrades the user-facing application. This lesson therefore separates worker success from primary-workload protection. The owned artifact is Node Resource Envelope & Primary Protection Budget v1: a versioned set of bounds and observations that states what the worker may consume, what headroom must remain for the primary workload, and when pressure requires degradation or pause.

2. LOC-014 owns only the resource-protection boundary

This lesson owns Resource Envelope and Protected Primary. Node-control authorization belongs to LOC-013, and power transitions belong to LOC-015. A resource decision may say that worker execution must pause, but it does not grant authority to shut down the node or redefine an operator grant. Keeping these concerns separate makes each decision auditable against its own evidence.

3. The envelope must be versioned and auditable

Record envelope_version, worker_class, and the measurement window. CPU, memory, I/O, and concurrency need independent fields. Changing a threshold without a new version destroys before/after comparability. An auditable result must identify which envelope version was evaluated, in which window, against which telemetry.

4. CPU weight is not a CPU hard cap

A CPU weight is a relative share under contention; a hard cap is a maximum bandwidth or rate. Linux cgroup v2 exposes cpu.max as a maximum bandwidth control. Windows Job Objects expose weight-based, hard-cap, and min/max CPU-rate modes with different semantics. The same-looking number does not imply the same behavior. Record the control mode and effective state, not an ambiguous percentage.

5. memory.low, memory.high, and memory.max have different meanings

In cgroup v2, memory.low is best-effort reclaim protection, memory.high creates throttling and reclaim pressure, and memory.max is the hard memory boundary. Crossing memory.high while remaining below memory.max is not automatically a hard-limit failure, but it is valid evidence of pressure and can justify degradation. Reaching a hard ceiling requires a stronger response such as pause or recovery.

6. Bound I/O and concurrency independently

A worker can remain inside CPU and memory bounds yet still damage interactivity through I/O bursts or excessive concurrency. Keep io_weight/io_budget and concurrency_cap separate. A one-number envelope is not defensible for a multi-resource workload.

7. Protected Primary is an explicit reservation

Primary headroom must be measurable: minimum CPU headroom, minimum memory headroom, or a maximum interactive-latency budget. The goal is not to let the worker consume every spare unit of machine capacity; it is to preserve declared room for the primary workload. If the worker is under its own cap but primary latency exceeds its budget, protection has failed and the decision cannot remain RUN.

8. Configured limits and effective limits are separate evidence

A successful API call or configuration write proves only that a request was made. Keep separate evidence for the effective control: state queries, accounting, notifications, or telemetry. Windows Job Objects provide accounting and limit-notification mechanisms, which supports this separation between configured constraint and observed behavior. If effective state is unconfirmed, preserve UNKNOWN rather than promoting to RUN.

9. Observe both the worker and the primary workload

For the worker, record observed CPU, memory pressure, and I/O. For the primary workload, record latency and reserved headroom. Looking only at the worker is insufficient. Protected Primary is supported only when worker bounds and primary metrics are simultaneously satisfied in the declared window.

10. Degrade before pause when the evidence supports it

Soft pressure can justify degradation: reduce concurrency, batch size, or cadence. If pressure is sustained but neither the hard ceiling nor primary protection is violated, degradation is more proportional than a full pause. Hard-limit breach, exhausted primary headroom, or severe latency violation can require pause. Every decision should include a reason and a recheck trigger.

11. Build a reproducible decision table

Each row should retain envelope version, CPU mode and limit, memory boundaries, I/O budget, concurrency, primary headroom, observed values, effective-limit evidence, violations, degrade/pause state, and reason. The table exists so another reviewer can reproduce the state without hidden reasoning.

12. Linux and Windows are enforcement mappings, not project thresholds

On Linux, the design can map to cgroup v2; on Windows, to Job Objects and CPU rate control. But MAKNOW thresholds do not come from operating-system documentation. The OS defines what a primitive means; the project defines what headroom and degradation/pause policy are appropriate for its workload.

13. Worked example: inference beside an active compile

Assume an inference worker on a workstation with a 35% hard CPU cap, memory.high at 6 GB, memory.max at 8 GB, an 80 MB/s I/O budget, and concurrency of 2. The primary latency budget is 120 ms. If worker memory rises to 6.7 GB while remaining below the hard maximum and primary latency is 105 ms, the bounded state is DEGRADED: soft memory pressure exists, but not a hard failure. If primary latency rises to 180 ms even while worker CPU is only 30%, PAUSE is justified because Protected Primary is violated.

14. Deterministic failure probes

Reject four shortcuts: (1) do not equate crossing memory.high with OOM; (2) do not equate staying under the worker cap with a healthy primary workload; (3) do not treat CPU weight as a percentage ceiling; and (4) do not treat successful configuration as proof of effective enforcement. The lab exercises these distinctions with deterministic synthetic fixtures while keeping expected labels out of learner-visible material.

15. Transfer to a lower-memory battery-powered laptop

Move the same worker to a laptop with less RAM and a tighter interactive-latency requirement. Preserve the envelope structure, but recompute memory high/max, concurrency, CPU window, and primary-latency budget. Do not copy the workstation decision. Rebuild the state from the new evidence. The invariant is measurable primary protection, not a fixed set of numbers.