98 Commits

Author SHA1 Message Date
69d2ba7038 Allow native format selection for separate reports 2026-11-20 03:14:07 +00:00
fbe7dd56e3 Use stdout redirection for main generation output 2026-11-20 02:16:44 +00:00
99b0ebfc03 Plan the CommandKit adoption sprint 2026-11-20 01:07:52 +00:00
bcb1a76e34 Record native operator interface ownership and align documentation 2026-11-20 00:49:27 +00:00
6ed4ac624a Clarify configuration authority and native inspection boundaries 2026-11-20 00:32:12 +00:00
c7b9c30c43 Add CommandKit adoption roadmap 2026-11-19 18:53:19 +00:00
5f32a4f2ad Settle application commands and prefer native convenience aliases 2026-11-19 18:20:17 +00:00
8078c6ecc7 Align Narratio requirements with native CommandKit reports 2026-11-19 18:16:28 +00:00
66a0954b52 Settle native configuration and namespace conventions 2026-11-19 18:07:53 +00:00
5eeb09d1ec Replace render with native prepared request preview in migration plan 2026-11-19 18:02:26 +00:00
f31dec61ef Settle output destination and native verbosity conventions 2026-11-19 17:54:57 +00:00
293374d7a7 Record native result and report file decisions 2026-11-19 16:20:45 +00:00
b3a0a73416 Record generation output and subprocess requirements 2026-11-19 16:11:00 +00:00
3f5e441756 Include comparison smoke tests and completion in migration scope 2026-11-19 16:01:20 +00:00
23108bd2f0 Record CommandKit migration direction and open decisions 2026-11-19 15:56:29 +00:00
d97e2b8e30 Remove completed PromptKit planning documents 2026-11-19 15:21:14 +00:00
3105f4d62f Prevent HTTP artifact limit overflow 2026-11-19 15:19:39 +00:00
6562d63a02 Write framework explanations in one pass 2026-11-19 15:18:26 +00:00
dd1915735f Clarify precedence for discovered collections 2026-11-19 15:17:46 +00:00
a2f3588639 Link the Go Text patent notice 2026-11-19 15:17:23 +00:00
3f481ea432 Clarify source-relative message paths 2026-11-19 15:17:02 +00:00
ac858be2a2 Bound the HTTP timeout regression tests 2026-11-19 15:16:33 +00:00
cf50650e55 Record PromptKit algorithm audit findings 2026-11-19 15:13:00 +00:00
7afe6ba333 Record collection discovery integration finding 2026-11-19 15:01:37 +00:00
16197ae9dd Record PromptKit adoption review findings 2026-11-19 14:54:28 +00:00
c5e54edaa5 Adopt PromptKit timeout fix and complete verification 2026-11-19 14:39:10 +00:00
78bcf86619 Remove obsolete dependency checksums 2026-11-18 19:33:58 +00:00
5d372dd37d Clarify runtime dependencies and attribution format 2026-11-18 19:33:16 +00:00
9bd1629a9e Correct timeout and dependency license notices 2026-11-18 19:32:26 +00:00
50c65adac4 Update documentation for PromptKit adoption 2026-11-18 19:25:54 +00:00
a2205db152 Demonstrate independent collection discovery 2026-11-18 19:20:55 +00:00
27db6b6f47 Migrate maintained PromptKit definitions and fixtures 2026-11-18 19:19:24 +00:00
f858d57322 Refactor the single-run HTTP contract 2026-11-18 19:12:07 +00:00
de7c866662 Adapt inspection to native PromptKit records 2026-11-18 19:08:41 +00:00
77f168c660 Migrate CLI execution and terminal reports 2026-11-18 19:04:15 +00:00
e7a8b0db04 Unify PromptKit and ConfigKit source wiring 2026-11-18 19:01:17 +00:00
ae5344a77d Plan the PromptKit adoption sprint 2026-11-18 18:52:40 +00:00
247b67312e Clarify optional collection discovery globs 2026-11-18 18:46:12 +00:00
ca7c7faf5c Limit inspection work during PromptKit adoption 2026-11-18 18:43:01 +00:00
a0134ea49a Document collection discovery in the PromptKit adoption roadmap 2026-11-18 18:39:10 +00:00
95a94249f1 Record the HTTP API cutover decision 2026-11-18 15:11:58 +00:00
87d7240f31 Document the PromptKit upgrade roadmap 2026-11-18 15:08:38 +00:00
1b1d967fc7 Remove completed ConfigKit planning documents 2026-11-18 14:31:37 +00:00
932fd6da25 Clarify source selector clearing behavior 2026-11-18 00:29:33 +00:00
65bd2da51a Record ConfigKit review finding 2026-11-17 23:51:33 +00:00
eec4fa2d91 Complete ConfigKit adoption validation 2026-11-17 22:18:13 +00:00
2c3d8e4c8b Document native application configuration adoption 2026-11-17 22:15:10 +00:00
79dfe0a3ef Update integration fixtures and collection examples 2026-11-17 22:12:10 +00:00
03b479b4d7 Test native application configuration behavior 2026-11-17 22:06:58 +00:00
5c780a4cc0 Separate application and framework configuration types 2026-11-17 22:03:08 +00:00
d79e23739f Use native ConfigKit application loading 2026-11-17 22:00:43 +00:00
49461b18e4 Select ConfigKit and Go toolchain versions 2026-11-17 21:58:07 +00:00
222f4056e6 Plan native ConfigKit migration 2026-11-17 20:40:57 +00:00
a5d8394313 Plan interim ConfigKit upgrade 2026-11-17 20:27:12 +00:00
ba24b7a879 Adopt updated standard repository policies 2026-11-17 20:09:23 +00:00
723fee9c46 Record ConfigKit configuration ownership 2026-10-04 18:58:51 +00:00
0cd95f6e8e Request prompt requirement inspection for Narratio 2026-10-04 17:15:59 +00:00
c233d03371 Advertise framework inspection commands in usage 2026-10-04 14:31:17 +00:00
907fc51236 Correct composed configuration example description 2026-10-04 14:26:46 +00:00
cd0811a49e Clarify definition inspection loading 2026-10-04 14:25:38 +00:00
1c8494ec20 Record PromptKit adoption review findings 2026-10-04 13:57:36 +00:00
58cb02f973 Complete PromptKit adoption audit 2026-10-04 13:17:16 +00:00
beaaea2f1a Align PromptKit architecture documentation 2026-10-04 13:11:48 +00:00
b913ef0d07 Document PromptKit source migration 2026-10-04 13:04:02 +00:00
411a67b241 Explain framework configuration paths safely 2026-10-04 12:46:12 +00:00
2ba2ce1b91 Add captured framework configuration inspection 2026-10-04 12:37:02 +00:00
c2e2b74f83 Protect PromptKit source and definition semantics 2026-10-04 12:30:38 +00:00
9ea9d0706d Migrate HTTP and report fixtures to PromptKit sources 2026-10-04 12:20:43 +00:00
5c302f18ac Migrate CLI execution tests to native definitions 2026-10-04 12:15:10 +00:00
54c8e9011e Migrate CLI tests to native PromptKit sources 2026-10-04 12:04:14 +00:00
2027b80311 Migrate maintained PromptKit definitions and examples 2026-10-04 11:41:00 +00:00
0df2aad3a8 Wire native PromptKit sources into CLI commands 2026-10-04 11:36:00 +00:00
0d5ecfa842 Replace legacy framework config with source selectors 2026-10-04 11:26:40 +00:00
c8e2b972f3 Upgrade PromptKit and catalog modules 2026-10-04 11:15:34 +00:00
b1bb55a9a0 Plan PromptKit configuration upgrade 2026-10-04 00:44:47 +00:00
82b0f231b6 Confirm PromptKit adoption decisions 2026-10-04 00:16:24 +00:00
15e7c1aed9 Plan PromptKit configuration adoption 2026-10-03 18:08:09 +00:00
bb5006517b Record ConfigKit adoption review finding 2026-10-03 17:52:18 +00:00
bcf2ddf246 Complete ConfigKit inheritance implementation handoff 2026-10-03 17:46:56 +00:00
ddcba9c639 Document backend configuration inheritance 2026-10-03 17:43:58 +00:00
70f7e96d02 Test CLI inheritance inspection and use 2026-10-03 17:40:35 +00:00
ea964707f7 Test inherited configuration resolution 2026-10-03 17:35:55 +00:00
bbb473a3d9 Adopt ConfigKit v0.5.0 inheritance 2026-10-03 17:33:35 +00:00
e1ce526114 Plan ConfigKit inheritance implementation 2026-10-03 17:26:28 +00:00
8b6c12f912 Plan ConfigKit inheritance adoption 2026-10-03 17:16:02 +00:00
9849c6bda2 Prepare Scriptorium v0.15.0 release notes
All checks were successful
ci/woodpecker/tag/release Pipeline was successful
2026-09-28 03:01:09 +00:00
777b727602 Update ConfigKit and PromptKit patch versions 2026-09-28 02:41:03 +00:00
81e1ef59e6 Clarify interface guidance and completed plan status 2026-09-28 02:25:45 +00:00
df762c3735 Complete policy alignment documentation handoff 2026-09-28 01:47:05 +00:00
417522f08c Align release policy with existing publication workflow 2026-09-28 01:44:38 +00:00
b3bb36fc86 Align architecture and testing policies with upstream 2026-09-28 01:43:29 +00:00
ba0d99f107 Adopt policy provenance and documentation guidance 2026-09-28 01:41:33 +00:00
538bc27472 Adopt open source policy and licensing notices 2026-09-28 01:39:10 +00:00
1bad076d48 Plan the policy alignment implementation 2026-09-28 01:14:38 +00:00
8452b54809 Revise the policy alignment roadmap 2026-09-28 01:11:57 +00:00
d6aecf5c50 Update library patches and licensing attribution 2026-09-26 22:01:03 +00:00
83856b4de8 Document the licensing policy alignment roadmap 2026-09-26 20:48:35 +00:00
39d3508705 Fix license name typos in COPYRIGHT 2026-09-26 20:38:50 +00:00
112 changed files with 6636 additions and 3019 deletions

View File

@@ -3,11 +3,13 @@ when:
steps: steps:
- name: build-release-assets - name: build-release-assets
image: golang:1.25 image: golang:1.27.4
commands: commands:
- | - |
set -eu set -eu
export GOTOOLCHAIN=local
version="$CI_COMMIT_TAG" version="$CI_COMMIT_TAG"
dist="dist" dist="dist"
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium" pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"

View File

@@ -1,4 +1,6 @@
Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide. Start with `docs/development.md` for orientation and use its policy reading guide
to select the policies applicable to the task. Do not read the entire suite by
default.
Review and follow `docs/policy/agents.md` before recommending, planning, or Read and follow `docs/policy/agents.md` before recommending, planning, or
implementing changes to this repository. implementing repository changes.

View File

@@ -5,7 +5,7 @@ Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: GPL-3.0-or-later SPDX-License-Identifier: GPL-3.0-or-later
Scriptorium is free software: you can redistribute it and/or modify it Scriptorium is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or the Free Software Foundation, either version 3 of the License, or
(at your option) any later version. (at your option) any later version.
@@ -14,6 +14,10 @@ The GNU General Public License version 3 is provided in LICENSE.
Scriptorium is distributed in the hope that it will be useful, Scriptorium is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details. GNU General Public License for more details.
Third-party code and assets are subject to their respective license terms. Third-party code and assets are subject to their respective license terms.
Policy documents adapted from Standard Repository Policies remain licensed
under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material,
upstream credit, and license links.

View File

@@ -6,7 +6,7 @@ OpenAI-compatible model endpoints, and returns generated output with validation
metadata. metadata.
The application uses The application uses
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/) [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/)
for prompt, profile, schema, preparation, generation, and validation behavior. for prompt, profile, schema, preparation, generation, and validation behavior.
Scriptorium owns executable configuration, CLI and HTTP mapping, process Scriptorium owns executable configuration, CLI and HTTP mapping, process
behavior, output presentation, and HTTP artifact-containment policy. behavior, output presentation, and HTTP artifact-containment policy.
@@ -33,25 +33,30 @@ a model. For complete invocation and output behavior, see the
- [CLI reference](docs/cli.md) - [CLI reference](docs/cli.md)
- [Configuration reference](docs/config.md) - [Configuration reference](docs/config.md)
- [Application configuration inspection](docs/cli.md#application-configuration-inspection) - [Application configuration inspection](docs/cli.md#application-configuration-inspection)
- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection)
- [HTTP API reference](docs/api.md) - [HTTP API reference](docs/api.md)
- [Operations guide](docs/operations.md) - [Operations guide](docs/operations.md)
- [Consumer integration overview](docs/consumers/api.md) - [Consumer integration overview](docs/consumers/api.md)
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md) - [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md)
- [Subprocess integration](docs/integrations/subprocess.md) - [Subprocess integration](docs/integrations/subprocess.md)
- [Architecture policy](docs/policy/architecture.md) - [Architecture policy](docs/policy/architecture.md)
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) - [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md) - [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
## Examples ## Examples
- [Minimal configuration](examples/config.yml) and - [Minimal configuration](examples/config.yml) and
[complete configuration](examples/config.full.yml), plus a [complete configuration](examples/config.full.yml), plus a
[composed import/overlay example](examples/config.composed.yml) [composed import/overlay example](examples/config.composed.yml), a
[collection composition example](examples/config.collections.yml), a
[collection checkout discovery example](examples/config.discovery.yml), and a
[backend inheritance example](examples/config.inheritance.yml)
- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/),
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
- [Render script](examples/render-markdown-summary.sh) - [Render script](examples/render-markdown-summary.sh)
- [HTTP request](examples/http-run.json) - [HTTP request](examples/http-run.json)
Scriptorium is licensed under the [BSD 3-Clause License](LICENSE). Scriptorium is licensed under the [GPL v3.0 or later](COPYRIGHT).
[Open Source attribution notices](docs/oss/attribution.md) are available. [Open Source attribution notices](docs/oss/attribution.md) are available.

View File

@@ -0,0 +1,71 @@
# ADR 0005: Adopt ConfigKit's Configuration Boundary
## Status
Accepted.
## Date
2026-10-04.
## Context
Scriptorium uses ConfigKit to resolve application configuration. Adopting its
standard semantics across the application suite gives operators a consistent
configuration model and keeps configuration processing under a single owner.
The application supplies its schema and domain rules through ConfigKit's public
definition API. ConfigKit returns the resolved configuration and inspection
information for use by Scriptorium.
## Decision
ConfigKit owns configuration loading and resolution semantics, including
decoding, imports, composition, precedence, overlays, inheritance, and
inspection. Scriptorium adopts those semantics through ConfigKit's supported
public APIs.
Scriptorium owns its application schema, defaults, value normalization, and
domain validation. It supplies these rules through ConfigKit's definition
callbacks so they participate in the library's resolution and validation flow.
Scriptorium consumes the final, fully resolved configuration returned by that
flow.
Scriptorium also owns application-facing choices: default discovery locations,
source and option selection, and the mapping of CLI inputs to ConfigKit options
and overrides. ConfigKit determines how the selected inputs are processed.
Scriptorium may expose ConfigKit's inspection APIs through operator interfaces
when demand warrants them. ConfigKit owns the underlying inspection semantics;
Scriptorium owns their application-facing presentation.
Resolution establishes configuration values. Runtime credentials, artifacts,
and downstream resources retain their respective preparation and execution
lifecycle. Promptkit owns its framework schema and domain rules when using
ConfigKit, consistent with [ADR 0004](0004-definition-boundary.md).
## Alternatives Considered
### Application-Owned Configuration Processing
Scriptorium could implement loading and composition locally. This offers
application-specific flexibility, but duplicates ConfigKit's responsibilities
and creates recurring maintenance and semantic drift across applications.
### ConfigKit-Owned Application Choices
Scriptorium could delegate discovery conventions and domain defaults to the
library. This reduces local decisions, but places application-specific behavior
in a shared configuration mechanism. The selected boundary keeps those choices
with the application while using the library's processing semantics.
## Consequences
Configuration changes follow the ownership boundary: processing capabilities
belong in ConfigKit, and application rules use its supported extension points.
ConfigKit upgrades are evaluated for their effects on Scriptorium's selected
inputs, domain callbacks, and operator interfaces.
The [architecture policy](../policy/architecture.md) owns current architectural
constraints, and the [configuration contract](../config.md) owns observable
application behavior. This ADR records the rationale for the ownership boundary.

View File

@@ -0,0 +1,53 @@
# ADR 0006: Adopt CommandKit's Native Operator Interfaces
## Status
Accepted. Complements [ADR 0004](0004-definition-boundary.md) and
[ADR 0005](0005-configkit-boundary.md). Both remain accepted and are not
superseded.
## Date
2026-11-19.
## Context
Scriptorium is adopting CommandKit's native operator interfaces within the
PromptKit and ConfigKit boundaries established by ADRs 0004 and 0005.
## Decision
Scriptorium adopts CommandKit's native operator interfaces.
ConfigKit owns configuration policy and everything in the configuration
lifecycle before the final, fully resolved configuration handoff. Application
schema and domain callbacks operate through ConfigKit's supported extension
points within that lifecycle.
PromptKit owns prompt definitions, preparation, execution, validation, and
inspection semantics. Its configuration is resolved through ConfigKit, with
PromptKit supplying its domain schema and rules through ConfigKit's supported
extension points.
Scriptorium owns the domain. After the handoff, it interprets the resolved
configuration values and uses them to perform useful work that satisfies the
user's request. It does not revise what constitutes effective configuration.
It supplies requests through PromptKit's supported APIs and uses the returned
results without redefining their meaning.
CommandKit's `ckconfig` and `ckprompt` integrations expose upstream ConfigKit
and PromptKit features. Scriptorium neutrally makes those features available
through the native interfaces, preserving upstream semantics.
## Alternatives Considered
Retaining custom configuration and prompt inspection would duplicate upstream
behavior and create another owner for its semantics. Use the native integrations
instead.
## Consequences
Standard inspection exposes the upstream result without constructing a different
effective document, reconciling separate explanation trees, or reinterpreting
upstream paths. The [adoption roadmap](../roadmap/commandkit-adoption.md) tracks
implementation.

View File

@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| Field | Required | Meaning | | Field | Required | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `prompt_id` | yes | Non-blank prompt ID. | | `prompt_id` | yes | Non-blank prompt ID. |
| `prompt_version` | no | Prompt version filter. |
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. | | `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
| `session_id` | no | Optional direct, non-secret session identifier. | | `session_id` | no | Optional direct, non-secret session identifier. |
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. | | `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
@@ -52,7 +51,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| `include_raw_output` | no | Include `raw_model_output` when true. | | `include_raw_output` | no | Include `raw_model_output` when true. |
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. | | `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. | | `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second limit for engine execution. Omitted, `null`, or `0` adds no deadline; positive values shorten the caller context deadline. | | `run_timeout_seconds` | no | Optional signed 64-bit whole-second engine operation budget. Omitted, `null`, or `0` adds no deadline. |
An input reference has a required `type` of `file` or `inline`. A `file` An input reference has a required `type` of `file` or `inline`. A `file`
reference requires `uri`; an `inline` reference requires `body`. reference requires `uri`; an `inline` reference requires `body`.
@@ -68,16 +67,17 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and `reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
framework credential semantics are defined by the framework credential semantics are defined by the
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md). [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
Explicit zero values for the numeric fields are overrides; zero Explicit zero values for the numeric fields are overrides; zero
`timeout_seconds` disables the per-attempt generation deadline only, retaining the `timeout_seconds` disables the per-attempt generation deadline only, retaining the
request context and configured transport cap. The timeout layers are defined in 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.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation). the [PromptKit v0.23.3 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
Each built-in transient retry gets a fresh generation timeout; the caller's Each built-in transient retry gets a fresh generation timeout; the caller's
request context remains the outer cancellation boundary. request context remains the outer cancellation boundary.
Raw API-key values are not accepted. `api_key` and any other unknown model Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
field cause `400 invalid_json`. and any other unknown field cause `400 invalid_json`. Prompt and profile IDs
are passed unchanged, including qualified collection IDs.
`model.reasoning_effort` is an optional JSON string with three states: omission `model.reasoning_effort` is an optional JSON string with three states: omission
inherits the selected profile, a non-empty string replaces its value, and an inherits the selected profile, a non-empty string replaces its value, and an
@@ -116,14 +116,14 @@ validation contract. The response contains:
optional `uri`; optional `uri`;
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus - `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
optional `errors` and `schema_path`; optional `errors` and `schema_path`;
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage, - `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
timing, validation, and repair-attempt metadata; and model parameters, input hashes, usage, and timing; and
- optional `raw_model_output` when requested. - optional `raw_model_output` when requested.
- optional `execution` when requested and a terminal observation exists. - optional `execution` when requested and a terminal observation exists.
`metadata.model_params` has `endpoint`, `model`, `temperature`, `metadata.model_params` has `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional `max_tokens`, `top_p`, and `timeout_seconds`, plus optional
`backend_id`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`. `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`, `metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable `total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
cache usage is reported as zero. cache usage is reported as zero.
@@ -132,10 +132,11 @@ When Promptkit resolves a direct or definition-rendered session ID,
`metadata.session_id` contains that effective result value. It is omitted when `metadata.session_id` contains that effective result value. It is omitted when
no effective session ID exists. no effective session ID exists.
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report `metadata.selected_backend_id` is omitted for an endpoint-only profile;
the corresponding Promptkit result fields independently when present. Both are Scriptorium does not infer backend identity from an endpoint. The redundant
omitted for an endpoint-only profile; Scriptorium does not infer backend `prompt_version`, `model_name`, `endpoint`, `validation_mode`,
identity from an endpoint. `validation_status`, `repair_attempts_used`, and `model_params.backend_id`
metadata members are not returned: use `model_params` and `validation`.
A validation failure has `validation.status: "failed"`, `is_valid: false`, A validation failure has `validation.status: "failed"`, `is_valid: false`,
and any available diagnostic errors, while still returning the artifact and and any available diagnostic errors, while still returning the artifact and
@@ -150,7 +151,7 @@ call was dispatched; if there is no terminal event, `execution` is omitted.
| Field | Meaning | | Field | Meaning |
| --- | --- | | --- | --- |
| `run_id`, `prompt_id`, `prompt_version`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. | | `run_id`, `prompt_id`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. | | `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. | | `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
| `status_code` | Provider status, omitted when unavailable. | | `status_code` | Provider status, omitted when unavailable. |
@@ -201,7 +202,7 @@ exceed it, the response is the compact `413 response_too_large` error without
| `400` | `prompt_render_failed` | Prompt template rendering failed. | | `400` | `prompt_render_failed` | Prompt template rendering failed. |
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. | | `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
| `404` | `not_found` | Route does not exist. | | `404` | `not_found` | Route does not exist. |
| `404` | `prompt_not_found` | Prompt ID or version does not exist. | | `404` | `prompt_not_found` | Prompt ID does not exist. |
| `404` | `profile_not_found` | Profile ID does not exist. | | `404` | `profile_not_found` | Profile ID does not exist. |
| `405` | `method_not_allowed` | The route does not accept the method. | | `405` | `method_not_allowed` | The route does not accept the method. |
| `408` | `request_canceled` | The caller context was canceled during a failed run. | | `408` | `request_canceled` | The caller context was canceled during a failed run. |
@@ -212,10 +213,11 @@ exceed it, the response is the compact `413 response_too_large` error without
| `500` | `internal_error` | Unclassified server failure. | | `500` | `internal_error` | Unclassified server failure. |
| `502` | `llm_failed` | Outbound model request failed. | | `502` | `llm_failed` | Outbound model request failed. |
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. | | `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
| `504` | `deadline_exceeded` | The execution context's deadline expired during a failed run. | | `504` | `deadline_exceeded` | PromptKit reports an operation timeout, or the parent deadline expired and the failed run wraps that deadline. |
These context outcomes require the execution context to have ended. A provider An operation timeout is checked before parent cancellation; a failed run
attempt timeout while it remains live retains `502 llm_failed`. A successful wrapping cancellation returns `408` when the parent is canceled. A provider
attempt timeout while the parent remains live retains `502 llm_failed`. A successful
run remains successful even if cancellation races with response formatting; run remains successful even if cancellation races with response formatting;
delivery after a client disconnect cannot be guaranteed. delivery after a client disconnect cannot be guaranteed.

View File

@@ -24,20 +24,24 @@ go run ./cmd/scriptorium render \
- `scriptorium render`: prepare a prompt and write prepared-run output. - `scriptorium render`: prepare a prompt and write prepared-run output.
- `scriptorium serve`: start the HTTP server. - `scriptorium serve`: start the HTTP server.
- `scriptorium inspect prompt`: inspect one prompt definition without model execution. - `scriptorium inspect prompt`: inspect one prompt definition without model execution.
- `scriptorium inspect profile`: inspect one effective profile without model execution. - `scriptorium inspect profile`: inspect one resolved profile without model execution.
- `scriptorium inspect configuration`: validate or inspect Promptkit's captured framework configuration.
- `scriptorium config validate`: validate application configuration without building an engine. - `scriptorium config validate`: validate application configuration without building an engine.
- `scriptorium config show`: show the resolved application configuration. - `scriptorium config show`: show the resolved application configuration.
- `scriptorium config sources`: show the ordered configuration sources. - `scriptorium config sources`: show the ordered configuration sources.
- `scriptorium config explain`: explain one effective or historical configuration path. - `scriptorium config explain`: explain one effective or historical configuration path.
All commands accept `--config <path>` and `--config-overlay <name>` and reject All command families accept `--config <path>` and `--config-overlay <name>`;
positional arguments. `--config-overlay` selects one application configuration positional arguments are rejected. `--config-overlay` selects one application
overlay; it is separate from `--profile`, which selects a Promptkit execution configuration overlay; it is separate from `--profile`, which selects a
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays) Promptkit execution profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
for name, root, and no-base behavior. `run`, for name, root, and absent-main behavior. `run`, `render`, `serve`, `inspect prompt`,
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`; `inspect profile`, and `inspect configuration` accept repeated
`inspect profile` does not. Supply the directory through the configuration `--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
contract or a supported `--prompt-dir` flag. Explicit application flags, They replace the configured source sequence in flag order. `--prompt-dir` and
`--profile-dir` are no longer supported; use `promptkit_sources` in application
configuration or the repeated source flags. Application `config` commands
remain independent of framework source loading. Explicit application flags,
including empty values, override file settings. Configuration load diagnostics including empty values, override file settings. Configuration load diagnostics
go to stderr and exit with status 1; successful load warnings are printed once go to stderr and exit with status 1; successful load warnings are printed once
before command work. before command work.
@@ -60,10 +64,8 @@ Optional flags:
| --- | --- | | --- | --- |
| `--config <path>` | Application configuration file. | | `--config <path>` | Application configuration file. |
| `--config-overlay <name>` | Selected application configuration overlay. | | `--config-overlay <name>` | Selected application configuration overlay. |
| `--prompt-dir <dir>` | Prompt-definition directory override. | | `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. | | `--schema-dir <dir>` | Schema base-directory override. |
| `--prompt-version <version>` | Optional prompt-definition version selector. |
| `--profile <id>` | Execution-profile override. | | `--profile <id>` | Execution-profile override. |
| `--session-id <id>` | Optional direct session identifier. | | `--session-id <id>` | Optional direct session identifier. |
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. | | `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
@@ -90,16 +92,15 @@ only; the caller context and configured transport cap remain active. CLI
durations are converted to whole seconds by truncation toward zero, so any durations are converted to whole seconds by truncation toward zero, so any
duration whose absolute value is below one second becomes an explicit duration whose absolute value is below one second becomes an explicit
zero-second override. The timeout layers are defined in the zero-second override. The timeout layers are defined in the
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation). [Promptkit outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
With the built-in client, each transient retry gets a fresh generation timeout; With the built-in client, each transient retry gets a fresh generation timeout;
this flag does not limit the complete run. this flag does not limit the complete run.
`--run-timeout` keeps subsecond precision and starts immediately before engine `--run-timeout` keeps subsecond precision and starts immediately before engine
execution. It bounds preparation, capacity waits, retry waits, generation, and execution. It bounds preparation, capacity waits, retry waits, generation, and
repairs where they honor context. Parsing, engine construction, and output repairs where they honor context. Parsing, engine construction, and output
writes are outside that interval. A failed run whose execution context reaches writes are outside that interval. A failed run identified by PromptKit as an
this deadline exits 1 with a safe deadline diagnostic; a completed invalid operation timeout exits 1 with a safe deadline diagnostic; a completed invalid
output still exits 2. It does not promise immediate interruption of synchronous output still exits 2. Synchronous work may not stop immediately.
work.
Omitting `--transient-retries` inherits the application setting or Promptkit's Omitting `--transient-retries` inherits the application setting or Promptkit's
current default of two additional attempts. The flag overrides only this current default of two additional attempts. The flag overrides only this
request; it does not alter the configured engine. Structural repair generations request; it does not alter the configured engine. Structural repair generations
@@ -107,10 +108,10 @@ have separate transient retry budgets.
There is no raw API-key flag. Use `--api-key-env`. There is no raw API-key flag. Use `--api-key-env`.
`--prompt-version` is passed directly to Promptkit. When it is omitted, the Prompt and profile IDs are passed unchanged, including collection-qualified
selected prompt ID must have exactly one available version. `--input` is IDs. The removed `--prompt-version` flag is rejected. `--input` is optional
optional at the CLI boundary: Promptkit decides whether the selected definition at the CLI boundary: PromptKit decides whether the selected definition requires
requires declared inputs or template-referenced values. declared inputs or template-referenced values.
`--session-id` supplies a direct, non-secret session identifier. A nonblank `--session-id` supplies a direct, non-secret session identifier. A nonblank
value replaces a definition-rendered session ID; an omitted or blank value lets value replaces a definition-rendered session ID; an omitted or blank value lets
@@ -157,7 +158,7 @@ scriptorium render [flags]
``` ```
`--prompt <id>` is required. The following optional flags are supported: `--prompt <id>` is required. The following optional flags are supported:
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`, `--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--profile`,
`--input`, `--var`, `--out`, `--llm-base-url`, `--input`, `--var`, `--out`, `--llm-base-url`,
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`, `--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding `--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding
@@ -172,6 +173,17 @@ include a retry field in prepared output.
`render` resolves profiles and schemas as part of preparation but `render` resolves profiles and schemas as part of preparation but
does not call an LLM. does not call an LLM.
To render from independently maintained collection checkouts:
```bash
go run ./cmd/scriptorium render --config ./examples/config.discovery.yml \
--prompt support/answer --profile support/fast \
--input transcript=./examples/fixtures/transcript.md
```
The [discovery example](../examples/discovery/framework.yml) also provides
`review/answer`; see [configuration discovery](config.md#collection-checkout-discovery).
## `scriptorium serve` ## `scriptorium serve`
```text ```text
@@ -185,8 +197,7 @@ Optional flags:
| `--config <path>` | Application configuration file. | | `--config <path>` | Application configuration file. |
| `--config-overlay <name>` | Selected application configuration overlay. | | `--config-overlay <name>` | Selected application configuration overlay. |
| `--addr <listen-address>` | HTTP listen-address override. | | `--addr <listen-address>` | HTTP listen-address override. |
| `--prompt-dir <dir>` | Prompt-definition directory override. | | `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
| `--profile-dir <dir>` | Custom profile-directory override. |
| `--schema-dir <dir>` | Schema base-directory override. | | `--schema-dir <dir>` | Schema base-directory override. |
| `--artifact-root <dir>` | Root for HTTP `file` input references. | | `--artifact-root <dir>` | Root for HTTP `file` input references. |
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. | | `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
@@ -199,27 +210,42 @@ schemas, and error codes are defined in the [HTTP API reference](api.md).
## `scriptorium inspect prompt` ## `scriptorium inspect prompt`
```text ```text
scriptorium inspect prompt --prompt ID [--prompt-version VERSION] scriptorium inspect prompt --prompt ID
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH] [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
``` ```
`--prompt` is required. Inspection uses normal configuration discovery and a `--prompt` is required. Inspection uses normal configuration discovery and the
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`, selected Promptkit sources, defaults to text regardless of
and writes to stdout unless `--out` is supplied. It loads and normalizes the `defaults.render_format`, and writes to stdout unless `--out` is supplied.
selected definition but does not resolve a profile, load a schema, render a
template, reserve backend capacity, or call a model. Both definition-inspection commands first construct the same engine used for
execution from the complete selected source sequence. Construction resolves
and validates all effective definitions, including unused ones, and captures
referenced message-file contents and static template syntax. Invalid unused
definitions or unreadable message resources can therefore prevent inspection.
No prompt collection is mandatory, but selected prompts are not ignored.
Inspection does not prepare an execution request, load request-time schemas or
artifacts, resolve credential values, reserve backend capacity, or call a model.
Prompt inspection does not select an execution profile or render request-specific
templates.
Prompt output includes ID, hash, optional default profile and input metadata,
and the output contract. Absent optional values are omitted; explicitly empty
or zero values are retained. Captured message text is not projected.
## `scriptorium inspect profile` ## `scriptorium inspect profile`
```text ```text
scriptorium inspect profile --profile ID scriptorium inspect profile --profile ID
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH] [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
``` ```
`--profile` is required; built-in profiles need no prompt directory. Inspection `--profile` is required. After the [full-source engine construction described
resolves profile inheritance and backend defaults, but never reads a credential above](#scriptorium-inspect-prompt), inspection selects one resolved profile
value, loads a prompt, reserves capacity, or calls a model. Unset provider with inheritance. `profile_model_params` contains only fields present on that
controls are shown as zero values when Promptkit leaves them unspecified. profile; it does not fill backend defaults. `api_key_required` is a separate
optional field. Explicit zero and empty values remain visible. Use `render`
for request-completed model settings.
## Application configuration inspection ## Application configuration inspection
@@ -230,19 +256,20 @@ scriptorium config sources [flags]
scriptorium config explain --path JSON_POINTER [flags] scriptorium config explain --path JSON_POINTER [flags]
``` ```
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, Each accepts `--config`, `--config-overlay`, `--schema-dir`, `--addr`,
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`, `--artifact-root`, `--max-request-bytes`,
`--max-artifact-bytes`, and `--max-response-bytes`. These are application `--max-artifact-bytes`, and `--max-response-bytes`. These are application
configuration selectors and overrides; request, credential, backend-editing, configuration selectors and overrides; request, credential, backend-editing,
output-format, and output-file flags are not accepted. Positional arguments output-format, and output-file flags are not accepted. Positional arguments
are rejected. are rejected.
`validate` writes no success output; status 0 means the application configuration `validate` writes no success output; status 0 means the application configuration
loaded and passed its own validation. It does not establish that a prompt loaded and passed its own validation. It does not establish that selected
directory exists, credentials are present, or Promptkit can construct an Promptkit sources can construct an engine, credentials are present, or a
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources` provider is available. `show` writes ConfigKit's resolved YAML snapshot. `sources`
writes one newline-terminated JSON array of source records in load order. Each writes one newline-terminated JSON array of source records in load order. Each
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI record has `id`, `label`, and `layer`, plus `path` when available. Application
main-file and import records use the `main` layer; explicit CLI
overrides appear as synthetic sources. Defaults-only input without overrides overrides appear as synthetic sources. Defaults-only input without overrides
produces `[]` for `sources`. produces `[]` for `sources`.
@@ -251,18 +278,64 @@ The empty string selects the root; `/server/addr` selects a field; `~1` and
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted `~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
according to the containing mapping or sequence. Dotted paths, file paths, according to the containing mapping or sequence. Dotted paths, file paths,
and URL fragments are not accepted. ConfigKit writes a human-readable account and URL fragments are not accepted. ConfigKit writes a human-readable account
of the effective value and its chronological default, base, overlay, CLI, of the effective value and its chronological default, file/import, overlay,
and normalization history, including removed historical values. This is not a CLI, normalization, and removed-value history. This is not a JSON schema or a
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
exit 1 without successful explanation output. successful explanation output.
Diagnostics and warnings go to stderr, never into successful stdout. Parse, Diagnostics and warnings go to stderr, never into successful stdout. Parse,
load, output, and diagnostic-write failures exit 1. Ordinary output writes may load, output, and diagnostic-write failures exit 1. Ordinary output writes may
leave partial data on failure. The inspection output can contain paths, leave partial data on failure. Application inspection can contain paths and
identifiers, `api_key_env` reference names, and ordinary `extra_params` values, configured values; protect its output accordingly. Raw API-key values are not
including displaced historical values in explanations; accepted by the application configuration schema.
protect it accordingly. Raw API-key values are not read or emitted by these
commands. ## Framework configuration inspection
```text
scriptorium inspect configuration validate [flags]
scriptorium inspect configuration show [flags]
scriptorium inspect configuration sources [flags]
scriptorium inspect configuration explain --path JSON_POINTER [flags]
```
Each operation accepts `--config`, `--config-overlay`, repeatable
`--promptkit-source`, and `--schema-dir`. These flags select the application
settings and framework sources; positional arguments, `--format`, and `--out`
are not accepted. Unlike `config validate`, framework `validate` constructs
the Promptkit engine and validates all effective definitions, including
unused ones. It writes nothing on success and does not prepare a request,
resolve a credential, or contact a provider.
`show` writes Promptkit's native effective YAML, an inspection snapshot rather
than a promised reloadable file. `sources` writes a
newline-terminated JSON array in captured source order. Each source record has
`id`, `label`, `layer`, `kind`, and `underlay_index`, plus `path` when available
and `imported_from` for imported sources. That nested object has `source_id`,
`line`, and `column`. Values and output structure are a projection of the
captured Promptkit view, not Scriptorium's application-source records.
`explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
syntax; `--path ''` selects the root. For example,
`/collections/support/profiles/0/model` addresses the first support profile's
model in the captured list. Escape `/` as `~1` and `~` as `~0`; dots in a key
remain literal. Malformed and unknown pointers exit 1 without a successful
report. Explanation prose is native and is not a stable machine-readable
format.
Framework `show` and `explain` use Promptkit's native redaction for its
classified credential-shaped provider fields, including historical values.
Environment-variable reference names and ordinary provider parameters remain
visible. Arbitrary prompt or provider content is not classified as secret by
name inspection, so treat these reports as sensitive. This redaction policy is
limited to framework configuration reports; it does not add redaction to
`inspect profile` or prepared-run output. Credentials are not resolved by any
of these inspection operations. Promptkit owns detailed field and source
semantics; see its tagged [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
Warnings and errors go to stderr. Successful `validate` writes nothing to
stdout; successful `show`, `sources`, and `explain` write their reports there.
Parse, load, path, and output failures exit 1. A native writer error may leave
partial output.
## Input And Variable Syntax ## Input And Variable Syntax

View File

@@ -1,68 +1,161 @@
# Configuration Reference # Configuration Reference
This is the canonical reference for Scriptorium application settings. Prompt, This is the canonical reference for Scriptorium application settings. Prompt,
profile, schema, execution-setting, built-in profile, and framework credential profile, backend, schema, execution-setting, built-in profile, and framework
semantics are defined by the credential semantics are defined by the
[Promptkit v0.11.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md). [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
outcomes, see the [HTTP API reference](api.md). outcomes, see the [HTTP API reference](api.md). For migration examples, see
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
## Discovery And Precedence ## Discovery And Precedence
Application settings are resolved in this order: ConfigKit assembles the selected main source, imports, and overlay, resolves
inheritance, and decodes the result with Scriptorium's typed defaults. It then
1. built-in Scriptorium defaults; applies explicitly supplied application CLI values, records application
2. a configuration file; then normalization, and validates the result. Source, composition, inheritance, and
3. CLI overrides. decoding failures happen before CLI assignment and cannot be repaired by it;
an override can correct a decoded value before application validation.
When `--config` is omitted, Scriptorium searches When `--config` is omitted, Scriptorium searches
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`. `/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
If neither exists, it uses built-in defaults. An explicit `--config` path must ConfigKit performs this ordered search for each load. If neither exists, it
exist and decode successfully. uses built-in defaults; an error in a selected candidate does not cause a
fallback. An explicit `--config` path must exist and decode successfully,
including when an empty path is explicitly supplied.
The maintained [minimal configuration](../examples/config.yml), The maintained [minimal configuration](../examples/config.yml),
[complete configuration](../examples/config.full.yml), and [complete configuration](../examples/config.full.yml),
[composed configuration](../examples/config.composed.yml) are copyable examples. [composed configuration](../examples/config.composed.yml),
[collection configuration](../examples/config.collections.yml), and
[framework inheritance configuration](../examples/config.inheritance.yml) are
copyable examples.
## Application Configuration File ## Application Configuration File
Configuration is decoded by ConfigKit v0.4.0 as strict YAML. Unknown fields, Application configuration is decoded by ConfigKit v1.2.1 as strict YAML.
empty files, multiple YAML documents, and YAML aliases/anchors are rejected. Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
An explicit empty string is a value: it clears a file-provided optional path are rejected.
or, for required `prompt_dir`, fails the command's prerequisite. A scalar An explicit empty string is a value and may clear a file-provided optional
`null` is not an empty string and is rejected for scalar fields; nullable string. A scalar `null` is not an empty string and is rejected for non-nullable
fields such as `transient_retries` retain their documented meaning. Raw fields; nullable fields such as `transient_retries` retain their documented
API-key fields are not accepted. meaning. Raw API-key fields and unknown application fields are rejected.
ConfigKit applies defaults, the selected file, then only explicitly supplied Only explicitly supplied application CLI flags override decoded settings. Paths
application CLI flags before validating the result. Paths in the application in the application document remain relative to the process working directory, not to the file's
document remain relative to the process working directory, not to the file's
directory. Load diagnostics are printed safely on stderr; invalid application directory. Load diagnostics are printed safely on stderr; invalid application
configuration exits with status 1. configuration exits with status 1.
### Promptkit source selectors
`promptkit_sources` is an ordered sequence of explicit Promptkit source
selectors. Each item must set exactly one of `file` or `directory`:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
```
An empty or null final resolved `promptkit_sources` list selects no
application-supplied framework sources; PromptKit's bundled OpenRouter underlay
still applies. A later sequence item overlays an earlier
one. Files within a selected directory are composed together, so conflicting
definitions in that group fail instead of using filename order as precedence.
An explicit file may use ConfigKit imports. The complete framework format and
source rules belong to the [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
Selector paths are relative to the process working directory, not to the
application configuration file. Application validation checks the selector
shape but does not open or validate Promptkit sources. `config validate`
therefore does not prove that selected sources can build an engine; use
`inspect configuration validate` for that separate check. Repeated
`--promptkit-source` flags replace the entire configured selector sequence
and preserve flag order. Without an authored collection policy, a selected
overlay replaces `promptkit_sources` as a whole; a declared sequence policy
may instead combine the lists.
### Collection checkout discovery
Select a framework discovery file using the existing file selector, as in
[config.discovery.yml](../examples/config.discovery.yml). Its native imports
select both supported collection-entry spellings:
```yaml
config:
imports:
- glob: collections/*/collection.yml
- glob: collections/*/collection.yaml
```
Both globs are optional, so either spelling may have no matches. Paths are
relative to the framework file; this example's `*` selects one checkout
level and is not a general layout restriction. Each entry declares its own
collection namespace and imports only its intended resource fragments. The
checkout directory name does not determine the namespace. New checkouts are
available on the next invocation without editing this file; a running server
does not reload them. See the [maintained collection examples](../examples/discovery/collections/).
Entries imported by one discovery file are composed together as peers.
Conflicting definitions of the same qualified resource ID fail to load;
filename, checkout, and glob order do not set precedence. To override a
discovered record, select a separate framework file later in
`promptkit_sources` and supply the complete replacement record.
### Explicit imports and selected overlays ### Explicit imports and selected overlays
A file-backed configuration may declare `configkit.imports` with relative Application files declare imports under root `config.imports`. Native `path`,
`path` or `glob` entries. Each entry is explicit; Scriptorium does not scan `dir`, and `glob` selectors, filters, recursion, destinations, and item
for fragments on its own. ConfigKit composes the selected file and imports by placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md).
conflict, so two fragments cannot define the same field merely to establish Imports are optional by default; set `required: true` when absence must fail.
precedence. A required missing import fails; an entry may use The old `optional` field is not supported. Directory selection has no default
`optional: true` to suppress target nonexistence. Imports are resolved from filename filter; author a pattern when only YAML files are intended. ConfigKit
the declaring file's canonical directory and remain within the selected composes peer sources strictly, rather than using filename order to resolve
file's canonical directory by default. Scriptorium does not widen that root. conflicts. Imports are resolved relative to their declaring file within the
native source root. Scriptorium does not widen that root.
Root `config.sequences` can declare an identity key and merge mode for a
collection. Scriptorium does not register or infer an identity for
`promptkit_sources`: absent an authored policy, unkeyed lists replace across
precedence boundaries. The [collection example](../examples/config.collections.yml)
declares `file` identity with `upsert`, combines imported file selectors, and
lets an overlay add another. CLI list overrides still replace the whole list.
At application precedence boundaries, omission preserves lower-precedence
selectors. Under ordinary list replacement, `[]` clears the selection and
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
contributes no records and `null` is invalid. To clear a collection with an
inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md#yaml-declarations-and-policy-lifetime)
for policy lifetime and combination rules.
These application root `config` controls do not change the separate
PromptKit v0.23.3 framework format: its selected framework files use the
[Promptkit contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
and their own native ConfigKit `config` controls.
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that `--config-overlay NAME` selects one file at `overlays/NAME.yml` below that
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
and exact lowercase `default` select no overlay. There is no fallback, and exact lowercase `default` select no overlay. There is no fallback,
case folding, inherited stack, or automatic selection; a missing selected case folding, inherited stack, or automatic selection; a missing selected
overlay fails. ConfigKit merges mapping fields and replaces other values, overlay fails. Mappings merge; sequence contributions and nulls at collection
including sequences and explicit nulls, before applying explicit CLI flags. destinations follow the effective collection policy described above. Other
An active overlay needs a selected base file. No-source defaults-only loads explicit nulls replace lower values subject to the application schema.
cannot use imports or an active overlay. Defaults-only loading can enable imports, but an absent main has no import
declarations. This CLI supplies no independent overlay root, so an active
overlay cannot be located without a selected main context. That is not a general
ConfigKit restriction.
The [composed example](../examples/config.composed.yml) imports two fragments The [composed example](../examples/config.composed.yml) imports the application
and has a selectable [local overlay](../examples/overlays/local.yml). From the [source-selection fragment](../examples/config-fragments/sources.yml) and has
repository root: a selectable [local overlay](../examples/overlays/local.yml). That fragment
selects the [framework backend file](../examples/framework/backends.yml) through
`promptkit_sources`; backend definitions are not imported into the application
document. From the repository root:
```bash ```bash
go run ./cmd/scriptorium render \ go run ./cmd/scriptorium render \
@@ -72,15 +165,25 @@ go run ./cmd/scriptorium render \
--input glossary=./examples/fixtures/glossary.yml --input glossary=./examples/fixtures/glossary.yml
``` ```
Import and overlay file locations are constrained by ConfigKit; Inspect the collection overlay and render without contacting a provider:
*application path values* such as `prompt_dir` remain relative
to the process working directory even when authored in a fragment or overlay. ```bash
These source constraints are separate from HTTP artifact containment. go run ./cmd/scriptorium config show --config ./examples/config.collections.yml --config-overlay collection
go run ./cmd/scriptorium render --config ./examples/config.collections.yml --config-overlay collection \
--prompt generic.markdown_summary \
--input transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml
```
Import and overlay file locations are constrained by ConfigKit; application
path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root`
remain relative to the process working directory even when authored in a
fragment or overlay. These source constraints are separate from Promptkit
message-resource paths and HTTP artifact containment.
| Field | Default | Meaning | | Field | Default | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. | | `promptkit_sources` | empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. |
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. | | `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
| `server.addr` | `:8080` | Address used by `serve`. | | `server.addr` | `:8080` | Address used by `serve`. |
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. | | `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
@@ -88,7 +191,6 @@ These source constraints are separate from HTTP artifact containment.
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. | | `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. | | `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. | | `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. | | `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
The size fields must be zero or greater. The [HTTP API](api.md) defines how The size fields must be zero or greater. The [HTTP API](api.md) defines how
@@ -96,55 +198,31 @@ each limit is enforced and reported. `server.artifact_root` configures an HTTP
deployment boundary; see [operations](operations.md) for deployment handling. deployment boundary; see [operations](operations.md) for deployment handling.
The `config validate`, `config show`, `config sources`, and `config explain` The `config validate`, `config show`, `config sources`, and `config explain`
commands inspect this commands inspect this application configuration without creating a Promptkit
application configuration without creating a Promptkit engine. `show` is a engine. `show` is a resolved inspection snapshot, not necessarily a reloadable
resolved inspection snapshot, not necessarily a reloadable file. Application file. Application validation does not check framework sources, backend
validation does not check framework sources, backend connectivity, or credential connectivity, or credential availability. Use `inspect configuration` for
availability. `api_key_env` is an environment-variable *name* and remains Promptkit's separately captured framework configuration; its four operations
visible in inspection; its environment value is never read by ConfigKit. are documented in the [CLI reference](cli.md#framework-configuration-inspection).
Ordinary backend `extra_params` values also remain visible, so keep secrets out
of those fields and protect inspection output as potentially sensitive.
`config explain --path /server/addr` uses JSON Pointer syntax to show the `config explain --path /server/addr` uses JSON Pointer syntax to show the
selected field's current value and history from defaults, files, overlays, selected field's current value and history from defaults, files, overlays,
explicit CLI overrides, and normalization. `--path ''` selects the root. explicit CLI overrides, and normalization. `--path ''` selects the root.
History includes replaced and removed values; `show` presents the final History includes replaced and removed values; `show` presents the final
resolved snapshot. Neither renderer looks up credential bytes, and neither resolved snapshot. The application schema rejects raw credential fields, but
claims to identify arbitrary secrets in unclassified parameter values. do not treat inspection as a general-purpose filter for sensitive strings.
## Custom Backends
Use `backends` when a profile selects an application-defined backend ID:
```yaml
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
```
Each mapping key is the case-sensitive backend ID. `endpoint` is required;
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
`queue_capacity` lets Promptkit use its default for a limited backend, while
an explicit `queue_capacity: 0` disables queueing.
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
validates backend IDs, endpoints, environment-variable names, extra parameters,
and capacity relationships when Scriptorium constructs its engine. There are no
backend command-line overrides. Store only an environment-variable name in
`api_key_env`; raw API-key fields are not accepted.
## Framework Source Mapping ## Framework Source Mapping
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit Scriptorium assembles selected Promptkit source files and directories in the
when constructing its engine. Scriptorium does not redefine or independently order described above, then constructs the Promptkit engine. Framework
parse those framework file formats. definitions and custom backends belong in those selected source files, not in
the Scriptorium application configuration. Message `content_file` paths use
the defining source's resource context and are captured when the engine is
constructed; schema and request-artifact loading remain preparation-time
operations. Scriptorium does not redefine or independently parse framework
file formats.
- Prompt selection, versions, message templates, inputs, output contracts, and - Prompt selection by ID, message templates, inputs, output contracts, and
session IDs are Promptkit contracts. session IDs are Promptkit contracts.
- Profile fields, numeric ranges, execution defaults, overlay precedence, - Profile fields, numeric ranges, execution defaults, overlay precedence,
built-in profiles, and credential rules are Promptkit contracts. built-in profiles, and credential rules are Promptkit contracts.
@@ -152,19 +230,18 @@ parse those framework file formats.
contracts. contracts.
See the See the
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) [tagged Promptkit format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
for all of those definitions. The files under for all of those definitions. The files under
[`examples/prompts`](../examples/prompts/), [`examples/prompts`](../examples/prompts/),
[`examples/profiles`](../examples/profiles/), and [`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium [`examples/schemas`](../examples/schemas/) are maintained Scriptorium
application inputs using that tagged format. application inputs using that tagged format.
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and PromptKit supplies a default-on OpenRouter bundle as the lowest-priority
`promptkit-openrouter-auto`. They can be selected as a prompt default or request underlay. Choose an actual bundled profile such as `auto`, or a complete
profile, and custom profile sources retain precedence. Their effective model application-owned profile; old catalog IDs are not aliases. Caller definitions
settings may change with a catalog upgrade; use a complete application-owned can replace bundled records by normal composition. Bundle availability is not
profile when fixed settings are required. See the tagged format reference for a readiness check or a promise of a fixed provider model.
the maintained-profile contract.
## Credentials And Outbound Behavior ## Credentials And Outbound Behavior
@@ -195,7 +272,7 @@ client retains its own retry behavior. The tagged integration contract owns
eligibility and timing. eligibility and timing.
Promptkit's Promptkit's
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md) [OpenAI-compatible integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
defines outbound authentication, provider request mapping, transport limits, defines outbound authentication, provider request mapping, transport limits,
and timeout layering. and timeout layering.
@@ -204,4 +281,4 @@ and timeout layering.
- [CLI reference](cli.md) - [CLI reference](cli.md)
- [HTTP API reference](api.md) - [HTTP API reference](api.md)
- [Operations guide](operations.md) - [Operations guide](operations.md)
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) - [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)

View File

@@ -13,8 +13,8 @@ and the HTTP service according to the boundary your application needs.
- Application configuration: [configuration reference](../config.md) - Application configuration: [configuration reference](../config.md)
Go applications that need an in-process prompt framework should import Go applications that need an in-process prompt framework should import
Promptkit directly. The tagged `go.maximumdirect.net/promptkit` directly. The tagged
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md) [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
owns that interface; Scriptorium does not provide a Go library package. owns that interface; Scriptorium does not provide a Go library package.
Consumers arriving from the former Scriptorium Go API should follow the Consumers arriving from the former Scriptorium Go API should follow the
[migration guide](migrating-to-promptkit.md). [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 and can incur another provider request. CLI exits belong to the
[CLI reference](../cli.md), HTTP status behavior belongs to the [CLI reference](../cli.md), HTTP status behavior belongs to the
[HTTP API reference](../api.md), and framework semantics belong to [HTTP API reference](../api.md), and framework semantics belong to
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md). [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).

View File

@@ -1,10 +1,16 @@
# Migrate From Scriptorium To Promptkit # Migrate From Scriptorium To Promptkit
This historical first hop targets Promptkit v0.11.1 and its former module
path. For the current public module `go.maximumdirect.net/promptkit` and the
ID-only configuration cutover, follow the
[current upgrade guide](upgrading-promptkit.md) afterward and consult the
[current Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
## Supported Migration Boundary ## Supported Migration Boundary
Scriptorium `v0.11.1` at Scriptorium `v0.11.1` at
`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides `gitea.maximumdirect.net/eric/scriptorium` is the final release that provides
the former in-process Go framework. Promptkit `v0.11.0` at the former in-process Go framework. Promptkit `v0.11.1` at
`gitea.maximumdirect.net/eric/promptkit` is the destination for that framework `gitea.maximumdirect.net/eric/promptkit` is the destination for that framework
API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only. API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only.
@@ -19,7 +25,7 @@ Start from a clean consumer checkout and review the pending diff before
committing it. Add the published Promptkit module: committing it. Add the published Promptkit module:
```sh ```sh
go get gitea.maximumdirect.net/eric/promptkit@v0.11.0 go get gitea.maximumdirect.net/eric/promptkit@v0.11.1
``` ```
For an ordinary consumer that imports the former root package under its For an ordinary consumer that imports the former root package under its
@@ -51,14 +57,14 @@ go mod tidy
go test ./... go test ./...
``` ```
Confirm that `go.mod` selects Promptkit `v0.11.0` and that no Go file imports Confirm that `go.mod` selects Promptkit `v0.11.1` and that no Go file imports
the former Scriptorium package: the former Scriptorium package:
```sh ```sh
test "$( test "$(
go list -m -f '{{.Path}}@{{.Version}}' \ go list -m -f '{{.Path}}@{{.Version}}' \
gitea.maximumdirect.net/eric/promptkit gitea.maximumdirect.net/eric/promptkit
)" = 'gitea.maximumdirect.net/eric/promptkit@v0.11.0' )" = 'gitea.maximumdirect.net/eric/promptkit@v0.11.1'
if git grep -n \ if git grep -n \
'gitea.maximumdirect.net/eric/scriptorium' \ 'gitea.maximumdirect.net/eric/scriptorium' \
-- '*.go' -- '*.go'
@@ -73,20 +79,20 @@ fi
Promptkit preserves the established engine, request, result, profile, Promptkit preserves the established engine, request, result, profile,
source-option, model-client, artifact, validation-value, and public-error source-option, model-client, artifact, validation-value, and public-error
shapes where practical. Exact declarations and current behavior belong to the shapes where practical. Exact declarations and current behavior belong to the
tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md) tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md)
and Go source. and Go source.
Promptkit also includes migration-relevant public contracts that were not in Promptkit also includes migration-relevant public contracts that were not in
Scriptorium `v0.11.1`: Scriptorium `v0.11.1`:
- [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/engine.go#L169-L174) - [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L169-L174)
and the and the
[`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/types.go#L315) [`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/types.go#L315)
provide the artifact-reading extension described by the tagged provide the artifact-reading extension described by the tagged
[extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md#extension-interfaces). [extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#extension-interfaces).
- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/engine.go#L33-L48) - [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L33-L48)
provide the specific identities described by the tagged provide the specific identities described by the tagged
[error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md#handle-errors). [error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#handle-errors).
Use those tagged owners for exact signatures, wrapping guarantees, and Use those tagged owners for exact signatures, wrapping guarantees, and
extension behavior. extension behavior.

View File

@@ -0,0 +1,110 @@
# Upgrade PromptKit Sources And Definitions
This guide covers the CLI and framework configuration cutover to
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md)
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
for the full upstream contract.
Removing version selectors and changing framework definition shapes are
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
## Application configuration
Existing application fields that already select the desired sources retain
their meaning. For example, this application configuration works both before
and after the cutover:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
```
The selected framework files must still be rewritten as described below.
Scriptorium uses one native application schema: discovery, imports, selected
overlays, source order, explicit overrides, and working-directory-relative
selector paths remain application configuration behavior. It loads framework
sources separately with PromptKit's schema. No second application schema or
legacy definition reader is provided. See the [configuration reference](../config.md).
## Rewrite framework definitions
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing `id`. For example, before:
```yaml
prompts:
report:
"1":
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
fast:
endpoint: https://example.invalid/v1
model: synthetic-model
```
After:
```yaml
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
```
Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
versions must remain independently selectable, give them distinct IDs and
update callers. Qualified IDs such as `support/answer` are passed unchanged.
PromptKit resolves `content_file` relative to the source that supplied the
field, including imported or inherited definitions. The
[framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md#messages-and-templates)
describes which paths are allowed within the source root.
Convert framework source controls from `configkit:` to `config:` and add
`required: true` for imports that must exist. An optional framework source
header, if present, is `version: 2`. Use sibling inheritance such as
`extends: {id: base}`.
Across ordered `promptkit_sources` entries, a later framework underlay replaces
the whole record for the same ID. Supply the complete intended replacement,
or create a distinct inherited record. Checkouts imported by the same
[discovery file](../config.md#collection-checkout-discovery) are peers:
conflicting definitions of the same ID fail instead of overriding one another.
Null profile endpoint, credential, or provider-map settings can fall
back to the selected backend; review behavior rather than assuming null clears
backend values. Keep JSON schemas self-contained instead of depending on remote
schema references. Application selectors remain separate from these framework
semantics.
## Replace catalog selections
The default-on OpenRouter bundle supplies actual profiles such as `auto` and
`gpt-sol-latest`. Former catalog and `promptkit-openrouter-*` IDs are not
compatibility aliases. Choose an intended current bundled profile explicitly,
or define a complete local profile with the endpoint, model, and settings you
need. Do not assume a new default model. The bundle is an underlay and caller
records can replace it through ordinary composition.
For multiple independently maintained repositories, see the
[collection-discovery example](../../examples/config.discovery.yml). Its
entry files declare their own namespaces; checkout names do not become IDs.
The [CLI reference](../cli.md) demonstrates qualified rendering and the
[operations guide](../operations.md) describes when updates take effect.

View File

@@ -2,23 +2,41 @@
This is the contributor entry point for Scriptorium. Scriptorium is an This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public application that consumes the public
[Promptkit v0.11.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md); [PromptKit v0.23.3 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md);
framework implementation work belongs in Promptkit. Application configuration framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v0.4.0; keep Scriptorium's schema and source selection local. uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
PromptKit uses the same ConfigKit release to load framework sources under its
own separate schema and format contract.
## Initial Orientation ## Initial Orientation
Before recommending, planning, or implementing work: Before recommending, planning, or implementing work:
1. read the [agent policy](policy/agents.md); 1. inspect the working tree and preserve unrelated changes;
2. inspect the working tree and preserve unrelated changes; 2. use the policy and task-specific reading guides below; and
3. read the [architecture policy](policy/architecture.md); 3. inspect the relevant implementation and tests before changing them.
4. follow the task-specific contracts and internal documents below; and
5. inspect the relevant implementation and tests before changing them.
Also read the [documentation policy](policy/documentation.md) before changing ## Policy Reading Guide
documentation and the [testing policy](policy/testing.md) before changing
tests. | Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
- Read applicable policies before making decisions they govern; multiple policies
may apply.
- Select policies using the task triggers above. Follow cross-references to
relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer
available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere
affected by the revision.
## Task-Specific Reading Guide ## Task-Specific Reading Guide
@@ -29,21 +47,31 @@ tests.
| 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) | | 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 | | 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` | | 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.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.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) |
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md) | | Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.3 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md) |
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) | | Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
| Runtime operation or recovery | [Operations](operations.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) | | 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) | | 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.0/docs/formats.md), and the related files under `examples/` | | Examples or copyable assets | The owning Scriptorium contract, the relevant [PromptKit v0.23.3 format contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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 | | 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 Cross-project changes land and release in Promptkit before Scriptorium adopts
the tagged version. Do not commit a Go workspace, local replacement, vendored the tagged version. Do not commit a Go workspace, local replacement, vendored
Promptkit source, or an import of a Promptkit `internal` package. Promptkit source, or an import of a Promptkit `internal` package.
The module graph can include upstream maintainer tools such as ReleaseKit and
their dependencies even though those graph-only packages are not linked into
the Scriptorium runtime; use `go list -deps ./cmd/scriptorium` to distinguish
the linked packages.
## Baseline Validation ## Baseline Validation
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
required by application ConfigKit v1.2.1. Running a published binary does not
require a Go installation. Release validation and builds use
the separately selected toolchain in the [release procedure](release.md).
For code changes, run: For code changes, run:
```bash ```bash

View File

@@ -55,8 +55,9 @@ protocol.
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
engine invocation. It is separate from the per-attempt generation timeout and engine invocation. It is separate from the per-attempt generation timeout and
does not include child startup or output writing. A deadline failure exits 1; does not include child startup or output writing. A typed operation deadline
supervisors still own process termination when they need to stop the child failure exits 1.
Supervisors still own process termination when they need to stop the child
outside that engine interval. outside that engine interval.
For deployment, filesystem permissions, and sensitive-artifact handling, see For deployment, filesystem permissions, and sensitive-artifact handling, see

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 External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is [HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged described by its tagged
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md). [Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
## Components And Collaborators ## Components And Collaborators
@@ -17,11 +17,14 @@ described by its tagged
`internal/adapter/cli`. `internal/adapter/cli`.
- `internal/adapter/cli` resolves settings through `internal/config`, - `internal/adapter/cli` resolves settings through `internal/config`,
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`, 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, - `internal/config` delegates application YAML decoding, default resolution,
overrides, and validation ordering to ConfigKit. The CLI supplies only overrides, and validation ordering to ConfigKit v1.2.1. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr. load diagnostics on stderr. PromptKit uses the same ConfigKit release to
load framework sources under its own definition and format contract. Both
domains use ConfigKit's native diagnostic writer.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit - `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs. and errors to HTTP DTOs.
@@ -35,7 +38,7 @@ described by its tagged
### CLI ### CLI
`run` calls `promptkit.Engine.Run`; `render` calls `run` calls `promptkit.Engine.Run`; `render` calls
`promptkit.Engine.Prepare`. Both share request mapping for prompt ID/version `promptkit.Engine.Prepare`. Both share request mapping for exact prompt ID
and profile selection, optional file inputs, variables, and presence-aware and profile selection, optional file inputs, variables, and presence-aware
execution overrides. Omitted framework settings remain zero values so Promptkit execution overrides. Omitted framework settings remain zero values so Promptkit
resolves its own defaults and definition-required inputs. resolves its own defaults and definition-required inputs.
@@ -44,14 +47,26 @@ run/render flag enters only the mapped request. The server uses the same engine
setting and retains one backend admission state. Render prepares without setting and retains one backend admission state. Render prepares without
generation. generation.
`inspect prompt` maps the selected ID and optional version to `inspect prompt` maps the selected ID to
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection `promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
data. It constructs the same configuration-aware engine but does not perform data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile`
preparation or generation. and formats Scriptorium-owned resolved profile data without backend completion.
`inspect profile` maps an explicit profile ID to `Engine.InspectProfile` and Both paths construct the same full-source engine as execution before inspecting
formats a safe application-owned effective profile view. It intentionally does the chosen definition; selected prompts are not filtered out. They do not
not require prompt, schema, or artifact sources. perform request preparation or generation. The [CLI definition-inspection
contract](../cli.md#scriptorium-inspect-prompt) owns the loading and runtime
boundaries, including the distinction between an optional prompt collection
and validating any prompts that were selected.
`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 The `config` family loads the same application ConfigKit result once and uses
its validation, effective-output, source, and explanation views directly. It its validation, effective-output, source, and explanation views directly. It
@@ -62,11 +77,14 @@ JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
with `promptkit.WithArtifactReader`, passes the engine through the HTTP with `promptkit.WithArtifactReader`, passes the engine through the HTTP
adapter's consumer-owned `Runner` interface, and starts the server. adapter's consumer-owned `Runner` interface, and starts the server.
The command paths assemble the engine from the same resolved prompt, profile, The command paths assemble the engine from application-selected framework
and schema directories plus configured custom backends. Each backend is mapped source files and directories plus the schema directory and retry setting.
to Promptkit's public `Backend` value and registered during engine construction, Individual files become import-enabled ConfigKit inputs; directory selections
so one constructed server engine retains one immutable backend registry and its are expanded through Promptkit's directory-input helper. Scriptorium supplies
associated capacity state. 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 ### HTTP
@@ -77,6 +95,9 @@ validation, model, usage, and metadata values directly.
The optional HTTP retry count maps to `RunRequest.TransientRetries` without The optional HTTP retry count maps to `RunRequest.TransientRetries` without
mutating the shared engine. Negative values are rejected before invocation; mutating the shared engine. Negative values are rejected before invocation;
Promptkit controls retries and backend admission for concurrent requests. Promptkit controls retries and backend admission for concurrent requests.
CLI and HTTP operation budgets map to PromptKit's `OperationTimeout`; HTTP
passes the caller context through unchanged. The public sentinels determine
timeout classification.
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader

View File

@@ -7,13 +7,13 @@ public behavior belongs in the linked contracts.
| Component | Implemented responsibility | References | | 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) | | `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/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 through ConfigKit v1.2.1, supplies the application 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/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) | | `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
Framework implementation packages are provided by Framework implementation packages are provided by
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md) [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
and are not part of this repository. and are not part of this repository.

View File

@@ -5,20 +5,26 @@
This document covers Scriptorium-owned source locations and the restricted HTTP This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged owned by the tagged
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md). [PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
## Application Source Locations ## Application Source Locations
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from `internal/config` resolves the ordered `promptkit_sources` sequence and
Scriptorium defaults, configuration files, and CLI overrides. It also resolves `schema_dir` from application configuration and explicit CLI overrides. It
the application-owned `backends` mapping into sorted engine settings. owns selector-shape validation, not framework file parsing. During engine
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps construction, `internal/adapter/cli` turns file selections into import-enabled
each configured backend to Promptkit's public engine registration when ConfigKit inputs and expands directory selections with
constructing an engine shared by the command path. `promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays, one per selector. Directory inputs retain the
helper's strict-composition grouping; no selected source becomes an implicit
framework main. The shared Promptkit engine receives the selected schema
directory and retry setting, and the default OpenRouter bundle remains enabled.
Scriptorium does not search, parse, validate, or overlay framework source files Promptkit uses ConfigKit to load and compose those framework inputs according
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema to Promptkit's own schema and format. Scriptorium does not parse or validate
resolution, ordinary file artifacts, and the related error identities. 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 The [configuration reference](../config.md) owns Scriptorium's source-location
fields and precedence. Maintained files under `examples/` are application fields and precedence. Maintained files under `examples/` are application
@@ -26,33 +32,43 @@ inputs that use Promptkit's tagged formats.
## Application Configuration Boundary ## Application Configuration Boundary
`internal/config` contains a ConfigKit-native `Document` definition. Its `internal/config` contains the application-owned ConfigKit-native `Document`
fresh defaults come from Scriptorium's existing default constants; its resolver definition. Its fresh defaults come from Scriptorium's existing default
records only actual trimming, path cleaning, and render-format normalization. constants; its resolver records only actual leaf-level trimming, path cleaning, and
The validator reports application retry, size-limit, and format errors without render-format normalization. The validator reports selector-shape, retry,
mutating the document or exposing rejected values. Application path values keep size-limit, and format errors without mutating the document or exposing
working-directory-relative meaning. ConfigKit owns strict YAML decoding and rejected values. Application path values keep working-directory-relative
presence semantics, including dynamic integer values in backend parameters. meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by PromptKit using
the same ConfigKit release under PromptKit's own schema and source contract.
The `Load` boundary selects an explicit file, the first existing implicit The `Load` boundary selects an explicit file or constructs a native ConfigKit
configuration file, or ConfigKit's defaults-only source. Only absence advances search over the ordered implicit paths. Discovery exhaustion uses defaults;
implicit discovery. One ConfigKit load applies explicit application overrides a selected-file error stops loading. One ConfigKit load enables imports,
before validation and returns a result containing the resolved document and applies explicitly supplied application overrides after decoding and before
its frozen inspection records. `Settings` converts that document into the resolution and validation, and returns the document and its frozen inspection
existing runtime settings with backend IDs sorted; it does not read files or records. `Settings` copies selectors in their resolved order into runtime
apply another merge. File-backed loads enable explicit ConfigKit imports and settings; it does not read files or apply another merge. ConfigKit uses the selected file's
select one named overlay when requested. ConfigKit uses the selected file's
canonical directory as the source root; the application does not widen it. canonical directory as the source root; the application does not widen it.
Application path values retain process-working-directory-relative meaning. Application path values retain process-working-directory-relative meaning.
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 Every configuration-loading command uses this boundary. The CLI maps only
explicitly visited application flags to ConfigKit overrides and prints explicitly visited application flags to ConfigKit overrides and prints
structured load diagnostics before engine construction. The old application structured load diagnostics before engine construction. Application and
framework load errors and warnings use their respective native writers. The old application
YAML decoder and merge path have been removed. YAML decoder and merge path have been removed.
Application `config` inspection reuses the result's frozen effective, Application `config` inspection reuses the result's frozen effective,
provenance, and history views without constructing an engine or reloading provenance, and history views without constructing an engine or reloading
sources. It does not resolve API-key environment values; ordinary backend sources. It does not resolve credentials. `inspect configuration` separately
parameters remain visible by the selected inspection policy. 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 ## Restricted HTTP Artifact Reader

View File

@@ -9,7 +9,9 @@ fields, or HTTP wire behavior.
- [CLI reference](cli.md): commands, output destinations, and exit codes. - [CLI reference](cli.md): commands, output destinations, and exit codes.
- [Configuration reference](config.md): application settings, source - [Configuration reference](config.md): application settings, source
locations, defaults, and credential mapping. locations, defaults, and credential mapping.
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md): - [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
source-selector and definition migration examples.
- [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md):
prompt, profile, schema, execution-setting, and framework credential prompt, profile, schema, execution-setting, and framework credential
contracts. contracts.
- [HTTP API reference](api.md): route, request/response schema, status codes, - [HTTP API reference](api.md): route, request/response schema, status codes,
@@ -39,10 +41,17 @@ without a report.
## Deploy The Filesystem And Process ## Deploy The Filesystem And Process
Provide the process with readable configured Promptkit prompt, profile, and Provide the process with readable selected Promptkit source files/directories
schema sources that follow the tagged framework formats. For an HTTP deployment and schema sources that follow the tagged framework formats. At engine
that accepts file artifacts, use a dedicated, narrow artifact directory rather construction, PromptKit v0.23.3 validates every selected effective definition,
than a general-purpose or sensitive filesystem tree. including unused definitions, and captures referenced message-file contents
and static template syntax. `serve` constructs one engine at startup; it does
not reload changed configuration or message content. Restart the process to
validate and capture a new configuration. Schema and request-artifact reads,
credential resolution, and provider work remain request-preparation or runtime
concerns. For an HTTP deployment that accepts file artifacts, use a dedicated,
narrow artifact directory rather than a general-purpose or sensitive filesystem
tree.
If application configuration uses explicit imports or a selected overlay, If application configuration uses explicit imports or a selected overlay,
deploy those files beneath the selected configuration file's canonical deploy those files beneath the selected configuration file's canonical
@@ -52,12 +61,15 @@ resolve from the process working directory, so set that directory deliberately
in the service manager. This configuration-source boundary is distinct from in the service manager. This configuration-source boundary is distinct from
the HTTP artifact root and does not constrain prompt or schema directories. the HTTP artifact root and does not constrain prompt or schema directories.
When upgrading existing definitions, review selected profile IDs. For independently maintained collections, place checkouts beneath the
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` were removed from the directory selected by your framework discovery file. The maintained
selected catalog. Choose an available catalog profile, one of Promptkit's [discovery example](../examples/config.discovery.yml) selects optional
maintained names, or a complete application-owned profile. New DeepSeek names `collection.yml` and `collection.yaml` entry files; each checkout owns its
are not aliases for the removed ones; see the namespace and explicit fragment imports. Update a checkout independently and
[v0.10 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md). invoke the CLI again, or restart a running server to capture the update. Do
not treat arbitrary YAML in a checkout as a framework source. When upgrading
definitions, review exact profile IDs and replace retired catalog references
as described in the [migration guide](consumers/upgrading-promptkit.md).
Run Scriptorium under an identity that can: Run Scriptorium under an identity that can:
@@ -87,25 +99,27 @@ and apply the same retention and access rules as for model input and output.
Before changing production inputs, profiles, or schemas: Before changing production inputs, profiles, or schemas:
1. use `config validate`, `config show`, or `config sources` to check the 1. use `config validate`, `config show`, or `config sources` to check
application configuration and its selected sources without constructing an Scriptorium's application configuration; these do not open Promptkit sources
engine; this does not verify prompt files, provider access, or credentials; or construct an engine;
2. confirm the deployed configuration selects the intended sources and model 2. use `inspect configuration validate` to construct the engine and validate
credentials; all selected framework definitions; this does not prepare a request, check
3. use [`render`](cli.md) with the same request inputs and variables to confirm credentials, load request-time schemas/artifacts, or contact a provider;
3. confirm the deployed configuration selects the intended sources and
environment-variable names;
4. use [`render`](cli.md) with the same request inputs and variables to confirm
preparation without a model call; preparation without a model call;
4. use [`run`](cli.md) for generation; and 5. use [`run`](cli.md) for generation; and
5. retain or discard validation-failed output according to the caller's 6. retain or discard validation-failed output according to the caller's
policy. policy.
Inspection output can include configuration paths, names, and ordinary backend Application configuration inspection can include paths and configured values.
parameters. `config explain --path` uses JSON Pointer paths and can show Framework `inspect configuration show` and `explain` use Promptkit's native
displaced historical values as well as the final value. Protect both the redaction for classified credential-shaped provider fields, including
selected paths and the output, especially when backend parameters contain historical values, while leaving environment-reference names and ordinary
sensitive identifiers; ConfigKit does not infer arbitrary secrets in those provider parameters visible. Neither report identifies arbitrary sensitive
parameters. Apply content by value or name. Protect inspection output accordingly; Scriptorium
access and retention controls; the application stores only API-key environment stores environment-variable names, not the resolved credential bytes.
reference names, not the resolved credential bytes.
The [maintained render script](../examples/render-markdown-summary.sh) is a The [maintained render script](../examples/render-markdown-summary.sh) is a
copyable preflight example. The CLI reference owns its complete invocation and copyable preflight example. The CLI reference owns its complete invocation and
@@ -150,7 +164,7 @@ setting and then Promptkit's default, while explicit zero disables additional
attempts. Existing generation timeouts apply attempts. Existing generation timeouts apply
per attempt, while the caller context covers the complete operation. Provider per attempt, while the caller context covers the complete operation. Provider
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the `Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md) [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
for details. for details.
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
@@ -158,8 +172,8 @@ be bounded. The existing generation timeout applies afresh to each attempt and
does not cap retry waits or the complete invocation. The whole-run interval does not cap retry waits or the complete invocation. The whole-run interval
covers the engine call, including capacity waiting and repairs as supported by covers the engine call, including capacity waiting and repairs as supported by
context cancellation; it excludes parsing, engine setup, and output writes. context cancellation; it excludes parsing, engine setup, and output writes.
HTTP callers can use [`run_timeout_seconds`](api.md) to shorten their request HTTP callers can use [`run_timeout_seconds`](api.md) to set the engine's
context for the same engine interval. The API distinguishes an expired operation budget for the same interval. The API distinguishes a typed expired
execution deadline from caller cancellation and from a provider-attempt execution deadline from caller cancellation and from a provider-attempt
timeout. A canceled capacity waiter releases its Promptkit admission state. timeout. A canceled capacity waiter releases its Promptkit admission state.

View File

@@ -1,113 +1,82 @@
# Open-Source Attribution # Open Source Attribution Notices
Scriptorium's own terms are in the repository [LICENSE](../../LICENSE). ## Standard Repository Policies
The [OSS policy](../policy/oss.md) governs these entries. Dependency versions
are recorded in [go.mod](../../go.mod) and [go.sum](../../go.sum); source and
notice links below identify the exact commits for the selected versions.
## Promptkit Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
`docs/policy/agents.md`, `docs/policy/documentation.md`,
`docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
of `docs/development.md`, adapted for this repository.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## PromptKit
Selected module: `go.maximumdirect.net/promptkit` at `v0.23.3`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL v3 companion](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/db05b56166ca2d8650dfaf660e1cf0eed3932e1d/LICENSE) [COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/LICENSE).
Source: [Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/commit/db05b56166ca2d8650dfaf660e1cf0eed3932e1d) [Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f).
## ConfigKit ## ConfigKit
Upstream copyright statement: no project-specific statement is present in the Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
selected module; the FSF copyright in its license text belongs to that license
document and is not substituted for a project notice.
SPDX-License-Identifier: LGPL-3.0-only Copyright (C) 2026 Eric Rakestraw
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) | SPDX-License-Identifier: LGPL-3.0-or-later
[GPL v3 companion](licenses/GPL-3.0.txt) |
[upstream LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/LICENSE)
Source: [ConfigKit v0.4.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258) License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
## Promptkit OpenRouter Catalog [Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
Upstream copyright statement: no project-specific statement is present in the
selected module. The linked upstream README records the profile assets'
Promptkit origin and the copyright holder's deliberate relicensing.
SPDX-License-Identifier: LGPL-3.0-only
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3 companion](licenses/GPL-3.0.txt) |
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab/LICENSE) |
[asset licensing notice](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab/README.md)
Source: [OpenRouter catalog v2.20260922.1](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab)
## Promptkit Rakestrawhome Catalog
Upstream copyright statement: no project-specific statement is present in the
selected module. The linked upstream README records the profile asset's
Promptkit origin and the copyright holder's deliberate relicensing.
SPDX-License-Identifier: LGPL-3.0-only
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3 companion](licenses/GPL-3.0.txt) |
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226/LICENSE) |
[asset licensing notice](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226/README.md)
Source: [Rakestrawhome catalog v2.20260922.0](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226)
## jsonschema/v6 ## jsonschema/v6
Upstream copyright statement: no project-specific statement is present in the Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
selected module; no substitute statement is inferred here.
SPDX-License-Identifier: Apache-2.0 SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[upstream LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE) [LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
Source: [jsonschema/v6 v6.0.2](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71) [Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
## golang.org/x/text ## golang.org/x/text
Copyright (c) 2009 The Go Authors. All rights reserved. Selected module: `golang.org/x/text` at `v0.44.0`.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) | License and notices: [BSD 3-Clause](licenses/go-x-text-BSD-3-Clause.txt) |
[upstream LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE) [LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
Source: [golang.org/x/text v0.14.0](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353) [Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## gopkg.in/yaml.v3
Copyright (c) 2006-2010 Kirill Simonov
Copyright (c) 2006-2011 Kirill Simonov
Copyright (c) 2011-2019 Canonical Ltd
Copyright 2011-2016 Canonical Ltd.
SPDX-License-Identifier: MIT AND Apache-2.0
The upstream LICENSE assigns MIT to files ported from libyaml and Apache 2.0
to the remaining files; these are file-specific terms, not alternatives.
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[upstream LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[upstream NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE)
Source: [gopkg.in/yaml.v3 v3.0.1](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51)
## go.yaml.in/yaml/v4 ## go.yaml.in/yaml/v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov Copyright 2006-2010 Kirill Simonov
Copyright 2011-2019 Canonical Ltd Copyright 2011-2019 Canonical Ltd
@@ -116,12 +85,9 @@ Copyright 2025 The go-yaml Project Contributors
SPDX-License-Identifier: MIT AND Apache-2.0 SPDX-License-Identifier: MIT AND Apache-2.0
The upstream NOTICE assigns MIT to files ported from libyaml and Apache 2.0
to the remaining files; these are file-specific terms, not alternatives.
License and notices: [MIT](licenses/MIT.txt) | License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) | [Apache 2.0](licenses/Apache-2.0.txt) |
[upstream LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) | [LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[upstream NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE) [NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
Source: [go.yaml.in/yaml/v4 v4.0.0-rc.6](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125) [Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).

View File

@@ -0,0 +1,170 @@
Creative Commons Attribution-ShareAlike 4.0 International
Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.
Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.
Creative Commons Attribution-ShareAlike 4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
Section 1 – Definitions.
a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
e. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
i. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights under this Public License.
k. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
Section 2 – Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
A. reproduce and Share the Licensed Material, in whole or in part; and
B. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
3. Term. The term of this Public License is specified in Section 6(a).
4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
5. Downstream recipients.
A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.
C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this Public License.
3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
Section 3 – License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified form), You must:
A. retain the following if it is supplied by the Licensor with the Licensed Material:
i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of warranties;
v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
b. ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
Section 4 – Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
Section 5 – Disclaimer of Warranties and Limitation of Liability.
a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
Section 6 – Term and Termination.
a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
2. upon express reinstatement by the Licensor.
c. For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
d. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
Section 7 – Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
Section 8 – Interpretation.
a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
Creative Commons may be contacted at creativecommons.org.

View File

@@ -0,0 +1,27 @@
Copyright 2009 The Go Authors.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google LLC nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View File

@@ -1,12 +1,14 @@
# Agent Policy # Agent Policy
**Base Policy Version:** 1.1 **Base Policy Version:** 1.3
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
## Purpose ## Purpose
Agents working in this repository must read and adhere to the following house rules. Agents must read and follow these rules.
## Implementation Discipline ## Implementation Discipline
@@ -43,15 +45,15 @@ unless that behavior was expressly selected as part of the contract.
## Git Commit Policy ## Git Commit Policy
By default, create a commit after completing each coherent unit of work, using a By default, commit each completed, nonempty unit of work using a
concise, plain-English message describing what changed. This policy is standing concise, plain-English message describing what changed. This policy is standing
authorization to create those local commits; a separate user request is not authorization to create those local commits; a separate user request is not
required. An explicit user instruction to leave work uncommitted takes precedence. required. An explicit user instruction to leave work uncommitted takes precedence.
A unit of work is a focused, reviewable outcome, including its relevant tests and A unit of work is a focused, reviewable outcome, including its relevant tests and
documentation. Do not commit after every intermediate edit or create empty commits. documentation.
Complete the appropriate validation before committing. If work is incomplete or Complete the appropriate validation before committing. If work is incomplete or
validation is blocked, report that state rather than presenting it as completed. validation is blocked, report that state accurately.
Before committing: Before committing:
@@ -59,10 +61,10 @@ Before committing:
changes. Identify changes that predate the current unit of work. changes. Identify changes that predate the current unit of work.
2. Exclude secrets, local environment files, generated junk, and unrelated changes. 2. Exclude secrets, local environment files, generated junk, and unrelated changes.
3. Stage only the files or hunks belonging to the completed unit. Use `git add .` 3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
only when every included change belongs to that unit. Do not disturb unrelated only when every included change belongs to that unit. Preserve unrelated
staged or unstaged work. staged and unstaged work.
4. Review `git diff --staged` and run appropriate checks for the change. Do not 4. Review `git diff --staged` and run appropriate checks for the change. Reuse
repeat checks already passed for unchanged content merely to create a commit. successful checks for unchanged content.
5. Review `git log --oneline -n 10` and use 5. Review `git log --oneline -n 10` and use
`git commit -m "<concise plain-English commit message>"`. `git commit -m "<concise plain-English commit message>"`.
6. Report the commit identifier and any remaining uncommitted work. 6. Report the commit identifier and any remaining uncommitted work.

View File

@@ -1,147 +1,124 @@
# Architecture Policy # Architecture Policy
**Base Policy Version:** 1.1 **Base Policy Version:** 1.3
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-19
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
## Purpose And Ownership ## Purpose And Ownership
This policy defines Scriptorium's purpose, responsibility and dependency The adopted policy defines the application's purpose and the architectural
boundaries, established invariants, and non-goals. Concrete component inventory constraints contributors must follow. It owns system boundaries, responsibility
and implementation mechanics belong in [internal documentation](../internal/overview.md); and dependency rules, established invariants, and explicit non-goals.
public behavior belongs in its canonical contracts.
Adopted constraints govern future development without implying that every Describe the concrete package inventory and implementation mechanics in internal
capability they could govern exists or is planned. Keep proposed structure and documentation. Link to canonical public contracts for their exact behavior and
implementation status in roadmaps, and decision rationale in ADRs. Acceptance to ADRs for decision rationale.
of a decision is not proof of implementation. Do not turn incidental choices
into architectural invariants.
## System Shape ## Architectural Approach
Scriptorium is an executable application with four command entry paths: CLI Hexagonal architecture is strongly recommended, including encapsulating external
`run`, CLI `render`, CLI `inspect`, and the HTTP service started by `serve`. integrations and APIs within internal adapters. Keep domain and application
The `inspect` command has prompt and profile modes. Scriptorium does not expose logic independent of external integration details, and make dependency direction
a reusable root Go package. clear in the adopted policy.
The application consumes Implement that separation with proportionate, idiomatic code. Choose interfaces
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md) and package layout to serve the application's actual boundaries. Use adapters
through its supported root package. Promptkit owns prompt execution, for collaborators with external integration responsibilities.
preparation, source formats, built-in profiles, model-client behavior, and
validation. Scriptorium owns application configuration, executable adapters,
prepared-run and definition-inspection presentation, process behavior, and HTTP
deployment policy.
Scriptorium also consumes ConfigKit v0.4.0 for application configuration ## Adopted Constraints And Implemented Structure
decoding, resolution, and validation flow. Scriptorium owns its application
schema, defaults, normalization, validation rules, source selection, and CLI
flag mapping; ConfigKit does not own Promptkit framework sources or HTTP
artifact containment.
The concrete package inventory is maintained in the Architectural constraints govern current and future development. Record
[internal overview](../internal/overview.md). 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.
As established by [ADR 0004](../adr/0004-definition-boundary.md), Scriptorium Constraints must reflect deliberately selected requirements and decisions.
aims to support the complete set of features in valid Promptkit prompt and Do not promote incidental implementation choices into architectural invariants.
profile definitions for its selected upstream version. Promptkit remains the
canonical parser and validator. Library-only features are considered
individually against the simple predefined-prompt execution model.
Maintain adapter boundaries with proportionate, idiomatic code. This approach ## Scriptorium's Purpose And System Shape
does not require an interface for every type, additional wrappers, or a fixed
directory tree for integrations that do not exist.
## Dependency Direction 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](../internal/overview.md) owns the concrete package
inventory; [adapter internals](../internal/adapters.md) and
[source internals](../internal/sources.md) own implementation mechanics.
```text ## Framework And Application Boundaries
cmd/scriptorium
|
v
CLI and HTTP adapters, configuration, defaults, and formatting
|
v
Promptkit (execution) and ConfigKit (application configuration)
```
- Retained application packages may import Promptkit's root package. Scriptorium consumes
- They must not import Promptkit `internal` packages. [PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
- They must not import Promptkit catalog modules directly. through its supported public root package. Promptkit owns prompt execution,
- They must not import the removed Scriptorium root facade or recreate former preparation, prompt and profile formats, built-in profiles, model-client
framework package families. behavior, validation, inspection semantics, and framework defaults. Scriptorium
- Adapter-owned interfaces use Promptkit public values when a consumer-side owns the application domain, executable CLI and HTTP adapters, process behavior,
substitution boundary is needed. and HTTP deployment policy. It interprets resolved configuration and uses
- Scriptorium passes omitted framework settings as zero values so Promptkit PromptKit's supported APIs and results to satisfy user requests. The [format
applies its own defaults. 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.
The repository architecture guard enforces these import and removal ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
invariants. 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.
Cross-project changes land and release in Promptkit before Scriptorium adopts As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
the tagged dependency. Do not commit Go workspaces, local replacements, Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
vendored Promptkit implementation, or unpublished dependency assumptions. neutrally expose upstream features and semantics. The current CLI still uses
custom presentation; the [adoption roadmap](../roadmap/commandkit-adoption.md)
tracks its replacement. This decision complements ADRs 0004 and 0005.
## Retained Boundaries 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.
- `internal/adapter/cli` owns commands, flags, configuration precedence, Application code may import Promptkit's public root package, but not its
process streams, output files, summaries, and exit codes. `internal` packages or catalog modules. It must not recreate the removed
- `internal/adapter/http` owns routes, strict JSON DTOs, size limits, response Scriptorium framework facade or former framework package families.
mapping, status mapping, and the restricted artifact reader. Adapter-owned interfaces use Promptkit public values when a consumer-side
- `internal/config` owns discovery and Scriptorium's application definition; substitution boundary is needed. Omitted framework settings pass as zero
ConfigKit owns strict YAML decoding and the load/override pipeline. values so Promptkit applies its own defaults. Cross-project changes land and
- `internal/defaults` owns Scriptorium application and HTTP defaults only. release in Promptkit before
- `internal/format` owns deterministic prepared-run and definition-inspection Scriptorium adopts its tagged dependency; do not commit Go workspaces, local
text and JSON presentation. replacements, vendored Promptkit source, or unpublished dependency assumptions.
- Promptkit owns framework orchestration and contracts. Its The repository's architecture guard protects these import and removal
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) boundaries. Adapter separation does not require an interface for every type,
and extra wrappers, or a fixed directory tree.
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md)
are canonical.
## HTTP Artifact Security Boundary ## Definition Support And Request State
Ordinary CLI file loading is provided by Promptkit. Scriptorium's HTTP adapter As decided in [ADR 0004](../adr/0004-definition-boundary.md), Scriptorium aims
injects a restricted `promptkit.ArtifactReader` for inbound HTTP requests. to support the complete set of features in valid Promptkit prompt and profile
That reader denies file references without an artifact root, enforces the definitions for its selected upstream version. Promptkit remains the canonical
configured byte limit, and applies Scriptorium's lexical root-containment rule. parser and validator. Library-only features are considered individually
The operating system still follows symlinks after the lexical check. against Scriptorium's simple predefined-prompt execution model.
This boundary handles untrusted request references under the documented External YAML and JSON decoding remains strict. Adapters map external values
deployment model; it is not a filesystem sandbox. Defending against a through Promptkit public requests and results without taking over framework
privileged actor concurrently modifying the host filesystem is outside the orchestration. Explicit numeric request overrides preserve presence, including
adopted scope, not a claim that such activity cannot occur. Do not infer zero. Adapters map Promptkit public error identities to CLI exits or HTTP
additional defenses or guarantees from hypothetical threats; raise unsettled statuses without classifying by message text. Raw API keys are not accepted
scope decisions under the [agent policy](agents.md). in Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved
The [HTTP API](../api.md) owns observable request outcomes, and
[operations](../operations.md) owns deployment permissions and root selection.
## State, Errors, And Secrets
Scriptorium has no durable run-state store, checkpoint, cache, or resume
mechanism. Recovery is a new request after correcting inputs, configuration, or
environment.
Each request is self-contained from the caller's perspective, without
conversation or workflow state retained from completed requests. This does
not mean the process is internally stateless. Shared engines, backend capacity
and queue accounting, in-flight coordination, cancellation, and server
lifecycle resources are permitted and must be shared where necessary to
enforce configured backend limits across concurrent requests. Such state must
be concurrency-safe and does not create a durable user-workflow contract.
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. secrets must not be emitted.
## Architectural Invariants Each execution request is self-contained from the caller's perspective; no
conversation or workflow state is retained from completed requests. This
- External YAML and JSON decoding remains strict. does not preclude process-scoped operational state. A server shares its
- CLI and HTTP behavior remains presentation and transport logic rather than Promptkit engine, backend registry, capacity admission and queue accounting
framework orchestration. across relevant concurrent requests so configured backend limits cannot be
- Explicit numeric request overrides preserve presence, including zero. bypassed by per-request construction. In-flight coordination, cancellation,
- HTTP artifact containment and byte limits remain Scriptorium policy. and server lifecycle state must be concurrency-safe. None of this creates a
- No application package depends on Promptkit implementation packages. durable workflow, checkpoint, cache, or resume contract; recovery is a new
request after correcting inputs, configuration, or environment.
## Non-Goals ## Non-Goals
@@ -153,5 +130,19 @@ secrets must not be emitted.
- Do not add durable workflow, archive, or resume behavior. - Do not add durable workflow, archive, or resume behavior.
- Do not add application-managed prompt modification, follow-up message flows, - Do not add application-managed prompt modification, follow-up message flows,
conversation management, or multi-step workflow orchestration. conversation management, or multi-step workflow orchestration.
## Trust Boundaries And Threat Scope
Work that is not implemented belongs in `docs/roadmap/`. 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.

View File

@@ -1,15 +1,16 @@
# Documentation Policy # Documentation Policy
**Base Policy Version:** 1.4 **Base Policy Version:** 1.12
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
## Purpose ## Purpose
This policy assigns each documentation topic to one canonical owner. Its goal is This policy assigns each documentation topic to one canonical owner. Its goal is
to keep this repository's documentation accurate, concise, discoverable, and to keep this application's documentation accurate, concise, discoverable, and resistant
resistant to drift for users, operators, developers, integrators, and LLM to drift for users, operators, developers, integrators, and LLM coding agents.
coding agents.
## Core Rules ## Core Rules
@@ -17,45 +18,38 @@ coding agents.
Each authoritative fact belongs in one document. A non-owning document may give Each authoritative fact belongs in one document. A non-owning document may give
a short, stable summary for orientation, but it must link to the canonical owner a short, stable summary for orientation, but it must link to the canonical owner
instead of repeating volatile details. for volatile details.
Volatile details include commands, flags, configuration fields and defaults, Volatile details include commands, flags, configuration fields and defaults,
module keys, schemas, file names, paths, status codes, retry behavior, and module keys, schemas, file names, paths, status codes, retry behavior, and
runtime guarantees. If readers could reasonably treat a statement as a runtime guarantees. If readers could reasonably treat a statement as a
contract, maintain it only in the owning document. contract, maintain it only in the owning document.
Minimal tested usage examples are allowed outside the owning contract when this
policy assigns them an orientation or instructional purpose. They must link to
the canonical contract and must not redefine complete syntax, defaults, or
semantics.
### Current And Future Behavior ### Current And Future Behavior
Outside `docs/roadmap/`, documentation describes implemented behavior only. Outside `docs/roadmap/`, documentation describes implemented behavior only.
Partial features may be described only to their implemented boundary. Partial features may be described only to their implemented boundary.
Architectural constraints may govern future changes without implying that the Architectural constraints may govern future changes. Describe current structure
components or capabilities they would govern already exist. This does not from implemented behavior.
permit describing a proposed system structure as implemented.
ADRs may record an accepted architectural decision before implementation, but ADRs may record an accepted architectural decision before implementation. The
acceptance must not be presented as proof that the behavior exists. The roadmap roadmap owns implementation status and sequencing until the decision is
owns implementation status and sequencing until the decision is implemented. implemented. Current architecture, user, operator, integration, and internal
Current architecture, user, operator, documentation are updated when the behavior lands.
integration, and internal documentation are updated when the behavior lands.
### Audience And Detail ### Audience And Detail
Write for the document's stated audience and include only the detail needed for Write for the document's stated audience and include only the detail needed for
its owned topic. User and operator docs should not expose implementation detail. its owned topic. Keep user and operator docs focused on using and operating the
Developer docs should link to user-facing and external contracts rather than application. Developer docs should link to user-facing and external contracts
restate them. for their definitions.
### Examples ### Examples
Complete copyable files belong in `examples/`. Documentation may use the Complete copyable files belong in `examples/`. Documentation may use the
smallest illustrative snippet needed to explain its owned topic, but should link smallest illustrative snippet needed to explain its owned topic, but should link
to maintained examples instead of embedding a second complete copy. to maintained examples for complete copyable files.
Examples must be valid, secret-free, and tested where practical. Commands and Examples must be valid, secret-free, and tested where practical. Commands and
configuration used in documentation should match the application. configuration used in documentation should match the application.
@@ -71,43 +65,42 @@ secret values.
| Topic | Canonical owner | Owned content | Content owned elsewhere | | Topic | Canonical owner | Owned content | Content owned elsewhere |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Product orientation and minimal end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward, including license and attribution navigation. | Complete command reference, configuration reference, operational procedures, implementation detail. | | Product orientation and minimal end-to-end quickstart | `README.md` | Purpose, value, shortest successful invocation, and navigation, including licensing and attribution. | Complete command reference, configuration reference, operational procedures, implementation detail. |
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, and detailed change recipes, which belong in the relevant internal component document. | | Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | | Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
| Agent policy | `docs/policy/agents.md` | Agent implementation discipline, proportionality, idiomatic simplicity, local commit rules, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. | | Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | | Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. |
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | | Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
| Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. |
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. |
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. | | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
| Configuration contract | `docs/config.md` | Application discovery and precedence, source locations, server fields, render default, HTTP limits, and credential mapping. | Promptkit framework formats and defaults, complete example files, CLI syntax, runtime lifecycle, and implementation detail. | | Configuration contract | `docs/config.md` | Application configuration discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | PromptKit framework formats and defaults, complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | | Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
| Release policy | `docs/policy/release.md` | Versioning and compatibility, release integrity and immutability, documentation requirements, proportionate gates, publication controls, source completion, and optional verification boundaries. | Repository-specific commands, installation guidance, historical summaries, and CI implementation details. |
| Release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, publication command and guards, asynchronous delivery, optional diagnostics, and failure recovery. | General release requirements, runtime operations, historical announcements, and current application contracts. |
| Version-specific release notes | `docs/releases/` | Immutable release summaries, compatibility notices, and migration announcements for one published version. | Complete CLI, HTTP, configuration, operations, or dependency contracts. |
| Open source licensing and attribution policy | `docs/policy/oss.md` | House attribution format, license-text and notice-link conventions, discoverability, maintenance, and handling of concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
| Project license | `LICENSE` | The project's own license terms. | Upstream component attribution and dependency license texts. |
| Upstream component attribution | `docs/oss/attribution.md` | Component names, copyright statements, license identification, and license, notice, and source links. | General attribution policy and complete standard license texts. |
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by attribution entries where applicable. | Project-specific upstream notices, attribution prose, and policy interpretation. |
| Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. | | Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
| Consumer guidance | `docs/consumers/` | Choosing between Scriptorium's executable interfaces and understanding consumer responsibilities. | HTTP wire semantics, CLI syntax, Promptkit's Go package, and internal implementation detail. | | Consumer guidance for executable use and migration | `docs/consumers/` | Task-oriented executable use, migration to PromptKit, minimal examples, and consumer responsibilities. | HTTP wire semantics, CLI syntax, PromptKit's public Go API, external protocol contracts, internal implementation detail. |
| External and durable integration contracts | `docs/integrations/` | Scriptorium-owned process and executable integration contracts. | Promptkit framework formats and outbound provider protocols, physical runtime placement, internal transformations, CLI syntax, and configuration defaults. | | Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | | Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | | Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. | | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
Documents that do not exist are required only when the corresponding interface Create supporting documents for existing interfaces and responsibilities when
or responsibility exists. Do not create placeholder API, consumer, integration, substantive content is available.
or operations documents for behavior the application does not have.
## Boundary Rules ## Boundary Rules
### Orientation ### Orientation
The README owns product orientation. The developer guide routes contributors. Link among orientation, architecture, and internal documents; maintain each
Architecture owns normative structure. Internal overview owns the current package or behavior description in its canonical owner.
concrete component map. These documents may link to one another but should not
maintain parallel package or behavior descriptions.
### Commands, Configuration, And Operations ### Commands, Configuration, And Operations
@@ -119,26 +112,25 @@ other contracts.
### Releases ### Releases
The release policy owns release requirements; the release procedure supplies The release policy defines requirements and invariants that every release must
the commands that satisfy them. Release notes are historical summaries, not satisfy. The repository-specific release procedure defines the commands and
current-state contract owners. The checked-in note at an immutable tag records workflow maintainers use to satisfy that policy. Release notes record history
that release; current documentation changes with the behavior it describes. at immutable tags. Maintain current behavior in its canonical documentation,
Neither a procedure nor a note may weaken policy or defer required updates to update it with the corresponding behavior changes, and keep release procedures
canonical contracts. consistent with adopted policy.
### Open Source Attribution ### Project Licensing And Upstream Attribution
The [OSS policy](oss.md) defines the House Format and README and release-link README and release documents link to the canonical licensing and attribution
conventions. Attribution entries own component-specific information. README materials under the [OSS policy](oss.md). The release procedure owns URL
and release documents provide navigation to those canonical materials; the construction and publication mechanics.
release procedure owns URL construction and publication mechanics.
### Contracts And Implementation ### Contracts And Implementation
Integration and API documents define externally observable shapes and Integration and API documents define externally observable shapes and
semantics. Internal documents explain how this project implements or consumes semantics. Internal documents explain how this application implements or consumes those
those contracts. Internal docs may name a field, file, or protocol to identify contracts. Internal docs may name a field, file, or protocol to identify a
a dependency, but must link to its canonical contract for the definition. dependency, but must link to its canonical contract for the definition.
### Security Topics ### Security Topics
@@ -160,31 +152,20 @@ Use sequentially numbered ADR filenames such as
6. alternatives considered; 6. alternatives considered;
7. consequences. 7. consequences.
Use one of these statuses: Treat the decision content of an accepted ADR as immutable. When a decision
changes, create a new ADR and update the earlier ADR's status to superseded.
- **Proposed:** the decision is under consideration and may change; ADRs should be reserved for major architectural decisions, such as ownership
- **Accepted:** the decision is approved, whether or not implementation is boundaries, large-scale architectural features, or invariants that rise to
complete; the level of architectural significance. Routine choices, implementation
- **Rejected:** the proposed decision was considered and not adopted; decisions, and rejected suggestions do not warrant an ADR unless they
- **Superseded:** a later ADR replaces the accepted decision. otherwise represent a significant architectural decision.
A proposed ADR transitions to accepted or rejected. An accepted ADR transitions Roadmaps should preserve plausible future work, not rejected product
to superseded only when a later accepted ADR replaces it. An ADR may be created ideas.
as accepted when the decision has already been made.
Treat the decision content of an accepted ADR as immutable. Its status and
supersession metadata may be updated, but a changed decision requires a new ADR.
A superseded ADR must link to its replacement, and the replacement must link
back to the superseded ADR. Rejected architectural alternatives belong in the
ADR; rejected product ideas belong in the roadmap.
## Maintenance ## Maintenance
Every policy document records its underlying template version and local
last-updated date immediately below the title. Update the date when revising
local policy; change the base version only when adopting a newer template.
Do not retain template adoption instructions in the local policy.
When behavior changes, update its canonical owner in the same change. If When behavior changes, update its canonical owner in the same change. If
ownership moves, remove the old definition and replace it with a link where ownership moves, remove the old definition and replace it with a link where
navigation remains useful. navigation remains useful.

27
docs/policy/meta.md Normal file
View File

@@ -0,0 +1,27 @@
# Policy Set Provenance
**Base Policy Version:** 1.0
**Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
## Origin And Local Authority
This repository's policy set is adapted from
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
The adopted local policies govern work in this repository. Upstream revisions
become local policy through deliberate adoption, preserving local decisions.
Each policy's `Upstream Source` identifies its adopted baseline.
## Adoption And Updates
For policy adoption, upstream revision reviews, and updates, consult the
[upstream adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
That guide and the reference example collection are maintained upstream and
accessed through links. Keep discovery links pointed at the current upstream
project and guide; keep adopted-source and example links pinned to commits.
The local [developer guide](../development.md) routes tasks to applicable
policies. Formal credit and licensing notices for the copied policy material
belong in the local [attribution document](../oss/attribution.md).

View File

@@ -1,81 +1,153 @@
# Open Source Licensing And Attribution Policy # Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.1 **Base Policy Version:** 1.9
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
## Purpose And Scope ## Purpose And Scope
This policy establishes a repeatable House Format for open source attribution This policy defines project licensing conventions and a repeatable House Format
and license notices. It covers upstream components incorporated into or for upstream attribution and license notices. It covers the project's own code
distributed with the project, including relevant transitive dependencies and and upstream components incorporated into or distributed with the application
copied code or assets. Treatment follows the component's terms and actual use, or library, including relevant transitive dependencies and copied code,
rather than its classification as a direct dependency. documentation, or assets.
Determine treatment from the component's terms and actual use.
Consulting development guidance or using tooling alone does not require an
attribution entry. Copying or adapting documentation for inclusion in the
repository is different: preserve its applicable attribution and license terms.
A material's role as development guidance does not exempt copied documents.
Apply any express permissions for attribution-free reuse of example formatting.
The baseline is a publicly available source repository with releases published The baseline is a publicly available source repository with releases published
alongside it. The format is independent of language, forge, and build system. alongside it. The format is independent of language, forge, and build system.
It does not require attribution for every development tool, establish license It does not require attribution for every development tool, establish license
compatibility, or resolve obligations beyond attribution and notice handling. compatibility, or resolve every obligation arising from use or distribution.
## Canonical Locations ## Canonical Locations
The [documentation policy](documentation.md) assigns ownership: The [documentation policy](documentation.md) assigns ownership:
- `LICENSE` contains the project's own license. Dependency attribution does - `COPYRIGHT`: project name, copyright statements, SPDX expression, grant,
not relicense the project. warranty disclaimer, and third-party statement.
- `docs/oss/attribution.md` contains the canonical component entries. - `LICENSE` contains the complete, unmodified project license text, including
- `docs/oss/licenses/` contains complete, verbatim standard license texts, incorporated companion text. Dependency attribution does not relicense the project.
including companion texts where applicable. - `docs/oss/attribution.md`: canonical component entries.
- `docs/oss/licenses/`: complete, verbatim standard and applicable companion texts.
Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`. Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`.
A shared standard text may serve multiple entries. Keep explanations outside A shared standard text may serve multiple entries. Keep explanations outside
license texts and preserve distinct versions and exceptions. license texts and preserve distinct versions and exceptions.
## House Format ## Upstream Reference Examples
Each component entry has five fields: Use the commit-pinned upstream examples to create actual project notices.
Retain their links and keep the example collection upstream; keep applicable
license texts locally as specified above.
1. **Project name**, normally as the entry heading. ## Project Licensing
Unless the author specifies otherwise, use **GPL version 3 or later**
(`GPL-3.0-or-later`) for applications and **LGPL version 3 or later**
(`LGPL-3.0-or-later`) for libraries. An author's explicit choice takes precedence:
for example, a one-off script may use MIT. Such a choice requires no exception
rationale, additional approval, or compensating controls under this policy.
These defaults guide new license selection. Adopting this policy does not
relicense existing code or override third-party terms. Preserve an existing
license unless the author deliberately changes it. For mixed-purpose projects,
follow the author's selected scope rather than inferring different licenses for
individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file.
Use the COPYRIGHT examples exactly as provided, except for placeholder
substitutions and changes expressly required or authorized by this policy or
the author.
Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant.
For GPLv3 projects, copy the complete GPLv3 text into `LICENSE`. For LGPLv3
projects, place the complete LGPLv3 text followed by the complete GPLv3 text in
`LICENSE`; the LGPL incorporates the GPL terms. Keep the texts unmodified and
place project-specific statements in `COPYRIGHT`. For the default grants, the
grant and SPDX expression in `COPYRIGHT` must expressly identify `or-later`;
follow the author’s choice if a different grant is selected.
For other licenses, provide their complete text and any required project-specific
fields; the standard reference collection remains unchanged. Keep `COPYRIGHT`,
`LICENSE`, SPDX expressions, and README descriptions consistent with the actual
grant. This convention introduces no blanket requirement for per-file headers;
preserve notices or add them where the applicable terms require them.
Identify separately licensed documentation or assets in the project grant, with
links to their attribution and license information. An application's default
code license does not override the terms of incorporated documentation.
## Upstream Attribution House Format
Begin `docs/oss/attribution.md` with `# Open Source Attribution Notices`,
followed directly by component entries. These comprise the complete document.
Each entry presents these five fields in order, with blank lines between them:
1. **Project name** as a level-two heading. An optional identification paragraph
may follow, such as `Selected module: MODULE at VERSION.` with the module and
version in backticks. For copied documentation, a concise `Material:` sentence
may identify the affected files and whether they were adapted or copied
without modification. A factual qualifier such as `(transitive dependency)`
is permitted. Limit optional identification prose to factual component and
material scope.
2. **Upstream copyright statement or statements**, preserving their wording. 2. **Upstream copyright statement or statements**, preserving their wording.
3. **SPDX license identifier or expression**, when applicable. Put multiple statements in separate paragraphs. Include this field when the
4. **License and notice links**, covering the applicable standard texts and selected upstream source supplies an applicable statement; otherwise, omit it.
upstream project-specific material. 3. **SPDX license identifier or expression**, when applicable, using
5. **Source repository link**, identifying the source corresponding to the `SPDX-License-Identifier: EXPRESSION`.
imported version. 4. **License and notice links**, beginning `License and notices:`, separated
by ` | `, and ending with a period. Label local standard texts by license
name, such as `MIT` or `Apache 2.0`. Label upstream files by their actual
filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`.
Illustrative Markdown, with placeholders for the actual upstream information: Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/attribution.md)
to create the project’s `docs/oss/attribution.md`.
The example illustrates omitted fields and multiple copyrights and licenses.
Replace the uppercase placeholders and illustrative URLs with actual component
information. Local license links are relative to the destination
`docs/oss/attribution.md`; copy the applicable texts into its `licenses/`
directory. Do not copy example entries for components the project does not use.
```markdown These are five fields, not a line limit. Omit the SPDX field when no applicable
## Example Library identifier exists; identify nonstandard terms through the linked text. Preserve
licensing alternatives and exceptions, and record a selected option when
relevant through the factual license identification. Do not invent an identifier
or silently resolve an unsettled licensing choice.
Copyright <upstream copyright statement> Keep entries factual. Do not add agent-authored explanations of license
expressions, file-level license scope, research performed, retained source
SPDX-License-Identifier: Apache-2.0 notices, or compliance conclusions. Avoid filler such as "none is invented
here" and embellished link labels such as "upstream LICENSE", "additional
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | [NOTICE](<upstream NOTICE URL at the imported commit>) patent grant", or "at the imported commit". Preserve actual required upstream
content; this rule excludes editorial additions, not required notices. Policy
Source: [Example Library](<upstream repository URL at the imported commit>) interpretation and exception reasoning belong in the adopted OSS policy or an
``` appropriate decision record, not the attribution document.
These are five fields, not a line limit. Include multiple statements and links
where needed. Omit the SPDX field when no applicable identifier exists; identify
nonstandard terms accurately through the linked text. Preserve licensing
alternatives and exceptions, and record a selected option when relevant. Do not
invent an identifier or silently resolve an unsettled licensing choice.
## License Texts And Upstream Links ## License Texts And Upstream Links
Link standard license texts to their local copies. Link project-specific Link standard license texts to their local copies. Link project-specific
notices to the upstream copies instead of storing them locally. Every upstream notices to their upstream copies. Every upstream repository or notice link must
repository or notice link must identify the exact commit corresponding to the identify the exact commit corresponding to the
imported version, including the selected source revision for copied material. imported version, including the selected source revision for copied material.
Do not use moving branches or version tags as substitutes for that commit.
Classify material by its contents, not its filename. An upstream `LICENSE`, Classify material according to its contents. An upstream `LICENSE`,
`COPYING`, or similar file may contain project-specific notices or exceptions `COPYING`, or similar file may contain project-specific notices or exceptions
in addition to standard wording. Link both the local standard text and the in addition to standard wording. Link both the local standard text and the
commit-specific upstream file when needed. Make companion license texts directly commit-specific upstream file when needed. Make companion license texts directly
reachable from the entry rather than leaving readers to infer their location. reachable from the entry.
For project-specific license and attribution material, this policy accepts For project-specific license and attribution material, this policy accepts
direct links to the applicable upstream texts as satisfying reproduction, direct links to the applicable upstream texts as satisfying reproduction,
@@ -91,17 +163,18 @@ source files; the central attribution entry does not authorize stripping them.
## Discoverability ## Discoverability
End the project's README with two friendly statements linking to its actual End the project's README with two friendly statements linking to its actual
license and the attribution document. For Scriptorium: grant in `COPYRIGHT` and the attribution document. For example, for a project
with the stated license:
```markdown ```markdown
Scriptorium is licensed under the [BSD 3-Clause License](LICENSE). Scriptorium is licensed under the [GPL v3.0 or later](COPYRIGHT).
[Open Source attribution notices](docs/oss/attribution.md) are available. [Open Source attribution notices](docs/oss/attribution.md) are available.
``` ```
Each new checked-in release document and its hosted download page must end Each new checked-in release document and its hosted download page must end
with links whose visible text is `LICENSE | ATTRIBUTION`. Use absolute URLs to with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute
those files at the release's immutable tag or corresponding immutable source URLs to those files at the release's immutable tag or corresponding immutable source
revision so the links work in both locations. This release navigation is distinct revision so the links work in both locations. This release navigation is distinct
from upstream component links, which must use the imported commit. from upstream component links, which must use the imported commit.
@@ -113,8 +186,9 @@ assets, source bundles, or a different binary package format.
## Maintenance And Exceptions ## Maintenance And Exceptions
Update notices in the change that adds, removes, upgrades, copies, or changes Update project licensing statements together when the author changes the grant
the distribution of a relevant component. Check the selected source's license or its scope. Update upstream notices in the change that adds, removes, upgrades,
copies, or changes the distribution of a relevant component. Check the selected source's license
and notices rather than assuming they are unchanged. Update affected entries, and notices rather than assuming they are unchanged. Update affected entries,
commit links, and texts; retain historical versions through Git. commit links, and texts; retain historical versions through Git.
@@ -128,8 +202,10 @@ to implement this policy.
Use the House Format routinely. Raise an exception only for a concrete obligation Use the House Format routinely. Raise an exception only for a concrete obligation
or unresolved rights question it does not address, including any arising from a or unresolved rights question it does not address, including any arising from a
particular distribution channel. Record the issue and selected treatment in the particular distribution channel. Record the issue and selected treatment in the
adopted policy or affected attribution entry as appropriate. Resolve the issue adopted OSS policy or an appropriate decision record. Attribution entries
before the affected use or distribution without reopening settled choices. contain the resulting factual identification and required material, without
repeating that reasoning. Resolve the issue before the affected use or
distribution without reopening settled choices.
Common ownership of projects is neither required nor a blanket exception. Common ownership of projects is neither required nor a blanket exception.
Apply the formatting convention prospectively. Do not rewrite published tags, Apply the formatting convention prospectively. Do not rewrite published tags,

View File

@@ -1,8 +1,10 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.2 **Base Policy Version:** 1.7
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
## Purpose ## Purpose
@@ -10,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents. routine intervention, avoid repeated work, and preserve published contents.
Adopt stronger verification or reproducibility requirements through an explicit
project-specific decision justified by the intended audience and support needs.
The repository-specific commands belong in `docs/release.md`. Historical release The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements. policy and link to it rather than introduce additional release requirements.
@@ -18,14 +23,13 @@ policy and link to it rather than introduce additional release requirements.
A source release identifies one exact committed source revision through an A source release identifies one exact committed source revision through an
immutable version tag and a version-matched, checked-in release note. The immutable version tag and a version-matched, checked-in release note. The
primary release branch is `main`; the authoritative publication remote is primary release branch is `main` unless the adopted policy specifies otherwise.
`origin`. The procedure must name the authoritative publication remote.
A successful push of the intended tag, with its source commit available on the A successful push of the intended tag, with its source commit available on the
authoritative primary branch, completes the release. Publish `main` before authoritative primary branch, completes the release. The source commit may be
invoking the publication command; the command requires pushed before the tag or published together with it through an atomic push.
that the remote branch exactly identifies the validated candidate and pushes The procedure must choose and document the supported approach.
only the selected annotated tag.
Release commands must finish at successful publication. They must not wait for Release commands must finish at successful publication. They must not wait for
or poll CI, require successful CI status, inspect downloadable artifacts, or or poll CI, require successful CI status, inspect downloadable artifacts, or
@@ -34,19 +38,20 @@ A failed or ambiguous push requires resolving the authoritative remote state
before declaring success or retrying; successful pushes do not require a before declaring success or retrying; successful pushes do not require a
separate remote read-back gate. separate remote read-back gate.
Scriptorium publishes Linux binaries and checksums asynchronously from the Repositories may publish source only. Additional binaries, images, packages,
tagged source. The procedure must identify those deliverables and the checksums, or other declared deliverables may be published asynchronously from
the tagged source. The procedure must identify those deliverables and the
responsibility of their automation. Published deliverables must be traceable responsibility of their automation. Published deliverables must be traceable
to that source and identify the same version. to that source and identify the same version.
Artifact delivery is a separate status. A successful tag push is not evidence Track source-release completion and artifact delivery separately. Report delivery
that artifacts are available. Delivery failures do not reverse source-release failures and optional investigations under artifact-delivery status.
success, and optional investigation must not delay release completion.
## Versioning And Compatibility ## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. Prereleases are not part of the adopted release channel. no leading zeroes. Prereleases require an explicit adopted policy defining
their format and use.
The selected version must be unused locally and on the authoritative remote. The selected version must be unused locally and on the authoritative remote.
Do not require queries to every configured remote or publication service. Do not require queries to every configured remote or publication service.
@@ -57,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`: For releases at or after `v1.0.0`:
- a major release may make intentional incompatible changes; - a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior; and - a minor release may add backward-compatible behavior or raise the Go consumer
minimum as described below; and
- a patch release may make backward-compatible fixes. - a patch release may make backward-compatible fixes.
In this context, "backward-compatible" means only that pre-existing, valid
configurations will continue to work following the relase. Behavior need not
remain strictly identical.
Before `v1.0.0`, a minor release may change a documented public, operational, Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must note explains the impact and required consumer action. A patch release must
@@ -69,6 +79,36 @@ Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts. changes; they do not redefine current compatibility contracts.
## Consumer Minimum And Release Toolchain
Distinguish the minimum toolchain supported for consumers from the toolchain
maintainers use to build and validate a release. Record the consumer minimum in
the language's standard metadata and explain its support meaning in canonical
documentation. Define the selected release toolchain and its setup commands in
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
choices.
For Go repositories, normally declare the initial stable release of the selected
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
when a dependency or an identified correctness fix requires it, and document
the reason.
For release-policy purposes, successful build and release validation on the
selected Go patch release are sufficient to presume support across that Go
series, subject to the declared consumer minimum and concrete evidence of
incompatibility. Investigate specific compatibility concerns as they arise.
Use the selected release toolchain for candidate validation and release builds,
including CI jobs performing those tasks. A newer validation patch version alone
leaves the consumer minimum unchanged.
A minor release may raise the Go consumer minimum, including from one Go series
to the next, both before and after `v1.0.0`. This is an explicit exception to the
backward-compatibility requirement for minor releases. Patch releases preserve
the consumer minimum. Explain an increase's impact and required consumer action
in the release note. Other incompatible changes remain subject to the versioning
rules above.
## Release Documentation And Preparation ## Release Documentation And Preparation
Every new release must include `docs/releases/<version>.md` in the tagged Every new release must include `docs/releases/<version>.md` in the tagged
@@ -76,9 +116,13 @@ source tree. Use the complete version tag as the filename and begin with a
title containing the product name and that exact version. title containing the product name and that exact version.
Include a short summary and any relevant compatibility impact or upgrade Include a short summary and any relevant compatibility impact or upgrade
instructions. Keep the note proportionate to the change. Fixed sections and instructions. Choose sections suited to the release and keep the note
explicit no-action boilerplate are not required. Existing historical notes proportionate to the change.
need not be rewritten to adopt this format.
Keep exact current contracts in their canonical documents and update affected
documentation with the behavior change. Link to those documents from the note
where useful. If annotated tags are used, derive their summary from the
checked-in note.
Include the release footer defined by the [OSS policy](oss.md#discoverability) Include the release footer defined by the [OSS policy](oss.md#discoverability)
in each new release document and preserve it on the hosted download page. The in each new release document and preserve it on the hosted download page. The
@@ -86,18 +130,11 @@ release procedure defines the concrete URLs and publication mechanics. Prepare
these links with the release note; they do not add a network check or approval these links with the release note; they do not add a network check or approval
gate. gate.
Keep exact current contracts in their canonical documents and update affected Handle version selection, release-note content, and retirement of completed
documentation with the behavior change. Link to those documents from the note roadmaps during preparation. Preserve planned and deferred work and repair
where useful. A release note must not substitute for current documentation. affected links when retiring roadmaps. Reuse ordinary change review for
Use annotated tags with their message derived from the checked-in note rather unintended files, credentials, and private data. Scope release-content review
than requiring a separately authored account of the same release. to the tagged source.
Version selection, release-note content, and retirement of completed roadmaps
are preparation responsibilities, not separate human approval gates. Preserve
planned and deferred work and repair affected links when retiring roadmaps.
Ordinary change review covers unintended files, credentials, and private data;
do not repeat it as a release-specific sign-off. Ignored local files are not
prohibited merely because they exist: they are not included in the tagged source.
## Candidate Validation ## Candidate Validation
@@ -107,24 +144,10 @@ mode or command may be provided for diagnosis, but must not be a required step
before publication repeats the same checks. before publication repeats the same checks.
Run the complete deterministic, offline default test suite once for the final Run the complete deterministic, offline default test suite once for the final
candidate, following the [testing policy](testing.md), and verify the required candidate, following the [testing policy](testing.md). For repositories that
build targets. Select those targets for the application's actual support publish builds, verify the required build targets. Select those targets for
commitments; native testing on each platform and access to particular hardware the application's actual support commitments; native testing on each platform
are not default release prerequisites. and access to particular hardware are not default release prerequisites.
The selected test invocation includes the race detector because the HTTP
service shares engines and backend capacity state across concurrent requests.
This single invocation covers both ordinary assertions and race detection.
Build both declared Linux architectures with the hosted release flags to catch
cross-compilation and packaging failures; native test hardware for each target
is not required. Existing architecture tests enforce dependency boundaries.
Retain narrow source guards against committed workspaces, vendor trees, and
module replacements: these can otherwise make a passing local build depend on
unpublished or substituted framework code. Disable workspace discovery and
vendor mode during validation. These guards preserve the established
cross-project boundary; they do not require exact dependency-version audits or
module-metadata rewrites at release time.
Additional gates must address a concrete risk that the existing checks do not Additional gates must address a concrete risk that the existing checks do not
adequately cover. Do not automatically require linting, race testing, module adequately cover. Do not automatically require linting, race testing, module
@@ -134,8 +157,8 @@ checks when their distinct protection justifies their cost. A one-time migration
check must not silently become a permanent release requirement. check must not silently become a permanent release requirement.
Release tests must not require real credentials, mutable application services, Release tests must not require real credentials, mutable application services,
paid APIs, provider probes, or inference calls. The procedure describes paid APIs, provider probes, or inference calls. The procedure may describe dependency
dependency preparation separately from offline validation. preparation separately from offline validation.
Avoid duplicate validation across release phases. Successful checks for the Avoid duplicate validation across release phases. Successful checks for the
same final candidate need not be repeated solely to satisfy another phase; same final candidate need not be repeated solely to satisfy another phase;
@@ -158,7 +181,9 @@ Automate the checks needed to publish the intended source under a fresh version:
- the worktree and index are clean on the primary release branch; - the worktree and index are clean on the primary release branch;
- the source being published is the exact candidate that passed validation, - the source being published is the exact candidate that passed validation,
including its matching release note; including its matching release note;
- the remote primary branch already identifies that exact candidate; and - the remote primary branch already identifies that candidate, or an atomic
source/tag push will advance it to that candidate without discarding remote
history; and
- the tag identifies the validated candidate and only the intended refs are - the tag identifies the validated candidate and only the intended refs are
published. published.
@@ -199,7 +224,8 @@ release without replacing its contents or reusing its version.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify: identify:
1. prerequisites, primary branch, and authoritative remote; 1. prerequisites, selected release toolchain, primary branch, and authoritative
remote;
2. version and release-note preparation; 2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards; 3. one publication command with its selected local checks and automated guards;
4. declared deliverables, required build targets, and automation responsibilities; 4. declared deliverables, required build targets, and automation responsibilities;
@@ -211,3 +237,27 @@ Use copyable commands where practical. Keep optional diagnostics and consumer
verification clearly optional. The procedure must not turn preparation work, verification clearly optional. The procedure must not turn preparation work,
ordinary change review, or post-publication investigation into additional ordinary change review, or post-publication investigation into additional
release gates. release gates.
## Scriptorium Release Selections
Scriptorium publishes stable releases from `main` through the authoritative
`origin` push endpoint. The validated candidate is published to the remote
branch before the annotated version tag; the publication command requires
exact agreement between the remote branch and candidate before pushing only
that tag. Atomic branch-and-tag publication and source-only delivery remain
general alternatives in this policy, not Scriptorium-supported workflows.
The tag message derives from the checked-in note. A successful tag push
completes the source release; binary delivery is asynchronous and does not
gate it.
The tagged source produces Linux amd64 and arm64 binaries and checksums through
the hosted workflow. Candidate validation runs the complete offline Go suite
once with the race detector because concurrent HTTP requests share engine and
backend capacity state. It builds both declared Linux targets. Narrow guards
reject committed workspaces, vendor trees, and module replacements so local
substitutions cannot mask unpublished framework code. These selected checks
address distinct application and release risks; no CI polling, artifact
availability, consumer installation, or new approval gate is required.
The [release procedure](../release.md) owns exact commands, targets, guards,
delivery reporting, and recovery steps.

View File

@@ -1,14 +1,16 @@
# Testing Policy # Testing Policy
**Base Policy Version:** 1.1 **Base Policy Version:** 1.3
**Last Updated:** 2026-09-26 **Last Updated**: 2026-11-17
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
## Purpose ## Purpose
Our tests exist to make **incorrect changes expensive and correct changes cheap**. Our tests exist to make **incorrect changes expensive and correct changes cheap**.
We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development. We optimize for sufficient confidence in important behavior while minimizing friction on future development.
## Every test has a cost ## Every test has a cost
@@ -22,9 +24,9 @@ Evaluate that tradeoff at two levels:
1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost? 1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would? 2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive. Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. Keep ordinary internal changes inexpensive.
The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing. Evaluate maintenance cost against the specific failure being protected. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
## Default testing style ## Default testing style
@@ -56,7 +58,7 @@ To the extent the following features are present in the application, prioritize
6. Previously observed or plausible regressions. 6. Previously observed or plausible regressions.
7. Representative integration and end-to-end workflows. 7. Representative integration and end-to-end workflows.
A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation. A package-level contract comprises behavior relied upon by another package or major collaborator.
Choose tests for requested behavior and established contracts. Tests must not Choose tests for requested behavior and established contracts. Tests must not
introduce new restrictions, guarantees, or threat scenarios merely because they introduce new restrictions, guarantees, or threat scenarios merely because they
@@ -75,14 +77,8 @@ Do not add tests merely because a function, branch, or line exists. Do not add a
## Choose the right test boundary ## Choose the right test boundary
Test through the narrowest stable boundary that expresses the behavior clearly. Choose the narrowest stable boundary that expresses the behavior clearly and
provides durable confidence with minimal incidental coupling.
For application configuration, ConfigKit owns exhaustive YAML grammar,
source traversal, import/overlay composition, provenance, and inspection
renderer tests. Scriptorium tests its selected definition, source discovery,
CLI override presence, command prerequisites, runtime conversion, credential
boundary, and representative execution/inspection workflows with the tagged
library. Do not copy the upstream parser test matrix into this repository.
This is often the package API, but it may instead be: This is often the package API, but it may instead be:
@@ -90,22 +86,15 @@ This is often the package API, but it may instead be:
- a package-level operation when several internal collaborators jointly produce the behavior; or - a package-level operation when several internal collaborators jointly produce the behavior; or
- a larger integration boundary when correctness emerges from interaction with a real dependency. - a larger integration boundary when correctness emerges from interaction with a real dependency.
Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
## Test behavior, not implementation ## Test behavior, not implementation
A test should protect a decision, contract, or invariant. A test must not memorialize the current implementation. A test should protect a selected decision, contract, or invariant.
A test is suspect when its main purpose is to detect that someone: A test is suspect when it primarily detects changes to private constants or
helpers, equivalent operation ordering, incidental formatting, equivalent
algorithms, or internal structure that preserves behavior.
- changed an internal constant; Behavioral tests should normally remain stable through internal refactoring that preserves the contract.
- renamed or split a private helper;
- reordered equivalent internal operations;
- changed incidental formatting;
- replaced one correct algorithm with another; or
- refactored internal object structure without changing behavior.
Refactoring should normally require no test edits unless the refactored structure is itself part of the contract.
## Expected effects of different changes ## Expected effects of different changes
@@ -122,7 +111,7 @@ A test failing is not the same as a test needing to be edited. Many tests may co
## Separate mechanism from policy ## Separate mechanism from policy
Configurable thresholds and defaults must not be duplicated throughout the test suite. Derive expectations from test-controlled configuration and relationships.
For this example, assume the selected contract rejects a request to start more For this example, assume the selected contract rejects a request to start more
processes than a configured limit. Do not encode its production default indirectly: processes than a configured limit. Do not encode its production default indirectly:
@@ -158,33 +147,52 @@ limit solely to reproduce this example.
The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement. The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals. Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior.
For established concurrency limits, distinguish these behaviors where the contract requires them: For established concurrency limits, distinguish these behaviors where the contract requires them:
1. **Configuration handling:** values are accepted or rejected according to the selected contract. 1. **Configuration handling:** values are accepted or rejected according to the selected contract.
2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit. 2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value. Use a test-controlled limit and measure the behavior relative to that limit.
## Avoid semantic duplication across layers ## Assign each behavior a test owner
Each behavior should have a clear test owner. Where these layers exist, assign ownership as follows:
- Configuration tests own application YAML, strict decoding, discovery, - Parser tests own parsing cases.
precedence, and application defaults. - Validator tests own validation rules.
- CLI tests own argument mapping, streams, summaries, exit behavior, and - Domain tests own transformations and invariants.
representative command workflows. - Adapter tests own external integration behavior.
- HTTP tests own DTOs, strict decoding, limits, status mapping, and restricted - Orchestrator tests own coordination and failure propagation.
artifact policy. - CLI tests own argument and configuration mapping.
- Formatter tests own prepared-run and definition-inspection text and JSON - End-to-end tests prove that representative assembled workflows work.
presentation.
- Architecture tests own dependency direction and removal invariants. Give each layer its distinct responsibility and keep expectation updates localized to the contract being changed.
## Scriptorium Test Ownership
- Application configuration tests own Scriptorium's definition, strict
decoding at its boundary, source discovery and selection, explicit CLI
override presence, application defaults, runtime conversion, and safe
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
import and overlay composition, provenance, and inspection renderers.
- CLI tests own argument mapping, streams, output, exit behavior, and
representative run, render, inspect, serve, and config workflows.
- HTTP tests own DTO decoding, transport limits, status and error mapping,
restricted artifact reading, and representative server workflows.
- Formatting tests own prepared-run and definition-inspection text and JSON
presentation. Architecture guards own dependency direction and removed
framework-package boundaries.
- Promptkit owns framework parsing, orchestration, validation, profiles, and - Promptkit owns framework parsing, orchestration, validation, profiles, and
model-client behavior. Scriptorium's definition compatibility fixtures protect model-client behavior. Scriptorium's definition and execution fixtures
its adapter plumbing without duplicating the upstream format contract. protect adoption through its public adapter boundary without duplicating
Promptkit's exhaustive format matrix.
Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files. HTTP lexical containment, size limits, and shared engine and backend capacity
across concurrent requests merit focused adapter coverage because violations
cross a security or concurrency boundary. Choose cases by realistic risk
rather than a coverage quota or a duplicated upstream matrix.
## Use test doubles deliberately ## Use test doubles deliberately
@@ -205,12 +213,9 @@ Mocks are appropriate when the contract includes facts such as:
- an expensive API is called no more than once; or - an expensive API is called no more than once; or
- a security audit event is emitted. - a security audit event is emitted.
Do not use mocks merely to isolate every object or reproduce the implementation's call graph.
## Go-specific guidance ## Go-specific guidance
Select techniques according to the behavior and risk being tested. The following Select techniques by behavior and risk:
are options, not a checklist that every package or application must satisfy:
- table-driven tests for meaningful behavioral categories and boundaries; - table-driven tests for meaningful behavioral categories and boundaries;
- `t.TempDir()` for real filesystem behavior; - `t.TempDir()` for real filesystem behavior;
@@ -220,55 +225,48 @@ are options, not a checklist that every package or application must satisfy:
- integration tests where correctness depends on component interaction; and - integration tests where correctness depends on component interaction; and
- a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries. - a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries.
Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. Use exact error-wording assertions only when the wording is contractual.
At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual. At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Use complete diagnostic snapshots only when the wording is contractual.
Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update. Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs. Keep tests readable and direct. Size test helpers and fixture frameworks to the maintenance benefit they provide.
## Coverage ## Coverage
Coverage is a diagnostic, not a target. Use coverage to locate untested critical branches and unexpectedly weak packages. Evaluate test quality through meaningful behavioral protection and choose coverage according to risk.
Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone. Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
Security-sensitive HTTP containment and external mappings may warrant denser
coverage than straightforward process wiring. Uneven coverage is acceptable
when it reflects risk.
## Regression tests ## Regression tests
A bug fix should normally include a regression test that fails before the fix and passes afterward. A bug fix should normally include a regression test that fails before the fix and passes afterward.
Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug. Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant.
Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it. Remove or consolidate a test when the underlying design has made recurrence impossible, its protection is redundant, or a stronger invariant test subsumes it.
## Deleting or rewriting tests ## Deleting or rewriting tests
Tests are maintained code, not permanent historical artifacts. Delete or rewrite tests when maintenance cost exceeds their continuing
protective value.
Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
Strong candidates include tests that: Strong candidates include tests that:
- require updates after harmless internal changes; - require updates after harmless internal changes;
- directly assert private constants without protecting a real contract; - assert incidental private constants or snapshot large amounts of incidental output;
- duplicate the same policy across several layers;
- verify mock choreography rather than outcomes; - verify mock choreography rather than outcomes;
- snapshot large amounts of incidental output; - duplicate policy across layers, retest trivial helpers covered by package
- test trivial private helpers already exercised through stable package behavior; behavior, or protect risks covered more effectively elsewhere;
- protect risks already covered more effectively elsewhere;
- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or - are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
- no longer correspond to a plausible failure mode. - no longer correspond to a plausible failure mode.
Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them. Several brittle tests may encode one genuine requirement. Consolidate them into one durable behavior-level or invariant test.
## Reviewing a proposed test ## Reviewing a proposed test
Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test. Use the following questions when a proposed test needs closer evaluation. Significant test additions should be reviewable against them; written answers are optional for routine tests.
1. Which requested behavior or established contract does it protect, and what realistic defect would violate it? 1. Which requested behavior or established contract does it protect, and what realistic defect would violate it?
2. How likely and consequential is that defect, and is it already protected elsewhere? 2. How likely and consequential is that defect, and is it already protected elsewhere?
@@ -282,10 +280,9 @@ A test suite is sufficient when:
- important requested behavior and established contracts are protected against realistic, consequential failures; - important requested behavior and established contracts are protected against realistic, consequential failures;
- boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere; - boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere;
- failures provide useful signal rather than redundant noise; - failures provide useful, distinct signals;
- legitimate internal changes usually do not require test edits; and - tests usually remain stable through legitimate internal changes; and
- additional tests would mostly repeat existing protection or preserve inconsequential implementation details. - additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
Sufficiency is a risk judgment, not a coverage percentage, test count, or required Reassess sufficiency as the application, its users, and the consequences of
mix of testing techniques. Reassess it as the application, its users, and the failure evolve.
consequences of failure evolve.

View File

@@ -9,11 +9,31 @@ discoverability requirements.
## Prepare The Candidate ## Prepare The Candidate
Use a POSIX shell, Git with a configured tagger identity and access to Use a POSIX shell, Git with a configured tagger identity and access to
`origin`, and a Go toolchain compatible with `go.mod`. The native host must `origin`, and the selected release toolchain, Go 1.27.4. The native host must
support Go's race detector and have its required C compiler. If Git is support Go's race detector and have its required C compiler. If Git is
configured to sign tags, its signing tool and key must be available. Run from the configured to sign tags, its signing tool and key must be available. Run from the
repository root. Provision the toolchain and module cache before offline repository root. The [developer guide](development.md#baseline-validation)
validation; when dependencies are not cached: explains the separate Go consumer minimum; selecting a release toolchain does
not raise that minimum.
Install Go 1.27.4 from the [official downloads](https://go.dev/dl/) or an
equivalent package source before validation. Set `release_go_root` to its
installation directory, replacing the illustrative path below, and select it
in the release shell:
```sh
release_go_root=/path/to/go1.27.4
export PATH="$release_go_root/bin:$PATH"
export GOTOOLCHAIN=local
go version
```
The version output should identify `go1.27.4`. Keep this selection and the
hosted workflow's Go image in step when deliberately updating the release
toolchain. Ordinary contributor checks may use another compatible toolchain.
Provision the module cache before offline validation; when dependencies are
not cached:
```sh ```sh
GOWORK=off go mod download GOWORK=off go mod download
@@ -23,20 +43,19 @@ Choose an unused stable version under the release policy. Commit its note as
`docs/releases/<version>.md`, beginning with a title such as `docs/releases/<version>.md`, beginning with a title such as
`# Scriptorium v0.14.0` (an example, not an instruction to select that version). `# Scriptorium v0.14.0` (an example, not an instruction to select that version).
Include a concise summary and relevant compatibility impact or upgrade action. Include a concise summary and relevant compatibility impact or upgrade action.
End the note with the following footer, replacing `<version>` in both absolute End the note with the following footer, replacing `<version>` in all three absolute
URLs with the selected version tag (for example, `v0.14.0`): URLs with the selected version tag (for example, `v0.14.0`):
```markdown ```markdown
[LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/docs/oss/attribution.md) [COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/docs/oss/attribution.md)
``` ```
Check that both URLs name files in the candidate tree at that tag. The tag may Check that all three URLs name files in the candidate tree at that tag. The tag may
not resolve online until publication. The checked-in note is copied unchanged not resolve online until publication. The checked-in note is copied unchanged
into the hosted release body by the existing workflow, so do not maintain a into the hosted release body by the existing workflow, so do not maintain a
second footer there. second footer there.
Update affected canonical documentation with the change, and retire completed Update affected canonical documentation with the change, and retire completed
roadmap material when appropriate while preserving deferred work and links. roadmap material when appropriate while preserving deferred work and links.
No extra release-specific review signoff is required.
Finish and commit the intended candidate on `main`, then publish that branch: Finish and commit the intended candidate on `main`, then publish that branch:
@@ -63,9 +82,8 @@ remote version, exact agreement with authoritative remote `main`, and a
checked-in note whose first-level title contains Scriptorium and the exact checked-in note whose first-level title contains Scriptorium and the exact
version. Ignored local files do not make the candidate dirty. version. Ignored local files do not make the candidate dirty.
The existing source-boundary guards reject committed workspaces, vendor trees, The source-boundary guards reject committed workspaces, vendor trees, and
and module replacements. No migration-specific exact Promptkit version audit module replacements.
is required.
It then runs the complete suite once with the race detector and builds Linux It then runs the complete suite once with the race detector and builds Linux
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and

26
docs/releases/v0.15.0.md Normal file
View File

@@ -0,0 +1,26 @@
# Scriptorium v0.15.0
This minor release changes Scriptorium's application grant to GPL version 3 or
later, aligns its repository policies and attribution notices, and updates the
selected Promptkit and ConfigKit patch releases.
## Licensing and upgrade impact
Scriptorium's application source and binaries are now distributed under
GPL-3.0-or-later. Review [COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/COPYRIGHT)
and [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/LICENSE)
before redistributing or incorporating this version. Material adapted from
Standard Repository Policies remains separately licensed under CC-BY-SA-4.0;
the [attribution notices](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/oss/attribution.md)
identify its scope and license text. Existing dependency grants are unchanged,
and earlier tagged releases retain their own published terms.
## Dependency updates
Scriptorium now selects Promptkit v0.11.2 and ConfigKit v0.4.2. The current
[CLI](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/cli.md),
[HTTP API](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/api.md),
and [configuration](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/config.md)
references describe the executable contracts.
[COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/oss/attribution.md)

View File

@@ -0,0 +1,334 @@
# CommandKit Adoption
## Status And Intent
Initial roadmap, prepared 2026-11-19. The product direction is agreed;
implementation has not begun. This document owns the target and product intent,
incorporating the decisions in the [migration notepad](commandkit-notepad.md).
The notepad remains the discussion
record. The [Narratio proposal](narratio-feature-request.md) supplies consumer
acceptance scenarios for requirements discovery. The
[implementation plan](implementation.md) owns the ordered stages and concrete
adapter choices.
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records
the native-interface adoption and ownership boundaries, complementing ADRs 0004
and 0005.
Make Scriptorium a CommandKit-native executable interface over PromptKit,
including ckconfig and ckprompt. Most subprocess consumers should be able to
select a stored prompt and consume its resulting artifact directly. Operators
and consumers needing inspection or metadata should use native upstream
interfaces and reports.
This is a full CLI cutover. Existing command names, flag spellings, parsing,
report shapes, and exit conventions are not compatibility constraints. Release
migration guidance replaces a compatibility layer. Implementation may proceed
in reviewable increments; this does not require shipping both interfaces.
## Current Baseline And Upstream References
Reviewed Scriptorium baseline: `5f32a4f2adb2d382a6cfce3a787ada4576be7705`.
The module uses Go 1.27.0, PromptKit v0.23.3, and ConfigKit v1.2.1. CommandKit
is not yet a dependency.
| Current implementation | Migration work |
| --- | --- |
| `internal/adapter/cli` dispatches and parses commands, resolves configuration, builds engines and requests, writes diagnostics, and returns integer statuses. | Replace dispatch and shared CLI mechanics with CommandKit; retain application loading, request mapping, and effects through its extension points. |
| `run` uses flag-based prompt selection and writes generated content; `--execution-report` writes an observer-derived Scriptorium report. | Adopt positional prompt selection, native request flags, and native result reporting. |
| `render`, `inspect prompt`, and `inspect profile` use custom presentation in `internal/format`. | Replace with native ckprompt operations and remove unused presentation code. |
| `config` and `inspect configuration` separately expose application and framework configuration. | Install one ckconfig family with `app` and `promptkit` scopes, including comparison. |
| `internal/config` owns application schema, discovery, defaults, and conversion through ConfigKit. | Adapt its loader and explicit overrides to standard selections and scope capabilities. |
| `serve` constructs a restricted HTTP artifact reader and one shared PromptKit engine. | Register it as an application command and preserve existing HTTP behavior. |
| `internal/report` also supplies HTTP's optional execution report. | Remove its superseded CLI use; retain functionality still used by HTTP. |
The [current CLI](../cli.md), [configuration contract](../config.md),
[adapter internals](../internal/adapters.md), and
[subprocess contract](../integrations/subprocess.md) describe the starting
behavior, not a compatibility checklist for this migration.
The reviewed upstream combination is CommandKit v0.7.0, ckconfig v0.9.0,
and ckprompt v0.10.0, documented at revision
`d330d7637f2e7507eca931a899397222c82bc892`:
- [Consumer guide][upstream-guide]: composition, loading, reusable bindings,
reporting, and outcomes.
- [CLI reference][upstream-cli]: native command grammar and observable behavior.
The selected released combination retains Scriptorium's adopted PromptKit
v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit
v0.23.2 minimum does not require a downgrade. Supported public APIs and released
dependencies remain subject to the existing
[architecture policy](../policy/architecture.md).
No selected-format accessor is required for this migration. The native
invocation reporter handles the main result on stdout; the existing writer API
handles the separate report with automatic or explicitly selected rendering.
The upstream accessor proposal remains optional API work, independent of
Scriptorium's adoption.
## Target End State
### Responsibilities And Scope
CommandKit owns command declarations, dispatch, common parsing, help, reporting,
and outcome mechanics. ckconfig and ckprompt supply their standard families.
ConfigKit owns configuration policy through the fully resolved handoff,
including resolution of PromptKit's configuration using PromptKit's schema and
rules. PromptKit owns definition, preparation, execution, validation, and
inspection semantics. Scriptorium owns the application domain: it interprets
resolved values and uses upstream APIs and results to satisfy user requests.
Application commands, process lifecycle, and artifact delivery remain local.
This preserves Scriptorium's request-independent execution model and support
for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md).
It adds no workflow, conversation, archive, or resume system. HTTP design review
remains separate work before v1.0; migrating its startup command does not
redesign the HTTP API or its execution-report representation.
Use shared upstream capabilities where available. A concrete missing shared
capability should prompt an upstream discussion before a local substitute.
Application-specific loading and effects remain ordinary application work.
### Command Surface
| Surface | Target |
| --- | --- |
| Generation | Application command `run PROMPT_ID`, with a required positional prompt ID and no duplicate prompt flag. |
| HTTP service | Application command `serve`. |
| Configuration | Native `config` family with `app` and `promptkit` scopes: scope discovery, validation, effective values, sources, explanations, and diff. |
| Resource inspection | Native prompt, profile, backend, namespace, and collection inventories and applicable named inspection. |
| Dependency discovery | Native `promptkit requirements show PROMPT_ID`. |
| Concrete validation | Native `promptkit requirements validate` capability. |
| Prepared preview | Native `promptkit show prepared PROMPT_ID`, replacing `render`. |
| Provider diagnostics | Native smoke-test commands, invoked explicitly. |
| Executable support | Native help, version, reporting modes, outcomes, and shell completion. |
Install application commands outside the reserved standard families. Enable
the native convenience aliases consistently. Prefer shorter spellings such as
`--profile`, `--input-file`, `--input-text`, and `--var` in examples and guidance
where applicable and unambiguous; canonical `--llm-*` spellings remain available.
Aliases retain upstream semantics: `--input` supplies literal text, and file
references use `--input-file`.
Reuse applicable ckprompt resource, input, and execution bindings for `run`.
Preserve explicit-value presence, including zero and empty values, and native
repeated mapping semantics. Do not carry forward comma splitting or obsolete
aliases merely because the old parser accepted them. Keep application source
selectors, server settings, output destinations, and whole-operation deadlines
distinct from framework request controls.
Completion initially uses native command, flag, static-value, and path
completion, with suitable application hints. Dynamic installed-resource
completion is not required. Smoke tests are explicit operator operations;
their inclusion does not make provider access a startup or release prerequisite.
Preserve native diagnostic findings, including successful invocations whose
reports describe unsupported or unsuccessful checks.
### Configuration Authority And Native Inspection
The migration implements the ownership decision in
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) through
these two boundaries:
1. **ConfigKit's completed result is authoritative configuration.** Scriptorium
supplies its schema, domain defaults, validation, and genuine application
configuration-resolution logic through ConfigKit's supported extension
points. Those callbacks operate within ConfigKit's lifecycle and evidence
model, including recording resolution changes through the supported APIs.
Scriptorium consumes the completed result without subsequently revising what
effective configuration means. Runtime conversion and request construction
may consume resolved values; they do not introduce another configuration
merge, defaulting, or normalization pass. This follows the configuration
boundary established in [ADR 0005](../adr/0005-configkit-boundary.md).
2. **Standard inspection exposes that result through native adapters.**
Scriptorium selects and acquires the requested configuration and declares
supported capabilities. Use `ckconfig.FromConfigKit` for the application
result and `ckprompt.ConfigScope` for PromptKit's captured configuration
inspection within the native `ckconfig` family. Scriptorium does not assemble
a different effective document, reconcile separate explanation trees, or
reinterpret upstream path semantics. Effective values, sources, explanations,
metadata, and comparisons come from the acquired upstream result through
those adapters. CommandKit owns their standard presentation.
Application selection and supported configuration overrides feed the loading
lifecycle before its completed result is exposed. Adapting loaders or supplying
scopes below does not authorize a second configuration-resolution or inspection
model. The `app` and `promptkit` scopes retain their respective upstream evidence;
they are not combined into a synthetic effective configuration.
### Configuration, Collections, And Request Context
Expose application configuration through `app` and captured framework
configuration through `promptkit`. Collections are resources within the
framework configuration, not separate configuration scopes. Application-only
inspection must work without constructing a PromptKit engine.
`--config` selects Scriptorium application configuration on every applicable
command, including framework inspection. That configuration selects framework
sources. Adopt native `--overlay` selection and upstream selection presence
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
not an arbitrary file path. Map selections through the application's ConfigKit
loader rather than retaining the old flag parser as a compatibility layer.
Preserve useful application source and server controls through appropriate selectors.
Enable temporary configuration overrides where the loader supports them,
passing native override records into loading. The reviewed PromptKit scope
does not support these overrides; do not emulate them locally. Configuration
comparison must support independent selections for both sides in both scopes,
including corresponding application selectors where needed.
Keep the established collection-discovery model: ConfigKit imports discover
`collection.yml` and `collection.yaml` entry points; each independently
maintained collection declares its namespace and imports its own definitions
through relative references. Retain the
[discovery example](../../examples/config.discovery.yml) and representative
multi-definition collection documentation. No Git update manager or custom
collection traversal is part of this migration.
Use native prompt, profile, and backend namespace selectors independently on
applicable commands. Short caller-supplied IDs use their selected namespace;
qualified IDs remain exact. Selection does not rewrite stored references.
Retain upstream inventory filters and defaults, including `--all-namespaces`.
Do not add a configurable default namespace in this migration.
Share applicable configuration selection, engine loading, and request mapping
across execution, preview, validation, and discovery. Preserve each operation's
upstream lifecycle: discovery can work before artifacts exist; preparation
loads and renders without generation. This is consistency of selection and
mapping, not a promise that separate invocations see an immutable snapshot.
### Generation, Reports, And Process Outcomes
Use a main CommandKit `Report` whose value is PromptKit's native `RunResult` and
whose text template emits only the resulting artifact content. The template
should emit artifact bytes without presentation decoration. Default/text serves raw
artifact consumers; JSON and YAML expose the full native result. The native
structured serialization, including its representation of artifact bytes,
remains upstream-owned. There is no Scriptorium result envelope.
| Selection | Behavior |
| --- | --- |
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
| `--format text` or default | Main result contains only the artifact. |
| `--format json` or `--format yaml` | Main result contains the native result and metadata. |
| `--report PATH` | Additionally write the native result through CommandKit's renderer, independently of the main format and destination. Without `--report-format`, use native automatic rendering. |
| `--report-format text\|yaml\|json` | Explicitly select the separate report's native rendering format. |
The separate report contains the same native `RunResult`, without the main
report's artifact-only text template. Omission of `--report-format` leaves the
format unset so CommandKit decides how to render it. Its current automatic
rendering for structured values is YAML; future upstream default changes flow
through. Scriptorium does not set a default report format.
There is no `--output` or legacy `--out` flag. Callers save the main result by
redirecting stdout in a shell or supplying a file as the subprocess stdout
destination. Diagnostics remain on stderr. Callers wanting main output omit
`--quiet`, including when stdout is redirected. Filename extensions do not
select formats. The separate report includes the native result's content as
well as metadata; it replaces the CLI's old
observer-derived metadata projection. A caller wanting an artifact file plus
metadata redirects stdout and selects a separate `--report` path. The caller
manages redirected destinations and retention; there is no automatic reporting
directory or report collection.
Native result reporting is available when PromptKit returns a result.
Operational errors return nonzero status and native failure diagnostics, without
synthesizing replacement results. Preserve PromptKit's distinction between a
completed content check reporting `ValidationFailed` and an operational failure
to perform the check. Neither extra content judgments nor a structured JSON
invocation-error envelope is part of this migration.
Adopt CommandKit's quiet and verbosity semantics, including rendering and
presentation failures. Console results use the invocation reporter; diagnostics
use its diagnostic channel. An explicit `--report` write is an application
effect rendered through the writer API and still occurs in quiet mode.
Quiet does not cancel generation; it suppresses the main result even when
stdout is redirected, while failure explanations remain visible. Move any
retained generation summary into an appropriate native message category.
Map typed upstream failures and configuration diagnostics into native outcomes,
without parsing error text. Standard statuses remain upstream-owned. Use an
application domain outcome for completed validation failure, distinct from
usage and diff-check outcomes. The implementation plan specifies the mapping.
Delivery failures must produce a nonzero outcome and explanation, preserving
native presentation-failure behavior where applicable, including an already
nonzero domain outcome. Requested file errors must not disappear merely because
they occur outside the invocation reporter.
For `--report`, use ordinary file replacement without creating parents. Attempt
the main output followed by the report, and attempt the report even if main
delivery fails. Open the report only when a native result exists. Redirection
and its file-creation or truncation behavior belong to the caller. Scriptorium
does not manage the main output file or check it against the report path. This
adds no rollback or transactional delivery; written bytes may remain after
failure.
Wire signal cancellation through the invocation context. Keep the application
whole-operation budget separate from the native per-attempt timeout binding.
Use `--run-timeout` with Go duration values mapped to PromptKit's
`OperationTimeout`, preserving upstream zero, negative-value, and timeout
behavior without a second timeout policy.
### Preview And Consumer Inspection
Remove `render`, its compatibility aliases, `defaults.render_format`, and
unused prepared-output formatters. Native prepared preview uses its upstream
report, default/text YAML presentation, standard formats, request flags,
diagnostics, and outcomes. It does not call a model. Consumers save preview
output through stdout capture or redirection, as they do for generation.
Adopt native inspection reports, including captured prompt messages and rendered
prepared content, without recreating old summary projections. Native schemas
and adopted upstream versions govern structured output; this migration adds no
separate schema-version wrapper or compatibility guarantee.
Implement the [Narratio acceptance scenarios](narratio-feature-request.md#consumer-acceptance-scenarios).
Requirements discovery exposes native classification, completeness, and issue
codes. Complete discovery is distinct from satisfied bindings and execution
readiness; partial discovery can succeed with status zero. Narratio owns its
pipeline, binding graph, and policy for incomplete findings. Preserve native
metadata without inventing prompt versions, variable defaults, or input schemas.
## Acceptance And Scope Boundaries
The target is met when Scriptorium exposes the native command surface and
application behavior above, superseded CLI machinery is retired, and maintained
documentation and examples describe the shipped interface. In particular:
- Configuration callbacks, runtime consumers, and native inspection agree on
ConfigKit's completed values and evidence. Application-only inspection needs
no PromptKit engine, and comparison sides retain independent selections.
- Applicable selection and request context remain consistent across execution,
preparation, discovery, and inspection of multiple independently maintained
collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate
reports expose the native result. Main output uses stdout and native quiet
semantics; the optional report file uses native automatic or explicitly
selected rendering, independently of quiet, with useful failure outcomes and
nontransactional delivery.
- Narratio's linked acceptance scenarios are supported, including useful partial
discovery and discovery before generated artifacts exist.
- Native help, aliases, completion, and explicit smoke testing are available.
Including smoke testing adds no provider access prerequisite to startup or
release validation.
- Server startup reaches the existing HTTP adapter with its transport,
restricted-reading, execution-report, and shared-capacity behavior intact.
- Canonical contracts, examples, dependency attribution, and migration guidance
reflect the cutover. The CLI migration includes positional prompt selection,
command replacements, literal versus file inputs, repeated mappings, overlay
selection, native endpoint/timeout controls, stdout redirection in place of
output-file flags, content-bearing reports, optional report-format selection,
report availability, quiet behavior, and changed exit statuses.
The [implementation plan](implementation.md) owns task sequencing, concrete
adapter mappings, verification steps, and sprint status. There are no unresolved
product decisions or selected-format accessor release prerequisite.
The [release policy](../policy/release.md#versioning-and-compatibility) governs
the eventual breaking release version. This migration does not itself select
or publish a release, introduce a compatibility layer, or settle the separate
pre-v1.0 HTTP design review.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md

View File

@@ -0,0 +1,331 @@
# CommandKit migration notepad
Status: discussion record incorporated into the
[adoption roadmap](commandkit-adoption.md) and
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md).
The roadmap owns implementation work; the ADR records the ownership decision.
## Product context
Scriptorium is a neutral executable interface over PromptKit. Its primary
consumers are applications that need to run stored prompts and consume their
output without importing PromptKit or building an internal prompting workflow.
The CLI and its subprocess contract are therefore central to this migration.
An installation may load many independently maintained collections. The
existing collection model remains the starting point: ConfigKit imports discover
`collection.yml` or `collection.yaml` entry points, each collection declares its
own namespace, and relative imports assemble its profiles and prompts. See the
[configuration contract](../config.md) and
[discovery example](../../examples/config.discovery.yml).
HTTP remains secondary to the CLI discussion. A broader HTTP design review is
planned before v1.0; adopting CommandKit does not itself settle that design.
## Agreed direction
### Full native cutover
Decision recorded 2026-11-19: become a CommandKit-native application, including
`ckconfig` and `ckprompt`, and adopt upstream public conventions and
recommendations as fully as possible.
Backward compatibility with existing CLI conventions is an explicit non-goal.
Legacy command names, flag spellings, parsing rules, report shapes, and exit
semantics do not constrain the new interface. Do not add compatibility wrappers,
legacy aliases, or duplicate inspection implementations solely to preserve the
old CLI. Adopt upstream convenience aliases as described below.
Provide migration guidance in release documentation so consumers can update
their invocations and output handling. Guidance replaces a compatibility layer;
it does not require a transition period with both interfaces. The
[release policy](../policy/release.md#versioning-and-compatibility) governs
release version selection and documentation of breaking changes.
### Ownership and integration
Use CommandKit for command declarations, parsing, help, reporting, and outcomes;
use `ckconfig` and `ckprompt` for their standardized operator interfaces.
Scriptorium should retire the corresponding custom inspection machinery as
those interfaces take over.
ConfigKit owns configuration policy through the fully resolved handoff,
including PromptKit configuration resolution. PromptKit owns prompting and
inspection semantics. Scriptorium interprets resolved values and uses upstream
APIs and results to satisfy user requests. CommandKit adoption does not introduce
workflow or conversation state. ADR 0006 records these boundaries.
Prefer shared upstream capabilities over new Scriptorium-specific equivalents.
If a required shared capability is missing, discuss an upstream request before
designing a local substitute. Application-specific behavior still belongs in
Scriptorium.
### Initial capability set
Decision recorded 2026-11-19: include configuration comparison, provider smoke
tests, and shell completion in the initial migration, alongside application and
PromptKit configuration scopes, resource inventories and inspection,
requirements discovery, concrete request validation, and prepared-request
preview.
Use the existing upstream capabilities. Configuration comparison should cover
both application and PromptKit scopes, with independent selections for each
side. Provider smoke tests run when explicitly invoked; including them does not
make them startup checks or release prerequisites. Document provider usage and
the distinction between successful diagnostic execution and positive findings.
Shell completion should use upstream command, flag, static-value, and path
completion, with appropriate hints for application-owned inputs. Dynamic
completion of installed resource names is a separate possible enhancement.
Application-specific wiring remains to be designed, but inclusion of these
capabilities is settled. The prepared-request preview decision is recorded below.
### Generation and subprocess requirements
Decision recorded 2026-11-19: optimize the default generation response for the
majority of consumers, who want only the raw resulting artifact. Metadata is
optional and available through the native result reporting choices below.
Prefer native CommandKit reporting and PromptKit result types before introducing
a Scriptorium-specific response format. A failure must produce a nonzero process
status and information explaining the failure. This does not require a new
structured error envelope: native diagnostics are an acceptable way to deliver
that information.
Scriptorium remains a neutral interface to PromptKit. Pass through the errors,
validation outcomes, and result information that PromptKit supplies rather than
adding independent judgments about generated content or redefining upstream
failure semantics. Adapting those outcomes to CommandKit and process exit codes
is application work; deciding what constitutes a PromptKit failure is not.
### Native result reporting and separate report files
Decision revised 2026-11-19: use a main CommandKit `Report` containing PromptKit's
native `RunResult`, with a text template that emits only generated content.
Default/text output serves artifact consumers; standard JSON/YAML formats expose
the native result and its metadata. This composes existing upstream APIs;
ckprompt does not supply a general generation command or prescribe this template.
Include an optional `--report PATH` flag requiring an explicit file destination.
Omitting it creates no separate report file. When requested, pass the native
`RunResult` to CommandKit's renderer without an artifact-only text template.
Optional `--report-format text|yaml|json` selects the native rendering format.
When omitted, leave the format unset and let CommandKit choose; its current
structured-value default is YAML, and future upstream changes flow through.
There is no Scriptorium default or filename-based selection. Report rendering
is independent of the main result's `--format`, representation, and destination.
Failure to write a requested report is a delivery failure and must produce a
nonzero outcome and diagnostic.
Do not include a configured reporting directory or automatic report collection
in the initial migration. The caller selects the report path and manages its
lifecycle. A configured directory may be considered later if automatic
collection becomes useful; an explicit report path would take precedence.
Native result reports are available when PromptKit returns a result. Operational
failures produce a nonzero exit and native diagnostics. This follows PromptKit's
capabilities and is the intended boundary, not a gap for Scriptorium to address.
Do not synthesize replacement results or add an alternative failure-report
format to compensate for the absence of a native result.
### Output destinations and verbosity
Decision revised 2026-11-19: remove the previously selected `--output` flag.
The main result uses the native invocation reporter and stdout. Callers save it
through shell redirection or a subprocess stdout destination; diagnostics remain
on stderr. Do not retain the old `--out` flag.
`--format` selects the stdout representation independently of redirection:
default/text emits the raw artifact, while JSON/YAML emits the native result
with metadata. The filename does not select the format. `--report PATH` remains
an additional native result report, so callers can save the raw artifact and its
report to separate files by redirecting stdout and supplying `--report`.
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
mode selection, message visibility, rendering, and presentation failures. Do
not add Scriptorium-specific exceptions to normal command-output suppression.
Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel.
An explicit `--report` write remains an application-owned effect in quiet mode,
using the existing writer API. Quiet suppresses the main result even when stdout
is redirected; callers wanting that result omit quiet. No
selected-format accessor is needed, so the upstream proposal is no longer a
migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
shared verbosity rules.
### Prepared-request preview
Decision recorded 2026-11-19: replace `render` entirely with the native
`promptkit show prepared PROMPT_ID` command, enabled through ckprompt's request
preparation integration. Remove `render` without a compatibility alias.
Use the native prepared-run report, standard request flags, diagnostics,
verbosity, and outcomes. Default and explicit text output use the upstream YAML
presentation; JSON remains available through `--format json`. Remove
`defaults.render_format` and any custom prepared-output formatting code left
unused by the migration.
Share application configuration selection, collection loading, and applicable
request construction with generation so previews describe the corresponding
execution request. PromptKit continues to own preparation semantics.
Use the native result stream for preview output; consumers can capture or
redirect stdout to save it, as with generation. File-output convenience does
not justify retaining a separate preview command. Update maintained examples
and release migration guidance to use `promptkit show prepared`.
### Configuration selection and namespaces
Decision recorded 2026-11-19: fully adopt native configuration and namespace
conventions. Expose the `app` and `promptkit` configuration scopes through
ckconfig. `app` inspects Scriptorium's application settings; `promptkit`
inspects the framework configuration assembled from the selected sources.
Collections do not become separate configuration scopes. Application-only
inspection must not require constructing a PromptKit engine.
`--config` consistently selects Scriptorium's application configuration,
including when inspecting the `promptkit` scope. That configuration selects
the framework sources and collection-discovery file. Adopt the standard
`--overlay` spelling and use consistent source-selection and loading rules
across generation, preview, inspection, requirements, and other applicable
commands. Keep the established ConfigKit collection-import model.
Enable the native prompt, profile, and backend namespace selectors on
applicable commands. They independently scope short caller-supplied resource
IDs; qualified IDs remain exact selections. Namespace selection does not
rewrite stored references or change collection discovery. Keep configuration
scope, resource namespace, and profile selection distinct.
Use native inventory filters, including namespace selection and
`--all-namespaces`, and retain upstream default listing behavior. Support
standard temporary configuration overrides where the upstream loader supports
them. The reviewed PromptKit configuration scope does not support those
overrides; do not add local override semantics to compensate.
Do not add configurable default namespaces in the initial migration. Use
qualified IDs and explicit namespace flags when selecting namespaced resources,
while retaining upstream behavior for unqualified IDs. Configurable defaults
can be considered later if a need arises.
### Native inspection reports and consumer requirements
Decision recorded 2026-11-19: adopt native inspection reports and the native
`promptkit requirements show` interface for Narratio's early dependency
discovery. Its consumer needs and acceptance scenarios are recorded in the
[aligned Narratio proposal](narratio-feature-request.md). This direction is
accepted; Scriptorium integration remains to be implemented.
Consume native report fields without a Scriptorium-specific schema-version
envelope. Use native nonzero outcomes and diagnostics for invocation failures;
JSON report selection does not require JSON errors. Neither a separately
versioned envelope nor programmatic invocation-failure categories blocks this
migration. A future concrete need for either belongs in an upstream discussion.
PromptKit owns requirement classification, discovery completeness, and structured
discovery issues. Completeness is distinct from satisfied bindings or execution
readiness; Narratio owns comparison against its planned inputs. Keep early
discovery separate from concrete request validation. Use current exact resource
identities and native input/variable metadata, without restoring obsolete prompt
versions or inventing input schemas or variable-default semantics.
Standard prompt inspection includes captured messages; prepared preview includes
rendered content. Adopt these native reports without rebuilding Scriptorium's
previous summary projections, and explain the changed presentation in migration
guidance. Requirements discovery retains its distinct upstream content boundary.
### Application commands and standard request flags
Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt
as a required positional operand and no duplicate prompt-selection flag. Keep
`serve` as the application command for the HTTP service. Both are CommandKit
commands owned by Scriptorium, outside the reserved `config` and `promptkit`
families. The CLI migration does not redesign the HTTP API.
Reuse ckprompt's applicable resource, input, and execution flag bindings.
Preserve native parsing, explicit-value presence, repeated mapping semantics,
and PromptKit's interpretation of request values. Keep application-specific
configuration/source selection, `--report`/`--report-format`, server options,
and the whole-operation deadline separate from framework request controls.
Enable upstream convenience aliases consistently on applicable commands,
including `run`. Prefer their shorter spellings in user-facing documentation,
examples, migration guidance, and subprocess integration examples wherever they
are applicable and unambiguous. For example, prefer `--profile`, `--input-file`,
`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream
spellings remain available with identical semantics; the preference does not
remove or rename them.
Aliases retain upstream meanings. In particular, `--input` supplies literal
text; file references use `--input-file`. Migration guidance must explain this
change along with endpoint and timeout naming and repeated mapping values.
Use the canonical spelling where a shorter alias would be ambiguous; do not
assign an upstream alias a different application-specific meaning.
## Upstream baseline
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
ckprompt **v0.10.0**. These are a review baseline, not a final dependency choice
for implementation. The [upstream consumer guide][upstream-guide] describes
their composition and supported extension points.
| Component | Relevant capabilities |
| --- | --- |
| CommandKit | Typed flags and operands with explicit-value presence, generated help and version, shared reporting and outcomes, optional shell completion. |
| ckconfig | Configuration scopes; validation, effective values, sources, explanations, and comparisons; temporary overrides where supported by the loader. |
| ckprompt | Prompt, profile, backend, namespace, and collection inventories; resource inspection; requirements discovery; optional concrete request validation, prepared-request previews, and provider smoke tests. Reusable request flags also serve application-owned commands. |
Scriptorium currently uses PromptKit v0.23.3 and ConfigKit v1.2.1. The reviewed
ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1. Validate the
chosen dependency combination while retaining Scriptorium's adopted PromptKit
fixes; the older declared minimum is not a reason to downgrade.
The [upstream CLI reference][upstream-cli] owns the detailed conventions. The
[current Scriptorium CLI](../cli.md) and
[subprocess contract](../integrations/subprocess.md) describe the starting point,
not requirements to reproduce during migration.
## Details for the feature roadmap
The product and interface direction is settled. The following details need
concrete implementation choices in the roadmap, but do not require another
architectural discussion before drafting it.
### Outcomes and process lifecycle
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
preserving its distinction between a completed content check reporting
`ValidationFailed` and an operational error. Select any necessary domain exit
code without reusing the current validation-failure exit 2, which conflicts with
CommandKit's usage convention. Also specify artifact/report delivery failures
using CommandKit's presentation-failure behavior where applicable. These are
adapter mappings, not a new application validation policy.
Signal cancellation and the whole-operation deadline remain application
responsibilities. Specify their mapping to the CommandKit invocation context
and PromptKit operation timeout, including the application deadline flag and
units, separately from the standard per-attempt timeout flag.
### File delivery
The roadmap and implementation plan specify ordinary report-file handling and
delivery ordering relative to stdout. The caller owns redirected destinations;
Scriptorium does not infer them or check for collisions with the report path.
Partial delivery follows native outcomes and the agreed result-availability
boundary.
### Adoption and verification
Confirm the released dependency combination, complete the application-specific
flag and loader mappings, and sequence replacement and removal of CLI code.
Define appropriate verification for the selected behavior and update canonical
documentation, examples, and release migration guidance as implementation lands.
## Roadmap handoff
The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and
integration details. Keep implementation status there; retain this notepad as
the discussion record.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md

View File

@@ -1,231 +0,0 @@
# ConfigKit Adoption
## Status And Intent
Implemented feature direction, drafted on 2026-09-26 and delivered through the
[implementation plan](implementation.md). This roadmap records the target
behavior and changes from the reviewed baseline; the implementation plan owns
sequencing, concrete interfaces, and verification evidence.
The user is adopting ConfigKit across an application suite to standardize
configuration semantics. Scriptorium will make a clean cutover to ConfigKit's
native conventions, including intentional breaking changes. Preserving the
legacy loader's behavior is not a goal: there will be no parallel legacy loader,
compatibility mode, or recreation of the old merging rules.
Alignment applies to application configuration, not to Promptkit-owned prompt,
profile, or schema definitions. Departures from ConfigKit conventions require an
application-specific reason or a genuine ownership boundary, not backward
compatibility alone. The [architecture policy](../policy/architecture.md) and
[ADR 0004](../adr/0004-definition-boundary.md) remain the scope boundaries.
## Reviewed Baseline (Historical)
Scriptorium consumes Promptkit v0.11.0. Its `internal/config` package uses
yaml.v3 directly and manually applies defaults, file settings, and CLI overrides.
It has a parser-specific integer decoder, ignores empty string overrides, and
treats an empty configuration file as defaults-only input. It has no application
configuration imports, selected overlays, or provenance/inspection interface.
The [configuration reference](../config.md), [CLI reference](../cli.md), and
[source internals](../internal/sources.md) own the current behavior.
The reviewed ConfigKit release is v0.4.0 at commit
`e6ced0d3d1194b58e0b3dc8970089471ba175258`. Adopt that published release as the
initial target, rather than a sibling checkout or unpublished replacement.
Its canonical references are:
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/config.md).
- [Consumer adoption guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/consumers/README.md).
- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/releases/v0.4.0.md).
ConfigKit requires Go 1.25, within Scriptorium's existing toolchain requirement.
It selects `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Removing Scriptorium's direct parser
usage does not remove yaml.v3 from the dependency graph: Promptkit still uses it.
The initial review passed ConfigKit's default test suite and Scriptorium's
configuration and CLI tests; that is baseline evidence, not migration validation.
## Target Ownership And Loading Model
| Owner | Responsibility |
| --- | --- |
| ConfigKit | Application YAML policy, source acquisition, composition, overlays, typed decoding, explicit override application, provenance, and redacted inspection. |
| Scriptorium | Source discovery, application schema and defaults, CLI parsing, recorded application normalization, semantic validation, command prerequisites, and runtime conversion. |
| Promptkit | Framework definition formats, backend semantics, credential lookup, engine defaults, and prompt execution. |
`internal/config` becomes a small application-specific ConfigKit integration,
not a second general-purpose configuration framework. Execution and inspection
share one configuration definition and loading pipeline. Defaults, selected base
and imports, selected overlay, and explicit application CLI overrides participate
in ConfigKit's lifecycle; resolution and validation follow its upstream rules.
Normalization that changes inspected values is recorded through its resolver.
Runtime conversion does not perform a hidden second merge or apply new defaults
after the inspection snapshot has been created.
Scriptorium retains its application field names and domain meanings unless a
specific change below requires otherwise. ConfigKit's public root API replaces
direct YAML decoding and parser-specific hooks. Application defaults remain
Scriptorium-owned; omitted framework settings still delegate to Promptkit.
Backend conversion retains deterministic registration and engine-scoped shared
capacity state. This work does not change the HTTP request contract or move
configuration loading into each HTTP request.
## Native Configuration Semantics
The target accepts ConfigKit's upstream YAML grammar, schema binding, limits,
composition, and value-presence rules without a legacy preprocessing layer.
Migration-visible changes include:
- An existing empty file is invalid; `{}` expresses an empty application mapping.
Defaults-only operation with no discovered file uses `NoSource` instead.
- Explicit empty strings, false values, and zeroes replace defaults. They are
not silently treated as omission. Application validation still decides whether
a resulting value is meaningful for its field or selected command.
- Null follows the application's declared nullable types. It is not a universal
spelling for omission. Scalars and structs do not accept null merely because
the former parser tolerated it.
- Anchors, aliases, merge keys, explicit tags, additional documents, unsupported
scalar spellings, and coercions rejected by ConfigKit are rejected here too.
- ConfigKit's reserved `configkit` key and resource limits apply, including in
dynamic application data. These constraints do not apply to independently
loaded Promptkit definitions or HTTP request bodies.
- Dynamic integers in backend `extra_params` use ConfigKit's `int64`
representation. Runtime mapping preserves their supported value semantics
rather than reserializing through YAML or demanding the old Go scalar type.
Presence remains meaningful at the framework boundary: omitted/null
`transient_retries` delegates to Promptkit, while explicit zero disables retries;
omitted backend queue capacity differs from explicit zero. Application HTTP
size defaults and zero-as-unlimited behavior remain. No new value ranges or
backend restrictions are introduced merely to adopt the library.
## Discovery, Imports, Overlays, And Paths
Source discovery remains Scriptorium-owned. The target retains the documented
explicit `--config` selection and ordered system-location search. An explicitly
empty config path is invalid rather than an implicit request for a default file.
If neither implicit candidate exists, loading uses defaults only; a selected
file that fails loading is not silently replaced with defaults. No implicit
working-directory configuration search, environment overlay, or directory scan
is added.
Application configuration supports ConfigKit's explicit path and glob imports.
Imports compose disjoint definitions; repeated non-mapping definitions are
conflicts, not last-writer-wins overrides. There is no implicit `conf.d` scan.
An optional `--config-overlay` selects ConfigKit's one named overlay using its
standard `overlays/<name>.yml` location, naming rules, and merge behavior. No
overlay is selected by default. Selecting an active overlay without a base
source follows ConfigKit's rejection of overlays with `NoSource`; Scriptorium
does not invent a root. Application overlays do not replace `--profile`,
`profile_dir`, or Promptkit's execution-profile selection.
Use the selected file's canonical directory as ConfigKit's default import and
overlay root. This root governs configuration source traversal only. Values of
`prompt_dir`, `profile_dir`, `schema_dir`, and `server.artifact_root` retain
working-directory-relative interpretation; absolute values remain absolute.
This is an explicit application path policy, not an upstream requirement or a
legacy parsing mode. ConfigKit's consumer examples demonstrate alternatives but
do not mandate source-file-relative application paths. This adoption does not
extend import containment to application data or alter HTTP artifact containment.
## CLI Overrides And Configuration Inspection
Only flags explicitly supplied by the user become ConfigKit application
override records. Parser defaults do not overwrite file or overlay settings.
Explicit empty values are not dropped. The existing invocation-specific prompt,
profile, input, model, timeout, output, and reporting options remain invocation
state rather than new application configuration fields. In particular, the
run/render retry flag remains a request override; it does not mutate the engine's
application retry setting or backend state.
Expose application configuration validation, effective redacted YAML, source
provenance, and explanation of an individual configuration path. These are
included features, not merely library capabilities available for future work.
They use ConfigKit diagnostics and inspection records from the shared loading
pipeline, including defaults, imports, overlays, explicit CLI values, and
recorded normalization. No separate inspection-only interpretation is maintained.
Configuration inspection does not execute prompts, make provider calls, or
resolve API-key values. Application validation is not a promise that every
Promptkit backend or definition is valid or that a provider is reachable.
Command-specific execution prerequisites remain with the relevant command;
inspection can explain an incomplete application configuration without requiring
an executable prompt selection. The interface is a CLI configuration command
family, not a second CLI framework or an HTTP configuration endpoint; the
implementation plan specifies its concrete commands and mappings.
Safe diagnostics must not restore raw parser errors or configuration values
that ConfigKit deliberately suppresses. Effective output and explanation use
the upstream redacted renderers; they are inspection output, not guaranteed
reloadable configuration. Under the maintainer's selected policy, backend
`extra_params` are visible in effective output and explanation, including
historical values. There is no blanket container masking, sensitive-key heuristic,
or new selective-redaction configuration surface.
## Credential Boundary And Deferred Features
Existing `api_key_env` values remain environment-name strings passed to Promptkit.
They do not become ConfigKit `Secret` fields. ConfigKit eagerly resolves effective
typed references and requires nonempty values; that would change Promptkit's
optional/required and selected-credential behavior. This departure from the
secret-reference feature is an ownership decision, not compatibility plumbing.
Raw API-key fields remain unsupported under the existing architecture policy.
API-key values are the only secrets requiring ConfigKit redaction in this
adoption. The application configuration holds environment-variable names, not
those values, so inspection neither resolves nor contains the actual keys.
Reference names remain visible. Do not tag `api_key_env` as secret merely to
hide its name, add an eager key lookup, or mask unrelated application settings.
The existing raw-key prohibition and Promptkit boundary provide the protection
without introducing a redundant credential-bearing configuration field.
Secrets-directory bootstrap and application schema versioning are deferred until
there is a concrete application need. Their availability in ConfigKit does not
make them mandatory. Hot reload, runtime resource replacement, remote imports,
automatic migrations, and general environment-variable overlays are outside
this adoption. These are scope limits for this feature, not new permanent
prohibitions on future explicitly requested work.
## Required Changes And Completion Criteria
- Replace manual decoding/default/override machinery with the shared ConfigKit
integration and retain only application-specific discovery, rules, and mapping.
- Support imports and selected overlays across commands that load application
configuration, and deliver the configuration inspection capabilities above.
- Update application configuration types, presence handling, CLI explicit-set
mapping, and diagnostics to match the selected native semantics.
- Update maintained examples and canonical configuration, CLI, operations,
architecture, and internal documentation when behavior lands. Upstream generic
contracts remain linked rather than copied into a competing specification.
- Add proportionate integration coverage for the cutover: defaults-only input,
explicit values and nulls, imports/conflicts, overlays, CLI precedence,
inspection agreement and API-key non-disclosure, visible dynamic backend
parameters, unchanged credential ownership, and representative
execution/server startup.
ConfigKit owns exhaustive parser and composition tests; Scriptorium tests its
adoption and application boundaries.
- Pin the published dependency and maintain ConfigKit and YAML attribution under
the [OSS policy](../policy/oss.md), using imported-commit source/notice links
and applicable standard and companion license texts.
- Document migration in a release appropriate for the intentional breaking
configuration changes under the [release policy](../policy/release.md).
Release selection and publication remain separate preparation work; this
roadmap adds no release gate, network probe, or new distribution format.
Completion means one ConfigKit-native application configuration path serves
execution and inspection, the selected user-facing features work, and migrated
examples and regression coverage demonstrate the documented semantics. It does
not require adopting every ConfigKit feature or changing Promptkit definitions.
## Resolved Inspection Policy
On 2026-09-26 the maintainer selected no redaction for `extra_params` and limited
the relevant secret to the API key. Inspection therefore preserves parameter
values and environment-reference names, while actual API-key values remain
outside the application configuration pipeline. Visibility is intentional;
this is not a promise to detect secrets placed inside arbitrary parameter values.
The delivered `config show` and `config explain` commands use ConfigKit's
inspection writers without secret tags or a second redaction path. Both
effective and historical parameter values remain visible; `api_key_env` names
remain visible while Promptkit alone resolves selected credential values.

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,166 @@
# Prompt input requirements for Narratio
Status: accepted direction, pending implementation through the CommandKit
migration. This proposal records Narratio's consumer needs and their mapping
to the native interface; it does not describe shipped Scriptorium behavior.
The [CommandKit notepad](commandkit-notepad.md) records the migration decisions.
## Consumer need
Narratio produces transcripts, extraction outputs, and generated artifacts in
a staged pipeline. It binds named inputs to a Scriptorium prompt when generating
each analysis artifact. A Narratio source ID and a prompt input name are separate
identities: for example, the source
`narratio.transcript.final_trimmed_markdown` might be supplied under the prompt
input name `transcript`.
Narratio needs to discover expected input names before running expensive
upstream stages and before the eventual input files exist. It can then show
operators how prompt inputs map to pipeline products and identify missing
bindings without reading prompt definitions or reproducing PromptKit's analysis.
## Selected native operation
Expose `scriptorium promptkit requirements show PROMPT_ID` through ckprompt.
Subprocess consumers select JSON with the standard `--format json` flag.
Default and explicit text output use the native YAML presentation.
The [upstream CLI contract][requirements-cli] owns syntax and report details.
Use the same application configuration and framework source selection as
execution, including `--config`, `--overlay`, and applicable application
selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
prompt/profile namespace flags supply the relevant discovery context.
Preserve upstream selection semantics, including the prompt's default profile
when an explicit profile is omitted. Qualified IDs identify installed resources;
there is no separate prompt-version selector or reported prompt-version field.
The selected profile establishes identity, not execution readiness. Selecting
another profile does not itself change the prompt's discovered requirements.
Scriptorium's loading and request mapping must preserve the same effective
selection and applicable caller context across discovery and execution.
Discovery requires no input bindings or output-artifact path. PromptKit performs
no artifact loading, schema loading, credential resolution, message rendering,
capacity reservation, or model call for this operation. Reading configuration
and prompt resources needed to build the captured engine is expected. The
[PromptKit discovery contract][requirements-api] owns the analysis and its
limits.
## Native response and consumer interpretation
Consume the native JSON report directly, without a Scriptorium-specific wrapper
or schema-version field. Successful report delivery writes one JSON document to
stdout, with diagnostics on stderr under CommandKit's standard reporting rules.
Consumers requesting a report should not enable quiet mode.
| Field | Consumer meaning |
| --- | --- |
| `prompt_id`, `profile_id` | Exact selected resource identities. |
| `inputs` | Declared and recognizable template-referenced inputs, including exact `name`, requirement `kind`, `declared`, `content_type`, `description`, and `explanation`. |
| `variables` | Recognizable caller-variable keys with `name`, requirement `kind`, `supplied`, and `explanation`. |
| `complete` | Whether the supported dependency analysis is complete for the supplied context. |
| `issues` | Structured discovery limitations with a `code`, associated input or variable names where known, and a human-readable description. |
PromptKit sorts input and variable entries by exact name, and deduplicates and
orders issues by their code and associated names. Preserve empty inventories
and false values. Input metadata distinguishes absent/null values from an
explicitly empty string. Explanations and issue descriptions are for display;
Narratio must use structured fields rather than parse their prose.
The native input metadata includes content type and description. Current
PromptKit inputs have no per-input schema declaration to project. Do not infer
constraints from names or treat the output-validation schema as an input schema.
Variable `supplied` records exact-key presence, including an explicitly empty
value; this interface does not introduce a separate variable-default system.
Requirements reports exclude artifact payloads, prompt contents, and unrelated
supplied variable values. A supplied value used to resolve an input identifier
can appear as that identifier. Keep this native behavior without adding a custom
projection of the report.
The upstream report contract and adopted dependency versions govern the shape.
Migration documentation must identify relevant consumer changes; this proposal
adds no independent response-versioning mechanism or stronger compatibility
guarantee.
## Conditional and incomplete discovery
PromptKit classifies dependencies as required, optional, or conditional using
the supplied context and its supported template analysis. Recognizable references
only on known skipped paths can be optional. Explicit required declarations
still apply. Unavailable input contents, unresolved variable values or dynamic
names, and unsupported dependency-relevant constructs can leave discovery
incomplete. Valid templates are not rejected merely because the analysis cannot
fully resolve them.
Narratio must inspect both the requirements and discovery completeness:
- `complete: true` establishes discovery coverage, not satisfied bindings,
valid future input bytes, or execution readiness. Required inputs or missing
required variables may still be present.
- `complete: false` preserves useful findings and structured issues. An empty
partial inventory does not prove that no inputs are needed.
- A partial report can return status zero. An issue is not itself an invocation
failure. Narratio owns its policy for proceeding with incomplete dependency
information.
Once input artifacts exist, native `promptkit requirements validate` can check
a concrete request through preparation. It is a separate operation and must not
replace early discovery. Neither operation guarantees later generation success.
Changes to configuration or resources between invocations can change findings.
## Failures
Use CommandKit's native nonzero outcomes and diagnostic messages for selection,
configuration, operational, and report-delivery failures. JSON report selection
does not turn diagnostic messages into a categorized JSON error response.
Narratio can attach the diagnostic to its own artifact or pipeline context;
it must not depend on parsing the message to recover a stable error category.
Structured discovery issue codes belong to successful inspection reports and
are distinct from invocation failures. Follow PromptKit's distinction between
partial discovery and failures that return no inspection. Absence of a future
input artifact is not a discovery failure because discovery does not load it.
The accepted consumer requirement is a nonzero return code plus failure
information. If programmatic failure categories or separate schema versioning
become necessary, discuss them upstream rather than introducing local wrappers.
Neither is a prerequisite for this migration.
## Consumer acceptance scenarios
1. A prompt requires `transcript`, but Narratio binds only `session_transcript`.
The native inventory identifies the exact required name before either file
exists, allowing Narratio to identify the missing binding.
2. A template references an undeclared input. Recognizable references appear in
the inventory with `declared: false`; unsupported dependency analysis is
explicitly incomplete rather than silently claiming full coverage.
3. An optional glossary is reported with its native classification, allowing
Narratio to distinguish it from a required binding.
4. Variables resolve a supported conditional dependency. Unknown conditions
retain conditional findings or discovery issues according to PromptKit.
5. Selecting another qualified prompt or profile reports the corresponding
identities. Prompt selection changes the analyzed definition; profile
selection alone does not change its requirements.
6. Discovery works with no generated input files, model access, or generation
credentials when the selected configuration and resources are readable and
valid for discovery.
7. An unknown prompt or invalid profile selection returns nonzero with native
diagnostics suitable for Narratio to associate with the affected artifact.
8. Narratio treats a complete report with missing required bindings differently
from a complete, satisfied dependency check, and handles partial reports
without assuming that status zero establishes completeness.
9. Scriptorium's adapter uses consistent configuration, namespaces, and applicable
request context across discovery, validation, preview, and execution.
## Scope boundary
Narratio owns its source catalog, stage ordering, source-to-input bindings,
artifact dependency graph, and session availability checks. Scriptorium exposes
PromptKit's native requirements through CommandKit. Narratio source IDs and
pipeline concepts do not become part of that interface. A graph renderer, HTTP
endpoint, batch operation, and changes to generation behavior are outside this
request.
[requirements-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md#promptkit-requirements
[requirements-api]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/requirements.go

View File

@@ -1,63 +1,223 @@
# OSS Policy Adoption # Standard Repository Policy Alignment
## Status ## Status And Intent
Completed on 2026-09-26. The upstream template work proposed here is now Agreed and delivered on 2026-09-28. This roadmap replaces the
available and adopted locally. This document records the adoption; the earlier licensing-only proposal with alignment of the complete applicable
[OSS policy](../policy/oss.md) is the canonical owner of the ongoing rules. policy set and its supporting documentation. It defines the targeted end state
and required changes. Its completed implementation plan is preserved in Git at
`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`.
The adopted baseline is the standard policy repository at commit The next release summary should mention the policy and licensing alignment,
`eea8bcd21a964b395e31971077d7fddb445f2c28`: the already-selected GPL-3.0-or-later application grant, and the separate
CC-BY-SA-4.0 treatment of adapted policy material. Version selection and
publication remain release preparation, not part of this delivery.
- OSS policy base version 1.1; The goal is identical policy language across adopting projects except where a
- documentation policy base version 1.4; and substantive, locally significant requirement or decision warrants customization.
- release policy base version 1.2. Adopt upstream wording verbatim for non-substantive differences. Existing local
phrasing is not, by itself, a reason to retain a variation.
Each affected policy records its base version and local update date. Template ## Review Revision And Current Baseline
adoption instructions were removed. Unchanged agent, architecture, and testing
policies retain their existing versions.
## Adoption Outcome The fixed upstream review revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Use the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
for this adoption. The review compared current local documents directly with
that revision; reconstruction or assessment of historical adoption baselines
is not required.
- [Documentation ownership](../policy/documentation.md) distinguishes the The reviewed Scriptorium revision is
project license, component entries, standard texts, and OSS policy. `d6aecf5c50269b7d130dbf19f416a67454cd9778`. It has six adopted policies,
- The [contributor guide](../development.md) routes dependency, copied-asset, without per-document Upstream Source metadata, and no `docs/policy/meta.md`.
attribution, and release-document work to the OSS policy. The policy targets below supersede the earlier roadmap's narrower version
- [Component entries](../oss/attribution.md) cover the six selected direct and targets.
transitive Go modules. Source and project-specific notice links identify the
imported commits. LGPL entries link directly to both LGPL v3 and GPL v3.
- Project-specific notices are linked upstream under the adopted house
interpretation. YAML's former local LICENSE and NOTICE copies were removed;
their history remains in Git. Missing upstream copyright statements are
identified in the affected entries rather than fabricated.
- The five applicable standard texts in `docs/oss/licenses/` match the upstream
reference collection byte-for-byte: GPL v3, LGPL v3, Apache 2.0, BSD 3-Clause,
and MIT. The reference collection documents their publisher/SPDX provenance.
Adoption removed a stray LGPL prefix, restored the complete Apache text,
separated the standard BSD text from the Go-specific notice, and added MIT.
- The [README](../../README.md) ends with friendly project-license and
attribution links. The [release policy](../policy/release.md) delegates footer
conventions to the OSS policy; the [release procedure](../release.md) retains
Scriptorium's immutable-tag URLs and existing hosted-body reuse.
## Preserved Scope | Policy and proposed Upstream Source | Current base | Target base | Target treatment |
| --- | --- | --- | --- |
| [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md) | 1.1 | 1.3 | Adopt shared rules verbatim, including commit discipline. |
| [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) | 1.1 | 1.3 | Adopt common principles and customize for Scriptorium's established boundaries. |
| [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) | 1.4 | 1.11 | Adopt shared language and tailor the canonical topic map. |
| [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md) | 1.1 | 1.3 | Adopt shared guidance with focused local test ownership. |
| [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) | 1.2 | 1.4 | Adopt common rules and retain justified release choices. |
| [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) | 1.1 | 1.8 | Adopt licensing, attribution, and reference-example conventions. |
| [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md) | Not adopted | 1.0 | Add provenance, local authority, and upstream discovery. |
This adoption changes documentation and attribution, not Scriptorium's license, Every existing policy needs language and provenance updates. No adopted policy
dependencies, application architecture, or release machinery. Published notes, is entirely update-free, but established application decisions, dependency
tags, and assets remain unchanged. Existing source-release completion and licenses, and release mechanics need no substantive change.
asynchronous binary-delivery behavior remain intact.
There is no new publication-time network check, approval gate, scanner, source Current supporting-document gaps include the README's obsolete BSD project
bundle, downloadable license asset, or modified-dependency rebuild exercise. license statement, the release procedure's two-link footer, an attribution
Concrete exceptions continue to receive the treatment specified by the adopted document that does not follow the new exact House Format, and orientation
OSS policy; the house format is not a universal legal-sufficiency guarantee. guidance that requires architecture reading even for unrelated work.
The architecture policy's command inventory also omits the implemented
`config` command family.
## Validation ## Target Policy Language And Local Customizations
The standard texts were compared against the upstream reference collection. Remove every `Base Policy Template` section and its adoption instructions.
The BSD reference intentionally retains its publisher's trailing space in the Replace instructional application-specific placeholders with actual decisions;
copyright placeholder; it is not reformatted to satisfy a whitespace check. do not leave template examples describing nonexistent components.
Dependency commit references were resolved from Go module origin metadata or
the selected upstream tag, and affected local links and upstream attribution Use upstream common language verbatim. Keep necessary local requirements
destinations were checked. No runtime code, commands, or executable examples clearly identifiable rather than paraphrasing entire shared sections.
changed. The following customizations are justified:
- **Architecture:** preserve PromptKit and ConfigKit ownership, full support
for valid PromptKit definitions, public dependency boundaries, HTTP artifact
containment, and simple predefined-prompt execution. Preserve caller-visible
request independence alongside shared engine and backend capacity state.
These are deliberate product and safety decisions, not generic template
choices. Adopt upstream architectural principles proportionately; they do
not require a wrapper or interface for every library. Correct the command
inventory and keep concrete package mechanics in internal documentation.
- **Documentation ownership:** tailor the topic map to the executable CLI and
HTTP application. Scriptorium does not offer a reusable public Go API;
consumer guidance covers executable use and migration to PromptKit.
PromptKit remains the owner of framework formats. Use upstream wording for
generic ownership, example, and ADR guidance instead of retaining redundant
local paraphrases. Preserve accepted ADR decisions and their history.
- **Testing:** retain a short project-specific ownership section distinguishing
Scriptorium's integration and adapter tests from upstream framework/parser
tests. This prevents duplication of PromptKit and ConfigKit test matrices.
HTTP containment and shared-capacity behavior justify focused adapter
coverage. Upstream observations about domain coverage are not quotas or a
hierarchy that displaces risk-based testing.
- **Release:** preserve branch-before-tag publication, annotated tags,
Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery.
Retain race testing because the server shares concurrent engine state and
source guards because local replacements, workspaces, or vendoring can hide
unpublished dependency substitutions. Keep gate rationale in policy and
concrete commands, targets, and publication choices in the release procedure.
Upstream's optional atomic-push approach does not require a new feature.
- **OSS:** use Scriptorium's actual GPL-3.0-or-later grant in the project
example. Preserve dependency grants and the settled House Format
interpretation for upstream notice links. The code grant does not extend
to separately licensed copied policy material.
No agent-policy exception is needed: upstream already preserves the local
commit authorization and safety boundaries. Stylistic preferences, alternate
wording, and generic elaboration do not justify additional exceptions.
## Provenance And Public Discovery
When adoption lands, each of the seven policies records its target
`Base Policy Version`, actual local adoption date in `Last Updated`, and
`Upstream Source` pointing to the exact corresponding file linked in the
table above. Do not substitute a repository homepage, moving branch, another
policy's URL, or a historical source revision for that per-document link.
Retain accurate provenance in later local edits.
The new local `docs/policy/meta.md` follows upstream language after removing
its template section. It establishes that adopted local policies govern the
repository and that upstream changes require deliberate adoption. Its public
discovery links remain current:
- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
Adopted-source and example links remain commit-pinned. Preserve the valid
commit-pinned example links supplied in the selected OSS policy; their asset
revision need not be rewritten merely to match the policy review revision.
Public discovery and attribution in this agreed adoption supersede the earlier
instruction not to reference the policy repository.
## Orientation And Selective Reading
Adapt [the upstream agent orientation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/agents/AGENTS.md)
into [root AGENTS.md](../../AGENTS.md), preserving applicable existing
code-discovery instructions. It points to the local contributor guide and
requires the agent policy before recommendations, planning, or implementation;
it does not require reading the entire suite by default.
The [contributor guide](../development.md) gains the upstream Policy Reading
Guide table and associated selection rules, including the new meta policy.
Retain Scriptorium's task-specific contract guide alongside it. Architecture
reading becomes task-triggered rather than unconditional. Relevant policies
are read before governed decisions, multiple policies may apply, material
already available in context may be reused, and expanded scope triggers
expanded reading. Policy-reading triggers live here, not in the documentation
topic map.
## Licensing And Attribution
Follow the [canonical copied-policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md).
Insert it directly beneath the prescribed attribution title and replace all
three placeholder URLs with the full review commit. Identify the actual
copied/adapted scope, including agent-orientation material and copied reading
guidance where used, rather than describing only policy files if additional
material is incorporated. Preserve creator, copyright, license, disclaimer,
and modification information through the supplied notices and links.
Required supporting changes:
- Add the complete, unmodified `docs/oss/licenses/CC-BY-SA-4.0.txt` from the
selected revision.
- Extend [COPYRIGHT](../../COPYRIGHT) to identify the adapted policy material
as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve
Scriptorium's GPL-3.0-or-later code grant and existing [LICENSE](../../LICENSE).
Unrelated application documentation is not automatically relicensed.
- Reformat [attribution](../oss/attribution.md) to the v1.8 House Format:
`# Open Source Attribution Notices`, followed directly by component entries;
factual optional identification; supplied copyrights; SPDX expressions;
license/notice links with actual filename labels and terminal periods;
and `[Source](COMMIT_URL).`.
- Remove its introductory policy prose, missing-copyright filler, and
agent-authored license-scope explanations. Omit an unavailable copyright
field instead of explaining that none was invented. Preserve actual
required upstream notices, applicable license expressions, and imported
dependency revisions.
- Correct [README](../../README.md) to link its GPL v3 or later statement to
`COPYRIGHT`, followed by the attribution link.
- Update [the release procedure](../release.md) to use the prospective
`COPYRIGHT | LICENSE | ATTRIBUTION` footer, with absolute immutable-release
URLs for all three destinations. The existing hosted workflow continues
copying the checked-in release note unchanged.
The documented CC-BY-SA arrangement is agreed for this adoption. Original
licensing-example formatting has upstream's CC0 permission; using it alone
does not require a separate attribution entry. Reproduced license texts and
third-party notices retain their own terms.
## Local Materials And Upstream References
Keep applicable adopted policies, Scriptorium's adapted root orientation and
developer guide, actual project notices, attribution entries, and required
license texts locally.
Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and
example collection upstream. Link to them as appropriate rather than copying
them into a parallel local handbook. The upstream `agents/AGENTS.md` is the
downstream orientation template, distinct from upstream's own root AGENTS.md.
Copy only needed standard license texts, not the entire reference collection.
## Scope And Completion Criteria
This work updates policy and supporting documentation. It does not change
application code, dependency versions or grants, release scripts, publication
mechanics, or accepted ADR decisions. No new scanner, recurring synchronization
check, license approval, publication-time network probe, or release gate is
introduced. Published releases, tags, notes, and assets remain unchanged.
Completion means:
- All seven policy files use the selected versions, accurate source links,
adoption dates, and upstream common wording, with template-only content
removed and local variations limited to the justified decisions above.
- Orientation and selective reading agree, and local links resolve without
depending on a sibling checkout.
- Policy attribution and document-license scope match the material actually
incorporated; required standard texts are complete and unmodified.
- README, attribution, release navigation, and still-operative roadmap
handoffs agree with the new conventions. Historical implementation evidence
remains available through the Git references in the implementation plan,
without making old footer directions current policy. The earlier
author-selected license change remains in the next release's preparation
context; publication remains separate work.
- Review checks the resulting rules, source/example URLs, notice facts, local
links, license-text fidelity, and final diff. Runtime tests are unnecessary
for documentation-only changes. A Git adoption record is sufficient; no
additional provenance database or recurring audit is required.
There are no unresolved policy choices for this scope.

View File

@@ -3,8 +3,9 @@
## Status ## Status
Complete. This document records the delivered feature scope and targeted end Complete. This document records the delivered feature scope and targeted end
state. The completed delivery plan is maintained in state. The completed delivery plan is preserved at
[implementation.md](implementation.md); current behavior remains defined by `git show e4405966c87c8a7843b340146e90cc1e515bef42:docs/roadmap/implementation.md`;
current behavior remains defined by
the canonical application contracts linked below. the canonical application contracts linked below.
The durable product and integration boundary for this work is established by The durable product and integration boundary for this work is established by

374
docs/roadmap/promptkit.md Normal file
View File

@@ -0,0 +1,374 @@
# PromptKit v0.12.0 Adoption
## Status And Intent
Drafted on 2026-10-03; source-selection and framework-inspection decisions
confirmed by the maintainer on 2026-10-04. The PromptKit v0.12.0 adoption has
been implemented and delivered after the complete audit passed on 2026-10-04.
This document remains target and decision context, not an implementation-stage
log. Release preparation remains separate; no release version has been
selected or published. No significant decisions remain open within this scope.
Adopt PromptKit's ConfigKit-native configuration boundary while preserving
Scriptorium's simple, request-independent execution model. As established in
[ADR 0004](../adr/0004-definition-boundary.md), valid prompt and profile
definitions for the selected PromptKit version should work without a narrower
Scriptorium field-level format. Library-only APIs are considered separately;
this upgrade does not turn Scriptorium into a workflow application.
The maintainer selected a native source cutover and full framework configuration
inspection. The latter uses upstream's native redaction in this new interface
only. These are deliberate product choices, not requirements inferred merely
from new library APIs.
## Reviewed Baseline And Upstream Target
The reviewed Scriptorium source is commit
`bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0.
The completed ConfigKit adoption selects ConfigKit
v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2`
catalog modules at v2.20260926.0.
Application configuration already uses one ConfigKit loading, inheritance,
resolution, validation, and inspection pipeline. Framework construction still
passes `prompt_dir` and `profile_dir` into the removed PromptKit directory
fields and registers application `backends` with `WithBackend`. Profile
inspection substitutes an empty prompt filesystem to avoid loading prompts.
Maintained prompt/profile files and inline test fixtures use the old embedded
`id`, `version`, and `base_profile` syntax.
The target is the published PromptKit v0.12.0 release at full commit
`4b8169da286917fde7875425bb32b799b12c6af3`. The published tag and downloaded
module identify that same revision. Canonical references are:
- [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/releases/v0.12.0.md).
- [Framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md).
- [Consumer and migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md).
- [Configuration ownership decision](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/adr/0001-configuration-boundary.md).
PromptKit now also selects ConfigKit v0.5.0, so no further ConfigKit upgrade is
needed. Go 1.25.5 remains sufficient. Its catalog selections are:
| Module | Version | Full source commit |
| --- | --- | --- |
| `promptkit-backend-openrouter/v3` | `v3.20260930.0` | `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` |
| `promptkit-backend-rakestrawhome/v3` | `v3.20260930.0` | `993443d88c451901f4c917fa00c204fd3b54d28d` |
This review examined upstream contracts and the affected Scriptorium adapters,
configuration, presentation, examples, and tests. It did not establish that the
unmodified application builds against the new, incompatible construction API.
## Targeted End State
### Framework Ownership And Source Assembly
Scriptorium constructs engines through PromptKit's public root package and
`Config.Sources`. ConfigKit owns source composition, overlays, inheritance,
presence, null values, and resource origins. PromptKit owns final definition
validation, catalog contributions, backend completion, content capture,
preparation, execution, and capacity coordination.
An operator-selected source may contain any combination of keyed `backends`,
`profiles`, and versioned `prompts`. Do not partition or filter documents by
directory name, filename, or a Scriptorium copy of the framework schema.
Do not independently preflight domain fields in lower-priority definitions
that the final effective configuration replaces. Syntax and composition
failures remain upstream loading failures.
The selected application interface is an ordered `promptkit_sources` sequence.
Each entry selects either a `file` or a `directory` and contributes one caller
underlay, from lowest to highest priority. A directory uses
`promptkit.DirectoryInputs` and strictly composes its recursively discovered
YAML files. A file uses `configkit.File`
with declared imports enabled, so an entry document can compose fragments.
All caller groups follow PromptKit's maintained catalogs and owned defaults.
No separately exposed `Sources.Main` setting is needed for this interface.
For example, the target application shape is:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./deployment/promptkit.yml
schema_dir: ./examples/schemas
```
Directories retain the helper's default of disabled imports. Enabling imports
while also recursively discovering their YAML targets would include those
files twice in the same group, which ConfigKit rejects. Use a selected entry
file with imports for that layout; do not silently deduplicate, skip files, or
convert composition conflicts into precedence.
Under this decision, `prompt_dir`, `profile_dir`, application `backends`,
and their directory flags are replaced, not retained as a second configuration
model. Framework backend definitions live with the framework sources rather
than passing through Scriptorium's scalar backend schema. A repeatable
`--promptkit-source PATH` selects a replacement ordered source list for
engine-using commands; each path selects a regular file or directory using the
same rules. Only an explicitly supplied flag overrides the configured list.
Application source discovery, its imports and selected overlay, explicit CLI
override handling, and working-directory-relative application paths remain
unchanged. `--config-overlay` still selects an application overlay; it does not
implicitly select a PromptKit layer or profile. Framework priority is explicit
in the source list, with import/resource containment supplied by upstream for
each selected root. This is not a new global filesystem sandbox.
### Complete Definition Support
The target accepts the keyed v0.12.0 formats without compatibility rewriting:
profile and backend IDs are mapping keys, prompt IDs contain keyed string
versions, and `extends` replaces `base_profile`. Literal IDs and references
retain their exact spelling, including punctuation and meaningful whitespace;
filenames do not establish identities.
All supported prompt/profile fields continue to reach PromptKit, including
inputs, message roles and cache metadata, inline and file content, session
templates, output validation and repair, backend/endpoint selection,
credentials by environment name, generation controls, and provider parameters.
The upstream format reference, not this list, owns the complete contract.
Presence must survive the boundary: omission, explicit zero/false/blank, and
null are not interchangeable. Inheritance and layers recursively combine maps;
an empty map does not clear inherited entries. Backend defaults apply after
effective profile inheritance. Changing a model or backend no longer drops
unrelated explicitly inherited settings. Profile null suppression and explicit
zero controls must affect outbound requests as specified upstream.
Partial profiles remain valid when request overrides can complete them.
Scriptorium must not introduce a mandatory model, credential, default profile,
or directory prerequisite that prevents such a request. With the selected
source interface, engine construction may have no prompt collection; missing
request selections fail through PromptKit's ordinary public errors rather than
a required `prompt_dir` check. Source selection does not imply provider access
or credential availability.
### Captured Definitions And Runtime Lifecycle
Engine construction validates every final effective definition, including
unused entries, and captures message-file content and static template syntax.
Invalid unused definitions or unreadable message resources may therefore fail
startup or inspection before a request selects them. An overwritten domain
value is not independently rejected merely because it appears in history.
ConfigKit's structural directives now also apply to framework input mappings,
including dynamic provider maps. Document the reserved `extends` key and the
difference from literal runtime provider parameters; do not invent a quoting
escape or a second inheritance resolver.
Content files use their effective field's source context, including imported
and inherited content. Retain those contexts by passing actual upstream
inputs; do not flatten files into synthetic mappings that lose origins.
Application paths remain working-directory-relative, whereas framework message
resources follow PromptKit's source-relative contract. Schema and request
artifact reads remain preparation-time resources; credentials and provider
operations retain their documented runtime boundaries.
A server retains one constructed engine across its requests, with shared
backend capacity and queue accounting. Definition/message edits require a new
engine; for this scope, restarting the server is the supported way to obtain
one. CLI invocations naturally construct fresh engines. No file watcher,
reload endpoint, per-request server reconstruction, or durable state is added.
This is not a transactional snapshot of all external files or credentials.
### Definition And Application Inspection
`inspect prompt` and `inspect profile` use the same selected configuration
snapshot as execution. Remove the empty-prompt-filesystem substitution.
Profile inspection still does not need request inputs, schema reads, model
calls, or credential values, but constructing its engine now validates and
captures all selected definitions, including prompts. A partial target may be
inspected without imposing preparation's completeness requirements.
`config validate`, `show`, `sources`, and `explain` remain application
configuration operations without constructing an engine. Under the selected
source cutover, they show source selections rather than the contents of
PromptKit's separately loaded definitions. They are not framework validation.
The separate framework inspection family below supplies framework validation
and captured provenance.
### Captured Framework Configuration Inspection
Add the CLI command family `inspect configuration` with `validate`, `show`,
`sources`, and `explain` operations. It uses the same application settings,
source selections, and engine construction as other engine-using commands,
without requiring a prompt/profile selection or request inputs. Each invocation
constructs one engine; reporting uses that engine's captured public view rather
than loading definitions again.
- `validate` succeeds when the engine constructs successfully and produces no
success report. It validates final definitions and captures message resources,
not provider access, credential availability, or request-specific preparation.
- `show` writes the captured effective YAML through
`ConfigurationInspection.WriteEffective`.
- `sources` presents structured JSON source records from
`ConfigurationInspection.Sources`, including the source kinds, layers, and
underlay positions needed to distinguish maintained and operator inputs.
- `explain --path JSON_POINTER` uses the native explanation view and writer
for effective values and history. Root and literal mapping-key paths follow
the same JSON Pointer conventions as application `config explain`; IDs with
slashes or punctuation must not become dotted-path lookups.
Use PromptKit's public `InspectConfiguration` and its native writers and
records. Surface applicable load diagnostics safely on stderr; successful
reports go to stdout. Inspection does not resolve credential values, contact
a provider, or watch/reopen sources after construction. Captured effective
configuration is distinct from backend-completed `inspect profile` output and
request-specific prepared output; none substitutes for the others.
The maintainer explicitly accepts upstream's credential-shaped provider-key
redaction for this new family, including effective and historical values.
Fields such as `token` and `password` can therefore be redacted here while
remaining visible in existing profile/prepared views. This is not blanket
redaction of `extra_params`, a change to parameters sent to providers, or a
change to existing inspection interfaces. Environment-reference names and
ordinary unclassified content can remain visible. Reports may contain prompt
text, provider data, paths, and identifiers; native redaction is not a promise
that the output is safe to disclose.
### Requests, Presentation, And Disclosure
Keep CLI/HTTP request independence, presence-aware execution overrides,
generation/whole-run timeout separation, transient retries, execution reports,
artifact policy, and public error mapping. Preserve existing serialized results
unless an upstream change actually requires an application contract change.
Prepared/profile numeric values alone are not proof that a zero control was
sent; verify upstream presence through generation or recorded outbound requests.
The dependency change alone does not require a new presence DTO. Continue
mapping errors by public identity rather than message text.
Environment-variable names remain visible; resolved API keys are never
printed or serialized. Ordinary `extra_params` retain their selected visibility
where those values are presented. Moving definitions out of application
settings changes what `config` can inspect, not their sensitivity classification.
Do not silently adopt broader redaction rules for existing profile/prepared
inspection.
## Work Needed From The Baseline
- **Dependencies and attribution:** select released PromptKit v0.12.0, tidy the
module graph, and use its selected `/v3` catalogs without direct application
imports. Remove obsolete `/v2` modules and `gopkg.in/yaml.v3` if no remaining
imports require them. Update PromptKit/catalog component entries and exact
source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md`. The reviewed
grants remain LGPL-3.0-or-later for PromptKit and MIT for the catalogs; reuse
the applicable local license texts. Preserve unrelated attribution entries
and historical release documents.
- **Application settings and CLI:** implement the selected source interface
through `internal/config` and shared CLI override mapping. Retire the backend
document/runtime conversion and old directory fields, add ordered source
selection, and update command help and prerequisites. Application validation
checks its schema and selector shape;
framework acquisition and domain validation belong to engine construction.
- **Shared engine wiring:** replace removed fields/options with upstream
inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime
collaborator injection, and use the same construction path for execution,
rendering, definition inspection, and serving. Preserve identifiable
PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete
prompt-filesystem inspection scaffolding.
- **Captured framework inspection:** add the `inspect configuration` family
with `validate`, `show`, `sources`, and `explain` using the shared engine path
and its public captured inspection view. Reuse native YAML/explanation writers,
preserve useful source-layer information in JSON presentation, and keep application
`config` independent of framework loading. Apply the approved native
redaction exception only to this new family.
- **Definitions and fixtures:** migrate every maintained prompt/profile file
under `examples/` and `testdata/`, and inline definitions and construction
helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax
and move backend examples into framework definitions. Review old explicit
zeros for their changed meaning instead of preserving obsolete expectations
mechanically. Keep useful feature-adoption coverage; filenames need not be
renamed merely to reduce historical naming.
- **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for
representative source order, same-group conflicts, file imports, combined
documents, inherited source-relative content, exact IDs/version selection,
null suppression, explicit zero/false, and partial-profile completion.
Verify eager failures for unused final definitions and unchanged captured
message content after file edits on an existing engine. Retain shared-server
capacity, retry, cancellation, restricted artifact, output, and error tests.
Cover framework inspection's effective YAML, source layers, literal-key
explanations, diagnostics, and effective/historical native redaction without
provider calls. Protect the distinction between application validation and
framework validation, and unchanged visibility in existing profile/prepared
inspection. Avoid snapshots of incidental writer prose.
Own integration risks locally without recreating upstream's exhaustive parser
or inheritance matrices; use offline clients or `httptest` for generation.
- **Current documentation and migration guidance:** update owning contracts
in `docs/config.md`, `docs/cli.md`, and `docs/operations.md`, affected internal
docs, `docs/development.md`, architecture version/ownership references,
README, examples, and applicable consumer guidance. Link to v0.12.0 framework
contracts rather than copying their specification. Correct statements that
ConfigKit does not participate in framework loading. Explain the selected
source migration, framework-inspection command family and scoped redaction
exception, and engine-rebuild requirement. Preserve accepted ADR
decision content. Update HTTP docs only where observable behavior changes.
## Compatibility And Release Impact
This is an intentional breaking adoption, not a patch-only dependency refresh.
Users must migrate definitions, inheritance syntax, source assembly, and
assumptions about numeric presence, recursive maps, eager validation, and file
reload. Under the selected native interface they must also migrate the
application source selectors and move application backend definitions into
PromptKit source files. Provide small before/after examples and runnable
offline migration checks when implementation lands; no automatic legacy parser
or catalog alias layer is proposed.
PromptKit's maintained profile IDs remain supported, not frozen to fixed model
settings. Review used external catalog IDs against the selected catalogs; do
not promise live provider availability or preserve every volatile inventory ID.
Hashes remain opaque equality values, not cross-version identity guarantees.
Under the [release policy](../policy/release.md), the eventual release must be
a new pre-1.0 minor version. Do not select or publish a release in this work
set. The previously completed ConfigKit work may share that release; final
version, notes, and roadmap retirement belong to release preparation.
## Completion Criteria And Scope Limits
Adoption is complete when the released dependency graph is selected, the
approved source interface reaches the canonical framework boundary without
losing definition semantics, maintained examples and fixtures use v0.12.0,
and CLI/HTTP workflows and inspection meet the target above. The new framework
inspection family must use captured native reports with its explicitly scoped
redaction behavior, without changing existing inspection disclosure. Run the
existing development checks, affected offline examples, and link/diff checks,
with focused new integration tests for the actual migration risks.
This work does not add conversations, appended/follow-up messages,
prepared-handle coordination, semantic retry workflows, embedded configuration
bundles, framework internals, or application-owned framework validation.
Library availability alone does not justify additional commands, endpoints,
resource controls, recurring upstream probes, or release gates. Deferred
interfaces are scope choices for this adoption, not permanent prohibitions.
## Confirmed Decisions
### Native Source Cutover
The maintainer accepted the ordered `promptkit_sources` file/directory interface
and moving backend definitions out of application settings. This exposes
combined definitions, explicit priority, imports, and full presence/null
semantics through their canonical owner. It removes duplicated backend
representation and avoids translating absent scalar fields into presence-aware
overlays. The deliberate application schema and CLI migration accompanies the
unavoidable framework format migration.
Retaining the old directories and application backend surface was considered
but not selected: it would reduce migration while retaining duplicate backend
configuration, presence/null translation, and a less flexible source interface.
### Native Framework Inspection With A Scoped Redaction Exception
The maintainer selected `inspect configuration` using the captured native view,
including upstream redaction in this new interface only, rather than deferring
the feature. Provenance and history make layered configuration easier to
diagnose, and native writers avoid maintaining a parallel representation.
The accepted tradeoff is different provider-parameter visibility between this
new view and existing profile/prepared inspection. Existing API-key-only
redaction choices remain otherwise unchanged. Deferral or an upstream
consumer-selectable sensitivity API could avoid that difference, but neither is
a prerequisite for this adoption. Do not reconstruct private configuration to
bypass native writers or depend on an unpublished upstream interface.

View File

@@ -1,77 +0,0 @@
# Promptkit Upgrade Review Remediation
## Scope And Status
Review baseline: `e177d7c`, covering implementation commits after `5c3b0cf`.
This document records a resolved test-contract issue; it does not authorize
unrelated implementation changes. No runtime defect or missing planned feature
was identified in this review. Release preparation remains separate work.
## R1: Remove The Unrequested Context-Identity Invariant
Priority: P3 (low). Status: Complete.
Original location: `internal/adapter/http/handler_test.go:334–349`,
`TestHandlerRunTimeoutValidationAndContextMapping`, introduced in `7de2b02`.
The test's `child` field and `(ctx != parent) != tc.child` assertion required
the exact parent context object for omitted/null/zero timeouts and a distinct
object for a positive timeout. The requested contract concerns effective
deadlines and cancellation propagation, not Go interface identity. In
particular, a harmless derived context that preserves the parent's deadline,
values, and cancellation would fail the omission cases despite satisfying the
application contract.
This elevated an incidental implementation choice into a test-enforced
invariant, contrary to the [agent policy](../policy/agents.md) and
[testing policy](../policy/testing.md). The current handler's context behavior
is correct; this is a maintainability issue, not a runtime cancellation bug.
### Required Change
Remove the identity comparison and the identity-only table field. Retain
behavioral assertions that an earlier parent deadline is not extended and
parent cancellation reaches execution. For omitted/null/zero values, verify
that no deadline is introduced when the parent has none. Retain coverage of
positive deadlines and the distinction between a canceled execution context
and a provider-attempt timeout while the execution context remains live.
Use the existing runner seam and focused cases; do not introduce a context
wrapper framework, timer abstraction, new public guarantee, or production
refactor solely to change this test.
### Completion Criteria
- Tests protect effective deadline/cancellation behavior without requiring
context object identity.
- A semantically equivalent derived context does not fail merely because it
is a different object.
- Existing timeout validation and HTTP outcome coverage remains intact.
### Resolution And Validation
Removed the identity-only table field and context comparisons. The test now
checks effective deadlines, including omitted/null/zero requests with no
parent deadline, and explicitly checks that parent cancellation reaches the
runner. Existing positive-deadline integration tests and live-context
provider-timeout mapping remain intact. No production code changed.
Focused HTTP timeout tests, `go test ./...`, `go test -race ./...`,
`go vet ./...`, a native build outside the repository, and `git diff --check`
all passed after remediation.
## Original Review Verification
- `go test -race -count=1 ./...` passed, including retry, shared-capacity,
deadline, report, definition-conformance, and architecture-boundary tests.
- `go vet ./...` passed.
- A native `cmd/scriptorium` build passed, with output outside the repository.
- The selected dependency is Promptkit v0.11.0 with its intended v2 catalogs.
- Application code, tests, release automation, and historical releases were
not changed during this review.
The runtime ownership boundaries remain as intended: Promptkit owns framework
formats, execution, retries, and backend admission; Scriptorium owns executable
adapters, application settings, HTTP artifact policy, deadlines, and terminal
report presentation. No additional runtime restrictions, durable workflow
state, or extra release compliance gates were identified in the reviewed diff.

View File

@@ -8,7 +8,8 @@ and publication remain separate release preparation. The baseline descriptions
below record the state when this roadmap was written, not current behavior. below record the state when this roadmap was written, not current behavior.
Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
v0.10.0 catalog transition. This document defines the desired end state and v0.10.0 catalog transition. This document defines the desired end state and
the changes from the current baseline. The [implementation plan](implementation.md) the changes from the current baseline. The historical plan at
`git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md`
owns sequencing, concrete interface choices, verification steps, and unresolved owns sequencing, concrete interface choices, verification steps, and unresolved
implementation decisions. implementation decisions.
@@ -268,6 +269,6 @@ boundaries.
the version-matched note remain release preparation. the version-matched note remain release preparation.
Concrete interface decisions and the selected distribution approach are recorded Concrete interface decisions and the selected distribution approach are recorded
in the completed [implementation plan](implementation.md). They do not expand in that completed historical plan. They do not expand
the product into conversations, follow-up messages, application-owned semantic the product into conversations, follow-up messages, application-owned semantic
retry loops, prepared-handle coordination, or multi-step workflows. retry loops, prepared-handle coordination, or multi-step workflows.

View File

@@ -1,4 +0,0 @@
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY

View File

@@ -0,0 +1,2 @@
promptkit_sources:
- file: ./examples/framework/backends.yml

View File

@@ -0,0 +1,2 @@
promptkit_sources:
- file: ./examples/profiles/local-fast.yaml

View File

@@ -0,0 +1,2 @@
promptkit_sources:
- file: ./examples/prompts/generic.markdown_summary.yaml

View File

@@ -1,3 +1,5 @@
prompt_dir: ./examples/prompts promptkit_sources:
profile_dir: ./examples/profiles - directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas

View File

@@ -0,0 +1,10 @@
config:
sequences:
- destination: [promptkit_sources]
key: file
mode: upsert
imports:
- dir: config-fragments/collections
pattern: '*.yml'
required: true
schema_dir: ./examples/schemas

View File

@@ -1,8 +1,8 @@
# Select from the repository root; application paths remain working-directory-relative. # Select from the repository root; application paths remain working-directory-relative.
configkit: config:
imports: imports:
- path: config-fragments/sources.yml - path: config-fragments/sources.yml
- path: config-fragments/backend.yml required: true
server: server:
addr: :8080 addr: :8080

View File

@@ -0,0 +1,2 @@
promptkit_sources:
- file: ./examples/discovery/framework.yml

View File

@@ -1,16 +1,9 @@
prompt_dir: ./examples/prompts promptkit_sources:
profile_dir: ./examples/profiles - directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0
server: server:
addr: 127.0.0.1:8080 addr: 127.0.0.1:8080
artifact_root: . artifact_root: .

View File

@@ -0,0 +1,6 @@
# Application paths are relative to the repository invocation directory.
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/inheritance.yml
schema_dir: ./examples/schemas

View File

@@ -1,5 +1,7 @@
prompt_dir: ./examples/prompts promptkit_sources:
profile_dir: ./examples/profiles - directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
server: server:

View File

@@ -0,0 +1,12 @@
config:
imports:
- path: profiles/base.yaml
destination: [collections, review, profiles]
placement: sequence-item
required: true
- path: prompts/answer.yaml
destination: [collections, review, prompts]
placement: sequence-item
required: true
collections:
review: {}

View File

@@ -0,0 +1,3 @@
id: base
endpoint: https://example.invalid/v1
model: review-example

View File

@@ -0,0 +1,8 @@
id: answer
default_profile: review/base
messages:
- role: user
content: Review this material and report your findings.
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,20 @@
config:
imports:
- path: profiles/base.yml
destination: [collections, support, profiles]
placement: sequence-item
required: true
- path: profiles/fast.yml
destination: [collections, support, profiles]
placement: sequence-item
required: true
- path: prompts/answer.yml
destination: [collections, support, prompts]
placement: sequence-item
required: true
- path: prompts/summarize.yml
destination: [collections, support, prompts]
placement: sequence-item
required: true
collections:
support: {}

View File

@@ -0,0 +1,2 @@
repository_metadata:
purpose: This file is not a PromptKit framework input.

View File

@@ -0,0 +1,4 @@
id: base
endpoint: https://example.invalid/v1
model: support-example
temperature: 0.2

View File

@@ -0,0 +1,3 @@
id: fast
extends: {id: base}
max_tokens: 256

View File

@@ -0,0 +1,3 @@
Answer the support request using this transcript:
{{input "transcript"}}

View File

@@ -0,0 +1,12 @@
id: answer
default_profile: support/fast
inputs:
- name: transcript
required: true
content_type: text/markdown
messages:
- role: user
content_file: ./answer.md
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,8 @@
id: summarize
default_profile: support/fast
messages:
- role: user
content: Summarize the support request concisely.
output:
format: text
validation_mode: none

View File

@@ -0,0 +1,4 @@
config:
imports:
- glob: collections/*/collection.yml
- glob: collections/*/collection.yaml

View File

@@ -0,0 +1,8 @@
backends:
- id: local-gpu
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
extra_params:
provider_option: enabled
concurrency_limit: 2
queue_capacity: 0

View File

@@ -0,0 +1,13 @@
backends:
- id: local-base
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
concurrency_limit: 2
queue_capacity: 4
extra_params:
provider_option: true
- id: local-gpu
extends: {id: local-base}
queue_capacity: 0
extra_params:
provider_option: false

View File

@@ -14,5 +14,6 @@
"vars": { "vars": {
"session_date": "2026-05-04" "session_date": "2026-05-04"
}, },
"include_raw_output": false "include_raw_output": false,
"include_execution_report": false
} }

View File

@@ -0,0 +1,2 @@
promptkit_sources:
- file: ./examples/profiles/local-gpu.yml

View File

@@ -1,4 +1,5 @@
id: local-fast profiles:
- id: local-fast
endpoint: http://localhost:8000/v1 endpoint: http://localhost:8000/v1
model: gpt-4o-mini model: gpt-4o-mini
temperature: 0.2 temperature: 0.2

View File

@@ -1,4 +1,5 @@
id: local-gpu profiles:
- id: local-gpu
backend: local-gpu backend: local-gpu
model: local-model model: local-model
reasoning_effort: low reasoning_effort: low

View File

@@ -1,4 +1,5 @@
id: local-quality profiles:
- id: local-quality
endpoint: http://localhost:8000/v1 endpoint: http://localhost:8000/v1
model: gpt-4.1 model: gpt-4.1
temperature: 0.0 temperature: 0.0

View File

@@ -1,5 +1,5 @@
id: dnd.session_recap prompts:
version: "1.0.0" - id: dnd.session_recap
default_profile: local-quality default_profile: local-quality
description: Example D&D session recap prompt definition for demonstration only. description: Example D&D session recap prompt definition for demonstration only.
inputs: inputs:

View File

@@ -1,5 +1,5 @@
id: generic.markdown_summary prompts:
version: "1.0.0" - id: generic.markdown_summary
default_profile: local-fast default_profile: local-fast
description: Generic markdown summary from transcript and glossary. description: Generic markdown summary from transcript and glossary.
inputs: inputs:

View File

@@ -1,5 +1,5 @@
id: generic.structured_events prompts:
version: "1.0.0" - id: generic.structured_events
default_profile: local-quality default_profile: local-quality
description: Produce structured event JSON from a transcript. description: Produce structured event JSON from a transcript.
inputs: inputs:

View File

@@ -7,7 +7,6 @@ cd "$repo_root"
go run ./cmd/scriptorium render \ go run ./cmd/scriptorium render \
--config ./examples/config.full.yml \ --config ./examples/config.full.yml \
--prompt generic.markdown_summary \ --prompt generic.markdown_summary \
--prompt-version 1.0.0 \
--profile local-gpu \ --profile local-gpu \
--session-id example-session \ --session-id example-session \
--reasoning-effort= \ --reasoning-effort= \

15
go.mod
View File

@@ -1,17 +1,14 @@
module gitea.maximumdirect.net/eric/scriptorium module gitea.maximumdirect.net/eric/scriptorium
go 1.25.5 go 1.27.0
require ( require (
gitea.maximumdirect.net/eric/ConfigKit v0.4.0 go.maximumdirect.net/configkit v1.2.1
gitea.maximumdirect.net/eric/promptkit v0.11.0 go.maximumdirect.net/promptkit v0.23.3
) )
require ( require (
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1 // indirect github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 // indirect go.yaml.in/yaml/v4 v4.0.0 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect golang.org/x/text v0.44.0 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
golang.org/x/text v0.14.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
) )

28
go.sum
View File

@@ -1,20 +1,12 @@
gitea.maximumdirect.net/eric/ConfigKit v0.4.0 h1:fo+vKff3zTGeWqJIA38NtT84b6OUP//9ZmBH3lFuKgk=
gitea.maximumdirect.net/eric/ConfigKit v0.4.0/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
gitea.maximumdirect.net/eric/promptkit v0.11.0 h1:x7JguOUiInPVXK0GEitjyoRFqqvcuSTjYUvqJ+whtik=
gitea.maximumdirect.net/eric/promptkit v0.11.0/go.mod h1:0zEBVlJJC+ldDdXazAgybYBXNSe74vwFx5dyOuSos/w=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1 h1:S2/Q/JDE+m8Ca3pDhAjVbfYrdlEhs9blj0STgNopHo0=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 h1:Y0EXc3eh12eKW2NrOviVqdk3oBo6UUjopt1YAa1B3Oc=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0/go.mod h1:mtgD1E0SGm0e/I8Ffhz+AYX7GN7RKUWJXehNFIKHs4Y=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= go.maximumdirect.net/promptkit v0.23.3 h1:bKbrkluwfgXUsm0e/mxz/TpV9b60yUtJLVUROLsM3VU=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= go.maximumdirect.net/promptkit v0.23.3/go.mod h1:vPFg76VXcffP0JBFMS2WADCHwV5FYvO2O4bvIoiDlwc=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=

View File

@@ -6,8 +6,8 @@ import (
"fmt" "fmt"
"io" "io"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config" appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
"go.maximumdirect.net/configkit"
) )
// applicationOverrides keeps explicit application flags separate from invocation state. // applicationOverrides keeps explicit application flags separate from invocation state.
@@ -16,10 +16,8 @@ func applicationOverrides(fs *flag.FlagSet) []configkit.Override {
fs.Visit(func(selected *flag.Flag) { fs.Visit(func(selected *flag.Flag) {
var path configkit.Path var path configkit.Path
switch selected.Name { switch selected.Name {
case "prompt-dir": case "promptkit-source":
path = configkit.Keys("prompt_dir") path = configkit.Keys("promptkit_sources")
case "profile-dir":
path = configkit.Keys("profile_dir")
case "schema-dir": case "schema-dir":
path = configkit.Keys("schema_dir") path = configkit.Keys("schema_dir")
case "addr": case "addr":
@@ -55,6 +53,7 @@ func loadApplicationSettings(configPath, overlay string, explicit bool, override
func writeApplicationError(output io.Writer, label string, err error) { func writeApplicationError(output io.Writer, label string, err error) {
var loadError *configkit.LoadError var loadError *configkit.LoadError
if errors.As(err, &loadError) { if errors.As(err, &loadError) {
_, _ = fmt.Fprintf(output, "%s error:\n", label)
if writeErr := configkit.WriteDiagnostics(output, loadError.Diagnostics()); writeErr != nil { if writeErr := configkit.WriteDiagnostics(output, loadError.Diagnostics()); writeErr != nil {
_, _ = fmt.Fprintf(output, "%s diagnostic write error: %v\n", label, writeErr) _, _ = fmt.Fprintf(output, "%s diagnostic write error: %v\n", label, writeErr)
} }

View File

@@ -6,8 +6,8 @@ import (
"fmt" "fmt"
"io" "io"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config" appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
"go.maximumdirect.net/configkit"
) )
type configurationSource struct { type configurationSource struct {
@@ -93,8 +93,6 @@ func configCommand(args []string, stdout, stderr io.Writer) int {
} }
func registerConfigurationOverrides(fs *flag.FlagSet) { func registerConfigurationOverrides(fs *flag.FlagSet) {
fs.String("prompt-dir", "", "prompt-definition directory override")
fs.String("profile-dir", "", "profile directory override")
fs.String("schema-dir", "", "schema directory override") fs.String("schema-dir", "", "schema directory override")
fs.String("addr", "", "HTTP listen address override") fs.String("addr", "", "HTTP listen address override")
fs.String("artifact-root", "", "HTTP artifact root override") fs.String("artifact-root", "", "HTTP artifact root override")

View File

@@ -7,6 +7,7 @@ import (
"io" "io"
"os" "os"
"path/filepath" "path/filepath"
"reflect"
"strings" "strings"
"testing" "testing"
@@ -31,13 +32,43 @@ func TestConfigCommandsInspectApplicationWithoutEngine(t *testing.T) {
} }
case "sources": case "sources":
var sources []configurationSource var sources []configurationSource
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 1 || sources[0].Layer != "base" { if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 1 || sources[0].Layer != "main" {
t.Fatalf("unexpected source records: %q (%v)", stdout, err) t.Fatalf("unexpected source records: %q (%v)", stdout, err)
} }
} }
} }
} }
func TestCollectionExampleLoadsAndRenders(t *testing.T) {
t.Chdir(filepath.Join("..", "..", ".."))
want := []appconfig.SourceSelection{
{File: "examples/framework/backends.yml"},
{File: "examples/profiles/local-fast.yaml"},
{File: "examples/prompts/generic.markdown_summary.yaml"},
}
for _, overlay := range []string{"", "collection"} {
result, err := appconfig.Load(appconfig.LoadOptions{Path: "examples/config.collections.yml", Explicit: true, Overlay: overlay})
if err != nil {
t.Fatal(err)
}
expected := append([]appconfig.SourceSelection{}, want...)
if overlay != "" {
expected = append(expected, appconfig.SourceSelection{File: "examples/profiles/local-gpu.yml"})
}
if !reflect.DeepEqual(result.Config.PromptKitSources, expected) {
t.Fatalf("overlay %q selectors = %+v, want %+v", overlay, result.Config.PromptKitSources, expected)
}
args := []string{"--config", "examples/config.collections.yml", "--prompt", "generic.markdown_summary", "--input", "transcript=examples/fixtures/transcript.md", "--input", "glossary=examples/fixtures/glossary.yml"}
if overlay != "" {
args = append(args, "--config-overlay", overlay)
}
code, stdout, stderr := runCLICommand(t, renderCommand, args)
if code != ExitOK || !strings.Contains(stdout, "generic.markdown_summary") || !strings.Contains(stdout, "local-fast") {
t.Fatalf("collection render failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
}
}
func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) { func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
dir := t.TempDir() dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil { if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
@@ -45,17 +76,17 @@ func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
} }
base := filepath.Join(dir, "config.yml") base := filepath.Join(dir, "config.yml")
for path, body := range map[string]string{ for path, body := range map[string]string{
base: "configkit:\n imports:\n - path: fragment.yml\nprompt_dir: ' ./before/../prompts '\nprofile_dir: ./profiles\n", base: "config:\n imports:\n - path: fragment.yml\n required: true\npromptkit_sources:\n - directory: ' ./before/../prompts '\nschema_dir: ./schemas\n",
filepath.Join(dir, "fragment.yml"): "server:\n addr: :8081\n", filepath.Join(dir, "fragment.yml"): "server:\n addr: :8081\n",
filepath.Join(dir, "overlays", "local.yml"): "server:\n addr: :9090\n", filepath.Join(dir, "overlays", "local.yml"): "promptkit_sources:\n - directory: ./overlay-prompts\nserver:\n addr: :9090\n",
} { } {
if err := os.WriteFile(path, []byte(body), 0o600); err != nil { if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatal(err) t.Fatal(err)
} }
} }
args := []string{"--config", base, "--config-overlay", "local", "--profile-dir=", "--addr", ":7070"} args := []string{"--config", base, "--config-overlay", "local", "--schema-dir=", "--addr", ":7070"}
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"show"}, args...)) code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"show"}, args...))
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "prompt_dir: prompts") || !strings.Contains(stdout, "profile_dir: ''") || !strings.Contains(stdout, "addr: :7070") { if code != ExitOK || stderr != "" || !strings.Contains(stdout, "directory: overlay-prompts") || !strings.Contains(stdout, "schema_dir: ''") || !strings.Contains(stdout, "addr: :7070") || strings.Contains(stdout, "before/../prompts") {
t.Fatalf("resolved effective output changed: code=%d out=%q err=%q", code, stdout, stderr) t.Fatalf("resolved effective output changed: code=%d out=%q err=%q", code, stdout, stderr)
} }
code, stdout, stderr = runCLICommand(t, configCommand, append([]string{"sources"}, args...)) code, stdout, stderr = runCLICommand(t, configCommand, append([]string{"sources"}, args...))
@@ -66,42 +97,52 @@ func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 5 { if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 5 {
t.Fatalf("unexpected composed source records: %+v (%v)", sources, err) t.Fatalf("unexpected composed source records: %+v (%v)", sources, err)
} }
for i, layer := range []string{"base", "base", "overlay", "cli", "cli"} { for i, layer := range []string{"main", "main", "overlay", "cli", "cli"} {
if string(sources[i].Layer) != layer { if string(sources[i].Layer) != layer {
t.Fatalf("source %d layer = %q, want %q", i, sources[i].Layer, layer) t.Fatalf("source %d layer = %q, want %q", i, sources[i].Layer, layer)
} }
} }
} }
func TestConfigInspectionKeepsReferencesAndOrdinaryParameters(t *testing.T) { func TestApplicationInspectionDoesNotAcquireFrameworkSources(t *testing.T) {
const name = "SCRIPTORIUM_CONFIG_TEST_API_KEY" dir := t.TempDir()
const secret = "synthetic-secret-value-should-not-appear" frameworkPath := filepath.Join(dir, "invalid-framework.yml")
path := writeAppConfigFile(t, `backends: if err := os.WriteFile(frameworkPath, []byte("not: [valid\n"), 0o600); err != nil {
synthetic:
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_CONFIG_TEST_API_KEY
extra_params:
visible_parameter: synthetic-ordinary-value
`)
t.Setenv(name, secret)
for _, present := range []bool{true, false} {
if !present {
if err := os.Unsetenv(name); err != nil {
t.Fatal(err) t.Fatal(err)
} }
} for _, frameworkSource := range []struct {
code, stdout, stderr := runCLICommand(t, configCommand, []string{"show", "--config", path}) name string
if code != ExitOK || stderr != "" || !strings.Contains(stdout, name) || !strings.Contains(stdout, "synthetic-ordinary-value") || strings.Contains(stdout, secret) { path string
t.Fatalf("credential boundary changed with present=%t: code=%d out=%q err=%q", present, code, stdout, stderr) }{
{name: "invalid definition", path: frameworkPath},
{name: "missing path", path: filepath.Join(dir, "missing-framework.yml")},
} {
t.Run(frameworkSource.name, func(t *testing.T) {
path := writeAppConfigFile(t, "promptkit_sources:\n - file: "+frameworkSource.path+"\n")
for _, args := range [][]string{
{"validate"},
{"show"},
{"sources"},
{"explain", "--path", "/promptkit_sources/0/file"},
} {
code, stdout, stderr := runCLICommand(t, configCommand, append(args, "--config", path))
if code != ExitOK || stderr != "" {
t.Fatalf("application inspection acquired configured framework source: args=%q code=%d out=%q err=%q", args, code, stdout, stderr)
} }
} }
result, err := appconfig.Load(appconfig.LoadOptions{Path: path, Explicit: true}) })
if err != nil {
t.Fatal(err)
} }
settings := appconfig.Settings(result.Config) }
if len(settings.Backends) != 1 || settings.Backends[0].ExtraParams["visible_parameter"] != "synthetic-ordinary-value" {
t.Fatalf("runtime backend parameters changed: %+v", settings.Backends) func TestConfigCommandsRejectRetiredFrameworkFields(t *testing.T) {
for _, field := range []string{"prompt_dir", "profile_dir", "backends"} {
t.Run(field, func(t *testing.T) {
path := writeAppConfigFile(t, field+": {}\n")
code, stdout, stderr := runCLICommand(t, configCommand, []string{"validate", "--config", path})
if code != ExitRuntimeError || stdout != "" || stderr == "" {
t.Fatalf("retired application field %q was accepted: code=%d out=%q err=%q", field, code, stdout, stderr)
}
})
} }
} }
@@ -127,51 +168,36 @@ func TestConfigCommandFailuresDoNotProduceSuccessfulOutput(t *testing.T) {
} }
} }
func TestConfigExplainUsesResolvedHistoryAndKeepsParametersVisible(t *testing.T) { func TestConfigExplainUsesResolvedHistory(t *testing.T) {
dir := t.TempDir() dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil { if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
t.Fatal(err) t.Fatal(err)
} }
base := filepath.Join(dir, "config.yml") base := filepath.Join(dir, "config.yml")
for path, body := range map[string]string{ for path, body := range map[string]string{
base: `prompt_dir: " ./prompts/../prompts " base: `promptkit_sources:
- directory: " ./prompts/../prompts "
server: server:
addr: :8080 addr: :8080
backends:
"team/blue~1":
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_EXPLAIN_KEY
extra_params:
"0": base-parameter
`,
filepath.Join(dir, "overlays", "local.yml"): `server:
addr: :9090
backends:
"team/blue~1":
extra_params:
"0": overlay-parameter
`, `,
filepath.Join(dir, "overlays", "local.yml"): "server:\n addr: :9090\n",
} { } {
if err := os.WriteFile(path, []byte(body), 0o600); err != nil { if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
t.Fatal(err) t.Fatal(err)
} }
} }
const keyValue = "synthetic-key-bytes-must-not-appear"
t.Setenv("SCRIPTORIUM_EXPLAIN_KEY", keyValue)
args := []string{"--config", base, "--config-overlay", "local", "--addr", ":9090"} args := []string{"--config", base, "--config-overlay", "local", "--addr", ":9090"}
for _, tc := range []struct { for _, tc := range []struct {
pointer string pointer string
want []string want []string
}{ }{
{pointer: "/server/addr", want: []string{":8080", ":9090", "--addr"}}, {pointer: "/server/addr", want: []string{":8080", ":9090", "--addr"}},
{pointer: "/prompt_dir", want: []string{"normalized application path", "prompts"}}, {pointer: "/promptkit_sources/0/directory", want: []string{"normalized application path", "prompts"}},
{pointer: "/backends/team~1blue~01/extra_params/0", want: []string{"base-parameter", "overlay-parameter"}}, {pointer: "", want: []string{"promptkit_sources", "server", "addr"}},
{pointer: "/backends/team~1blue~01/api_key_env", want: []string{"SCRIPTORIUM_EXPLAIN_KEY"}},
{pointer: "", want: []string{"base-parameter", "overlay-parameter", "SCRIPTORIUM_EXPLAIN_KEY"}},
} { } {
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", tc.pointer}, args...)) code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", tc.pointer}, args...))
if code != ExitOK || stderr != "" || strings.Contains(stdout, keyValue) { if code != ExitOK || stderr != "" {
t.Fatalf("explain %q failed or disclosed key: code=%d out=%q err=%q", tc.pointer, code, stdout, stderr) t.Fatalf("explain %q failed: code=%d out=%q err=%q", tc.pointer, code, stdout, stderr)
} }
for _, want := range tc.want { for _, want := range tc.want {
if !strings.Contains(stdout, want) { if !strings.Contains(stdout, want) {
@@ -179,13 +205,6 @@ backends:
} }
} }
} }
if err := os.Unsetenv("SCRIPTORIUM_EXPLAIN_KEY"); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", "/backends/team~1blue~01/api_key_env"}, args...))
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "SCRIPTORIUM_EXPLAIN_KEY") || strings.Contains(stdout, keyValue) {
t.Fatalf("absent credential changed reference explanation: code=%d out=%q err=%q", code, stdout, stderr)
}
} }
func TestConfigExplainRejectsUnknownOrMalformedPaths(t *testing.T) { func TestConfigExplainRejectsUnknownOrMalformedPaths(t *testing.T) {

View File

@@ -0,0 +1,82 @@
package cli
import (
"fmt"
"os"
"path/filepath"
"strings"
"testing"
)
func TestCollectionCheckoutDiscoveryAcrossInvocations(t *testing.T) {
fixture, err := filepath.Abs(filepath.Join("..", "..", "..", "examples", "discovery"))
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
name string
first string
second string
}{
{name: "yml then yaml", first: "support-repo", second: "review-repo"},
{name: "yaml then yml", first: "review-repo", second: "support-repo"},
} {
t.Run(tc.name, func(t *testing.T) {
root := t.TempDir()
framework, err := os.ReadFile(filepath.Join(fixture, "framework.yml"))
if err != nil {
t.Fatal(err)
}
frameworkPath := filepath.Join(root, "framework.yml")
if err := os.WriteFile(frameworkPath, framework, 0o644); err != nil {
t.Fatal(err)
}
collections := filepath.Join(root, "collections")
if err := os.MkdirAll(collections, 0o755); err != nil {
t.Fatal(err)
}
install := func(name string) {
t.Helper()
if err := os.CopyFS(filepath.Join(collections, name), os.DirFS(filepath.Join(fixture, "collections", name))); err != nil {
t.Fatal(err)
}
}
config := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkPath))
input := filepath.Join(root, "transcript.md")
if err := os.WriteFile(input, []byte("synthetic discovery transcript"), 0o644); err != nil {
t.Fatal(err)
}
args := func(name string) []string {
if name == "support-repo" {
return []string{"--config", config, "--prompt", "support/answer", "--profile", "support/fast", "--input", "transcript=" + input}
}
return []string{"--config", config, "--prompt", "review/answer", "--profile", "review/base"}
}
check := func(name string) {
t.Helper()
code, out, stderr := runCLICommand(t, renderCommand, args(name))
if code != ExitOK {
t.Fatalf("render %s: code=%d stderr=%s", name, code, stderr)
}
if name == "support-repo" {
for _, want := range []string{"prompt: support/answer", "selected_profile_id: support/fast", "model: support-example", "max_tokens: 256", "Answer the support request", "synthetic discovery transcript"} {
if !strings.Contains(out, want) {
t.Fatalf("missing %q: %s", want, out)
}
}
} else if !strings.Contains(out, "prompt: review/answer") || !strings.Contains(out, "model: review-example") || !strings.Contains(out, "Review this material") {
t.Fatalf("unexpected review render: %s", out)
}
}
install(tc.first)
check(tc.first)
code, _, _ := runCLICommand(t, renderCommand, args(tc.second))
if code != ExitRuntimeError {
t.Fatal("uninstalled collection unexpectedly selected")
}
install(tc.second)
check(tc.first)
check(tc.second)
})
}
}

View File

@@ -0,0 +1,162 @@
package cli
import (
"encoding/json"
"errors"
"flag"
"fmt"
"io"
"go.maximumdirect.net/configkit"
)
type frameworkConfigurationConfig struct {
mode, configPath, configOverlay, schemaDir string
path string
configExplicit bool
pathExplicit bool
overrides []configkit.Override
diagnostics []configkit.Diagnostic
}
type frameworkConfigurationSource struct {
ID string `json:"id"`
Label string `json:"label"`
Layer configkit.Layer `json:"layer"`
Kind configkit.SourceKind `json:"kind"`
UnderlayIndex int `json:"underlay_index"`
Path string `json:"path,omitempty"`
ImportedFrom *frameworkConfigurationLocation `json:"imported_from,omitempty"`
}
type frameworkConfigurationLocation struct {
SourceID string `json:"source_id"`
Line int `json:"line"`
Column int `json:"column"`
}
func inspectFrameworkConfigurationCommand(args []string, stdout, stderr io.Writer) int {
cfg, err := parseFrameworkConfigurationArgs(args)
if err != nil {
writeApplicationError(stderr, "inspect configuration parse", err)
return ExitRuntimeError
}
var explanationPath configkit.Path
if cfg.mode == "explain" {
explanationPath, err = configkit.ParsePath(cfg.path)
if err != nil {
writeApplicationError(stderr, "inspect configuration path", err)
return ExitRuntimeError
}
}
settings, err := resolveAppSettingsForFrameworkConfiguration(cfg)
if err != nil {
writeApplicationError(stderr, "inspect configuration", err)
return ExitRuntimeError
}
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
return ExitRuntimeError
}
engine, err := newEngine(settings)
if err != nil {
writeApplicationError(stderr, "engine", err)
return ExitRuntimeError
}
view, err := engine.InspectConfiguration()
if err != nil {
writeApplicationError(stderr, "inspect configuration", err)
return ExitRuntimeError
}
if err := configkit.WriteDiagnostics(stderr, view.Diagnostics()); err != nil {
return ExitRuntimeError
}
if cfg.mode == "validate" {
return ExitOK
}
if cfg.mode == "explain" {
if err := view.WriteExplanation(stdout, explanationPath); err != nil {
fmt.Fprintf(stderr, "inspect configuration explain %q: %v\n", cfg.path, err)
return ExitRuntimeError
}
return ExitOK
}
switch cfg.mode {
case "show":
err = view.WriteEffective(stdout)
case "sources":
sources := frameworkConfigurationSources(view.Sources())
err = json.NewEncoder(stdout).Encode(sources)
}
if err != nil {
fmt.Fprintf(stderr, "inspect configuration output error: %v\n", err)
return ExitRuntimeError
}
return ExitOK
}
func parseFrameworkConfigurationArgs(args []string) (*frameworkConfigurationConfig, error) {
if len(args) == 0 {
return nil, errors.New("configuration operation is required")
}
cfg := &frameworkConfigurationConfig{mode: args[0]}
switch cfg.mode {
case "validate", "show", "sources", "explain":
default:
return nil, fmt.Errorf("unknown configuration operation %q", cfg.mode)
}
fs := flag.NewFlagSet("inspect configuration "+cfg.mode, flag.ContinueOnError)
fs.SetOutput(io.Discard)
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
var promptkitSources promptKitSourceFlagValue
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
fs.StringVar(&cfg.path, "path", "", "JSON Pointer to explain (required for explain)")
if err := fs.Parse(args[1:]); err != nil {
return nil, err
}
if fs.NArg() != 0 {
return nil, fmt.Errorf("unexpected positional args: %v", fs.Args())
}
cfg.configExplicit = flagWasSet(fs, "config")
cfg.pathExplicit = flagWasSet(fs, "path")
if cfg.mode == "explain" && !cfg.pathExplicit {
return nil, errors.New("--path is required for explain")
}
cfg.overrides = applicationOverrides(fs)
return cfg, nil
}
func resolveAppSettingsForFrameworkConfiguration(cfg *frameworkConfigurationConfig) (engineSettings, error) {
settings, diagnostics, err := loadApplicationSettings(cfg.configPath, cfg.configOverlay, cfg.configExplicit, cfg.overrides)
if err != nil {
return engineSettings{}, err
}
cfg.diagnostics = diagnostics
return engineSettings{
promptkitSources: settings.PromptKitSources,
schemaDir: settings.SchemaDir,
transientRetries: settings.TransientRetries,
}, nil
}
func frameworkConfigurationSources(sources []configkit.SourceInfo) []frameworkConfigurationSource {
result := make([]frameworkConfigurationSource, 0, len(sources))
for _, source := range sources {
item := frameworkConfigurationSource{
ID: source.ID, Label: source.Label, Layer: source.Layer,
Kind: source.Kind, UnderlayIndex: source.UnderlayIndex, Path: source.Path,
}
if source.ImportedFrom != nil {
item.ImportedFrom = &frameworkConfigurationLocation{
SourceID: source.ImportedFrom.SourceID,
Line: source.ImportedFrom.Line,
Column: source.ImportedFrom.Column,
}
}
result = append(result, item)
}
return result
}

View File

@@ -0,0 +1,391 @@
package cli
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
configkit "go.maximumdirect.net/configkit"
)
func TestFrameworkConfigurationCommandsNeedNoPromptOrCredential(t *testing.T) {
configPath := writeAppConfigFile(t, "{}\n")
code, stdout, stderr := runCLICommand(t, inspectCommand, []string{
"configuration", "validate", "--config", configPath,
})
if code != ExitOK || stdout != "" || stderr != "" {
t.Fatalf("source-free validation failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
t.Setenv("SCRIPTORIUM_FRAMEWORK_KEY", "")
root := t.TempDir()
frameworkFile := filepath.Join(root, "framework.yml")
writeFrameworkSourceFile(t, root, "framework.yml", `backends:
- id: local
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_FRAMEWORK_KEY
profiles:
- id: protected
backend: local
model: offline-model
api_key_required: true
`)
configPath = writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
for _, mode := range []string{"validate", "show", "sources"} {
code, stdout, stderr = runCLICommand(t, inspectCommand, []string{
"configuration", mode, "--config", configPath,
})
if code != ExitOK || stderr != "" {
t.Fatalf("%s required a prompt or credential: code=%d stdout=%q stderr=%q", mode, code, stdout, stderr)
}
if mode == "validate" && stdout != "" {
t.Fatalf("validation wrote success output: %q", stdout)
}
if mode == "show" && (!strings.Contains(stdout, "profiles:") || !strings.Contains(stdout, "offline-model")) {
t.Fatalf("effective framework YAML is missing: %q", stdout)
}
}
}
func TestFrameworkConfigurationSourcesProjectsOrderedNativeRecords(t *testing.T) {
root := t.TempDir()
importDir := filepath.Join(root, "catalog")
if err := os.MkdirAll(importDir, 0o755); err != nil {
t.Fatal(err)
}
mainPath := writeFrameworkSourceFile(t, root, "main.yml", `config:
imports:
- path: catalog/fragment.yml
required: true
backends:
- id: local
endpoint: http://127.0.0.1:1/v1
`)
fragmentPath := writeFrameworkSourceFile(t, importDir, "fragment.yml", `profiles:
- id: imported
model: imported-model
`)
directory := t.TempDir()
directoryPath := writeFrameworkSourceFile(t, directory, "directory.yml", `profiles:
- id: directory
model: directory-model
`)
configuredMissing := filepath.Join(root, "configured-but-replaced.yml")
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", configuredMissing))
args := []string{
"configuration", "sources", "--config", configPath,
"--promptkit-source", mainPath,
"--promptkit-source", directory,
}
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
if code != ExitOK || stderr != "" || !strings.HasSuffix(stdout, "\n") {
t.Fatalf("framework sources command failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
var sources []frameworkConfigurationSource
if err := json.Unmarshal([]byte(stdout), &sources); err != nil {
t.Fatalf("decode framework source DTOs: %v\n%s", err, stdout)
}
var rawSources []map[string]any
if err := json.Unmarshal([]byte(stdout), &rawSources); err != nil {
t.Fatalf("decode framework source fields: %v", err)
}
mainIndex := findFrameworkSource(t, sources, mainPath)
fragmentIndex := findFrameworkSource(t, sources, fragmentPath)
directoryIndex := findFrameworkSource(t, sources, directoryPath)
main := sources[mainIndex]
fragment := sources[fragmentIndex]
directorySource := sources[directoryIndex]
if !(mainIndex < fragmentIndex && fragmentIndex < directoryIndex) {
t.Fatalf("captured source order changed: main=%d fragment=%d directory=%d", mainIndex, fragmentIndex, directoryIndex)
}
if main.ID == "" || main.Label == "" || main.Layer != configkit.LayerUnderlay || main.Kind != configkit.SourceKindFile || main.UnderlayIndex < 1 {
t.Fatalf("explicit file source fields are incomplete: %+v", main)
}
for _, key := range []string{"id", "label", "layer", "kind", "underlay_index", "path"} {
if _, exists := rawSources[mainIndex][key]; !exists {
t.Fatalf("source DTO omitted %q: %#v", key, rawSources[mainIndex])
}
}
for _, key := range []string{"ID", "Label", "Layer", "Kind", "UnderlayIndex", "filesystem"} {
if _, exists := rawSources[mainIndex][key]; exists {
t.Fatalf("source DTO exposed implementation field %q: %#v", key, rawSources[mainIndex])
}
}
if fragment.Layer != configkit.LayerUnderlay || fragment.Kind != configkit.SourceKindFile || fragment.ImportedFrom == nil ||
fragment.ImportedFrom.SourceID != main.ID || fragment.ImportedFrom.Line < 1 || fragment.ImportedFrom.Column < 1 {
t.Fatalf("import source fields are incomplete: %+v", fragment)
}
if importedFrom, ok := rawSources[fragmentIndex]["imported_from"].(map[string]any); !ok || importedFrom["source_id"] != main.ID || importedFrom["line"] == nil || importedFrom["column"] == nil {
t.Fatalf("import location DTO fields are incomplete: %#v", rawSources[fragmentIndex])
}
if directorySource.Layer != configkit.LayerUnderlay || directorySource.Kind != configkit.SourceKindFile || directorySource.UnderlayIndex <= main.UnderlayIndex {
t.Fatalf("directory-selected source fields/order are incomplete: %+v (main %+v)", directorySource, main)
}
}
func TestFrameworkConfigurationShowFailsBeforeOutputForInvalidFinalDefinition(t *testing.T) {
root := t.TempDir()
frameworkFile := writeFrameworkSourceFile(t, root, "invalid.yml", `prompts:
- id: unused
messages:
- role: user
content: "{{"
output:
format: text
validation_mode: none
`)
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
code, stdout, stderr := runCLICommand(t, configCommand, []string{"validate", "--config", configPath})
if code != ExitOK || stdout != "" || stderr != "" {
t.Fatalf("application validation loaded framework definitions: code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
for _, args := range [][]string{
{"configuration", "validate", "--config", configPath},
{"configuration", "show", "--config", configPath},
{"configuration", "sources", "--config", configPath},
{"configuration", "explain", "--config", configPath, "--path", ""},
} {
code, stdout, stderr = runCLICommand(t, inspectCommand, args)
if code != ExitRuntimeError || stdout != "" || stderr == "" {
t.Fatalf("invalid final framework definition was reported as success: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
}
}
}
func TestFrameworkConfigurationCommandsRejectExtraArgumentsAndReportWriterErrors(t *testing.T) {
configPath := writeAppConfigFile(t, "{}\n")
for _, args := range [][]string{
{"configuration"},
{"configuration", "explain"},
{"configuration", "show", "unexpected"},
{"configuration", "sources", "--format", "json"},
} {
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
if code != ExitRuntimeError || stdout != "" || stderr == "" {
t.Fatalf("invalid inspection arguments were accepted: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
}
}
writerError := errors.New("synthetic framework output failure")
var stderr bytes.Buffer
code := inspectCommand([]string{"configuration", "show", "--config", configPath}, frameworkConfigurationFailingWriter{err: writerError}, &stderr)
if code != ExitRuntimeError || !strings.Contains(stderr.String(), writerError.Error()) {
t.Fatalf("effective-output writer failure was not reported: code=%d stderr=%q", code, stderr.String())
}
stderr.Reset()
code = inspectCommand([]string{"configuration", "explain", "--config", configPath, "--path", ""}, frameworkConfigurationFailingWriter{err: writerError}, &stderr)
if code != ExitRuntimeError || !strings.Contains(stderr.String(), writerError.Error()) {
t.Fatalf("explanation writer failure was not reported: code=%d stderr=%q", code, stderr.String())
}
}
func TestFrameworkConfigurationExplainUsesLiteralJSONPointersAndNativeHistory(t *testing.T) {
root := t.TempDir()
lower := writeFrameworkSourceFile(t, root, "lower.yml", `collections:
support:
backends:
- id: local
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
extra_params:
token: backend-token-displaced-canary
password: backend-password-canary
visible_option: backend-visible-value
provider.option: dotted-visible-value
profiles:
- id: summary
backend: support/local
model: lower-model
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
extra_params:
token: profile-token-displaced-canary
password: profile-password-displaced-canary
visible_option: profile-visible-value
provider.option: dotted-visible-value
prompts:
- id: explainable
default_profile: support/summary
messages:
- role: user
content: hello
output:
format: text
validation_mode: none
`)
upperRoot := t.TempDir()
upper := writeFrameworkSourceFile(t, upperRoot, "upper.yml", `collections:
support:
backends:
- id: local
endpoint: http://127.0.0.1:1/v1
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
extra_params:
token: backend-token-effective-canary
password: backend-password-effective-canary
visible_option: backend-visible-value
provider.option: dotted-visible-value
profiles:
- id: summary
backend: support/local
model: effective-model
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
extra_params:
token: profile-token-effective-canary
password: profile-password-effective-canary
visible_option: profile-visible-value
provider.option: dotted-visible-value
`)
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n - file: %q\n", lower, upper))
const secret = "environment-value-must-never-be-emitted"
t.Setenv("SCRIPTORIUM_EXPLAIN_REFERENCE", secret)
for _, tc := range []struct {
path string
want []string
unwant []string
}{
{
path: "/collections/support/backends/0/extra_params/token",
unwant: []string{"backend-token-displaced-canary", "backend-token-effective-canary"},
},
{
path: "/collections/support/backends/0/extra_params/password",
unwant: []string{"backend-password-displaced-canary", "backend-password-effective-canary"},
},
{
path: "/collections/support/profiles/0/model",
want: []string{"effective-model", "lower-model"},
unwant: []string{},
},
{
path: "/collections/support/profiles/0/extra_params/token",
unwant: []string{"profile-token-displaced-canary", "profile-token-effective-canary"},
},
{
path: "/collections/support/profiles/0/extra_params/password",
unwant: []string{"profile-password-displaced-canary", "profile-password-effective-canary"},
},
{
path: "/collections/support/profiles/0/api_key_env",
want: []string{"SCRIPTORIUM_EXPLAIN_REFERENCE"},
unwant: []string{secret},
},
{
path: "/collections/support/profiles/0/extra_params/provider.option",
want: []string{"dotted-visible-value"},
unwant: []string{"provider/option"},
},
{
path: "",
want: []string{"profiles:", "effective-model"},
unwant: []string{"profile-token-displaced-canary", "backend-password-effective-canary"},
},
} {
args := []string{"configuration", "explain", "--config", configPath, "--path", tc.path}
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
if code != ExitOK || stderr != "" {
t.Fatalf("explain %q failed: code=%d stdout=%q stderr=%q", tc.path, code, stdout, stderr)
}
if stdout == "" {
t.Fatalf("explain %q produced no output", tc.path)
}
for _, value := range tc.want {
if !strings.Contains(stdout, value) {
t.Errorf("explain %q omitted %q: %s", tc.path, value, stdout)
}
}
for _, value := range tc.unwant {
if strings.Contains(stdout, value) {
t.Errorf("explain %q disclosed %q: %s", tc.path, value, stdout)
}
}
if strings.Contains(stdout, secret) {
t.Errorf("explain %q disclosed the resolved environment value: %s", tc.path, stdout)
}
}
code, stdout, stderr := runCLICommand(t, inspectCommand, []string{"configuration", "show", "--config", configPath})
if code != ExitOK || stderr != "" {
t.Fatalf("framework show failed: code=%d stderr=%q", code, stderr)
}
for _, value := range []string{"SCRIPTORIUM_EXPLAIN_REFERENCE", "backend-visible-value", "profile-visible-value", "dotted-visible-value"} {
if !strings.Contains(stdout, value) {
t.Errorf("effective report omitted visible configuration %q: %s", value, stdout)
}
}
for _, value := range []string{
"backend-token-displaced-canary", "backend-token-effective-canary",
"backend-password-displaced-canary", "backend-password-effective-canary",
"profile-token-displaced-canary", "profile-token-effective-canary",
"profile-password-displaced-canary", "profile-password-effective-canary", secret,
} {
if strings.Contains(stdout, value) {
t.Errorf("effective report disclosed classified or resolved value %q: %s", value, stdout)
}
}
profileCode, profileOutput, profileError := runCLICommand(t, inspectCommand, []string{
"profile", "--config", configPath, "--profile", "support/summary", "--format", "json",
})
if profileCode != ExitOK || profileError != "" {
t.Fatalf("existing profile inspection failed: code=%d stdout=%q stderr=%q", profileCode, profileOutput, profileError)
}
var profile renderformat.ProfileInspection
if err := json.Unmarshal([]byte(profileOutput), &profile); err != nil {
t.Fatalf("decode profile inspection: %v\n%s", err, profileOutput)
}
if pointerValue(profile.ProfileModelParams.Model) != "effective-model" || pointerValue(profile.ProfileModelParams.ExtraParams)["visible_option"] != "profile-visible-value" {
t.Fatalf("existing profile inspection changed configured provider data: %+v", profile.ProfileModelParams)
}
if strings.Contains(profileOutput, secret) {
t.Fatalf("profile inspection emitted resolved environment data: %s", profileOutput)
}
code, rendered, stderr := runCLICommand(t, renderCommand, []string{"--config", configPath, "--prompt", "support/explainable"})
if code != ExitOK || stderr != "" {
t.Fatalf("prepared output failed: code=%d stdout=%q stderr=%q", code, rendered, stderr)
}
if !strings.Contains(rendered, "profile-visible-value") || strings.Contains(rendered, secret) {
t.Fatalf("prepared output did not preserve ordinary provider data or disclosed environment data: %s", rendered)
}
}
func TestFrameworkConfigurationExplainRejectsMissingMalformedAndUnknownPaths(t *testing.T) {
configPath := writeAppConfigFile(t, "{}\n")
for _, args := range [][]string{
{"configuration", "explain"},
{"configuration", "explain", "--path", "not-a-pointer"},
{"configuration", "explain", "--path", "/profiles/team~2summary/model"},
{"configuration", "explain", "--config", configPath, "--path", "/profiles/missing/model"},
} {
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
if code != ExitRuntimeError || stdout != "" || stderr == "" {
t.Fatalf("invalid explanation path was accepted: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
}
}
}
func findFrameworkSource(t *testing.T, sources []frameworkConfigurationSource, path string) int {
t.Helper()
for index, source := range sources {
if filepath.Clean(source.Path) == filepath.Clean(path) {
return index
}
}
t.Fatalf("selected source path %q was not present: %+v", path, sources)
return -1
}
type frameworkConfigurationFailingWriter struct {
err error
}
func (writer frameworkConfigurationFailingWriter) Write([]byte) (int, error) {
return 0, writer.err
}

View File

@@ -0,0 +1,75 @@
package cli
import (
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
type promptKitSourceFlagEntry struct {
selector string
path string
}
// promptKitSourceFlagValue treats each occurrence as one selected source path.
type promptKitSourceFlagValue struct {
entries []promptKitSourceFlagEntry
}
func (value *promptKitSourceFlagValue) Set(path string) error {
trimmed := strings.TrimSpace(path)
if trimmed == "" {
return errors.New("--promptkit-source requires a nonblank path")
}
info, err := os.Stat(filepath.Clean(trimmed))
if err != nil {
reason := "unavailable"
if errors.Is(err, os.ErrPermission) {
reason = "permission denied"
}
return fmt.Errorf("--promptkit-source %q: %s", path, reason)
}
selector := ""
switch {
case info.IsDir():
selector = "directory"
case info.Mode().IsRegular():
selector = "file"
default:
return fmt.Errorf("--promptkit-source %q must be a regular file or directory", path)
}
value.entries = append(value.entries, promptKitSourceFlagEntry{selector: selector, path: path})
return nil
}
func (value *promptKitSourceFlagValue) Get() any {
selections := make([]any, 0, len(value.entries))
for _, entry := range value.entries {
selections = append(selections, map[string]any{entry.selector: entry.path})
}
return selections
}
func (value *promptKitSourceFlagValue) String() string {
paths := make([]string, 0, len(value.entries))
for _, entry := range value.entries {
paths = append(paths, entry.path)
}
return fmt.Sprint(paths)
}
func writeFrameworkDiagnostics(output io.Writer, engine *promptkit.Engine) error {
view, err := engine.InspectConfiguration()
if err != nil {
return fmt.Errorf("inspect captured PromptKit diagnostics: %w", err)
}
return configkit.WriteDiagnostics(output, view.Diagnostics())
}

View File

@@ -0,0 +1,386 @@
package cli
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"reflect"
"testing"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
configkit "go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
)
func TestFrameworkSourceGroupsComposeAndValidateEffectiveDefinitions(t *testing.T) {
conflicting := t.TempDir()
writeFrameworkSourceFile(t, conflicting, "first.yml", `profiles:
- id: selected
model: first
`)
writeFrameworkSourceFile(t, conflicting, "second.yml", `profiles:
- id: selected
model: second
`)
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{Directory: conflicting}}}); err == nil {
t.Fatal("conflicting files in one source group unexpectedly constructed an engine")
}
lower := t.TempDir()
upper := t.TempDir()
empty := t.TempDir()
writeFrameworkSourceFile(t, lower, "lower.yml", `profiles:
- id: selected
endpoint: not-a-url
model: lower-model
temperature: 10
`)
writeFrameworkSourceFile(t, upper, "upper.yml", `profiles:
- id: selected
endpoint: http://127.0.0.1:1/v1
model: upper-model
temperature: 0.5
`)
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{
{Directory: lower}, {Directory: empty}, {Directory: upper},
}, "")
inspection, err := engine.InspectProfile(context.Background(), "selected")
if err != nil {
t.Fatalf("inspect profile after later source replacement: %v", err)
}
if pointerValue(inspection.Endpoint) != "http://127.0.0.1:1/v1" || pointerValue(inspection.Model) != "upper-model" || pointerValue(inspection.Temperature) != 0.5 {
t.Fatalf("later source did not replace lower values before validation: %+v", inspection)
}
}
func TestFrameworkSourceConstructionUsesCombinedDocumentAndRejectsInvalidSources(t *testing.T) {
root := t.TempDir()
combined := filepath.Join(root, "combined.yml")
writeFrameworkSourceFile(t, root, "combined.yml", `backends:
- id: local
endpoint: http://127.0.0.1:1/v1
profiles:
- id: selected
backend: local
model: combined-model
prompts:
- id: combined.prompt
default_profile: selected
messages:
- role: user
content: hello
output:
format: text
validation_mode: none
`)
client := &frameworkSourceCaptureClient{}
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{{File: combined}}, "", promptkit.WithLLMClient(client))
if _, err := engine.Run(context.Background(), promptkit.RunRequest{PromptID: "combined.prompt"}); err != nil {
t.Fatalf("run definitions from one combined document: %v", err)
}
if len(client.requests) != 1 || client.requests[0].Target.BackendID != "local" || client.requests[0].Target.Model != "combined-model" {
t.Fatalf("combined backend/profile/prompt values did not reach generation: %+v", client.requests)
}
malformed := filepath.Join(root, "malformed.yml")
writeFrameworkSourceFile(t, root, "malformed.yml", "not: [valid\n")
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: malformed}}}); err == nil {
t.Fatal("malformed framework source unexpectedly constructed an engine")
}
invalidUnused := filepath.Join(root, "invalid-unused.yml")
writeFrameworkSourceFile(t, root, "invalid-unused.yml", `prompts:
- id: unused.prompt
messages:
- role: user
content: "{{"
output:
format: text
validation_mode: none
`)
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: invalidUnused}}}); !errors.Is(err, promptkit.ErrInvalidConfig) {
t.Fatalf("invalid unused definition did not fail as framework configuration: %v", err)
}
}
func TestFrameworkRejectsObsoleteVersionKeyedPrompt(t *testing.T) {
root := t.TempDir()
path := writeFrameworkSourceFile(t, root, "obsolete.yml", `prompts:
old-prompt:
"1":
messages:
- role: user
content: hello
output:
format: text
validation_mode: none
`)
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: path}}}); !errors.Is(err, promptkit.ErrInvalidConfig) {
t.Fatalf("obsolete version-keyed definition was not rejected by PromptKit: %v", err)
}
}
func TestFrameworkImportsRetainResourceOriginsAndCaptureAtConstruction(t *testing.T) {
root := t.TempDir()
catalogDir := filepath.Join(root, "catalog")
if err := os.MkdirAll(catalogDir, 0o755); err != nil {
t.Fatal(err)
}
schemaDir := filepath.Join(root, "schemas")
if err := os.MkdirAll(schemaDir, 0o755); err != nil {
t.Fatal(err)
}
mainFile := filepath.Join(root, "main.yml")
writeFrameworkSourceFile(t, root, "main.yml", `config:
imports:
- path: catalog/base.yml
required: true
`)
writeFrameworkSourceFile(t, catalogDir, "base.yml", `profiles:
- id: profile-primary
endpoint: http://127.0.0.1:1/v1
model: imported-model
prompts:
- id: team-prompt
default_profile: profile-primary
inputs:
- name: source
required: true
messages:
- role: user
content_file: ./body.md
- role: user
content: 'Artifact: {{input "source"}}'
output:
format: json
validation_mode: json_schema
schema_path: response.schema.json
`)
writeFrameworkSourceFile(t, catalogDir, "body.md", "Captured message for {{.audience}}")
artifactPath := filepath.Join(root, "request-artifact.txt")
writeFrameworkSourceFile(t, root, "request-artifact.txt", "initial artifact")
writeFrameworkSourceFile(t, schemaDir, "response.schema.json", `{"type":"object","title":"initial schema"}`)
selections := []appconfig.SourceSelection{{File: mainFile}}
engine := newFrameworkSourceTestEngine(t, selections, schemaDir)
writeFrameworkSourceFile(t, catalogDir, "body.md", "edited message for {{.audience}}")
writeFrameworkSourceFile(t, root, "request-artifact.txt", "prepared artifact")
writeFrameworkSourceFile(t, schemaDir, "response.schema.json", `{"type":"object","title":"prepared schema"}`)
prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
PromptID: "team-prompt",
Inputs: map[string]promptkit.ArtifactRef{"source": promptkit.File(artifactPath)},
Vars: map[string]string{"audience": "reader"},
})
if err != nil {
t.Fatalf("prepare inherited imported prompt: %v", err)
}
if len(prepared.Messages) != 2 || prepared.Messages[0].Content != "Captured message for reader" || prepared.Messages[1].Content != "Artifact: prepared artifact" {
t.Fatalf("resource origin or capture/preparation behavior changed: %+v", prepared.Messages)
}
if prepared.SelectedProfileID != "profile-primary" {
t.Fatalf("profile ID was not preserved: %+v", prepared)
}
if prepared.StructuredOutput == nil || prepared.StructuredOutput.JSONSchema == nil || prepared.StructuredOutput.JSONSchema.Schema.(map[string]any)["title"] != "prepared schema" {
t.Fatalf("schema was not loaded during preparation: %+v", prepared.StructuredOutput)
}
newEngine := newFrameworkSourceTestEngine(t, selections, schemaDir)
newPrepared, err := newEngine.Prepare(context.Background(), promptkit.RunRequest{
PromptID: "team-prompt",
Inputs: map[string]promptkit.ArtifactRef{"source": promptkit.File(artifactPath)},
Vars: map[string]string{"audience": "reader"},
})
if err != nil {
t.Fatalf("prepare with newly captured message: %v", err)
}
if newPrepared.Messages[0].Content != "edited message for reader" {
t.Fatalf("new engine did not observe the message edit: %+v", newPrepared.Messages[0])
}
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\nschema_dir: %q\n", mainFile, schemaDir))
code, stdout, stderr := runCLICommand(t, renderCommand, []string{
"--config", configPath,
"--prompt", "team-prompt",
"--input", "source=" + artifactPath,
"--var", "audience=reader",
"--format", "json",
})
if code != ExitOK {
t.Fatalf("render exact literal IDs through CLI: code=%d stderr=%q", code, stderr)
}
var rendered promptkit.PreparedRun
if err := json.Unmarshal([]byte(stdout), &rendered); err != nil {
t.Fatalf("decode rendered literal-ID fixture: %v", err)
}
if rendered.PromptID != "team-prompt" || rendered.SelectedProfileID != "profile-primary" {
t.Fatalf("CLI changed exact prompt/profile IDs: %+v", rendered)
}
}
func TestNativeProfileInheritanceAndPresenceReachTheClientBoundary(t *testing.T) {
root := t.TempDir()
frameworkFile := filepath.Join(root, "framework.yml")
writeFrameworkSourceFile(t, root, "framework.yml", `backends:
- id: first
endpoint: https://first.example/v1
api_key_env: FIRST_BACKEND_KEY
extra_params:
source: first
nested:
first_backend: true
- id: second
endpoint: https://second.example/v1
api_key_env: SECOND_BACKEND_KEY
extra_params:
source: second
nested:
second_backend: true
profiles:
- id: parent
backend: first
model: parent-model
temperature: 0.7
top_p: 0.6
max_tokens: 45
timeout_seconds: 30
service_tier: flex
extra_params:
nested:
parent_profile: true
retained: "yes"
- id: backend-child
extends: {id: parent}
backend: second
model: child-model
- id: presence-child
extends: {id: parent}
backend: second
api_key_env: null
temperature: null
max_tokens: 0
timeout_seconds: 0
extra_params:
nested:
explicit_false: false
- id: map-null
backend: second
model: map-model
extra_params: null
- id: map-empty
backend: second
model: map-model
extra_params: {}
prompts:
- id: execution.prompt
messages:
- role: user
content: hello
output:
format: text
validation_mode: none
`)
client := &frameworkSourceCaptureClient{}
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{{File: frameworkFile}}, "", promptkit.WithLLMClient(client))
for _, profileID := range []string{"backend-child", "presence-child", "map-null", "map-empty"} {
if _, err := engine.Run(context.Background(), promptkit.RunRequest{PromptID: "execution.prompt", ProfileID: profileID}); err != nil {
t.Fatalf("run profile %q: %v", profileID, err)
}
}
if len(client.requests) != 4 {
t.Fatalf("expected four provider-bound requests, got %d", len(client.requests))
}
backendChild := client.requests[0].Target
wantBackendParams := map[string]any{"source": "second", "nested": map[string]any{
"second_backend": true, "parent_profile": true, "retained": "yes",
}}
if backendChild.BackendID != "second" || backendChild.Endpoint != "https://second.example/v1" || backendChild.APIKeyEnv != "SECOND_BACKEND_KEY" || backendChild.Model != "child-model" ||
backendChild.Temperature != 0.7 || backendChild.TopP != 0.6 || backendChild.MaxTokens != 45 || backendChild.TimeoutSeconds != 30 || backendChild.ServiceTier != "flex" || !reflect.DeepEqual(backendChild.ExtraParams, wantBackendParams) {
t.Fatalf("backend change lost backend-derived or explicit inherited values: %+v", backendChild)
}
presenceRequest := client.requests[1]
presenceTarget := presenceRequest.Target
if presenceTarget.APIKeyEnv != "SECOND_BACKEND_KEY" || presenceTarget.Temperature != 0 || presenceTarget.MaxTokens != 0 || presenceTarget.TimeoutSeconds != 0 ||
!presenceRequest.TargetPresence.MaxTokens || !presenceRequest.TargetPresence.TimeoutSeconds || presenceRequest.TargetPresence.Temperature || !presenceRequest.TargetPresence.TopP {
t.Fatalf("explicit null/zero presence did not reach the injected client: target=%+v presence=%+v", presenceTarget, presenceRequest.TargetPresence)
}
wantPresenceParams := map[string]any{"source": "second", "nested": map[string]any{
"second_backend": true, "parent_profile": true, "retained": "yes", "explicit_false": false,
}}
if !reflect.DeepEqual(presenceTarget.ExtraParams, wantPresenceParams) {
t.Fatalf("recursive provider-map retention changed: %#v", presenceTarget.ExtraParams)
}
if !reflect.DeepEqual(client.requests[2].Target.ExtraParams, map[string]any{"source": "second", "nested": map[string]any{"second_backend": true}}) {
t.Fatalf("whole-map null did not fall back to backend defaults: %#v", client.requests[2].Target.ExtraParams)
}
if !reflect.DeepEqual(client.requests[3].Target.ExtraParams, map[string]any{"source": "second", "nested": map[string]any{"second_backend": true}}) {
t.Fatalf("empty provider map unexpectedly cleared backend defaults: %#v", client.requests[3].Target.ExtraParams)
}
}
func TestCLICompletesPartialFrameworkProfileWithRequestOverrides(t *testing.T) {
root := t.TempDir()
frameworkFile := writeFrameworkSourceFile(t, root, "partial.yml", `profiles:
- id: partial
prompts:
- id: partial.prompt
default_profile: partial
messages:
- role: user
content: hello
output:
format: text
validation_mode: none
`)
provider := newTestLLMServer("completed partial profile", nil)
defer provider.Close()
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
code, stdout, stderr := runCLICommand(t, runCommand, []string{
"--config", configPath,
"--prompt", "partial.prompt",
"--llm-base-url", provider.URL + "/v1",
"--model", "request-model",
})
if code != ExitOK || stdout != "completed partial profile" {
t.Fatalf("request overrides did not complete the partial profile: code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
}
func newFrameworkSourceTestEngine(t *testing.T, selections []appconfig.SourceSelection, schemaDir string, options ...promptkit.Option) *promptkit.Engine {
t.Helper()
engine, err := newEngine(engineSettings{promptkitSources: selections, schemaDir: schemaDir}, options...)
if err != nil {
var loadError *configkit.LoadError
if errors.As(err, &loadError) {
t.Fatalf("construct engine from selected framework sources: %v (%+v)", err, loadError.Diagnostics())
}
t.Fatalf("construct engine from selected framework sources: %v", err)
}
return engine
}
func writeFrameworkSourceFile(t *testing.T, directory, name, contents string) string {
t.Helper()
if err := os.MkdirAll(directory, 0o755); err != nil {
t.Fatalf("create framework source directory: %v", err)
}
path := filepath.Join(directory, name)
if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
t.Fatalf("write framework source %q: %v", path, err)
}
return path
}
type frameworkSourceCaptureClient struct {
requests []promptkit.GenerateRequest
}
func (client *frameworkSourceCaptureClient) Generate(_ context.Context, request promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
client.requests = append(client.requests, request)
return &promptkit.GenerateResponse{Content: "ok"}, nil
}

View File

@@ -6,17 +6,15 @@ import (
"flag" "flag"
"fmt" "fmt"
"io" "io"
"io/fs"
"path/filepath" "path/filepath"
"strings" "strings"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/promptkit"
appformat "gitea.maximumdirect.net/eric/scriptorium/internal/format" appformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
"go.maximumdirect.net/configkit"
) )
type promptInspectionConfig struct { type promptInspectionConfig struct {
configPath, promptDir, promptID, promptVersion, outputPath string configPath, promptID, schemaDir, outputPath string
configOverlay string configOverlay string
configExplicit bool configExplicit bool
outputFormat appformat.OutputFormat outputFormat appformat.OutputFormat
@@ -25,7 +23,7 @@ type promptInspectionConfig struct {
} }
type profileInspectionConfig struct { type profileInspectionConfig struct {
configPath, profileDir, profileID, outputPath string configPath, profileID, schemaDir, outputPath string
configOverlay string configOverlay string
configExplicit bool configExplicit bool
outputFormat appformat.OutputFormat outputFormat appformat.OutputFormat
@@ -33,15 +31,6 @@ type profileInspectionConfig struct {
diagnostics []configkit.Diagnostic diagnostics []configkit.Diagnostic
} }
// emptyPromptDefinitionFS satisfies Promptkit's engine-level prompt-source
// requirement without exposing the caller's working directory. Profile
// inspection never reads this source.
type emptyPromptDefinitionFS struct{}
func (emptyPromptDefinitionFS) Open(name string) (fs.File, error) {
return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
}
func inspectCommand(args []string, stdout, stderr io.Writer) int { func inspectCommand(args []string, stdout, stderr io.Writer) int {
if len(args) == 0 { if len(args) == 0 {
fmt.Fprintln(stderr, "inspect parse error: inspection mode is required") fmt.Fprintln(stderr, "inspect parse error: inspection mode is required")
@@ -50,6 +39,9 @@ func inspectCommand(args []string, stdout, stderr io.Writer) int {
if args[0] == "profile" { if args[0] == "profile" {
return inspectProfileCommand(args[1:], stdout, stderr) return inspectProfileCommand(args[1:], stdout, stderr)
} }
if args[0] == "configuration" {
return inspectFrameworkConfigurationCommand(args[1:], stdout, stderr)
}
if args[0] != "prompt" { if args[0] != "prompt" {
fmt.Fprintln(stderr, "inspect parse error: unknown inspection mode") fmt.Fprintln(stderr, "inspect parse error: unknown inspection mode")
return ExitRuntimeError return ExitRuntimeError
@@ -69,10 +61,14 @@ func inspectCommand(args []string, stdout, stderr io.Writer) int {
} }
engine, err := newEngine(settings) engine, err := newEngine(settings)
if err != nil { if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err) writeApplicationError(stderr, "engine", err)
return ExitRuntimeError return ExitRuntimeError
} }
inspection, err := engine.InspectPrompt(context.Background(), cfg.promptID, cfg.promptVersion) if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
return ExitRuntimeError
}
inspection, err := engine.InspectPrompt(context.Background(), cfg.promptID)
if err != nil { if err != nil {
fmt.Fprintf(stderr, "inspect error: %v\n", err) fmt.Fprintf(stderr, "inspect error: %v\n", err)
return ExitRuntimeError return ExitRuntimeError
@@ -103,9 +99,13 @@ func inspectProfileCommand(args []string, stdout, stderr io.Writer) int {
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil { if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
return ExitRuntimeError return ExitRuntimeError
} }
engine, err := newEngine(settings, promptkit.WithPromptFS(emptyPromptDefinitionFS{}, ".")) engine, err := newEngine(settings)
if err != nil { if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err) writeApplicationError(stderr, "engine", err)
return ExitRuntimeError
}
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
return ExitRuntimeError return ExitRuntimeError
} }
inspection, err := engine.InspectProfile(context.Background(), cfg.profileID) inspection, err := engine.InspectProfile(context.Background(), cfg.profileID)
@@ -130,7 +130,9 @@ func parseProfileInspectionArgs(args []string) (*profileInspectionConfig, error)
fs := flag.NewFlagSet("inspect profile", flag.ContinueOnError) fs := flag.NewFlagSet("inspect profile", flag.ContinueOnError)
fs.SetOutput(io.Discard) fs.SetOutput(io.Discard)
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay) registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profiles") var promptkitSources promptKitSourceFlagValue
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
fs.StringVar(&cfg.profileID, "profile", "", "profile ID to inspect") fs.StringVar(&cfg.profileID, "profile", "", "profile ID to inspect")
rawFormat := "" rawFormat := ""
fs.StringVar(&rawFormat, "format", "", "output format: text or json") fs.StringVar(&rawFormat, "format", "", "output format: text or json")
@@ -163,7 +165,7 @@ func resolveAppSettingsForProfileInspection(cfg *profileInspectionConfig) (engin
return engineSettings{}, err return engineSettings{}, err
} }
cfg.diagnostics = diagnostics cfg.diagnostics = diagnostics
return engineSettings{profileDir: settings.ProfileDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil return engineSettings{promptkitSources: settings.PromptKitSources, schemaDir: settings.SchemaDir, transientRetries: settings.TransientRetries}, nil
} }
func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) { func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
@@ -171,9 +173,10 @@ func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
fs := flag.NewFlagSet("inspect prompt", flag.ContinueOnError) fs := flag.NewFlagSet("inspect prompt", flag.ContinueOnError)
fs.SetOutput(io.Discard) fs.SetOutput(io.Discard)
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay) registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definitions") var promptkitSources promptKitSourceFlagValue
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to inspect") fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to inspect")
fs.StringVar(&cfg.promptVersion, "prompt-version", "", "optional prompt version")
rawFormat := "" rawFormat := ""
fs.StringVar(&rawFormat, "format", "", "output format: text or json") fs.StringVar(&rawFormat, "format", "", "output format: text or json")
fs.StringVar(&cfg.outputPath, "out", "", "optional output file path") fs.StringVar(&cfg.outputPath, "out", "", "optional output file path")
@@ -205,8 +208,5 @@ func resolveAppSettingsForPromptInspection(cfg *promptInspectionConfig) (engineS
return engineSettings{}, err return engineSettings{}, err
} }
cfg.diagnostics = diagnostics cfg.diagnostics = diagnostics
if strings.TrimSpace(settings.PromptDir) == "" { return engineSettings{promptkitSources: settings.PromptKitSources, schemaDir: settings.SchemaDir, transientRetries: settings.TransientRetries}, nil
return engineSettings{}, errors.New(errPromptDirRequired)
}
return engineSettings{promptDir: settings.PromptDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil
} }

View File

@@ -13,13 +13,13 @@ import (
"strings" "strings"
"time" "time"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/promptkit"
httpadapter "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http" httpadapter "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config" appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults" "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format" renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report" executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
) )
const ( const (
@@ -28,17 +28,11 @@ const (
ExitValidationFailed = 2 ExitValidationFailed = 2
) )
const (
errPromptDirRequired = "prompt directory is required; provide --prompt-dir or config.yml prompt_dir"
)
type runConfig struct { type runConfig struct {
configPath string configPath string
promptDir string promptkitSources []appconfig.SourceSelection
profileDir string
promptID string promptID string
promptVersion string
profileID string profileID string
sessionID string sessionID string
inputRaw listFlag inputRaw listFlag
@@ -53,7 +47,6 @@ type runConfig struct {
topP float64 topP float64
reasoningEffort string reasoningEffort string
schemaDir string schemaDir string
backends []appconfig.BackendSettings
timeout time.Duration timeout time.Duration
runTimeout time.Duration runTimeout time.Duration
transientRetries int transientRetries int
@@ -83,22 +76,19 @@ type serveConfig struct {
configPath string configPath string
addr string addr string
promptDir string promptkitSources []appconfig.SourceSelection
profileDir string
schemaDir string schemaDir string
artifactRoot string artifactRoot string
maxRequestBytes int64 maxRequestBytes int64
maxArtifactBytes int64 maxArtifactBytes int64
maxResponseBytes int64 maxResponseBytes int64
backends []appconfig.BackendSettings
transientRetries *int transientRetries *int
diagnostics []configkit.Diagnostic diagnostics []configkit.Diagnostic
configOverlay string configOverlay string
} }
type commonCommandSettings struct { type commonCommandSettings struct {
promptDir string promptkitSources []appconfig.SourceSelection
profileDir string
schemaDir string schemaDir string
serverAddr string serverAddr string
artifactRoot string artifactRoot string
@@ -106,7 +96,6 @@ type commonCommandSettings struct {
maxArtifactBytes int64 maxArtifactBytes int64
maxResponseBytes int64 maxResponseBytes int64
defaultRenderFormat renderformat.PreparedRunOutputFormat defaultRenderFormat renderformat.PreparedRunOutputFormat
backends []appconfig.BackendSettings
transientRetries *int transientRetries *int
diagnostics []configkit.Diagnostic diagnostics []configkit.Diagnostic
} }
@@ -164,7 +153,11 @@ func runCommand(args []string, stdout, stderr io.Writer) int {
engine, err := newEngine(cfg.engineSettings()) engine, err := newEngine(cfg.engineSettings())
if err != nil { if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err) writeApplicationError(stderr, "engine", err)
return ExitRuntimeError
}
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
return ExitRuntimeError return ExitRuntimeError
} }
return executeRun(cfg, req, engine.Run, stdout, stderr) return executeRun(cfg, req, engine.Run, stdout, stderr)
@@ -176,16 +169,10 @@ func executeRun(cfg *runConfig, req promptkit.RunRequest, run func(context.Conte
collector = executionreport.NewCollector() collector = executionreport.NewCollector()
req.Observer = collector.Observe req.Observer = collector.Observe
} }
runContext := context.Background() req.OperationTimeout = cfg.runTimeout
cancel := func() {} res, runErr := run(context.Background(), req)
if cfg.runTimeout > 0 {
runContext, cancel = context.WithTimeout(runContext, cfg.runTimeout)
}
res, runErr := run(runContext, req)
contextErr := runContext.Err()
cancel()
if runErr != nil { if runErr != nil {
if errors.Is(contextErr, context.DeadlineExceeded) { if errors.Is(runErr, promptkit.ErrOperationTimeout) {
fmt.Fprintln(stderr, "run error: execution deadline exceeded") fmt.Fprintln(stderr, "run error: execution deadline exceeded")
} else { } else {
fmt.Fprintln(stderr, runErrorMessage(runErr)) fmt.Fprintln(stderr, runErrorMessage(runErr))
@@ -242,7 +229,11 @@ func renderCommand(args []string, stdout, stderr io.Writer) int {
engine, err := newEngine(cfg.runConfig.engineSettings()) engine, err := newEngine(cfg.runConfig.engineSettings())
if err != nil { if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err) writeApplicationError(stderr, "engine", err)
return ExitRuntimeError
}
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
return ExitRuntimeError return ExitRuntimeError
} }
@@ -283,7 +274,11 @@ func serveCommand(args []string, stderr io.Writer) int {
engine, err := newEngine(cfg.engineSettings(), promptkit.WithArtifactReader(artifactReader)) engine, err := newEngine(cfg.engineSettings(), promptkit.WithArtifactReader(artifactReader))
if err != nil { if err != nil {
fmt.Fprintf(stderr, "engine error: %v\n", err) writeApplicationError(stderr, "engine", err)
return ExitRuntimeError
}
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
return ExitRuntimeError return ExitRuntimeError
} }
@@ -400,8 +395,8 @@ func parseServeArgs(args []string) (*serveConfig, error) {
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay) registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
fs.StringVar(&cfg.addr, "addr", "", "HTTP listen address") fs.StringVar(&cfg.addr, "addr", "", "HTTP listen address")
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definition YAML files") var promptkitSources promptKitSourceFlagValue
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profile YAML files") fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas") fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
fs.StringVar(&cfg.artifactRoot, "artifact-root", "", "base directory for HTTP file input artifacts") fs.StringVar(&cfg.artifactRoot, "artifact-root", "", "base directory for HTTP file input artifacts")
fs.Int64Var(&cfg.maxRequestBytes, "max-request-bytes", 0, "maximum HTTP request body bytes; 0 disables the limit") fs.Int64Var(&cfg.maxRequestBytes, "max-request-bytes", 0, "maximum HTTP request body bytes; 0 disables the limit")
@@ -420,30 +415,23 @@ func parseServeArgs(args []string) (*serveConfig, error) {
return nil, err return nil, err
} }
cfg.promptDir = settings.promptDir cfg.promptkitSources = settings.promptkitSources
cfg.profileDir = settings.profileDir
cfg.schemaDir = settings.schemaDir cfg.schemaDir = settings.schemaDir
cfg.addr = settings.serverAddr cfg.addr = settings.serverAddr
cfg.artifactRoot = settings.artifactRoot cfg.artifactRoot = settings.artifactRoot
cfg.maxRequestBytes = settings.maxRequestBytes cfg.maxRequestBytes = settings.maxRequestBytes
cfg.maxArtifactBytes = settings.maxArtifactBytes cfg.maxArtifactBytes = settings.maxArtifactBytes
cfg.maxResponseBytes = settings.maxResponseBytes cfg.maxResponseBytes = settings.maxResponseBytes
cfg.backends = settings.backends
cfg.transientRetries = settings.transientRetries cfg.transientRetries = settings.transientRetries
cfg.diagnostics = settings.diagnostics cfg.diagnostics = settings.diagnostics
if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
return nil, err
}
return cfg, nil return cfg, nil
} }
func registerExecutionRequestFlags(fs *flag.FlagSet, cfg *runConfig) { func registerExecutionRequestFlags(fs *flag.FlagSet, cfg *runConfig) {
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definition YAML files") var promptkitSources promptKitSourceFlagValue
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profile YAML files") fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to run") fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to run")
fs.StringVar(&cfg.promptVersion, "prompt-version", "", "optional prompt definition version")
fs.StringVar(&cfg.profileID, "profile", "", "optional execution profile ID; if omitted, prompt default_profile is used") fs.StringVar(&cfg.profileID, "profile", "", "optional execution profile ID; if omitted, prompt default_profile is used")
fs.StringVar(&cfg.sessionID, "session-id", "", "optional session ID") fs.StringVar(&cfg.sessionID, "session-id", "", "optional session ID")
fs.Var(&cfg.inputRaw, "input", "input mapping(s): name=path (repeatable, comma-separated)") fs.Var(&cfg.inputRaw, "input", "input mapping(s): name=path (repeatable, comma-separated)")
@@ -472,17 +460,12 @@ func finalizeExecutionRequestConfig(fs *flag.FlagSet, cfg *runConfig) error {
return err return err
} }
cfg.promptDir = settings.promptDir cfg.promptkitSources = settings.promptkitSources
cfg.profileDir = settings.profileDir
cfg.schemaDir = settings.schemaDir cfg.schemaDir = settings.schemaDir
cfg.defaultRenderFormat = settings.defaultRenderFormat cfg.defaultRenderFormat = settings.defaultRenderFormat
cfg.backends = settings.backends
cfg.configuredTransientRetries = settings.transientRetries cfg.configuredTransientRetries = settings.transientRetries
cfg.diagnostics = settings.diagnostics cfg.diagnostics = settings.diagnostics
if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
return err
}
if strings.TrimSpace(cfg.promptID) == "" { if strings.TrimSpace(cfg.promptID) == "" {
return errors.New("--prompt is required") return errors.New("--prompt is required")
} }
@@ -524,8 +507,7 @@ func resolveCommonSettings(fs *flag.FlagSet, configPath, overlay string) (common
return commonCommandSettings{}, err return commonCommandSettings{}, err
} }
return commonCommandSettings{ return commonCommandSettings{
promptDir: settings.PromptDir, promptkitSources: settings.PromptKitSources,
profileDir: settings.ProfileDir,
schemaDir: settings.SchemaDir, schemaDir: settings.SchemaDir,
serverAddr: settings.ServerAddr, serverAddr: settings.ServerAddr,
artifactRoot: settings.ArtifactRoot, artifactRoot: settings.ArtifactRoot,
@@ -533,54 +515,50 @@ func resolveCommonSettings(fs *flag.FlagSet, configPath, overlay string) (common
maxArtifactBytes: settings.MaxArtifactBytes, maxArtifactBytes: settings.MaxArtifactBytes,
maxResponseBytes: settings.MaxResponseBytes, maxResponseBytes: settings.MaxResponseBytes,
defaultRenderFormat: settings.DefaultRenderFormat, defaultRenderFormat: settings.DefaultRenderFormat,
backends: settings.Backends,
transientRetries: settings.TransientRetries, transientRetries: settings.TransientRetries,
diagnostics: diagnostics, diagnostics: diagnostics,
}, nil }, nil
} }
func validateRequiredLibraryDirs(promptDir string) error {
if strings.TrimSpace(promptDir) == "" {
return errors.New(errPromptDirRequired)
}
return nil
}
type engineSettings struct { type engineSettings struct {
promptDir string promptkitSources []appconfig.SourceSelection
profileDir string
schemaDir string schemaDir string
backends []appconfig.BackendSettings
transientRetries *int transientRetries *int
} }
func (c runConfig) engineSettings() engineSettings { func (c runConfig) engineSettings() engineSettings {
return engineSettings{promptDir: c.promptDir, profileDir: c.profileDir, schemaDir: c.schemaDir, backends: c.backends, transientRetries: c.configuredTransientRetries} return engineSettings{promptkitSources: c.promptkitSources, schemaDir: c.schemaDir, transientRetries: c.configuredTransientRetries}
} }
func (c serveConfig) engineSettings() engineSettings { func (c serveConfig) engineSettings() engineSettings {
return engineSettings{promptDir: c.promptDir, profileDir: c.profileDir, schemaDir: c.schemaDir, backends: c.backends, transientRetries: c.transientRetries} return engineSettings{promptkitSources: c.promptkitSources, schemaDir: c.schemaDir, transientRetries: c.transientRetries}
} }
func newEngine(settings engineSettings, options ...promptkit.Option) (*promptkit.Engine, error) { func newEngine(settings engineSettings, options ...promptkit.Option) (*promptkit.Engine, error) {
engineOptions := make([]promptkit.Option, 0, len(settings.backends)+len(options)) underlays := make([]configkit.Underlay, 0, len(settings.promptkitSources))
for _, configured := range settings.backends { for index, selection := range settings.promptkitSources {
engineOptions = append(engineOptions, promptkit.WithBackend(promptkit.Backend{ var inputs []configkit.Input
ID: configured.ID, switch {
Endpoint: configured.Endpoint, case selection.File != "" && selection.Directory == "":
APIKeyEnv: configured.APIKeyEnv, inputs = []configkit.Input{{Source: configkit.File(selection.File), Imports: true}}
ExtraParams: configured.ExtraParams, case selection.Directory != "" && selection.File == "":
ConcurrencyLimit: configured.ConcurrencyLimit, var err error
QueueCapacity: configured.QueueCapacity, inputs, err = promptkit.DirectoryInputs(selection.Directory)
})) if err != nil {
cause := fmt.Errorf("PromptKit source %d directory %q: %w", index+1, selection.Directory, err)
return nil, fmt.Errorf("engine initialization from application configuration: %w", errors.Join(promptkit.ErrInvalidConfig, cause))
}
default:
cause := fmt.Errorf("PromptKit source %d must select exactly one file or directory", index+1)
return nil, fmt.Errorf("engine initialization from application configuration: %w", errors.Join(promptkit.ErrInvalidConfig, cause))
}
underlays = append(underlays, configkit.Underlay{Inputs: inputs})
} }
engineOptions = append(engineOptions, options...)
engine, err := promptkit.NewEngine(promptkit.Config{ engine, err := promptkit.NewEngine(promptkit.Config{
PromptDir: settings.promptDir, Sources: promptkit.ConfigurationSources{Underlays: underlays},
ProfileDir: settings.profileDir,
SchemaDir: settings.schemaDir, SchemaDir: settings.schemaDir,
TransientRetries: settings.transientRetries, TransientRetries: settings.transientRetries,
}, engineOptions...) }, options...)
if err != nil { if err != nil {
return nil, fmt.Errorf("engine initialization from application configuration: %w", err) return nil, fmt.Errorf("engine initialization from application configuration: %w", err)
} }
@@ -644,7 +622,6 @@ func buildRunRequestFromConfig(cfg *runConfig) (promptkit.RunRequest, error) {
} }
return promptkit.RunRequest{ return promptkit.RunRequest{
PromptID: cfg.promptID, PromptID: cfg.promptID,
PromptVersion: cfg.promptVersion,
ProfileID: cfg.profileID, ProfileID: cfg.profileID,
SessionID: cfg.sessionID, SessionID: cfg.sessionID,
Inputs: inputs, Inputs: inputs,
@@ -723,9 +700,8 @@ func printSummary(stderr io.Writer, res *promptkit.RunResult) {
if res == nil { if res == nil {
return return
} }
fmt.Fprintf(stderr, "prompt=%s@%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d", fmt.Fprintf(stderr, "prompt=%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d",
res.PromptID, res.PromptID,
res.PromptVersion,
res.SelectedProfileID, res.SelectedProfileID,
res.ModelName, res.ModelName,
res.Validation.Status, res.Validation.Status,
@@ -755,10 +731,11 @@ func runErrorMessage(err error) string {
func printUsage(w io.Writer) { func printUsage(w io.Writer) {
fmt.Fprintln(w, "usage: scriptorium <run|render|serve|inspect|config> ...") fmt.Fprintln(w, "usage: scriptorium <run|render|serve|inspect|config> ...")
fmt.Fprintln(w, " run: scriptorium run [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] --prompt ID [--prompt-version VERSION] [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--out path] [--execution-report path] [--timeout 10m] [--run-timeout 10m] [--transient-retries N]") fmt.Fprintln(w, " run: scriptorium run [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] --prompt ID [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--out path] [--execution-report path] [--timeout 10m] [--run-timeout 10m] [--transient-retries N]")
fmt.Fprintln(w, " render: scriptorium render [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] --prompt ID [--prompt-version VERSION] [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--format text|json] [--out path] [--timeout 10m] [--transient-retries N]") fmt.Fprintln(w, " render: scriptorium render [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] --prompt ID [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--format text|json] [--out path] [--timeout 10m] [--transient-retries N]")
fmt.Fprintf(w, " serve: scriptorium serve [--config PATH] [--config-overlay NAME] [--addr %s] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] [--artifact-root DIR] [--max-request-bytes N] [--max-artifact-bytes N] [--max-response-bytes N]\n", defaults.HTTPAddrDefault) fmt.Fprintf(w, " serve: scriptorium serve [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--addr %s] [--schema-dir DIR] [--artifact-root DIR] [--max-request-bytes N] [--max-artifact-bytes N] [--max-response-bytes N]\n", defaults.HTTPAddrDefault)
fmt.Fprintln(w, " inspect prompt: scriptorium inspect prompt --prompt ID [--prompt-version VERSION] [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out path]") fmt.Fprintln(w, " inspect prompt: scriptorium inspect prompt --prompt ID [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out path]")
fmt.Fprintln(w, " inspect profile: scriptorium inspect profile --profile ID [--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out path]") fmt.Fprintln(w, " inspect profile: scriptorium inspect profile --profile ID [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out path]")
fmt.Fprintln(w, " inspect configuration: scriptorium inspect configuration <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--path JSON_POINTER (required for explain)]")
fmt.Fprintln(w, " config: scriptorium config <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [application overrides] [--path /pointer for explain]") fmt.Fprintln(w, " config: scriptorium config <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [application overrides] [--path /pointer for explain]")
} }

File diff suppressed because it is too large Load Diff

View File

@@ -15,7 +15,7 @@ import (
const ( const (
scriptoriumModulePath = "gitea.maximumdirect.net/eric/scriptorium" scriptoriumModulePath = "gitea.maximumdirect.net/eric/scriptorium"
promptkitInternalPath = "gitea.maximumdirect.net/eric/promptkit/internal" promptkitInternalPath = "go.maximumdirect.net/promptkit/internal"
promptkitOpenRouterCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-openrouter" promptkitOpenRouterCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-openrouter"
promptkitRakestrawhomeCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome" promptkitRakestrawhomeCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome"
) )
@@ -149,7 +149,7 @@ func TestForbiddenImportScannerAllowsRetainedApplicationPackages(t *testing.T) {
source := `package consumer source := `package consumer
import ( import (
_ "gitea.maximumdirect.net/eric/promptkit" _ "go.maximumdirect.net/promptkit"
_ "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http" _ "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
_ "gitea.maximumdirect.net/eric/scriptorium/internal/config" _ "gitea.maximumdirect.net/eric/scriptorium/internal/config"
_ "gitea.maximumdirect.net/eric/scriptorium/internal/defaults" _ "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"

View File

@@ -6,12 +6,13 @@ import (
"errors" "errors"
"fmt" "fmt"
"io" "io"
"math"
"mime" "mime"
"os" "os"
"path/filepath" "path/filepath"
"strings" "strings"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/promptkit"
) )
var ( var (
@@ -136,7 +137,11 @@ func readArtifactFile(path string, maxBytes int64) (*promptkit.Artifact, error)
var reader io.Reader = file var reader io.Reader = file
if maxBytes > 0 { if maxBytes > 0 {
reader = io.LimitReader(file, maxBytes+1) readLimit := maxBytes
if readLimit < math.MaxInt64 {
readLimit++ // Read one extra byte to detect an oversized file.
}
reader = io.LimitReader(file, readLimit)
} }
body, err := io.ReadAll(reader) body, err := io.ReadAll(reader)
if err != nil { if err != nil {

View File

@@ -3,14 +3,45 @@ package httpadapter
import ( import (
"context" "context"
"errors" "errors"
"math"
"mime" "mime"
"os" "os"
"path/filepath" "path/filepath"
"testing" "testing"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/promptkit"
) )
func TestRestrictedArtifactReaderReturnsDetachedBodies(t *testing.T) {
root := t.TempDir()
if err := os.WriteFile(filepath.Join(root, "input.txt"), []byte("original"), 0o644); err != nil {
t.Fatal(err)
}
reader, err := NewRestrictedArtifactReader(root, 0)
if err != nil {
t.Fatal(err)
}
for _, ref := range []promptkit.ArtifactRef{promptkit.Inline("original"), promptkit.File("input.txt")} {
first, err := reader.Read(context.Background(), ref)
if err != nil {
t.Fatal(err)
}
second, err := reader.Read(context.Background(), ref)
if err != nil {
t.Fatal(err)
}
first.Body[0] = 'X'
first.Name = "changed"
if string(second.Body) != "original" || second.Name == "changed" {
t.Fatalf("read results share mutable state: %+v", second)
}
second.Body[1] = 'Y'
if string(first.Body) != "Xriginal" {
t.Fatalf("reader retained a body alias: %q", first.Body)
}
}
}
func TestRestrictedArtifactReaderReadsContainedFiles(t *testing.T) { func TestRestrictedArtifactReaderReadsContainedFiles(t *testing.T) {
root := t.TempDir() root := t.TempDir()
outside := t.TempDir() outside := t.TempDir()
@@ -150,6 +181,15 @@ func TestRestrictedArtifactReaderEnforcesLimits(t *testing.T) {
t.Fatalf("expected unlimited artifact, got %#v and %v", artifact, err) t.Fatalf("expected unlimited artifact, got %#v and %v", artifact, err)
} }
maxLimited, err := NewRestrictedArtifactReader(root, math.MaxInt64)
if err != nil {
t.Fatalf("construct reader at maximum limit: %v", err)
}
artifact, err = maxLimited.Read(context.Background(), promptkit.File("large.txt"))
if err != nil || string(artifact.Body) != "123456" || artifact.Size != 6 {
t.Fatalf("expected full artifact at maximum limit, got %#v and %v", artifact, err)
}
if _, err := NewRestrictedArtifactReader(root, -1); err == nil { if _, err := NewRestrictedArtifactReader(root, -1); err == nil {
t.Fatal("expected negative limit to fail") t.Fatal("expected negative limit to fail")
} }

View File

@@ -8,7 +8,6 @@ import (
type runRequestDTO struct { type runRequestDTO struct {
PromptID string `json:"prompt_id"` PromptID string `json:"prompt_id"`
PromptVersion string `json:"prompt_version,omitempty"`
ProfileID string `json:"profile_id,omitempty"` ProfileID string `json:"profile_id,omitempty"`
SessionID string `json:"session_id,omitempty"` SessionID string `json:"session_id,omitempty"`
Inputs map[string]inputRefDTO `json:"inputs"` Inputs map[string]inputRefDTO `json:"inputs"`
@@ -59,28 +58,21 @@ type artifactDTO struct {
type metadataDTO struct { type metadataDTO struct {
RunID string `json:"run_id"` RunID string `json:"run_id"`
PromptID string `json:"prompt_id"` PromptID string `json:"prompt_id"`
PromptVersion string `json:"prompt_version"`
PromptHash string `json:"prompt_hash"` PromptHash string `json:"prompt_hash"`
RenderedPromptHash string `json:"rendered_prompt_hash"` RenderedPromptHash string `json:"rendered_prompt_hash"`
SelectedProfileID string `json:"selected_profile_id"` SelectedProfileID string `json:"selected_profile_id"`
SelectedBackendID string `json:"selected_backend_id,omitempty"` SelectedBackendID string `json:"selected_backend_id,omitempty"`
SessionID string `json:"session_id,omitempty"` SessionID string `json:"session_id,omitempty"`
ModelName string `json:"model_name"`
Endpoint string `json:"endpoint"`
ModelParams modelParamsDTO `json:"model_params"` ModelParams modelParamsDTO `json:"model_params"`
InputHashes map[string]string `json:"input_hashes"` InputHashes map[string]string `json:"input_hashes"`
Usage tokenUsageDTO `json:"usage"` Usage tokenUsageDTO `json:"usage"`
StartTime time.Time `json:"start_time"` StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time"` EndTime time.Time `json:"end_time"`
DurationMS int64 `json:"duration_ms"` DurationMS int64 `json:"duration_ms"`
ValidationMode string `json:"validation_mode"`
ValidationStatus string `json:"validation_status"`
RepairAttemptsUsed int `json:"repair_attempts_used"`
} }
type modelParamsDTO struct { type modelParamsDTO struct {
Endpoint string `json:"endpoint"` Endpoint string `json:"endpoint"`
BackendID string `json:"backend_id,omitempty"`
Model string `json:"model"` Model string `json:"model"`
Temperature float64 `json:"temperature"` Temperature float64 `json:"temperature"`
MaxTokens int `json:"max_tokens"` MaxTokens int `json:"max_tokens"`

View File

@@ -10,9 +10,9 @@ import (
"strings" "strings"
"time" "time"
"gitea.maximumdirect.net/eric/promptkit"
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults" "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report" executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
"go.maximumdirect.net/promptkit"
) )
type Runner interface { type Runner interface {
@@ -106,38 +106,36 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
model = executionTargetOverrideFromModelOverrideDTO(req.Model) model = executionTargetOverrideFromModelOverrideDTO(req.Model)
} }
runContext := r.Context() var operationTimeout time.Duration
if req.RunTimeoutSeconds != nil && *req.RunTimeoutSeconds > 0 { if req.RunTimeoutSeconds != nil && *req.RunTimeoutSeconds > 0 {
var cancel context.CancelFunc operationTimeout = time.Duration(*req.RunTimeoutSeconds) * time.Second
runContext, cancel = context.WithTimeout(runContext, time.Duration(*req.RunTimeoutSeconds)*time.Second)
defer cancel()
} }
mappedRequest := promptkit.RunRequest{ mappedRequest := promptkit.RunRequest{
PromptID: req.PromptID, PromptID: req.PromptID,
PromptVersion: req.PromptVersion,
ProfileID: req.ProfileID, ProfileID: req.ProfileID,
SessionID: req.SessionID, SessionID: req.SessionID,
Inputs: mappedInputs, Inputs: mappedInputs,
Vars: req.Vars, Vars: req.Vars,
Execution: model, Execution: model,
TransientRetries: req.TransientRetries, TransientRetries: req.TransientRetries,
OperationTimeout: operationTimeout,
} }
var collector *executionreport.Collector var collector *executionreport.Collector
if req.IncludeExecutionReport { if req.IncludeExecutionReport {
collector = executionreport.NewCollector() collector = executionreport.NewCollector()
mappedRequest.Observer = collector.Observe mappedRequest.Observer = collector.Observe
} }
res, err := h.runner.Run(runContext, mappedRequest) res, err := h.runner.Run(r.Context(), mappedRequest)
var execution *executionreport.Execution var execution *executionreport.Execution
if collector != nil { if collector != nil {
execution = collector.Snapshot() execution = collector.Snapshot()
} }
if err != nil { if err != nil {
switch runContext.Err() { switch {
case context.DeadlineExceeded: case errors.Is(err, promptkit.ErrOperationTimeout), errors.Is(err, context.DeadlineExceeded) && errors.Is(r.Context().Err(), context.DeadlineExceeded):
writeRunFailure(w, http.StatusGatewayTimeout, "deadline_exceeded", "run execution deadline exceeded", execution, h.options.MaxResponseBytes) writeRunFailure(w, http.StatusGatewayTimeout, "deadline_exceeded", "run execution deadline exceeded", execution, h.options.MaxResponseBytes)
return return
case context.Canceled: case errors.Is(err, context.Canceled) && errors.Is(r.Context().Err(), context.Canceled):
writeRunFailure(w, http.StatusRequestTimeout, "request_canceled", "run request canceled", execution, h.options.MaxResponseBytes) writeRunFailure(w, http.StatusRequestTimeout, "request_canceled", "run request canceled", execution, h.options.MaxResponseBytes)
return return
} }
@@ -159,14 +157,11 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
Metadata: metadataDTO{ Metadata: metadataDTO{
RunID: res.RunID, RunID: res.RunID,
PromptID: res.PromptID, PromptID: res.PromptID,
PromptVersion: res.PromptVersion,
PromptHash: res.PromptHash, PromptHash: res.PromptHash,
RenderedPromptHash: res.RenderedPromptHash, RenderedPromptHash: res.RenderedPromptHash,
SelectedProfileID: res.SelectedProfileID, SelectedProfileID: res.SelectedProfileID,
SelectedBackendID: res.SelectedBackendID, SelectedBackendID: res.SelectedBackendID,
SessionID: res.SessionID, SessionID: res.SessionID,
ModelName: res.ModelName,
Endpoint: res.Endpoint,
ModelParams: modelParamsDTOFromExecutionTarget(res.EffectiveModelParams), ModelParams: modelParamsDTOFromExecutionTarget(res.EffectiveModelParams),
InputHashes: res.InputHashes, InputHashes: res.InputHashes,
Usage: tokenUsageDTO{ Usage: tokenUsageDTO{
@@ -179,9 +174,6 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
StartTime: res.StartTime, StartTime: res.StartTime,
EndTime: res.EndTime, EndTime: res.EndTime,
DurationMS: res.Duration.Milliseconds(), DurationMS: res.Duration.Milliseconds(),
ValidationMode: string(res.Validation.Mode),
ValidationStatus: string(res.Validation.Status),
RepairAttemptsUsed: res.Validation.RepairAttempts,
}, },
Execution: execution, Execution: execution,
} }
@@ -221,7 +213,6 @@ func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *
func modelParamsDTOFromExecutionTarget(target promptkit.ExecutionTarget) modelParamsDTO { func modelParamsDTOFromExecutionTarget(target promptkit.ExecutionTarget) modelParamsDTO {
return modelParamsDTO{ return modelParamsDTO{
Endpoint: target.Endpoint, Endpoint: target.Endpoint,
BackendID: target.BackendID,
Model: target.Model, Model: target.Model,
Temperature: target.Temperature, Temperature: target.Temperature,
MaxTokens: target.MaxTokens, MaxTokens: target.MaxTokens,
@@ -255,16 +246,16 @@ func mapRunError(err error) (int, string, string) {
return http.StatusBadRequest, "profile_required", "profile_id is required when prompt default_profile is not set" return http.StatusBadRequest, "profile_required", "profile_id is required when prompt default_profile is not set"
case errors.Is(err, promptkit.ErrAPIKeyEnvMissing): case errors.Is(err, promptkit.ErrAPIKeyEnvMissing):
return http.StatusBadRequest, "api_key_env_missing", "api_key_env is set but the environment variable is missing" return http.StatusBadRequest, "api_key_env_missing", "api_key_env is set but the environment variable is missing"
case errors.Is(err, ErrFileNotAllowed), errors.Is(err, ErrFileOutsideRoot):
return http.StatusBadRequest, "artifact_not_allowed", "file input artifact is not allowed"
case errors.Is(err, ErrFileTooLarge):
return http.StatusRequestEntityTooLarge, "artifact_too_large", "file input artifact is too large"
case errors.Is(err, promptkit.ErrPromptLoad): case errors.Is(err, promptkit.ErrPromptLoad):
return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition" return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition"
case errors.Is(err, promptkit.ErrProfileLoad): case errors.Is(err, promptkit.ErrProfileLoad):
return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile" return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile"
case errors.Is(err, promptkit.ErrInvalidRequest): case errors.Is(err, promptkit.ErrInvalidRequest):
return http.StatusBadRequest, "invalid_request", "invalid run request" return http.StatusBadRequest, "invalid_request", "invalid run request"
case errors.Is(err, ErrFileNotAllowed), errors.Is(err, ErrFileOutsideRoot):
return http.StatusBadRequest, "artifact_not_allowed", "file input artifact is not allowed"
case errors.Is(err, ErrFileTooLarge):
return http.StatusRequestEntityTooLarge, "artifact_too_large", "file input artifact is too large"
case errors.Is(err, promptkit.ErrArtifactLoad): case errors.Is(err, promptkit.ErrArtifactLoad):
return http.StatusBadRequest, "artifact_read_failed", "failed to read input artifact" return http.StatusBadRequest, "artifact_read_failed", "failed to read input artifact"
case errors.Is(err, promptkit.ErrPromptRender): case errors.Is(err, promptkit.ErrPromptRender):

View File

@@ -4,6 +4,7 @@ import (
"bytes" "bytes"
"context" "context"
"encoding/json" "encoding/json"
"errors"
"fmt" "fmt"
"net/http" "net/http"
"net/http/httptest" "net/http/httptest"
@@ -15,7 +16,8 @@ import (
"testing" "testing"
"time" "time"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
) )
type fakeRunner struct { type fakeRunner struct {
@@ -335,11 +337,13 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
name, body string name, body string
parent context.Context parent context.Context
wantDeadline time.Time wantDeadline time.Time
wantTimeout time.Duration
}{ }{
{name: "omitted inherits deadline", body: `{"prompt_id":"p"}`, parent: parent, wantDeadline: parentDeadline}, {name: "omitted inherits deadline", body: `{"prompt_id":"p"}`, parent: parent, wantDeadline: parentDeadline},
{name: "null inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: parent, wantDeadline: parentDeadline}, {name: "null inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: parent, wantDeadline: parentDeadline},
{name: "zero inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: parent, wantDeadline: parentDeadline}, {name: "zero inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: parent, wantDeadline: parentDeadline},
{name: "positive preserves earlier deadline", body: `{"prompt_id":"p","run_timeout_seconds":10}`, parent: parent, wantDeadline: parentDeadline}, {name: "positive preserves earlier deadline", body: `{"prompt_id":"p","run_timeout_seconds":10}`, parent: parent, wantDeadline: parentDeadline, wantTimeout: 10 * time.Second},
{name: "positive adds operation budget", body: `{"prompt_id":"p","run_timeout_seconds":2}`, parent: context.Background(), wantTimeout: 2 * time.Second},
{name: "omitted adds no deadline", body: `{"prompt_id":"p"}`, parent: context.Background()}, {name: "omitted adds no deadline", body: `{"prompt_id":"p"}`, parent: context.Background()},
{name: "null adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: context.Background()}, {name: "null adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: context.Background()},
{name: "zero adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: context.Background()}, {name: "zero adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: context.Background()},
@@ -352,6 +356,9 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
if ok != !tc.wantDeadline.IsZero() || (ok && !deadline.Equal(tc.wantDeadline)) { if ok != !tc.wantDeadline.IsZero() || (ok && !deadline.Equal(tc.wantDeadline)) {
t.Fatalf("execution deadline: got %v (present=%t), want %v", deadline, ok, tc.wantDeadline) t.Fatalf("execution deadline: got %v (present=%t), want %v", deadline, ok, tc.wantDeadline)
} }
if req.OperationTimeout != tc.wantTimeout {
t.Fatalf("operation timeout = %v, want %v", req.OperationTimeout, tc.wantTimeout)
}
return &promptkit.RunResult{}, nil return &promptkit.RunResult{}, nil
})) }))
w := httptest.NewRecorder() w := httptest.NewRecorder()
@@ -381,6 +388,22 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":10}`))) h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":10}`)))
assertHTTPErrorCode(t, w, http.StatusBadGateway, "llm_failed") assertHTTPErrorCode(t, w, http.StatusBadGateway, "llm_failed")
expired, cancelExpired := context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
defer cancelExpired()
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
return nil, fmt.Errorf("run failed: %w", ctx.Err())
}))
w = httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)).WithContext(expired))
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
return nil, errors.Join(promptkit.ErrOperationTimeout, context.Canceled)
}))
w = httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)).WithContext(canceled))
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
successContext, cancelSuccess := context.WithCancel(context.Background()) successContext, cancelSuccess := context.WithCancel(context.Background())
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) { h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
cancelSuccess() cancelSuccess()
@@ -446,7 +469,6 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
}, },
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true}, Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
PromptID: "prompt-1", PromptID: "prompt-1",
PromptVersion: "1.0.0",
PromptHash: "phash", PromptHash: "phash",
RenderedPromptHash: "rhash", RenderedPromptHash: "rhash",
SelectedProfileID: "exec-default", SelectedProfileID: "exec-default",
@@ -507,8 +529,10 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
if metadata["prompt_id"] != "prompt-1" { if metadata["prompt_id"] != "prompt-1" {
t.Fatalf("unexpected metadata.prompt_id: %#v", metadata["prompt_id"]) t.Fatalf("unexpected metadata.prompt_id: %#v", metadata["prompt_id"])
} }
if metadata["prompt_version"] != "1.0.0" { for _, field := range []string{"prompt_version", "model_name", "endpoint", "validation_mode", "validation_status", "repair_attempts_used"} {
t.Fatalf("unexpected metadata.prompt_version: %#v", metadata["prompt_version"]) if _, ok := metadata[field]; ok {
t.Fatalf("redundant metadata field %q: %#v", field, metadata)
}
} }
if metadata["selected_profile_id"] != "exec-default" { if metadata["selected_profile_id"] != "exec-default" {
t.Fatalf("unexpected metadata.selected_profile_id: %#v", metadata["selected_profile_id"]) t.Fatalf("unexpected metadata.selected_profile_id: %#v", metadata["selected_profile_id"])
@@ -516,9 +540,6 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
if metadata["selected_backend_id"] != "local" { if metadata["selected_backend_id"] != "local" {
t.Fatalf("unexpected metadata.selected_backend_id: %#v", metadata["selected_backend_id"]) t.Fatalf("unexpected metadata.selected_backend_id: %#v", metadata["selected_backend_id"])
} }
if metadata["model_name"] != "m1" || metadata["endpoint"] != "http://llm/v1" {
t.Fatalf("unexpected model metadata: name=%#v endpoint=%#v", metadata["model_name"], metadata["endpoint"])
}
usage := metadata["usage"].(map[string]any) usage := metadata["usage"].(map[string]any)
if usage["prompt_tokens"] != float64(1) || usage["completion_tokens"] != float64(2) || usage["total_tokens"] != float64(3) { if usage["prompt_tokens"] != float64(1) || usage["completion_tokens"] != float64(2) || usage["total_tokens"] != float64(3) {
t.Fatalf("unexpected base usage metadata: %#v", usage) t.Fatalf("unexpected base usage metadata: %#v", usage)
@@ -527,8 +548,8 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
t.Fatalf("unexpected cache usage metadata: %#v", usage) t.Fatalf("unexpected cache usage metadata: %#v", usage)
} }
modelParams := metadata["model_params"].(map[string]any) modelParams := metadata["model_params"].(map[string]any)
if modelParams["backend_id"] != "local" { if _, ok := modelParams["backend_id"]; ok || modelParams["model"] != "m1" || modelParams["endpoint"] != "http://llm/v1" {
t.Fatalf("expected model_params.backend_id=local, got %#v", modelParams["backend_id"]) t.Fatalf("unexpected model parameters: %#v", modelParams)
} }
if modelParams["api_key_env"] != envName { if modelParams["api_key_env"] != envName {
t.Fatalf("expected model_params.api_key_env=%q, got %#v", envName, modelParams["api_key_env"]) t.Fatalf("expected model_params.api_key_env=%q, got %#v", envName, modelParams["api_key_env"])
@@ -560,7 +581,7 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
} }
} }
func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) { func TestHandlerAllowsOmittedInputsAndPreservesQualifiedIDs(t *testing.T) {
r := &fakeRunner{result: &promptkit.RunResult{ r := &fakeRunner{result: &promptkit.RunResult{
Artifact: promptkit.Artifact{Body: []byte("ok")}, Artifact: promptkit.Artifact{Body: []byte("ok")},
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationNone, IsValid: true}, Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationNone, IsValid: true},
@@ -569,8 +590,8 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
h := NewHandler(r) h := NewHandler(r)
for _, body := range []string{ for _, body := range []string{
`{"prompt_id":"prompt-1","prompt_version":"2"}`, `{"prompt_id":"support/prompt-1","profile_id":"support/profile-1"}`,
`{"prompt_id":"prompt-1","prompt_version":"2","inputs":{}}`, `{"prompt_id":"support/prompt-1","profile_id":"support/profile-1","inputs":{}}`,
} { } {
req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(body)) req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(body))
w := httptest.NewRecorder() w := httptest.NewRecorder()
@@ -579,8 +600,8 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
if w.Code != http.StatusOK { if w.Code != http.StatusOK {
t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String()) t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
} }
if r.last.PromptVersion != "2" { if r.last.PromptID != "support/prompt-1" || r.last.ProfileID != "support/profile-1" {
t.Fatalf("expected prompt version to be mapped, got %q", r.last.PromptVersion) t.Fatalf("qualified IDs changed: %+v", r.last)
} }
if r.last.Inputs != nil { if r.last.Inputs != nil {
t.Fatalf("expected omitted or empty inputs to remain nil, got %#v", r.last.Inputs) t.Fatalf("expected omitted or empty inputs to remain nil, got %#v", r.last.Inputs)
@@ -588,6 +609,16 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
} }
} }
func TestHandlerRejectsRemovedPromptVersion(t *testing.T) {
runner := &fakeRunner{result: &promptkit.RunResult{}}
w := httptest.NewRecorder()
NewHandler(runner).ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","prompt_version":"1"}`)))
assertHTTPErrorCode(t, w, http.StatusBadRequest, "invalid_json")
if runner.last.PromptID != "" {
t.Fatal("runner invoked for removed selector")
}
}
func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) { func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) {
tests := []struct { tests := []struct {
name string name string
@@ -597,8 +628,8 @@ func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) {
}{ }{
{ {
name: "no declared inputs", name: "no declared inputs",
definition: `id: p definition: `prompts:
version: "1" - id: p
default_profile: exec default_profile: exec
messages: messages:
- role: user - role: user
@@ -611,8 +642,8 @@ output:
}, },
{ {
name: "optional input omitted", name: "optional input omitted",
definition: `id: p definition: `prompts:
version: "1" - id: p
default_profile: exec default_profile: exec
inputs: inputs:
- name: note - name: note
@@ -628,8 +659,8 @@ output:
}, },
{ {
name: "required input omitted", name: "required input omitted",
definition: `id: p definition: `prompts:
version: "1" - id: p
default_profile: exec default_profile: exec
inputs: inputs:
- name: note - name: note
@@ -646,8 +677,8 @@ output:
}, },
{ {
name: "template input omitted", name: "template input omitted",
definition: `id: p definition: `prompts:
version: "1" - id: p
default_profile: exec default_profile: exec
messages: messages:
- role: user - role: user
@@ -781,7 +812,6 @@ func TestHandlerPostRunsSuccessUsingPromptDefaultProfile(t *testing.T) {
r := &fakeRunner{result: &promptkit.RunResult{ r := &fakeRunner{result: &promptkit.RunResult{
Artifact: promptkit.Artifact{Body: []byte("ok")}, Artifact: promptkit.Artifact{Body: []byte("ok")},
PromptID: "prompt-1", PromptID: "prompt-1",
PromptVersion: "1.0.0",
SelectedProfileID: "prompt-default", SelectedProfileID: "prompt-default",
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true}, Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
EffectiveModelParams: promptkit.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"}, EffectiveModelParams: promptkit.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
@@ -988,7 +1018,7 @@ func TestHandlerSessionIDUsesPromptkitResolution(t *testing.T) {
if tc.definitionSession != "" { if tc.definitionSession != "" {
sessionLine = " session_id: " + tc.definitionSession + "\n" sessionLine = " session_id: " + tc.definitionSession + "\n"
} }
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("id: p\nversion: \"1\"\ndefault_profile: exec\n"+sessionLine+`messages: if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("prompts:\n - id: p\n default_profile: exec\n"+sessionLine+` messages:
- role: user - role: user
content: "hi" content: "hi"
output: output:
@@ -997,13 +1027,10 @@ output:
`), 0o644); err != nil { `), 0o644); err != nil {
t.Fatalf("write prompt fixture: %v", err) t.Fatalf("write prompt fixture: %v", err)
} }
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("id: exec\nendpoint: http://127.0.0.1:1/v1\nmodel: test\n"), 0o644); err != nil { if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("profiles:\n - id: exec\n endpoint: http://127.0.0.1:1/v1\n model: test\n"), 0o644); err != nil {
t.Fatalf("write profile fixture: %v", err) t.Fatalf("write profile fixture: %v", err)
} }
engine, err := promptkit.NewEngine(promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir}, promptkit.WithLLMClient(handlerLLMClient{})) engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, promptkit.WithLLMClient(handlerLLMClient{}))
if err != nil {
t.Fatalf("new engine: %v", err)
}
body := `{"prompt_id":"p"}` body := `{"prompt_id":"p"}`
if tc.requestSession != "" { if tc.requestSession != "" {
@@ -1035,8 +1062,8 @@ output:
func TestHandlerSharesBackendCapacityAcrossConcurrentRequests(t *testing.T) { func TestHandlerSharesBackendCapacityAcrossConcurrentRequests(t *testing.T) {
promptDir := t.TempDir() promptDir := t.TempDir()
profileDir := t.TempDir() profileDir := t.TempDir()
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`id: p if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
version: "1" - id: p
default_profile: limited default_profile: limited
messages: messages:
- role: user - role: user
@@ -1047,7 +1074,8 @@ output:
`), 0o644); err != nil { `), 0o644); err != nil {
t.Fatalf("write prompt fixture: %v", err) t.Fatalf("write prompt fixture: %v", err)
} }
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: limited if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
- id: limited
backend: limited backend: limited
model: test model: test
`), 0o644); err != nil { `), 0o644); err != nil {
@@ -1055,19 +1083,8 @@ model: test
} }
queueCapacity := 0 queueCapacity := 0
client := &blockingLLMClient{started: make(chan struct{}, 1), release: make(chan struct{})} client := &blockingLLMClient{started: make(chan struct{}, 1), release: make(chan struct{})}
engine, err := promptkit.NewEngine( backend := promptkit.BackendConfig{ID: "limited", Endpoint: stringPointer("http://127.0.0.1:1/v1"), ConcurrencyLimit: intPointer(1), QueueCapacity: &queueCapacity}
promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir}, engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, &backend, promptkit.WithLLMClient(client))
promptkit.WithBackend(promptkit.Backend{
ID: "limited",
Endpoint: "http://127.0.0.1:1/v1",
ConcurrencyLimit: 1,
QueueCapacity: &queueCapacity,
}),
promptkit.WithLLMClient(client),
)
if err != nil {
t.Fatalf("new engine: %v", err)
}
h := NewHandler(engine) h := NewHandler(engine)
first := httptest.NewRecorder() first := httptest.NewRecorder()
firstDone := make(chan struct{}) firstDone := make(chan struct{})
@@ -1198,14 +1215,49 @@ func TestHandlerDeadlineCancelsBuiltInRetryWait(t *testing.T) {
})) }))
defer provider.Close() defer provider.Close()
h := newRetryHandler(t, provider.URL+"/v1", intPointer(1), 0, nil) h := newRetryHandler(t, provider.URL+"/v1", intPointer(1), 0, nil)
w := httptest.NewRecorder() w, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1}`)
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":1}`)))
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded") assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
if !errors.Is(err, promptkit.ErrOperationTimeout) {
t.Fatalf("engine did not attribute retry wait to operation timeout: %v", err)
}
if atomic.LoadInt32(&hits) != 1 { if atomic.LoadInt32(&hits) != 1 {
t.Fatalf("expected one provider call before canceled retry wait, got %d", atomic.LoadInt32(&hits)) t.Fatalf("expected one provider call before canceled retry wait, got %d", atomic.LoadInt32(&hits))
} }
} }
func TestHandlerDeadlineDuringBuiltInGeneration(t *testing.T) {
started := make(chan struct{}, 1)
release := make(chan struct{})
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
started <- struct{}{}
<-release
}))
defer provider.Close()
defer close(release)
h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 0, nil)
w, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1,"include_execution_report":true}`)
select {
case <-started:
default:
t.Fatal("provider call did not start")
}
if !errors.Is(err, promptkit.ErrOperationTimeout) || !errors.Is(err, context.DeadlineExceeded) {
t.Errorf("engine did not attribute in-flight generation to operation timeout: %v (deadline cause: %t)", err, errors.Is(err, context.DeadlineExceeded))
}
var response struct {
Execution *struct {
Failure string `json:"failure"`
} `json:"execution"`
}
if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
t.Fatal(err)
}
if response.Execution == nil || response.Execution.Failure != "deadline" {
t.Errorf("terminal report did not classify deadline: %+v", response.Execution)
}
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
}
func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) { func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
started := make(chan struct{}, 1) started := make(chan struct{}, 1)
release := make(chan struct{}) release := make(chan struct{})
@@ -1228,20 +1280,24 @@ func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
}() }()
queue := 1 queue := 1
h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 1, &queue) h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 1, &queue)
firstCtx, cancelFirst := context.WithTimeout(context.Background(), 10*time.Second)
defer cancelFirst()
first := httptest.NewRecorder() first := httptest.NewRecorder()
done := make(chan struct{}) done := make(chan struct{})
go func() { go func() {
defer close(done) defer close(done)
h.ServeHTTP(first, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`))) h.ServeHTTP(first, httptest.NewRequestWithContext(firstCtx, http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)))
}() }()
select { select {
case <-started: case <-started:
case <-time.After(3 * time.Second): case <-time.After(3 * time.Second):
t.Fatal("first provider call did not start") t.Fatal("first provider call did not start")
} }
waiting := httptest.NewRecorder() waiting, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1}`)
h.ServeHTTP(waiting, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":1}`)))
assertHTTPErrorCode(t, waiting, http.StatusGatewayTimeout, "deadline_exceeded") assertHTTPErrorCode(t, waiting, http.StatusGatewayTimeout, "deadline_exceeded")
if !errors.Is(err, promptkit.ErrOperationTimeout) {
t.Fatalf("engine did not attribute capacity wait to operation timeout: %v", err)
}
if atomic.LoadInt32(&hits) != 1 { if atomic.LoadInt32(&hits) != 1 {
t.Fatalf("capacity waiter reached provider: hits=%d", atomic.LoadInt32(&hits)) t.Fatalf("capacity waiter reached provider: hits=%d", atomic.LoadInt32(&hits))
} }
@@ -1254,27 +1310,48 @@ func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
if first.Code != http.StatusOK { if first.Code != http.StatusOK {
t.Fatalf("first request: status=%d body=%s", first.Code, first.Body.String()) t.Fatalf("first request: status=%d body=%s", first.Code, first.Body.String())
} }
third := httptest.NewRecorder() third, _ := serveObservedTimeoutRequest(h, `{"prompt_id":"p"}`)
h.ServeHTTP(third, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)))
if third.Code != http.StatusOK || atomic.LoadInt32(&hits) != 2 { if third.Code != http.StatusOK || atomic.LoadInt32(&hits) != 2 {
t.Fatalf("admission was not released: status=%d hits=%d body=%s", third.Code, atomic.LoadInt32(&hits), third.Body.String()) t.Fatalf("admission was not released: status=%d hits=%d body=%s", third.Code, atomic.LoadInt32(&hits), third.Body.String())
} }
} }
func serveObservedTimeoutRequest(h *Handler, body string) (*httptest.ResponseRecorder, error) {
// Bound the test independently of the shorter operation budget under test.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
var runErr error
observed := NewHandlerWithOptions(runnerFunc(func(ctx context.Context, request promptkit.RunRequest) (*promptkit.RunResult, error) {
result, err := h.runner.Run(ctx, request)
runErr = err
return result, err
}), h.options)
w := httptest.NewRecorder()
observed.ServeHTTP(w, httptest.NewRequestWithContext(ctx, http.MethodPost, "/v1/runs", strings.NewReader(body)))
return w, runErr
}
func newRetryHandler(t *testing.T, endpoint string, retries *int, concurrency int, queue *int) *Handler { func newRetryHandler(t *testing.T, endpoint string, retries *int, concurrency int, queue *int) *Handler {
t.Helper() t.Helper()
promptDir := t.TempDir() promptDir := t.TempDir()
profileDir := t.TempDir() profileDir := t.TempDir()
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("id: p\nversion: \"1\"\ndefault_profile: limited\nmessages:\n - role: user\n content: hi\noutput:\n format: text\n validation_mode: none\n"), 0o644); err != nil { if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
- id: p
default_profile: limited
messages:
- role: user
content: hi
output:
format: text
validation_mode: none
`), 0o644); err != nil {
t.Fatal(err) t.Fatal(err)
} }
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("id: limited\nbackend: limited\nmodel: test\n"), 0o644); err != nil { if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("profiles:\n - id: limited\n backend: limited\n model: test\n"), 0o644); err != nil {
t.Fatal(err)
}
engine, err := promptkit.NewEngine(promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir, TransientRetries: retries}, promptkit.WithBackend(promptkit.Backend{ID: "limited", Endpoint: endpoint, ConcurrencyLimit: concurrency, QueueCapacity: queue}))
if err != nil {
t.Fatal(err) t.Fatal(err)
} }
backend := promptkit.BackendConfig{ID: "limited", Endpoint: &endpoint, ConcurrencyLimit: &concurrency, QueueCapacity: queue}
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, retries, &backend)
return NewHandler(engine) return NewHandler(engine)
} }
@@ -1626,6 +1703,7 @@ func TestHandlerPublicErrorMapping(t *testing.T) {
{name: "file denied", err: ErrFileNotAllowed, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"}, {name: "file denied", err: ErrFileNotAllowed, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
{name: "file outside root", err: ErrFileOutsideRoot, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"}, {name: "file outside root", err: ErrFileOutsideRoot, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
{name: "file too large", err: ErrFileTooLarge, status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"}, {name: "file too large", err: ErrFileTooLarge, status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
{name: "file too large with broad category", err: errors.Join(ErrFileTooLarge, promptkit.ErrInvalidRequest, promptkit.ErrArtifactLoad), status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
{name: "artifact", err: wrap(promptkit.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"}, {name: "artifact", err: wrap(promptkit.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"},
{name: "prompt render", err: wrap(promptkit.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"}, {name: "prompt render", err: wrap(promptkit.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"},
{name: "capacity", err: &promptkit.CapacityError{BackendID: "private-backend"}, status: http.StatusServiceUnavailable, code: "capacity_exceeded", message: "model backend capacity is exhausted", avoidCause: "private-backend"}, {name: "capacity", err: &promptkit.CapacityError{BackendID: "private-backend"}, status: http.StatusServiceUnavailable, code: "capacity_exceeded", message: "model backend capacity is exhausted", avoidCause: "private-backend"},
@@ -1770,8 +1848,8 @@ func newHandlerEngineWithOptions(t *testing.T, options ...promptkit.Option) *pro
promptDir := t.TempDir() promptDir := t.TempDir()
profileDir := t.TempDir() profileDir := t.TempDir()
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`id: p if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
version: "1" - id: p
default_profile: exec default_profile: exec
messages: messages:
- role: user - role: user
@@ -1783,21 +1861,15 @@ output:
`), 0o644); err != nil { `), 0o644); err != nil {
t.Fatalf("write prompt fixture: %v", err) t.Fatalf("write prompt fixture: %v", err)
} }
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: exec if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
- id: exec
endpoint: http://example.invalid/v1 endpoint: http://example.invalid/v1
model: model model: model
`), 0o644); err != nil { `), 0o644); err != nil {
t.Fatalf("write profile fixture: %v", err) t.Fatalf("write profile fixture: %v", err)
} }
engine, err := promptkit.NewEngine(promptkit.Config{ return newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, options...)
PromptDir: promptDir,
ProfileDir: profileDir,
}, options...)
if err != nil {
t.Fatalf("construct public engine: %v", err)
}
return engine
} }
func newDefinitionHandler(t *testing.T, definition string) *Handler { func newDefinitionHandler(t *testing.T, definition string) *Handler {
@@ -1808,21 +1880,46 @@ func newDefinitionHandler(t *testing.T, definition string) *Handler {
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(definition), 0o644); err != nil { if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(definition), 0o644); err != nil {
t.Fatalf("write prompt fixture: %v", err) t.Fatalf("write prompt fixture: %v", err)
} }
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: exec if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
- id: exec
endpoint: http://example.invalid/v1 endpoint: http://example.invalid/v1
model: model model: model
`), 0o644); err != nil { `), 0o644); err != nil {
t.Fatalf("write profile fixture: %v", err) t.Fatalf("write profile fixture: %v", err)
} }
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, promptkit.WithLLMClient(handlerLLMClient{}))
return NewHandler(engine)
}
func newHandlerEngineFromDirectories(t *testing.T, promptDir, profileDir string, retries *int, backend *promptkit.BackendConfig, options ...promptkit.Option) *promptkit.Engine {
t.Helper()
promptInputs, err := promptkit.DirectoryInputs(promptDir)
if err != nil {
t.Fatalf("load prompt inputs: %v", err)
}
profileInputs, err := promptkit.DirectoryInputs(profileDir)
if err != nil {
t.Fatalf("load profile inputs: %v", err)
}
underlays := []configkit.Underlay{{Inputs: promptInputs}, {Inputs: profileInputs}}
if backend != nil {
underlays = append(underlays, configkit.Underlay{Inputs: []configkit.Input{{Source: promptkit.BackendSource("test backend", []promptkit.BackendConfig{*backend})}}})
}
engine, err := promptkit.NewEngine(promptkit.Config{ engine, err := promptkit.NewEngine(promptkit.Config{
PromptDir: promptDir, Sources: promptkit.ConfigurationSources{Underlays: underlays},
ProfileDir: profileDir, TransientRetries: retries,
}, promptkit.WithLLMClient(handlerLLMClient{})) }, options...)
if err != nil { if err != nil {
t.Fatalf("construct public engine: %v", err) t.Fatalf("construct public engine: %v", err)
} }
return NewHandler(engine) return engine
}
func stringPointer(value string) *string {
return &value
} }
func assertHTTPErrorCode(t *testing.T, w *httptest.ResponseRecorder, status int, code string) { func assertHTTPErrorCode(t *testing.T, w *httptest.ResponseRecorder, status int, code string) {

View File

@@ -4,28 +4,24 @@ import (
"path/filepath" "path/filepath"
"strings" "strings"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults" "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format" renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
"go.maximumdirect.net/configkit"
) )
// Document is Scriptorium's ConfigKit-native application configuration shape. // Document is Scriptorium's ConfigKit-native application configuration shape.
type Document struct { type Document struct {
PromptDir string `yaml:"prompt_dir"` PromptKitSources []SourceSelection `yaml:"promptkit_sources"`
ProfileDir string `yaml:"profile_dir"`
SchemaDir string `yaml:"schema_dir"` SchemaDir string `yaml:"schema_dir"`
TransientRetries *int `yaml:"transient_retries"` TransientRetries *int `yaml:"transient_retries"`
Server ServerDocument `yaml:"server"` Server ServerDocument `yaml:"server"`
Defaults DefaultsDocument `yaml:"defaults"` Defaults DefaultsDocument `yaml:"defaults"`
Backends map[string]BackendDocument `yaml:"backends"`
} }
type BackendDocument struct { // SourceSelection identifies one PromptKit configuration file or directory.
Endpoint string `yaml:"endpoint"` type SourceSelection struct {
APIKeyEnv string `yaml:"api_key_env"` File string `yaml:"file"`
ExtraParams map[string]any `yaml:"extra_params"` Directory string `yaml:"directory"`
ConcurrencyLimit int `yaml:"concurrency_limit"`
QueueCapacity *int `yaml:"queue_capacity"`
} }
type ServerDocument struct { type ServerDocument struct {
@@ -77,8 +73,11 @@ func resolveDocument(document *Document, resolution *configkit.Resolution) error
} }
} }
normalizePath(configkit.Keys("prompt_dir"), &document.PromptDir) for i := range document.PromptKitSources {
normalizePath(configkit.Keys("profile_dir"), &document.ProfileDir) path := configkit.Keys("promptkit_sources").Index(i)
normalizePath(path.Key("file"), &document.PromptKitSources[i].File)
normalizePath(path.Key("directory"), &document.PromptKitSources[i].Directory)
}
normalizePath(configkit.Keys("schema_dir"), &document.SchemaDir) normalizePath(configkit.Keys("schema_dir"), &document.SchemaDir)
normalizePath(configkit.Keys("server", "artifact_root"), &document.Server.ArtifactRoot) normalizePath(configkit.Keys("server", "artifact_root"), &document.Server.ArtifactRoot)
normalizeString(configkit.Keys("server", "addr"), &document.Server.Addr, normalizeString(configkit.Keys("server", "addr"), &document.Server.Addr,
@@ -89,6 +88,13 @@ func resolveDocument(document *Document, resolution *configkit.Resolution) error
} }
func validateDocument(document *Document, validation *configkit.Validation) { func validateDocument(document *Document, validation *configkit.Validation) {
for i, source := range document.PromptKitSources {
hasFile := source.File != ""
hasDirectory := source.Directory != ""
if hasFile == hasDirectory {
validation.Error(configkit.Keys("promptkit_sources").Index(i), "exactly one of file or directory must be non-empty")
}
}
if document.TransientRetries != nil && *document.TransientRetries < 0 { if document.TransientRetries != nil && *document.TransientRetries < 0 {
validation.Error(configkit.Keys("transient_retries"), "must be greater than or equal to zero") validation.Error(configkit.Keys("transient_retries"), "must be greater than or equal to zero")
} }

View File

@@ -7,7 +7,7 @@ import (
"strings" "strings"
"testing" "testing"
configkit "gitea.maximumdirect.net/eric/ConfigKit" "go.maximumdirect.net/configkit"
) )
func loadDocumentBytes(content string) (*configkit.Result[Document], error) { func loadDocumentBytes(content string) (*configkit.Result[Document], error) {
@@ -25,8 +25,9 @@ func TestDocumentDefaultsAndExplicitValues(t *testing.T) {
t.Fatalf("unexpected defaults-only result: %+v sources=%+v", defaultsOnly.Config, defaultsOnly.Sources()) t.Fatalf("unexpected defaults-only result: %+v sources=%+v", defaultsOnly.Config, defaultsOnly.Sources())
} }
result, err := loadDocumentBytes(`prompt_dir: "" result, err := loadDocumentBytes(`promptkit_sources:
profile_dir: "" - file: " ./bundle/../framework.yml "
- directory: "./profiles"
schema_dir: "" schema_dir: ""
transient_retries: 0 transient_retries: 0
server: server:
@@ -37,12 +38,6 @@ server:
max_response_bytes: 0 max_response_bytes: 0
defaults: defaults:
render_format: " JSON " render_format: " JSON "
backends:
local:
endpoint: "http://fixture.invalid/v1"
queue_capacity: 0
extra_params:
sample_count: 23
`) `)
if err != nil { if err != nil {
t.Fatalf("explicit-value load: %v", err) t.Fatalf("explicit-value load: %v", err)
@@ -54,30 +49,70 @@ backends:
if config.TransientRetries == nil || *config.TransientRetries != 0 { if config.TransientRetries == nil || *config.TransientRetries != 0 {
t.Fatalf("explicit zero retry budget lost: %+v", config.TransientRetries) t.Fatalf("explicit zero retry budget lost: %+v", config.TransientRetries)
} }
if backend := config.Backends["local"]; backend.QueueCapacity == nil || *backend.QueueCapacity != 0 || backend.ExtraParams["sample_count"] != int64(23) { if want := []SourceSelection{{File: "framework.yml"}, {Directory: "profiles"}}; !reflect.DeepEqual(config.PromptKitSources, want) {
t.Fatalf("backend presence or dynamic integer changed: %+v", backend) t.Fatalf("source selectors did not decode: %+v", config.PromptKitSources)
} }
if config.Defaults.RenderFormat != "json" { if config.Defaults.RenderFormat != "json" {
t.Fatalf("render format normalization failed: %q", config.Defaults.RenderFormat) t.Fatalf("render format normalization failed: %q", config.Defaults.RenderFormat)
} }
nullable, err := loadDocumentBytes("transient_retries: null\nbackends:\n local:\n queue_capacity: null\n") nullable, err := loadDocumentBytes("transient_retries: null\npromptkit_sources: null\n")
if err != nil { if err != nil {
t.Fatalf("nullable-value load: %v", err) t.Fatalf("nullable-value load: %v", err)
} }
if nullable.Config.TransientRetries != nil || nullable.Config.Backends["local"].QueueCapacity != nil { if nullable.Config.TransientRetries != nil || nullable.Config.PromptKitSources != nil {
t.Fatalf("nullable fields did not remain nil: %+v", nullable.Config) t.Fatalf("nullable fields did not remain nil: %+v", nullable.Config)
} }
}
nullBackends, err := loadDocumentBytes("backends: null\n") func TestDocumentSourceSelectionsDoNotAcquirePaths(t *testing.T) {
if err != nil || nullBackends.Config.Backends != nil { for _, tc := range []struct {
t.Fatalf("nullable backend map did not remain nil: %+v error=%v", nullBackends, err) name string
content string
want []SourceSelection
}{
{name: "omitted", content: "{}\n"},
{name: "null", content: "promptkit_sources: null\n"},
{name: "empty", content: "promptkit_sources: []\n"},
{name: "nonexistent file", content: "promptkit_sources:\n - file: ./missing/framework.yml\n", want: []SourceSelection{{File: "missing/framework.yml"}}},
{name: "nonexistent directory", content: "promptkit_sources:\n - directory: ./missing/framework\n", want: []SourceSelection{{Directory: "missing/framework"}}},
} {
t.Run(tc.name, func(t *testing.T) {
result, err := loadDocumentBytes(tc.content)
if err != nil {
t.Fatalf("load source selectors: %v", err)
}
if len(result.Config.PromptKitSources) != len(tc.want) || len(tc.want) > 0 && !reflect.DeepEqual(result.Config.PromptKitSources, tc.want) {
t.Fatalf("source selectors changed: got=%+v want=%+v", result.Config.PromptKitSources, tc.want)
}
})
}
}
func TestSettingsCopiesPromptKitSourcesInOrder(t *testing.T) {
document := Document{PromptKitSources: []SourceSelection{
{File: "./first.yml"},
{Directory: "./second"},
}}
settings := Settings(document)
if !reflect.DeepEqual(settings.PromptKitSources, document.PromptKitSources) {
t.Fatalf("source ordering changed: got=%+v want=%+v", settings.PromptKitSources, document.PromptKitSources)
}
document.PromptKitSources[0].File = "changed.yml"
if settings.PromptKitSources[0].File != "./first.yml" {
t.Fatalf("settings retained the document's source slice: %+v", settings.PromptKitSources)
}
if empty := Settings(Document{PromptKitSources: []SourceSelection{}}).PromptKitSources; empty == nil {
t.Fatal("explicit empty source list was not copied")
} }
} }
func TestDocumentRecordsEffectiveNormalization(t *testing.T) { func TestDocumentRecordsEffectiveNormalization(t *testing.T) {
result, err := loadDocumentBytes(`prompt_dir: " ./one/../two " result, err := loadDocumentBytes(`promptkit_sources:
profile_dir: " " - file: " ./one/../two "
- file: "./blank.yml"
directory: " "
- directory: "./three/../three"
server: server:
artifact_root: " ./data/../artifacts " artifact_root: " ./data/../artifacts "
addr: " :9000 " addr: " :9000 "
@@ -87,19 +122,22 @@ defaults:
if err != nil { if err != nil {
t.Fatalf("load normalized document: %v", err) t.Fatalf("load normalized document: %v", err)
} }
if result.Config.PromptDir != "two" || result.Config.ProfileDir != "" || result.Config.Server.ArtifactRoot != "artifacts" || result.Config.Server.Addr != ":9000" { if want := []SourceSelection{{File: "two"}, {File: "blank.yml"}, {Directory: "three"}}; !reflect.DeepEqual(result.Config.PromptKitSources, want) {
t.Fatalf("unexpected normalized source selections: %+v", result.Config.PromptKitSources)
}
if result.Config.Server.ArtifactRoot != "artifacts" || result.Config.Server.Addr != ":9000" {
t.Fatalf("unexpected normalized values: %+v", result.Config) t.Fatalf("unexpected normalized values: %+v", result.Config)
} }
var effective bytes.Buffer var effective bytes.Buffer
if err := result.WriteEffective(&effective); err != nil { if err := result.WriteEffective(&effective); err != nil {
t.Fatalf("write effective configuration: %v", err) t.Fatalf("write effective configuration: %v", err)
} }
for _, fragment := range []string{"prompt_dir: two", "profile_dir: ''", "artifact_root: artifacts", "addr: :9000", "render_format: json"} { for _, fragment := range []string{"file: two", "directory: ''", "directory: three", "artifact_root: artifacts", "addr: :9000", "render_format: json"} {
if !strings.Contains(effective.String(), fragment) { if !strings.Contains(effective.String(), fragment) {
t.Fatalf("effective output omitted %q: %s", fragment, effective.String()) t.Fatalf("effective output omitted %q: %s", fragment, effective.String())
} }
} }
explanation, known := result.Explain(configkit.Keys("prompt_dir")) explanation, known := result.Explain(configkit.Keys("promptkit_sources").Index(0).Key("file"))
if !known || explanation.Effective.YAML != "two\n" { if !known || explanation.Effective.YAML != "two\n" {
t.Fatalf("explanation does not agree with effective value: %+v known=%t", explanation, known) t.Fatalf("explanation does not agree with effective value: %+v known=%t", explanation, known)
} }
@@ -112,10 +150,26 @@ defaults:
if !found { if !found {
t.Fatalf("normalization was not recorded: %+v", explanation.History) t.Fatalf("normalization was not recorded: %+v", explanation.History)
} }
unchanged, err := loadDocumentBytes("promptkit_sources:\n - file: framework.yml\n")
if err != nil {
t.Fatalf("load unchanged source path: %v", err)
}
unchangedExplanation, known := unchanged.Explain(configkit.Keys("promptkit_sources").Index(0).Key("file"))
if !known {
t.Fatal("unchanged source path was not inspectable")
}
for _, change := range unchangedExplanation.History {
if change.Origin.Operation == configkit.ChangeNormalization {
t.Fatalf("unchanged source path recorded a normalization: %+v", unchangedExplanation.History)
}
}
} }
func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) { func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) {
for _, tc := range []struct{ name, content, path string }{ for _, tc := range []struct{ name, content, path string }{
{"empty source selector", "promptkit_sources:\n - file: ''\n", "/promptkit_sources/0"},
{"multiple source selectors", "promptkit_sources:\n - file: secret-path\n directory: private-path\n", "/promptkit_sources/0"},
{"negative retry", "transient_retries: -9173\n", "/transient_retries"}, {"negative retry", "transient_retries: -9173\n", "/transient_retries"},
{"negative request limit", "server:\n max_request_bytes: -9173\n", "/server/max_request_bytes"}, {"negative request limit", "server:\n max_request_bytes: -9173\n", "/server/max_request_bytes"},
{"negative artifact limit", "server:\n max_artifact_bytes: -9173\n", "/server/max_artifact_bytes"}, {"negative artifact limit", "server:\n max_artifact_bytes: -9173\n", "/server/max_artifact_bytes"},
@@ -134,7 +188,7 @@ func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) {
if diagnostic.Code == configkit.CodeValidateError && diagnostic.Path.String() == tc.path { if diagnostic.Code == configkit.CodeValidateError && diagnostic.Path.String() == tc.path {
found = true found = true
} }
if strings.Contains(diagnostic.Message, "9173") || strings.Contains(diagnostic.Message, "private-invalid-value") { if strings.Contains(diagnostic.Message, "9173") || strings.Contains(diagnostic.Message, "private-invalid-value") || strings.Contains(diagnostic.Message, "secret-path") || strings.Contains(diagnostic.Message, "private-path") {
t.Fatalf("diagnostic disclosed rejected value: %+v", diagnostic) t.Fatalf("diagnostic disclosed rejected value: %+v", diagnostic)
} }
} }
@@ -153,7 +207,13 @@ func TestDocumentRejectsNativeShapeErrors(t *testing.T) {
"server:\n max_request_bytes: null\n", "server:\n max_request_bytes: null\n",
"defaults:\n render_format: null\n", "defaults:\n render_format: null\n",
"server:\n unknown_field: 1\n", "server:\n unknown_field: 1\n",
"backends:\n local:\n unknown_field: 1\n", "promptkit_sources:\n - file: ./selected.yml\n unknown_field: 1\n",
"promptkit_sources:\n - file: ./selected.yml\n directory: ./also-selected\n",
"promptkit_sources:\n - file: null\n",
"promptkit_sources: ./not-a-sequence.yml\n",
"prompt_dir: ./old-prompts\n",
"profile_dir: ./old-profiles\n",
"backends:\n local:\n endpoint: http://example.invalid/v1\n",
} { } {
_, err := loadDocumentBytes(content) _, err := loadDocumentBytes(content)
if err == nil { if err == nil {

View File

@@ -1,13 +1,10 @@
package config package config
import ( import (
"errors"
"fmt" "fmt"
"os"
"sort"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format" renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
"go.maximumdirect.net/configkit"
) )
// LoadOptions selects one application source and explicit configuration values. // LoadOptions selects one application source and explicit configuration values.
@@ -21,35 +18,15 @@ type LoadOptions struct {
// Load resolves one ConfigKit document and retains its inspection snapshot. // Load resolves one ConfigKit document and retains its inspection snapshot.
func Load(options LoadOptions) (*configkit.Result[Document], error) { func Load(options LoadOptions) (*configkit.Result[Document], error) {
var source configkit.Source var source configkit.Source
fileBacked := false
if options.Explicit { if options.Explicit {
source = configkit.File(options.Path) source = configkit.File(options.Path)
fileBacked = true
} else { } else {
selected := "" source = configkit.SearchConfig("scriptorium", configkit.SearchPaths(defaultConfigSearchPaths...))
for _, candidate := range defaultConfigSearchPaths {
if _, err := os.Stat(candidate); err == nil {
selected = candidate
break
} else if !errors.Is(err, os.ErrNotExist) {
reason := "filesystem error"
if errors.Is(err, os.ErrPermission) {
reason = "permission denied"
}
return nil, fmt.Errorf("cannot inspect configuration path %q: %s", candidate, reason)
}
}
if selected == "" {
source = configkit.NoSource()
} else {
source = configkit.File(selected)
fileBacked = true
}
} }
result, err := configkit.Load(source, configkit.Options[Document]{ result, err := configkit.Load(source, configkit.Options[Document]{
Definition: documentDefinition(), Definition: documentDefinition(),
Imports: fileBacked, Imports: true,
Overlay: options.Overlay, Overlay: options.Overlay,
Overrides: options.Overrides, Overrides: options.Overrides,
}) })
@@ -62,8 +39,6 @@ func Load(options LoadOptions) (*configkit.Result[Document], error) {
// Settings converts a validated document without another merge or normalization. // Settings converts a validated document without another merge or normalization.
func Settings(document Document) AppSettings { func Settings(document Document) AppSettings {
settings := AppSettings{ settings := AppSettings{
PromptDir: document.PromptDir,
ProfileDir: document.ProfileDir,
SchemaDir: document.SchemaDir, SchemaDir: document.SchemaDir,
ServerAddr: document.Server.Addr, ServerAddr: document.Server.Addr,
ArtifactRoot: document.Server.ArtifactRoot, ArtifactRoot: document.Server.ArtifactRoot,
@@ -73,24 +48,8 @@ func Settings(document Document) AppSettings {
DefaultRenderFormat: renderformat.PreparedRunOutputFormat(document.Defaults.RenderFormat), DefaultRenderFormat: renderformat.PreparedRunOutputFormat(document.Defaults.RenderFormat),
TransientRetries: document.TransientRetries, TransientRetries: document.TransientRetries,
} }
if document.Backends != nil { if document.PromptKitSources != nil {
ids := make([]string, 0, len(document.Backends)) settings.PromptKitSources = append([]SourceSelection{}, document.PromptKitSources...)
for id := range document.Backends {
ids = append(ids, id)
}
sort.Strings(ids)
settings.Backends = make([]BackendSettings, 0, len(ids))
for _, id := range ids {
backend := document.Backends[id]
settings.Backends = append(settings.Backends, BackendSettings{
ID: id,
Endpoint: backend.Endpoint,
APIKeyEnv: backend.APIKeyEnv,
ExtraParams: backend.ExtraParams,
ConcurrencyLimit: backend.ConcurrencyLimit,
QueueCapacity: backend.QueueCapacity,
})
}
} }
return settings return settings
} }

View File

@@ -8,7 +8,7 @@ import (
"strings" "strings"
"testing" "testing"
configkit "gitea.maximumdirect.net/eric/ConfigKit" "go.maximumdirect.net/configkit"
) )
func useConfigSearchPaths(t *testing.T, paths ...string) { func useConfigSearchPaths(t *testing.T, paths ...string) {
@@ -29,19 +29,19 @@ func TestLoadSelectsOrderedSourceAndKeepsItsSnapshot(t *testing.T) {
dir := t.TempDir() dir := t.TempDir()
first := filepath.Join(dir, "first.yml") first := filepath.Join(dir, "first.yml")
second := filepath.Join(dir, "second.yml") second := filepath.Join(dir, "second.yml")
writeApplicationFile(t, first, "prompt_dir: ./first\n") writeApplicationFile(t, first, "promptkit_sources:\n - file: ./first.yml\n")
writeApplicationFile(t, second, "prompt_dir: ./second\n") writeApplicationFile(t, second, "promptkit_sources:\n - directory: ./second\n")
useConfigSearchPaths(t, first, second) useConfigSearchPaths(t, first, second)
result, err := Load(LoadOptions{Path: filepath.Join(dir, "ignored.yml")}) result, err := Load(LoadOptions{Path: filepath.Join(dir, "ignored.yml")})
if err != nil { if err != nil {
t.Fatalf("load first implicit source: %v", err) t.Fatalf("load first implicit source: %v", err)
} }
if result.Config.PromptDir != "first" || len(result.Sources()) != 1 || result.Sources()[0].Path != first { if !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "first.yml"}}) || len(result.Sources()) != 1 || result.Sources()[0].Path != first {
t.Fatalf("unexpected implicit source: config=%+v sources=%+v", result.Config, result.Sources()) t.Fatalf("unexpected implicit source: config=%+v sources=%+v", result.Config, result.Sources())
} }
writeApplicationFile(t, first, "prompt_dir: ./changed\n") writeApplicationFile(t, first, "promptkit_sources:\n - file: ./changed.yml\n")
if result.Config.PromptDir != "first" { if !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "first.yml"}}) {
t.Fatalf("result did not retain resolved snapshot: %+v", result.Config) t.Fatalf("result did not retain resolved snapshot: %+v", result.Config)
} }
@@ -49,7 +49,7 @@ func TestLoadSelectsOrderedSourceAndKeepsItsSnapshot(t *testing.T) {
t.Fatal(err) t.Fatal(err)
} }
result, err = Load(LoadOptions{}) result, err = Load(LoadOptions{})
if err != nil || result.Config.PromptDir != "second" || result.Sources()[0].Path != second { if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{Directory: "second"}}) || result.Sources()[0].Path != second {
t.Fatalf("second implicit source not selected: result=%+v err=%v", result, err) t.Fatalf("second implicit source not selected: result=%+v err=%v", result, err)
} }
@@ -113,7 +113,7 @@ func TestLoadDefaultsOnlyAndOverridesBeforeValidation(t *testing.T) {
if err != nil || result.Config.Defaults.RenderFormat != "json" { if err != nil || result.Config.Defaults.RenderFormat != "json" {
t.Fatalf("override did not precede validation: result=%+v err=%v", result, err) t.Fatalf("override did not precede validation: result=%+v err=%v", result, err)
} }
if len(result.Sources()) != 2 || result.Sources()[0].Layer != configkit.LayerBase || result.Sources()[1].Layer != configkit.LayerCLI { if len(result.Sources()) != 2 || result.Sources()[0].Layer != configkit.LayerMain || result.Sources()[1].Layer != configkit.LayerCLI {
t.Fatalf("source order changed: %+v", result.Sources()) t.Fatalf("source order changed: %+v", result.Sources())
} }
writeApplicationFile(t, path, "defaults: [\n") writeApplicationFile(t, path, "defaults: [\n")
@@ -124,8 +124,11 @@ func TestLoadDefaultsOnlyAndOverridesBeforeValidation(t *testing.T) {
} }
} }
func TestSettingsCopiesResolvedValuesAndSortsBackends(t *testing.T) { func TestSettingsCopiesResolvedValuesAndSourceOrder(t *testing.T) {
result, err := loadDocumentBytes(`schema_dir: "" result, err := loadDocumentBytes(`schema_dir: ""
promptkit_sources:
- directory: ./profiles
- file: ./framework.yml
transient_retries: 0 transient_retries: 0
server: server:
addr: "" addr: ""
@@ -133,13 +136,6 @@ server:
max_request_bytes: 0 max_request_bytes: 0
defaults: defaults:
render_format: json render_format: json
backends:
zed:
endpoint: http://zed.invalid/v1
extra_params:
count: 4
alpha:
queue_capacity: 0
`) `)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -151,31 +147,49 @@ backends:
if settings.TransientRetries == nil || *settings.TransientRetries != 0 { if settings.TransientRetries == nil || *settings.TransientRetries != 0 {
t.Fatalf("retry presence lost: %+v", settings.TransientRetries) t.Fatalf("retry presence lost: %+v", settings.TransientRetries)
} }
if len(settings.Backends) != 2 || settings.Backends[0].ID != "alpha" || settings.Backends[1].ID != "zed" { if want := []SourceSelection{{Directory: "profiles"}, {File: "framework.yml"}}; !reflect.DeepEqual(settings.PromptKitSources, want) {
t.Fatalf("backend order changed: %+v", settings.Backends) t.Fatalf("source ordering changed: got=%+v want=%+v", settings.PromptKitSources, want)
}
if settings.Backends[0].QueueCapacity == nil || *settings.Backends[0].QueueCapacity != 0 || settings.Backends[1].QueueCapacity != nil {
t.Fatalf("queue presence changed: %+v", settings.Backends)
}
if value := settings.Backends[1].ExtraParams["count"]; value != int64(4) {
t.Fatalf("dynamic number changed shape: %T %v", value, value)
} }
if got := Settings(documentDefaults()); got.TransientRetries != nil || got.Backends != nil { if got := Settings(documentDefaults()); got.TransientRetries != nil || got.PromptKitSources != nil {
t.Fatalf("default nullable values changed: %+v", got) t.Fatalf("default nullable values changed: %+v", got)
} }
} }
func TestLoadDiscoveryErrorQuotesPath(t *testing.T) { func TestLoadDiscoveryErrorQuotesPath(t *testing.T) {
dir := t.TempDir() dir := t.TempDir()
loop := filepath.Join(dir, "loop-\n.yml") path := filepath.Join(dir, "directory-\n.yml")
if err := os.Symlink(loop, loop); err != nil { if err := os.Mkdir(path, 0o700); err != nil {
t.Skipf("symlink unavailable: %v", err) t.Fatal(err)
} }
useConfigSearchPaths(t, loop) useConfigSearchPaths(t, path)
_, err := Load(LoadOptions{}) _, err := Load(LoadOptions{})
if err == nil || !strings.Contains(err.Error(), `\n`) || strings.Contains(err.Error(), "loop-\n.yml") { var loadError *configkit.LoadError
t.Fatalf("discovery error did not quote path safely: %v", err) if !errors.As(err, &loadError) {
t.Fatalf("expected structured error: %v", err)
}
var diagnostics strings.Builder
if err := configkit.WriteDiagnostics(&diagnostics, loadError.Diagnostics()); err != nil {
t.Fatal(err)
}
if !strings.Contains(diagnostics.String(), string(configkit.CodeSourceNotRegular)) || strings.Contains(diagnostics.String(), "directory-\n.yml") {
t.Fatalf("discovery diagnostics exposed an unescaped path: %s", diagnostics.String())
}
// A decoding diagnostic can contain an authored configuration path even
// though the nonregular-file diagnostic omits its filesystem path.
file := filepath.Join(dir, "invalid.yml")
writeApplicationFile(t, file, "server:\n \"bad\\nkey\": value\n")
_, err = Load(LoadOptions{Path: file, Explicit: true})
if !errors.As(err, &loadError) {
t.Fatalf("expected decoding diagnostic: %v", err)
}
diagnostics.Reset()
if err := configkit.WriteDiagnostics(&diagnostics, loadError.Diagnostics()); err != nil {
t.Fatal(err)
}
if !strings.Contains(diagnostics.String(), `\n`) || strings.Contains(diagnostics.String(), "bad\nkey") {
t.Fatalf("diagnostic path was not escaped: %q", diagnostics.String())
} }
} }
@@ -188,25 +202,29 @@ func TestLoadComposesExplicitImportsAndSelectedOverlay(t *testing.T) {
t.Fatal(err) t.Fatal(err)
} }
base := filepath.Join(dir, "config.yml") base := filepath.Join(dir, "config.yml")
writeApplicationFile(t, base, "configkit:\n imports:\n - glob: fragments/*.yml\nprompt_dir: ./base-prompts\nserver:\n addr: :8081\n") writeApplicationFile(t, base, "config:\n imports:\n - glob: fragments/*.yml\n required: true\npromptkit_sources:\n - file: ./base-framework.yml\n")
writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "backends:\n alpha:\n endpoint: http://alpha.invalid/v1\n") writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "server:\n addr: :8081\n")
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "backends:\n beta:\n endpoint: http://beta.invalid/v1\n") writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "defaults:\n render_format: json\n")
writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "prompt_dir: ./overlay-prompts\nserver:\n addr: :9090\n") writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "promptkit_sources:\n - directory: ./overlay-framework\nserver:\n addr: :9090\n")
result, err := Load(LoadOptions{Path: base, Explicit: true}) result, err := Load(LoadOptions{Path: base, Explicit: true})
if err != nil || result.Config.PromptDir != "base-prompts" || len(result.Config.Backends) != 2 || len(result.Sources()) != 3 { if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "base-framework.yml"}}) || result.Config.Server.Addr != ":8081" || result.Config.Defaults.RenderFormat != "json" || len(result.Sources()) != 3 {
t.Fatalf("disjoint imports did not compose: result=%+v err=%v", result, err) t.Fatalf("disjoint imports did not compose: result=%+v err=%v", result, err)
} }
result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{ result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{
Path: configkit.Keys("server", "addr"), Value: ":7070", Flag: "--addr", Path: configkit.Keys("promptkit_sources"), Value: []any{map[string]any{"file": "./cli-framework.yml"}}, Flag: "--promptkit-source",
}}}) }}})
if err != nil || result.Config.PromptDir != "overlay-prompts" || result.Config.Server.Addr != ":7070" || len(result.Sources()) != 5 { if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "cli-framework.yml"}}) || result.Config.Server.Addr != ":9090" || len(result.Sources()) != 5 {
t.Fatalf("overlay or explicit override changed: result=%+v err=%v", result, err) t.Fatalf("overlay or explicit override changed: result=%+v err=%v", result, err)
} }
result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local"})
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{Directory: "overlay-framework"}}) {
t.Fatalf("overlay did not replace the source list: result=%+v err=%v", result, err)
}
if _, err := Load(LoadOptions{Path: base, Explicit: true, Overlay: "missing"}); err == nil { if _, err := Load(LoadOptions{Path: base, Explicit: true, Overlay: "missing"}); err == nil {
t.Fatal("missing selected overlay accepted") t.Fatal("missing selected overlay accepted")
} }
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "backends:\n alpha:\n endpoint: http://conflict.invalid/v1\n") writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "server:\n addr: :8082\n")
if _, err := Load(LoadOptions{Path: base, Explicit: true}); err == nil { if _, err := Load(LoadOptions{Path: base, Explicit: true}); err == nil {
t.Fatal("conflicting import accepted") t.Fatal("conflicting import accepted")
} else { } else {
@@ -217,17 +235,103 @@ func TestLoadComposesExplicitImportsAndSelectedOverlay(t *testing.T) {
} }
} }
func TestLoadRejectsOverlayWithoutBase(t *testing.T) { func TestLoadOverlayWithoutMainContext(t *testing.T) {
useConfigSearchPaths(t, filepath.Join(t.TempDir(), "absent.yml")) useConfigSearchPaths(t, filepath.Join(t.TempDir(), "absent.yml"))
if _, err := Load(LoadOptions{Overlay: "local"}); err == nil { if _, err := Load(LoadOptions{Overlay: "local"}); err == nil {
t.Fatal("overlay without base accepted") t.Fatal("overlay without a main context accepted")
} else { } else {
var loadError *configkit.LoadError var loadError *configkit.LoadError
if !errors.As(err, &loadError) { if !errors.As(err, &loadError) {
t.Fatalf("no-base overlay lost structured diagnostic: %v", err) t.Fatalf("no-context overlay lost structured diagnostic: %v", err)
} }
} }
if _, err := Load(LoadOptions{Overlay: "default"}); err != nil { if _, err := Load(LoadOptions{Overlay: "default"}); err != nil {
t.Fatalf("default must select no overlay: %v", err) t.Fatalf("default must select no overlay: %v", err)
} }
} }
func TestLoadDoesNotFallThroughSelectedInvalidSource(t *testing.T) {
dir := t.TempDir()
first, second := filepath.Join(dir, "first.yml"), filepath.Join(dir, "second.yml")
writeApplicationFile(t, first, "server: [\n")
writeApplicationFile(t, second, "server:\n addr: ':9090'\n")
useConfigSearchPaths(t, first, second)
if _, err := Load(LoadOptions{}); err == nil {
t.Fatal("malformed selected file fell through to the second candidate")
}
}
func TestLoadImportRequirednessAndDestination(t *testing.T) {
dir := t.TempDir()
main := filepath.Join(dir, "config.yml")
for _, tc := range []struct {
name, declaration string
wantError bool
}{
{"optional by default", "- path: absent.yml", false},
{"required", "- path: absent.yml\n required: true", true},
{"removed optional field", "- path: absent.yml\n optional: true", true},
} {
t.Run(tc.name, func(t *testing.T) {
writeApplicationFile(t, main, "config:\n imports:\n "+tc.declaration+"\n")
_, err := Load(LoadOptions{Path: main, Explicit: true})
if (err != nil) != tc.wantError {
t.Fatalf("load error = %v, want error %t", err, tc.wantError)
}
})
}
fragments := filepath.Join(dir, "fragments")
if err := os.Mkdir(fragments, 0o700); err != nil {
t.Fatal(err)
}
writeApplicationFile(t, filepath.Join(fragments, "server.yml"), "addr: ':8181'\n")
writeApplicationFile(t, main, "config:\n imports:\n - dir: fragments\n pattern: '*.yml'\n destination: [server]\n required: true\n")
result, err := Load(LoadOptions{Path: main, Explicit: true})
if err != nil {
t.Fatal(err)
}
info, ok := result.Metadata().Lookup(configkit.Keys("server", "addr"))
if result.Config.Server.Addr != ":8181" || !ok || len(info.Origin.Locations) == 0 {
t.Fatalf("mounted value or origin missing: config=%+v origin=%+v", result.Config.Server, info)
}
}
func TestLoadAuthoredSelectorCollection(t *testing.T) {
dir := t.TempDir()
for _, subdir := range []string{"fragments", "overlays"} {
if err := os.Mkdir(filepath.Join(dir, subdir), 0o700); err != nil {
t.Fatal(err)
}
}
main := filepath.Join(dir, "config.yml")
writeApplicationFile(t, main, "config:\n sequences:\n - destination: [promptkit_sources]\n key: file\n mode: upsert\n imports:\n - dir: fragments\n pattern: '*.yml'\n required: true\n")
writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "promptkit_sources:\n - file: a.yml\n")
peer := filepath.Join(dir, "fragments", "b.yml")
writeApplicationFile(t, peer, "promptkit_sources:\n - file: b.yml\n")
writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "promptkit_sources:\n - file: c.yml\n")
result, err := Load(LoadOptions{Path: main, Explicit: true, Overlay: "local"})
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "a.yml"}, {File: "b.yml"}, {File: "c.yml"}}) {
t.Fatalf("authored upsert did not retain selectors: result=%+v err=%v", result, err)
}
result, err = Load(LoadOptions{Path: main, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{
Path: configkit.Keys("promptkit_sources"), Value: []any{map[string]any{"file": "cli.yml"}}, Flag: "--promptkit-source",
}}})
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "cli.yml"}}) {
t.Fatalf("CLI list did not replace selectors: result=%+v err=%v", result, err)
}
writeApplicationFile(t, peer, "promptkit_sources:\n - file: a.yml\n")
if _, err := Load(LoadOptions{Path: main, Explicit: true}); err == nil {
t.Fatal("duplicate authored peer identity accepted")
}
}
func TestLoadOverrideCannotRepairDecodeError(t *testing.T) {
path := filepath.Join(t.TempDir(), "config.yml")
writeApplicationFile(t, path, "server:\n max_request_bytes: not-a-number\n")
_, err := Load(LoadOptions{Path: path, Explicit: true, Overrides: []configkit.Override{{
Path: configkit.Keys("server", "max_request_bytes"), Value: int64(12), Flag: "--max-request-bytes",
}}})
if err == nil {
t.Fatal("override repaired an undecodable source value")
}
}

View File

@@ -14,8 +14,7 @@ var defaultConfigSearchPaths = []string{
// AppSettings holds the validated application values used by executable adapters. // AppSettings holds the validated application values used by executable adapters.
type AppSettings struct { type AppSettings struct {
PromptDir string PromptKitSources []SourceSelection
ProfileDir string
SchemaDir string SchemaDir string
ServerAddr string ServerAddr string
ArtifactRoot string ArtifactRoot string
@@ -23,15 +22,5 @@ type AppSettings struct {
MaxArtifactBytes int64 MaxArtifactBytes int64
MaxResponseBytes int64 MaxResponseBytes int64
DefaultRenderFormat renderformat.PreparedRunOutputFormat DefaultRenderFormat renderformat.PreparedRunOutputFormat
Backends []BackendSettings
TransientRetries *int TransientRetries *int
} }
type BackendSettings struct {
ID string
Endpoint string
APIKeyEnv string
ExtraParams map[string]any
ConcurrencyLimit int
QueueCapacity *int
}

View File

@@ -7,50 +7,49 @@ import (
"fmt" "fmt"
"strconv" "strconv"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/promptkit"
) )
type PromptInspection struct { type PromptInspection struct {
PromptID string `json:"prompt_id"` PromptID string `json:"prompt_id"`
PromptVersion string `json:"prompt_version"`
PromptHash string `json:"prompt_hash"` PromptHash string `json:"prompt_hash"`
DefaultProfileID string `json:"default_profile_id"` DefaultProfileID *string `json:"default_profile_id,omitempty"`
Inputs []PromptInspectionInput `json:"inputs"` Inputs *[]PromptInspectionInput `json:"inputs,omitempty"`
OutputContract OutputContract `json:"output_contract"` OutputContract OutputContract `json:"output_contract"`
} }
type PromptInspectionInput struct { type PromptInspectionInput struct {
Name string `json:"name"` Name string `json:"name"`
Required bool `json:"required"` Required *bool `json:"required,omitempty"`
ContentType string `json:"content_type"` ContentType *string `json:"content_type,omitempty"`
Description string `json:"description"` Description *string `json:"description,omitempty"`
} }
type OutputContract struct { type OutputContract struct {
Format string `json:"format"` Format string `json:"format"`
ValidationMode string `json:"validation_mode"` ValidationMode string `json:"validation_mode"`
SchemaPath string `json:"schema_path"` SchemaPath *string `json:"schema_path,omitempty"`
RepairAttempts int `json:"repair_attempts"` RepairAttempts *int `json:"repair_attempts,omitempty"`
} }
type ProfileInspection struct { type ProfileInspection struct {
ProfileID string `json:"profile_id"` ProfileID string `json:"profile_id"`
EffectiveModelParams ProfileModelParams `json:"effective_model_params"` ProfileModelParams ProfileModelParams `json:"profile_model_params"`
APIKeyRequired bool `json:"api_key_required"` APIKeyRequired *bool `json:"api_key_required,omitempty"`
} }
type ProfileModelParams struct { type ProfileModelParams struct {
BackendID string `json:"backend_id"` BackendID *string `json:"backend_id,omitempty"`
Endpoint string `json:"endpoint"` Endpoint *string `json:"endpoint,omitempty"`
Model string `json:"model"` Model *string `json:"model,omitempty"`
Temperature float64 `json:"temperature"` Temperature *float64 `json:"temperature,omitempty"`
MaxTokens int `json:"max_tokens"` MaxTokens *int `json:"max_tokens,omitempty"`
TopP float64 `json:"top_p"` TopP *float64 `json:"top_p,omitempty"`
TimeoutSeconds int `json:"timeout_seconds"` TimeoutSeconds *int `json:"timeout_seconds,omitempty"`
ServiceTier string `json:"service_tier"` ServiceTier *string `json:"service_tier,omitempty"`
ReasoningEffort string `json:"reasoning_effort"` ReasoningEffort *string `json:"reasoning_effort,omitempty"`
APIKeyEnv string `json:"api_key_env"` APIKeyEnv *string `json:"api_key_env,omitempty"`
ExtraParams map[string]any `json:"extra_params"` ExtraParams *map[string]any `json:"extra_params,omitempty"`
} }
func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat OutputFormat) ([]byte, error) { func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat OutputFormat) ([]byte, error) {
@@ -58,12 +57,15 @@ func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat Outp
return nil, errors.New("prompt inspection is nil") return nil, errors.New("prompt inspection is nil")
} }
dto := PromptInspection{ dto := PromptInspection{
PromptID: value.PromptID, PromptVersion: value.PromptVersion, PromptHash: value.PromptHash, DefaultProfileID: value.DefaultProfileID, PromptID: value.PromptID, PromptHash: value.PromptHash, DefaultProfileID: value.DefaultProfileID,
Inputs: make([]PromptInspectionInput, len(value.Inputs)),
OutputContract: OutputContract{Format: string(value.OutputContract.Format), ValidationMode: string(value.OutputContract.ValidationMode), SchemaPath: value.OutputContract.SchemaPath, RepairAttempts: value.OutputContract.RepairAttempts}, OutputContract: OutputContract{Format: string(value.OutputContract.Format), ValidationMode: string(value.OutputContract.ValidationMode), SchemaPath: value.OutputContract.SchemaPath, RepairAttempts: value.OutputContract.RepairAttempts},
} }
for i, input := range value.Inputs { if value.Inputs != nil {
dto.Inputs[i] = PromptInspectionInput{Name: input.Name, Required: input.Required, ContentType: input.ContentType, Description: input.Description} inputs := make([]PromptInspectionInput, len(*value.Inputs))
for i, input := range *value.Inputs {
inputs[i] = PromptInspectionInput{Name: input.Name, Required: input.Required, ContentType: input.ContentType, Description: input.Description}
}
dto.Inputs = &inputs
} }
switch outputFormat { switch outputFormat {
case OutputFormatJSON: case OutputFormatJSON:
@@ -74,16 +76,36 @@ func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat Outp
return append(data, '\n'), nil return append(data, '\n'), nil
case OutputFormatText: case OutputFormatText:
var b bytes.Buffer var b bytes.Buffer
fmt.Fprintf(&b, "prompt_id: %s\nprompt_version: %s\nprompt_hash: %s\ndefault_profile_id: %s\ninputs:", dto.PromptID, dto.PromptVersion, dto.PromptHash, dto.DefaultProfileID) fmt.Fprintf(&b, "prompt_id: %s\nprompt_hash: %s\n", dto.PromptID, dto.PromptHash)
if len(dto.Inputs) == 0 { if dto.DefaultProfileID != nil {
fmt.Fprintln(&b, " []") fmt.Fprintf(&b, "default_profile_id: %s\n", *dto.DefaultProfileID)
}
if dto.Inputs != nil {
if len(*dto.Inputs) == 0 {
fmt.Fprintln(&b, "inputs: []")
} else { } else {
fmt.Fprintln(&b) fmt.Fprintln(&b, "inputs:")
for _, input := range dto.Inputs { for _, input := range *dto.Inputs {
fmt.Fprintf(&b, " - name: %s\n required: %t\n content_type: %s\n description: %s\n", input.Name, input.Required, input.ContentType, strconv.Quote(input.Description)) fmt.Fprintf(&b, " - name: %s\n", input.Name)
if input.Required != nil {
fmt.Fprintf(&b, " required: %t\n", *input.Required)
}
if input.ContentType != nil {
fmt.Fprintf(&b, " content_type: %s\n", *input.ContentType)
}
if input.Description != nil {
fmt.Fprintf(&b, " description: %s\n", strconv.Quote(*input.Description))
} }
} }
fmt.Fprintf(&b, "output_contract:\n format: %s\n validation_mode: %s\n schema_path: %s\n repair_attempts: %d\n", dto.OutputContract.Format, dto.OutputContract.ValidationMode, dto.OutputContract.SchemaPath, dto.OutputContract.RepairAttempts) }
}
fmt.Fprintf(&b, "output_contract:\n format: %s\n validation_mode: %s\n", dto.OutputContract.Format, dto.OutputContract.ValidationMode)
if dto.OutputContract.SchemaPath != nil {
fmt.Fprintf(&b, " schema_path: %s\n", *dto.OutputContract.SchemaPath)
}
if dto.OutputContract.RepairAttempts != nil {
fmt.Fprintf(&b, " repair_attempts: %d\n", *dto.OutputContract.RepairAttempts)
}
return b.Bytes(), nil return b.Bytes(), nil
default: default:
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat) return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)
@@ -94,12 +116,11 @@ func FormatProfileInspection(value *promptkit.ProfileInspection, outputFormat Ou
if value == nil { if value == nil {
return nil, errors.New("profile inspection is nil") return nil, errors.New("profile inspection is nil")
} }
target := value.EffectiveModelParams dto := ProfileInspection{ProfileID: value.ProfileID, APIKeyRequired: value.APIKeyRequired, ProfileModelParams: ProfileModelParams{
params := map[string]any{} BackendID: value.Backend, Endpoint: value.Endpoint, Model: value.Model, Temperature: value.Temperature,
for key, item := range target.ExtraParams { MaxTokens: value.MaxTokens, TopP: value.TopP, TimeoutSeconds: value.TimeoutSeconds, ServiceTier: value.ServiceTier,
params[key] = item ReasoningEffort: value.ReasoningEffort, APIKeyEnv: value.APIKeyEnv, ExtraParams: value.ExtraParams,
} }}
dto := ProfileInspection{ProfileID: value.ProfileID, APIKeyRequired: value.APIKeyRequired, EffectiveModelParams: ProfileModelParams{BackendID: target.BackendID, Endpoint: target.Endpoint, Model: target.Model, Temperature: target.Temperature, MaxTokens: target.MaxTokens, TopP: target.TopP, TimeoutSeconds: target.TimeoutSeconds, ServiceTier: target.ServiceTier, ReasoningEffort: target.ReasoningEffort, APIKeyEnv: target.APIKeyEnv, ExtraParams: params}}
switch outputFormat { switch outputFormat {
case OutputFormatJSON: case OutputFormatJSON:
data, err := json.MarshalIndent(dto, "", " ") data, err := json.MarshalIndent(dto, "", " ")
@@ -109,12 +130,48 @@ func FormatProfileInspection(value *promptkit.ProfileInspection, outputFormat Ou
return append(data, '\n'), nil return append(data, '\n'), nil
case OutputFormatText: case OutputFormatText:
var b bytes.Buffer var b bytes.Buffer
fmt.Fprintf(&b, "profile_id: %s\neffective_model_params:\n backend_id: %s\n endpoint: %s\n model: %s\n temperature: %g\n max_tokens: %d\n top_p: %g\n timeout_seconds: %d\n service_tier: %s\n reasoning_effort: %s\n api_key_env: %s\n extra_params: ", dto.ProfileID, dto.EffectiveModelParams.BackendID, dto.EffectiveModelParams.Endpoint, dto.EffectiveModelParams.Model, dto.EffectiveModelParams.Temperature, dto.EffectiveModelParams.MaxTokens, dto.EffectiveModelParams.TopP, dto.EffectiveModelParams.TimeoutSeconds, dto.EffectiveModelParams.ServiceTier, dto.EffectiveModelParams.ReasoningEffort, dto.EffectiveModelParams.APIKeyEnv) fmt.Fprintf(&b, "profile_id: %s\nprofile_model_params:\n", dto.ProfileID)
paramsJSON, err := json.Marshal(dto.EffectiveModelParams.ExtraParams) p := dto.ProfileModelParams
if p.BackendID != nil {
fmt.Fprintf(&b, " backend_id: %s\n", *p.BackendID)
}
if p.Endpoint != nil {
fmt.Fprintf(&b, " endpoint: %s\n", *p.Endpoint)
}
if p.Model != nil {
fmt.Fprintf(&b, " model: %s\n", *p.Model)
}
if p.Temperature != nil {
fmt.Fprintf(&b, " temperature: %g\n", *p.Temperature)
}
if p.MaxTokens != nil {
fmt.Fprintf(&b, " max_tokens: %d\n", *p.MaxTokens)
}
if p.TopP != nil {
fmt.Fprintf(&b, " top_p: %g\n", *p.TopP)
}
if p.TimeoutSeconds != nil {
fmt.Fprintf(&b, " timeout_seconds: %d\n", *p.TimeoutSeconds)
}
if p.ServiceTier != nil {
fmt.Fprintf(&b, " service_tier: %s\n", *p.ServiceTier)
}
if p.ReasoningEffort != nil {
fmt.Fprintf(&b, " reasoning_effort: %s\n", *p.ReasoningEffort)
}
if p.APIKeyEnv != nil {
fmt.Fprintf(&b, " api_key_env: %s\n", *p.APIKeyEnv)
}
if p.ExtraParams != nil {
paramsJSON, err := json.Marshal(p.ExtraParams)
if err != nil { if err != nil {
return nil, err return nil, err
} }
fmt.Fprintf(&b, "%s\napi_key_required: %t\n", paramsJSON, dto.APIKeyRequired) fmt.Fprintf(&b, " extra_params: %s\n", paramsJSON)
}
if dto.APIKeyRequired != nil {
fmt.Fprintf(&b, "api_key_required: %t\n", *dto.APIKeyRequired)
}
return b.Bytes(), nil return b.Bytes(), nil
default: default:
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat) return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)

View File

@@ -5,120 +5,91 @@ import (
"strings" "strings"
"testing" "testing"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/promptkit"
) )
func TestFormatPromptInspectionPreservesDeclaredOrderAndEmptyValues(t *testing.T) { func ptr[T any](value T) *T { return &value }
value := &promptkit.PromptInspection{PromptID: "p", PromptVersion: "1", PromptHash: "hash", Inputs: []promptkit.PromptInputDefinition{{Name: "first", Required: true, ContentType: "text/plain", Description: "first input"}, {Name: "second"}}, OutputContract: promptkit.OutputContract{Format: "text", ValidationMode: promptkit.ValidationNone}}
text, err := FormatPromptInspection(value, OutputFormatText)
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(text), "default_profile_id: \ninputs:\n - name: first") || strings.Index(string(text), "name: first") > strings.Index(string(text), "name: second") {
t.Fatalf("unexpected text inspection: %s", text)
}
jsonOutput, err := FormatPromptInspection(value, OutputFormatJSON)
if err != nil {
t.Fatal(err)
}
if !strings.HasSuffix(string(jsonOutput), "\n") || !strings.Contains(string(jsonOutput), `"default_profile_id": ""`) {
t.Fatalf("unexpected json inspection: %s", jsonOutput)
}
}
func TestFormatPromptInspectionRejectsNil(t *testing.T) { func TestPromptInspectionOptionalFieldsAndDisclosure(t *testing.T) {
inputs := []promptkit.PromptInputInspection{{Name: "first", Required: ptr(false), ContentType: ptr(""), Description: ptr("")}, {Name: "second"}}
value := &promptkit.PromptInspection{PromptID: "support/p", PromptHash: "hash", DefaultProfileID: ptr(""), Inputs: &inputs,
Messages: []promptkit.PromptMessageInspection{{Role: "user", Content: "private message"}}, Description: ptr("private description"), SessionID: ptr("private session"),
OutputContract: promptkit.PromptOutputInspection{Format: "text", ValidationMode: promptkit.ValidationNone, SchemaPath: ptr(""), RepairAttempts: ptr(0)}}
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
output, err := FormatPromptInspection(value, format)
if err != nil {
t.Fatal(err)
}
s := string(output)
for _, forbidden := range []string{"private message", "private description", "private session", "prompt_version"} {
if strings.Contains(s, forbidden) {
t.Fatalf("inspection exposed %q: %s", forbidden, s)
}
}
if strings.Index(s, "first") > strings.Index(s, "second") {
t.Fatalf("input order changed: %s", s)
}
if !strings.Contains(s, "default_profile_id") || !strings.Contains(s, "repair_attempts") || !strings.Contains(s, "required") {
t.Fatalf("present empty values missing: %s", s)
}
}
value.DefaultProfileID, value.Inputs = nil, nil
value.OutputContract.SchemaPath, value.OutputContract.RepairAttempts = nil, nil
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
output, err := FormatPromptInspection(value, format)
if err != nil {
t.Fatal(err)
}
for _, absent := range []string{"default_profile_id", "inputs", "schema_path", "repair_attempts"} {
if strings.Contains(string(output), absent) {
t.Fatalf("absent %s rendered: %s", absent, output)
}
}
}
empty := []promptkit.PromptInputInspection{}
value.Inputs = &empty
output, err := FormatPromptInspection(value, OutputFormatJSON)
if err != nil || !strings.Contains(string(output), `"inputs": []`) {
t.Fatalf("empty inputs lost: %s %v", output, err)
}
if _, err := FormatPromptInspection(nil, OutputFormatText); err == nil { if _, err := FormatPromptInspection(nil, OutputFormatText); err == nil {
t.Fatal("expected nil inspection error") t.Fatal("nil prompt accepted")
} }
} }
func TestFormatProfileInspectionPreservesSafeEffectiveValues(t *testing.T) { func TestProfileInspectionPreservesOnlyPresentValues(t *testing.T) {
const secret = "sentinel-secret-must-not-appear" params := map[string]any{}
t.Setenv("FIXTURE_PROFILE_API_KEY", secret) value := &promptkit.ProfileInspection{ProfileID: "support/fast", Backend: ptr("backend"), Model: ptr(""), Temperature: ptr(0.0), MaxTokens: ptr(0), APIKeyRequired: ptr(false), ExtraParams: &params}
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
value := &promptkit.ProfileInspection{ output, err := FormatProfileInspection(value, format)
ProfileID: "custom-derived",
EffectiveModelParams: promptkit.ExecutionTarget{
BackendID: "fixture-custom",
Endpoint: "http://127.0.0.1:11434/v1",
Model: "fixture-model",
Temperature: 0.25,
MaxTokens: 640,
TopP: 0.9,
TimeoutSeconds: 45,
ServiceTier: "flex",
ReasoningEffort: "high",
APIKeyEnv: "FIXTURE_PROFILE_API_KEY",
ExtraParams: map[string]any{
"zeta": true,
"alpha": map[string]any{"nested": []any{"first", 2.0}},
},
},
APIKeyRequired: true,
}
jsonOutput, err := FormatProfileInspection(value, OutputFormatJSON)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
secondJSONOutput, err := FormatProfileInspection(value, OutputFormatJSON) s := string(output)
for _, key := range []string{"profile_model_params", "backend_id", "model", "temperature", "max_tokens", "api_key_required", "extra_params"} {
if !strings.Contains(s, key) {
t.Fatalf("present %s missing: %s", key, s)
}
}
for _, key := range []string{"effective_model_params", "endpoint", "api_key_env", "top_p"} {
if strings.Contains(s, key) {
t.Fatalf("absent %s appeared: %s", key, s)
}
}
}
output, err := FormatProfileInspection(value, OutputFormatJSON)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
if string(jsonOutput) != string(secondJSONOutput) || !strings.HasSuffix(string(jsonOutput), "\n") { var decoded map[string]any
t.Fatalf("expected deterministic newline-terminated JSON, got %q", jsonOutput) if err := json.Unmarshal(output, &decoded); err != nil {
}
if strings.Contains(string(jsonOutput), secret) {
t.Fatalf("inspection exposed an environment secret: %s", jsonOutput)
}
var decoded ProfileInspection
if err := json.Unmarshal(jsonOutput, &decoded); err != nil {
t.Fatalf("decode profile inspection: %v", err)
}
if decoded.ProfileID != "custom-derived" || decoded.EffectiveModelParams.BackendID != "fixture-custom" {
t.Fatalf("unexpected profile identity: %+v", decoded)
}
if decoded.EffectiveModelParams.APIKeyEnv != "FIXTURE_PROFILE_API_KEY" || !decoded.APIKeyRequired {
t.Fatalf("unexpected credential metadata: %+v", decoded)
}
alpha, ok := decoded.EffectiveModelParams.ExtraParams["alpha"].(map[string]any)
if !ok || len(alpha["nested"].([]any)) != 2 {
t.Fatalf("nested extra parameters were not preserved: %#v", decoded.EffectiveModelParams.ExtraParams)
}
textOutput, err := FormatProfileInspection(value, OutputFormatText)
if err != nil {
t.Fatal(err) t.Fatal(err)
} }
textValue := string(textOutput) p := decoded["profile_model_params"].(map[string]any)
if !strings.Contains(textValue, "backend_id: fixture-custom") || if p["backend_id"] != "backend" || p["model"] != "" || p["temperature"] != float64(0) || decoded["api_key_required"] != false || len(p["extra_params"].(map[string]any)) != 0 {
!strings.Contains(textValue, "api_key_env: FIXTURE_PROFILE_API_KEY") || t.Fatalf("wrong values: %#v", decoded)
!strings.Contains(textValue, `extra_params: {"alpha":{"nested":["first",2]},"zeta":true}`) ||
!strings.Contains(textValue, "api_key_required: true") {
t.Fatalf("unexpected text inspection: %s", textValue)
}
if strings.Contains(textValue, secret) {
t.Fatalf("text inspection exposed an environment secret: %s", textValue)
}
}
func TestFormatProfileInspectionPreservesEmptyBackendAndRejectsNil(t *testing.T) {
output, err := FormatProfileInspection(&promptkit.ProfileInspection{
ProfileID: "endpoint-only",
EffectiveModelParams: promptkit.ExecutionTarget{
Endpoint: "http://127.0.0.1:8000/v1",
Model: "fixture-model",
},
}, OutputFormatJSON)
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(output), `"backend_id": ""`) ||
!strings.Contains(string(output), `"extra_params": {}`) {
t.Fatalf("expected explicit empty backend and object extra params, got %s", output)
} }
if _, err := FormatProfileInspection(nil, OutputFormatText); err == nil { if _, err := FormatProfileInspection(nil, OutputFormatText); err == nil {
t.Fatal("expected nil profile inspection error") t.Fatal("nil profile accepted")
} }
} }

View File

@@ -9,7 +9,7 @@ import (
"sort" "sort"
"strings" "strings"
"gitea.maximumdirect.net/eric/promptkit" "go.maximumdirect.net/promptkit"
) )
var ErrUnknownPreparedRunFormat = errors.New("unknown prepared run format") var ErrUnknownPreparedRunFormat = errors.New("unknown prepared run format")
@@ -106,7 +106,6 @@ func (textPreparedRunFormatter) Format(prepared *promptkit.PreparedRun) ([]byte,
var b bytes.Buffer var b bytes.Buffer
fmt.Fprintf(&b, "prompt: %s\n", prepared.PromptID) fmt.Fprintf(&b, "prompt: %s\n", prepared.PromptID)
fmt.Fprintf(&b, "prompt_version: %s\n", prepared.PromptVersion)
fmt.Fprintf(&b, "selected_profile_id: %s\n", prepared.SelectedProfileID) fmt.Fprintf(&b, "selected_profile_id: %s\n", prepared.SelectedProfileID)
if prepared.SelectedBackendID != "" { if prepared.SelectedBackendID != "" {
fmt.Fprintf(&b, "selected_backend_id: %s\n", prepared.SelectedBackendID) fmt.Fprintf(&b, "selected_backend_id: %s\n", prepared.SelectedBackendID)

Some files were not shown because too many files have changed in this diff Show More