5.5 KiB
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.