5.8 KiB
Source Internals
Purpose
This document covers Scriptorium-owned source locations and the restricted HTTP artifact reader. Prompt, profile, schema, and ordinary artifact semantics are owned by the tagged Promptkit v0.12.0 format reference.
Application Source Locations
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
old-path ConfigKit v0.5.0 inputs and expands directory selections with
promptkit.DirectoryInputs, then passes the ordered groups as Promptkit
configuration underlays. The shared Promptkit engine receives the selected
schema directory and retry setting as well.
Promptkit uses ConfigKit to load and compose those framework inputs according to Promptkit's own schema and format. Scriptorium does not parse or validate Promptkit definitions. Promptkit owns definition selection and validation, profile built-ins and overlays, schema resolution, ordinary file artifacts, captured framework configuration inspection, and related error identities.
The configuration reference owns Scriptorium's source-location
fields and precedence. Maintained files under examples/ are application
inputs that use Promptkit's tagged formats.
Application Configuration Boundary
internal/config contains the application-owned ConfigKit-native Document
definition. Its fresh defaults come from Scriptorium's existing default
constants; its resolver records only actual leaf-level trimming, path cleaning, and
render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative
meaning. ConfigKit v1.2.0 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through
its older ConfigKit under Promptkit's own schema and source contract.
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
canonical directory as the source root; the application does not widen it.
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
explicitly visited application flags to ConfigKit overrides and prints
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.
Application config inspection reuses the result's frozen effective,
provenance, and history views without constructing an engine or reloading
sources. It does not resolve credentials. inspect configuration separately
constructs an engine and exposes Promptkit's captured framework view; only its
framework show and explain reports receive Promptkit's native,
credential-shaped redaction. Neither inspection family is a general-purpose
filter for arbitrary sensitive values.
Restricted HTTP Artifact Reader
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 owns observable request outcomes, and operations 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.
Verification And Change Recipe
Inspect:
internal/config/document_test.gointernal/config/load_test.gointernal/adapter/cli/run_test.gointernal/adapter/http/artifact_reader_test.gointernal/adapter/http/handler_test.go
When changing an application source location or HTTP artifact policy:
- preserve strict configuration precedence and the Promptkit public boundary;
- keep containment and size policy in Scriptorium;
- update focused configuration, reader, and handler tests;
- update the configuration, HTTP, and operations contracts as applicable; and
- do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.