Refresh architecture and configuration documentation for current runtime behavior

docs/architecture/structured-llm.md

@@ -1,90 +1,72 @@
 # Structured LLM Architecture
 
-## Purpose
-
+## Scope
 This document describes Audita's structured LLM runtime boundary and adapter behavior.
 
-## Why Audita owns the adapter
-
-Audita owns a small structured LLM adapter so that core runtime behavior is controlled inside the repository:
-- request construction and schema handling are explicit and testable;
-- retries, timeouts, cancellation, and error redaction are consistent across modules and validators;
-- provider SDK types are not exposed outside the adapter boundary;
-- dependency weight and transitive provider-specific behavior are reduced.
-
-At runtime, the rest of Audita depends only on the internal contract:
-- `StructuredLLMClient`
+## Runtime boundary
+Production LLM integration depends on the internal contract only:
+- `contracts.StructuredLLMClient`
 - `CompleteStructured(ctx, req, out)`
 
-## OpenAI-compatible request shape
+Provider SDK types do not leak past this boundary.
 
-At a conceptual level, Audita sends chat completion requests with:
-- `model`
-- `messages` (role/content pairs)
-- `response_format`:
-  - `type = "json_schema"`
-  - `json_schema.name` (stable schema name)
-  - `json_schema.strict = true`
-  - `json_schema.schema` (registered JSON Schema payload)
+## Adapter ownership
+`internal/framework/llm` owns the OpenAI-compatible HTTP adapter and shared LLM runtime utilities.
 
-The adapter uses OpenAI-compatible `POST {base_url}/chat/completions` over `net/http`.
+Key responsibilities:
+- request assembly;
+- timeout/cancellation propagation;
+- bounded retry behavior;
+- scheduler integration;
+- provider response decoding;
+- error redaction.
 
-## Structured response schema registry
+## Structured schema registry
+Structured response schemas are registered in `internal/framework/responseschema` and include stable metadata:
+- `id`
+- `version`
+- `name`
+- `json_schema`
+- `sha256`
 
-Structured response schemas are registered in `internal/framework/responseschema` with stable metadata:
-- schema key
-- schema ID
-- schema version
-- schema name (OpenAI-compatible `response_format` name)
-- raw JSON Schema payload
-- SHA-256 hash
+Current schema keys:
+- `correction_set`
+- `validator_decision_set`
 
-Current schemas:
-- `correction_set`:
-  - id `audita.correction_set`
-  - version `v1`
-  - name `audita_correction_set_v1`
-- `validator_decision_set`:
-  - id `audita.validator_decision_set`
-  - version `v1`
-  - name `audita_validator_decision_set_v1`
+Schema metadata is attached to diagnostics through `Schema.DiagnosticsMap()`.
 
-## Provider compatibility assumptions
+## Request shape assumptions
+Audita targets OpenAI-compatible chat-completions endpoints and sends structured requests with:
+- model;
+- chat messages;
+- `response_format.type = json_schema`;
+- schema name and JSON schema payload.
 
-Audita assumes an OpenAI-compatible chat-completions endpoint that:
-- accepts message arrays with model selection;
-- accepts `response_format.type = json_schema`;
-- returns a completion with assistant message content and optional usage metadata.
+## Local validation remains mandatory
+Provider schema enforcement is treated as transport-level guardrails.
 
-Provider-specific differences are expected in strictness and error payload shapes, so the adapter treats provider output as untrusted until locally decoded.
+Audita still validates output locally before applying behavior changes:
+- proposal decoding and proposal invariants;
+- validator decision decoding and cardinality checks;
+- deterministic validation and apply-time rules.
 
-## Local decode and validation remain mandatory
+## Shared malformed-output policy
+Malformed structured-output classification is centralized in `internal/framework/structuredoutput`.
 
-Provider-level structured output is a transport guardrail, not final validation.
+Proposal generation and validator execution both use this shared classifier so downgrade behavior cannot drift between the two paths.
 
-After receiving a response, Audita still:
-- decodes assistant content into typed request-specific structs;
-- validates proposal and validator payload invariants locally;
-- enforces deterministic validator/cardinality rules before any transcript application.
+## Secrets and redaction
+Secret extraction for LLM redaction is centralized in `llm.ConfiguredSecrets(cfg)` and reused by proposal and validator diagnostics writers.
 
-This protects runtime correctness even when provider responses are malformed, partial, or semantically inconsistent.
+Secrets are redacted from:
+- diagnostics artifacts;
+- report artifacts;
+- surfaced adapter/runtime errors.
 
-## Diagnostics and redaction
+## Concurrency and scheduling
+LLM execution is constrained by composed scheduler limits:
+- total LLM concurrency;
+- proposal LLM concurrency;
+- validation LLM concurrency.
 
-When structured schemas are used, diagnostics metadata records:
-- schema ID
-- schema version
-- schema name
-- schema hash
-
-Diagnostics and surfaced errors preserve secret redaction:
-- API keys and bearer tokens are redacted from request/response/error artifacts;
-- redaction is applied before diagnostic files are written.
-
-## Runtime behavior guarantees
-
-The structured LLM path preserves existing runtime guarantees:
-- bounded LLM call execution through schedulers;
-- context-aware cancellation and timeout propagation;
-- retry behavior for transient failures and retryable malformed structured responses;
-- deterministic module/chunk/proposal/validator behavior outside provider nondeterminism.
+The scheduler is FIFO and context-aware so permits are released on success, failure, and cancellation.