Document Scriptorium as a Promptkit application

docs/policy/architecture.md

@@ -1,83 +1,102 @@
 # Architecture
 
-This document is the development architecture policy for Scriptorium.
-
-It is for developers and LLM coding agents. User-facing behavior belongs in `README.md` and the docs under `docs/` that target operators/users.
+This document defines Scriptorium's current application architecture and
+durable development boundaries.
 
 ## System Shape
 
-Scriptorium is a narrow prompt-execution application with three executable
-entry paths: CLI `run`, CLI `render`, and the HTTP service started by `serve`.
-It also provides a public Go package for in-process use. Executable adapters
-consume framework behavior through that public facade; the facade continues to
-compose the framework implementation inside this single repository. Its current
-component inventory is maintained in the [internal overview](../internal/overview.md).
+Scriptorium is an executable application with three entry paths: CLI `run`, CLI
+`render`, and the HTTP service started by `serve`. It does not expose a reusable
+root Go package.
 
-Domain behavior is centralized in `internal/usecase` and `internal/domain`.
+The application consumes
+[Promptkit v0.1.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
+through its supported root package. Promptkit owns prompt execution,
+preparation, source formats, built-in profiles, model-client behavior, and
+validation. Scriptorium owns application configuration, executable adapters,
+prepared-run presentation, process behavior, and HTTP deployment policy.
 
-## Core Principles
-
-- Keep orchestration narrow: Scriptorium executes one prompt request; it is not a multi-step workflow engine.
-- Keep adapter logic thin: adapters map external shapes to public engine
-  requests/results and should not hold framework decisions.
-- Keep boundaries explicit: repositories/loaders/renderers/validators/LLM client stay behind package interfaces.
-- Keep external decoding strict: configuration, prompt, and profile YAML and
-  HTTP JSON should reject unknown fields.
-- Keep secrets out of payloads: raw API key values must not be accepted or emitted.
+The concrete package inventory is maintained in the
+[internal overview](../internal/overview.md).
 
 ## Dependency Direction
 
-- Adapters translate external shapes and IO concerns; they do not make
-  use-case decisions.
-- Executable adapters and prepared-run formatting use the public facade for
-  framework behavior rather than importing framework implementation packages
-  directly.
-- Use-case and domain code depend on explicit repository, renderer, validator,
-  and LLM interfaces rather than adapter implementations.
-- Source, rendering, validation, and LLM implementations remain behind their
-  package boundaries.
-- Dependency-specific types must not leak across unrelated package boundaries.
-- Prefer the standard library; add an external dependency only when it
-  materially reduces risk or complexity.
+```text
+cmd/scriptorium
+        |
+        v
+CLI and HTTP adapters, configuration, defaults, and formatting
+        |
+        v
+gitea.maximumdirect.net/eric/promptkit
+```
 
-## State And Persistence Policy
+- Retained application packages may import Promptkit's root package.
+- They must not import Promptkit `internal` packages.
+- They must not import the removed Scriptorium root facade or recreate former
+  framework package families.
+- Adapter-owned interfaces use Promptkit public values when a consumer-side
+  substitution boundary is needed.
+- Scriptorium passes omitted framework settings as zero values so Promptkit
+  applies its own defaults.
 
-Scriptorium has no durable run-state store.
+The repository architecture guard enforces these import and removal
+invariants.
 
-- No built-in resume/checkpoint/archive behavior.
-- Recovery model is rerun after correcting inputs/config/environment.
+## Retained Boundaries
 
-## Contract Ownership
+- `internal/adapter/cli` owns commands, flags, configuration precedence,
+  process streams, output files, summaries, and exit codes.
+- `internal/adapter/http` owns routes, strict JSON DTOs, size limits, response
+  mapping, status mapping, and the restricted artifact reader.
+- `internal/config` owns discovery and strict decoding of Scriptorium
+  application configuration.
+- `internal/defaults` owns Scriptorium application and HTTP defaults only.
+- `internal/format` owns deterministic prepared-run text and JSON presentation.
+- Promptkit owns framework orchestration and contracts. Its
+  [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md)
+  and
+  [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/integrations/openai-compatible-chat.md)
+  are canonical.
 
-The [CLI](../cli.md), [configuration](../config.md), [HTTP API](../api.md),
-[public Go package](../consumers/pkg-scriptorium.md), and
-[integration](../integrations/) documents own their respective external
-contracts. This policy keeps only the architectural boundaries that govern
-their implementation.
+## HTTP Artifact Security Boundary
 
-## Error Handling And Logging
+Ordinary CLI file loading is provided by Promptkit. Scriptorium's HTTP adapter
+injects a restricted `promptkit.ArtifactReader` for inbound HTTP requests.
+That reader denies file references without an artifact root, enforces the
+configured byte limit, and applies Scriptorium's lexical root-containment rule.
+The operating system still follows symlinks after the lexical check.
 
-- Wrap errors with domain/operation context.
-- Map public error identities to adapter-appropriate statuses/codes without
-  leaking sensitive internals.
-- Never emit raw secret values.
+The [HTTP API](../api.md) owns observable request outcomes, and
+[operations](../operations.md) owns deployment permissions and root selection.
 
-## Testing And Documentation
+## State, Errors, And Secrets
 
-Testing philosophy and change-validation expectations are defined by the
-[testing policy](testing.md). Documentation ownership and maintenance rules are
-defined by the [documentation policy](documentation.md).
+Scriptorium has no durable run-state store, checkpoint, cache, or resume
+mechanism. Recovery is a new request after correcting inputs, configuration, or
+environment.
+
+Adapters map Promptkit public error identities into 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.
 
 ## Architectural Invariants
 
-- `Runner.Run` reuses `Runner.Prepare` flow.
-- Raw API key values must not be accepted through external configuration or
-  request payloads, and resolved secret values must not be emitted.
+- External YAML and JSON decoding remains strict.
+- CLI and HTTP behavior remains presentation and transport logic rather than
+  framework orchestration.
+- Explicit numeric request overrides preserve presence, including zero.
+- HTTP artifact containment and byte limits remain Scriptorium policy.
+- No application package depends on Promptkit implementation packages.
 
 ## Non-Goals
 
-- Do not move orchestration responsibilities from external callers into Scriptorium.
-- Do not add adapter-specific business logic in `internal/adapter/*` packages.
-- Do not bypass repository/renderer/validator/LLM boundaries by introducing cross-package coupling.
+- 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.
 
 Work that is not implemented belongs in `docs/roadmap/`.