scriptorium/docs/policy/architecture.md

Architecture Policy

Base Policy Version: 1.3

Last Updated: 2026-09-28

Upstream Source: d84a38ebab/docs/policy/architecture.md

Purpose And Ownership

The adopted policy defines the application's purpose and the architectural constraints contributors must follow. It owns system boundaries, responsibility and dependency rules, established invariants, and explicit non-goals.

Describe the concrete package inventory and implementation mechanics in internal documentation. Link to canonical public contracts for their exact behavior and to ADRs for decision rationale.

Architectural Approach

Hexagonal architecture is strongly recommended, including encapsulating external integrations and APIs within internal adapters. Keep domain and application logic independent of external integration details, and make dependency direction clear in the adopted policy.

Implement that separation with proportionate, idiomatic code. Choose interfaces and package layout to serve the application's actual boundaries. Use adapters for collaborators with external integration responsibilities.

Adopted Constraints And Implemented Structure

Architectural constraints govern current and future development. Record implemented structure accurately, proposals and implementation status in the roadmap, and significant decisions and rationale in ADRs. Describe a target structure as implemented when its changes land.

Constraints must reflect deliberately selected requirements and decisions. Do not promote incidental implementation choices into architectural invariants.

Scriptorium's Purpose And System Shape

Scriptorium is an executable application with CLI run, render, inspect, and config command families and an HTTP service started by serve. It offers simple, request-independent execution of predefined prompts, not a reusable Scriptorium root Go API or a workflow framework. The internal overview owns the concrete package inventory; adapter internals and source internals own implementation mechanics.

Framework And Application Boundaries

Scriptorium consumes Promptkit v0.11.2 through its supported public root package. Promptkit owns prompt execution, preparation, prompt and profile formats, built-in profiles, model-client behavior, validation, and framework defaults. Scriptorium owns application configuration, executable CLI and HTTP adapters, prepared-run and definition-inspection presentation, process behavior, and HTTP deployment policy. The format reference and outbound integration contract remain Promptkit's contracts.

Scriptorium uses ConfigKit v0.4.2 for strict application YAML decoding, resolution, and validation flow. Scriptorium retains its application schema, defaults, normalization, validation rules, source selection, and CLI override mapping. ConfigKit does not own Promptkit framework sources or HTTP artifact containment. The configuration contract owns externally observable configuration behavior.

Application code may import Promptkit's public root package, but not its internal packages or catalog modules. It must not recreate the removed Scriptorium framework facade or former framework package families. Adapter-owned interfaces use Promptkit public values when a consumer-side substitution boundary is needed. Omitted framework settings pass as zero values so Promptkit applies its own defaults. Cross-project changes land and release in Promptkit before Scriptorium adopts its tagged dependency; do not commit Go workspaces, local replacements, vendored Promptkit source, or unpublished dependency assumptions. The repository's architecture guard protects these import and removal boundaries. Adapter separation does not require an interface for every type, extra wrappers, or a fixed directory tree.

Definition Support And Request State

As decided in ADR 0004, Scriptorium aims to support the complete set of features in valid Promptkit prompt and profile definitions for its selected upstream version. Promptkit remains the canonical parser and validator. Library-only features are considered individually against Scriptorium's simple predefined-prompt execution model.

External YAML and JSON decoding remains strict. Adapters map external values through Promptkit public requests and results without taking over framework orchestration. Explicit numeric request overrides preserve presence, including zero. Adapters map Promptkit public error identities to CLI exits or HTTP statuses without classifying by message text. Raw API keys are not accepted in Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved secrets must not be emitted.

Each execution request is self-contained from the caller's perspective; no conversation or workflow state is retained from completed requests. This does not preclude process-scoped operational state. A server shares its Promptkit engine, backend registry, capacity admission and queue accounting across relevant concurrent requests so configured backend limits cannot be bypassed by per-request construction. In-flight coordination, cancellation, and server lifecycle state must be concurrency-safe. None of this creates a durable workflow, checkpoint, cache, or resume contract; recovery is a new request after correcting inputs, configuration, or environment.

Non-Goals

• Do not recreate an in-process Scriptorium framework API or compatibility facade.
• Do not copy Promptkit types, defaults, built-in profiles, or implementation into Scriptorium.
• Do not move CLI, inbound HTTP, process, or deployment policy into Promptkit.
• Do not add durable workflow, archive, or resume behavior.
• Do not add application-managed prompt modification, follow-up message flows, conversation management, or multi-step workflow orchestration.

Trust Boundaries And Threat Scope

Ordinary CLI file loading belongs to Promptkit. For untrusted inbound HTTP artifact references, Scriptorium injects a restricted promptkit.ArtifactReader. It denies file references without an artifact root, applies the configured byte limit, and enforces lexical root containment. The operating system follows symlinks after that lexical check. This is not a filesystem sandbox or a defense against a privileged actor concurrently modifying the host filesystem; that threat is outside the adopted scope. Do not infer stronger defenses from hypothetical threats. Raise unsettled scope decisions under the agent policy.

The HTTP API owns observable request outcomes, the configuration contract owns credential supply, and operations owns deployment permissions and root selection. The source internals describe reader mechanics.