base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Record self-contained schema decision and future bundling idea

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-05 04:03:38 +00:00
parent e8e112186e
commit c542b81666
2 changed files with 55 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/roadmap/audit/catalog.md
View File

@@ -79,14 +79,17 @@ Sources: [Correctness 1](01-correctness.md#1-provider-source-helpers-silently-ch
## 6. Make Provider-Native Schema Constraints Self-Contained ## 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 validation freezes referenced schema resources, but the provider receives only
the root document and cannot resolve its local external references. Select the root document and cannot resolve its local external references.
correct resource packaging, or an explicit local-only fallback policy, without [Decision 2](#decision-2-provider-submission-of-multi-resource-schemas) selects
naively inlining recursive schemas or silently dropping native constraints. self-contained schema documents and removal of external-resource loading.
Add a wire-level regression demonstrating a usable provider constraint, not Reject references requiring another document during preparation with an
merely successful local compilation. Entry 21 is a separate compilation actionable error; retain references within the selected document. Add coverage
refactor and does not solve this packaging problem. 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), 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). [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 storage in release notes as a deliberate pre-1.0 contract correction. This
record does not itself implement the change. 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 ## Open Decisions
Work through the remaining decisions below in order, retaining their original 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 for the consumer-minimum decision. Implementation details and optional cleanup
do not become release gates merely by appearing in this catalog. 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 ### Decision 3: Authentication Response Budget And Overflow Outcome
**Related findings:** [2](#2-bound-authentication-probe-response-consumption) **Related findings:** [2](#2-bound-authentication-probe-response-consumption)

13
docs/roadmap/future.md
View File

@@ -38,8 +38,17 @@ consumers.
## Ideas ## Ideas
No unselected ideas are currently recorded here. Deliberately postponed ideas ### Schema Bundling
remain in the [deferred catalog](deferred.md).
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 ## Entry Format