Document the Promptkit v0.9 adoption plan

docs/adr/0004-definition-boundary.md

@@ -0,0 +1,112 @@
+# 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.