--- id: DOM-PFM-LLM-002 title: AI Operation realises: CON-PFM-LLM-002 product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owned_by: SVC-PFM-LLM-llm readable_by: [] lifecycle: STATE-PFM-LLM-004 custom_fields: none identity: >- A declared operation key and increasing version number identify routing history. Provider, model and version number identify price history. Generated row identifiers and content digests make published versions referable. attributes: - name: operation key kind: text required: true computed: false notes: Selects one of the keys declared by the catalogue. - name: application and feature kind: text required: true computed: false notes: Identifies the application and product feature used in accounting. - name: provider and model kind: text required: true computed: false notes: Selects a single provider and model; no substitute routing is configured. - name: generation settings kind: collection required: true computed: false notes: Defines reasoning effort and the output-token ceiling. - name: limits kind: collection required: true computed: false notes: 'Defines turn, tool, discovery, repair, retry, time and credit budgets.' - name: prompt reference and version kind: text required: true computed: false notes: Identifies the prompt template and its declared revision. - name: preflight estimate kind: collection required: true computed: false notes: Describes typical input and output usage for reservation sizing. - name: routing version kind: collection required: true computed: true notes: 'Stores the declared routing with its number, digest and publication time.' - name: model price kind: collection required: true computed: false notes: Defines credit and cent conversion rates per usage dimension. - name: rate version kind: collection required: true computed: true notes: Stores immutable published conversions with a number and digest. - name: AI task key kind: collection required: true computed: false notes: 'Defines a task identity, application and feature in code without separate publication.' relationships: - to: DOM-PFM-LLM-001 cardinality: one routing version and one rate version to many requests ownership: Requests retain their source facts; this relationship does not transfer request ownership. cross_service: false - to: DOM-PFM-LLM-003 cardinality: many operations to each organization's allowance ownership: The allowance owns period accounting and configuration; linked records consume those figures. cross_service: false - to: DOM-PFM-LLM-004 cardinality: one operation to many usage rows and catalog entries ownership: Reporting derives its values without owning the underlying records. cross_service: false invariants: - id: INV-DOM-PFM-LLM-002-01 statement: >- Operation resolution rejects undeclared keys and missing published routing or rates before creating a request. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/catalog/catalog-authority.ts:resolveLlmOperation' - id: INV-DOM-PFM-LLM-002-02 statement: >- Catalogue validation rejects invalid routing, pricing, identity and budget declarations before any publication write. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/catalog/validate-catalog-declarations.ts:assertCatalogDeclarationsValid' - id: INV-DOM-PFM-LLM-002-03 statement: An unchanged current digest adds no version; changed or reverted content receives the next number. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/routing-versions.ts:appendRoutingVersion' - id: INV-DOM-PFM-LLM-002-04 statement: Database triggers refuse ordinary updates and deletes of published routing and price versions. enforced_at: - database provenance: observed source: 'services-platform:db/migrations/0048_llm.sql:llm_refuse_version_change' - id: INV-DOM-PFM-LLM-002-05 statement: >- Reservation credits equal the rounded turn estimate multiplied by permitted turns and bounded by the declared ceiling. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/catalog/pricing.ts:reservationCredits' - id: INV-DOM-PFM-LLM-002-06 statement: >- Pricing sums dimensions before division, rounds credits upward and cents to nearest, and preserves unpriced units without charging them. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/catalog/pricing.ts:convertUsageToCredits' - id: INV-DOM-PFM-LLM-002-07 statement: Task creation requires a declared execution key with a valid application and feature. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/catalog/llm-executions.ts:requireLlmExecution' - id: INV-DOM-PFM-LLM-002-08 statement: >- A competing publication accepts an identical winning digest and rejects a different winner rather than retrying indefinitely. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/routing-versions.ts:appendRoutingVersion' physical: - platform.llm_operation_routing_versions - platform.llm_model_rate_versions evidence: - >- services-platform at ad3f6a6: modules/llm/catalog/* (llm-operations.ts, llm-rate-definitions.ts, llm-executions.ts, pricing.ts, digest-declarations.ts, validate-catalog-declarations.ts); services/catalog/materialize-catalog.ts, catalog-authority.ts; services/persistence/routing-versions.ts, rate-versions.ts; db/llm-operation-routing-versions.table.ts, llm-model-rate-versions.table.ts; db/migrations/0048_llm.sql; aws/lambda/migrate.handler.ts:publishLlmCatalog; prompts/queries/generate-query.md. --- # AI Operation ## What It Models An AI operation defines a repeatable kind of model work, including routing, prompt version, expected usage and conversation budgets. Separate model prices determine credit and monetary charges. The pinned catalogue declares query generation and its task key. ## Identity and Attributes A declared key identifies the operation. Published versions carry generated identifiers, increasing version numbers and content digests. Model prices are versioned by provider and model. Integer rates price usage per million units; one credit corresponds to one hundredth of a cent at list price. ## Relationships Requests retain the routing and price references they resolved. Organization limits and temporary exemptions refer to operation keys. Usage groups requests by declared application, feature, operation and model. ## Invariants Validation precedes publication and rejects invalid declarations before any append. Publication itself consists of separate transactions, so a later persistence failure can leave earlier versions committed. Database triggers refuse ordinary updates and deletions of version history. Reservation sizing and usage rounding follow the published pricing functions. ## How It Is Stored and Shared Engineers maintain declarations and deployment publishes changed versions. The histories are global configuration shared by organizations. Warm processes cache the resolved current versions; the resolver retries a missing lookup, but does not verify an existing cached row against the database. HQ reads the catalogue and rates through dedicated operations. ## Open Design Questions Conversation budgets do not constitute absolute spending or duration guarantees: final-answer acceptance precedes some budget checks, and tools have no enforced deadline. The recorded direction for another macroservice requires a shared runtime and Platform metering boundary. Older running code can combine its estimate with a differently published routing version.