Settle schema selection and runtime API decisions
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user