---
id: WF-PFM-LLM-001
title: Run one metered AI request
trigger: Run one metered AI conversation for a consuming feature.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference:
  - IOP-PFM-LLM-002
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-LLM-001
  - CAP-PFM-LLM-002
  - CAP-PFM-LLM-004
  - CAP-PFM-LLM-007
  - CAP-PFM-LLM-013
moves:
  - STATE-PFM-LLM-001
  - STATE-PFM-LLM-003
  - STATE-PFM-LLM-005
  - STATE-PFM-LLM-006
crosses:
  - SVC-PFM-LLM-llm
idempotency: >-
  Every call creates a request; only status and settlement writes are conditional. Consumer task replay can
  suppress another call but does not repair incomplete period accounting.
concurrency: >-
  Admission serializes on the monthly row and respects the running cap. Access checks, reservation recording
  and settlement movements are separate transactions.
hops:
  - 'n': 1
    actor_or_service: Consuming feature (Queries generation worker)
    action: >-
      The consumer supplies prompt values, messages, tools, handlers and final-answer validation on its task
      context.
    anchor: 'services-platform:modules/queries/services/generate/run-generation.ts:runGeneration'
    seam: sync
    on_failure: Propagate the consumer error before runtime work begins.
    left_inconsistent: No foundation record has been created.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/queries/services/generate/generation-runner.ts:foundationGenerationRunner'
  - 'n': 2
    actor_or_service: LLM foundation runtime
    action: Resolve published routing and pricing and render the prompt.
    anchor: 'services-platform:modules/llm/services/catalog/catalog-authority.ts:resolveLlmOperation'
    seam: sync
    on_failure: Reject missing declarations or publication before creating a request.
    left_inconsistent: No request or hold exists.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 3
    actor_or_service: LLM foundation runtime
    action: Calculate reservation and create estimated request bookkeeping with context attribution.
    anchor: 'services-platform:modules/llm/services/persistence/invocations.ts:createInvocation'
    seam: sync
    on_failure: Propagate creation failure.
    left_inconsistent: No allowance movement has occurred.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 4
    actor_or_service: LLM foundation runtime
    action: Check AI and operation switches and record a refusal snapshot when access is disabled.
    anchor: 'services-platform:modules/llm/services/limits/tenant-limits.ts:checkOperationAccess'
    seam: sync
    on_failure: Return the closed disabled-operation error; persistence failure propagates.
    left_inconsistent: An estimated row can remain for recovery even without a provider call or hold.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 5
    actor_or_service: Credit ledger
    action: Create the month when needed and conditionally reserve credits and a running slot.
    anchor: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits'
    seam: sync
    on_failure: Reject insufficient allowance or concurrency and record the admission snapshot.
    left_inconsistent: A failed refusal write can leave estimated bookkeeping after an unheld admission decision.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:authorize'
  - 'n': 6
    actor_or_service: LLM foundation runtime
    action: Record the reservation amount on the request after the hold succeeds.
    anchor: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationReserved'
    seam: sync
    on_failure: Propagate write failure before the protected cleanup block.
    left_inconsistent: The period can retain an unrecorded hold and slot that recovery cannot fully release.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 7
    actor_or_service: LLM foundation runtime and evidence store
    action: 'Write redacted request evidence, then persist capture status and its optional reference.'
    anchor: 'services-platform:modules/llm/services/evidence/evidence-store.ts:captureEvidence'
    seam: sync
    on_failure: Absorb capture-helper failure; propagate metadata-write failure outside cleanup.
    left_inconsistent: A hold remains and an evidence object can lack a recorded reference.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/invocations.ts:recordPayloadCapture'
  - 'n': 8
    actor_or_service: LLM foundation runtime
    action: Record dispatch before entering protected provider execution.
    anchor: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationDispatched'
    seam: sync
    on_failure: Propagate dispatch-write failure outside cleanup.
    left_inconsistent: The recorded reservation remains until a later recovery pass.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 9
    actor_or_service: LLM foundation runtime and Anthropic
    action: 'Construct the selected provider and run the tool loop, recording attempts and retrying eligible errors.'
    anchor: 'services-platform:modules/llm/runtime/run-tool-loop.ts:runToolLoop'
    seam: sync
    on_failure: >-
      Provider-execution and attempt-recording errors become failed loop results; provider construction can
      escape to cleanup.
    left_inconsistent: >-
      In-memory usage can be charged despite an absent attempt row; escaped errors and cleanup failures have
      separate accounting effects.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/runtime/execute-with-llm-retry.ts:executeWithLlmRetry'
  - 'n': 10
    actor_or_service: LLM foundation runtime and evidence store
    action: Write redacted response evidence and record its capture result.
    anchor: 'services-platform:modules/llm/services/execution/run-operation.ts:recordCapture'
    seam: sync
    on_failure: Absorb body-write failure; metadata-write failure escapes to release cleanup.
    left_inconsistent: 'Real provider usage can be followed by a zero-cost release, or cleanup can itself fail.'
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 11
    actor_or_service: LLM foundation runtime
    action: 'Record conversation outcome, counts and usage, using pending for unmeasured completion.'
    anchor: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationCompleted'
    seam: sync
    on_failure: An uncaught persistence error invokes release cleanup.
    left_inconsistent: 'The request can be released despite incurred usage, or remain unsettled if cleanup fails.'
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/invocations.ts:markInvocationFailed'
  - 'n': 12
    actor_or_service: LLM foundation runtime and credit ledger
    action: 'Settle the request and task totals together, then replace the period hold with its charge separately.'
    anchor: 'services-platform:modules/llm/services/execution/run-operation.ts:settleInvocation'
    seam: sync
    on_failure: Skip another charge when settlement did not apply; failures can enter cleanup.
    left_inconsistent: >-
      A missing period charge or repeated release can separate request cost from monthly balances and disturb
      other holds.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:runOperation'
  - 'n': 13
    actor_or_service: Credit ledger
    action: 'Evaluate charged-usage thresholds, insert newly reached crossings and attempt their notices.'
    anchor: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:evaluateCrossings'
    seam: sync
    on_failure: Log notice-start errors; crossing persistence errors can escape settlement.
    left_inconsistent: >-
      A committed period movement followed by failure can cause another cleanup release; absent crossings
      await another settlement.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/metering/llm-credit-ledger.ts:settle'
  - 'n': 14
    actor_or_service: LLM foundation runtime
    action: 'Return outcome, answer, usage and request identity, or raise the closed provider error.'
    anchor: 'services-platform:modules/llm/services/metering/llm-metering-errors.ts:LlmProviderRefusedError'
    seam: sync
    on_failure: The consumer interprets and validates returned outcomes.
    left_inconsistent: The consumer’s subsequent domain writes are outside this runtime contract.
    observer: 'Request and attempt history where writes succeeded, consumer errors and runtime telemetry.'
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/run-operation.ts:providerFailure'
branches:
  - Admission refusal ends before evidence and provider execution.
  - A failed loop result is settled before the closed provider error is raised.
  - A provider refusal can incur usage and is raised after settlement.
