2026-07-05 03:13:50 +00:00
|
|
|
# Source Internals
|
|
|
|
|
|
|
|
|
|
## Purpose
|
|
|
|
|
|
2026-07-28 14:21:19 +00:00
|
|
|
This document covers Scriptorium-owned source locations and the restricted HTTP
|
|
|
|
|
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
|
|
|
|
|
owned by the tagged
|
2026-10-04 13:11:48 +00:00
|
|
|
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
2026-07-28 14:21:19 +00:00
|
|
|
|
|
|
|
|
## Application Source Locations
|
|
|
|
|
|
2026-10-04 13:11:48 +00:00
|
|
|
`internal/config` resolves the ordered `promptkit_sources` sequence and
|
|
|
|
|
`schema_dir` from application configuration and explicit CLI overrides. It
|
|
|
|
|
owns selector-shape validation, not framework file parsing. During engine
|
|
|
|
|
construction, `internal/adapter/cli` turns file selections into import-enabled
|
2026-11-17 22:15:10 +00:00
|
|
|
old-path ConfigKit v0.5.0 inputs and expands directory selections with
|
2026-10-04 13:11:48 +00:00
|
|
|
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
|
|
|
|
|
configuration underlays. The shared Promptkit engine receives the selected
|
|
|
|
|
schema directory and retry setting as well.
|
|
|
|
|
|
|
|
|
|
Promptkit uses ConfigKit to load and compose those framework inputs according
|
|
|
|
|
to Promptkit's own schema and format. Scriptorium does not parse or validate
|
|
|
|
|
Promptkit definitions. Promptkit owns definition selection and validation,
|
|
|
|
|
profile built-ins and overlays, schema resolution, ordinary file artifacts,
|
|
|
|
|
captured framework configuration inspection, and related error identities.
|
2026-07-28 14:21:19 +00:00
|
|
|
|
|
|
|
|
The [configuration reference](../config.md) owns Scriptorium's source-location
|
|
|
|
|
fields and precedence. Maintained files under `examples/` are application
|
|
|
|
|
inputs that use Promptkit's tagged formats.
|
|
|
|
|
|
2026-09-26 18:08:36 +00:00
|
|
|
## Application Configuration Boundary
|
2026-09-26 17:58:16 +00:00
|
|
|
|
2026-10-04 13:11:48 +00:00
|
|
|
`internal/config` contains the application-owned ConfigKit-native `Document`
|
|
|
|
|
definition. Its fresh defaults come from Scriptorium's existing default
|
2026-11-17 22:15:10 +00:00
|
|
|
constants; its resolver records only actual leaf-level trimming, path cleaning, and
|
2026-10-04 13:11:48 +00:00
|
|
|
render-format normalization. The validator reports selector-shape, retry,
|
|
|
|
|
size-limit, and format errors without mutating the document or exposing
|
|
|
|
|
rejected values. Application path values keep working-directory-relative
|
2026-11-17 22:15:10 +00:00
|
|
|
meaning. ConfigKit v1.2.0 owns strict application YAML decoding and presence
|
2026-10-04 13:11:48 +00:00
|
|
|
semantics. Framework configuration is separately loaded by Promptkit through
|
2026-11-17 22:15:10 +00:00
|
|
|
its older ConfigKit under Promptkit's own schema and source contract.
|
2026-09-26 18:00:50 +00:00
|
|
|
|
2026-11-17 22:15:10 +00:00
|
|
|
The `Load` boundary selects an explicit file or constructs a native ConfigKit
|
|
|
|
|
search over the ordered implicit paths. Discovery exhaustion uses defaults;
|
|
|
|
|
a selected-file error stops loading. One ConfigKit load enables imports,
|
|
|
|
|
applies explicitly supplied application overrides after decoding and before
|
|
|
|
|
resolution and validation, and returns the document and its frozen inspection
|
|
|
|
|
records. `Settings` copies selectors in their resolved order into runtime
|
|
|
|
|
settings; it does not read files or apply another merge. ConfigKit uses the selected file's
|
2026-09-26 18:12:27 +00:00
|
|
|
canonical directory as the source root; the application does not widen it.
|
|
|
|
|
Application path values retain process-working-directory-relative meaning.
|
2026-09-26 17:58:16 +00:00
|
|
|
|
2026-10-04 13:11:48 +00:00
|
|
|
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.
|
2026-10-03 17:43:58 +00:00
|
|
|
|
2026-09-26 18:08:36 +00:00
|
|
|
Every configuration-loading command uses this boundary. The CLI maps only
|
|
|
|
|
explicitly visited application flags to ConfigKit overrides and prints
|
2026-11-17 22:15:10 +00:00
|
|
|
structured load diagnostics before engine construction. Application and
|
|
|
|
|
framework load errors and warnings use their respective native writers. The old application
|
2026-09-26 18:08:36 +00:00
|
|
|
YAML decoder and merge path have been removed.
|
2026-09-26 18:21:38 +00:00
|
|
|
Application `config` inspection reuses the result's frozen effective,
|
|
|
|
|
provenance, and history views without constructing an engine or reloading
|
2026-10-04 13:11:48 +00:00
|
|
|
sources. It does not resolve credentials. `inspect configuration` separately
|
|
|
|
|
constructs an engine and exposes Promptkit's captured framework view; only its
|
|
|
|
|
framework `show` and `explain` reports receive Promptkit's native,
|
|
|
|
|
credential-shaped redaction. Neither inspection family is a general-purpose
|
|
|
|
|
filter for arbitrary sensitive values.
|
2026-09-26 17:58:16 +00:00
|
|
|
|
2026-07-28 14:21:19 +00:00
|
|
|
## Restricted HTTP Artifact Reader
|
|
|
|
|
|
|
|
|
|
`internal/adapter/http` implements `promptkit.ArtifactReader` for HTTP
|
|
|
|
|
requests. The `serve` path injects it with
|
|
|
|
|
`promptkit.WithArtifactReader`, replacing Promptkit's ordinary reader for
|
|
|
|
|
inbound HTTP inputs.
|
|
|
|
|
|
|
|
|
|
The reader:
|
|
|
|
|
|
|
|
|
|
- accepts inline references without an artifact root;
|
|
|
|
|
- denies file references when no root is configured;
|
|
|
|
|
- resolves relative paths below the configured root;
|
|
|
|
|
- accepts absolute paths only when they are lexically within that root;
|
|
|
|
|
- rejects lexical traversal outside the root;
|
|
|
|
|
- applies the configured file byte limit, with zero meaning unlimited;
|
|
|
|
|
- preserves content type, body, size, hash, name, and URI metadata; and
|
|
|
|
|
- honors context cancellation.
|
|
|
|
|
|
|
|
|
|
Containment is lexical and does not resolve symlinks. The operating system
|
|
|
|
|
follows symlinks after the check. The [HTTP API](../api.md) owns observable
|
|
|
|
|
request outcomes, and [operations](../operations.md) owns safe deployment
|
|
|
|
|
permissions and root selection.
|
|
|
|
|
|
|
|
|
|
Reader errors remain identifiable after Promptkit wraps them as artifact-load
|
|
|
|
|
failures, allowing the HTTP adapter to preserve Scriptorium status and error
|
|
|
|
|
codes.
|
2026-07-05 03:13:50 +00:00
|
|
|
|
2026-07-26 14:20:06 +00:00
|
|
|
## Verification And Change Recipe
|
2026-07-05 03:13:50 +00:00
|
|
|
|
2026-07-26 14:20:06 +00:00
|
|
|
Inspect:
|
2026-07-05 03:13:50 +00:00
|
|
|
|
2026-09-26 18:08:36 +00:00
|
|
|
- `internal/config/document_test.go`
|
|
|
|
|
- `internal/config/load_test.go`
|
2026-07-28 14:21:19 +00:00
|
|
|
- `internal/adapter/cli/run_test.go`
|
2026-07-28 00:40:25 +00:00
|
|
|
- `internal/adapter/http/artifact_reader_test.go`
|
2026-07-28 14:21:19 +00:00
|
|
|
- `internal/adapter/http/handler_test.go`
|
2026-07-26 14:06:55 +00:00
|
|
|
|
2026-07-28 14:21:19 +00:00
|
|
|
When changing an application source location or HTTP artifact policy:
|
2026-07-05 03:13:50 +00:00
|
|
|
|
2026-07-28 14:21:19 +00:00
|
|
|
1. preserve strict configuration precedence and the Promptkit public boundary;
|
|
|
|
|
2. keep containment and size policy in Scriptorium;
|
|
|
|
|
3. update focused configuration, reader, and handler tests;
|
|
|
|
|
4. update the [configuration](../config.md), [HTTP](../api.md), and
|
|
|
|
|
[operations](../operations.md) contracts as applicable; and
|
|
|
|
|
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.
|