--- id: STATE-PFM-QRY-007 title: Query schedule enablement object: DOM-PFM-QRY-004 product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 states: - name: enabled meaning: The recurrence supplies a next occurrence for dispatch when due. - name: paused meaning: >- The schedule has been paused by a person or created paused as a duplicate; manual execution remains separately available. - name: paused by Platform meaning: >- Automatic execution stopped after access loss or a five-failure streak, with a visible pause reason. - name: paused for a deleted report meaning: Its source report was removed; the remaining schedule can be deleted but cannot resume. - name: imported and paused meaning: The converted legacy delivery awaits confirmation that the old schedule has stopped. - name: deleted meaning: >- Deletion removed the schedule and its run and delivery rows; existing files retain their own expiry. transitions: - from: enabled to: paused trigger: An authorized person pauses recurrence. guard: The caller is the owner or has schedule-management authority. side_effects: - the scheduler clears the next occurrence who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/services/schedules/query-schedule-library.ts' - from: paused to: enabled trigger: An authorized person resumes a user-paused schedule. guard: The caller can operate it and the owner can execute its source. side_effects: - the next occurrence is calculated from the resume time who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:resumeQuerySchedule' - from: paused by Platform to: enabled trigger: The person resumes after an automatic pause. guard: The caller can operate the schedule and passes resume checks. side_effects: - the pause reason and failure streak are cleared; recurrence is recalculated who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/services/schedules/query-schedule-library.ts' - from: imported and paused to: enabled trigger: The imported schedule is resumed. guard: The request acknowledges that the legacy schedule is disabled. side_effects: - recurrence is calculated from the new resume time who: owner or schedule manager provenance: documented source: 'services-platform:docs/migrations/query-scheduling-exports/README.md#D13' - from: enabled to: paused by Platform trigger: Automatic execution detects source access loss. guard: The failed work is an automatic occurrence rather than a manual runner’s access failure. side_effects: - access_lost settles the run and the schedule receives its access-loss pause reason who: system (schedule consumer) provenance: observed source: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' - from: enabled to: paused by Platform trigger: The failure streak reaches five runs. guard: The failure threshold is reached. side_effects: - the scheduler records its automatic-pause event who: system (scheduling library) provenance: observed source: >- services-platform:node_modules/@rhythmsoftware/macroservice-schedules/dist/schedule-repository.js (DEFAULT_AUTO_PAUSE_AFTER_FAILURES) - from: enabled to: paused for a deleted report trigger: The source report is removed. guard: This enabled schedule refers to that report. side_effects: - >- the deletion transaction pauses recurrence, records report_deleted and clears the report reference who: system (report deletion) provenance: observed source: 'services-platform:modules/queries/services/reports/report-library.ts:removeReport' - from: paused to: paused for a deleted report trigger: The paused schedule’s source report is removed. guard: This schedule refers to that report. side_effects: - the deletion transaction records the report-deleted pause who: system (report deletion) provenance: observed source: 'services-platform:modules/queries/services/reports/report-library.ts:removeReport' - from: paused for a deleted report to: deleted trigger: The remaining report-deleted schedule is removed. guard: The caller can operate the schedule. side_effects: - run and recipient rows cascade away; completed files keep their own lifetime who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/db/query-schedules.table.ts' - from: enabled to: deleted trigger: The enabled schedule is removed. guard: The caller can operate the schedule. side_effects: - dependent run and delivery rows are removed who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:deleteQuerySchedule' - from: paused to: deleted trigger: The paused schedule is removed. guard: The caller can operate the schedule. side_effects: - dependent run and delivery rows are removed who: owner or schedule manager provenance: observed source: 'services-platform:modules/queries/aws/api/query-schedules.routes.ts:deleteQuerySchedule' invalid: - from: paused for a deleted report to: enabled why: A removed report leaves no source to resume or execute manually. - from: imported and paused to: enabled why: >- Legacy resume requires the explicit old-schedule-disabled confirmation; the guard cannot independently verify the external schedule. concurrency: >- Version-aware edits go through the scheduling library to recalculate due time. An occurrence already queued can execute after a crossing pause. Ownership changes and query refreshes do not themselves change enablement. evidence: - >- services-platform at ad3f6a6: modules/queries/services/schedules/*.ts; db/query-schedules.table.ts, schedules.table.ts; aws/api/query-schedules.routes.ts; @rhythmsoftware/macroservice-schedules (schedule-states, schedule-repository); docs/migrations/query-scheduling-exports/README.md (D2–D13) --- # Query schedule enablement ## The Lifecycle ```mermaid stateDiagram-v2 state "enabled" as s0 state "paused" as s1 state "paused by Platform" as s2 state "paused for a deleted report" as s3 state "imported and paused" as s4 state "deleted" as s5 s0 --> s1 s1 --> s0 s2 --> s0 s4 --> s0 s0 --> s2 s0 --> s2 s0 --> s3 s1 --> s3 s3 --> s5 s0 --> s5 s1 --> s5 ``` Enablement includes user pauses and distinct operational pause reasons. The reason determines whether the owner can resume or must remove the schedule. ## Transitions Explained Pause and resume update recurrence through the scheduling library. Access failures, repeated failures and report removal set their corresponding automatic reasons. ## What Cannot Happen A deleted report cannot be restored through schedule resume. Legacy confirmation is a required acknowledgement rather than an external-system verification. ## Concurrency and Timing A pause cannot recall an occurrence already handed to the queue; subsequent due occurrences stop.