# Source Internals

## Purpose

This document describes how source packages load prompt definitions, profiles,
schemas, and artifacts. The [configuration reference](../config.md) owns their
user-facing formats and settings. The [HTTP API reference](../api.md) owns
HTTP-visible artifact outcomes; [operations](../operations.md) owns deployment
handling.

## Prompt Definitions

`internal/promptdef` provides filesystem and `fs.FS` repositories. Both use
`internal/filecatalog` for recursive YAML discovery, deterministic ordering,
display paths, and root cleaning.

Repositories select a prompt by YAML ID and optional version rather than by
path. They decode through strict YAML handling, reject duplicate matching
definitions, and resolve `content_file` relative to the definition. The `fs.FS`
implementation resolves content paths inside its source root; absolute paths and
traversal outside that root are rejected before file access.

## Profiles And Built-Ins

`internal/profile` provides filesystem, `fs.FS`, and overlay repositories.
`internal/profile/builtin` exposes embedded assets through the same repository
interface.

An overlay asks its primary source first. It falls back only when the primary
reports `ErrProfileNotFound`; invalid YAML, duplicate IDs, validation failures,
and raw-key failures are returned rather than hidden by fallback. This makes a
custom ID override a built-in ID while retaining errors in the custom source.

The public engine can overlay in-memory profiles ahead of both file-backed and
built-in repositories. Profile field definitions, validation ranges, and the
built-in catalog remain in the [configuration reference](../config.md).

## Schemas

`internal/validate` supplies `StandardValidator` for filesystem sources and
`FSValidator` for `fs.FS` sources. Directory-backed validation loads the named
schema path; it does not search directories by basename. `fs.FS` schema paths
are cleaned and checked against their configured root, while a single-file
source matches its file base name.

The runner requests a schema document before generation when it needs
structured output. JSON and schema mismatches in generated content are
validation results; source access, decoding, registration, and compilation
failures are operational errors.

## Artifacts

`internal/artifact` owns the framework's ordinary inline and unrestricted file
reader. The public engine uses it by default and permits consumers to replace it
for every input through the public `ArtifactReader` extension. The
HTTP adapter owns its restricted reader for HTTP containment: `serve` injects
that reader into the public engine with `WithArtifactReader`.

The rooted reader cleans paths and applies lexical containment without resolving
symlinks. It checks relative references against the configured root and accepts
absolute references only when they remain inside that lexical root. The OS still
follows symlinks after that check. The public containment outcome is documented
by the [HTTP API reference](../api.md); deployment permissions belong in
[operations](../operations.md).

## Failure Boundaries

Source packages report repository, decoding, duplicate, validation, and read
failures to their callers. They do not select public status codes or response
schemas. The runner categorizes source failures and the public engine preserves
the corresponding public error identities; adapters map those identities to
their own external contract.

Source reads use current filesystem or `fs.FS` content for each request. These
packages create no manifests, checkpoints, or durable run state.

## Verification And Change Recipe

Inspect:

- `internal/promptdef/repository_test.go`
- `internal/profile/repository_test.go`
- `internal/profile/builtin/repository_test.go`
- `internal/artifact/reader_test.go`
- `internal/adapter/http/artifact_reader_test.go`
- `internal/validate/standard_validator_test.go`
- `engine_test.go`

When updating prompt, profile, schema, or built-in assets:

1. keep assets valid for the strict loader and the relevant source boundary;
2. update the [configuration reference](../config.md) when a file-format,
   catalog, or default changes;
3. run focused source and integration tests, including the built-in repository
   test when embedded assets change; and
4. update this document when discovery, precedence, containment, or failure
   mechanics change.

The [testing policy](../policy/testing.md) owns global test sufficiency.