Document Scriptorium as a Promptkit application
This commit is contained in:
@@ -2,115 +2,86 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
Adapters translate external inputs into public engine requests and translate
|
||||
public results or errors back to their interface. They own IO and presentation
|
||||
mechanics; use-case decisions remain behind the root `scriptorium` facade.
|
||||
Scriptorium adapters translate executable inputs into Promptkit public requests
|
||||
and translate Promptkit results or errors back to CLI or HTTP behavior. They
|
||||
own IO and presentation mechanics, not framework decisions.
|
||||
|
||||
External contracts are canonical in the [CLI reference](../cli.md), [HTTP API
|
||||
reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
|
||||
External contracts are canonical in the [CLI reference](../cli.md) and
|
||||
[HTTP API reference](../api.md). Promptkit's public engine contract is
|
||||
described by its tagged
|
||||
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md).
|
||||
|
||||
## Components And Collaborators
|
||||
|
||||
- `cmd/scriptorium` passes process arguments and streams to
|
||||
`internal/adapter/cli`.
|
||||
- `internal/adapter/cli` parses commands, resolves application settings through
|
||||
`internal/config`, constructs the public engine, and owns process output
|
||||
handling.
|
||||
- `internal/adapter/http` decodes DTOs, maps them to public run requests,
|
||||
calls its local public `Runner` interface, and maps public errors and results
|
||||
to HTTP DTOs.
|
||||
- The root `scriptorium` package maps its public types and options to internal
|
||||
collaborators and maps selected internal errors to public sentinels.
|
||||
- `internal/format` formats public prepared runs for the CLI.
|
||||
- `internal/adapter/cli` resolves settings through `internal/config`,
|
||||
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
||||
and owns output files, summaries, and exit codes.
|
||||
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
|
||||
public values, calls its adapter-owned `Runner` interface, and maps results
|
||||
and errors to HTTP DTOs.
|
||||
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
|
||||
or JSON.
|
||||
|
||||
## Wiring Flows
|
||||
|
||||
### CLI
|
||||
|
||||
The CLI resolves configuration before constructing the public engine. `run`
|
||||
calls `Engine.Run` with a public request and `render` calls `Engine.Prepare`
|
||||
with the same request mapping. `serve` constructs the HTTP-owned restricted
|
||||
artifact reader, injects it with `WithArtifactReader`, passes the resulting
|
||||
engine directly to the HTTP handler, and starts the server.
|
||||
`run` calls `promptkit.Engine.Run`; `render` calls
|
||||
`promptkit.Engine.Prepare`. Both share request mapping for prompt/profile
|
||||
selection, file inputs, variables, and presence-aware execution overrides.
|
||||
Omitted framework settings remain zero values so Promptkit resolves its own
|
||||
defaults.
|
||||
|
||||
Parser state records whether numeric runtime values were explicitly supplied.
|
||||
That presence is carried into `scriptorium.ExecutionTargetOverride`, allowing
|
||||
the engine to distinguish omitted values from explicit zero overrides.
|
||||
`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it
|
||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
||||
|
||||
### HTTP
|
||||
|
||||
The handler first enforces transport limits, strict JSON decoding, and the
|
||||
minimal request shape. It maps DTO values to public types without deciding
|
||||
prompt selection, source behavior, or validation semantics. On success it maps
|
||||
the public result to the response DTO; on failure it uses `errors.Is` over
|
||||
public framework errors and HTTP-local artifact-policy errors to choose the
|
||||
public error mapping.
|
||||
The handler enforces transport limits and strict JSON decoding before mapping
|
||||
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
|
||||
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
|
||||
validation, model, usage, and metadata values directly.
|
||||
|
||||
The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
|
||||
and externally observable limit behavior.
|
||||
|
||||
### Public Go Facade
|
||||
|
||||
`NewEngine` applies public options, selects filesystem, `fs.FS`, single-file,
|
||||
or in-memory dependencies, and constructs a runner. The conversion functions
|
||||
copy maps and slices across the boundary so callers do not receive internal
|
||||
domain values. The facade maps selected internal errors to the public sentinel
|
||||
set and keeps direct request API keys out of public results.
|
||||
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
|
||||
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
|
||||
errors preserve their identity through Promptkit's artifact-load boundary.
|
||||
|
||||
## Package-Local Guarantees
|
||||
|
||||
- Adapters do not embed framework orchestration or source-loading decisions.
|
||||
- Configuration is resolved before adapter dependency composition.
|
||||
- CLI and HTTP consume the public engine without a repairer; a repairer remains
|
||||
available only through explicit internal runner construction.
|
||||
- DTO conversion preserves explicit numeric-override presence.
|
||||
- Error mapping matches error identities, not error text.
|
||||
- No adapter creates durable run state; caller-selected output files are not
|
||||
application state.
|
||||
- Adapters contain no copied framework types or orchestration.
|
||||
- Configuration is resolved before Promptkit engine construction.
|
||||
- Explicit numeric overrides preserve presence, including zero.
|
||||
- HTTP DTO and error mapping remains stable and transport-owned.
|
||||
- Resolved secrets are not serialized or printed.
|
||||
- No adapter creates durable run state.
|
||||
|
||||
## Failure And Verification Boundaries
|
||||
## Verification
|
||||
|
||||
Keep external error payloads concise, preserve strict external decoding, and do
|
||||
not serialize resolved secret values. Validation content failures remain result
|
||||
state; runtime failures remain errors for the relevant adapter to map.
|
||||
|
||||
Inspect focused tests when changing this area:
|
||||
Inspect:
|
||||
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
- `engine_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/format/prepared_run_test.go`
|
||||
- `internal/adapter/dependency_test.go`
|
||||
|
||||
Run the affected adapter package tests and recheck the relevant canonical
|
||||
contract. The [testing policy](../policy/testing.md) owns global test
|
||||
sufficiency guidance.
|
||||
The adapter tests protect parsing, configuration mapping, output, status
|
||||
mapping, restricted artifacts, and representative real Promptkit-engine
|
||||
workflows. The dependency test protects the repository boundary.
|
||||
|
||||
## Change Recipes
|
||||
|
||||
### Application Configuration Fields
|
||||
For a CLI or HTTP change:
|
||||
|
||||
1. Add the field to the relevant `internal/config` shape and default handling.
|
||||
2. Parse and validate it, then preserve configuration and CLI-override
|
||||
precedence while wiring it through its consuming adapter.
|
||||
3. Add focused configuration and adapter tests for parsing, mapping, and
|
||||
effective behavior.
|
||||
4. Update the [configuration contract](../config.md) and any affected external
|
||||
contract.
|
||||
1. identify the Scriptorium-owned external contract;
|
||||
2. map through Promptkit public values without copying framework semantics;
|
||||
3. add or update the narrow application-owned test;
|
||||
4. update the canonical Scriptorium contract; and
|
||||
5. coordinate and tag Promptkit first if a required public capability is
|
||||
genuinely absent.
|
||||
|
||||
### CLI Flags
|
||||
|
||||
1. Add the flag to the relevant parser in `internal/adapter/cli/run.go`.
|
||||
2. Keep command scope and application-configuration precedence intentional.
|
||||
3. Add or update parser and command tests in
|
||||
`internal/adapter/cli/run_test.go`.
|
||||
4. Update the [CLI contract](../cli.md) and affected maintained examples.
|
||||
|
||||
### Adapter Capabilities
|
||||
|
||||
1. Define or reuse an adapter-local consumer interface with public facade
|
||||
types when a test seam is needed.
|
||||
2. Implement translation and IO behavior without moving framework decisions out
|
||||
of the public engine.
|
||||
3. Add focused mapping, parsing, and error-behavior tests.
|
||||
4. Update this document and the affected public or integration contract. Update
|
||||
[source internals](sources.md) when source-loading behavior changes.
|
||||
Update [source internals](sources.md) when application source locations or HTTP
|
||||
artifact containment changes.
|
||||
|
||||
@@ -1,86 +0,0 @@
|
||||
# LLM Internals
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/llm` defines the provider-neutral `Client` interface and the
|
||||
OpenAI-compatible client implementation. The [OpenAI-compatible integration
|
||||
contract](../integrations/openai-compatible-chat.md) owns the outbound HTTP wire
|
||||
format and protocol behavior.
|
||||
|
||||
## Construction
|
||||
|
||||
`NewOpenAICompatibleClient` validates a non-empty configured base URL, records
|
||||
an optional default model, and resolves one transport cap. A supplied client
|
||||
with a positive timeout supplies that cap; otherwise a positive configured
|
||||
timeout is used, then the internal default.
|
||||
|
||||
When callers supply an `http.Client`, construction clones it rather than
|
||||
mutating the caller's instance. A supplied client with a zero or negative
|
||||
timeout receives the resolved transport cap in the clone. The client stores the
|
||||
trimmed base URL, default model, and cloned client.
|
||||
|
||||
## Generate Flow
|
||||
|
||||
`Generate` receives a `domain.GenerateRequest` from the runner:
|
||||
|
||||
1. validate the effective timeout and choose the request endpoint;
|
||||
2. map the domain request to the internal wire-request representation;
|
||||
3. validate and flatten extra parameters and encode JSON;
|
||||
4. derive a child context when the effective generation timeout is positive,
|
||||
then create the HTTP request with that context;
|
||||
5. prefer a direct API key, otherwise resolve the configured key environment
|
||||
variable;
|
||||
6. execute with the construction-time HTTP client, reject non-success status
|
||||
responses without returning
|
||||
provider response bodies; and
|
||||
7. decode the response subset into `domain.GenerateResponse`.
|
||||
|
||||
`openAIChatRequestFromGenerateRequest` is the conversion boundary for effective
|
||||
model defaults, explicit numeric-presence state, rendered messages, structured
|
||||
output, and session-ID validation. `openAIChatRequestPayload` protects reserved
|
||||
fields and JSON encoding before an HTTP call. The external payload shape is
|
||||
defined only in the [integration contract](../integrations/openai-compatible-chat.md).
|
||||
|
||||
## Error Categories
|
||||
|
||||
The package uses these internal sentinels:
|
||||
|
||||
- `ErrInvalidConfig` for invalid client construction;
|
||||
- `ErrInvalidRequest` for invalid effective generation input;
|
||||
- `ErrRequestFailed` for request construction or transport failures;
|
||||
- `ErrUnexpectedStatus` for non-success HTTP responses; and
|
||||
- `ErrMalformedResponse` for invalid or incomplete successful-response data.
|
||||
|
||||
The runner maps an invalid LLM request to its invalid-request category and
|
||||
other LLM failures to its generation category. Adapters then apply their public
|
||||
error contracts.
|
||||
|
||||
## Package-Local Guarantees
|
||||
|
||||
- The default-model fallback happens before wire encoding.
|
||||
- Per-generation timeout handling derives a request context; it never replaces
|
||||
or mutates the configured HTTP client's transport cap.
|
||||
- Direct API keys take precedence over environment lookup within this client.
|
||||
- Provider response bodies are discarded for non-success status responses.
|
||||
- The client does not implement retries, tool calls, or a stateful session
|
||||
store.
|
||||
|
||||
## Verification And Change Recipe
|
||||
|
||||
Inspect:
|
||||
|
||||
- `internal/llm/openai_compatible_client_test.go`
|
||||
- `internal/usecase/runner_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
|
||||
When changing the client:
|
||||
|
||||
1. keep domain-to-wire mapping inside `internal/llm` and preserve the `Client`
|
||||
interface;
|
||||
2. test construction, timeout selection, mapping, and error categorization;
|
||||
3. update the [OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md)
|
||||
for any observable wire or protocol change; and
|
||||
4. update [runner internals](runner.md) if the client boundary or structured
|
||||
output handoff changes.
|
||||
|
||||
The [testing policy](../policy/testing.md) owns global test sufficiency.
|
||||
@@ -1,48 +1,18 @@
|
||||
# Internal Component Overview
|
||||
|
||||
## Purpose
|
||||
|
||||
This is the inventory of Scriptorium's implemented components for contributors.
|
||||
The [architecture policy](../policy/architecture.md) owns normative boundaries
|
||||
and invariants; public behavior belongs in the linked contracts.
|
||||
|
||||
## Public And Command Entrypoints
|
||||
This is the complete inventory of Scriptorium's implemented Go components.
|
||||
The [architecture policy](../policy/architecture.md) owns normative boundaries;
|
||||
public behavior belongs in the linked contracts.
|
||||
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| Root package `scriptorium` | Public Go facade that constructs the engine, exposes request/result types and options, and maps internal errors. | [Go package contract](../consumers/pkg-scriptorium.md), [adapter internals](adapters.md) |
|
||||
| `cmd/scriptorium` | Process entrypoint that delegates command execution to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/cli` | Parses commands, resolves application settings, constructs Promptkit engines, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/config` | Discovers and strictly decodes application configuration and applies built-in and CLI precedence. | [configuration contract](../config.md), [adapter internals](adapters.md) |
|
||||
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
|
||||
| `internal/format` | Formats Promptkit prepared-run values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
|
||||
## Adapters, Domain, And Use Case
|
||||
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| `internal/adapter/cli` | Parses CLI commands, constructs the public engine from application settings, and handles process input and output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/http` | Maps HTTP requests and responses through public engine values, maps public errors, and owns restricted HTTP artifact policy. | [HTTP API contract](../api.md), [adapter internals](adapters.md) |
|
||||
| `internal/domain` | Defines core request, result, output-contract, and LLM-boundary types. | [runner internals](runner.md) |
|
||||
| `internal/usecase` | Implements `Runner` preparation, execution, validation coordination, and the repairer boundary. | [runner internals](runner.md) |
|
||||
|
||||
## Configuration And Sources
|
||||
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| `internal/config` | Loads application settings, applies defaults, and applies CLI overrides. | [configuration contract](../config.md), [adapter internals](adapters.md) |
|
||||
| `internal/defaults` | Holds compile-time default values used when application settings are resolved. | [configuration contract](../config.md) |
|
||||
| `internal/promptdef` | Loads prompt definitions from filesystem and `fs.FS` sources. | [configuration contract](../config.md), [source internals](sources.md) |
|
||||
| `internal/profile` | Loads filesystem and `fs.FS` execution profiles and combines profile repositories. | [configuration contract](../config.md), [source internals](sources.md) |
|
||||
| `internal/profile/builtin` | Provides embedded built-in execution profiles as a repository. | [configuration contract](../config.md), [source internals](sources.md) |
|
||||
| `internal/filecatalog` | Provides shared YAML discovery and source-root helpers. | [source internals](sources.md) |
|
||||
| `internal/artifact` | Provides the framework's ordinary inline and unrestricted file artifact reader. | [configuration contract](../config.md), [source internals](sources.md) |
|
||||
| `internal/prompt` | Renders prompt templates into messages. | [runner internals](runner.md) |
|
||||
|
||||
## Formatting, Validation, And Model Access
|
||||
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| `internal/format` | Formats public prepared-run information for CLI output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/validate` | Defines validation interfaces and provides standard filesystem and `fs.FS` schema validation. | [configuration contract](../config.md), [source internals](sources.md), [runner internals](runner.md) |
|
||||
| `internal/llm` | Defines the provider-neutral LLM client boundary and its OpenAI-compatible implementation. | [OpenAI-compatible integration](../integrations/openai-compatible-chat.md), [LLM internals](llm.md), [runner internals](runner.md) |
|
||||
|
||||
Focused internal documents describe the components that have detailed
|
||||
orchestration, adapter, or source behavior. Package tests live alongside the
|
||||
implementation and are identified in those focused documents where relevant.
|
||||
Framework implementation packages are provided by
|
||||
[Promptkit v0.1.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md)
|
||||
and are not part of this repository.
|
||||
|
||||
@@ -1,120 +0,0 @@
|
||||
# Runner Internals
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/usecase.Runner` is the prompt-execution orchestrator. It prepares
|
||||
domain requests, invokes an injected LLM client, validates output, and returns
|
||||
domain results. Transport parsing, response mapping, and public type conversion
|
||||
remain outside this package.
|
||||
|
||||
The [configuration reference](../config.md) owns prompt, profile, schema, and
|
||||
runtime-setting definitions. Public error behavior is defined by the
|
||||
[HTTP API](../api.md) and [Go package](../consumers/pkg-scriptorium.md)
|
||||
contracts.
|
||||
|
||||
## Dependencies And Construction
|
||||
|
||||
`Runner` receives these collaborators:
|
||||
|
||||
- `promptdef.Repository`;
|
||||
- `profile.Repository`;
|
||||
- `artifact.Reader`;
|
||||
- `prompt.Renderer`;
|
||||
- `llm.Client`;
|
||||
- `validate.Validator`; and
|
||||
- an optional `OutputRepairer`.
|
||||
|
||||
`NewRunner` constructs a runner without a repairer. `NewRunnerWithRepairer`
|
||||
accepts one explicitly. The public engine chooses concrete repositories and
|
||||
readers; executable adapters reach the runner only through that engine. The
|
||||
runner does not load application configuration.
|
||||
|
||||
## Prepare Flow
|
||||
|
||||
`Prepare` performs one deterministic preparation pass for a request:
|
||||
|
||||
1. validate the prompt ID and load the prompt definition;
|
||||
2. hash the definition and select the explicit or default profile;
|
||||
3. load the profile and resolve effective execution settings;
|
||||
4. validate endpoint, model, and credential availability;
|
||||
5. resolve the output contract and, for JSON Schema output, load a structured
|
||||
schema document before model execution;
|
||||
6. read and hash input artifacts;
|
||||
7. render messages and the session ID; and
|
||||
8. return a `PreparedRun` containing the effective state and rendered-prompt
|
||||
hash.
|
||||
|
||||
Execution settings merge defaults, profile values, and a request override.
|
||||
Numeric override presence is retained so explicit zero values are not confused
|
||||
with omissions.
|
||||
|
||||
## Run And Validation Flow
|
||||
|
||||
`Run` creates a run ID and timestamps, then calls `Prepare` rather than
|
||||
duplicating preparation. It sends the prepared prompt, effective target,
|
||||
target-presence state, and optional structured-output specification to the LLM
|
||||
client. It converts the returned content to an output artifact, validates it,
|
||||
and returns the artifact, validation, hashes, usage, and timing metadata.
|
||||
|
||||
A validator can return a content result or an operational error. Content
|
||||
failures stay in the result; schema loading, compilation, and validator
|
||||
operational failures are returned as `ErrValidation`. The canonical distinction
|
||||
for callers is documented by the public contracts.
|
||||
|
||||
## Repair Boundary
|
||||
|
||||
Repair is an internal optional loop. It starts only when a repairer is present,
|
||||
the output contract permits one or more attempts, validation failed, and the
|
||||
validation mode is JSON or JSON Schema. Each repair receives the previous
|
||||
output, validation errors, effective target, structured-output specification,
|
||||
and attempt metadata; every repaired result is validated again.
|
||||
|
||||
`NewDefaultOutputRepairer` delegates to the injected LLM client. The public
|
||||
engine, and therefore CLI and HTTP, uses `NewRunner` and does not inject this
|
||||
repairer.
|
||||
|
||||
## Error Translation
|
||||
|
||||
Runner sentinels identify failure categories for adapters:
|
||||
|
||||
- `ErrInvalidRequest`
|
||||
- `ErrProfileRequired`
|
||||
- `ErrAPIKeyEnvMissing` and `ErrAPIKeyRequired`
|
||||
- `ErrPromptLoad`, `ErrProfileLoad`, and `ErrArtifactLoad`
|
||||
- `ErrPromptRender`
|
||||
- `ErrLLMGenerate`
|
||||
- `ErrValidation`
|
||||
|
||||
Wrap errors with those sentinels and preserve their identities through
|
||||
`errors.Is`; adapters must not classify errors by message text. The runner
|
||||
passes direct keys only to the LLM boundary and never includes resolved key
|
||||
values in prepared or run results.
|
||||
|
||||
## Package-Local Guarantees
|
||||
|
||||
- `Run` always reuses `Prepare`.
|
||||
- Schema documents are loaded before the initial LLM call when structured output
|
||||
is required.
|
||||
- Output validation records attempts used, including repair attempts.
|
||||
- Runner state is per request; the package does not create a durable run store
|
||||
or manifest.
|
||||
- Source, renderer, validator, and LLM implementations remain injected
|
||||
boundaries.
|
||||
|
||||
## Verification And Change Recipe
|
||||
|
||||
Inspect:
|
||||
|
||||
- `internal/usecase/runner_test.go`
|
||||
- `engine_test.go`
|
||||
|
||||
When changing orchestration:
|
||||
|
||||
1. identify the collaborator boundary and the affected `Prepare` or `Run` state;
|
||||
2. preserve the `Run`-through-`Prepare` path and error identity;
|
||||
3. add focused runner or integration tests for changed state transitions,
|
||||
validation, or repair behavior; and
|
||||
4. update the owning external contract and any affected source or LLM internal
|
||||
document.
|
||||
|
||||
The [testing policy](../policy/testing.md) owns global test sufficiency.
|
||||
@@ -2,98 +2,67 @@
|
||||
|
||||
## 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.
|
||||
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.1.0/docs/formats.md).
|
||||
|
||||
## Prompt Definitions
|
||||
## Application Source Locations
|
||||
|
||||
`internal/promptdef` provides filesystem and `fs.FS` repositories. Both use
|
||||
`internal/filecatalog` for recursive YAML discovery, deterministic ordering,
|
||||
display paths, and root cleaning.
|
||||
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
|
||||
Scriptorium defaults, configuration files, and CLI overrides.
|
||||
`internal/adapter/cli` passes those paths into `promptkit.Config` when
|
||||
constructing the engine.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Profiles And Built-Ins
|
||||
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.
|
||||
|
||||
`internal/profile` provides filesystem, `fs.FS`, and overlay repositories.
|
||||
`internal/profile/builtin` exposes embedded assets through the same repository
|
||||
interface.
|
||||
## Restricted HTTP Artifact Reader
|
||||
|
||||
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.
|
||||
`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 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).
|
||||
The reader:
|
||||
|
||||
## Schemas
|
||||
- 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.
|
||||
|
||||
`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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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/promptdef/repository_test.go`
|
||||
- `internal/profile/repository_test.go`
|
||||
- `internal/profile/builtin/repository_test.go`
|
||||
- `internal/artifact/reader_test.go`
|
||||
- `internal/config/config_test.go`
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/validate/standard_validator_test.go`
|
||||
- `engine_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
|
||||
When updating prompt, profile, schema, or built-in assets:
|
||||
When changing an application source location or HTTP artifact policy:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user