Align PromptKit architecture documentation

This commit is contained in:
2026-10-04 13:11:48 +00:00
parent b913ef0d07
commit beaaea2f1a
8 changed files with 104 additions and 55 deletions

View File

@@ -68,11 +68,11 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
framework credential semantics are defined by the
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
Explicit zero values for the numeric fields are overrides; zero
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
request context and configured transport cap. The timeout layers are defined in
the [Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
the [Promptkit v0.12.0 outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
Each built-in transient retry gets a fresh generation timeout; the caller's
request context remains the outer cancellation boundary.

View File

@@ -14,7 +14,7 @@ and the HTTP service according to the boundary your application needs.
Go applications that need an in-process prompt framework should import
Promptkit directly. The tagged
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
owns that interface; Scriptorium does not provide a Go library package.
Consumers arriving from the former Scriptorium Go API should follow the
[migration guide](migrating-to-promptkit.md).
@@ -35,4 +35,4 @@ Scriptorium does not persist run state. A retry can produce different output
and can incur another provider request. CLI exits belong to the
[CLI reference](../cli.md), HTTP status behavior belongs to the
[HTTP API reference](../api.md), and framework semantics belong to
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).

View File

@@ -2,9 +2,11 @@
This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public
[Promptkit v0.11.2 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md);
[Promptkit v0.12.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md);
framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v0.5.0; keep Scriptorium's schema and source selection local.
Promptkit also uses ConfigKit to load framework sources under Promptkit's own
schema and format contract.
## Initial Orientation
@@ -45,13 +47,14 @@ Before recommending, planning, or implementing work:
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) |
| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#promptkit-source-selectors), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
| Prompt, profile, schema, generation, or validation semantics | [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit v0.12.0 integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) |
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
| Runtime operation or recovery | [Operations](operations.md) |
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md), and the related files under `examples/` |
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit v0.12.0 format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md), and the related files under `examples/` |
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents |
Cross-project changes land and release in Promptkit before Scriptorium adopts

View File

@@ -9,7 +9,7 @@ own IO and presentation mechanics, not framework decisions.
External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md).
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md).
## Components And Collaborators
@@ -17,11 +17,13 @@ described by its tagged
`internal/adapter/cli`.
- `internal/adapter/cli` resolves settings through `internal/config`,
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
and owns output files, summaries, and exit codes.
exposes application and captured framework configuration inspection, and
owns output files, summaries, and exit codes.
- `internal/config` delegates application YAML decoding, default resolution,
overrides, and validation ordering to ConfigKit. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr.
load diagnostics on stderr. Promptkit uses ConfigKit to load framework
sources under its own definition and format contract.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs.
@@ -53,6 +55,15 @@ preparation or generation.
formats a safe application-owned effective profile view. It intentionally does
not require prompt, schema, or artifact sources.
`inspect configuration` builds the same engine from the selected native
Promptkit source sequence, reads its captured configuration view, and delegates
effective output and explanation to Promptkit's native writers. The adapter
projects captured source records into its small JSON DTO. Its validation
operation constructs the engine without preparing a request. Framework source
semantics and report redaction are owned by Promptkit; the [CLI
contract](../cli.md#framework-configuration-inspection) documents the exposed
operations and their deliberately limited redaction scope.
The `config` family loads the same application ConfigKit result once and uses
its validation, effective-output, source, and explanation views directly. It
does not construct a Promptkit engine. The CLI maps source records into a small
@@ -62,11 +73,14 @@ JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
adapter's consumer-owned `Runner` interface, and starts the server.
The command paths assemble the engine from the same resolved prompt, profile,
and schema directories plus configured custom backends. Each backend is mapped
to Promptkit's public `Backend` value and registered during engine construction,
so one constructed server engine retains one immutable backend registry and its
associated capacity state.
The command paths assemble the engine from application-selected framework
source files and directories plus the schema directory and retry setting.
Individual files become import-enabled ConfigKit inputs; directory selections
are expanded through Promptkit's directory-input helper. Scriptorium supplies
those ordered underlays through Promptkit's public configuration API rather
than parsing or mapping framework definitions itself. The server constructs
one engine, which retains the framework's backend registry and associated
capacity state across requests.
### HTTP

View File

@@ -7,13 +7,13 @@ public behavior belongs in the linked contracts.
| Component | Implemented responsibility | References |
| --- | --- | --- |
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) |
| `internal/config` | Selects application sources, supplies the application ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
Framework implementation packages are provided by
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
and are not part of this repository.

View File

