Add Phase 9 LLM scheduler, config resolution, diagnostics primitives

docs/architecture.md

@@ -23,6 +23,9 @@ Implemented today:
 - Deterministic validator-chain execution in the runner with cardinality enforcement.
 - Module-level validator decision/rejection reporting.
 - Internal structured LLM client contract plus an `instructor-go`-backed adapter package.
+- Bounded LLM scheduler/semaphore infrastructure with context-aware permit handling.
+- Runtime primary/validation LLM effective-config resolution helpers with validation inheritance.
+- Generic JSON prompt/response diagnostics writer primitives with secret redaction.
 
 Not implemented in CLI runtime path today:
 - Real module execution pipeline (`glossary`, `homophones`, `spoken_word`, `grammar`).
@@ -32,7 +35,8 @@ Not implemented in CLI runtime path today:
 - End-to-end transcript polishing with real module behavior.
 
 Phase sequencing note:
-- structured LLM client infrastructure is implemented, but scheduler and runtime wiring remain Phase 9 follow-up work;
+- structured LLM client, scheduler, config-resolution helpers, and diagnostics primitives are implemented;
+- runtime wiring from modules/validators/runner into this LLM infrastructure remains Phase 9 follow-up work;
 - LLM-backed validators remain Phase 10 work.
 
 ## Actual Go package layout
@@ -92,6 +96,9 @@ internal/framework/validators/
 
 internal/framework/llm/
   instructor_client.go
+  scheduler.go
+  effective_config.go
+  diagnostics.go
 ```
 
 ## Current CLI behavior
@@ -189,6 +196,11 @@ Current runtime boundary:
 - the CLI/runner runtime path does not instantiate this adapter yet;
 - no production LLM requests are performed by `audita process`.
 
+`internal/framework/llm` also provides:
+- a bounded `Scheduler` for controlled concurrent LLM calls with reliable permit release;
+- primary/validation effective-config resolution helpers, including validation inheritance fallback to primary settings;
+- generic interaction diagnostics primitives that write machine-readable JSON artifacts for request metadata, request payload, response payload, and optional error payload with secret redaction.
+
 ## Implemented normalization behavior
 Normalization (`internal/core/normalization`) currently:
 - sorts by segment start time;

docs/rewrite-notes.md

@@ -58,13 +58,18 @@ Implemented:
   - optional API key support for local-compatible endpoints
   - API-key redaction in returned errors
   - typed structured decode into caller-provided outputs.
+- LLM scheduler/semaphore infrastructure for bounded concurrency with context-aware acquisition and reliable release.
+- LLM effective-config resolution helpers:
+  - primary config resolution
+  - validation config inheritance from primary when validation fields are unset
+  - validation override behavior when validation fields are set.
+- Generic JSON diagnostics primitives for LLM interactions (request metadata, request payload, response payload, optional error payload) with secret redaction.
 
 Not yet implemented in runtime pipeline:
 - Real correction modules.
-- Structured LLM scheduler/concurrency orchestration.
 - Runtime wiring from production runner/modules into the structured LLM adapter.
 - LLM-backed validators.
-- Prompt/response diagnostics for LLM calls.
+- Module/validator call-site wiring to emit LLM prompt/response diagnostics artifacts.
 - End-to-end transcript polishing behavior.
 
 ## Completed phases
@@ -196,14 +201,14 @@ Implemented:
 
 Not implemented in Phase 8 (by design):
 - LLM-backed validators (Phase 10).
-- Structured LLM scheduler behavior or runtime wiring (Phase 9 follow-up).
+- Structured LLM runtime wiring (Phase 9 follow-up).
 - Real correction modules.
-- Prompt/response diagnostics.
+- Prompt/response diagnostics runtime wiring.
 - End-to-end transcript polishing.
 
 ## Remaining work plan
 
-Next recommended phase: **Phase 9 follow-up (scheduler + runtime LLM wiring, still no real modules)**.
+Next recommended phase: **Phase 9 follow-up (runtime LLM wiring, still no real modules)**.
 
 ## Phase 9: Structured LLM client and scheduler infrastructure
 
@@ -218,10 +223,9 @@ Implemented in this phase so far:
 - Added adapter unit tests for model/base URL handling, retries, context cancellation, optional API key behavior, and error redaction.
 
 Still pending in Phase 9:
-- Scheduler/semaphore behavior for bounded concurrency.
 - Runtime wiring in runner/module infrastructure (without introducing real modules yet).
-- Prompt/response diagnostics writer primitives for LLM call artifacts.
-- Full primary vs validation LLM config-resolution plumbing into runtime LLM call sites.
+- Wiring prompt/response diagnostics primitives into future module/validator call sites.
+- Wiring effective primary/validation LLM config resolution into runtime LLM call sites.
 
 ### Purpose
 
@@ -230,11 +234,8 @@ Implement the provider-neutral LLM infrastructure needed by both proposal genera
 ### Scope
 
 Implement (remaining):
-- Primary LLM config resolution.
-- Validation LLM config resolution and inheritance from primary settings.
-- Redaction of credentials in all diagnostics and reports.
-- LLM scheduler/semaphore for bounded backend concurrency.
-- Prompt/response diagnostics writer primitives that can later be used by modules and validators.
+- Runtime wiring for primary/validation effective LLM config resolution.
+- Runtime usage of diagnostics primitives with credential redaction.
 
 Do not implement:
 - Real correction modules.
@@ -249,7 +250,6 @@ The codebase has a tested OpenAI-compatible structured-output client adapter, bu
 ### Definition of done
 
 Remaining checklist to close Phase 9:
-- Scheduler enforces configured concurrency.
 - Primary and validation LLM settings resolve correctly in runtime wiring.
 - Prompt/response diagnostic primitives exist.
 - API keys are not leaked.