From 95a94249f14f636e72eedb07e1ab93504c69a690 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 18 Nov 2026 15:11:58 +0000 Subject: [PATCH] Record the HTTP API cutover decision --- docs/roadmap/promptkit-v0.23.2-adoption.md | 74 ++++++++++------------ 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/docs/roadmap/promptkit-v0.23.2-adoption.md b/docs/roadmap/promptkit-v0.23.2-adoption.md index fee303b..51235aa 100644 --- a/docs/roadmap/promptkit-v0.23.2-adoption.md +++ b/docs/roadmap/promptkit-v0.23.2-adoption.md @@ -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.