--- id: DOM-PFM-LLM-001 title: AI Request realises: CON-PFM-LLM-001 product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-PFM-LLM-llm readable_by: [] lifecycle: STATE-PFM-LLM-001 custom_fields: none identity: >- A generated request identifier is created before admission. The record retains its organization, local month, operation versions and optional task association; attempt positions identify its provider requests. attributes: - name: organization kind: reference required: true computed: false notes: Derived from the executing organization rather than supplied as a request argument. - name: operation kind: reference required: true computed: false notes: Names a declared catalogue operation; unresolved operations fail before record creation. - name: allowance period kind: reference required: true computed: true notes: Uses the start month in the organization’s calendar. - name: routing version and rate version kind: reference required: true computed: true notes: Pins the routing and price resolved for this request. - name: 'provider, model and prompt version' kind: text required: true computed: true notes: 'Copies provider, model and prompt identity from routing history.' - name: application and feature kind: text required: true computed: true notes: Copies application and feature attribution from the resolved routing. - name: caller attribution kind: collection required: true computed: true notes: 'Retains actor, access type, request and correlation identifiers and any asserted service beneficiary.' - name: AI task kind: reference required: false computed: true notes: Present only for requests using the wrapper’s exact scoped context. - name: status kind: enum required: true computed: false notes: Records accounting progress independently of the model outcome. - name: estimate and reservation kind: number required: true computed: true notes: Stores the bounded per-turn estimate and its monetary equivalent. - name: conversation counts kind: number required: false computed: true notes: 'Retains turn, tool and attempt counts and whether persisted attempts were truncated.' - name: outcome and error classification kind: enum required: false computed: true notes: Describes conversation completion separately from closed failure or refusal classification. - name: reported usage kind: collection required: false computed: true notes: Aggregates provider-reported units and retains dimensions without declared prices. - name: settlement kind: money required: false computed: true notes: 'Retains charge, settlement kind and time; estimate settlements omit monetary cost.' - name: refusal figures kind: collection required: false computed: true notes: 'Preserves allowance, needed credits, concurrency, switches and active capacity at refusal time.' - name: captured content kind: collection required: true computed: true notes: 'Retains capture state, optional object references and expiry; bodies remain outside the database.' - name: attempts kind: collection required: false computed: false notes: 'Retains operational attempt metadata and individual prices, capped at sixty-four stored entries.' - name: past-window alert kind: date required: false computed: true notes: Records the first recovery alert for a request beyond its settlement window. relationships: - to: DOM-PFM-LLM-002 cardinality: many requests to one routing version and one rate version ownership: The operation catalogue owns its definitions; related records keep references. cross_service: false - to: DOM-PFM-LLM-003 cardinality: many requests to one monthly allowance period ownership: The allowance owns period accounting and configuration; linked records consume those figures. cross_service: false - to: DOM-PFM-LLM-004 cardinality: many requests summarised into many daily usage rows ownership: Reporting derives its values without owning the underlying records. cross_service: false invariants: - id: INV-DOM-PFM-LLM-001-01 statement: The runtime creates the request before reserving credits or contacting a provider. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation' - id: INV-DOM-PFM-LLM-001-02 statement: 'Normal status writes compare the expected state, and a competing change produces a no-op.' enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/db/llm-invocations.table.ts:LLM_INVOCATION_TRANSITIONS' - id: INV-DOM-PFM-LLM-001-03 statement: >- Settlement changes the request and task totals once; period accounting remains separate and cleanup can still release credits after a competing settlement. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled' - id: INV-DOM-PFM-LLM-001-04 statement: 'Estimate settlement omits cents, while release records zero credits and cents.' enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled' - id: INV-DOM-PFM-LLM-001-05 statement: Admission refusal records its reason and snapshot without dispatching or taking a hold. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationRefused' - id: INV-DOM-PFM-LLM-001-06 statement: The runtime derives routing and feature attribution from published configuration. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation' - id: INV-DOM-PFM-LLM-001-07 statement: Only the exact task-scoped context attaches a request to an execution. enforced_at: - service provenance: observed source: 'services-platform:modules/llm/services/execution/execution-scope.ts:llmExecutionIdOf' - id: INV-DOM-PFM-LLM-001-08 statement: >- Attempt rows contain operational metadata; counts beyond sixty-four mark truncation without storing more rows. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/db/llm-invocation-attempts.table.ts:MAX_ATTEMPTS_PER_INVOCATION' - id: INV-DOM-PFM-LLM-001-09 statement: A captured body requires a non-null storage key. enforced_at: - database provenance: observed source: 'services-platform:db/migrations/0048_llm.sql:llm_invocations_request_payload_key_check' - id: INV-DOM-PFM-LLM-001-10 statement: Request settlement increments task totals in the same transaction. enforced_at: - service - database provenance: observed source: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled' - id: INV-DOM-PFM-LLM-001-11 statement: Documented organization row policy restricts request and attempt access to the selected organization. enforced_at: - database provenance: documented source: 'services-platform:docs/llm.md#The tables' - id: INV-DOM-PFM-LLM-001-12 statement: 'Stored request failure classifications use a closed vocabulary, and caller errors use Rhythm’s wording.' enforced_at: - service provenance: observed source: 'services-platform:modules/llm/db/llm-invocations.table.ts:LLM_INVOCATION_ERROR_CLASSIFICATIONS' physical: - platform.llm_invocations - platform.llm_invocation_attempts - platform.llm_executions - platform.llm_invocations_query (reporting view) - platform-llm-evidence- (evidence bucket) evidence: - >- services-platform at ad3f6a6: modules/llm/db/llm-invocations.table.ts, llm-invocation-attempts.table.ts, llm-executions.table.ts; services/persistence/invocations.ts, executions.ts; services/execution/run-operation.ts, execution-scope.ts, with-llm-execution.ts; services/metering/refusal-snapshot.ts; services/evidence/*; db/migrations/0048_llm.sql; docs/llm.md (The order of the steps, Attribution, Executions, The refusal snapshot). --- # AI Request ## What It Models An AI request records one model conversation for a consuming feature. Support uses it to inspect attribution, provider attempts, outcome and charge. Its task groups related requests, while captured evidence holds redacted conversation bodies separately. ## Identity and Attributes The runtime creates the identifier before admission. It copies published routing and price references and derives attribution from the caller context. A local month key identifies the allowance period even before that period exists. Outcome and settlement are independent: unsuccessful work can incur a charge, and an estimate settlement has no known monetary cost. Task records retain their declared feature, subject, caller, timing and accumulated settlements. ## Relationships The request refers to operation versions and an allowance month. An optional task association comes from the exact context supplied by the execution wrapper. Derived reporting groups closed requests by their start day. The consuming feature retains responsibility for validating and applying the answer. ## Invariants Normal status changes require an expected current status. Settlement excludes requests already settled or refused and increments task totals in its own transaction. That protection does not make allowance movements atomic with request changes. Attempt storage has a retention-count limit, while evidence references have database checks. ## How It Is Stored and Shared Platform stores requests, attempts and tasks under organization-scoped access. HQ detail routes enter the selected organization; the reporting reader uses the daily aggregate instead. Customer reports omit conversation bodies and sensitive bookkeeping. Private object storage holds redacted bodies under the organization prefix with a ninety-day lifecycle policy; workspace removal deletes those versions after dependent records. ## Open Design Questions A hold can commit before its amount is recorded on the request, and settlement can commit before the month receives its charge. Recovery does not repair terminal requests with incomplete period accounting. Product must decide how stale requests should be charged and whether asserted beneficiary attribution needs verification.