scriptorium/docs/internal/sources.md

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 format reference.

Application Source Locations

internal/config resolves prompt_dir, profile_dir, and schema_dir from Scriptorium defaults, configuration files, and CLI overrides. It also resolves the application-owned backends mapping into sorted engine settings. internal/adapter/cli passes the directories into promptkit.Config and maps each configured backend to Promptkit's public engine registration when constructing an engine shared by the command path.

Scriptorium does not search, parse, validate, or overlay framework source files itself. Promptkit owns prompt selection, profile built-ins and overlays, schema resolution, ordinary file artifacts, and the related error identities.

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 a ConfigKit-native Document definition. Its fresh defaults come from Scriptorium's existing default constants; its resolver records only actual trimming, path cleaning, and render-format normalization. The validator reports application retry, size-limit, and format errors without mutating the document or exposing rejected values. Application path values keep working-directory-relative meaning. ConfigKit owns strict YAML decoding and presence semantics, including dynamic integer values in backend parameters.

The Load boundary selects an explicit file, the first existing implicit configuration file, or ConfigKit's defaults-only source. Only absence advances implicit discovery. One ConfigKit load applies explicit application overrides before validation and returns a result containing the resolved document and its frozen inspection records. Settings converts that document into the existing runtime settings with backend IDs sorted; it does not read files or apply another merge. Imports and selected overlays remain disabled until their own user-facing integration is ready.

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. The old application YAML decoder and merge path have been removed.

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.go
• internal/config/load_test.go
• internal/adapter/cli/run_test.go
• internal/adapter/http/artifact_reader_test.go
• internal/adapter/http/handler_test.go

When changing an application source location or HTTP artifact policy:

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, HTTP, and operations contracts as applicable; and
5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.