# Prompt-Owned Schemas Implementation Plan ## Objective And Authority Implement [prompt-owned-schemas.md](prompt-owned-schemas.md). That feature roadmap owns the accepted selection, composition, scope, ownership, and migration decisions. The [consumer request](prompt-owned-schemas-request.md) is background, not authority for application-specific behavior. Respect [ADR-0001](../adr/0001-configuration-boundary.md): interpret only ConfigKit's final effective configuration and its effective resource context. The baseline is commit `adfccb5`, with ConfigKit v1.3.0 and the prepared message-content hash. This is one end-to-end sprint, divided into sequential single-prompt stages for a Luna coding agent. Intermediate stages may fail to compile. Do not add compatibility shims or duplicate implementations merely to make an intermediate commit coherent. No stage requires human approval, external publication, or a dependency upgrade. Commit completed units under repository policy; commits are not review gates. Start with [development.md](../development.md) and the applicable [agent](../policy/agents.md), [architecture](../policy/architecture.md), [testing](../policy/testing.md), and [documentation](../policy/documentation.md) policies. Read the [format reference](../formats.md), [source/validation internals](../internal/sources.md), and existing GoDoc before changing their contracts. Reuse existing file-path, schema compilation, cancellation, and ownership machinery where applicable. ## Concrete Design For This Sprint ### Public Values And Configuration - Add `Schema any` with `json:"schema,omitempty"` to public `OutputContract`. Nil means no inline selection; a nonnil empty object and `false` are selections. Preserve `SchemaPath string` and its existing JSON field. Do not add runtime `SchemaFile`, filesystem handles, or a standalone schema-loading API. - Add `Schema any` and `SchemaFile *string` to `PromptOutputConfig`, retaining `SchemaPath *string`. `PromptSource` emits `schema` only for a nonnull inline value and emits each nonnil reference pointer. As with existing typed helpers, raw ConfigKit mappings express explicit null and composition controls. - Add `Schema any` and `SchemaFile *string` to `PromptOutputInspection`, with `schema` and `schema_file` JSON/YAML names and `omitempty`. Preserve its existing path presence. Expose configured values/references, not filesystem capabilities or file contents. Generic configuration inspection already exposes declared application and collection roots; no additional public root-inspection API is needed. - Decode optional `schema_root` strings at the application root and collection entries. Absent/null collection roots select the application root; absent/null application roots mean no root. A nonnull blank root is invalid. An explicitly supplied `"."` is valid when accompanied by usable source context. - In JSON Schema mode, exactly one nonnull effective `schema`, `schema_file`, or `schema_path` is required. Reject blank file/path selections and conflicts. Outside that mode, do not resolve, compile, or impose new selection checks on unused schema fields. Retain ordinary ConfigKit decoding semantics. Use native ConfigKit values for captured configuration. For active runtime inline values, use standard JSON encoding and the existing schema JSON decoder to obtain an operation-owned document; do not introduce a custom numeric bridge or the bounded provider-extra copier. JSON null, including typed nil values encoded as null, means no selection. Empty objects and booleans must survive. Unsupported/cyclic Go values that cannot be encoded fail as invalid request values, not panics. JSON-compatible but invalid schema documents fail compilation at preparation through the existing validation-error boundary. Preserve existing file JSON decoding and its numeric behavior; promise no new cross-input numeric equivalence. Clone captured, already-supported trees using the existing trusted document ownership path, without provider-extra depth/node limits. ### Schema-Root Helper Migration Replace the out-of-band root settings with one mapping helper: ```go func SchemaRootSource(label, root string) configkit.Source ``` It returns `configkit.Mapping(label, map[string]any{"schema_root": root})`, without opening files or validating raw contributions. Callers place its input at their chosen native ConfigKit layer and provide a filesystem context, just as they do for `PromptSource`. For example, for an `fs.FS`: ```go filesystem := configkit.NewFilesystem("application", schemaFS) rootInput := configkit.Input{ Source: promptkit.SchemaRootSource("application schemas", "schemas"), Filesystem: &configkit.FilesystemContext{ FS: &filesystem, Root: ".", BaseDir: ".", }, } // Supply rootInput in configkit.Underlay{Inputs: []configkit.Input{rootInput}}, // or use &rootInput as Main when no other main input is needed. ``` Remove `Config.SchemaDir`, `WithSchemaFS`, and `WithSchemaFile`, and the internal option setters/flags used solely by those APIs. This is an intentional pre-1.0 API migration, not a deprecation period. Do not silently translate options into a highest-priority layer or preserve last-option-wins behavior. Callers needing collection-specific roots use ordinary collection mappings with context; the helper need not grow collection-specific parameters. Migration: a directory or filesystem becomes a context-backed root mapping; a former single-file source becomes a `schema_file` on a configured prompt or a root mapping plus its basename in `schema_path`. For an unrelated per-request file, the caller reads/decodes it and supplies `Schema` inline. Host-directory examples use an explicit `os.DirFS`/ConfigKit filesystem context. Do not infer a working-directory root. This preserves the requested directory/filesystem capabilities without preserving a second source-selection system. ### Internal Resource And Preparation Model Separate serializable selections from resource capabilities: - Extend domain output selections with inline `Schema` and the configured `SchemaFile` reference string. The latter is internal, not a new request field. - Capture an optional applicable root and optional source-relative file binding with the prompt definition. Use small source-neutral domain values containing an `fs.FS` and resolved filesystem path. Exclude those capabilities from JSON and definition hashing. Keep the root separate from the output contract so it remains available to a runtime `SchemaPath` replacement. - Configuration binding resolves a field's effective filesystem/base directory using the current effective-origin lookup and `SourceContext`, as `readContent` does. Extract binding from reading so schema capture does not call `Open`, `Stat`, or compile a schema to establish file existence. Apply existing `filecatalog` path containment rules. Missing context/invalid reference metadata is a configuration error; missing or malformed file data is a preparation error. - Add internal `validate.Input` containing `Contract domain.OutputContract` and optional `File` binding. Change `ValidationPreparer.PrepareValidation` to accept this input. Non-schema modes need no file. JSON Schema mode selects the inline document or the one bound file and uses one common compilation pipeline. - After complete request-contract replacement, the runner selects the binding: configured `schema_file` uses its captured binding only without a replacement; `SchemaPath` binds under the selected prompt's applicable root; inline values need no file. A replacement never borrows the configured inline/file selection. A missing root for a runtime path is an invalid request. Existing public error translation remains authoritative. Internal names may follow local conventions, but implement these responsibilities once. Do not carry ConfigKit objects into execution, reread configuration, query history during execution, or serialize filesystem objects. The selected root is not a list to search. Root selection happens before opening the requested file. ## Stage 1 — Add Schema Value Shapes And Ownership Status: complete. Read `types.go`, `prompts.go`, `resource_inspection.go`, `convert.go`, domain output contracts, and the existing schema-document ownership/decoder helpers. 1. Add the public/configuration/inspection fields selected above, corresponding internal fields, and the small resource-binding and validation-input values. Keep selection data separate from the capabilities used to load it. 2. Extend `PromptSource` and output conversions. Preserve false and empty-object presence; do not use truthiness or map length to decide selection. 3. Establish one shared output-selection check for the effective active mode. Separate selection validity from schema compilation. Preserve format and repair-attempt rules. For typed nil runtime inline values, use the standard JSON null result before counting selections. 4. Add operation-owned inline decoding using the existing JSON document path. Reuse trusted cloning after capture/decoding. Avoid an encode/decode round trip at each getter or conversion; ordinary detached getters clone supported trees. 5. Update shallow output-contract/definition copies that now contain mutable schema values. Do not change schema ownership by accidentally routing these values through the provider-extra copier. Tests: extend focused domain selection and typed-source tests for nil/null, `false`, `true`, `{}`, conflicting selections, blank references, and inactive mode behavior. Add a focused runtime inline encoding failure case. Do not run the full suite while downstream signatures are intentionally incomplete. Completion: representations and ownership rules are implemented, with no public runtime filesystem API or truthiness-based loss of schemas. ## Stage 2 — Capture Roots Through Native Configuration Inputs Status: complete. Work in `internal/configuration/load.go`, its normalization/capture helpers, the new root source helper, `engine.go`, and internal engine construction. 1. Add optional roots to decoded application/collection records. Validate only final effective root values and obtain each root's effective source context. Build application and collection root bindings once during construction, using the existing shared metadata snapshot rather than scanning the full resolved tree per prompt. 2. Capture the applicable root with each prompt under the accepted collection scope rule. A declared collection root wins even if a subsequently selected file is missing there. Null clearing restores application-root selection. 3. Implement `SchemaRootSource` and remove the legacy public and internal schema-source configuration paths described above, including the implicit default. Remove now-unused schema-specific defaults/imports, not unrelated artifact-source machinery. 4. Wire the engine toward a source-neutral validator receiving operation inputs, rather than constructing a validator tied to one engine-wide root. Update affected configuration/engine tests and fixtures enough to express the new root inputs; later stages finish preparation integration. Tests: root/collection capture with an explicit mapping context, root override context from another source, null fallback, blank/missing context diagnostics, and native layer precedence for the mapping helper. Use a counting filesystem to demonstrate construction does not inspect schema file existence. Completion: root selection and context come solely from the final ConfigKit configuration. No option-specific precedence or implicit root remains. ## Stage 3 — Capture Prompt-Owned Schema Selections And References Status: complete. Work in `internal/configuration/prompts.go`, resource projections, normalization, and prompt-definition snapshots/hashing. 1. Extend output capture for all three fields. Validate exactly one effective active selection, using ConfigKit's existing presence/null data when needed. Do not reject overwritten contributions or reconstruct native composition. 2. Extract a reusable effective-field resource binder from `readContent`. Preserve message-file read/close behavior; schema-file capture uses binding only. Inherited references use their contributing field's context, not the child's source. Root and file binding use existing path/context rules. 3. For configured active `schema_path`, require an applicable root and validate path metadata without opening the file. Bind active `schema_file` from that field's context. Inline selections need neither binding nor root. 4. Extend `PromptOutputResource`, `InspectPrompt`, and public projections to include selected values/references without opening files. Keep detached schema trees in public results and preserve existing inspection presence rules. 5. Include configured inline values and file-reference strings in the existing definition-hash input; exclude resource capabilities. Use the existing hash algorithm, not a new digest API or file-content read. Root context and schema file bytes are not newly promised hash inputs. Leave both prepared-message hash algorithms and their semantics unchanged. Tests: imports/inheritance and overrides preserve effective field context; composition can merge inline mappings and explicitly clear alternatives; same basenames in different filesystems stay distinct; inactive schema fields do not trigger resource binding. Inspect a prompt with a missing schema file successfully, then leave actual file failure for preparation. Completion: final selections, source bindings, inspection, and definition snapshots agree without eager schema I/O or a second composition pass. ## Stage 4 — Unify Inline And File Schema Preparation Work in `internal/validate/validator.go` and the current validator implementation. 1. Adapt the preparer to `validate.Input`. Replace duplicated engine-root-specific preparation routes with a source-neutral validator. Migrate internal validator tests to bound files/inline documents; retain useful path/decoder tests at their owning helper rather than keeping obsolete constructors just for tests. 2. Load a selected file once through the bound filesystem and existing context-checked chunk reader. Preserve read/close error handling and the single-complete-JSON-document decoder. Inline values use their captured or operation-owned document without a file read. 3. Feed both routes through the existing dialect, self-contained-resource, schema-location, and root compilation checks. Retain supported IDs, anchors, internal references, filename independence, and external-resource rejection. Keep existing canonical escaped retrieval URLs for file sources; use a stable private absolute retrieval URL for inline documents, without new public IDs. 4. Store the selected document and compiled root in the existing prepared plan. `SchemaDocument()` returning `false` is a document, not missing metadata. Use the same value for local checks and provider constraints. 5. Preserve synchronous cancellation checks around reads, decoding, compilation, and validation. No background dependency workers or new cache is needed. Tests: object and boolean schemas work by both routes; equivalent documents give equivalent validation; invalid schema documents/dialects, external refs, valid internal refs, exact file JSON numbers, and cancellation retain their existing classifications. Reuse focused tests rather than duplicating the entire schema suite for every route. Completion: one source-neutral preparation/compilation path produces the existing operation-local plan with no extra resource reads for `$ref` resolution. ## Stage 5 — Bind Effective Contracts In Every Execution Path Work in `internal/usecase/runner.go`, prepared execution, engine wiring, and `smoke_inference_case.go`. 1. Resolve the complete effective output contract first, then its file binding. Retain surrounding root scope for runtime `SchemaPath`; discard configured `schema_file` binding and configured inline value on a request replacement. Store the selected input in preparation state and pass it to the preparer. 2. Keep malformed selection/root requirements within existing invalid-config construction or invalid-request runtime boundaries. Read/decode/compile failures remain operational validation errors before generation. Include selected prompt/reference context while preserving error identities and cancellation precedence. 3. Keep `Prepare`, `ValidateRequest`, `Run`, and `PrepareExecution` on the shared preparation path. `RunPrepared` retains/reuses the plan and needs no schema binding, file read, or compilation at execution time. Preserve callback, operation-budget, admission, and continuation behavior. 4. Preserve prompt-ID-based structured-output naming and the existing provider submission path. Repair reuses the same plan/document; it does not reselect schema forms or roots. Do not invent provider-support assertions. 5. Migrate private smoke-schema setup to an explicit bound private resource and the same preparer, independent of application schema roots. Update internal fake preparers to the new signature; preserve the intentional nil-validator behavior of focused use-case tests. Tests: runtime inline/path replacement, no borrowed configured selection, missing runtime root, and collection-root selection during replacement. Existing ordinary/prepared, validation-only, continuation, and smoke tests should compile and exercise the common pipeline. Verify preparation failures do not call a model. Completion: all execution entry points select and retain exactly the intended schema plan, without an out-of-band engine schema root. ## Stage 6 — Verify Public Projections And Ownership Finish public facade conversion and serialization changes in `convert.go`, `types.go`, `resource_inspection.go`, `json.go`, and prepared notification paths. 1. Extend existing JSON/YAML contract tests for inline `false`, `{}`, absence, inspection references, and backward decoding of values omitting new fields. The prepared JSON projection already inherits public struct fields; avoid a second serialization DTO. Preserve ordinary manual-value JSON behavior rather than introducing schema compilation on JSON decode. 2. Test that mutating typed input after its source snapshot, inspection results, `Prepare` results, `Details`, `OnPrepared`, or injected-client schema metadata cannot alter captured configuration or retained execution. Extend existing ownership fixtures rather than duplicating every handle lifecycle test. 3. Keep configured file-reference inspection separate from the schema document shown in prepared `StructuredOutput`. Public runtime `OutputContract` has no `SchemaFile`; do not fabricate an inline selection or path merely to fill that projection. The prepared structured-output document is the selected content. `ValidationResult.SchemaPath` keeps its explicit-root path meaning and is empty for the new inline/source-relative forms; no synthetic sentinel path or new result field is needed. 4. Check every remaining shallow output-contract copy now containing `Schema`. Trusted internal sharing stays immutable; public copies detach mutable trees. Do not marshal filesystem bindings, or recompile schemas in inspection/getters. Tests: focused typed-source, resource-inspection, prepared/notification, and JSON contract packages. Retain schema-document tests that exceed provider-extra copy limits; new inline handling must not route trusted documents through those limits. Completion: all exposed values are faithful and caller-owned where the existing API requires it, with no resource capability leakage or extra schema work. ## Stage 7 — Verify Mixed Collections And Captured Lifecycles Add focused external-package integration coverage using real ConfigKit composition and injected provider/transport boundaries. Prefer a small fixture with distinct risks over a Cartesian product of settings. 1. Build one engine with independent collection roots, application-root fallback, source-relative schemas, and inline schemas together. Mix embedded-like and operator filesystem contexts, with identical schema basenames. Replace one prompt/schema selection while unrelated prompts remain usable. 2. Cover inherited source context and overridden context through actual imports or layers, including a root inherited from a different source than its prompt. Exercise explicit null when switching forms and ConfigKit's native whole-value replacement control. No custom overlay behavior belongs in expected results. 3. Confirm missing files under the chosen root fail without another root search. Missing/malformed schema files permit engine construction but fail preparation; missing selection/context/root metadata fails at its configured boundary. 4. Capture a prepared execution, then modify/remove its schema source. The handle executes and repairs against its captured plan; a later ordinary preparation observes the changed source. Count reads to protect capture behavior, not incidental compiler-internal call counts. 5. Confirm equivalent forms submit the selected document to an offline recording client and validate generated results with those same constraints. Include a boolean-schema case. Preserve transport error behavior rather than testing assumptions about live provider support. Completion: the mixed Scriptorium/Notarius layout and prepared-plan lifecycle are covered end to end without application-managed mounts or live infrastructure. ## Stage 8 — Migrate Documentation And Validate The Assembled Sprint 1. Update GoDoc and [formats.md](../formats.md) for selection/null/composition, source context, root scope, inactive modes, preparation failures, and removed implicit root. Update the [consumer guide](../consumers/pkg-promptkit.md) with runtime inline replacement and context-backed root/helper migration examples. Keep exact API declarations in GoDoc and configuration rules in the format reference; link rather than repeat them everywhere. 2. Update [sources.md](../internal/sources.md), [runner.md](../internal/runner.md), and the internal overview where responsibilities changed. Adapt maintained examples/fixtures referencing removed schema options to inline, source-relative, or explicit context-backed roots as appropriate. Keep one representative maintained mixed-source example rather than adding an application asset assembly tutorial. 3. Make the canonical migration documentation cover positional public struct literals, removed schema options/field, and the absence of an implicit root. Release preparation will select the version and summarize these changes in its release note under the release policy. This sprint selects no release number and does not rewrite published notes or require a publication check. 4. Audit the complete diff against the feature roadmap. Remove old schema-source wiring, obsolete helper-only tests/defaults, and stale current-state references. Historical published notes and the original request are not current API owners. Do not remove unrelated path/artifact machinery or change dependency versions or the Go consumer minimum for this feature. 5. Follow the development guide's newest locally installed Go selection with `GOTOOLCHAIN=local` and `GOWORK=off`. Format changed Go files; run `go test -race ./...`, `go vet ./...`, and `git diff --check`. The complete suite includes maintained examples; no repeated example gate or benchmark run is required. Check changed local documentation links. Fix failures using focused reruns and validate the final assembled changes proportionately. Completion: all stages' behavior and tests are implemented, documentation describes the new configuration/API migration, and assembled validation succeeds. Do not tag, push, publish dependencies, or require external consumer updates to finish this sprint. Retire completed roadmaps during normal release preparation. ## Open Questions None. The three product decisions are accepted in the feature roadmap; this plan selects the remaining API, helper migration, and preparation plumbing details.