--- id: WF-PFM-QRY-006 title: Produce a query's complete result as a file trigger: A person or schedule requests a CSV or Excel file for an executable query with its runtime values. product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f inference: [] implements: - CAP-PFM-QRY-014 moves: - STATE-PFM-QRY-006 crosses: - SVC-PFM-QRY-queries idempotency: >- Admission ties the queue identity to the export and fixes its storage key. Redelivery reuses unfinished work; a successful publish followed by a failed queue-row delete can produce another delivery. concurrency: >- Interactive query exports use their own queue and configured worker concurrency, separate from scheduled delivery. Each generator processes one query page at a time. hops: - 'n': 1 actor_or_service: Start export route (queries API) action: >- Open any saved source as the caller, substitute runtime values and compile the resulting query with current dataset access. anchor: 'services-platform:modules/queries/services/exports/query-export-library.ts' seam: sync on_failure: >- Refuse inaccessible sources, invalid values or unavailable fields before creating the file request. left_inconsistent: Admission has not written export work at this point. observer: the person provenance: observed source: 'services-platform:modules/queries/services/exports/query-export-library.ts' - 'n': 2 actor_or_service: Start export route action: 'Commit the queued file and queued-work row together, then nudge dispatch.' anchor: 'services-platform:modules/queries/db/query-export-requests.table.ts' seam: queue on_failure: A failed nudge leaves the periodic dispatcher to find the row. left_inconsistent: The durable request remains queued until dispatch succeeds. observer: the person following the export provenance: observed source: 'services-platform:modules/queries/services/exports/query-export-library.ts' - 'n': 3 actor_or_service: Export dispatcher action: >- Claim cross-workspace queue rows, publish each to the query-generator or report-renderer queue and remove accepted rows. anchor: 'services-platform:modules/queries/services/exports/dispatch-query-exports.ts' seam: schedule on_failure: Rejected publication retains the request for a later claim. left_inconsistent: 'The file can wait longer, or receive duplicate delivery after a publish/delete interruption.' observer: the dispatcher's silence and error alarms provenance: observed source: 'services-platform:modules/queries/services/exports/dispatch-query-exports.ts' - 'n': 4 actor_or_service: Export worker action: >- Start unfinished work as the requester, read thousand-row keyset pages and stream CSV or Excel into multipart storage while recording progress. anchor: 'services-platform:modules/queries/services/exports/run-query-export.ts:runQueryExport' seam: queue on_failure: >- Permanent request failures settle promptly; infrastructure errors redeliver until the final receive, with handled multipart uploads aborted. left_inconsistent: >- A claim or running row can remain until retry or reconciliation; no exclusive worker lease is established here. observer: the person following the export; the dead-letter queue alarm provenance: observed source: 'services-platform:modules/queries/services/exports/run-query-export.ts' - 'n': 5 actor_or_service: Export worker action: 'Record successful file size, rows and completion-based expiry.' anchor: 'services-platform:modules/queries/services/persistence/query-exports.ts' seam: sync on_failure: A completion write failure can cause rebuilding on redelivery. left_inconsistent: The stored object can exist while its row still says running. observer: the person following the export provenance: observed source: 'services-platform:modules/queries/services/exports/run-query-export.ts' - 'n': 6 actor_or_service: Download route action: >- Authorize the requester or eligible schedule authority and issue a five-minute signed object link for a ready, unexpired file. anchor: 'services-platform:modules/queries/aws/api/query-exports.routes.ts:downloadQueryExport' seam: sync on_failure: >- Other readers receive not found; unfinished and expired files receive their corresponding refusal. left_inconsistent: The storage object is not changed by download refusal. observer: the person provenance: observed source: 'services-platform:modules/queries/services/exports/query-export-library.ts' branches: - >- Public delivery links verify their seven-day token and continued schedule-recipient membership, record a download and use the common invalid-link response for refusal. waits: - The console polls the file record until production settles. evidence: - >- services-platform at ad3f6a6: modules/queries/services/exports/*.ts; aws/logic/queries-exports.lambda.ts; aws/resources/query-exports.sqs.ts; db/query-exports.table.ts, query-export-requests.table.ts; docs/queued-work.md; docs/migrations/query-scheduling-exports/README.md (D1, D9–D12) - 'react-console at baf6dae: components/queries/export-dialog.tsx' controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, 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-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Produce a query's complete result as a file ## What It Does A person or schedule requests a CSV or Excel file for an executable query with its runtime values. Public delivery links verify their seven-day token and continued schedule-recipient membership, record a download and use the common invalid-link response for refusal. ## The Flow ```mermaid sequenceDiagram participant C as Request or schedule participant H0 as Start export route queries API participant H1 as Start export route participant H2 as Export dispatcher participant H3 as Export worker participant H4 as Export worker participant H5 as Download route C->>H0: Open any saved source as the caller, substitute runtime values and compile the resulting query with H0-)H1: Commit the queued file and queued-work row together, then nudge dispatch H1-)H2: Claim cross-workspace queue rows, publish each to the query-generator or report-renderer queue and r H2-)H3: Start unfinished work as the requester, read thousand-row keyset pages and stream CSV or Excel into H3->>H4: Record successful file size, rows and completion-based expiry H4->>H5: Authorize the requester or eligible schedule authority and issue a five-minute signed object link fo ``` Open any saved source as the caller, substitute runtime values and compile the resulting query with current dataset access. Commit the queued file and queued-work row together, then nudge dispatch. Claim cross-workspace queue rows, publish each to the query-generator or report-renderer queue and remove accepted rows. Start unfinished work as the requester, read thousand-row keyset pages and stream CSV or Excel into multipart storage while recording progress. Record successful file size, rows and completion-based expiry. Authorize the requester or eligible schedule authority and issue a five-minute signed object link for a ready, unexpired file. ## When Something Fails Refuse inaccessible sources, invalid values or unavailable fields before creating the file request. Admission has not written export work at this point. A failed nudge leaves the periodic dispatcher to find the row. The durable request remains queued until dispatch succeeds. Rejected publication retains the request for a later claim. The file can wait longer, or receive duplicate delivery after a publish/delete interruption. Permanent request failures settle promptly; infrastructure errors redeliver until the final receive, with handled multipart uploads aborted. A claim or running row can remain until retry or reconciliation; no exclusive worker lease is established here. A completion write failure can cause rebuilding on redelivery. The stored object can exist while its row still says running. Other readers receive not found; unfinished and expired files receive their corresponding refusal. The storage object is not changed by download refusal. ## Idempotency and Concurrency Admission ties the queue identity to the export and fixes its storage key. Redelivery reuses unfinished work; a successful publish followed by a failed queue-row delete can produce another delivery. Interactive query exports use their own queue and configured worker concurrency, separate from scheduled delivery. Each generator processes one query page at a time.