---
id: WF-PFM-DJE-017
title: Maintain monthly history partitions
trigger: 'Daily scheduled maintenance runs, or deployment requests a create-only pass.'
product_area: platform
module: data-job-engine
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-DJE-020
moves: []
crosses:
  - SVC-PFM-DJE-partitions
hops:
  - 'n': 1
    actor_or_service: 'Partition maintenance (migration function, schema owner)'
    action: >-
      Prepare each registered table’s current and future partitions with
      inherited security.
    anchor: >-
      services-platform:modules/partitions/services/maintenance/maintain-partitions.ts:maintainPartitions
    seam: schedule
    on_failure: Record a table failure and continue the remaining tables.
    left_inconsistent: The failed table may still lack future storage.
    observer: Failure metric and alarm.
    provenance: test
    source: >-
      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
  - 'n': 2
    actor_or_service: Partition maintenance
    action: >-
      During retiring passes, detach eligible months, archive them and drop only
      archived storage.
    anchor: 'services-platform:db/partitions.ts:detachExpiredPartitions'
    seam: schedule
    on_failure: Retain a detached secured month when its archive fails.
    left_inconsistent: Archived or detached leftovers can await another pass.
    observer: Dropped and failed metrics.
    provenance: documented
    source: 'services-platform:docs/partitions.md#The helpers'
  - 'n': 3
    actor_or_service: Partition maintenance
    action: >-
      After all table passes, fail the overall result if any failed; otherwise
      emit its heartbeat.
    anchor: >-
      services-platform:modules/partitions/services/maintenance/maintain-partitions.ts:PartitionMaintenanceFailure
    seam: schedule
    on_failure: Return invocation failure so later maintenance repeats the passes.
    left_inconsistent: Successfully maintained tables keep their completed work.
    observer: Separate failure and heartbeat alarms.
    provenance: test
    source: >-
      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
idempotency: >-
  Existing partitions remain unchanged, and successfully removed months need no
  repeated removal. Detached archive leftovers are found on later passes.
concurrency: >-
  The daily schedule is one invocation pattern, not a global lock against
  deploy-time maintenance. Deployment requests creation only and cannot retire
  history.
branches:
  - >-
    Engine receipts and refusals remain unpartitioned; registered history
    belongs to other modules.
waits: []
evidence:
  - >-
    services-platform at ad3f6a65:
    modules/partitions/services/maintenance/maintain-partitions.ts,
    partitions-maintenance.work.ts;
    aws/logic/partitions-maintenance.schedule.ts;
    aws/lambda/scheduled-maintenance.ts; db/partitioned-tables.ts,
    db/partitions.ts; docs/partitions.md.
controls: [TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Maintain Monthly History Partitions

## What It Does

Partition maintenance prepares current and future history storage and retires eligible old months through each table’s archive contract. It uses the schema-owner connection and continues after individual table failures.

## The Flow

```mermaid
flowchart TD
  H1["Partition maintenance (migration function, schema owner)"] --> H2
  H2["Partition maintenance"] --> H3
  H3["Partition maintenance"]
```

## When Something Fails

Archive failure preserves detached storage, and one table’s failure does not prevent another table’s maintenance. Overall failure and heartbeat signals distinguish errors from a missing successful run.

## Open Design Questions

Product still needs to settle the long-term owner of history maintenance.