--- id: ATS-PFM-DJE-019 scope: CAP-PFM-DJE-019 product_area: platform module: data-job-engine revision: 2 status: proposed approved_by: null approved_at: null source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 scenarios: - id: ATS-PFM-DJE-019-01 title: Pressure classification follows strict thresholds level: unit proves: - BR-CAP-PFM-DJE-019-01 preconditions: Supply literal signal readings. steps: - do: Evaluate their pressure levels. expect: >- Strictly exceeding configured thresholds produces the corresponding level; an API without a baseline is not classified by latency. provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is constrained when ACU utilization is above 80 % expected: >- Strictly exceeding configured thresholds produces the corresponding level; an API without a baseline is not classified by latency. negative: false data_needs: No additional fixture is needed. bound_to: - TST-PFM-DJE-159 provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is constrained when ACU utilization is above 80 % category: boundary binding_evidence: - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is constrained when ACU utilization is above 80 % - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is constrained when the proxy borrow latency p99 is above 1 s - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is critical when ACU is at its maximum and CPU is above 85 % - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#does not judge an API that has no baseline yet - id: ATS-PFM-DJE-019-02 title: Consistent readings and spacing govern transitions level: unit proves: - BR-CAP-PFM-DJE-019-02 preconditions: Prepare alternating and sustained reading sequences. steps: - do: Evaluate sequential state decisions. expect: >- Three supporting readings permit escalation, the spacing interval prevents another immediate transition and scaling alone remains constrained. provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#enters constrained on three constrained readings in a row expected: >- Three supporting readings permit escalation, the spacing interval prevents another immediate transition and scaling alone remains constrained. negative: false data_needs: No additional fixture is needed. bound_to: - TST-PFM-DJE-159 provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#enters constrained on three constrained readings in a row category: transition binding_evidence: - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#enters constrained on three constrained readings in a row - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#stays normal on two constrained readings and a calm one - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#makes no second change within five minutes of the last - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#is never critical while ACU is below its maximum, however high the CPU (scenario 14) - id: ATS-PFM-DJE-019-03 title: Protection states supply their declared factors level: unit proves: - BR-CAP-PFM-DJE-019-03 preconditions: Prepare each capacity state. steps: - do: Inspect its workload factors. expect: >- Constrained halves bulk and heavy; critical stops bulk and quarters heavy while leaving ordinary factors unchanged. provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#halves bulk and heavy in constrained and arms the read ceiling expected: >- Constrained halves bulk and heavy; critical stops bulk and quarters heavy while leaving ordinary factors unchanged. negative: false data_needs: No additional fixture is needed. bound_to: - TST-PFM-DJE-159 provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#halves bulk and heavy in constrained and arms the read ceiling category: rule binding_evidence: - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#halves bulk and heavy in constrained and arms the read ceiling - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#stops bulk and quarters heavy in critical, keeping writes and reads whole - id: ATS-PFM-DJE-019-04 title: Capacity management is staff-only and permissioned level: api proves: - BR-CAP-PFM-DJE-019-04 preconditions: Use a staff caller holding another HQ key and a customer administrator. steps: - do: Attempt a pin mutation as the staff caller and a pin read as the customer administrator. expect: Both requests receive a forbidden response. provenance: test source: >- services-platform:modules/capacity/tests/e2e/capacity-pins.e2e.spec.js#refuses a staff member who holds only another HQ key expected: Both requests receive a forbidden response. negative: true data_needs: Permission personas. bound_to: - TST-PFM-DJE-152 provenance: test source: >- services-platform:modules/capacity/tests/e2e/capacity-pins.e2e.spec.js#refuses a staff member who holds only another HQ key category: permission binding_evidence: - >- services-platform:modules/capacity/tests/e2e/capacity-pins.e2e.spec.js#refuses a staff member who holds only another HQ key - >- services-platform:modules/capacity/tests/e2e/capacity-pins.e2e.spec.js#refuses a customer's administrator, whatever they hold at their customer's scope - id: ATS-PFM-DJE-019-05 title: Invalid pins preserve the stored override level: api proves: - BR-CAP-PFM-DJE-019-05 preconditions: Prepare a stored pin. steps: - do: 'Send unknown states, blank reasons and invalid expiry times.' expect: Each refusal identifies its field and leaves the pin intact. provenance: test source: >- services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#refuses a state that is not one of the four, naming state expected: Each refusal identifies its field and leaves the pin intact. negative: true data_needs: No additional fixture is needed. bound_to: - TST-PFM-DJE-153 provenance: test source: >- services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#refuses a state that is not one of the four, naming state category: validation binding_evidence: - >- services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#refuses a state that is not one of the four, naming state - >- services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#refuses a blank reason, naming reason - >- 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 - >- services-platform:modules/capacity/tests/integration/services/persistence/capacity-state-pins.integration.spec.js#leaves the stored pin unchanged after every refusal - id: ATS-PFM-DJE-019-06 title: Pin changes have audit attribution level: api proves: - BR-CAP-PFM-DJE-019-06 preconditions: No existing pin is required. steps: - do: Create and release a pin. expect: Both audit entries describe before and after values. 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 expected: Both audit entries describe before and after values. negative: false data_needs: No additional fixture is needed. bound_to: - TST-PFM-DJE-155 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 category: invariant binding_evidence: - >- 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 - id: ATS-PFM-DJE-019-07 title: Sustained emergency respects the throttle switch level: unit proves: - BR-CAP-PFM-DJE-019-07 preconditions: 'Prepare switch-off and switch-on cases, prolonged emergency and recovery.' steps: - do: Evaluate decisions and apply stage changes. expect: >- Disabled throttling makes no gateway call; enabled prolonged emergency changes declared values and recovery restores them. provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#applies the stage throttles after five further minutes of emergency without relief expected: >- Disabled throttling makes no gateway call; enabled prolonged emergency changes declared values and recovery restores them. negative: false data_needs: Gateway and signal test doubles. bound_to: - TST-PFM-DJE-159 - TST-PFM-DJE-156 provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#applies the stage throttles after five further minutes of emergency without relief category: failure binding_evidence: - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#applies the stage throttles after five further minutes of emergency without relief - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#never applies the stage throttles when the flag is off - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#restores the stage throttles first, before leaving emergency - >- services-platform:modules/capacity/tests/unit/services/capacity/apply-emergency-throttles.spec.ts#makes no call to API Gateway - >- services-platform:modules/capacity/tests/unit/services/capacity/apply-emergency-throttles.spec.ts#patches the stage-wide method settings with the emergency rate and burst - >- services-platform:modules/capacity/tests/unit/services/capacity/apply-emergency-throttles.spec.ts#patches the stage back to its normal rate and burst - id: ATS-PFM-DJE-019-08 title: Consecutive signal failures restore the normal state level: unit proves: - BR-CAP-PFM-DJE-019-08 preconditions: Prepare previous critical state without a pin and failed signal reads. steps: - do: Evaluate the first and second failed ticks. expect: The first holds critical and the second returns normal. provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#keeps the previous state for one tick expected: The first holds critical and the second returns normal. negative: false data_needs: A signal test double. bound_to: - TST-PFM-DJE-159 provenance: test source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#keeps the previous state for one tick category: failure binding_evidence: - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#keeps the previous state for one tick - >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#falls to normal on the second failed read in a row - id: ATS-PFM-DJE-019-09 title: One publication failure leaves the other channel usable category: failure level: api proves: - BR-CAP-PFM-DJE-019-09 preconditions: Prepare a decided critical state and independent cache and parameter clients. steps: - do: 'Fail each publication channel in turn, then fail both.' expect: >- One failed channel leaves the other carrying the decision; failure of both makes the invocation fail. provenance: proposed source: 'services-platform:docs/workload-governance.md#Capacity sentinel' expected: >- One failed channel leaves the other carrying the decision; failure of both makes the invocation fail. negative: true data_needs: Prepare a decided critical state and independent cache and parameter clients. bound_to: [] provenance: proposed source: 'services-platform:docs/workload-governance.md#Capacity sentinel' - id: ATS-PFM-DJE-019-10 title: A critical protection factor holds admission without stalled failure category: interaction level: api exercises: - CAP-PFM-DJE-014 - CAP-PFM-DJE-019 proves: - BR-CAP-PFM-DJE-014-05 - BR-CAP-PFM-DJE-014-07 - BR-CAP-PFM-DJE-019-03 preconditions: Prepare a file job with waiting batches and a readable capacity factor of zero. steps: - do: >- Attempt admission beyond fifteen minutes, then publish normal capacity and attempt it again. expect: >- Zero capacity holds the job without a stalled failure; restored capacity admits work within the remaining ceilings. provenance: proposed source: >- macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#hands over no more batches at once than the budget allows; macroservice-libraries:packages/data-jobs/src/admission-budget.ts:tenantBulkCeiling; macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#fails a job whose ceiling has been held by work that is not moving, rather than waiting for room for ever; services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#stops bulk and quarters heavy in critical, keeping writes and reads whole expected: >- Zero capacity holds the job without a stalled failure; restored capacity admits work within the remaining ceilings. negative: true data_needs: Prepare a file job with waiting batches and a readable capacity factor of zero. bound_to: [] provenance: proposed source: >- macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#hands over no more batches at once than the budget allows; macroservice-libraries:packages/data-jobs/src/admission-budget.ts:tenantBulkCeiling; macroservice-libraries:packages/data-jobs/src/tests/integration/bulk-data-jobs.integration.spec.ts#fails a job whose ceiling has been held by work that is not moving, rather than waiting for room for ever; services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#stops bulk and quarters heavy in critical, keeping writes and reads whole - id: ATS-PFM-DJE-019-11 title: Capacity protection does not gate scheduled partition maintenance category: interaction level: api exercises: - CAP-PFM-DJE-019 - CAP-PFM-DJE-020 proves: - BR-CAP-PFM-DJE-019-03 - BR-CAP-PFM-DJE-020-01 - BR-CAP-PFM-DJE-020-04 preconditions: 'Prepare critical capacity and registered history tables, including one failing table.' steps: - do: Keep bulk admission held while running the scheduled maintenance pass. expect: >- History maintenance still prepares eligible storage and reports its failing table; it does not consume bulk admission slots. provenance: proposed 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; services-platform:modules/partitions/tests/integration/services/maintenance/maintain-partitions.integration.spec.js#creates the current month and the two after it on the first run, and drops nothing; services-platform:modules/partitions/aws/logic/partitions-maintenance.schedule.ts:createPartitionsMaintenanceSchedule; services-platform:modules/partitions/tests/integration/services/maintenance/maintain-partitions.integration.spec.js#fails the run as a whole when one table’s pass failed, naming that table expected: >- History maintenance still prepares eligible storage and reports its failing table; it does not consume bulk admission slots. negative: true data_needs: 'Prepare critical capacity and registered history tables, including one failing table.' bound_to: [] provenance: proposed 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; services-platform:modules/partitions/tests/integration/services/maintenance/maintain-partitions.integration.spec.js#creates the current month and the two after it on the first run, and drops nothing; services-platform:modules/partitions/aws/logic/partitions-maintenance.schedule.ts:createPartitionsMaintenanceSchedule; services-platform:modules/partitions/tests/integration/services/maintenance/maintain-partitions.integration.spec.js#fails the run as a whole when one table’s pass failed, naming that table 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). - >- Testing back-fill: related capability rules, domain invariants, state transitions and crossing workflows at the pinned source revisions. coverage: rule: covered transition: 'gap: FND-PFM-DJE-079' validation: covered permission: covered edge: 'gap: FND-PFM-DJE-079' failure: covered boundary: covered concurrency: 'gap: FND-PFM-DJE-079' invariant: covered interaction: covered coverage_notes: transition: >- Selected lifecycle examples do not cover every applicable object and batch transition. The linked finding retains the remaining matrix. execution: >- Covered means a specification scenario exists. Proposed scenarios and registered suites with no run result do not establish executed conformance. related: - CAP-PFM-DJE-014 workflows: - WF-PFM-DJE-015 - WF-PFM-DJE-016 coverage_evidence: - rule: BR-CAP-PFM-DJE-019-01 scenarios: - ATS-PFM-DJE-019-01 provenance: proposed source: 'services-platform:modules/capacity/services/capacity/decide-state.ts:assessReading' - rule: BR-CAP-PFM-DJE-019-02 scenarios: - ATS-PFM-DJE-019-02 provenance: proposed source: >- services-platform:modules/capacity/tests/unit/services/capacity/decide-state.spec.ts#makes no second change within five minutes of the last - rule: BR-CAP-PFM-DJE-019-03 scenarios: - ATS-PFM-DJE-019-03 - ATS-PFM-DJE-019-10 - ATS-PFM-DJE-019-11 provenance: proposed 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 - rule: BR-CAP-PFM-DJE-019-04 scenarios: - ATS-PFM-DJE-019-04 provenance: proposed 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 - rule: BR-CAP-PFM-DJE-019-05 scenarios: - ATS-PFM-DJE-019-05 provenance: proposed 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 - rule: BR-CAP-PFM-DJE-019-06 scenarios: - ATS-PFM-DJE-019-06 provenance: proposed 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 - rule: BR-CAP-PFM-DJE-019-07 scenarios: - ATS-PFM-DJE-019-07 provenance: proposed source: 'services-platform:docs/workload-governance.md#Capacity sentinel' - rule: BR-CAP-PFM-DJE-019-08 scenarios: - ATS-PFM-DJE-019-08 provenance: proposed source: 'services-platform:modules/capacity/services/capacity/decide-state.ts:decideCapacityState' --- # Control capacity protection during database pressure: Capability Test Specification ## Coverage The structured coverage rows link required rules to their scenarios. A covered category has a defined check; executable coverage and successful execution require separate evidence. The category map keeps incomplete lifecycle matrices and other missing checks visible as findings. ## Interactions With Related Capabilities A critical protection factor holds admission without stalled failure. Capacity protection does not gate scheduled partition maintenance. The interaction scenarios use the related capabilities' rule references and identify the shared fixture and observable outcome.