Document shared configuration and repair defaults
This commit is contained in:
@@ -16,10 +16,11 @@ contributor workflow and validation.
|
||||
| `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, programmatic profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
|
||||
| `examples/go-library/observe` | Demonstrates offline retry, observation, prepared notification, and separately budgeted coordinated proposal and assessment runs using two profiles on one finite backend. It is not a public library package. | [Example program](../../examples/go-library/observe/main.go) |
|
||||
| `internal/backend` | Holds a defensive, immutable lookup of final backend definitions, including diagnostic metadata, plus capacity policies validated by the configuration adapter. | [Backend registry](../../internal/backend/registry.go) |
|
||||
| `internal/configuration` | Loads root and namespaced resources through ConfigKit; validates final values, captures indexed resource views and source-relative prompt content, compiled templates, requirement metadata, identity inventories, backend and presence-aware execution profiles, and the read-only provenance inspection view. | [Typed loader](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
|
||||
| `internal/configuration` | Supplies component rules and captures final shared settings and native inspection evidence into owned indexed resources, compiled templates, requirement metadata, identities, and execution profiles. | [Configuration capture](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
|
||||
| `internal/settings` | Declares the shared public configuration data model exposed through root aliases under ADR 0002; contains no loading or execution logic. | [Settings declarations](../../internal/settings/settings.go), [ADR 0002](../adr/0002-shared-configuration-data-model.md) |
|
||||
| `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) |
|
||||
| `internal/domain` | Defines internal framework values for requests, immutable conversation exchanges, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, validation, and source-neutral smoke diagnostics, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, output contracts, and resource-identity syntax and qualification. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [exchange storage](../../internal/domain/exchange.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) |
|
||||
| `internal/engine` | Assembles caller-selected configuration into one snapshot, then constructs shared capacity, rendering, validation, generation, repair, the ordinary runner, and the smoke tester for each engine. Immutable namespace views share those collaborators and qualify caller-supplied execution, inspection, and diagnostic selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. It delegates resource inspection and identity listing directly to the captured configuration rather than the runner. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#typed-configuration-loading), [internal runner](runner.md) |
|
||||
| `internal/engine` | Assembles an already captured configuration into shared capacity, rendering, validation, generation, repair, runner, and smoke-test collaborators. Immutable namespace views share those collaborators and qualify selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. It delegates resource inspection and listing to the capture. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#typed-configuration-loading), [internal runner](runner.md) |
|
||||
| `internal/generation` | Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, ordinary attempt observations, and invocation-local evidence for diagnostics. | [Internal generation coordination](generation.md) |
|
||||
| `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
|
||||
| `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |
|
||||
|
||||
@@ -30,6 +30,11 @@ internal callers and tests.
|
||||
Each invocation carries its state in request, prepared-run, and result values.
|
||||
The runner has no durable run or session store.
|
||||
|
||||
Request output-contract replacements carry an optional repair budget. The
|
||||
runner resolves that budget from the replacement's validation mode before
|
||||
building the concrete validation plan; prepared execution retains the resolved
|
||||
integer. Configured budgets are already resolved by the configuration adapter.
|
||||
|
||||
Captured exchanges are immutable parent-linked domain values. Each holds only
|
||||
its new rendered suffix, final assistant message, and run identities; flattening
|
||||
iteratively fills a single detached message buffer for preparation or projects
|
||||
|
||||
@@ -10,38 +10,24 @@ source semantics. Internal packages are not consumer APIs.
|
||||
|
||||
## Typed Configuration Loading
|
||||
|
||||
`internal/configuration` is the single adapter from ConfigKit's final
|
||||
effective configuration to execution-owned definitions and resource views. It performs one
|
||||
layered load, captures the needed effective presence, records
|
||||
field-level normalization and derived defaults during resolution, and validates all effective
|
||||
root and collection backend, profile, and prompt values. Replaced lower-layer
|
||||
domain values are not separately validated. It indexes root resources under
|
||||
their unqualified IDs and collection resources under their full
|
||||
`namespace/local-key` IDs while retaining ConfigKit's resolved tree. It builds an immutable backend index and presence-aware profile
|
||||
targets, applying final backend defaults only after profile inheritance. Runtime
|
||||
lookups use those final indexes and exact stored references; they do not rewrite
|
||||
or resolve resources from ConfigKit source history. The runtime/domain packages
|
||||
do not depend on ConfigKit.
|
||||
The root facade composes Promptkit rules into a ConfigKit definition. An
|
||||
application-owned load or the standalone constructor produces final settings
|
||||
at `/promptkit`; `internal/configuration` captures execution-owned resources
|
||||
from those settings and a native inspection view without another load.
|
||||
`internal/settings` supplies the shared data declarations exposed through
|
||||
root aliases. The adapter records normalization and validates effective values,
|
||||
then uses one metadata snapshot for presence and source origins. Runtime/domain
|
||||
packages do not depend on ConfigKit.
|
||||
|
||||
ConfigKit owns source headers, imports, composition, and source evidence.
|
||||
Promptkit does not preparse contributions: it validates the final effective
|
||||
values once, captures the indexed identities and their original resource
|
||||
contexts, and retains ConfigKit's resolved result for explicit operator inspection.
|
||||
Accepted non-main source headers are consumed during composition; the main
|
||||
source declaration remains available in that inspection view. Collection
|
||||
release labels are descriptive metadata, not selection inputs. The
|
||||
[format reference](../formats.md#source-headers-collections-and-resource-ids)
|
||||
owns the exact source-header and collection contracts.
|
||||
|
||||
The `ConfigurationInspection.Diff` facade method compares two retained results
|
||||
through a private wrapper and a narrow `internal/configuration.Diff` bridge.
|
||||
The wrapper keeps `Result[document]` inside the adapter; the bridge delegates
|
||||
once to ConfigKit and returns its public difference records. Comparison
|
||||
uses only frozen effective values and does not reopen sources, resolve runtime
|
||||
credentials, or enter the execution path. ConfigKit applies sensitivity from
|
||||
both results; reports may still contain ordinary application data. See the
|
||||
[consumer comparison guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration)
|
||||
and ConfigKit's [comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md#effective-configuration-diffs).
|
||||
Capture detaches known settings, builds indexed definitions and profile targets,
|
||||
and binds source-relative resources from the effective field's source context.
|
||||
It retains a frozen native focused view and copied diagnostics, not the mutable
|
||||
application result. Configuration inspection delegates reporting, redaction,
|
||||
history and comparison to ConfigKit; explicit queries and metadata retain
|
||||
whole-application paths and evidence. Runtime never derives values from history.
|
||||
The [format reference](../formats.md#source-headers-collections-and-resource-ids)
|
||||
owns the configuration contract and the [consumer guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration)
|
||||
describes reporting scope.
|
||||
|
||||
After resource materialization and effective-profile snapshot construction, the
|
||||
adapter captures lexically ordered identity inventories for backends, profiles,
|
||||
@@ -52,15 +38,15 @@ captured values without consulting ConfigKit or copying resource definitions.
|
||||
The root `DirectoryInputs` and `FilesystemInputs` helpers discover sorted YAML
|
||||
files under an explicit root, provide resource context, and leave imports
|
||||
disabled. Each returned slice belongs to one strict-composition group; file
|
||||
order does not confer priority. Engine assembly prepends a dedicated embedded
|
||||
OpenRouter underlay unless disabled, without modifying caller-owned slices.
|
||||
order does not confer priority. The standalone facade prepends a dedicated
|
||||
embedded OpenRouter underlay unless disabled, without modifying caller-owned slices.
|
||||
Caller underlays are composed in their given
|
||||
order, followed by the optional main input. The
|
||||
[configuration tests](../../internal/configuration/load_test.go) exercise the
|
||||
real loader and final-value handoff.
|
||||
|
||||
The public `CollectionInput` helper mounts one caller-selected source at
|
||||
`collections/<namespace>` and enables ConfigKit imports for that input. The
|
||||
`/promptkit/collections/<namespace>` and enables ConfigKit imports for that input. The
|
||||
helper does not read the source; ConfigKit retains responsibility for loading,
|
||||
composition, imports, and source-local resource context. Imported or inherited
|
||||
`content_file` values continue resolving relative to the source that contributed
|
||||
@@ -83,7 +69,7 @@ declaration; absent and null fields remain distinguishable from explicit
|
||||
strings, including empty strings. It closes content-file handles before
|
||||
returning and retains no source capability for public inspection.
|
||||
|
||||
Prompt materialization shares a lazy metadata snapshot across root and collection
|
||||
Prompt materialization shares one metadata snapshot across root and collection
|
||||
resources during construction, avoiding a full metadata copy per collection.
|
||||
Input metadata, message content and templates, and output contracts are captured
|
||||
separately before the definition, inspection, and hash are assembled. Schema
|
||||
|
||||
Reference in New Issue
Block a user