Record the HTTP API cutover decision
This commit is contained in:
@@ -5,8 +5,10 @@
|
|||||||
Accepted direction; not yet implemented. Upgrade the existing Scriptorium
|
Accepted direction; not yet implemented. Upgrade the existing Scriptorium
|
||||||
product in one native cutover. Use the released PromptKit and ConfigKit APIs
|
product in one native cutover. Use the released PromptKit and ConfigKit APIs
|
||||||
for framework and configuration mechanisms that they already own. Provide
|
for framework and configuration mechanisms that they already own. Provide
|
||||||
migration guidance, not a second application schema, a legacy definition
|
migration guidance for configuration, definitions, and CLI usage, not a
|
||||||
reader, or compatibility aliases.
|
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
|
The [definition boundary](../adr/0004-definition-boundary.md) and
|
||||||
[configuration boundary](../adr/0005-configkit-boundary.md) remain in effect.
|
[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
|
including a qualified collection ID where appropriate. Remove the CLI
|
||||||
version selector and the corresponding version members from the CLI and HTTP
|
version selector and the corresponding version members from the CLI and HTTP
|
||||||
request, response, inspection, and report contracts where they exist. Do not
|
request, response, inspection, and report contracts where they exist. Do not
|
||||||
accept a legacy version selector and then ignore it. The HTTP route decision
|
accept a legacy version selector and then ignore it.
|
||||||
below determines where the single new HTTP contract is served.
|
|
||||||
|
|
||||||
Continue to distinguish framework configuration, resolved resources, and
|
Continue to distinguish framework configuration, resolved resources, and
|
||||||
request preparation. Framework configuration inspection reports the
|
request preparation. Framework configuration inspection reports the
|
||||||
@@ -96,13 +97,25 @@ to existing prompt inspection output.
|
|||||||
PromptKit owns preparation, provider calls, retries, capacity, validation,
|
PromptKit owns preparation, provider calls, retries, capacity, validation,
|
||||||
and repair. Preserve the configured shared server engine and established
|
and repair. Preserve the configured shared server engine and established
|
||||||
backend admission behavior. Use PromptKit's native operation timeout for the
|
backend admission behavior. Use PromptKit's native operation timeout for the
|
||||||
existing whole-run budget where it can preserve the current execution
|
existing whole-run budget where it can preserve the execution boundary and
|
||||||
boundary and error mapping. A provider-attempt timeout is still distinct
|
support the intended CLI and HTTP outcomes. A provider-attempt timeout is
|
||||||
from the whole-run deadline; caller cancellation still applies. Keep the
|
still distinct from the whole-run deadline; caller cancellation still
|
||||||
existing context wrapper if delegation would change those semantics rather
|
applies. Keep the existing context wrapper if delegation would change those
|
||||||
than introducing two independent timers. CLI process behavior, HTTP
|
semantics rather than introducing two independent timers. CLI process
|
||||||
decoding, limits, restricted artifact loading, safe diagnostics, and
|
behavior, HTTP decoding, limits, restricted artifact loading, safe
|
||||||
application-owned execution reports remain adapter responsibilities.
|
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
|
## 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
|
overrides and optional-value presence. Check that the restricted HTTP
|
||||||
artifact reader transfers ownership of returned artifacts and bytes under
|
artifact reader transfers ownership of returned artifacts and bytes under
|
||||||
the new public contract without changing Scriptorium's containment policy.
|
the new public contract without changing Scriptorium's containment policy.
|
||||||
Preserve the established execution outcome, size-limit, cancellation, and
|
Preserve established CLI outcomes outside the intentional cutover changes.
|
||||||
credential-disclosure behavior 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
|
- **Give operators a migration path in documentation.** Update the
|
||||||
[consumer migration guide](../consumers/upgrading-promptkit.md) with
|
[consumer migration guide](../consumers/upgrading-promptkit.md) with
|
||||||
before-and-after application and framework examples, directions for old
|
before-and-after application and framework examples, directions for old
|
||||||
prompt versions and catalog references, and the changed CLI and HTTP
|
prompt versions and catalog references, and the changed CLI contract.
|
||||||
contracts. Explain semantic changes that can survive a syntactic
|
Explain semantic changes that can survive a syntactic conversion,
|
||||||
conversion, particularly replacement, null fallback, and schema
|
particularly replacement, null fallback, and schema
|
||||||
resolution. Update the canonical configuration, CLI, HTTP, subprocess, and
|
resolution. Document the new HTTP contract directly in the
|
||||||
internal references where their implementation changes. Refresh current
|
[API reference](../api.md) and update its maintained examples. Update the
|
||||||
contributor and architecture references to the selected upstream release,
|
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
|
leaving historical release records intact. Record release impact as
|
||||||
an intentional incompatible change under the
|
an intentional incompatible change under the
|
||||||
[release policy](../policy/release.md#versioning-and-compatibility); this
|
[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,
|
explicit zero overrides, shared backend admission, timeout attribution,
|
||||||
safe output, and unchanged HTTP artifact policy. No live inference is
|
safe output, and unchanged HTTP artifact policy. No live inference is
|
||||||
needed to validate the migration.
|
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