@@ -5,20 +5,24 @@
This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
## Application Source Locations
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
the application-owned `backends` mapping into sorted engine settings.
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
each configured backend to Promptkit's public engine registration when
constructing an engine shared by the command path.
`internal/config` resolves the ordered `promptkit_sources` sequence and
`schema_dir` from application configuration and explicit CLI overrides. It
owns selector-shape validation, not framework file parsing. During engine
construction, `internal/adapter/cli` turns file selections into import-enabled
ConfigKit inputs and expands directory selections with
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays. The shared Promptkit engine receives the selected
schema directory and retry setting as well.
Scriptorium does not search, parse, validate, or overlay framework source files
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
resolution, ordinary file artifacts, and the related error identities.
Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate
Promptkit definitions. Promptkit owns definition selection and validation,
profile built-ins and overlays, schema resolution, ordinary file artifacts,
captured framework configuration inspection, and related error identities.
The [configuration reference](../config.md) owns Scriptorium's source-location
fields and precedence. Maintained files under `examples/` are application
@@ -26,13 +30,15 @@ inputs that use Promptkit's tagged formats.
## Application Configuration Boundary
`internal/config` contains a ConfigKit-native `Document` definition. Its
fresh defaults come from Scriptorium's existing default constants; its resolver
records only actual trimming, path cleaning, and render-format normalization.
The validator reports application retry, size-limit, and format errors without
mutating the document or exposing rejected values. Application path values keep
working-directory-relative meaning. ConfigKit owns strict YAML decoding and
presence semantics, including dynamic integer values in backend parameters.
`internal/config` contains the application-owned ConfigKit-native `Document`
definition. Its fresh defaults come from Scriptorium's existing default
constants; its resolver records only actual trimming, path cleaning, and
render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative
meaning. ConfigKit owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through
ConfigKit under Promptkit's own schema and source contract.
The `Load` boundary selects an explicit file, the first existing implicit
configuration file, or ConfigKit's defaults-only source. Only absence advances
@@ -45,11 +51,10 @@ select one named overlay when requested. ConfigKit uses the selected file's
canonical directory as the source root; the application does not widen it.
Application path values retain process-working-directory-relative meaning.
ConfigKit resolves effective sibling inheritance after source assembly and
overrides, before typed decoding. Runtime conversion and Promptkit registration
consume those resolved values through the existing `Settings` path. The
[configuration reference](../config.md#application-mapping-inheritance) owns
the application-visible inheritance behavior.
Runtime conversion consumes the resolved application values through the
existing `Settings` path. Promptkit receives selected framework sources only
after application configuration has loaded and validated; its source merge,
definition validation, and captured inspection view remain framework-owned.
Every configuration-loading command uses this boundary. The CLI maps only
explicitly visited application flags to ConfigKit overrides and prints
@@ -57,8 +62,11 @@ structured load diagnostics before engine construction. The old application
YAML decoder and merge path have been removed.
Application `config` inspection reuses the result's frozen effective,
provenance, and history views without constructing an engine or reloading
sources. It does not resolve API-key environment values; ordinary backend
parameters remain visible by the selected inspection policy.
sources. It does not resolve credentials. `inspect configuration` separately
constructs an engine and exposes Promptkit's captured framework view; only its
framework `show` and `explain` reports receive Promptkit's native,
credential-shaped redaction. Neither inspection family is a general-purpose
filter for arbitrary sensitive values.
## Restricted HTTP Artifact Reader

View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-10-03
**Last Updated**: 2026-10-04
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md
@@ -50,23 +50,32 @@ inventory; [adapter internals](../internal/adapters.md) and
## Framework And Application Boundaries
Scriptorium consumes
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/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, 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](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md)
definition-inspection presentation, captured-configuration inspection
exposure, process behavior, and HTTP deployment policy. The [format
reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts.
Scriptorium uses ConfigKit v0.5.0 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 also resolves sibling inheritance in application input
mappings. ConfigKit does not own Promptkit framework sources or HTTP artifact
mapping. Promptkit also uses ConfigKit to decode and assemble framework
sources under Promptkit's own schema and format contract; Scriptorium selects
the inputs but does not parse Promptkit definitions. ConfigKit is the shared
loading mechanism, not the owner of either domain schema or HTTP artifact
containment. The [configuration contract](../config.md) owns externally
observable configuration behavior.
observable application behavior, while Promptkit owns framework formats.
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

View File

@@ -3,8 +3,8 @@
## Status, Baseline, And Authority
Planned on 2026-10-04 against Scriptorium
`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–11 are complete; stages
12–13 are pending.
`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–12 are complete; stage
13 is pending.
This plan is for a Luna coding agent: implement the stages in sequential order,
normally one stage per implementation prompt. The
[feature roadmap](promptkit.md) owns the target state, scope, and confirmed
@@ -670,7 +670,22 @@ framework inspection for application validation or expecting automatic reload.
## Stage 12: Align Developer, Internal, And Architecture Documentation
Status: Pending. Depends on Stage 11.
Status: Complete. Current Promptkit references in the developer guide, internal
component/source/adapter docs, architecture policy, and affected HTTP API and
consumer guidance now target v0.12.0; historical migration and roadmap records
remain pinned to the versions they describe. The developer reading guide now
routes native source selection and captured framework inspection to their
owners without changing its selective policy-reading guidance. Internal docs
describe the application selector sequence, ConfigKit's separate application
and framework schema owners, shared CLI engine assembly, Promptkit-native
configuration reports, and existing server capacity ownership; stale backend
registration, old directory, and application-inheritance claims were removed.
Architecture ownership and the approved show/explain-only native redaction
scope were aligned, with Base Policy Version, Upstream Source, ADR decisions,
shared engine capacity, request independence, and HTTP lexical artifact
containment unchanged. The full-config application validator and all four
framework configuration inspection operations ran offline; the HTTP wire
contract was unchanged and `git diff --check` passes.
Files: `docs/development.md`, `docs/internal/overview.md`, `adapters.md`,
`sources.md`, `docs/policy/architecture.md`, and affected current consumer/API