# 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](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). ## 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 ConfigKit 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](../config.md) 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 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 owns strict application YAML decoding and presence semantics. Framework configuration is separately loaded by Promptkit through ConfigKit under Promptkit's own schema and source contract. 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. File-backed loads enable explicit ConfigKit imports and select one named overlay when requested. 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. 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](../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. ## 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](../config.md), [HTTP](../api.md), and [operations](../operations.md) contracts as applicable; and 5. do not duplicate Promptkit loaders, formats, or ordinary artifact behavior.