---
id: STATE-PFM-QRY-012
title: Export coverage declaration
object: DOM-PFM-QRY-004
product_area: platform
module: queries
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: active
    meaning: >-
      The registry records an active dataset declaration for future export coverage; package
      generation remains undeployed.
  - name: deferred
    meaning: The declaration records a reason that package coverage is deferred.
  - name: retired
    meaning: >-
      The owning service explicitly omitted the dataset from its declared set, retaining retirement
      history.
transitions:
  - from: active
    to: active
    trigger: Activation supplies a new schema release for the dataset.
    guard: Its schema version is not already registered with conflicting content.
    side_effects:
      - 'the declaration is replaced, its version retained and the registry version advanced'
    who: system (manifest activation)
    provenance: observed
    source: >-
      services-platform:modules/data-exports/services/export-coverage/reconcile-coverage.ts:planCoverage
  - from: active
    to: retired
    trigger: An explicit dataset declaration list omits an existing dataset.
    guard: >-
      The owning service supplied a datasets property, including an empty list; an absent property
      does not retire declarations.
    side_effects:
      - retirement time is retained and the registry version advances
    who: system (manifest activation)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/export-coverage/reconcile-coverage.ts'
  - from: retired
    to: active
    trigger: Activation declares a retired dataset again.
    guard: The declaration passes owner and version checks.
    side_effects:
      - the declaration is reactivated and the registry version advances
    who: system (manifest activation)
    provenance: observed
    source: 'services-platform:modules/data-exports/services/export-coverage/reconcile-coverage.ts'
invalid:
  - from: active
    to: active
    why: >-
      Existing schema versions cannot silently identify changed declaration content; conflicting
      declarations remain unapplied.
concurrency: >-
  Manifest activation applies the coverage plan transactionally while logging conflicts without
  failing activation. Duplicate declaring owners and changed content under a recorded schema version
  are rejected for the affected declaration.
invariants:
  - INV-DOM-PFM-QRY-004-13
evidence:
  - >-
    services-platform at ad3f6a6: modules/data-exports/services/export-coverage/*.ts;
    db/export-coverage-datasets.table.ts; export-coverage/contract.ts; docs/data-exports.md (repair
    notes of 2026-10-18)
---

# Export coverage declaration

## The Lifecycle

```mermaid
stateDiagram-v2
  state "active" as s0
  state "deferred" as s1
  state "retired" as s2
  s0 --> s0
  s0 --> s2
  s2 --> s0
```

Coverage is a release registry, separate from query-dataset registration and from any completed package.

## Transitions Explained

A changed schema version can replace a declaration; explicit omission retires it and a later declaration can restore it. Deferred declarations record unsupported coverage.

## What Cannot Happen

A service with no datasets property is distinct from an explicit empty list, which requests retirement of its declarations.

## Concurrency and Timing

Coverage conflicts are logged and do not fail the service activation.