Appendix A - 11. Resource-pressure gating (admit before, shed during)

The Structure of Resource-pressure gating (admit before, shed during) — its shape at a glance:

One pressure signal has three readers: an admission gate left of dispatch that refuses doomed work before a worktree exists, an execution shed at compute that stops a job pressure has overtaken, and an advisory callable for operator judgment.

flowchart LR
  Monitor[(Pressure signal<br/>GREEN/YELLOW/RED)] --> Admit{Admission gate}
  Monitor --> Shed{Execution shed}
  Monitor --> Advise([Advisory read])
  Admit -->|RED| Defer([Refuse / defer dispatch])
  Shed -->|RED| Stop([Shed running job])

Accessible description: one host-pressure signal feeds three readers — an admission gate that refuses or defers a heavy dispatch under RED before a worktree exists, an execution shed that stops a running heavy job under RED, and an advisory callable the operator consults — so heavy work is neither started into nor left running on an overloaded host.

Projected from the catalogue entry mediators-and-resource-locks / Resource-pressure gating (admit before, shed during).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Govern a saturable host resource with a live pressure signal read at two layers: an admission gate that refuses or defers heavy work before it is dispatched, and an execution shed that stops heavy work already running when pressure spikes, both driven by one signal that is also callable for the operator's own judgment. Heavy work is then neither started into an overloaded host nor left running on one (our instance: a GREEN/YELLOW/RED host-load monitor that gates agent dispatch and sheds heavy compute at the mediators).

Motivation

A cardinality cap (N-at-a-time) bounds how many heavy jobs run, not whether the host can bear them right now. Two failures follow. Dispatch into overload: the orchestrator admits a heavy agent onto an already-saturated machine because the only pre-dispatch check guards a different resource (free disk, say); the agent starts, reaches the compute mediators, and is refused, so it polls and sheds, burning wall-clock (a heavy agent has burned ~10 minutes polling) on work that never had headroom. Run into overload: pressure rises after a job was admitted, and nothing stops the now-too-heavy job mid-flight. Cardinality caps and single-resource admission checks miss both. The missing ingredient is a live pressure reading consulted at the two moments work is admitted and executed.

Applicability

A live pressure signal over the saturable resource, cheap enough to read at every dispatch and every compute entry.
A pre-dispatch gate seam the signal can hang on, sibling to whatever admission checks already exist (disk floor, quota).
An execution-time shed the signal drives at the compute step.
One signal, shared: admission and execution must read the same reading, or they disagree (admit-then-shed churn is that disagreement, when only the execution layer reads pressure).
A heavy-vs-light work class, so light work is not gated by a signal only heavy work saturates.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The two layers are not redundant: admission prevents the startup cost of doomed work; execution shedding catches pressure that rose after admission. One shared signal drives both, or they disagree and reintroduce the admit-then-shed churn.

def read_pressure() -> str:
    """One coarse level over the saturable resource — cheap enough for every dispatch and compute entry."""
    ...  # returns "GREEN" | "YELLOW" | "RED"

def admit_dispatch(is_heavy: bool) -> str:
    if is_heavy and read_pressure() == "RED":          # gate LEFT of dispatch — never start doomed work
        return "defer"                                  # defer with a wake condition, never silently drop
    return "admit"

def compute_shed(is_heavy: bool) -> str:
    if is_heavy and read_pressure() == "RED":          # catches pressure that rose AFTER admission
        return "shed"
    return "run"

Consequences

Coarse by design. GREEN/YELLOW/RED is a blunt instrument: a too-eager RED starves throughput, a too-lax one still admits overload. The thresholds are a tuning surface, not set-and-forget.
Admission must defer, not drop. A heavy brief refused under sustained RED needs a retry/defer policy, or it starves; the gate degrades to a deferral with a wake condition, never a silent drop.
Two readers, one signal; keep them consistent. If the admission gate and the shed read different signals or thresholds, you reintroduce the churn the mechanism exists to kill. One shared signal is what makes the two layers agree.
The advisory read is soft. Its value is the operator choosing to consult it; unlike the gates, it cannot enforce.

Example use within DocAble

A host load/pressure monitor (GREEN/YELLOW/RED) read by the compute mediators to refuse-and-shed heavy-class work under RED.
A pre-dispatch admission gate, sibling to a free-disk floor, that refuses/defers heavy dispatch (⚠️ the disk floor is wired; the load-pressure gate is the identified extension that closes the dispatch-into-overload waste).
The monitor as a plain callable the operator consults for YELLOW-aware dispatch judgment.

Counterpart — aggregate-compute-protection, and the finer test-serializer / build-serializer: they ration heavy compute by cardinality (how many run at once); this rations by live pressure (whether the host can bear more now), across admission and execution. The named axis is cap-the-count versus gate-on-the-condition; a saturable host usually wants both.
Layer — the two readers sit at two points of the path-to-work: the admission gate left of dispatch, the execution shed at compute. The shared signal is what keeps the two layers agreeing. Moving the check left (admission) is the same shift-left logic that puts a cheap gate before an expensive one.