Files
notarius/docs/config.md

584 lines
37 KiB
Markdown

# Configuration
This is the canonical reference for Notarius configuration fields, defaults,
source selection, and selectable modules. The sole application version is
`6` (also accepted as `"6"`). [CLI Reference](cli.md) owns invocation syntax;
[Operations](operations.md) owns physical state and recovery; integration
contracts own artifact payloads.
Upgrading an older deployment or caller? Use the
[native migration guide](consumers/native-migration.md).
## Configuration Discovery And Precedence
Configuration-consuming commands select one main file:
1. Explicit `--config`, which must not be empty.
2. Nonblank `NOTARIUS_CONFIG`.
3. `notarius.yml`, then `notarius.yaml`, in the working directory.
4. Go's user configuration directory: first its `notarius/` subdirectory,
trying `notarius.yml`, `notarius.yaml`, `config.yml`, `config.yaml`,
`main.yml`, `main.yaml`; then the two `notarius.*` names directly beneath it.
5. `/usr/local/etc/notarius/`, then `/etc/notarius/`, with those six names;
finally `/etc/notarius.yml` and `/etc/notarius.yaml`.
Generic working-directory filenames and home-directory searches are not enabled.
Missing discovery candidates advance the search; a selected missing, unreadable,
or invalid explicit source fails without fallback. Exhausted discovery fails.
Discovery selects a main file rather than layering every candidate.
Use explicit selection for services and subprocesses.
One ConfigKit result contains the application and native PromptKit settings.
Its source layers, from lower to higher priority, are:
1. The bundled OpenRouter resource underlay.
2. Embedded Notarius prompts/profiles and their filesystem-backed schema root.
3. Optional operator companions beside the **actual selected main file**:
`prompts.yml` and recursively selected `*.yml`/`*.yaml` files in `prompts/`.
These form one strict peer group: filenames do not confer priority and
conflicting contributions fail.
4. The selected application main source and its native import graph.
5. The selected ConfigKit overlay.
Companions are wrapperless native PromptKit settings mounted at `/promptkit`.
They are optional only when absent; malformed or unreadable selected content
fails. The loader does not search the invocation directory for substitute
companions. A companion's imports and content-file paths retain its native
source context. Main imports use their declared destinations; main-file native
settings belong beneath `promptkit`.
Source assembly, inheritance, typed defaults/decoding, explicit configuration
overrides, application normalization, and validation use ConfigKit's native
processing order. Overrides cannot repair earlier parse, composition, version,
inheritance, or decoding errors. The same captured result serves inspection and
engine construction, not a separate profile loader.
The overlay selector is a name: `development` selects
`overlays/development.yml` under the selected main source's configuration root.
Empty and exact lowercase `default` select the base. A missing selected overlay
fails; there is no overlay stack or extension fallback. Application overlays are
distinct from PromptKit profiles. See [ConfigKit's selected-overlay contract][overlays].
Only `NOTARIUS_CONFIG` participates in application environment selection.
Credential environment names are native PromptKit settings, not field-level
application environment overlays.
## Maintained Examples
- [Minimal](../examples/dnd-minimal/config.yml): embedded resources only, Seriatim
input, generic chunking, and one spell lane.
- [Complete](../examples/dnd-complete/config.yml): ordered steps and all D&D
families, generated references, independent state roots, workers, cache/mode/
turn controls, and selected domain auxiliaries. Its
[companion](../examples/dnd-complete/prompts.yml) demonstrates native profile
and backend inheritance without replacing native queue defaults.
- The complete [pipeline fragment](../examples/dnd-complete/pipelines/dnd-session.yml)
and [first-step fragment](../examples/dnd-complete/pipelines/dnd-session.describe-session.yml)
retain declaration-relative imports and references. Its development pipeline
selects a derived profile and zero semantic correction turns. The
[development overlay](../examples/dnd-complete/overlays/development.yml)
demonstrates serial workers and cache bypass.
The examples use separate directories so complete-example companions do not
alter minimal-example selection. Use these full files as starting points;
the fragments below illustrate individual settings.
## File Shape And Defaults
Application fields are strict. Unknown application fields, duplicate mapping
keys, blank identifiers, and identifiers duplicated after trimming are rejected.
PromptKit-owned resource records use the [native format][formats], including its
extension-field and strict nested-object rules; arbitrary extension fields are
not automatically secret.
| Root field | Type | Default / meaning |
| --- | --- | --- |
| `version` | integer or quoted string | Required; `6` only, without translation of older versions. |
| `promptkit` | native settings | Embedded and bundled resources, overlaid by selected sources. |
| `pipelines` | map | Empty; maps IDs to pipeline definitions. |
| `concurrency.workers` | positive integer | `64`; one shared ready-job pool. |
| `output.directory` | nonempty path | `./notarius-output`. |
| `cache_directory` | path | Omitted or empty selects `os.UserCacheDir()/notarius`. |
| `debug.directory` | path | Omitted selects `/tmp/notarius-debug`; explicit empty disables capture. |
Nonempty relative application destinations and reference paths resolve from the
file contributing the surviving declaration, including imported, overlaid, or
inherited values. A child replacement keeps the child's origin. Built-in relative
destinations use the selected main file's directory; invocation path overrides
use the working directory. Absolute paths remain absolute.
An empty output directory is invalid. Empty cache selection deliberately chooses
the per-user default; on Linux this normally follows `XDG_CACHE_HOME` or
`~/.cache`. Null is not a universal substitute for omission or empty: effective
types and application validation still apply. Directory selection does not
configure filesystem access policy or enable debug. See
[Operations](operations.md) for lifecycle, permissions, and provisioning.
## Imports And Sibling Inheritance
Root `config` contains native controls such as imports and sequence declarations.
For example:
~~~yaml
config:
imports:
- path: pipelines/dnd-session.yml
required: true
~~~
Imports are optional by default. Paths, directory selection, destinations,
sequence-item placement, source containment, and dependency-ready assembly order
follow [ConfigKit's import contract][imports]. Imported fragments need not repeat
the application version. A nested application field named `config` is ordinary
data, not another source-control block.
Mapping inheritance names a sibling, such as `extends: production` inside
`pipelines`. Identified-list inheritance uses an identity mapping such as
`extends: {id: parent}`. Parents must survive in the same sibling collection;
these are not paths or cross-namespace references.
Child mappings recursively overlay parents. Scalars and null replace inherited
values; an empty mapping does not clear existing fields. Lists follow their
native registered/declared composition policy. Pipeline steps are identified by
`id`: native upsert replaces a matching **whole record** in place and appends
new IDs. It does not patch fields of a matching step. Unidentified lists replace
as whole values across layers. Explicit replace with `[]` clears a list; empty
append/upsert does not. Validator lists are not automatically identified.
An identified record's `extends` can retain a distinct sibling's fields before
applying child changes. All surviving records remain real validated records,
not template-only definitions. Every final pipeline step executes and lane IDs
must be unique across the pipeline; inheriting a step's lanes does not remove
them. Pipeline-level inheritance with step upsert is suitable for full variants.
Omitted fields inherit; explicit zero, false, and empty collections retain their
presence. Null can clear an inherited value but remains subject to that field's
type and fallback semantics. Omitting `extends` retains a lower relationship;
`extends: null` cancels that relationship rather than independently deleting
other composed fields. `extends` is a reserved native configuration key, not
ordinary module-option data. See [native inheritance][inheritance] and
[sequence composition][sequences] for full rules.
Explicit configuration assignments use native mapping paths. They cannot walk
sequence indexes, assign the version, or introduce inheritance controls. Mapping
values overlay; list values replace the whole decoded list. Inheritance/defaulting
does not run again afterward. [CLI Reference](cli.md#configuration-selection)
owns assignment syntax.
## PromptKit Profiles
Native `promptkit` settings contain identified `backends`, `profiles`, and
`prompts` lists, plus a `collections` mapping. Notarius embeds its resources
in `collections.notarius`. Runtime IDs are qualified, for example
`notarius/dnd-extraction` and `notarius/dnd.spells`; the bundled root backend
is `openrouter`. Resource IDs are literal, not resource-version paths.
A collection's local record ID omits its namespace; references to resources in
that collection use the qualified runtime ID.
A wrapperless companion can add a profile variant:
~~~yaml
collections:
notarius:
profiles:
- id: campaign
extends: {id: dnd-extraction}
model: example-model
~~~
The pipeline can then select `llm_profile: notarius/campaign`. In the main
application file, place that same mapping beneath `promptkit`. The parent
reference is local to the same profile list; profile/backend references otherwise
name their intended exact ID. The [complete companion](../examples/dnd-complete/prompts.yml)
shows a runnable inherited backend/profile combination.
Later same-ID resources replace complete lower records, not selected fields.
Use a distinct inherited sibling to retain a parent's fields; replacing a record
with only one changed field does not implicitly keep the old definition.
Native `extends`, explicit null, list policy, and source contexts apply to
resources just as to other configuration. See [resource inheritance][resource-inheritance].
The embedded D&D profile selects `openrouter`, model `openai/gpt-5.6-luna`,
a `240` second timeout, and `flex` service tier, leaving reasoning unset.
Initial/correction pairs share their bundled default profile. Explicit application
profile selections and run overrides reach producers, validators, and correction
requests; validators can otherwise select their own profile.
A native backend supplies endpoint, credential-environment name, optional
capacity/queue controls, provider parameters, and explicit smoke metadata.
Profiles may supply backend or endpoint, model, sampling/token controls, timeout,
service tier, reasoning, credential policy, and provider parameters. Partial
profiles are valid; preparation must complete the actual target. Resource
inspection is not a backend-completed or run-overridden target prediction.
Notarius injects **no backend concurrency or queue defaults**. Native admission
is shared by backend ID within the engine, independently of workers; distinct
IDs do not automatically share capacity even if their endpoints match. An
endpoint-only profile has no backend identity. Configure native backend limits
when desired; the [upstream backend contract][backends] owns defaults and queue
semantics.
Profile omission, explicit values, and null differ. For example, native null
`endpoint` or `api_key_env` permits backend fallback, while an explicitly empty
string clears those sources; zero sampling values remain intentional. Blank/null
reasoning suppresses the outbound control. Changing backend/model does not
automatically clear unrelated explicit inherited settings. Use the
[native defaults table][profile-defaults], not inferred old-wrapper behavior.
Only credential environment **names** belong in files, never values. Native
secret-aware inspection preserves marked secret omissions; arbitrary prompt,
source, or extension data is not promised safe to disclose.
### Prompt Output Contracts And Schemas
Prompt declarations select response format, validation mode, and schema. Bundled
initial, correction, and validator prompts omit structural-repair counts:
Notarius inherits the upstream default, not an independent application-pinned
count. Native prompt customization can explicitly change that budget. Transient
provider retries are also native, distinct from application semantic turns.
See [native output contracts][output-contract].
Schemas may be inline, `schema_file` relative to its contributing source, or
`schema_path` within an explicit applicable `schema_root`. Exactly one schema
selection is used for JSON Schema mode. Null clears an alternative; switching
forms can require clearing the inherited selection. Native preparation reads
and compiles schemas; configuration/preflight does not read them.
Embedded Notarius prompts use their collection's filesystem-rooted schemas.
A nonnull collection root takes precedence over the root `promptkit.schema_root`;
absent/null collection roots fall back to that application root. A nonnull blank
root is invalid. Replacing `collections.notarius.schema_root` selects the new
context for its remaining path-based schemas. A missing file does not fall back
to embedded or working-directory roots. Other collections are unaffected.
Schema resources must be self-contained; native schema rules are in
[PromptKit's schema reference][schemas].
## Concurrency, Output, Cache, And Debug
`concurrency.workers` bounds active ready extraction and lane-completion jobs
together, including their validation/correction. It must be positive, has no
application maximum, and is independent of CPU count and native backend limits.
Explicit `1` gives serial jobs. Waiting for prerequisites occupies no worker;
nested validators do not request another worker. It is not a cross-backend
provider-call ceiling.
`output.directory`, `cache_directory`, and `debug.directory` select independent
roots. `/var/cache/notarius` is the convention for an explicitly provisioned
system-wide cache, not the per-user default. No directory setting creates a
permission policy or retention service.
A configured debug destination alone does not enable capture. Explicit empty
disables it; a nonempty invocation override can re-enable it. Native debug
selection and presentation modes are independent. See [CLI Reference](cli.md#run)
for invocation controls and [Operations](operations.md) for state handling.
## Pipelines
Each nonblank `pipelines` key defines a configured pipeline.
| Field | Type | Default / rules |
| --- | --- | --- |
| `llm_profile` | string | Optional qualified profile selection; explicit blank/null is invalid. |
| `mode` | `strict\|permissive` | Producer terminal mode; see below. |
| `max_additional_turns` | nonnegative integer | Semantic correction allowance excluding the initial response. |
| `cache` | `auto\|bypass\|refresh` | Eligible model-result reuse policy. |
| `input` | binding | Required. |
| `chunk` | binding | Defaults to `generic`. |
| `output` | binding | Defaults to `json`. |
| `artifacts` | lane map | Compact single-step form, mutually exclusive with `steps`. |
| `steps` | ordered list | Nonempty when selected; each record has a unique nonblank `id`, `artifacts`, and optional `references`. |
| `references` | map | External reference defaults for compatible targets. |
A lane ID is unique across all steps. Each lane requires `extract`, defaults
`merge` to `appendorder`, and defaults `normalize` to `noop`. References and
validator overrides belong on eligible bindings, not lane-wide fields.
Ordered steps finish before their generated artifacts feed later steps.
For each selected LLM role, profile precedence is explicit invocation override,
binding `llm_profile`, pipeline `llm_profile`, then native prompt default.
Deterministic roles do not receive LLM defaults/overrides and reject explicit
profile assignments. A supplied empty invocation profile clears the application
selection and lets the prompt default apply; configured blank profiles are invalid.
### Producer Controls
Chunk, extract, merge, and normalize bindings resolve controls before execution:
| Control | Precedence, highest first | Default |
| --- | --- | --- |
| `mode` | Binding, pipeline, application | `strict` |
| `max_additional_turns` | Binding, pipeline, application | `2` |
| `cache` | Explicit invocation cache, binding, pipeline, application | `auto` |
Omission inherits. Zero turns disables semantic correction; a positive allowance
is not a requirement to use every turn. The complete applicable validator chain
assesses each usable initial/revised candidate, including the final permitted
response. Native coordination owns conversation/iteration; the allowance does
not count transport retries or structural repair. Deterministic work does not
acquire conversations or generic retries.
Strict requires an accepted result. Permissive explicitly permits only the
module's supported fallback, with intrinsic shape/source/downstream checks,
without claiming ordinary semantic approval or rerunning the normal chain.
A whole-source D&D scene plan, empty extraction collection where valid, or safe
final normalization groups/merged input are supported directions. Scene
descriptions cannot use an invalid empty collection or fabricated description.
Unsupported fallback construction fails; cancellation stops without fallback.
Eligible cacheable work uses `auto` to read/store accepted results, `bypass`
for neither, and `refresh` to skip reads and replace only after new acceptance.
Failures preserve earlier acceptance. Fallback and actually affected dependent
work skip both lookup and storage; unrelated predecessors remain reusable.
Settings/policy changes may still reuse old accepted content; select bypass/
refresh when deliberately applying changed policy. Best-effort cache I/O does
not fail otherwise successful work. [Operations](operations.md) owns recovery
and physical storage, not a checkpoint/resume contract.
## Module Bindings And Validators
Every module binding is an object containing `module`, even without options.
| Binding field | Meaning |
| --- | --- |
| `module` | Registered compatible key; required. |
| `llm_profile` | Optional nonblank qualified profile for an LLM-backed role. |
| `mode`, `max_additional_turns`, `cache` | Resolved producer controls above. |
| `options` | Selected module's strict option object. |
| `references` | Declared slots on chunk/extract/merge/normalize bindings. |
| `validators` | Ordered replacement chain on those producer bindings. |
Omitted validators use the production default. `validators: []` replaces it
with an empty chain; a nonempty list replaces it in listed order. Null is not an
empty list. Validator bindings accept only `module`, optional LLM-backed
`llm_profile`, and `options`; they have no separate producer mode, semantic-turn
allowance, references, or nested validators. Each validator executes once per
candidate assessment. Intrinsic codec/schema checks remain with an empty chain,
as do source parsing, plan materialization, and necessary module/fallback/cache
construction checks. Ordinary artifact citation existence/containment checks
are supplied by configured validators and can be omitted by chain replacement.
See [default chains](#production-validator-keys-and-default-chains).
The `json` output options are:
| Option | Default / rules |
| --- | --- |
| `include_chunk_map` | Boolean, default false; publish when enabled and available. |
| `evidence_context` | Omitted disables publication; otherwise a strict object. |
| `evidence_context.enabled` | Required boolean; false permits no other evidence fields. |
| `evidence_context.lanes` | When enabled, required nonempty list of unique trimmed configured lane IDs. |
| `evidence_context.window_units` | When enabled, nonnegative integer, default `3`; zero keeps only directly cited units. |
Filtered-out configured lanes contribute no evidence. Unknown or incompatible
options fail. Evidence is opt-in because it can persist source text and metadata.
Logical formats belong to [chunk-map](integrations/chunk-map.md) and
[evidence-context](integrations/evidence-context.md) contracts.
## References And Ordered Handoffs
Reference maps bind named slots that the selected target declares. An external
reference is an object with `path`. Pipeline-level maps accept only external
paths; step-local and binding-local maps may also select a normalized artifact
from an earlier step:
~~~yaml
steps:
- id: describe-session
artifacts:
npc-registry:
extract:
module: dnd/npc-registry
normalize:
module: dnd/npc-registry
- id: extract-events
references:
npc_registry:
artifact:
step: describe-session
lane: npc-registry
artifacts:
spells:
extract:
module: dnd/spells
normalize:
module: dnd/spells
~~~
An artifact selector contains only **step** and **lane**. The producer must be
an earlier step and the selected artifact must be compatible with the consumer
slot. A generated binding supplies one normalized artifact in memory, including a
supported qualified fallback; it does not name a file. A configured generated
dependency remains required even when that consumer slot is otherwise optional.
Pipeline references are configuration defaults. A matching step-local or
binding-local external path overrides a pipeline default. CLI reference
bindings are then operational overrides of configured external paths; their
pipeline, lane, and binding scopes and precedence are defined by the
[CLI reference](cli.md#reference-selectors). A CLI file reference cannot
replace a configured generated artifact handoff. Required slots must be bound
after configuration and CLI reference actions are applied. A YAML reference
path resolves from the file that supplies its surviving declaration, including
an imported fragment or selected overlay. CLI reference paths resolve relative
to the process working directory.
### D&D Reference Slots
The following slot names are accepted by the implemented D&D modules when the
selected target declares them:
| Slot | Source and use |
| --- | --- |
| **party** | Optional text campaign context. This is the canonical party-roster spelling. |
| **roster** | Accepted compatibility alias for **party**. |
| **players** | Optional text player context. |
| **glossary** | Optional text campaign glossary. |
| **spell_catalog** | Optional JSON spell-catalog overlay for spell extraction and normalization. See [spell-catalog overlays](integrations/dnd-spell-catalog-overlays.md). |
| **location_registry** | Required normalized location registry for location-occurrence extraction and normalization. |
| **item_registry** | Required normalized item registry for item-occurrence extraction and normalization. |
| **npc_registry** | Normalized NPC registry. Optional for spells and combat turns; required for NPC occurrences and enemy-event extraction and normalization. |
| **scene_descriptions** | Required normalized scene-description artifact for combat-turn and enemy-event extraction. |
| **combat_turns** | Required normalized combat-turn artifact for enemy-event extraction. |
| **npc_occurrences** | Required normalized NPC-occurrence artifact for enemy-event extraction. |
Registry-backed occurrence and enemy-event artifact slots have the following
exact binding contracts. Durable semantics and wire shapes remain in their
[NPC occurrence](integrations/dnd-npc-occurrence-artifacts.md),
[location occurrence](integrations/dnd-location-occurrence-artifacts.md),
[item occurrence](integrations/dnd-item-occurrence-artifacts.md), and
[enemy-event](integrations/dnd-enemy-event-artifacts.md) contracts.
| Slot | Accepted artifact kind | Media type | Maximum size | Required stage |
| --- | --- | --- | --- | --- |
| `npc_registry` | `dnd/npc-registry` | `application/json` | 1,048,576 bytes | extract and normalize |
| `scene_descriptions` | `dnd/scene-description-list` | `application/json` | 1,048,576 bytes | extract only |
| `combat_turns` | `dnd/combat-turn-list` | `application/json` | 1,048,576 bytes | extract only |
| `npc_occurrences` | `dnd/npc-occurrence-list` | `application/json` | 1,048,576 bytes | extract only |
| `location_registry` | `dnd/location-registry` | `application/json` | 1,048,576 bytes | location-occurrence extract and normalize |
| `item_registry` | `dnd/item-registry` | `application/json` | 1,048,576 bytes | item-occurrence extract and normalize |
Scene descriptions accept **party**, **players**, and **glossary**, but not
**roster**. NPC occurrences require **npc_registry** for both extraction and
normalization. Combat turns require **scene_descriptions** for extraction; the
normalized combat-turn module may use optional **npc_registry**. Location occurrences
require **location_registry** for extraction and normalization. Item occurrences require
**item_registry** for extraction and normalization. Enemy-event extraction requires all
four of its JSON artifact slots; its normalizer requires **npc_registry**.
The [complete example](../examples/dnd-complete/config.yml) shows the ordered
generated bindings.
## Production Module Keys
| Kind | Keys |
| --- | --- |
| Input | **seriatim** |
| Chunk | **generic**, **dnd/scenes** |
| Extract | **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** |
| Merge | **appendorder** |
| Normalize | **noop**, **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** |
| Output | **json** |
`dnd/scenes` and every D&D extractor are `llm_backed`. The
`dnd/npc-registry`, `dnd/location-registry`, and `dnd/item-registry`
normalizers are also `llm_backed` for bounded duplicate proposals; every other
D&D normalizer is `deterministic`. LLM-backed bindings use the effective
[PromptKit profile](#promptkit-profiles). The complete example binds each
registry in an earlier step before its occurrence consumer.
The D&D artifact contracts define each emitted schema:
[spells](integrations/dnd-spell-artifacts.md),
[NPC registry](integrations/dnd-npc-registry-artifacts.md),
[NPC occurrences](integrations/dnd-npc-occurrence-artifacts.md),
[combat turns](integrations/dnd-combat-turn-artifacts.md),
[item registry](integrations/dnd-item-registry-artifacts.md),
[item occurrences](integrations/dnd-item-occurrence-artifacts.md),
[scene descriptions](integrations/dnd-scene-description-artifacts.md),
[enemy events](integrations/dnd-enemy-event-artifacts.md),
[location registry](integrations/dnd-location-registry-artifacts.md), and
[location occurrences](integrations/dnd-location-occurrence-artifacts.md).
## Production Validator Keys And Default Chains
Available validator keys are:
| Family | Keys |
| --- | --- |
| Generic | **generic/always_accept**, **generic/always_reject**, **generic/valid_json**, **generic/valid_json_schema** |
| Spells | **extract/dnd/spells/shape**, **extract/dnd/spells/catalog**, **extract/dnd/spells/source_refs**, **extract/dnd/spells/source_relatedness** |
| NPC registry | **extract/dnd/npc-registry/shape**, **extract/dnd/npc-registry/source_refs**, **extract/dnd/npc-registry/source_relatedness**, **normalize/dnd/npc-registry/identity** |
| Combat turns | **extract/dnd/combat-turns/shape**, **extract/dnd/combat-turns/source_refs**, **extract/dnd/combat-turns/source_relatedness**, **normalize/dnd/combat-turns/invariants** |
| Item occurrences | **extract/dnd/item-occurrences/shape**, **extract/dnd/item-occurrences/registry**, **extract/dnd/item-occurrences/source_refs**, **extract/dnd/item-occurrences/source_relatedness**, **normalize/dnd/item-occurrences/invariants** |
| Item registry | **extract/dnd/item-registry/shape**, **extract/dnd/item-registry/source_refs**, **extract/dnd/item-registry/source_relatedness**, **normalize/dnd/item-registry/identity** |
| NPC occurrences | **extract/dnd/npc-occurrences/shape**, **extract/dnd/npc-occurrences/registry**, **extract/dnd/npc-occurrences/source_refs**, **extract/dnd/npc-occurrences/source_relatedness**, **normalize/dnd/npc-occurrences/invariants** |
| Scene descriptions | **extract/dnd/scene-descriptions/shape**, **extract/dnd/scene-descriptions/source_refs**, **extract/dnd/scene-descriptions/source_relatedness**, **extract/dnd/scene-descriptions/combat_semantics** (LLM-backed, opt-in), **normalize/dnd/scene-descriptions/invariants** |
| Enemy events | **extract/dnd/enemy-events/shape**, **extract/dnd/enemy-events/engagements**, **extract/dnd/enemy-events/source_refs**, **extract/dnd/enemy-events/source_relatedness**, **normalize/dnd/enemy-events/invariants** |
| Location registry | **extract/dnd/location-registry/shape**, **extract/dnd/location-registry/source_refs**, **extract/dnd/location-registry/source_relatedness**, **normalize/dnd/location-registry/identity** |
| Location occurrences | **extract/dnd/location-occurrences/shape**, **extract/dnd/location-occurrences/registry**, **extract/dnd/location-occurrences/source_refs**, **extract/dnd/location-occurrences/source_relatedness**, **normalize/dnd/location-occurrences/invariants** |
`extract/dnd/scene-descriptions/combat_semantics` is not in a production default chain. To opt in, replace the scene extractor validator chain with the current ordered chain plus the semantic validator last, and retain a positive semantic-turn allowance if a rejection should request a corrected scene:
~~~yaml
extract:
module: dnd/scene-descriptions
max_additional_turns: 1
validators:
- module: generic/valid_json
- module: extract/dnd/scene-descriptions/shape
- module: extract/dnd/scene-descriptions/source_refs
- module: generic/valid_json_schema
- module: extract/dnd/scene-descriptions/source_relatedness
- module: extract/dnd/scene-descriptions/combat_semantics
~~~
An override replaces, rather than extends, the default chain. See [Module Bindings And Validators](#module-bindings-and-validators) for binding and profile rules, and [producer controls](#producer-controls) for semantic correction and terminal mode.
The validator runs once per candidate assessment. Native transient retries and
structural repair remain internal to that execution; there is no separate
validator semantic-turn allowance.
When no override is configured, production D&D bindings use the following
ordered chains. Each row lists extract then normalize; spell chains are the
same at both stages.
| Lane | Extract | Normalize |
| --- | --- | --- |
| Spells | generic/valid_json, extract/dnd/spells/shape, extract/dnd/spells/catalog, extract/dnd/spells/source_refs, generic/valid_json_schema, extract/dnd/spells/source_relatedness | Same as extract |
| NPC registry | generic/valid_json, extract/dnd/npc-registry/shape, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness | generic/valid_json, extract/dnd/npc-registry/shape, normalize/dnd/npc-registry/identity, extract/dnd/npc-registry/source_refs, generic/valid_json_schema, extract/dnd/npc-registry/source_relatedness |
| Combat turns | generic/valid_json, extract/dnd/combat-turns/shape, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness | generic/valid_json, extract/dnd/combat-turns/shape, normalize/dnd/combat-turns/invariants, extract/dnd/combat-turns/source_refs, generic/valid_json_schema, extract/dnd/combat-turns/source_relatedness |
| Item occurrences | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness | generic/valid_json, extract/dnd/item-occurrences/shape, extract/dnd/item-occurrences/registry, normalize/dnd/item-occurrences/invariants, extract/dnd/item-occurrences/source_refs, generic/valid_json_schema, extract/dnd/item-occurrences/source_relatedness |
| Item registry | generic/valid_json, extract/dnd/item-registry/shape, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness | generic/valid_json, extract/dnd/item-registry/shape, normalize/dnd/item-registry/identity, extract/dnd/item-registry/source_refs, generic/valid_json_schema, extract/dnd/item-registry/source_relatedness |
| NPC occurrences | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness | generic/valid_json, extract/dnd/npc-occurrences/shape, extract/dnd/npc-occurrences/registry, normalize/dnd/npc-occurrences/invariants, extract/dnd/npc-occurrences/source_refs, generic/valid_json_schema, extract/dnd/npc-occurrences/source_relatedness |
| Scene descriptions | generic/valid_json, extract/dnd/scene-descriptions/shape, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness | generic/valid_json, extract/dnd/scene-descriptions/shape, normalize/dnd/scene-descriptions/invariants, extract/dnd/scene-descriptions/source_refs, generic/valid_json_schema, extract/dnd/scene-descriptions/source_relatedness |
| Enemy events | generic/valid_json, extract/dnd/enemy-events/shape, extract/dnd/enemy-events/engagements, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness | generic/valid_json, extract/dnd/enemy-events/shape, normalize/dnd/enemy-events/invariants, extract/dnd/enemy-events/source_refs, generic/valid_json_schema, extract/dnd/enemy-events/source_relatedness |
| Location registry | generic/valid_json, extract/dnd/location-registry/shape, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness | generic/valid_json, extract/dnd/location-registry/shape, normalize/dnd/location-registry/identity, extract/dnd/location-registry/source_refs, generic/valid_json_schema, extract/dnd/location-registry/source_relatedness |
| Location occurrences | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness | generic/valid_json, extract/dnd/location-occurrences/shape, extract/dnd/location-occurrences/registry, normalize/dnd/location-occurrences/invariants, extract/dnd/location-occurrences/source_refs, generic/valid_json_schema, extract/dnd/location-occurrences/source_relatedness |
Chains are only registered for the D&D extract and normalize modules shown
above; select an explicit override when a different compatible chain is
required.
## Validation And Inspection
Configuration validation checks the selected native application document.
Pipeline validation additionally resolves production modules/options, validator
targets, references, generated handoffs, and statically known prompt/profile
dependencies. It needs no transcript, reference bytes, credential values,
provider calls, or state directories. Partial profiles pass; request-time data
and dynamic selections remain runtime checks. [CLI Reference](cli.md#pipeline-commands)
owns commands for both boundaries.
Native whole-app and focused PromptKit inspection use the same selected result
and secret-aware provenance. Profile inspection describes stored fields, not a
prediction of a completed request; prepared preview is the native request boundary.
See [configuration commands](cli.md#configuration-commands) and
[PromptKit commands](cli.md#promptkit-commands).
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[backends]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#backend-definitions
[profile-defaults]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#defaults-and-overrides
[resource-inheritance]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#resource-inheritance
[output-contract]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#output-contract
[schemas]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#schemas
[imports]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#explicit-imports
[overlays]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#selected-overlays
[inheritance]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#sibling-inheritance
[sequences]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#strict-document-composition