diff --git a/docs/roadmap/prompt-owned-schemas.md b/docs/roadmap/prompt-owned-schemas.md index 108636c..60de0e9 100644 --- a/docs/roadmap/prompt-owned-schemas.md +++ b/docs/roadmap/prompt-owned-schemas.md @@ -1,7 +1,7 @@ # Prompt-Owned Inline And Source-Relative Schemas -Status: proposed target and implementation roadmap. Decision 1 is accepted; -Decisions 2 and 3 remain open. Examples describe target, not implemented, syntax. +Status: accepted design decisions and implementation roadmap. All three decisions +are settled. Examples describe target, not implemented, syntax. This document authorizes no code changes and selects no release number. ## Purpose And Boundary @@ -17,6 +17,11 @@ schema namespace. PromptKit owns reusable resource resolution and structural validation; Notarius retains content interpretation, domain validation, and artifact handling. +Scriptorium represents the primary workflow: one engine loads multiple collections, +some with their own schema roots and others with source-relative or inline schemas. +Supporting these layouts together is a first-class requirement. Runtime schema +substitution is uncommon; modest caller-side work is acceptable for that case. + Follow the [ConfigKit handoff boundary](../adr/0001-configuration-boundary.md). ConfigKit owns imports, inheritance, composition, and effective field context. PromptKit interprets the final result. Neither the configuration adapter nor the @@ -64,7 +69,7 @@ The accepted configuration forms are: Inline and source-relative forms are the new capability. The explicit-root route remains available, with optional collection-specific roots and an application-wide -default. Decisions 2 and 3 below settle selection and API details. There is no +default. Decisions 2 and 3 below record selection and API semantics. There is no multi-root fallback search or implicit working-directory root. Illustrative inline output fragment: @@ -153,8 +158,13 @@ security model, automatic mounts, or schema search paths. A source-relative reference without a usable context needs a diagnostic identifying the field and prompt, rather than an inferred working directory. -Inline values participate in native ConfigKit composition. Interpret selection, -null clearing, and conflicts from the final effective values under Decision 2. +Inline values participate in native ConfigKit composition. In JSON Schema mode, +require exactly one nonnull selection among `schema`, `schema_file`, and +`schema_path` after composition. Null clears a selection; `{}` and `false` are +schema values. Blank file references are invalid. Ignore schema selections outside +JSON Schema mode, preserving the existing behavior for paths. Switching forms may +require explicitly clearing an inherited alternative; no field takes precedence +over another. Whole-schema replacement uses ConfigKit's existing controls. No PromptKit pass repairs or replays configuration composition. A source-neutral runtime representation may retain the filesystem capability and resolved resource reference needed for preparation; runtime components need not depend on ConfigKit @@ -187,10 +197,18 @@ problem. Avoid promising diagnostics for nonexistent partial validation plans. ### Public API And Inspection -Keep complete request-level output-contract replacement. A replacement must not -retain the prompt's schema selection or resource context implicitly. The -recommended programmatic forms are inline values and the existing explicit-root -path; Decision 3 addresses source-relative runtime files. +Keep complete request-level output-contract replacement, with no additional +configuration merge. A replacement must not retain the prompt's schema selection +or the source context of its `schema_file` field implicitly. Support inline values +and `SchemaPath` in runtime contracts. Runtime `SchemaPath` uses the selected +prompt's applicable collection/application root under Decision 1: replacing the +output contract does not erase the surrounding collection configuration. + +Keep `schema_file` in configuration, where ConfigKit supplies effective source +context, including for typed configuration sources. Do not add a runtime +filesystem-reference API in this work. A caller needing an unrelated schema file +can read and decode it, then supply its value inline. This prioritizes configured +collection workflows without requiring extra runtime source machinery. Extend typed prompt configuration helpers, public output contracts, conversions, and inspection consistently. Inline values and exposed details must follow @@ -224,10 +242,10 @@ and new provider-specific dialects are outside this work. ## Work From The Baseline -1. **Settle configuration and API selection.** Resolve the decisions below and - sketch YAML, typed prompt sources, and request-level overrides. Specify - absence/null, empty values, inactive validation modes, and representation of - inline values without changing ConfigKit's composition rules. +1. **Specify concrete API shapes.** Translate the accepted decisions into YAML, + typed prompt sources, and request-level overrides. Define the Go representation + of inline values, preserving absence, empty objects, and boolean schemas. + Specify helper migration without changing ConfigKit's composition rules. 2. **Capture schema ownership.** Extend configuration decoding, normalization, domain selection, and inspection. Share the existing effective-field resource resolution mechanics where useful, but separate resource binding from file @@ -263,6 +281,8 @@ existing injected-client or transport seams. same local constraints and provider schema value through ordinary preparation. - Embedded/operator prompts coexist with identical schema basenames; replacing one prompt leaves unrelated schema selections usable. +- One engine loads collections using independent roots, source-relative files, + and inline schemas together, without caller-managed mounts or file copying. - Imports and inheritance retain effective field context; overrides change it. Resolution is independent of process working directory and observes existing root/context rules. @@ -273,9 +293,11 @@ existing injected-client or transport seams. no root, and `schema_path` without an applicable root fails clearly. - Native inline composition, null clearing, conflicting forms, empty objects, boolean schemas, and malformed selections follow the chosen contract. -- Request replacement does not borrow the prompt's schema or context. Explicit - schema source helpers follow the accepted composition model and documented - migration, without a special Go-option precedence rule. +- Request replacement does not borrow the prompt's schema selection or + `schema_file` context. Runtime `SchemaPath` uses the applicable configured + collection/application root; inline replacements require no root. Explicit + schema source helpers follow native composition and documented migration, + without a special Go-option precedence rule. - Missing/invalid files fail at preparation, not eager engine construction; prepared execution survives later source modification/removal. Inline input and returned-detail mutation do not alter retained execution state. @@ -288,7 +310,7 @@ existing injected-client or transport seams. continue using the common plan without duplicating schema loading or compilation beyond existing self-contained checks. -## Decisions And Remaining Questions +## Accepted Decisions ### 1. How Should New File References Coexist With `schema_path`? @@ -310,14 +332,12 @@ root changes do not reinterpret `schema_path` as a source-relative file. ### 2. How Should Selection, Composition, And Clearing Work? -**Status: open.** - -**Recommendation:** in JSON Schema mode, require exactly one nonnull effective +**Accepted:** in JSON Schema mode, require exactly one nonnull effective selection among the three forms. Null clears a selection; `{}` and `false` remain schema values, not absence. Blank file/path selections are invalid rather than -fallback instructions. Preserve existing inactive-mode behavior for legacy paths -and apply a consistent rule to new forms rather than introducing unrelated -restrictions on unused fields. +fallback instructions. Ignore schema selections outside JSON Schema mode, +preserving existing inactive-mode behavior for paths without introducing +unrelated restrictions on unused fields. Inline mappings compose according to ConfigKit. Switching forms may require explicitly clearing the inherited alternative, for example `schema_file: null` @@ -326,28 +346,39 @@ controls; PromptKit does not invent its own replacement pass. This is predictabl from final configuration and aligns with the existing message-content selection pattern, though it requires an explicit clear when switching inherited forms. -**Alternative:** define fixed precedence, such as inline over source-relative +**Alternative considered:** define fixed precedence, such as inline over source-relative file over legacy path. This also works on final effective values and makes a higher-priority form convenient without clearing another field. It can silently leave stale alternatives that reappear when the preferred form is cleared, and makes the effective configuration less obvious to operators. Explicit conflict -errors are preferable unless consumers demonstrate substantial value in fallback. +errors were selected to avoid a PromptKit-specific precedence rule. ### 3. How Much Source Selection Should Programmatic Requests Expose? -**Status: open.** - -**Recommendation:** support inline values and existing `SchemaPath` in request +**Accepted:** support inline values and `SchemaPath` in request contracts; keep source-relative `schema_file` tied to configuration inputs with resource context. Typed configuration sources can supply that context through ConfigKit just as they do for message files. Request replacement is complete and -never borrows the prompt's source implicitly. This meets the consumer request -without making each runtime output contract a filesystem configuration API. +never borrows the prompt's `schema_file` context implicitly. Runtime `SchemaPath` +uses the applicable configured root under Decision 1. Collection root selection +is surrounding configuration, not inheritance from the replaced output contract. -**Alternative:** also let runtime contracts supply an explicit filesystem/base -context with a schema file reference. That supports per-request schemas from -several filesystems without an engine-wide root or caller preloading. It adds -source ownership, detachment, and serialization questions to the public runtime -API. It is viable for a demonstrated runtime-source use case, but not necessary -for prompt-owned collections or inline programmatic schemas. Neither approach -needs an implicit working-directory or multi-root lookup. +Mixed collection layouts are the common case and must work together in one +engine. Runtime substitution can use inline values or the applicable configured +root. For an unrelated runtime file, the caller reads and decodes the schema and +supplies the inline value. The small application burden for this uncommon case +does not justify a new runtime filesystem-reference API in this roadmap. + +**Alternative deferred:** let runtime contracts supply an explicit filesystem +and file reference. This could help per-job or tenant-specific schemas and +runtime-selected bundles by reusing PromptKit's reading, decoding, diagnostics, +and preparation lifecycle. It adds a public resource type and ownership/lifetime +semantics. Revisit only for a concrete consumer need; configured collections do +not require it. Neither approach needs implicit working-directory lookup. + +## Remaining Planning Work + +No product decisions remain open among Decisions 1–3. Implementation planning +still needs concrete public Go shapes and the adaptation/migration of existing +schema-source helpers within the accepted ConfigKit composition model. These +details must preserve the accepted scope and selection rules.