113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# Preserve Definition Compatibility And A Simple Execution Model
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-08-29.
|
|
|
|
## Context
|
|
|
|
Scriptorium is a user-facing application built on Promptkit. Promptkit is a Go
|
|
library with both declarative framework formats and public APIs intended for
|
|
applications that need to assemble specialized integrations or workflows.
|
|
|
|
Scriptorium needs a durable rule for deciding which upstream capabilities it
|
|
must support. Treating every new Promptkit public API as an application feature
|
|
would steadily expand Scriptorium into a workflow framework. Selecting an
|
|
arbitrary subset of prompt or profile fields would instead make valid Promptkit
|
|
definitions unexpectedly unusable through Scriptorium.
|
|
|
|
The intended product is narrower: Scriptorium provides simple executable
|
|
interfaces that select and execute predefined prompts and return their results
|
|
in a consistent, repeatable form. It is not intended to own conversations,
|
|
modify prompts dynamically, coordinate follow-up messages, or manage complex
|
|
multi-step workflows.
|
|
|
|
## Decision
|
|
|
|
Scriptorium will aim to support the complete set of features expressible in
|
|
valid Promptkit prompt and profile definitions for the Promptkit version it
|
|
selects. This includes the schema, backend, source, and request plumbing needed
|
|
to prepare and execute those definitions without Scriptorium imposing a
|
|
narrower field-level format contract.
|
|
|
|
Promptkit remains the canonical parser and validator for its definitions.
|
|
Scriptorium will pass its configured framework sources and mapped request
|
|
values through the supported Promptkit public facade rather than copying
|
|
Promptkit formats, defaults, or validation rules.
|
|
|
|
Promptkit library features that are not required to use valid prompt or profile
|
|
definitions are considered individually. They may be incorporated when they
|
|
serve Scriptorium's simple execution model and fit its application-owned CLI,
|
|
HTTP, configuration, presentation, security, and process boundaries. A public
|
|
Promptkit declaration does not by itself require a corresponding Scriptorium
|
|
interface.
|
|
|
|
Each execution request will remain self-contained from the caller's
|
|
perspective. A request must not depend on conversation or workflow state
|
|
retained from a completed request, and Scriptorium will not become a general
|
|
workflow or conversation system. Application-managed prompt modification,
|
|
appended or follow-up message flows, conversation state, prepared-handle
|
|
coordination, multi-step orchestration, and similar higher-level workflows are
|
|
outside its intended scope.
|
|
|
|
Scriptorium may, and when necessary must, maintain process-scoped operational
|
|
state shared by concurrent requests. This includes the configured Promptkit
|
|
engine and backend registry, capacity admission and queue accounting,
|
|
in-flight request coordination, cancellation, and ordinary server lifecycle
|
|
resources. The state must be scoped so configured backend limits apply across
|
|
all relevant in-flight requests. But this is operational implementation state,
|
|
not durable user workflow or conversation state.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Expose Every Promptkit Public Feature
|
|
|
|
This would make the application surface track the library API closely, but it
|
|
would blur the boundary between a reusable Go library and a simple executable
|
|
consumer. Library-oriented lifecycle, source-construction, extension, and
|
|
workflow primitives would add commands, wire contracts, configuration, and
|
|
state without necessarily improving predefined prompt execution.
|
|
|
|
### Support A Curated Subset Of Definition Fields
|
|
|
|
This would keep the application small in the short term, but valid Promptkit
|
|
definitions could fail or behave differently solely because they were invoked
|
|
through Scriptorium. Maintaining a parallel field-level compatibility list
|
|
would also duplicate upstream format ownership and create recurring drift.
|
|
|
|
### Expand Scriptorium Into A Workflow Service
|
|
|
|
Scriptorium could own conversations, prompt changes, follow-up messages,
|
|
retries, checkpoints, and multi-step execution. That is a different product
|
|
with durable state, lifecycle, recovery, privacy, and operational requirements
|
|
that are not justified by Scriptorium's current purpose.
|
|
|
|
## Consequences
|
|
|
|
- Promptkit upgrades require an audit of the complete prompt and profile format
|
|
contracts, not only a source-compatibility build.
|
|
- Scriptorium adapters must not add unconditional request requirements that
|
|
reject a definition Promptkit can validly prepare or execute.
|
|
- Application configuration may need new plumbing, such as custom backend
|
|
registration, when it is necessary to use a valid profile feature.
|
|
- Definition parsing, validation, precedence, inheritance, defaults, and
|
|
built-in catalogs remain Promptkit responsibilities.
|
|
- A running HTTP server must share its appropriately scoped Promptkit engine
|
|
across requests so the engine's backend admission and concurrency limits
|
|
cannot be bypassed by per-request construction.
|
|
- Process-scoped counters, queues, in-flight request records, cancellation, and
|
|
lifecycle resources are permitted implementation state. They must be
|
|
concurrency-safe and do not create a durable resume or conversation
|
|
contract.
|
|
- Library-only source constructors, injected collaborators, opaque lifecycle
|
|
handles, and request-composition primitives remain optional Scriptorium
|
|
features rather than automatic requirements.
|
|
- New application features must be evaluated against the simple,
|
|
request-independent predefined-prompt execution model.
|
|
- Work that implements this decision remains tracked in roadmaps until it is
|
|
delivered and incorporated into current-state contracts.
|