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
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.