--- id: DOM-PFM-QRY-004 title: Export realises: CON-PFM-QRY-004 product_area: platform module: queries revision: 1 status: draft design_intent: proposed implementation_evidence: partially-observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-QRY-queries readable_by: [] lifecycle: - STATE-PFM-QRY-006 - STATE-PFM-QRY-007 - STATE-PFM-QRY-008 - STATE-PFM-QRY-009 - STATE-PFM-QRY-010 - STATE-PFM-QRY-011 - STATE-PFM-QRY-012 custom_fields: none identity: >- Files, schedules, runs, deliveries and workspace export executions have workspace-scoped identities. A schedule occurrence is unique by schedule and occurrence time, and a recipient delivery by run and recipient. Each workspace has one export-settings record; coverage uses product-wide dataset names and schema versions. attributes: - name: export file · kind and source kind: enum required: true computed: false notes: >- Query files retain the dataset and substituted request. Report files retain the report reference and print parameters. - name: export file · format and options kind: enum required: true computed: false notes: >- Query exports use CSV or Excel with chosen heading behavior; descriptions require Excel. Reports use PDF, with Excel supported for coded and table kinds. - name: export file · requester kind: reference required: true computed: false notes: The requesting person supplies the current access used to produce the file. - name: export file · status and outcome kind: enum required: true computed: false notes: >- Persisted status is queued, running, succeeded or failed. Progress, final size and row count, or a coded failure describe the outcome; expiry is computed on read. - name: export file · storage and expiry kind: date required: true computed: true notes: >- The object key is fixed at request time. Successful completion records an expiry thirty days later, while bucket lifecycle separately controls physical retention. - name: schedule · source kind: reference required: true computed: false notes: >- Query schedules retain a definition snapshot and source version. Report schedules retain a report reference and version for change detection. - name: schedule · timetable kind: collection required: true computed: false notes: >- The recurrence is at least hourly and includes its time zone, occurrence tracking, failure streak and automatic-pause reason. - name: schedule · owner kind: reference required: true computed: false notes: >- Automatic execution reconstructs the schedule owner’s access. Taking ownership requires schedule-management authority. - name: schedule · recipients and message kind: collection required: true computed: false notes: >- Deliveries target up to fifty distinct workspace people or addresses with a published template and message. Query delivery skips empty results by default. - name: schedule · imported legacy kind: enum required: false computed: false notes: >- Converted legacy schedules start paused and require confirmation that the old delivery is disabled before resuming. - name: run and deliveries kind: collection required: false computed: true notes: >- Runs keep attempts, status and file outcome. Recipient rows keep communication submissions, skip reasons and link download counts. - name: workspace export · definition kind: collection required: false computed: false notes: >- Workspace settings retain package choices, one-to-thirty-day retention, up to twenty additional notification people and active, paused or suspended status. - name: workspace export · destinations kind: collection required: false computed: false notes: >- At most five unique storage connections are configured with relative destination paths, enablement and a file-delivery binding. - name: workspace export · execution kind: collection required: false computed: false notes: >- Admission captures trigger, cutoff, settings and allowance use. Execution rows retain status, phase, counts and failure details. - name: workspace export · package kind: collection required: false computed: true notes: >- Package, volume, staging, manifest, delivery-attempt and notice records exist in the foundation schema but are not produced by a deployed runner. - name: workspace export · coverage kind: collection required: false computed: true notes: >- Coverage declarations retain active, deferred or retired status, schema version and content hash; a registry version tracks reconciliation. relationships: - to: DOM-PFM-QRY-002 cardinality: many-to-one ownership: >- Query schedules keep a restricting saved-query reference and their own definition snapshot; query files retain their source only as origin metadata. cross_service: false - to: DOM-PFM-QRY-003 cardinality: many-to-one ownership: >- Report schedules and files refer to the presentation, with file references cleared on report removal. cross_service: false - to: DOM-PFM-QRY-001 cardinality: many-to-one ownership: The query file records the dataset used for its executed request. cross_service: false invariants: - id: INV-DOM-PFM-QRY-004-01 statement: File admission commits the export row and its queued-work request together. enforced_at: - service provenance: observed source: 'services-platform:modules/queries/db/query-export-requests.table.ts' - id: INV-DOM-PFM-QRY-004-02 statement: >- Conditional persistence updates govern queued, running and terminal file statuses, and failed rows retain a failure code. enforced_at: - service provenance: observed source: >- services-platform:modules/queries/services/persistence/query-exports.ts:startQueryExportRun, completeQueryExport, failQueryExport - id: INV-DOM-PFM-QRY-004-03 statement: >- Query and report files enforce their distinct source shapes and permitted formats; description rows are an Excel option. enforced_at: - database provenance: observed source: >- services-platform:modules/queries/db/query-exports.table.ts (per-kind CHECK, query_exports_include_descriptions_check) - id: INV-DOM-PFM-QRY-004-04 statement: >- File reads and downloads check the requester or eligible schedule authority; delivery links additionally require continued recipient membership. enforced_at: - service provenance: observed source: >- services-platform:modules/queries/services/exports/query-export-library.ts; modules/queries/services/schedules/schedule-export-hooks.ts - id: INV-DOM-PFM-QRY-004-05 statement: >- Schedule occurrence uniqueness prevents duplicate admission, and recipient identity constrains each run’s communication-request record. enforced_at: - database - service provenance: observed source: >- services-platform:modules/queries/db/schedule-runs.table.ts (schedule_runs_occurrence_uidx); modules/queries/db/query-schedule-deliveries.table.ts - id: INV-DOM-PFM-QRY-004-06 statement: >- Schedules allow at most fifty recipients and require the external-recipient grant for outside addresses. enforced_at: - service provenance: observed source: 'services-platform:modules/queries/services/schedules/query-schedule-library.ts' - id: INV-DOM-PFM-QRY-004-07 statement: >- A query schedule keeps its saved definition until an explicit refresh; message edits do not repin the query. enforced_at: - service provenance: documented source: 'services-platform:docs/migrations/query-scheduling-exports/README.md#D3' - id: INV-DOM-PFM-QRY-004-08 statement: >- Run processing records execution and delivery results rather than editing the schedule definition, apart from implemented automatic-pause changes. enforced_at: - service provenance: observed source: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' - id: INV-DOM-PFM-QRY-004-09 statement: >- The database permits one settings definition and at most one queued or running workspace export execution per workspace. enforced_at: - database - service provenance: observed source: >- services-platform:modules/data-exports/db/data-export-definitions.table.ts (data_export_definitions_tenant_uq); modules/data-exports/db/data-export-executions.table.ts (data_export_executions_one_active_uidx) - id: INV-DOM-PFM-QRY-004-10 statement: Export settings and execution admission require a live workspace outside sandbox mode. enforced_at: - service provenance: observed source: >- services-platform:modules/data-exports/services/persistence/definitions.ts:requireExportEligibleTenant - id: INV-DOM-PFM-QRY-004-11 statement: >- Admission and destination changes audit within their transaction. Early package deletion has an audited persistence helper, but its customer action is unavailable. enforced_at: - service provenance: observed source: >- services-platform:modules/data-exports/services/persistence/executions.ts; modules/data-exports/services/persistence/destinations.ts; modules/data-exports/services/persistence/artifacts.ts - id: INV-DOM-PFM-QRY-004-12 statement: >- Workspace execution, delivery and package persistence helpers lock their rows and check the allowed starting statuses. enforced_at: - service provenance: observed source: >- services-platform:modules/data-exports/services/persistence/executions.ts; modules/data-exports/services/persistence/deliveries.ts - id: INV-DOM-PFM-QRY-004-13 statement: >- Coverage reconciliation rejects changed content under an existing schema version and advances the registry version when declarations change. enforced_at: - service provenance: observed source: >- services-platform:modules/data-exports/services/export-coverage/reconcile-coverage.ts:planCoverage - id: INV-DOM-PFM-QRY-004-14 statement: >- Package volume keys are confined to their package prefix rather than permitting arbitrary storage objects. enforced_at: - service provenance: observed source: 'services-platform:modules/data-exports/services/persistence/volumes.ts' physical: - platform.query_exports - platform.query_export_requests - platform.query_schedules - platform.query_schedule_recipients - platform.query_schedule_deliveries - platform.schedules - platform.schedule_runs - platform.data_export_definitions - platform.data_export_destinations - platform.data_export_executions - platform.data_export_artifacts - platform.data_export_volumes - platform.data_export_parts - platform.data_export_deliveries - platform.data_export_delivery_attempts - platform.data_export_notices - platform.data_export_jobs - platform.data_export_job_steps - platform.data_export_job_events - platform.export_coverage_datasets - platform.export_coverage_versions - the Rhythm 1.0 export bucket (query and report files) and the data exports bucket (packages) evidence: - >- services-platform at ad3f6a6: modules/queries/db/query-export*.table.ts, query-schedule*.table.ts, schedules.table.ts, schedule-runs.table.ts; services/exports/*.ts; services/schedules/*.ts; services/rendering/*.ts - >- services-platform at ad3f6a6: modules/data-exports/db/*.table.ts; services/**/*.ts; aws/api/*.routes.ts; docs/data-exports.md; docs/migrations/query-scheduling-exports/README.md (D1–D13, verified 2026-10-17); docs/proposals/tenant-data-export/20-risks-tradeoffs-decisions.md (decided 2026-10-18) --- # Export ## What It Models The export concept joins two delivery designs: query and report files, including recurring delivery, and complete workspace packages. Their different service owners remain explicit. ## Identity and Attributes File requests have requester-scoped outcomes. Schedules keep recurrence and recipients separately from occurrence runs. Workspace admission copies settings into an execution that is independent of later settings edits. ## Relationships Source references support provenance and deletion rules without making exported content the owner of application records. ## Invariants The invariant rows distinguish deployed file processing from workspace-package persistence helpers. Stored schemas alone do not establish generation, cleanup or delivery orchestration. ## How It Is Stored and Shared The query service owns files and schedules. The data export service owns workspace definitions, coverage and package foundations. External storage and Communications implement separate integration boundaries. ## Open Design Questions The queued workspace export blockage, temporary binding store and proposed concept split remain open. No completed package flow is established at these source revisions.