---
id: WF-PFM-LLM-003
title: Publish the operation catalog at deploy
trigger: Publish changed model configuration during deployment.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-LLM-005
moves:
  - STATE-PFM-LLM-004
crosses:
  - SVC-PFM-LLM-llm
idempotency: >-
  Compare each declaration digest with current history; matching publication is a no-op and reverted content
  appends another number.
concurrency: >-
  Unique numbered histories resolve identical competing publishers; differing winners fail. Cached consumers
  need not immediately observe a new publication.
hops:
  - 'n': 1
    actor_or_service: Deploy-time migration function
    action: Run publication after migrations using a system context without an organization.
    anchor: 'services-platform:aws/lambda/migrate.handler.ts:publishLlmCatalog'
    seam: sync
    on_failure: Fail the deployment publication step on error.
    left_inconsistent: Earlier committed appends remain.
    observer: Deployment logs and publication failure response.
    provenance: observed
    source: 'services-platform:aws/lambda/migrate.handler.ts:publishLlmCatalog'
  - 'n': 2
    actor_or_service: Catalog publication
    action: 'Validate operation, price and execution declarations before writes.'
    anchor: 'services-platform:modules/llm/catalog/validate-catalog-declarations.ts:assertCatalogDeclarationsValid'
    seam: sync
    on_failure: Reject the entire invalid catalogue with its validation issues.
    left_inconsistent: No publication has started.
    observer: Deployment logs and publication failure response.
    provenance: observed
    source: 'services-platform:modules/llm/services/catalog/materialize-catalog.ts:materializeLlmCatalog'
  - 'n': 3
    actor_or_service: Catalog publication
    action: Append changed model-price versions before routing versions.
    anchor: 'services-platform:modules/llm/services/persistence/rate-versions.ts:appendRateVersion'
    seam: sync
    on_failure: Stop publication on a failed append.
    left_inconsistent: Previously committed prices remain and can affect existing model routing.
    observer: Deployment logs and publication failure response.
    provenance: observed
    source: 'services-platform:modules/llm/services/catalog/materialize-catalog.ts:materializeLlmCatalog'
  - 'n': 4
    actor_or_service: Catalog publication
    action: Append changed operation-routing versions.
    anchor: 'services-platform:modules/llm/services/persistence/routing-versions.ts:appendRoutingVersion'
    seam: sync
    on_failure: Fail on persistence error or a different competing publication.
    left_inconsistent: Earlier operations retain their new versions while later ones retain previous history.
    observer: Deployment logs and publication failure response.
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/routing-versions.ts:appendRoutingVersion'
branches:
  - The structured hops retain the applicable alternative path and its failure boundary.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: aws/lambda/migrate.handler.ts (publishLlmCatalog and the migration
    sequence); modules/llm/services/catalog/materialize-catalog.ts; catalog/validate-catalog-declarations.ts,
    digest-declarations.ts; services/persistence/routing-versions.ts, rate-versions.ts;
    db/migrations/0048_llm.sql.
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-006, TC-AI-007, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Publish the operation catalog at deploy

## What It Does

Engineers change declared prices and routing; deployment validates their complete catalogue before any append.

## The Flow

```mermaid
flowchart TD
  H1["Run publication after migrations using a system context without an organization."]
  H2["Validate operation, price and execution declarations before writes."]
  H1 --> H2
  H3["Append changed model-price versions before routing versions."]
  H2 --> H3
  H4["Append changed operation-routing versions."]
  H3 --> H4
```

Rates are appended first, then operation versions. Matching digests retain their existing number.

## When Something Fails

A persistence failure stops publication but preserves earlier committed appends. Those prices can already affect requests for existing routing.

## Open Design Questions

Catalogue-wide atomicity and warm-cache convergence are not implemented guarantees.