Settle schema selection and runtime API decisions

This commit is contained in:
2026-11-20 14:19:34 +00:00
parent 0603a4f0dd
commit adfccb5370

View File

@@ -1,7 +1,7 @@
# Prompt-Owned Inline And Source-Relative Schemas # Prompt-Owned Inline And Source-Relative Schemas
Status: proposed target and implementation roadmap. Decision 1 is accepted; Status: accepted design decisions and implementation roadmap. All three decisions
Decisions 2 and 3 remain open. Examples describe target, not implemented, syntax. are settled. Examples describe target, not implemented, syntax.
This document authorizes no code changes and selects no release number. This document authorizes no code changes and selects no release number.
## Purpose And Boundary ## Purpose And Boundary
@@ -17,6 +17,11 @@ schema namespace. PromptKit owns reusable resource resolution and structural
validation; Notarius retains content interpretation, domain validation, and validation; Notarius retains content interpretation, domain validation, and
artifact handling. 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). Follow the [ConfigKit handoff boundary](../adr/0001-configuration-boundary.md).
ConfigKit owns imports, inheritance, composition, and effective field context. ConfigKit owns imports, inheritance, composition, and effective field context.
PromptKit interprets the final result. Neither the configuration adapter nor the 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 Inline and source-relative forms are the new capability. The explicit-root route
remains available, with optional collection-specific roots and an application-wide 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. multi-root fallback search or implicit working-directory root.
Illustrative inline output fragment: 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 reference without a usable context needs a diagnostic identifying the field and
prompt, rather than an inferred working directory. prompt, rather than an inferred working directory.
Inline values participate in native ConfigKit composition. Interpret selection, Inline values participate in native ConfigKit composition. In JSON Schema mode,
null clearing, and conflicts from the final effective values under Decision 2. 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 No PromptKit pass repairs or replays configuration composition. A source-neutral
runtime representation may retain the filesystem capability and resolved resource runtime representation may retain the filesystem capability and resolved resource
reference needed for preparation; runtime components need not depend on ConfigKit 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 ### Public API And Inspection
Keep complete request-level output-contract replacement. A replacement must not Keep complete request-level output-contract replacement, with no additional
retain the prompt's schema selection or resource context implicitly. The configuration merge. A replacement must not retain the prompt's schema selection
recommended programmatic forms are inline values and the existing explicit-root or the source context of its `schema_file` field implicitly. Support inline values
path; Decision 3 addresses source-relative runtime files. 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, Extend typed prompt configuration helpers, public output contracts, conversions,
and inspection consistently. Inline values and exposed details must follow 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 ## Work From The Baseline
1. **Settle configuration and API selection.** Resolve the decisions below and 1. **Specify concrete API shapes.** Translate the accepted decisions into YAML,
sketch YAML, typed prompt sources, and request-level overrides. Specify typed prompt sources, and request-level overrides. Define the Go representation
absence/null, empty values, inactive validation modes, and representation of of inline values, preserving absence, empty objects, and boolean schemas.
inline values without changing ConfigKit's composition rules. Specify helper migration without changing ConfigKit's composition rules.
2. **Capture schema ownership.** Extend configuration decoding, normalization, 2. **Capture schema ownership.** Extend configuration decoding, normalization,
domain selection, and inspection. Share the existing effective-field resource domain selection, and inspection. Share the existing effective-field resource
resolution mechanics where useful, but separate resource binding from file 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. same local constraints and provider schema value through ordinary preparation.
- Embedded/operator prompts coexist with identical schema basenames; replacing - Embedded/operator prompts coexist with identical schema basenames; replacing
one prompt leaves unrelated schema selections usable. 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. - Imports and inheritance retain effective field context; overrides change it.
Resolution is independent of process working directory and observes existing Resolution is independent of process working directory and observes existing
root/context rules. root/context rules.
@@ -273,9 +293,11 @@ existing injected-client or transport seams.
no root, and `schema_path` without an applicable root fails clearly. no root, and `schema_path` without an applicable root fails clearly.
- Native inline composition, null clearing, conflicting forms, empty objects, - Native inline composition, null clearing, conflicting forms, empty objects,
boolean schemas, and malformed selections follow the chosen contract. boolean schemas, and malformed selections follow the chosen contract.
- Request replacement does not borrow the prompt's schema or context. Explicit - Request replacement does not borrow the prompt's schema selection or
schema source helpers follow the accepted composition model and documented `schema_file` context. Runtime `SchemaPath` uses the applicable configured
migration, without a special Go-option precedence rule. 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; - Missing/invalid files fail at preparation, not eager engine construction;
prepared execution survives later source modification/removal. Inline input prepared execution survives later source modification/removal. Inline input
and returned-detail mutation do not alter retained execution state. 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 continue using the common plan without duplicating schema loading or compilation
beyond existing self-contained checks. beyond existing self-contained checks.
## Decisions And Remaining Questions ## Accepted Decisions
### 1. How Should New File References Coexist With `schema_path`? ### 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? ### 2. How Should Selection, Composition, And Clearing Work?
**Status: open.** **Accepted:** in JSON Schema mode, require exactly one nonnull effective
**Recommendation:** in JSON Schema mode, require exactly one nonnull effective
selection among the three forms. Null clears a selection; `{}` and `false` remain selection among the three forms. Null clears a selection; `{}` and `false` remain
schema values, not absence. Blank file/path selections are invalid rather than schema values, not absence. Blank file/path selections are invalid rather than
fallback instructions. Preserve existing inactive-mode behavior for legacy paths fallback instructions. Ignore schema selections outside JSON Schema mode,
and apply a consistent rule to new forms rather than introducing unrelated preserving existing inactive-mode behavior for paths without introducing
restrictions on unused fields. unrelated restrictions on unused fields.
Inline mappings compose according to ConfigKit. Switching forms may require Inline mappings compose according to ConfigKit. Switching forms may require
explicitly clearing the inherited alternative, for example `schema_file: null` 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 from final configuration and aligns with the existing message-content selection
pattern, though it requires an explicit clear when switching inherited forms. 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 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 higher-priority form convenient without clearing another field. It can silently
leave stale alternatives that reappear when the preferred form is cleared, and leave stale alternatives that reappear when the preferred form is cleared, and
makes the effective configuration less obvious to operators. Explicit conflict 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? ### 3. How Much Source Selection Should Programmatic Requests Expose?
**Status: open.** **Accepted:** support inline values and `SchemaPath` in request
**Recommendation:** support inline values and existing `SchemaPath` in request
contracts; keep source-relative `schema_file` tied to configuration inputs with contracts; keep source-relative `schema_file` tied to configuration inputs with
resource context. Typed configuration sources can supply that context through resource context. Typed configuration sources can supply that context through
ConfigKit just as they do for message files. Request replacement is complete and 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 never borrows the prompt's `schema_file` context implicitly. Runtime `SchemaPath`
without making each runtime output contract a filesystem configuration API. 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 Mixed collection layouts are the common case and must work together in one
context with a schema file reference. That supports per-request schemas from engine. Runtime substitution can use inline values or the applicable configured
several filesystems without an engine-wide root or caller preloading. It adds root. For an unrelated runtime file, the caller reads and decodes the schema and
source ownership, detachment, and serialization questions to the public runtime supplies the inline value. The small application burden for this uncommon case
API. It is viable for a demonstrated runtime-source use case, but not necessary does not justify a new runtime filesystem-reference API in this roadmap.
for prompt-owned collections or inline programmatic schemas. Neither approach
needs an implicit working-directory or multi-root lookup. **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.