Escape schema resources and reuse compiled plans

docs/internal/overview.md

@@ -25,9 +25,9 @@ contributor workflow and validation.
 | `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select OpenRouter. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) |
 | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) |
 | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
-| `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates frozen validation plans for prepared execution. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
+| `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
 | `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including response decoding, authentication, deadline handling, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
-| `internal/usecase` | Resolves prompt definitions and hashes, profiles, backends, and targets for exact inspection and request settings for preparation, and coordinates ordinary execution and one-attempt prepared execution across internal sources, rendering, artifact loading, generation, validation, capacity, and optional repair. | [Internal runner](runner.md), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
+| `internal/usecase` | Resolves prompt definitions and hashes, profiles, backends, and targets for exact inspection and request settings for preparation, and coordinates ordinary execution and one-attempt prepared execution across internal sources, rendering, artifact loading, operation-local validation plans, generation, capacity, and optional repair. | [Internal runner](runner.md), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |
 
 The root package assembles these internal components without exposing their
 representations. Consumers depend only on the root facade.

docs/internal/runner.md

@@ -20,8 +20,9 @@ and override semantics consumed by the runner.
 profiles, backend resolution, artifacts, rendering, model generation, and
 validation. The root engine supplies one immutable registry containing the
 built-in backend and validated consumer additions, one engine-local run
-admitter, and a model client wrapped by the same capacity manager. Schema
-documents are loaded through the validator's optional schema-loader interface.
+admitter, and a model client wrapped by the same capacity manager. Validation
+plans and provider-facing schema metadata come from the validator's preparation
+interface.
 An output repairer can be injected internally, but the ordinary runner
 constructor does not enable one.
 
@@ -77,7 +78,8 @@ performs only the work needed to validate routing and admission:
 The completion phase consumes that state without reloading the prompt,
 profile, or backend:
 
-1. load structured-output schema metadata when required;
+1. create one operation-local validation plan and derive structured-output
+   schema metadata from it when required;
 2. load and hash input artifacts;
 3. render messages and the prompt-defined session;
 4. apply any direct session ID;
@@ -88,7 +90,10 @@ profile, or backend:
 `Run` performs backend admission between the phases. This structure preserves
 one execution-precedence and error-ordering implementation while allowing a
 full backend pool to reject work before expensive schema, artifact, and
-rendering operations.
+rendering operations. `Prepare` discards the plan after returning its public
+metadata. `Run` retains the plan through initial and repaired-output validation
+and discards it when the operation ends. Prepared execution stores the same
+kind of plan only in its private payload.
 
 Pointer-based numeric overrides preserve an explicit zero. Invalid negative or
 out-of-range values fail as invalid requests. Endpoint overrides do not change
@@ -119,8 +124,9 @@ its `RunAdmitter` to reserve capacity for the effective backend ID. A nil
 admitter is an internal unlimited fallback. After successful admission, `Run`
 immediately defers the returned release function, performs the completion
 phase, makes one initial generation call, builds the named output artifact,
-and validates that artifact. Invalid generated content remains a validation
-result; an inability to perform validation is an operational error.
+and validates that artifact with the plan compiled during completion. Invalid
+generated content remains a validation result; an inability to perform
+validation is an operational error.
 
 The admission lease covers completion-phase preparation, initial generation,
 validation, every repair, and every exit. It bounds accepted work without
@@ -134,8 +140,8 @@ target and session ID, validation errors, prior output, and structured-output
 specification. The default repairer uses the same wrapped client as initial
 generation, so each repair reacquires the selected backend's active permit
 while remaining inside its original admission lease. Repair never performs a
-second bounded admission. This capability remains internal and is not a public
-option.
+second bounded admission, and repaired outputs use the operation's existing
+validation plan. This capability remains internal and is not a public option.
 
 A successful result includes the output artifact and raw output, validation
 state, effective session ID, prompt and rendered-prompt hashes, selected

docs/internal/sources.md

@@ -121,19 +121,21 @@ filesystem or an `fs.FS`. Invalid generated content is returned as a validation
 result; inability to load, register, or compile a schema is an operational
 error.
 
-For executable preparation, the built-in validators create a frozen validation
-plan. None, basic, and JSON modes retain the effective output contract without
-source access. JSON Schema mode loads the root document, resolves and compiles
-every transitive reference during preparation, and retains the compiled
-validator. The provider-facing structured-output metadata uses that same
-captured root document.
+Every preparation operation creates one operation-local validation plan. None,
+basic, and JSON modes retain the effective output contract without source
+access. JSON Schema mode loads the root document once, resolves and compiles
+each transitive reference, and retains the compiled validator. Schema compiler
+resources use canonical escaped file or private-scheme URLs; loaders decode
+their paths once and enforce the configured source boundary. The
+provider-facing structured-output metadata uses the root document captured by
+the same plan.
 
-`PrepareExecution` also completes prompt and profile selection, artifact
-loading and hashing, session and message rendering, and target resolution.
-`RunPrepared` uses the retained source-derived state and validation plan; it
-does not reopen prompt, profile, input, or schema sources and does not rerender
-the request. By contrast, ordinary `Prepare` produces a preparation value only:
-a later `Run` performs its own source resolution and preparation.
+`Prepare` discards its validation plan after returning metadata. `Run` retains
+its plan for initial and repaired-output validation, then discards it with the
+operation. `PrepareExecution` retains the plan in its private frozen payload;
+`RunPrepared` uses that plan without reopening prompt, profile, input, or
+schema sources or rerendering the request. A later ordinary `Run` always
+performs fresh source resolution and preparation.
 
 The [validator tests](../../internal/validate/standard_validator_test.go) own
 basic, JSON, JSON Schema, source resolution, schema loading, compilation,