Record the HTTP API cutover decision

This commit is contained in:
2026-11-18 15:11:58 +00:00
parent 87d7240f31
commit 95a94249f1

View File

@@ -5,8 +5,10 @@
Accepted direction; not yet implemented. Upgrade the existing Scriptorium
product in one native cutover. Use the released PromptKit and ConfigKit APIs
for framework and configuration mechanisms that they already own. Provide
migration guidance, not a second application schema, a legacy definition
reader, or compatibility aliases.
migration guidance for configuration, definitions, and CLI usage, not a
second application schema, a legacy definition reader, or compatibility
aliases. Refactor the early-beta HTTP API directly, without an HTTP migration
or backward-compatibility requirement.
The [definition boundary](../adr/0004-definition-boundary.md) and
[configuration boundary](../adr/0005-configkit-boundary.md) remain in effect.
@@ -78,8 +80,7 @@ Execution, rendering, and prompt inspection select a prompt by exact ID,
including a qualified collection ID where appropriate. Remove the CLI
version selector and the corresponding version members from the CLI and HTTP
request, response, inspection, and report contracts where they exist. Do not
accept a legacy version selector and then ignore it. The HTTP route decision
below determines where the single new HTTP contract is served.
accept a legacy version selector and then ignore it.
Continue to distinguish framework configuration, resolved resources, and
request preparation. Framework configuration inspection reports the
@@ -96,13 +97,25 @@ to existing prompt inspection output.
PromptKit owns preparation, provider calls, retries, capacity, validation,
and repair. Preserve the configured shared server engine and established
backend admission behavior. Use PromptKit's native operation timeout for the
existing whole-run budget where it can preserve the current execution
boundary and error mapping. A provider-attempt timeout is still distinct
from the whole-run deadline; caller cancellation still applies. Keep the
existing context wrapper if delegation would change those semantics rather
than introducing two independent timers. CLI process behavior, HTTP
decoding, limits, restricted artifact loading, safe diagnostics, and
application-owned execution reports remain adapter responsibilities.
existing whole-run budget where it can preserve the execution boundary and
support the intended CLI and HTTP outcomes. A provider-attempt timeout is
still distinct from the whole-run deadline; caller cancellation still
applies. Keep the existing context wrapper if delegation would change those
semantics rather than introducing two independent timers. CLI process
behavior, HTTP decoding, limits, restricted artifact loading, safe
diagnostics, and application-owned execution reports remain adapter
responsibilities.
### HTTP Contract
Serve one ID-only HTTP execution contract. Choose the route, request and
response shapes, and status mapping that best fit the single-run model.
There is no need to preserve `POST /v1/runs` or to introduce a successor
route solely to signal incompatibility. No HTTP compatibility routes,
legacy payload adapters, or client migration procedures are needed.
Retain operational boundaries such as configured size limits, restricted
artifact access, credential handling, and shared backend admission; these
serve the application independently of wire compatibility.
## Work Needed From The Baseline
@@ -134,17 +147,20 @@ application-owned execution reports remain adapter responsibilities.
overrides and optional-value presence. Check that the restricted HTTP
artifact reader transfers ownership of returned artifacts and bytes under
the new public contract without changing Scriptorium's containment policy.
Preserve the established execution outcome, size-limit, cancellation, and
credential-disclosure behavior outside the intentional cutover changes.
Preserve established CLI outcomes outside the intentional cutover changes.
Validate the HTTP adapter against its new contract and the application
boundaries above, not against old wire shapes.
- **Give operators a migration path in documentation.** Update the
[consumer migration guide](../consumers/upgrading-promptkit.md) with
before-and-after application and framework examples, directions for old
prompt versions and catalog references, and the changed CLI and HTTP
contracts. Explain semantic changes that can survive a syntactic
conversion, particularly replacement, null fallback, and schema
resolution. Update the canonical configuration, CLI, HTTP, subprocess, and
internal references where their implementation changes. Refresh current
contributor and architecture references to the selected upstream release,
prompt versions and catalog references, and the changed CLI contract.
Explain semantic changes that can survive a syntactic conversion,
particularly replacement, null fallback, and schema
resolution. Document the new HTTP contract directly in the
[API reference](../api.md) and update its maintained examples. Update the
canonical configuration, CLI, subprocess, and internal references where
their implementation changes. Refresh current contributor and
architecture references to the selected upstream release,
leaving historical release records intact. Record release impact as
an intentional incompatible change under the
[release policy](../policy/release.md#versioning-and-compatibility); this
@@ -158,23 +174,3 @@ application-owned execution reports remain adapter responsibilities.
explicit zero overrides, shared backend admission, timeout attribution,
safe output, and unchanged HTTP artifact policy. No live inference is
needed to validate the migration.
## Open Decisions
### HTTP Route For The ID-Only Contract
**Recommendation:** Replace `POST /v1/runs` with a successor route such as
`POST /v2/runs` and support only the successor in the new release. Removing
`prompt_version` changes a documented request and output contract. A new route
makes that break explicit and lets a stale client fail even if it happened
not to send the removed field. Operators must update the URL as well as
their request and response handling, but there is no route forwarding or
legacy model to maintain.
**Alternative:** Cut over `POST /v1/runs` in place as part of the incompatible
application release. This is viable if all deployed HTTP callers can migrate
in lockstep and changing the URL would add unnecessary deployment work.
The downside is that callers omitting the old field could reach a changed
contract at the same URL, while callers sending it fail strict decoding.
Either choice has one live contract; compatibility routing is not part of
this work.