---
id: STATE-PFM-QRY-011
title: Workspace export delivery
object: DOM-PFM-QRY-004
product_area: platform
module: queries
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: not-implemented
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: pending
    meaning: A delivery row awaits processing for its destination or hosted download.
  - name: delivering
    meaning: The helper marked destination transfer in progress; no deployed consumer performs it yet.
  - name: delivered
    meaning: 'The row records accepted delivery, independently of any appended attempt record.'
  - name: failed
    meaning: 'The row retains the failure class, code and bounded operator summary.'
  - name: withheld
    meaning: 'The delivery is withheld rather than attempted, such as for a disabled destination.'
  - name: expired
    meaning: The row records that its package is no longer eligible for unfinished delivery.
  - name: superseded
    meaning: The failed delivery was marked replaced; creating its replacement is a separate operation.
transitions:
  - from: pending
    to: delivering
    trigger: Future processing calls the transfer-start helper.
    guard: The locked row is pending.
    side_effects:
      - delivery status changes; attempt insertion is a separate call
    who: 'system (delivery consumer, not yet built)'
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: failed
    to: delivering
    trigger: Future retry processing calls the transfer-start helper.
    guard: The locked row is failed.
    side_effects:
      - delivery status changes; another attempt requires a separate insertion
    who: 'system (delivery consumer, not yet built)'
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: delivering
    to: delivered
    trigger: The accepted-outcome helper is called.
    guard: The locked row is delivering.
    side_effects:
      - delivered status and supplied metadata are recorded separately from attempt history
    who: system
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts:markDelivered'
  - from: delivering
    to: failed
    trigger: The failure helper is called.
    guard: The locked row is delivering.
    side_effects:
      - 'failure class, code and summary are stored; attempt history is separate'
    who: system
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: pending
    to: withheld
    trigger: Processing marks an unavailable destination withheld.
    guard: The locked row is pending.
    side_effects: []
    who: system
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: pending
    to: expired
    trigger: Package cleanup calls expiry for pending delivery.
    guard: The locked row is pending.
    side_effects: []
    who: system (sweep)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: failed
    to: expired
    trigger: Package cleanup calls expiry for failed delivery.
    guard: The locked row is failed.
    side_effects: []
    who: system (sweep)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: withheld
    to: expired
    trigger: Package cleanup calls expiry for withheld delivery.
    guard: The locked row is withheld.
    side_effects: []
    who: system (sweep)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
  - from: failed
    to: superseded
    trigger: The supersession helper is called.
    guard: The locked row is failed; the customer retry route is unimplemented.
    side_effects:
      - the old row is marked superseded; replacement creation is separate
    who: administrator with execute permission (future)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/persistence/deliveries.ts'
invalid:
  - from: delivered
    to: delivering
    why: The same settled delivered row cannot begin transfer again.
  - from: superseded
    to: delivering
    why: A superseded row remains historical; any replacement needs its own row.
concurrency: >-
  Delivery status changes lock the row. Attempt numbers are allocated under the delivery lock and
  attempt rows are append-only for the application role. Status helpers and attempt insertion remain
  separate calls.
evidence:
  - >-
    services-platform at ad3f6a6: modules/data-exports/db/data-export-deliveries.table.ts,
    data-export-delivery-attempts.table.ts; services/persistence/deliveries.ts,
    delivery-attempts.ts; services/destinations/bindings.ts
---

# Workspace export delivery

## The Lifecycle

```mermaid
stateDiagram-v2
  state "pending" as s0
  state "delivering" as s1
  state "delivered" as s2
  state "failed" as s3
  state "withheld" as s4
  state "expired" as s5
  state "superseded" as s6
  s0 --> s1
  s3 --> s1
  s1 --> s2
  s1 --> s3
  s0 --> s4
  s0 --> s5
  s3 --> s5
  s4 --> s5
  s3 --> s6
```

Delivery statuses describe the workspace export foundation. They are not evidence of a deployed destination consumer or retry route.

## Transitions Explained

The helpers check starting status and record outcomes; attempts are appended separately. Supersession marks the old row without creating a replacement.

## What Cannot Happen

A delivered or superseded record cannot reenter transfer through these helpers.

## Concurrency and Timing

Row locks protect status and attempt numbering, while actual transfer, storage effects and retry orchestration remain unfinished.