---
id: STATE-PFM-QRY-003
title: Query generation
object: DOM-PFM-QRY-002
product_area: platform
module: queries
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: working
    meaning: >-
      The admitted request awaits its worker or is being drafted, and the console can poll for
      settlement.
  - name: succeeded
    meaning: >-
      The outcome is a validated query, a clarification request or an explanation that the language
      cannot express the request.
  - name: failed
    meaning: The attempt settled with a declared failure code rather than provider-error text.
  - name: removed
    meaning: Retention cleanup deleted the generation record after thirty days.
transitions:
  - from: working
    to: succeeded
    trigger: The worker returns an accepted final outcome.
    guard: The stored generation is still working.
    side_effects:
      - >-
        the validated query or clarification or unsupported outcome is retained with metadata and
        the invocation reference
    who: system (generation worker)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/run-generation.ts'
  - from: working
    to: failed
    trigger: The worker encounters a terminal generation failure.
    guard: The stored generation is still working.
    side_effects:
      - a declared code is retained; diagnostic details remain in logging
    who: system (generation worker)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/generation-problem-codes.ts'
  - from: working
    to: failed
    trigger: The asynchronous worker invocation fails during admission.
    guard: The generation has not settled.
    side_effects:
      - the admitted row is failed without waiting for abandonment cleanup
    who: system (generate route)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/start-generation.ts'
  - from: working
    to: failed
    trigger: Reconciliation finds the worker deadline and margin exceeded.
    guard: The generation has not settled.
    side_effects:
      - the stored failure code is GenerationAbandoned
    who: system (generation reconciler)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/reconcile-generations.ts'
  - from: succeeded
    to: removed
    trigger: Retention cleanup finds a success older than thirty days.
    guard: The retention cutoff has passed.
    side_effects:
      - the request and outcome row are removed
    who: system (generation reconciler)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/reconcile-generations.ts'
  - from: failed
    to: removed
    trigger: Retention cleanup finds a failed generation older than thirty days.
    guard: The retention cutoff has passed.
    side_effects:
      - the generation row is removed
    who: system (generation reconciler)
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/reconcile-generations.ts'
invalid:
  - from: succeeded
    to: failed
    why: >-
      A terminal outcome is not replaced by another settlement; a late reconciler update loses its
      working-status condition.
  - from: failed
    to: working
    why: The same generation does not restart. A new request or refinement creates another record.
concurrency: >-
  Worker and reconciler settlement use the same working-status condition, leaving one stored
  outcome. A predecessor must settle before refinement. Admission allowance is advisory; concurrent
  admissions can still lose at the foundation reservation gate.
invariants:
  - INV-DOM-PFM-QRY-002-11
  - INV-DOM-PFM-QRY-002-12
evidence:
  - >-
    services-platform at ad3f6a6: modules/queries/db/query-generations.table.ts;
    services/generate/start-generation.ts, run-generation.ts, reconcile-generations.ts,
    generation-problem-codes.ts; docs/llm/llm-foundation-and-generate-query.md (accepted 2026-10-12)
---

# Query generation

## The Lifecycle

```mermaid
stateDiagram-v2
  state "working" as s0
  state "succeeded" as s1
  state "failed" as s2
  state "removed" as s3
  s0 --> s1
  s0 --> s2
  s0 --> s2
  s0 --> s2
  s1 --> s3
  s2 --> s3
```

Generation has one working status and two persisted terminal outcomes. Retention removal is a later deletion rather than another inference attempt.

## Transitions Explained

A successful conversation may ask for clarification or report an unsupported request. Query outcomes are validated and compiled before storage; model-written explanation remains outcome content.

## What Cannot Happen

Conditional settlement prevents a completed worker and abandonment sweep from overwriting each other.

## Concurrency and Timing

The five-minute reconciler identifies abandoned workers and removes old records. Allowance and in-flight restrictions remain foundation gates, not guarantees of admission success.