---
id: STATE-PFM-QRY-004
title: Query recipe declaration
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: active
    meaning: 'The registered recipe is available for discovery, drafting and permitted execution.'
  - name: retired
    meaning: >-
      The application omitted the recipe from its release, while independent saved questions retain
      their origin reference.
transitions:
  - from: active
    to: active
    trigger: Registration supplies changed recipe content.
    guard: The release validates and uses a changed recipe version.
    side_effects:
      - template and parameter metadata are replaced; existing derived questions remain independent
    who: the owning application's deploy
    provenance: observed
    source: >-
      services-platform:modules/queries/services/recipe-registration/register-query-recipes.ts:registerQueryRecipes
  - from: active
    to: retired
    trigger: The new release omits the recipe.
    guard: The whole manifest validates.
    side_effects:
      - the recipe is retired; dependent list reads can report recipe_missing
    who: the owning application's deploy
    provenance: observed
    source: 'services-platform:modules/queries/db/query-recipes.table.ts (retired_at)'
  - from: retired
    to: active
    trigger: A later release includes the retired recipe.
    guard: The whole manifest validates.
    side_effects:
      - the existing recipe row is reactivated
    who: the owning application's deploy
    provenance: observed
    source: 'services-platform:modules/queries/db/query-recipes.table.ts'
invalid:
  - from: active
    to: active
    why: A changed declaration with the existing recipe version fails release validation.
concurrency: >-
  The whole release is validated before persistence, and identical declarations need no replacement.
  Workspace custom-object recipes instead follow the source object’s activation.
evidence:
  - >-
    services-platform at ad3f6a6:
    modules/queries/services/recipe-registration/register-query-recipes.ts;
    db/query-recipes.table.ts; services/recipes/recipe-liveness.ts;
    docs/queries/saved-queries-and-recipes.md#3.3
---

# Query recipe declaration

## The Lifecycle

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

A recipe is an application-owned query template, released under a stable identity and version.

## Transitions Explained

Registration can replace content under a changed version, retire an omitted recipe or reactivate it later. Independent drafted questions remain unchanged.

## What Cannot Happen

Version validation prevents silently changing the content identified by an existing recipe release.

## Concurrency and Timing

Custom-object recipes are generated from workspace object configuration rather than from an application release alone.