--- id: WF-PFM-QRY-004 title: Draft a query from a written request trigger: >- A permitted person submits a written query request, optionally with an open query or settled predecessor for refinement. product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f inference: - IOP-PFM-QRY-001 implements: - CAP-PFM-QRY-003 moves: - STATE-PFM-QRY-003 crosses: - SVC-PFM-QRY-queries idempotency: >- Each submission creates a generation and can incur another metered invocation. Conditional working-status settlement prevents two stored verdicts, but does not prove that a duplicate invocation performs no inference. concurrency: >- Worker concurrency bounds environment processing. Foundation reservations and in-flight limits provide the spending and simultaneous-call gates; a working predecessor cannot be refined. hops: - 'n': 1 actor_or_service: Generate route (queries API) action: >- Validate the trimmed request, resolve the base dataset for the caller and check any supplied current query. anchor: 'services-platform:modules/queries/services/generate/start-generation.ts' seam: sync on_failure: Refuse malformed input or missing access before admission. left_inconsistent: No generation row is created by these refusals. observer: the person (refusal message) provenance: observed source: 'services-platform:modules/queries/services/generate/start-generation.ts' - 'n': 2 actor_or_service: Generate route action: Check the advisory allowance against the operation reservation estimate. anchor: 'services-platform:modules/queries/services/generate/generation-allowance.ts' seam: sync on_failure: Refuse insufficient allowance with the foundation code and credit information. left_inconsistent: No generation is admitted by this allowance refusal. observer: the person provenance: observed source: 'services-platform:modules/queries/services/generate/generation-allowance.ts' - 'n': 3 actor_or_service: Generate route action: >- Commit a working generation, then asynchronously invoke its worker with the workspace and generation identity. anchor: 'services-platform:modules/queries/services/generate/start-generation.ts' seam: event on_failure: An observed invocation failure immediately settles the generation as failed. left_inconsistent: A crash after commit but before invocation can leave working status until reconciliation. observer: the person polling; the sweep provenance: observed source: 'services-platform:modules/queries/services/generate/start-generation.ts' - 'n': 4 actor_or_service: Generation worker action: >- Rebuild the requester context and assemble permitted metadata and fenced request context. Keep the base and nearest whole datasets within the dictionary budget. anchor: 'services-platform:modules/queries/services/generate/query-dictionary.ts' seam: sync on_failure: Fail if the base context cannot fit or required configuration is unavailable. left_inconsistent: The request settles with a code rather than a partial dictionary submission. observer: the person polling provenance: observed source: 'services-platform:modules/queries/services/generate/generate-query-context.ts' - 'n': 5 actor_or_service: LLM foundation action: >- Call the foundation with validation, bounded test-run and final-outcome tools, within the declared turn, tool, repair and time budgets. anchor: 'services-platform:modules/queries/services/generate/generation-runner.ts' seam: sync on_failure: >- Provider or foundation failures return declared codes; invocation settlement accounts for actual spend. left_inconsistent: A process interruption may require foundation reconciliation of the reservation. observer: the LLM usage records; the generation log provenance: observed source: 'services-platform:modules/queries/services/generate/generate-query-tools.ts' - 'n': 6 actor_or_service: Generation worker action: >- Apply deterministic defaults, validate the request and generation restrictions, and compile as the requester. Store an accepted query, clarification or unsupported outcome, or reject the final output. anchor: 'services-platform:modules/queries/services/generate/run-generation.ts' seam: sync on_failure: Conditional settlement records a failure code; diagnostics stay in logs. left_inconsistent: 'Only one outcome is retained, including any permitted model-authored explanatory content.' observer: the person polling provenance: observed source: 'services-platform:modules/queries/services/generate/validate-generated-query.ts' - 'n': 7 actor_or_service: Query designer (console) action: >- Poll the outcome and load an accepted draft into the designer for inspection and ordinary user-triggered execution. anchor: 'react-console:lib/queries/platform/generate-interpret.ts' seam: sync on_failure: Translate the stored code into the console failure message. left_inconsistent: The person can still build a query manually after generation failure. observer: the person provenance: observed source: 'react-console:components/queries/ai-prompt-bar.tsx' branches: - >- Clarification and unsupported responses are successful conversation outcomes without an executable draft. - Refinement creates a new generation with the previous request and outcome as context. waits: - >- The console waits for settlement within its polling limit; the worker has a two-minute operation budget plus execution margin. evidence: - >- services-platform at ad3f6a6: modules/queries/services/generate/*.ts; aws/logic/queries-generation.lambda.ts; modules/llm/catalog/llm-operations.ts; docs/llm/llm-foundation-and-generate-query.md (work plan approved 2026-10-10, accepted 2026-10-12) - >- react-console at baf6dae: components/queries/ai-prompt-bar.tsx; lib/queries/platform/generate-interpret.ts 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-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, 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] --- # Draft a query from a written request ## What It Does A permitted person submits a written query request, optionally with an open query or settled predecessor for refinement. Clarification and unsupported responses are successful conversation outcomes without an executable draft. ## The Flow ```mermaid sequenceDiagram participant C as Request or schedule participant H0 as Generate route queries API participant H1 as Generate route participant H2 as Generate route participant H3 as Generation worker participant H4 as LLM foundation participant H5 as Generation worker participant H6 as Query designer console C->>H0: Validate the trimmed request, resolve the base dataset for the caller and check any supplied current H0->>H1: Check the advisory allowance against the operation reservation estimate H1-)H2: Commit a working generation, then asynchronously invoke its worker with the workspace and generation H2->>H3: Rebuild the requester context and assemble permitted metadata and fenced request context H3->>H4: Call the foundation with validation, bounded test-run and final-outcome tools, within the declared t H4->>H5: Apply deterministic defaults, validate the request and generation restrictions, and compile as the r H5->>H6: Poll the outcome and load an accepted draft into the designer for inspection and ordinary user-trigg ``` Validate the trimmed request, resolve the base dataset for the caller and check any supplied current query. Check the advisory allowance against the operation reservation estimate. Commit a working generation, then asynchronously invoke its worker with the workspace and generation identity. Rebuild the requester context and assemble permitted metadata and fenced request context. Keep the base and nearest whole datasets within the dictionary budget. Call the foundation with validation, bounded test-run and final-outcome tools, within the declared turn, tool, repair and time budgets. Apply deterministic defaults, validate the request and generation restrictions, and compile as the requester. Store an accepted query, clarification or unsupported outcome, or reject the final output. Poll the outcome and load an accepted draft into the designer for inspection and ordinary user-triggered execution. ## When Something Fails Refuse malformed input or missing access before admission. No generation row is created by these refusals. Refuse insufficient allowance with the foundation code and credit information. No generation is admitted by this allowance refusal. An observed invocation failure immediately settles the generation as failed. A crash after commit but before invocation can leave working status until reconciliation. Fail if the base context cannot fit or required configuration is unavailable. The request settles with a code rather than a partial dictionary submission. Provider or foundation failures return declared codes; invocation settlement accounts for actual spend. A process interruption may require foundation reconciliation of the reservation. Conditional settlement records a failure code; diagnostics stay in logs. Only one outcome is retained, including any permitted model-authored explanatory content. Translate the stored code into the console failure message. The person can still build a query manually after generation failure. ## Idempotency and Concurrency Each submission creates a generation and can incur another metered invocation. Conditional working-status settlement prevents two stored verdicts, but does not prove that a duplicate invocation performs no inference. Worker concurrency bounds environment processing. Foundation reservations and in-flight limits provide the spending and simultaneous-call gates; a working predecessor cannot be refined.