Files
scriptorium/docs/internal/sources.md

56 lines
3.2 KiB
Markdown
Raw Normal View History

# Source Internals
This document covers application acquisition and the restricted HTTP artifact
reader. [Configuration](../config.md) owns field/discovery/composition contracts;
the [PromptKit formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
own framework resources and execution semantics.
## Application Boundary And Engine Construction
`internal/config.Load` selects an explicit File or the ordered native SearchConfig
presets and performs one ConfigKit load with imports, overlay selection, and
explicit overrides. It returns the actual Result with native inspection evidence.
Definition callbacks supply application defaults, record actual path/address
normalizations through ConfigKit, and validate retry/HTTP-size domains. Settings
conversion consumes completed values without another merge or normalization pass.
The typed application PromptKit section selects acquisition only. In
`engine.go`, a nonempty resolved configuration path becomes an import-enabled
main Input; an empty path leaves Main nil. The schema base and retry default are
passed directly, retaining the bundled underlay. There is no source-list parser,
directory classification/expansion, or one-underlay-per-selector algorithm.
Framework imports resolve within the native source context. Message resources
are captured from their defining contexts at engine construction. Schema and
request-artifact acquisition retain their preparation-time behavior.
Independent collection checkouts are discovered by native file import globs,
not application traversal. New invocations reload normally; a server retains
its single engine until restart.
Application-only inspection uses its completed result without framework
acquisition. Framework inspection exposes the native captured view separately.
Diagnostic decoration in the [CLI adapter](adapters.md) carries application
messages without combining evidence trees or effective documents. There is no
per-invocation engine/config cache or cross-invocation snapshot guarantee.
## Restricted HTTP Artifact Reader
The HTTP adapter implements `promptkit.ArtifactReader`; server construction
injects it through the public option. Ordinary CLI artifact loading remains
upstream-owned.
The reader accepts inline content without a root. File references need a root;
relative paths resolve below it and absolute paths must be lexically contained.
Traversal outside is rejected and the configured file byte limit applies, with
zero unlimited. Reads preserve native artifact metadata and honor cancellation.
Containment does not resolve symlinks. The OS may follow a symlink inside the
root to an outside target; this is not a filesystem sandbox or a defense against
privileged concurrent filesystem modification. Reader errors retain identity
through upstream artifact-load wrapping, enabling the existing HTTP mapping.
The [HTTP API](../api.md) owns outcomes and [operations](../operations.md) owns
safe root/permission selection. Configuration, CLI acquisition/engine, and HTTP
reader/handler tests own their respective boundaries; upstream owns exhaustive
source traversal, format parsing, ordinary artifacts, and inspection semantics.