Document native configuration and toolchain requirements

This commit is contained in:
2026-11-17 20:56:06 +00:00
parent 5bab35f096
commit 244f258413
6 changed files with 91 additions and 26 deletions

View File

@@ -4,6 +4,6 @@ when:
steps:
- name: validate-release
image: golang:1.25.5
image: golang:1.27.0
commands:
- ./scripts/check-release-source.sh "$CI_COMMIT_TAG"

View File

@@ -31,7 +31,7 @@ demonstrates all implemented D&D lanes and the supporting campaign references.
## Install A Source Release
Source builds require Go at or above the consumer minimum declared in
[`go.mod`](go.mod). Its patch-level minimum is required by the selected PromptKit
[`go.mod`](go.mod). Go 1.27.0 is required by the selected ConfigKit
dependency.
Install a pinned source release with Go:

View File

@@ -6,6 +6,13 @@ Configuration fields, discovery rules, and selectable module keys are defined
in [Configuration](config.md); runtime state and recovery procedures are
defined in [Operations](operations.md).
Configuration-consuming commands share the same selection: explicit `--config`,
then `NOTARIUS_CONFIG`, then working-directory, user, and system searches. A
selected file's loading failure is terminal. Reports use that selected source;
the [configuration reference](config.md#configuration-discovery-and-precedence)
defines the filename groups and value precedence. Use `--config` for a fixed
service or subprocess selection.
## Command Summary
~~~

View File

@@ -1,7 +1,7 @@
# Configuration
This is the canonical reference for Notarius configuration. Configuration files
are YAML and must declare version 5. They select pipelines and their modules;
are YAML; the main file must declare version 5. They select pipelines and their modules;
the [CLI reference](cli.md) owns invocation syntax, and
[Operations](operations.md) owns run-state procedures.
@@ -11,17 +11,30 @@ Commands that load configuration choose a file in this order:
1. a non-empty **--config** CLI value;
2. a non-empty **NOTARIUS_CONFIG** environment value;
3. the installed default file at **/usr/local/etc/notarius/config.yml**, when
it exists.
3. `notarius.yml`, then `notarius.yaml` in the working directory;
4. the user configuration directory; then
5. the Unix system configuration directories.
The command fails if none of these paths provides a configuration file.
The user search checks `<user-config>/notarius/` for `notarius.yml`,
`notarius.yaml`, `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`, in
that order, then `<user-config>/notarius.yml` and `notarius.yaml`. The system
search uses the same groups under `/usr/local/etc/notarius/` and `/etc/notarius/`,
then `/etc/notarius.yml` and `/etc/notarius.yaml`. Generic filenames in the
working directory are not candidates. Home-directory search is not enabled.
Discovery selects one main file; it does not layer all candidates. A missing
candidate advances the search, but an explicitly selected missing file, access
error, or invalid selected file fails without fallback. An exhausted search
fails. Use an explicit `--config` for services and subprocesses that need a
fixed selection independent of their working directory.
For configuration values, precedence is:
1. built-in defaults;
2. composed YAML sources, including imports;
3. the selected ConfigKit overlay; and
4. explicitly supplied configuration-valued run flags.
3. the selected ConfigKit overlay and inheritance;
4. typed decoding and explicitly supplied configuration-valued run flags; and
5. Notarius resolution and validation.
`--config-overlay` selects a ConfigKit overlay from `overlays/<name>.yml`
beneath the selected configuration root. Empty and `default` select no overlay.
@@ -38,7 +51,8 @@ have no effect; `NOTARIUS_CONFIG` remains a source-discovery input.
ordered steps, all implemented D&D lanes, generated references, state
settings, bounded LLM concurrency, and the maintained
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) and imports its
pipeline from [a fragment](../examples/pipelines/dnd-session.yml).
pipeline from [a fragment](../examples/pipelines/dnd-session.yml), which imports
its [first step](../examples/pipelines/dnd-session.describe-session.yml).
The complete fragment also defines `dnd-session-development`, which inherits
the complete pipeline and profile while setting
@@ -102,24 +116,42 @@ Built-in relative destinations use the selected main configuration file's
directory; explicit `--output-dir` and `--debug-dir` values use the invocation
working directory. Absolute values remain unchanged.
The root file can use ConfigKit imports to compose disjoint definitions. Imports
and selected overlays remain under the configuration root; they do not merge or
append a pipeline's `steps` sequence. An overlay replaces sequences as defined
by ConfigKit, so changing an individual ordered binding requires supplying the
whole replacement sequence.
Use source-root `config` controls for imports and collection declarations. For
example, an essential fragment should explicitly be required:
~~~yaml
config:
imports:
- path: pipelines/session.yml
required: true
~~~
Imports are optional by default. ConfigKit supports paths, lists, directories,
globs, exclusions, recursive selection, destinations, and sequence-item placement;
its native input-root rules apply. Imported fragments need not declare a version.
The complete example places a mapping fragment at a step-list destination. Nested
application data named `config` is ordinary data, not a control block.
When migrating application files, rename genuine root `configkit` control
blocks to `config` in the main file and fragments. This is not a compatibility
alias: `configkit` is ordinary data under the new reader. PromptKit profile
documents still use their separate older engine and retain `configkit` controls;
see [PromptKit Profiles](#promptkit-profiles).
## Sibling Inheritance
ConfigKit v0.5.0 supports native `extends` composition in mappings. A directive
ConfigKit supports native `extends` composition in mappings and identified
sequence records. A directive
names exactly one immediate sibling in the same mapping; it is not a path or a
cross-scope lookup. Imports, the selected overlay, and explicit overrides are
composed before inheritance, which runs before typed decoding and normal
Notarius validation. Every definition, including a parent and definitions not
cross-scope lookup. Imports and the selected overlay are composed before
inheritance and typed decoding. Explicit CLI assignments follow decoding and
inheritance, before Notarius resolution and validation; they cannot repair an
earlier structural or decoding error. Every definition, including a parent and definitions not
selected for a run, remains subject to ordinary validation.
Child mappings recursively overlay parent mappings. A child sequence, scalar,
or null replaces the inherited value. This makes pipeline inheritance useful
for reusing a complete pipeline while replacing whole ordered lists:
Child mappings recursively overlay parent mappings. Scalars and null replace
inherited values. Unidentified sequences replace as whole values; pipeline
steps are identified by `id` and use native upsert by default:
~~~yaml
pipelines:
@@ -133,10 +165,31 @@ pipelines:
~~~
Pipeline names are siblings within `pipelines`; nested mappings such as named
artifact lanes also have their own sibling namespace. Step entries are a
sequence, so a step cannot extend another step. Replacing `steps` or a validator
chain supplies the complete replacement sequence; entries are not appended or
merged by identifier.
artifact lanes also have their own sibling namespace. Distinct imported step IDs
combine in source order; duplicate peer IDs conflict. Across an overlay or
inheritance, upsert replaces a matching step as a complete record in place and
appends new IDs. It does not merge individual fields of a matching step. An
identified record can itself use native `extends`. Authors may select `replace`
or `append` with a `config.sequences` declaration at the relevant destination;
an explicit replacement with `[]` clears the list, while empty append or upsert
does not. Notarius then validates the resulting pipeline, including its nonempty
step requirement. Validator chains are not automatically identified. Authors
may declare identities for other lists when needed. CLI list assignment replaces
the complete decoded list.
For example, an overlay can opt into replacing a pipeline's steps:
~~~yaml
config:
sequences:
- destination: [pipelines, production, steps]
mode: replace
pipelines:
production:
steps:
- id: extract
artifacts: {spells: {extract: {module: dnd/spells}}}
~~~
Inherited values count as explicit input for Notarius's existing
presence-sensitive rules: zero, false, and empty-list overrides stay explicit

View File

@@ -8,7 +8,7 @@ who need implementation mechanics should read [Run State Internals](internal/sta
## Source Deployment
Linux is the supported deployment platform. Install a pinned source release
with the Go version declared in `go.mod` (currently Go 1.25.5):
with the Go version declared in `go.mod` (currently Go 1.27.0):
~~~sh
GOWORK=off go install \

View File

@@ -402,6 +402,11 @@ Prompt size: one supporting fragment and existing example coverage.
## Stage 9 — Update Operator And Consumer Documentation
**Complete.** Operator references now describe native discovery, composition,
override timing, path bases, and the separate PromptKit format. Source-install,
release-validation, and advisory CI toolchain guidance select Go 1.27.0.
Maintained-example resolution and validation tests pass.
Goal: document implemented native behavior and migration in canonical homes.
Work: