---
id: STATE-PFM-LLM-004
title: Operation and price version lifecycle
object: DOM-PFM-LLM-002
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: declared
    meaning: Code contains configuration not yet represented by the current published digest.
  - name: current
    meaning: The highest published version number for this key; warm readers can still use an older cache.
  - name: superseded
    meaning: A higher version number exists while earlier requests retain this version.
transitions:
  - from: declared
    to: current
    trigger: Deployment publishes a changed or first declaration.
    guard: Catalogue validation passes; rates are appended before routing.
    side_effects:
      - Append the next number and digest and update the publishing process’s cache.
    who: Deploy-time migration function
    provenance: observed
    source: 'services-platform:modules/llm/services/catalog/materialize-catalog.ts:materializeLlmCatalog'
  - from: current
    to: superseded
    trigger: A later deployment appends changed or reverted content.
    guard: The publication validates and its append commits.
    side_effects:
      - Preserve the earlier immutable row and existing request references.
    who: Deploy-time migration function
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/routing-versions.ts:appendRoutingVersion'
  - from: current
    to: current
    trigger: Deployment presents the existing current digest.
    guard: The digest matches the latest version read.
    side_effects:
      - Return the published row without appending another version.
    who: Deploy-time migration function
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/rate-versions.ts:appendRateVersion'
invalid:
  - from: superseded
    to: current
    why: Reverting content appends a new numbered row rather than activating an old one.
  - from: current
    to: declared
    why: Published history cannot be turned back into editable configuration through ordinary update or deletion.
  - from: declared
    to: superseded
    why: Validation failure writes nothing; later persistence failure can still leave partial publication.
concurrency: >-
  Concurrent appenders contend for a unique version number. A matching winning digest is accepted; differing
  content fails publication. Warm readers cache successful lookups without checking whether the referenced row
  still exists.
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/services/catalog/materialize-catalog.ts;
    services/persistence/routing-versions.ts, rate-versions.ts; catalog/validate-catalog-declarations.ts,
    digest-declarations.ts; db/migrations/0048_llm.sql (llm_refuse_version_change);
    aws/lambda/migrate.handler.ts.
---

# Operation and price version lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  declared --> current
  current --> superseded
  current --> current
```

## Transitions Explained

Current and superseded are derived positions in numbered history, not stored state flags. Deployment validates the catalogue and publishes rate and routing changes separately. Unchanged digests retain their number; a revert receives a new number.

## What Cannot Happen

Ordinary database writes cannot edit or delete a published version. Validation refuses invalid configuration before publication, but does not roll back appends committed before a later persistence error.

## Concurrency and Timing

Deployment runs catalogue publication after migrations. Warm consumers can retain earlier routing or pricing, and estimates come from their loaded code declaration. The design does not assume instant cache convergence.