Document prompt-owned schemas and finalize migration

This commit is contained in:
2026-11-20 15:46:39 +00:00
parent 9bed36282a
commit e9a12d43c2
16 changed files with 174 additions and 106 deletions

View File

@@ -28,7 +28,7 @@ contributor workflow and validation.
| `internal/profile` | Provides a narrow captured-profile lookup contract and not-found identity. | [Profile lookup](../../internal/profile/repository.go), [framework formats](../formats.md) |
| `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data, and conservatively enumerates dependencies from captured template syntax. | [Go-template renderer](../../internal/prompt/go_renderer.go), [requirement discovery](../../internal/prompt/requirements.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 operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) |
| `internal/validate` | Creates operation-local validation plans from inline schema documents or bound filesystem resources and validates basic, JSON, and JSON Schema output. | [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 bounded response decoding, authentication, deadline handling, per-invocation HTTP evidence and built-in diagnostic probes, and ownership of the OpenAI-compatible reserved request-field policy. | [Internal model client](llm.md) |
| `internal/observation` | Owns invocation-local run IDs, presence-aware usage and phase accounting, synchronous metadata event delivery and composition, and explicit terminal-based group aggregation; smoke diagnostics keep their private evidence outside ordinary observer events. | [Internal execution observation](observation.md) |
| `internal/usecase` | Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair, advances a single conversation branch, and runs explicit smoke diagnostics with private cases, shared generation/capacity, and optional built-in HTTP probes. | [Internal runner](runner.md), [requirement inspection](../../internal/usecase/requirements_inspection.go), [prepared-execution implementation](../../internal/usecase/prepared_execution.go) |

View File

@@ -126,12 +126,12 @@ performs only the work needed to validate routing and admission:
1. validate the required prompt selection and normalize any direct session ID;
2. select the captured prompt definition and hash;
3. select the request profile or the prompt's default profile;
4. retain the profile's selected backend identity, when present;
5. apply explicit request overrides to its captured backend-completed target;
6. validate endpoint, model, numeric overrides, and credential requirements;
7. resolve and validate the effective output contract without loading its
schema; and
3. resolve and validate the effective output contract and select its applicable
bound file without loading its schema;
4. select the request profile or the prompt's default profile;
5. retain the profile's selected backend identity, when present;
6. apply explicit request overrides to its captured backend-completed target;
7. validate endpoint, model, numeric overrides, and credential requirements; and
8. retain the definition, source identities, effective settings, output
contract, and preparation start time in invocation-local state.

View File

@@ -86,7 +86,10 @@ returning and retains no source capability for public inspection.
Prompt materialization shares a lazy metadata snapshot across root and collection
resources during construction, avoiding a full metadata copy per collection.
Input metadata, message content and templates, and output contracts are captured
separately before the definition, inspection, and hash are assembled.
separately before the definition, inspection, and hash are assembled. Schema
root and source-relative file bindings capture the effective field context
without opening schema files; capabilities are excluded from the hash. Inline
schema values and file-reference strings participate in the definition hash.
Normalization and defaults are recorded at individual resolved field paths,
including message roles and cache controls. List indexes identify fields for
@@ -212,18 +215,20 @@ buffer-to-string copy. The
## Schemas And Output Validation
`internal/validate` provides validators backed by an operating-system
filesystem or an `fs.FS`. Invalid generated content is returned as a validation
`internal/validate` prepares a source-neutral input containing an output contract
and an optional bound `fs.FS` file. Invalid generated content is returned as a validation
result; inability to load, register, or compile a schema is an operational
error. Basic validation checks body emptiness on the byte slice directly
instead of first making a response-sized string copy.
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, compiles its declared
access. JSON Schema mode uses the captured inline document or loads the bound
root document once, compiles its declared
schema locations, and retains the compiled root validator. External resources
are rejected without file or network loading; in-document references remain
supported. Root resources use canonical escaped file or private-scheme URLs. The
supported. Bound files use canonical escaped private-scheme URLs; inline values
use a stable private retrieval URL. The
provider-facing structured-output metadata uses the root document captured by
the same plan. Its detached schema document is not revalidated against the
runtime provider-value copier's traversal limits. Smoke inference uses a