Files
scriptorium/docs/policy/architecture.md

153 lines
8.5 KiB
Markdown
Raw Normal View History

# Architecture Policy
**Base Policy Version:** 1.3
**Last Updated**: 2026-11-20
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/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`, native `promptkit`
and `config` 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](../internal/overview.md) owns the concrete package
inventory; [adapter internals](../internal/adapters.md) and
[source internals](../internal/sources.md) own implementation mechanics.
## Framework And Application Boundaries
Scriptorium consumes
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
through its supported public root package. Promptkit owns prompt execution,
preparation, prompt and profile formats, built-in profiles, model-client
behavior, validation, inspection semantics, and framework defaults. Scriptorium
owns the application domain, executable CLI and HTTP adapters, process behavior,
and HTTP deployment policy. It interprets resolved configuration and uses
PromptKit's supported APIs and results to satisfy user requests. The [format
reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts.
ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
fully resolved configuration handoff. Scriptorium supplies application schema
and domain callbacks through ConfigKit's supported extension points and consumes
the completed result without redefining effective configuration. PromptKit's
configuration is also resolved through ConfigKit, with PromptKit supplying its
domain schema and rules. The [configuration contract](../config.md) owns
externally observable application behavior; PromptKit owns framework formats.
As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
neutrally expose upstream features and semantics. CommandKit owns shared command,
parsing, presentation, and outcome mechanics; application commands and effects
remain local. Standard configuration inspection uses native adapters without
custom effective documents or evidence reconciliation. This decision complements
ADRs 0004 and 0005; the completed
[adoption record](https://forge.maximumdirect.net/eric/scriptorium/src/commit/f5573f7c8f2ddf0d69414a05c978c8d6cfe291e7/docs/roadmap/commandkit-adoption.md)
remains in Git history.
The CLI exposes Promptkit's captured framework configuration inspection. Its
`show` and `explain` reports use Promptkit's native redaction for classified
credential-shaped fields, including historical values. This scoped behavior is
not a general-purpose filter for arbitrary sensitive content and does not
extend to application configuration or existing prompt/profile inspection.
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](../adr/0004-definition-boundary.md), 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](agents.md).
The [HTTP API](../api.md) owns observable request outcomes, the
[configuration contract](../config.md) owns credential supply, and
[operations](../operations.md) owns deployment permissions and root selection.
The [source internals](../internal/sources.md) describe reader mechanics.