102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# 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](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md).
|
|
|
|
## 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](../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 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. 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.
|
|
|
|
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 API-key environment values; ordinary backend
|
|
parameters remain visible by the selected inspection policy.
|
|
|
|
## 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.
|