---
id: STATE-PFM-QRY-006
title: Query export file
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: queued
    meaning: 'The file request and queue entry are committed, awaiting dispatch or worker start.'
  - name: running
    meaning: The generator or renderer is producing the requested file using the requester context.
  - name: succeeded
    meaning: 'The completed object is downloadable until the recorded expiry, subject to access checks.'
  - name: failed
    meaning: >-
      The file request has a coded terminal failure. Handled query-upload failures abort the
      multipart upload, but the status does not certify removal of every stored object.
  - name: expired
    meaning: >-
      The completion-based expiry has passed; this is a read-time condition rather than a persisted
      status.
transitions:
  - from: queued
    to: running
    trigger: A worker receives the queued export.
    guard: The row is queued or running rather than terminal.
    side_effects:
      - execution obtains the requester context and begins file production
    who: system (export worker or report renderer)
    provenance: observed
    source: 'services-platform:modules/queries/services/exports/run-query-export.ts'
  - from: running
    to: running
    trigger: The queue delivers unfinished work again.
    guard: The export remains running.
    side_effects:
      - production restarts with the original storage key
    who: system
    provenance: observed
    source: 'services-platform:modules/queries/db/query-exports.table.ts'
  - from: running
    to: succeeded
    trigger: The generator finishes and stores the object.
    guard: The export still accepts completion.
    side_effects:
      - 'final size, rows and completion-based expiry are recorded; waiting delivery can proceed'
    who: system
    provenance: observed
    source: 'services-platform:modules/queries/services/exports/run-query-export.ts'
  - from: running
    to: failed
    trigger: A permanent refusal occurs or infrastructure retries are exhausted.
    guard: The export accepts failure settlement.
    side_effects:
      - handled query multipart work is aborted; the failure code and readable detail are saved
    who: system
    provenance: observed
    source: 'services-platform:modules/queries/services/rendering/render-report.ts'
  - from: queued
    to: failed
    trigger: Pre-render checks find lost access or a missing report.
    guard: The request has not settled.
    side_effects:
      - the failure is recorded as access_lost
    who: system (report renderer)
    provenance: observed
    source: 'services-platform:modules/queries/services/rendering/render-report.ts'
  - from: succeeded
    to: expired
    trigger: The recorded completion-based expiry passes.
    guard: The current time is beyond the expiry.
    side_effects:
      - >-
        authenticated download refuses the expired file; public delivery shows its invalid-link
        response
    who: the Rhythm 1.0 bucket's lifecycle rule
    provenance: observed
    source: >-
      services-platform:modules/queries/services/persistence/query-exports.ts:completeQueryExport;
      modules/queries/services/exports/query-export-library.ts
invalid:
  - from: succeeded
    to: running
    why: A settled successful record is acknowledged on redelivery rather than restarted.
  - from: failed
    to: queued
    why: A failed request stays terminal; another user request creates another file record.
concurrency: >-
  Redelivery accepts an unfinished queued or running record and uses its original storage key.
  Settled records are left unchanged. Reusing a key does not establish an exclusive worker lease or
  exactly-once physical execution.
invariants:
  - INV-DOM-PFM-QRY-004-01
  - INV-DOM-PFM-QRY-004-02
  - INV-DOM-PFM-QRY-004-03
evidence:
  - >-
    services-platform at ad3f6a6: modules/queries/db/query-exports.table.ts;
    services/exports/run-query-export.ts; services/rendering/render-report.ts;
    docs/migrations/query-scheduling-exports/README.md (D9–D12, verified 2026-10-17)
---

# Query export file

## The Lifecycle

```mermaid
stateDiagram-v2
  state "queued" as s0
  state "running" as s1
  state "succeeded" as s2
  state "failed" as s3
  state "expired" as s4
  s0 --> s1
  s1 --> s1
  s1 --> s2
  s1 --> s3
  s0 --> s3
  s2 --> s4
```

File status describes production, while expiry describes whether a completed result remains available for download.

## Transitions Explained

Workers can restart unfinished work into the original object key. Completion records file metadata and the expiry; failures record a bounded explanation.

## What Cannot Happen

Conditional status writes refuse reopening a settled result. Physical retention belongs to the storage lifecycle as well as application download checks.

## Concurrency and Timing

The queue is at least once. The design records redelivery behavior without claiming that two deliveries cannot overlap while a record remains running.