promptkit/docs/internal/sources.md

Internal Sources And Validation

Purpose

This document describes Promptkit's implemented internal source, artifact, rendering, and output-validation behavior. The architecture policy owns the library boundary and dependency rules. None of these internal packages is a supported consumer API, and the root engine assembles them behind its public source options and values. The framework format reference owns the exact file fields, validation modes, built-in catalog, and source precedence.

Prompt Definitions

internal/promptdef discovers YAML deterministically, decodes and validates definitions, selects an ID and optional version, and resolves file-backed message content within the selected operating-system or fs.FS source.

Its package tests own prompt selection, strict decoding, definition validation, duplicate detection, and source containment: prompt-definition repository tests.

Profiles And Built-Ins

internal/profile loads and validates execution profiles from an operating-system filesystem or an fs.FS. It supports a primary repository with fallback only when the primary reports that a profile is absent.

internal/profile/builtin embeds the maintained built-in profile catalog and can place a caller-selected repository ahead of that catalog. Profile behavior is owned by the profile repository tests, while catalog completeness, duplicate IDs, and overlay behavior are owned by the built-in repository tests.

Ordinary Artifacts

internal/artifact resolves inline references and unrestricted, caller-selected file paths. It copies content into an artifact, records metadata and a content hash, applies a content-type fallback, and honors context cancellation.

This ordinary reader does not implement an inbound HTTP security boundary. In particular, it does not constrain files to an application root or impose an HTTP request-size policy. Scriptorium's restricted HTTP reader remains an application concern outside Promptkit. The artifact reader tests own the implemented reader behavior and failures.

Rendering

internal/prompt renders definition messages as Go templates using named artifacts and variables. It carries message roles, session IDs, and cache control into the rendered prompt. The renderer tests own rendering behavior.

Schemas And Output Validation

internal/validate provides validators backed by an operating-system filesystem or an fs.FS. Invalid generated content is returned as a validation result; inability to load, register, or compile a schema is an operational error.

The validator tests own basic, JSON, JSON Schema, source resolution, schema loading, compilation, and content-failure behavior.