waits:
  - >-
    Provider attempts are bounded by the attempt timeout and remaining loop duration; handlers and final
    validation have no enforced deadline.
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/services/execution/run-operation.ts;
    services/metering/llm-credit-ledger.ts, llm-metering-errors.ts, refusal-snapshot.ts;
    services/persistence/invocations.ts, allowance-periods.ts; services/limits/tenant-limits.ts;
    services/evidence/evidence-store.ts; runtime/run-tool-loop.ts, execute-with-llm-retry.ts, retry-policy.ts,
    provider-factory.ts; modules/queries/services/generate/run-generation.ts, generation-runner.ts (the
    consumer, read to name it); docs/llm.md#The order of the steps, which is the design.
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, 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-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Run one metered AI request

## What It Does

The consumer controls question construction and answer validation. Platform records routing, admission, attempts, evidence and settlement. Query generation is the pinned consumer; general Jazz AI replies bypass this path.

## The Flow

```mermaid
flowchart TD
  H1["The consumer supplies prompt values, messages, tools, handlers and final-answer validation on its task context."]
  H2["Resolve published routing and pricing and render the prompt."]
  H1 --> H2
  H3["Calculate reservation and create estimated request bookkeeping with context attribution."]
  H2 --> H3
  H4["Check AI and operation switches and record a refusal snapshot when access is disabled."]
  H3 --> H4
  H5["Create the month when needed and conditionally reserve credits and a running slot."]
  H4 --> H5
  H6["Record the reservation amount on the request after the hold succeeds."]
  H5 --> H6
  H7["Write redacted request evidence, then persist capture status and its optional reference."]
  H6 --> H7
  H8["Record dispatch before entering protected provider execution."]
  H7 --> H8
  H9["Construct the selected provider and run the tool loop, recording attempts and retrying eligible errors."]
  H8 --> H9
  H10["Write redacted response evidence and record its capture result."]
  H9 --> H10
  H11["Record conversation outcome, counts and usage, using pending for unmeasured completion."]
  H10 --> H11
  H12["Settle the request and task totals together, then replace the period hold with its charge separately."]
  H11 --> H12
  H13["Evaluate charged-usage thresholds, insert newly reached crossings and attempt their notices."]
  H12 --> H13
  H14["Return outcome, answer, usage and request identity, or raise the closed provider error."]
  H13 --> H14
```

The request write precedes admission, capture and dispatch. After the loop result, response capture and request settlement precede separate monthly accounting and threshold evaluation.

## When Something Fails

Earlier failures can strand holds. Escaped errors attempt release, but errors caught by the tool loop return failed results with accumulated usage for settlement. A failed period update or repeated cleanup release can leave monthly accounting inconsistent.

## Open Design Questions

Decide atomic accounting boundaries and the charge policy for stale work.