---
id: CAP-PFM-LLM-003
title: Keep one account for a multi-request AI task
feature: FEAT-PFM-LLM-01
product_area: platform
module: llm
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
intent_sources: []
purpose: Group related model requests into a task whose outcome and total cost staff can inspect.
outcomes:
  - A task aggregates its request counts and charges.
  - An idempotency key prevents a duplicate task from running.
  - Failed tasks retain charges from completed requests.
concepts:
  - CON-PFM-LLM-001
actors:
  - ACT-PFM-034
  - ACT-PFM-032
surfaces:
  - api
  - job
preconditions:
  - The execution key exists in the catalog.
postconditions:
  - The execution retains its final outcome and request totals.
permissions: []
rules:
  - id: BR-CAP-PFM-LLM-003-01
    proved_by: [ATS-PFM-LLM-003-01, ATS-PFM-LLM-003-08, TST-PFM-LLM-018, TST-PFM-LLM-045]
    statement: >-
      The execution starts running before its first request and closes completed or failed with its completion
      time and elapsed duration.
    kind: lifecycle
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/with-llm-execution.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-02
    proved_by: [ATS-PFM-LLM-003-02, TST-PFM-LLM-018]
    statement: >-
      Only the exact context supplied by the execution wrapper associates a request with it; outside or
      derived contexts carry no execution association.
    kind: invariant
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/execution-scope.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-03
    proved_by: [ATS-PFM-LLM-003-03, TST-PFM-LLM-018]
    statement: Opening a nested execution is rejected and makes the enclosing execution fail.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/with-llm-execution.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-04
    proved_by: [ATS-PFM-LLM-003-04, TST-PFM-LLM-018, TST-PFM-LLM-057]
    statement: >-
      An unknown execution key is rejected before creating a record, and duplicate keys, unknown applications
      or empty features invalidate publication.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/catalog/llm-executions.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-05
    proved_by: [ATS-PFM-LLM-001-12, ATS-PFM-LLM-003-05, ATS-PFM-LLM-003-09, ATS-PFM-LLM-003-11, TST-PFM-LLM-018, TST-PFM-LLM-032]
    statement: >-
      Request settlement atomically adds one request and its credits and cents to the execution; estimated
      settlement adds no cents, released settlement adds no cost, refusals add no settlement count, and late
      settlements still contribute.
    kind: calculation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/invocations.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-06
    proved_by: [ATS-PFM-LLM-003-06, ATS-PFM-LLM-003-10, TST-PFM-LLM-012, TST-PFM-LLM-018]
    statement: >-
      Reusing an organization’s execution idempotency key returns the earlier running or closed execution as a
      replay without invoking the task again.
    kind: policy
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/with-llm-execution.ts'
    origin: none
  - id: BR-CAP-PFM-LLM-003-07
    proved_by: []
    statement: >-
      The execution retains its declared identity, application, feature, caller attribution and any subject
      record.
    kind: invariant
    enforced_at:
      - service
    must_prove: false
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/lifecycle/executions.integration.spec.js#records the
      declared key, the attribution and the subject
    origin: none
  - id: BR-CAP-PFM-LLM-003-08
    proved_by: []
    statement: >-
      A settlement log identifies its enclosing execution when one exists and leaves that association absent
      otherwise.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/lifecycle/executions.integration.spec.js#carries the
      execution id on the call made inside the execution
    origin: none
  - id: BR-CAP-PFM-LLM-003-09
    proved_by: [ATS-PFM-LLM-003-07]
    statement: >-
      A task failure remains the caller’s error even if closing its execution also fails; that close failure
      is logged. After successful task work, a close failure is returned to the caller.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: 'services-platform:modules/llm/services/execution/with-llm-execution.ts:withLlmExecution'
    origin: none
scenarios:
  - id: SC-CAP-PFM-LLM-003-01
    given: A task performs three requests.
    when: The task finishes successfully.
    then: Its execution records their count and summed charges.
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/lifecycle/executions.integration.spec.js#charges the
      period exactly what the execution totalled
  - id: SC-CAP-PFM-LLM-003-02
    given: A task fails after two completed requests.
    when: The failure closes the execution.
    then: The failed task retains those request charges and its elapsed time.
    provenance: test
    source: >-
      services-platform:modules/llm/tests/integration/lifecycle/executions.integration.spec.js#keeps the
      credits those two calls were charged
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-LLM-001
related:
  - CAP-PFM-LLM-009
  - CAP-PFM-LLM-011
journeys: []
open_questions: []
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Executions);
    modules/llm/services/execution/with-llm-execution.ts, execution-scope.ts; catalog/llm-executions.ts;
    db/llm-executions.table.ts; tests integration/lifecycle/executions.integration.spec.js,
    integration/db/llm-executions.table.integration.spec.js, unit/catalog/llm-executions.spec.ts.
controls: [TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-004, TC-LOG-005, 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]
exercised_by: [FAS-PFM-LLM-01-01, FAS-PFM-LLM-01-02, FAS-PFM-LLM-01-03, FAS-PFM-LLM-01-05]
suites: [TST-PFM-LLM-012, TST-PFM-LLM-018, TST-PFM-LLM-032, TST-PFM-LLM-045, TST-PFM-LLM-057]
---

# Keep one account for a multi-request AI task

## Purpose

Group related model requests into a task whose outcome and total cost staff can inspect.

## How It Works

A consuming feature opens an execution around the work it wants to account for. The wrapper supplies a context that associates its model requests with that execution. Each request still passes through normal admission and settlement. Settlements add to the execution’s counters as they become final. A refusal remains associated with the task without becoming a settled request count. The wrapper closes the task according to whether its work returns or throws. Reusing an idempotency key retrieves the prior execution without repeating the work. Recovery later identifies abandoned tasks and reports counter drift.

## Relationships

- Run AI requests with consistent attribution and accounting supplies the prerequisite behavior for this outcome.