Add artifact reading and output validation

docs/internal/overview.md

@@ -19,10 +19,12 @@ contributor workflow and validation.
 | `internal/profile` | Loads strictly decoded, validated execution profiles from filesystem and `fs.FS` sources and composes repositories with error-preserving fallback. | [Profile repositories](../../internal/profile/filesystem_repository.go) |
 | `internal/profile/builtin` | Embeds the built-in execution profile catalog and combines it with an optional primary repository. | [Built-in profile repository](../../internal/profile/builtin/repository.go) |
 | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) |
+| `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) |
+| `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources. | [Internal sources and validation](sources.md) |
 
 These packages provide the internal model, source, and rendering foundation.
-Artifact reading, output validation, model clients, orchestration, and a usable
-public engine are not implemented in Promptkit yet.
+Model clients, orchestration, and a usable public engine are not implemented in
+Promptkit yet.
 
 ## Maintenance
 

docs/internal/sources.md

@@ -0,0 +1,67 @@
+# Internal Sources And Validation
+
+## Purpose
+
+This document describes Promptkit's implemented internal source, artifact,
+rendering, and output-validation behavior. The
+[architecture policy](../policy/architecture.md) owns the library boundary and
+dependency rules. None of these internal packages is a supported consumer API,
+and the root package does not yet assemble them into a usable engine.
+
+## Prompt Definitions
+
+`internal/promptdef` loads prompt definitions from an operating-system
+filesystem or an `fs.FS`. It discovers YAML deterministically, decodes fields
+strictly, validates definitions, selects an ID and optional version, and
+resolves file-backed message content within the selected source.
+
+Its package tests own prompt selection, strict decoding, definition validation,
+duplicate detection, and source containment:
+[prompt-definition repository tests](../../internal/promptdef/repository_test.go).
+
+## Profiles And Built-Ins
+
+`internal/profile` loads strictly decoded execution profiles from an
+operating-system filesystem or an `fs.FS`. It validates required profile data,
+rejects raw API keys, and 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](../../internal/profile/repository_test.go), while
+catalog completeness, duplicate IDs, and overlay behavior are owned by the
+[built-in repository tests](../../internal/profile/builtin/repository_test.go).
+
+## 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](../../internal/artifact/reader_test.go) 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](../../internal/prompt/renderer_test.go) own rendering behavior.
+
+## Schemas And Output Validation
+
+`internal/validate` provides validators backed by an operating-system
+filesystem or an `fs.FS`. Validation can be skipped, require non-empty output,
+require JSON, or apply a JSON Schema loaded with the source's path semantics.
+Invalid generated content is returned as a validation result; inability to
+load, register, or compile a schema is an operational error.
+
+The [validator tests](../../internal/validate/standard_validator_test.go) own
+basic, JSON, JSON Schema, source resolution, schema loading, compilation, and
+content-failure behavior.