diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 2d168cb..7d3d614 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -79,14 +79,17 @@ Sources: [Correctness 1](01-correctness.md#1-provider-source-helpers-silently-ch ## 6. Make Provider-Native Schema Constraints Self-Contained -**Confirmed implementation gap; packaging policy needs selection.** Local +**Confirmed implementation gap; self-contained schemas selected.** Local validation freezes referenced schema resources, but the provider receives only -the root document and cannot resolve its local external references. Select -correct resource packaging, or an explicit local-only fallback policy, without -naively inlining recursive schemas or silently dropping native constraints. -Add a wire-level regression demonstrating a usable provider constraint, not -merely successful local compilation. Entry 21 is a separate compilation -refactor and does not solve this packaging problem. +the root document and cannot resolve its local external references. +[Decision 2](#decision-2-provider-submission-of-multi-resource-schemas) selects +self-contained schema documents and removal of external-resource loading. +Reject references requiring another document during preparation with an +actionable error; retain references within the selected document. Add coverage +for early rejection and for self-contained schemas reaching the provider intact. +Implementation remains pending. Entry 21 is a separate compilation refactor; +coordinate it with this simplification rather than preserving unnecessary +external-resource machinery. Sources: [Correctness 2](01-correctness.md#2-external-schema-resources-do-not-reach-the-provider-constraint), [Testing 5](08-testing.md#5-multi-resource-schema-tests-do-not-establish-a-usable-provider-constraint). @@ -478,6 +481,40 @@ regressions together. Explain the migration for readers that reuse returned storage in release notes as a deliberate pre-1.0 contract correction. This record does not itself implement the change. +### Decision 2: Provider Submission Of Multi-Resource Schemas + +**Related findings:** [6](#6-make-provider-native-schema-constraints-self-contained) +and [21](#21-share-schema-compilation-and-declare-the-runners-real-dependency). + +**Status:** Accepted; implementation pending. + +**Decision:** Require self-contained schema documents. Continue loading the +selected schema from a file and supporting references within that document, +such as `#/$defs/address`. Reject references requiring another document during +preparation with an actionable error. Remove external-resource loading support +and update the owning documentation and tests as a deliberate compatibility +change. Do not introduce a local-only validation mode or implement bundling in +this remediation. + +**Rationale:** OpenRouter's documented structured-output request accepts one +schema object, with no accompanying collection of external schema files. +PromptKit currently supports local validation of resources it cannot faithfully +submit. Requiring a self-contained document resolves that mismatch without +adding a schema transformation subsystem. Provider-specific schema restrictions +still apply; self-containment does not guarantee universal provider acceptance. + +**Alternatives considered:** Bundling could preserve multi-file authoring and +reuse, but its value does not currently justify the machinery needed to preserve +reference semantics. Retain a [schema bundler](../future.md#schema-bundling) as a +possible future enhancement, not approved implementation work. An explicit +local-only mode would preserve external local validation but add a distinct +execution behavior that is not needed for the selected scope. + +**Remediation follow-through:** Cover external-reference rejection and retained +in-document references, including recursion where otherwise supported. Update +schema documentation and release notes, and simplify the shared compilation +work in finding 21 accordingly. This record does not itself implement the change. + ## Open Decisions Work through the remaining decisions below in order, retaining their original @@ -487,34 +524,6 @@ unrelated fixes. In particular, updating the maintainer toolchain need not wait for the consumer-minimum decision. Implementation details and optional cleanup do not become release gates merely by appearing in this catalog. -### Decision 2: Provider Submission Of Multi-Resource Schemas - -**Related findings:** [6](#6-make-provider-native-schema-constraints-self-contained) -and [21](#21-share-schema-compilation-and-declare-the-runners-real-dependency). - -**Question:** How should native structured output represent a schema whose -local validation depends on external resources? - -**Recommendation:** First investigate packaging the operation's captured -resource graph into a self-contained provider constraint. Check identifiers, -relative references, anchors, recursion, and supported dialects before choosing -an encoding. Prefer correct packaging when it fits a proportionate scope, -while keeping resource completeness distinct from any provider's supported -schema subset. A standalone offline validation of the actual emitted constraint -should establish the selected packaging behavior. - -**Alternative:** Offer an explicit local-only validation choice when native -submission cannot represent the resource graph. This preserves useful local -validation and avoids building a general schema transformation system, but -forgoes native generation constraints for that selected mode and needs a clear -consumer-facing selection mechanism. Silently dropping native constraints is -not equivalent to an explicit choice. - -**Resolve before implementation:** Establish packaging feasibility and select -the submission/fallback policy, including behavior for unsupported cases. -Coordinate the compilation refactor with that result; it does not itself fix -provider packaging or establish universal provider acceptance. - ### Decision 3: Authentication Response Budget And Overflow Outcome **Related findings:** [2](#2-bound-authentication-probe-response-consumption) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index dbd008d..138cd28 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -38,8 +38,17 @@ consumers. ## Ideas -No unselected ideas are currently recorded here. Deliberately postponed ideas -remain in the [deferred catalog](deferred.md). +### Schema Bundling + +Allow consumers to author reusable schemas across multiple files and package +them into a single self-contained schema for local validation and provider +submission. This could restore multi-file authoring convenience after the +[self-contained schema decision](audit/catalog.md#decision-2-provider-submission-of-multi-resource-schemas). + +Bundling would need to preserve reference semantics, identifiers, anchors, and +recursion. A complete bundle would not guarantee that a provider supports every +schema feature. This is a possible future enhancement; implementation is not +part of the audit remediation and is not currently approved. ## Entry Format