---
id: SVC-PFM-DJE-capacity
title: Capacity Sentinel
product_area: platform
module: data-job-engine
repository: services-platform
source_module: modules/capacity
revision: 1
status: draft
design_intent: confirmed
origin: >-
  services-platform:docs/proposals/api-workload-governance/README.md (D1 to D10
  approved by Andrew 2026-10-17; brief 3.2);
  services-platform:docs/workload-governance.md. Thresholds and budgets are
  proposed starting values.
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
owns:
  - DOM-PFM-DJE-006
does_not_own:
  - >-
    Consuming services apply protection factors through their own admission
    mechanisms.
  - >-
    Gateway rate controls and firewall policies retain their workload-governance
    owners.
  - >-
    Workspace workload profiles belong to operational policy rather than the
    sentinel record model.
operations:
  - operation_id: getCapacityHealth
    intent: Expose function readiness and deployed-build information.
    access: public
    permission: 'none: public health route'
    realises: []
    published_to_submissions: 'not published: operational readiness has no submission contract'
  - operation_id: getCapacityStatePin
    intent: 'Inspect the stored incident override, including an expired value.'
    access: system
    permission: 'hq.capacity.manage (Rhythm staff, system scope)'
    realises:
      - CAP-PFM-DJE-019
    published_to_submissions: 'not published: Rhythm staff operation outside any workspace intake'
  - operation_id: pinCapacityState
    intent: >-
      Replace the protection override with a validated state, reason and bounded
      expiry, recording audit evidence.
    access: system
    permission: 'hq.capacity.manage (Rhythm staff, system scope)'
    realises:
      - CAP-PFM-DJE-019
    published_to_submissions: 'not published: Rhythm staff operation outside any workspace intake'
  - operation_id: unpinCapacityState
    intent: >-
      Remove an existing override and audit the removal so automatic evaluation
      can resume.
    access: system
    permission: 'hq.capacity.manage (Rhythm staff, system scope)'
    realises:
      - CAP-PFM-DJE-019
    published_to_submissions: 'not published: Rhythm staff operation outside any workspace intake'
events: []
jobs:
  - name: platform_capacity_sentinel
    kind: schedule (every minute)
    does: >-
      Gather metrics and memory, evaluate protection, update enabled emergency
      targets and publish independent channel values.
integrations:
  - system: Database and API metrics
    direction: inbound
    contract: >-
      Read the minute metric window and classify unavailable signals as decision
      input.
  - system: API stage throttle parameters
    direction: outbound
    contract: >-
      Update declared API stage targets only when enabled sustained emergency
      permits it.
  - system: Capacity cache and parameter
    direction: outbound
    contract: >-
      Write protection state, factors and decision time independently to cache
      and parameter storage.
consistency:
  - rule: Pin mutation and its audit values share a transaction.
    kind: transactional
    compensation: A failed transaction does not persist a partial pin change.
  - rule: >-
      Published state reaches consumers after scheduled evaluation and their
      cache interval, subject to successful channel writes.
    kind: eventual
    compensation: >-
      Later ticks repair unsuccessful channel publication; invocation recovery
      follows schedule and function delivery policies.
evidence:
  - >-
    services-platform at ad3f6a65: modules/capacity/aws/api/capacity.routes.ts,
    capacity.schemas.ts; aws/logic/capacity-sentinel.lambda.ts,
    capacity-api.lambda.ts; services/**; db/capacity-state-pins.table.ts;
    docs/workload-governance.md.
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-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-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]
---

# Capacity Sentinel

## What This Service Is For

The sentinel publishes shared database protection factors and permits bounded staff incident overrides. Consuming services determine how much work those factors admit.

## Boundary

This contract owns the protection model and staff pin. It exposes public health and staff-only system controls; customer administration grants do not provide access.

## Operations in Words

Authorized staff inspect, replace and remove a pin. Replacement validates state, reason and expiry, and mutations retain audit evidence. Public health reports readiness. None of these routes publishes a Submissions binding.

## Events and Jobs

One reserved-concurrency sentinel evaluates each minute. It writes cache and parameter state rather than publishing a business event. Emergency API stage reductions use a separate switch that starts disabled.

## Consistency Guarantees

Pin writes are transactional, while stage changes and state publications have separate outcomes. An active pin precedes signal fallback; without one, repeated signal failure returns normal. Publication errors can leave stale channels rather than changing the decision to normal.