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. internal/adapter/cli passes those paths into promptkit.Config when constructing the engine.

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.

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/config_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.