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
**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)