---
id: CAP-PFM-DJE-019
title: Control capacity protection during database pressure
feature: FEAT-PFM-DJE-06
product_area: platform
module: data-job-engine
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
intent_sources:
  - 'services-platform:docs/workload-governance.md#Capacity sentinel'
purpose: >-
  Capacity protection reduces shared workload budgets under database pressure and allows staff to hold a
  bounded state during an incident.
outcomes:
  - Repeated pressure readings guide gradual state changes.
  - Bulk work yields capacity before ordinary traffic is reduced.
  - 'Staff overrides require a reason, expiry and audit record.'
concepts:
  - CON-PFM-DJE-006
actors:
  - ACT-PFM-038
  - ACT-PFM-012
surfaces:
  - api
  - job
preconditions: []
postconditions: []
permissions:
  - key: hq.capacity.manage
    where_checked: api
    scope: global
rules:
  - id: BR-CAP-PFM-DJE-019-01
    proved_by: [ATS-PFM-DJE-019-01, TST-PFM-DJE-159]
    statement: >-
      Minute readings classify pressure using capacity utilization above 80%, load above 1.5 times the
      derived processor estimate, connection borrowing above one second, API latency above twice baseline
      or detected scaling; saturation or borrowing above three seconds is critical.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/capacity/services/capacity/decide-state.ts:assessReading'
    origin: none
    note: >-
      The implementation estimates one processor per ACU, treats 98% utilization as the configured
      maximum, and detects scaling from CPU at least 50% rising by at least five points.
  - id: BR-CAP-PFM-DJE-019-02
    proved_by: [ATS-PFM-DJE-019-02, TST-PFM-DJE-159]
    statement: >-
      Automatic escalation requires three supporting readings, recovery steps down after five calmer
      readings, and changes are spaced by five minutes; sustained critical readings can then enter
      emergency, while scaling alone reaches only constrained.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#makes no
      second change within five minutes of the last
    origin: none
  - id: BR-CAP-PFM-DJE-019-03
    proved_by: [ATS-PFM-DJE-014-12, ATS-PFM-DJE-019-03, ATS-PFM-DJE-019-10, ATS-PFM-DJE-019-11, ATS-PFM-DJE-020-05, TST-PFM-DJE-159]
    statement: >-
      Constrained applies 0.5 bulk and heavy factors; critical applies zero bulk and 0.25 heavy;
      emergency additionally applies 0.5 write and read factors.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#stops bulk and
      quarters heavy in critical, keeping writes and reads whole
    origin: none
  - id: BR-CAP-PFM-DJE-019-04
    proved_by: [ATS-PFM-DJE-019-04, TST-PFM-DJE-152]
    statement: >-
      Capacity inspection and pin management use staff-only routes and capacity authority;
      customer-scoped administrators cannot use them.
    kind: permission
    enforced_at:
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/e2e/capacity-pins.e2e.spec.js#refuses a customer's
      administrator, whatever they hold at their customer's scope
    origin: none
  - id: BR-CAP-PFM-DJE-019-05
    proved_by: [ATS-PFM-DJE-019-05, TST-PFM-DJE-153]
    statement: >-
      A capacity pin requires a known state, nonblank reason and future expiry within 24 hours; invalid
      input names its field without changing the stored pin.
    kind: validation
    enforced_at:
      - api
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#refuses
      an expiry more than a day ahead, naming expires_at
    origin: none
  - id: BR-CAP-PFM-DJE-019-06
    proved_by: [ATS-PFM-DJE-019-06, TST-PFM-DJE-155]
    statement: >-
      Pin and release operations audit their previous and resulting values; the next sentinel tick
      applies an active pin without the automatic spacing restriction.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/integration/services/pins/capacity-pins.integration.spec.js#records
      the pin and its removal, each with what it was and what it became
    origin: none
  - id: BR-CAP-PFM-DJE-019-07
    proved_by: [ATS-PFM-DJE-019-07, TST-PFM-DJE-156, TST-PFM-DJE-159]
    statement: >-
      When enabled and emergency readings persist for five further minutes, the sentinel applies declared
      emergency stage throttles and restores their normal values on recovery.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: documented
    source: 'services-platform:docs/workload-governance.md#Capacity sentinel'
    origin: none
  - id: BR-CAP-PFM-DJE-019-08
    proved_by: [ATS-PFM-DJE-019-08, TST-PFM-DJE-159]
    statement: >-
      Without an active pin, a failed signal read holds the previous state for one tick and a second
      consecutive failure returns it to normal.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/capacity/services/capacity/decide-state.ts:decideCapacityState'
    origin: none
  - id: BR-CAP-PFM-DJE-019-09
    proved_by: [ATS-PFM-DJE-019-09]
    statement: >-
      The sentinel publishes its state independently to cache and parameter channels so one failed write
      does not prevent the other.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: documented
    source: 'services-platform:docs/workload-governance.md#Capacity sentinel'
    origin: none
scenarios:
  - id: SC-CAP-PFM-DJE-019-01
    given: Three consecutive readings show capacity utilization above 80%.
    when: The sentinel evaluates the new window.
    then: It enters constrained and publishes a bulk factor of one half.
    provenance: test
    source: >-
      services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#enters
      constrained on three constrained readings in a row
edge_cases: []
constraints: []
depends_on: []
related:
  - CAP-PFM-DJE-014
journeys: []
open_questions: []
evidence:
  - >-
    Reviewed evidence: services-platform (ad3f6a65): docs/workload-governance.md (Capacity sentinel;
    Capacity table); modules/capacity/** (routes, schemas, services decide-state, run-sentinel,
    publish-state, apply-emergency-throttles, capacity-pins; db capacity-state-pins.table.ts); tests
    decide-state.spec.ts, capacity-state-pins.integration.spec.js, capacity-pins.integration.spec.js,
    capacity-pins.e2e.spec.js.
  - >-
    Reviewed evidence: macroservice-libraries (54536a44): packages/data-jobs/README.md (The ports:
    capacityFactor).
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-IAM-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-DJE-06-01, FAS-PFM-DJE-06-02, FAS-PFM-DJE-06-03, FAS-PFM-DJE-06-04, FAS-PFM-DJE-06-05]
suites: [TST-PFM-DJE-152, TST-PFM-DJE-153, TST-PFM-DJE-155, TST-PFM-DJE-156, TST-PFM-DJE-159]
---

# Control capacity protection during database pressure

## Purpose

Capacity protection reduces shared workload budgets under database pressure and allows staff to hold a bounded state during an incident.

## How It Works

The sentinel periodically reads database pressure and API latency signals. It classifies those readings before deciding whether a state transition is justified. Several consistent readings and a spacing interval prevent rapid oscillation. More severe states reduce bulk and heavy budgets first. Sustained emergency can also reduce ordinary write and read budgets. Authorized staff can pin a known state with an expiry and reason. The pin takes precedence over automatic readings until it expires. Emergency stage changes require a separate switch and declared throttle targets. Independent publication channels distribute the factors. The thresholds remain proposed values whose operational fitness needs load evidence.

## Relationships

- File admission uses the published bulk factor to reduce its budget.