Record the HTTP API cutover decision
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user