Add internal framework orchestration

docs/internal/overview.md

@@ -22,10 +22,11 @@ contributor workflow and validation.
 | `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) |
 | `internal/llm` | Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests, response decoding, authentication, and deadline handling. | [Internal model client](llm.md) |
+| `internal/usecase` | Coordinates preparation and execution across internal sources, rendering, artifact loading, generation, validation, and optional repair. | [Internal runner](runner.md) |
 
 These packages provide the internal model, source, rendering, validation, and
-model-client foundation. Orchestration and a usable public engine are not
-implemented in Promptkit yet.
+model-client workflow. A usable public engine is not implemented in Promptkit
+yet.
 
 ## Maintenance
 

docs/internal/runner.md

@@ -0,0 +1,83 @@
+# Internal Runner
+
+## Purpose
+
+This document describes Promptkit's implemented internal orchestration. The
+[architecture policy](../policy/architecture.md) owns dependency and consumer
+boundaries. The [source and validation document](sources.md) owns repository,
+artifact, rendering, and validation behavior, while the
+[model-client document](llm.md) owns generation behavior and failure
+categories.
+
+The runner remains under `internal/usecase`. The root package does not yet
+assemble it into a usable public engine.
+
+## Collaborators
+
+`Runner` coordinates narrow internal interfaces for prompt definitions,
+profiles, artifacts, rendering, model generation, and validation. Schema
+documents are loaded through the validator's optional schema-loader interface.
+An output repairer can be injected internally, but the ordinary runner
+constructor does not enable one.
+
+Each invocation carries its state in request, prepared-run, and result values.
+The runner has no durable run or session store.
+
+## Preparation Flow
+
+`Prepare` performs the reusable pre-generation workflow:
+
+1. validate the prompt selection and load the prompt definition;
+2. hash the loaded definition;
+3. select the request profile or the prompt's default profile;
+4. resolve application-neutral defaults, profile values, and explicit request
+   overrides in that order;
+5. validate endpoint, model, numeric overrides, and credential requirements;
+6. resolve the output contract and load a structured-output schema when
+   required;
+7. load and hash input artifacts;
+8. render and hash the prompt; and
+9. return the effective settings, source identities, messages, hashes, and
+   preparation timing.
+
+Pointer-based numeric overrides preserve an explicit zero. Invalid negative or
+out-of-range values fail as invalid requests. A direct API key takes
+precedence over environment lookup for execution; secret values remain
+excluded from serialized metadata.
+
+## Run Flow
+
+`Run` calls `Prepare` rather than maintaining a second preparation path. It
+performs one initial generation call, builds the named output artifact, and
+validates that artifact. Invalid generated content remains a validation result;
+an inability to perform validation is an operational error.
+
+When an internal repairer is present, a JSON or JSON Schema content failure can
+trigger bounded repair attempts. Repair receives the effective execution
+target, validation errors, prior output, and structured-output specification.
+This capability remains internal and is not a public option.
+
+A successful result includes the output artifact and raw output, validation
+state, prompt and rendered-prompt hashes, selected profile, effective settings,
+input hashes, token usage, a generated run identifier, and UTC timing.
+
+## Failure Categories
+
+Package errors distinguish invalid requests, required profile selection,
+credential failures, and prompt, profile, artifact, rendering, generation, and
+validation failures. Wrapping preserves the package identities needed by the
+future facade and retains collaborator identities where they are part of the
+internal contract. Context cancellation propagates through the invoked
+collaborator and is classified by the owning operation.
+
+## Test Ownership And Changes
+
+The [runner tests](../../internal/usecase/runner_test.go) own preparation order,
+selection and override precedence, schema-before-generation behavior, hashing,
+generation and validation outcomes, bounded repair, credentials and redaction,
+error categories, artifact metadata, usage, and timing.
+
+Changes to orchestration should continue to use the existing package
+interfaces, keep request state local to an invocation, and preserve `Run`'s use
+of `Prepare`. Source, renderer, validator, or model-client contract changes
+belong first in their owning package and document.

docs/policy/architecture.md

@@ -34,9 +34,11 @@ The implemented internal components consist of:
 - `internal/artifact`, which resolves ordinary inline and unrestricted
   caller-selected file references;
 - `internal/validate`, which validates basic, JSON, and JSON Schema output
-  using filesystem and `fs.FS` schema sources; and
+  using filesystem and `fs.FS` schema sources;
 - `internal/llm`, which defines the provider-neutral generation boundary and
-  implements outbound OpenAI-compatible chat requests.
+  implements outbound OpenAI-compatible chat requests; and
+- `internal/usecase`, which coordinates preparation and execution across the
+  internal framework components.
 
 The defaults and renderer depend on the domain model. Prompt-definition and
 profile repositories use the domain model, file catalog, and YAML decoder. The
@@ -44,8 +46,9 @@ built-in profile repository supplies an embedded `fs.FS` to the profile
 package. Artifact reading uses the domain model and application-neutral
 defaults. Validation uses the domain model, file catalog, and JSON Schema
 implementation. The model client uses the domain model, application-neutral
-defaults, and an injected or standard-library HTTP client. Orchestration and
-the public engine have not yet been extracted.
+defaults, and an injected or standard-library HTTP client. The use-case runner
+depends on the narrow interfaces owned by each internal component. The public
+engine has not yet been extracted.
 
 Future framework extraction must follow this dependency direction: