--- id: SVC-ACC-BKS-maintenance title: Accounting scheduling and lifecycle service product_area: accounting module: books repository: services-accounting source_module: modules/maintenance revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 owns: [] does_not_own: - >- Batches, Reconciliation and Billing own the business handlers invoked for their schedules. - >- Platform owns workspace records and the jobs ordering provisioning, export and erasure. - 'Transactions declares its own participant, which maintenance registers.' - >- Schedule history and lifecycle facets belong to the Accounting workspace object shared with configuration. operations: - operation_id: getSchedulingHealth intent: Report deployment health and the scheduling build identity. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: deployment health, without a captured business request' - operation_id: previewSchedule intent: >- Validate and describe a recurrence and return warnings and five upcoming occurrences in instant and local-time forms, defaulting the zone from the workspace without saving. access: console permission: accounting.application.access realises: - CAP-ACC-BKS-018 published_to_submissions: 'not published: unsaved preview, without an intake capture' - operation_id: listScheduleRuns intent: >- Return newest-first run history in pages capped at two hundred after checking the owner record’s read permission. access: console permission: >- accounting.application.access, plus the owning record's read permission checked by the handler (recurring-batches, batches, reconciliation-exceptions, reconciliation-batches or recurring-billing-runs read) realises: - CAP-ACC-BKS-018 published_to_submissions: >- not published: configuration or operational information retrieval, without an intake capture - operation_id: describe intent: >- Return each Accounting lifecycle participant’s manifest and supported operations. access: internal permission: 'none: invoked by Platform''s lifecycle jobs under the service role' realises: - CAP-ACC-BKS-019 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' - operation_id: provision intent: >- Execute the named participant’s provisioning step; configuration inserts the five provisioned tender methods. access: internal permission: 'none: invoked by Platform''s provisioning job under the service role' realises: - CAP-ACC-BKS-019 - CAP-ACC-BKS-012 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' - operation_id: verifyProvisioned intent: >- Check the named participant’s completion criteria and return missing requirements. access: internal permission: 'none: invoked by Platform''s provisioning job under the service role' realises: - CAP-ACC-BKS-019 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' - operation_id: purge intent: >- Delete one batch from the participant’s first nonempty table after a fresh deleting-state guard, returning continuation or completion. access: internal permission: 'none: invoked by Platform''s deletion job under the service role' realises: - CAP-ACC-BKS-019 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' - operation_id: inventory intent: Count remaining workspace rows in the participant’s declared tables. access: internal permission: 'none: invoked by Platform''s lifecycle jobs under the service role' realises: - CAP-ACC-BKS-019 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' - operation_id: export intent: >- Stage one batch of a declared dataset and return the written part and continuation cursor. access: internal permission: 'none: invoked by Platform''s export job under the service role' realises: - CAP-ACC-BKS-019 published_to_submissions: 'not published: internal workspace orchestration, without an intake capture' events: - name: schedule run message (Accounting schedules queue) direction: produced when: A due claim is offered to the queue payload_summary: >- A versioned run envelope names the workspace, schedule and occurrence and can include correlation details - name: schedule run message (Accounting schedules queue) direction: consumed when: A schedule message arrives at the consumer payload_summary: >- A versioned run envelope names the workspace, schedule and occurrence and can include correlation details jobs: - >- A minute dispatcher with reserved concurrency one commits bounded claims before offering messages to the queue. - >- A queue consumer with a two-invocation cap calls registered handlers and records outcomes; five consecutive failures pause enabled future scheduling. - >- A lifecycle function with reserved concurrency one answers bounded steps requested by Platform. - >- An availability gate consults cached workspace standing before Accounting requests, with a thirty-second cache lifetime. integrations: - system: Platform scheduler rule and queue infrastructure direction: inbound contract: >- A minute rule invokes dispatch; the queue has a dead-letter queue and age alarms, and dispatch has a silence alarm. - system: Platform lifecycle jobs direction: inbound contract: >- Platform invokes participant description, provisioning, completion verification, bounded purge, inventory and export; reset is unsupported. - system: Platform staging storage direction: outbound contract: >- Parts contain compressed JSON Lines under the request prefix. A configured bucket must match, an empty setting blocks export, and an undefined injected setting does not restrict the bucket. - system: Platform workspace record direction: outbound contract: >- The service reads lifecycle standing, status and time zone without owning the workspace record. - system: Batch posting jobs direction: outbound contract: >- Roll and automatic-close work can prepare posting in the same transaction and start it afterward. Refusal can retain an unposted closed batch; a failed start can leave a submitted job. consistency: - rule: >- Occurrence uniqueness creates at most one history row; a queued or running handler may be started repeatedly. kind: transactional compensation: >- No scheduler undo exists; occurrence uniqueness does not make handlers idempotent. - rule: >- Expected refusals finish immediately. Unexpected faults request redelivery until the final receive records failure and acknowledges; malformed messages or failure-recording errors can reach the dead-letter queue. kind: eventual compensation: >- Terminal failed occurrences are not restarted automatically; owners retain responsibility for partial business effects. - rule: >- Repeated provisioning preserves existing rows and does not duplicate the provisioned methods. kind: transactional compensation: Conflict-safe insertion requires no undo. - rule: >- A purge call commits one table batch in a deleting workspace or rolls that batch back. kind: transactional compensation: >- Earlier committed batches stay erased; continuation removes remaining rows. - rule: >- A staged export part requires every record to pass the recognized-secret check; database reads and storage do not share a transaction. kind: eventual compensation: >- A failed part is abandoned and retry targets the same location, without freezing record values. - rule: >- Availability uses a thirty-second cache, whereas each purge batch rechecks workspace standing directly. kind: eventual compensation: No restoration or compensation follows an observed state change. evidence: - >- services-accounting at f47cb263: modules/maintenance/aws/api/scheduling.routes.ts (operations), aws/scheduling.module.ts, aws/logic/*.ts, aws/lambda/*.ts - >- services-accounting at f47cb263: modules/maintenance/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS (the six lifecycle operations), tenant-availability.ts - >- services-accounting at f47cb263: modules/maintenance/services/participants/*, services/exports/*, services/persistence/*, services/scheduled-work/accounting-scheduled-work.ts - >- services-accounting:package-lock.json (locked macroservice-http healthRoute and macroservice-schedules dispatcher, consumer, repository and schedule-run-message) controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-007, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-006, TC-AVL-001, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005] --- # Accounting scheduling and lifecycle service ## What This Service Is For Maintenance times recurring Accounting work and supplies bounded provisioning, export and erasure steps to Platform. It also gates Accounting requests against observed workspace availability. ## Boundary Owning modules save their schedule definitions and implement business handlers. Maintenance supplies recurrence, dispatch and history. Platform owns lifecycle transitions and continuation; participant declarations and dataset readers also live beside other Accounting modules. ## Operations in Words Staff can preview recurrence without saving and read history only with the owning record’s read permission. Internal lifecycle calls describe participants, provision and verify setup, count remaining rows, purge one batch or export one dataset batch. None is a Submissions intake operation. ## Events and Jobs The dispatcher commits before publishing. Explicit publication refusal releases the offered run, but a crash in that gap can strand it. The consumer can repeat unfinished handler work, including concurrent duplicate deliveries. Expected business refusals settle without retry; unexpected errors redeliver, with successful final failure recording acknowledged rather than sent to the dead-letter queue. ## Consistency Guarantees Provisioning uses conflict-safe insertion. Purge is bounded, guarded and irreversible after commit. Export checks recognized secret shapes, not every possible secret, and its creation cutoff does not provide a value snapshot. Cache delays affect ordinary availability; purge reads standing afresh. Posting prepared by a scheduled close has a separate post-commit start boundary.