---
id: WF-PFM-DJE-016
title: Pin and release the capacity state
trigger: 'Rhythm staff read, replace or remove a capacity pin.'
product_area: platform
module: data-job-engine
revision: 1
status: draft
design_intent: confirmed
origin: >-
  services-platform:docs/proposals/api-workload-governance/README.md (approved
  2026-10-17), README §8.1 and brief 3.2 (operator pin)
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-DJE-019
moves:
  - STATE-PFM-DJE-006
crosses:
  - SVC-PFM-DJE-capacity
hops:
  - 'n': 1
    actor_or_service: Capacity routes (Rhythm HQ)
    action: Require the capacity key at staff system scope.
    anchor: >-
      services-platform:modules/capacity/aws/api/capacity.routes.ts:capacityRoutes
    seam: sync
    on_failure: Return forbidden access to customer administrators.
    left_inconsistent: The override is unchanged.
    observer: The request response exposes the result.
    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
  - 'n': 2
    actor_or_service: Pin service
    action: >-
      Validate state, reason and future expiry, replace the pin and record
      before/after audit values.
    anchor: >-
      services-platform:modules/capacity/services/pins/capacity-pins.ts:pinCapacityState
    seam: sync
    on_failure: Name invalid fields and retain the stored override.
    left_inconsistent: No partial invalid pin is accepted.
    observer: The audit record.
    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
  - 'n': 3
    actor_or_service: Capacity sentinel
    action: >-
      Apply the active pin on evaluation; resume automatic timing after release
      or expiry.
    anchor: >-
      services-platform:modules/capacity/services/capacity/decide-state.ts:decideCapacityState
    seam: schedule
    on_failure: Treat unreadable pin storage as no active override.
    left_inconsistent: Publication may lag the administrative change until evaluation.
    observer: Sentinel logs and the state gauge.
    provenance: observed
    source: >-
      services-platform:modules/capacity/services/capacity/decide-state.ts:decideCapacityState
idempotency: >-
  Replacing a pin overwrites the singleton value. Removing an absent pin
  produces no audit entry.
concurrency: >-
  The pin’s singleton key gives replacement semantics. Audit records describe
  the performed writes; the sentinel applies the value it reads on its next
  tick.
branches: []
waits:
  - >-
    The next minute evaluation observes a new pin; expiry removes its
    precedence.
evidence:
  - >-
    services-platform at ad3f6a65: modules/capacity/aws/api/capacity.routes.ts,
    capacity.schemas.ts; services/pins/capacity-pins.ts;
    services/persistence/capacity-state-pins.ts;
    db/capacity-state-pins.table.ts.
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Pin And Release The Capacity State

## What It Does

Pin management records a bounded incident override and audit evidence. The next sentinel evaluation uses the active pin before resuming automatic metrics-based decisions.

## The Flow

```mermaid
flowchart TD
  H1["Capacity routes (Rhythm HQ)"] --> H2
  H2["Pin service"] --> H3
  H3["Capacity sentinel"]
```

## When Something Fails

Invalid administrative input leaves the prior value intact. Storage and sentinel timing mean a pin change is not an immediate published-state change, and failed pin reads do not hold the override.

## Open Design Questions

The recorded findings identify the remaining limits; this examination does not authorize stronger behavior or change the planning rules.