eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 18 Wiki Activity

Plan pipeline configuration improvements

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-30 03:41:56 +00:00
parent 8b4b328c4e
commit 3b5e9db41f
2 changed files with 1989 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

739
docs/roadmap/pipeline-configuration-ergonomics.md Normal file
View File

@@ -0,0 +1,739 @@
# Pipeline Configuration Ergonomics
## Status
Accepted target state. This document owns the intended feature scope, user
intent, policy choices, and target end state until the behavior is implemented.
## Goal
Make Narratio's pipeline configuration easier to organize, vary, inspect, and
reuse without weakening its strict configuration contract or turning it into a
general-purpose configuration or workflow language.
The feature should let operators:
- split a large pipeline configuration into explicitly imported partial files;
- maintain one production-default pipeline plus a selectable testing profile;
- keep stable settings separate from frequently edited models and artifacts;
- define a character-oriented artifact workflow once and expand it for every
character in the selected campaign;
- reuse one campaign-owned party roster across multiple artifact families and
the Notarius integration; and
- inspect and compare the fully resolved configuration before running a
session.
All composition and expansion must produce the same concrete, validated
`PipelineConfig` and concrete configured-artifact map consumed by the existing
stage, planning, manifest, artifact, and adapter boundaries.
## User Intent
Pipeline configuration currently combines long-lived platform and transcript
settings with model choices, prompt-backed artifact definitions, and publish
rules that change frequently during development. Keeping all of those concerns
in one file makes edits noisy and makes production/testing variation difficult
to review.
Character-specific artifacts introduce a second kind of repetition. Several
artifact families, including character meta-analysis and character-specific
item tracking, should execute once per campaign character. Their prompt,
inputs, dependencies, and output shape are shared, while player, character,
class, alias, and output identity vary by party member. Those campaign facts do
not belong in a global pipeline definition.
The desired model is therefore:
```text
pipeline.yml + explicit imports + one selected profile
│
campaign.yml + party.yml ─┤
▼
resolved effective configuration
│
expand party-driven families
│
defaults and strict validation
▼
existing concrete pipeline and artifact model
```
## Architectural Constraints
The feature must preserve the configuration and orchestration policies in
[`docs/policy/architecture.md`](../policy/architecture.md):
- YAML remains strict and rejects unknown fields.
- Defaults remain centralized and are applied exactly once.
- Composition and expansion are deterministic and testable.
- Session templating remains narrow; this feature does not introduce arbitrary
expressions, scripting, or a general template language.
- The canonical stage sequence and fixed invalidation relation remain
application-owned and non-configurable.
- Stages receive resolved Narratio-owned configuration and do not implement
import, profile, or family semantics independently.
- External tools continue to own their private runtime configuration and
defaults.
- Raw secrets remain indirect and are never introduced into composed YAML,
effective-configuration output, manifests, or diagnostics.
Configuration composition belongs to `internal/config`. CLI selection and
production loading belong to `internal/app`. Party parsing must be a
Narratio-owned campaign-input contract. Artifact-family expansion must finish
before existing configured-artifact validation, catalog construction,
planning, reconciliation, or execution begins.
## Configuration Imports
### Root document
Keep `pipeline.yml` as the selected pipeline entry point. Add an optional
top-level composition envelope with explicitly ordered imports:
```yaml
composition:
imports:
- conf.d/platform.yml
- conf.d/transcripts.yml
- conf.d/extraction.yml
- conf.d/artifacts.yml
- conf.d/publish.yml
default_profile: production
profiles:
production:
overlay: profiles/production.yml
testing:
overlay: profiles/testing.yml
```
An existing monolithic `pipeline.yml` without `composition` remains valid and
retains its current behavior. The root document may contain ordinary pipeline
fields alongside `composition`, allowing incremental migration.
`imports` is the public term. Imported files are partial pipeline
configuration documents rather than independently runnable pipelines.
### Import boundaries
- Only the root pipeline document may declare `composition`, imports, or
profiles. Imported and overlay documents cannot import other documents.
- Every import is explicit. Narratio does not automatically scan `conf.d` or
interpret unlisted files.
- Import paths are relative to the root pipeline file's directory, must remain
confined beneath that directory, and must resolve to supported regular YAML
files. Absolute paths, traversal, non-regular files, and cycles are rejected.
- All ordinary relative pipeline paths retain one stable base: the root
pipeline file's directory. Moving a field between imported files must not
silently change the meaning of its relative path.
- The declared import order is retained for diagnostics and provenance, but it
is not an implicit precedence mechanism between base imports.
- Composition metadata is removed before the effective mapping is decoded as
strict `PipelineConfig` data.
### Additive merge contract
Base configuration from the root document and its imports is additive:
- mappings merge recursively when their child fields are disjoint;
- two files may therefore contribute different entries beneath a shared map
such as `scriptorium.artifacts`;
- defining the same final field or keyed entry in more than one base source is
an error, even when the values are identical;
- lists are atomic values and cannot be contributed more than once at the same
base configuration path;
- mapping/scalar, mapping/list, and other incompatible type collisions are
errors; and
- duplicate YAML keys within one source remain errors.
Errors must identify the complete configuration path and every source file
that claims it. This contract prevents an import reorder or newly added file
from silently changing production behavior.
Composition must operate on a presence-aware YAML representation before Go
struct decoding. Merging already decoded structs is not sufficient because it
cannot reliably distinguish omission from explicitly configured `false`, zero,
an empty collection, or another meaningful zero value.
## Named Profiles
### Selection and precedence
Exactly one named profile may be active for an invocation. A composition root
may define `default_profile`; the maintained production-shaped configuration
uses `production`. Add `--profile <name>` to the common configuration flags for
every command that loads pipeline configuration:
```bash
narratio run SESSION
narratio run SESSION --profile testing
narratio session plan SESSION --profile testing
narratio regenerate-artifacts SESSION --profile testing
```
The explicit CLI value overrides `default_profile`. An unknown profile, a
profile selection against a configuration that defines no such profile, an
empty profile name, or a default naming an undefined profile is an error before
stage composition. Do not add an environment-variable selector in this
feature; profile selection should remain visible in the command or root
configuration.
Only one profile can be selected. Profiles cannot extend other profiles, and
callers cannot stack several profiles. A single overlay provides the required
production/testing variation without creating user-programmable precedence.
### Overlay semantics
The selected profile is the sole intentional override layer:
- mappings recursively merge with the assembled base mapping;
- scalar and boolean leaves replace base leaves;
- lists replace the complete base list rather than concatenate implicitly;
- keyed maps such as configured artifacts merge by key, allowing a testing
profile to add experimental artifacts;
- an existing artifact can be disabled explicitly with `enabled: false`;
- an overlay cannot change a value's YAML kind incompatibly; and
- the fully overlaid result undergoes the same strict decode, defaults, path
resolution, expansion, and validation as a monolithic configuration.
Generic deletion syntax is outside this feature. Shared definitions should
live in base imports, while production-only and testing-only definitions live
in their corresponding overlays. Existing enable/disable fields and complete
list replacement cover the required cases without a YAML patch language.
### Effective identity and provenance
Every loaded configuration must retain bounded, non-secret provenance:
- the root pipeline path;
- the selected profile name, including whether it came from the default or
CLI;
- the ordered imported and overlay source paths;
- a deterministic digest of the normalized effective pipeline configuration;
and
- enough source ownership information to explain composition errors and
effective values.
Run reporting and invocation state should identify the selected profile and
effective configuration digest. The profile name is provenance, not a blanket
cache key: changing profiles must invalidate only work whose result-affecting
effective configuration changed.
## Canonical Campaign Party Contract
### Ownership and schema
Make `party.yml` a strict, versioned Narratio campaign-input contract. A
canonical file has this shape:
```yaml
schema_version: narratio.party.v1
characters:
arannis:
player:
name: Eric
character:
name: Arannis
alias:
- Ari
- The Grey Owl
classes:
- name: wizard
level: 8
brenna:
player:
name: Jane
character:
name: Brenna
classes:
- name: paladin
level: 6
- name: warlock
level: 2
```
The contract has these semantics:
- `schema_version` is required and must equal `narratio.party.v1`.
- `characters` is a non-empty mapping.
- Each mapping key is the stable `character_id` and must satisfy the existing
configured-artifact key grammar.
- `player.name` and `character.name` are required, non-empty display strings.
- `character.alias` is optional and accepts a list of zero or more non-empty
alias strings. The singular field spelling `alias` is intentional.
- Leading or trailing whitespace and control characters in names, aliases, and
class names are rejected rather than silently normalized.
- A character alias cannot equal that character's primary name, another alias,
or another character's primary name or alias under case-insensitive
comparison. This keeps party-member grounding unambiguous. Player names may
repeat because one player may control more than one character.
- `character.classes` is required and non-empty. Every entry has a required
free-form `name` and an optional positive integer `level`.
- Class names are not restricted to a Narratio-owned D&D enumeration.
- Duplicate class names for one character are rejected case-insensitively.
- Class order and alias order are preserved.
- Narratio derives a deterministic class summary such as
`paladin 6 / warlock 2` and an alias summary that joins declared aliases with
`, ` in their declared order.
- Unknown fields and trailing YAML documents are rejected.
The stable `character_id`, rather than a display name, owns generated artifact
identity. Changing a display name, alias, class, or level retains that identity
and changes the relevant semantic inputs. Changing the mapping key is an
intentional remove-and-add operation.
### Load and prepare behavior
The selected campaign's effective `party_file` resolves relative to
`campaign.yml`. Narratio must load and validate canonical party data during
combined pipeline/campaign resolution so `session plan`, configuration
inspection, and artifact-family expansion see the same roster before stage
execution.
`prepare` continues to materialize the canonical document as
`inputs/party.yml`, record its source and content identity, and expose it as
`narratio.input.party`. The same canonical file is passed unchanged to
Notarius's `party` reference slot, which currently accepts YAML reference
material without imposing a competing roster schema.
### Players projection and compatibility
The canonical party document becomes the eventual single source of truth for
player-to-character relationships. Narratio derives a deterministic,
documented players-only YAML projection during prepare, materializes it at
`inputs/players.yml`, records its content identity, and exposes it through the
existing `narratio.input.players` source. This preserves the separate Notarius
`players` reference and existing Scriptorium source without requiring every
campaign to maintain duplicate facts.
The projection uses this versioned shape, with entries sorted by stable
character ID:
```yaml
schema_version: narratio.players.v1
players:
- name: Eric
character:
id: arannis
name: Arannis
alias:
- Ari
- The Grey Owl
```
There is one projection entry per character rather than one grouped entry per
display player name. This permits one player to control several characters and
does not conflate distinct players who happen to share a display name.
Backward compatibility must be narrow and removable:
- an unversioned legacy party file continues to be treated as opaque reference
material when the existing `players_file` is also configured;
- legacy mode preserves the current prepared `party` and `players` behavior
but cannot drive artifact-family expansion;
- configuring a party-driven artifact family with a legacy roster produces a
clear migration error;
- canonical `narratio.party.v1` mode derives players and rejects a separate
`players_file`, preventing contradictory authorities;
- parsing, validation, documentation, and tests for legacy mode live behind a
clearly identified compatibility boundary with comments stating that it is
intended for removal after migration; and
- the maintained examples migrate to canonical mode and demonstrate no
separate players file.
The derived players projection is a durable integration contract and must be
documented under `docs/integrations/` rather than left as incidental generated
YAML.
## Party-Driven Artifact Families
### Configuration model
Add `scriptorium.artifact_families`, separate from the existing concrete
`scriptorium.artifacts` map:
```yaml
scriptorium:
artifact_families:
character_meta:
enabled: true
for_each: party.characters
prompt_id: dnd.character_meta
profile_id: production
output_path_pattern: artifacts/characters/{character_id}/meta.md
inputs:
transcript:
source: narratio.transcript.final_trimmed
required: true
member_vars:
player_name: player.name
character_name: character.name
character_class: character.class_summary
character_aliases: character.alias_summary
character_items:
enabled: true
for_each: party.characters
prompt_id: dnd.character_items
profile_id: production
output_path_pattern: artifacts/characters/{character_id}/items.md
inputs:
transcript:
source: narratio.transcript.final_trimmed
required: true
item_occurrences:
source: narratio.extraction.item_occurrences
required: true
member_vars:
character_name: character.name
```
Families support the ordinary result-affecting fields shared by concrete
Scriptorium artifacts: enablement, prompt and profile IDs, timeout,
render-debug policy, ordinary dependencies, inputs, and static variables.
`output_path_pattern` replaces concrete `output_path` at the family level.
`for_each` is not an expression language. This feature accepts only the exact
source `party.characters`. `member_vars` maps a Scriptorium variable name to
one of a closed set of canonical values:
- `character_id`;
- `player.name`;
- `character.name`;
- `character.class_summary`; and
- `character.alias_summary`.
Static `vars` and resolved member variables merge deterministically. Duplicate
variable names across the two maps are rejected rather than assigned implicit
precedence. Narratio's existing reserved sticky-session variable remains
application-owned and is applied after expansion under its current rules.
### Narrow substitution
`{character_id}` is the only family substitution supported in this feature.
It is required in `output_path_pattern` and may appear exactly where documented
for family-owned publish destinations. Unknown, repeated in an invalid
position, unresolved, or malformed substitutions are errors. Names, aliases,
classes, environment values, and arbitrary YAML paths cannot be interpolated
into configuration strings.
### Concrete expansion
For each family and party character, resolution creates one ordinary concrete
artifact key by joining the normalized family key, an underscore, and the
stable character ID:
```text
character_meta_arannis
character_items_arannis
```
Expansion must be sorted, deterministic, and completed before existing
configured-artifact defaults and validation. Every generated artifact then
uses the existing catalog, dependency planner, fingerprinting, manifest,
reconciliation, execution, materialization, and publish boundaries.
Validation rejects:
- invalid family keys or character IDs;
- generated keys that fail the existing configured-artifact grammar;
- collisions between generated artifacts, explicit concrete artifacts, or
family names;
- duplicate or escaping output paths;
- a family with no canonical party source;
- invalid member-variable selectors;
- a selected profile that leaves an executable family incomplete; and
- any expanded artifact that fails ordinary concrete-artifact validation.
An added party character creates missing concrete artifacts. Removing a
character removes those artifacts from effective configuration so existing
analyze reconciliation classifies their old records as removed. A change to a
member field changes only fingerprints that actually consume its resolved
value or the party document as an input.
### Dependencies between families
Ordinary `depends_on` continues to name shared concrete artifacts such as
`session_recap`. Add a typed `member_dependencies` list for corresponding
members of another family:
```yaml
character_items:
member_dependencies:
- character_meta
```
For `arannis`, this expands to a dependency on
`character_meta_arannis`. The referenced family must use the same party source
and generate the same character ID. Cycles and missing members are rejected by
the existing concrete dependency validation after expansion.
When a family input consumes the corresponding member output, provide a narrow
pre-expansion member-artifact source form owned by configuration resolution.
The syntax is:
```yaml
inputs:
prior_meta:
source: narratio.member_artifact.character_meta
required: true
```
For the `arannis` member, this resolves to
`narratio.artifact.character_meta_arannis` before ordinary runtime validation.
The referenced family must also appear in `member_dependencies`. The
`narratio.member_artifact.*` form must not survive into stage or adapter
configuration as a new runtime artifact kind.
### Selection and reporting
Extend artifact selection so an exact family key selects all of that family's
concrete members. An exact generated key selects only that member. Explicitly
selecting a disabled family follows the existing rule for explicitly selected
disabled concrete artifacts: all generated targets must still have valid
executable fields. Mixed family and concrete selections are normalized and
deduplicated after expansion.
Planning, run summaries, artifact listing, and effective-configuration output
must show both family origin and concrete artifact identity. Execution remains
entirely concrete; a family is not a dynamic pipeline stage or runtime loop.
### Family publish rules
Allow a family to declare one typed publish policy so operators need not repeat
one publish output per character:
```yaml
publish:
enabled: true
required: false
dest_pattern: artifacts/characters/{character_id}/meta.md
```
Resolution expands this into ordinary concrete publish rules. When
`dest_pattern` is omitted, the generated artifact's output path is used where
the existing publish contract permits derivation. Conflicts with explicit
publish rules, duplicate destinations, unsafe paths, and generated sources
that are unavailable are rejected by the existing publish policy after
expansion. Family publish behavior must not introduce wildcard source matching
at runtime.
## Profile-Safe Resume And Invalidation
Named profiles are safe only if result-affecting model and configuration
changes cannot silently reuse incompatible successful stage results. Artifact
analysis already has a versioned semantic fingerprint that includes effective
prompt/profile identifiers, variables, dependencies, inputs, and output
identity. The broader pipeline requires the same principle at every applicable
stage boundary.
Audit each stage's resume contract and add a versioned semantic configuration
fingerprint wherever current evidence does not already cover all
Narratio-observable result-affecting settings. In particular, switching an
Audita model through a profile must not reuse polish output produced by the
testing model. Conversely, changing only an operational timeout, binary path,
workspace path, diagnostic location, or profile name must not invalidate
byte-equivalent semantic work unless that value genuinely affects the stage's
canonical result.
The selected profile name and complete effective-config digest are retained as
provenance. Resume decisions use stage-specific effective semantics rather
than the profile name as a blanket invalidator. This permits production and
testing profiles to share unaffected transcript work while correctly staling
changed stages and their fixed transitive dependents.
Private configuration, prompt, model, executable, and module contents loaded
inside an external tool remain outside Narratio's observable fingerprint
boundary unless an existing integration contract exposes their identity.
Changing such private inputs continues to require explicit force, and the
documentation must not claim otherwise.
## Configuration Inspection
Add a `config` command family that performs composition without running a
session:
```bash
narratio config validate [--config <pipeline.yml>] [--profile <name>]
narratio config show [--config <pipeline.yml>] [--profile <name>]
narratio config sources [--config <pipeline.yml>] [--profile <name>]
narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>]
```
Required behavior:
- `validate` composes imports and the selected profile, resolves campaign data
when required for party-driven families, expands artifacts and publish rules,
applies defaults, and runs strict validation without creating session or run
state.
- `show` emits deterministic normalized effective YAML, including generated
concrete artifacts, without raw credentials or environment values.
- `sources` reports root, import, profile, campaign, and party provenance and
identifies which source owns effective configuration paths.
- `diff` compares normalized effective configurations rather than raw files
and clearly identifies additions, removals, and value changes.
- output order is deterministic and suitable for review, but output formatting
is not a substitute for the effective configuration digest.
If family expansion requires a campaign, these commands accept the existing
campaign selection mechanisms or report clearly that pipeline-only validation
cannot complete the party-dependent portion. They must not silently choose an
unintended campaign.
## Required Application Changes
The implemented feature will require coordinated changes across existing
owners rather than a parallel configuration subsystem:
- `internal/config`: presence-aware YAML composition, import confinement,
profile overlays, provenance, effective digesting, party parsing and
validation, players projection, family expansion, defaults, and final strict
validation;
- `internal/app`: `--profile` plumbing through every configuration-consuming
command, `config` inspection commands, campaign-aware inspection, profile
reporting, and one shared loading path;
- `internal/artifactpolicy` and `internal/artifacts`: generated concrete source
registration, family-aware selection metadata, derived-player identity, and
reuse of the existing configured-artifact grammar and path policy;
- `internal/stage`: consumption only of expanded concrete artifacts, party and
derived-player preparation, and stage-specific semantic resume evidence;
- `internal/manifest`: bounded profile/effective-config provenance and any
versioned stage semantic fingerprints required for safe reuse;
- publish planning: expansion of family publish declarations into existing
concrete rules before ordinary validation and execution;
- Notarius composition: continue passing prepared `party` and `players`
sources, with canonical mode sourcing both from the party-owned contract;
and
- Scriptorium composition: receive only resolved concrete artifacts and
string/bool variables under the existing adapter contract.
There must be one production configuration-loading path. Remote session
loading, restore, status, planning, helper commands, and execution must not
independently reimplement import, profile, campaign, or family selection.
## Documentation And Examples
When behavior is implemented, update the canonical owners in the same change:
- [`docs/config.md`](../config.md): import, merge, profile, party selection,
family fields, defaults, and validation contracts;
- [`docs/cli.md`](../cli.md): `--profile` and `config` command syntax and output
behavior;
- [`docs/operations.md`](../operations.md): recommended production/testing
bundle layout, migration, inspection, and profile-switching workflow;
- [`docs/policy/architecture.md`](../policy/architecture.md): only the durable
composition, campaign-data ownership, and semantic-resume invariants;
- `docs/integrations/`: the canonical party and derived players YAML contracts;
- [`docs/internal/overview.md`](../internal/overview.md) and focused internal
configuration, manifest, analyze, prepare, and publish documents: implemented
ownership and mechanics; and
- `examples/`: a validated split configuration bundle, production/testing
overlays, canonical party roster with aliases and multiclass data, at least
two party-driven artifact families, and representative family publishing.
Do not copy complete example bundles into reference prose. Maintained examples
must be secret-free and loaded by the repository's example validation test.
## Testing Expectations
Testing should protect the public contracts and high-risk composition and
state-reuse behavior without coupling to private merge helpers. Required
confidence includes:
- monolithic configuration compatibility;
- recursive mapping composition and all duplicate/type/list conflict classes;
- import confinement, missing files, non-regular files, unsupported nesting,
source-aware diagnostics, deterministic ordering, and duplicate YAML keys;
- explicit zero-value profile overrides, list replacement, keyed-map additions,
unknown profiles, invalid defaults, and absence of profile stacking;
- canonical party schema validation, aliases, alias/name ambiguity, multiclass
summaries, stable IDs, malformed data, and legacy/canonical mode separation;
- deterministic players projection and prepared-input provenance;
- deterministic multi-family expansion, generated identities and paths,
variable binding, same-member dependencies, collisions, additions,
removals, and family selection;
- expansion into ordinary analyze planning, fingerprints, manifests, partial
selection, failure handling, and publish rules;
- model/profile changes staling only stages whose semantic configuration
changed while unaffected transcript work remains reusable;
- representative CLI validation, show, sources, diff, plan, and run behavior;
and
- maintained monolithic, imported, production, and testing examples loading
and validating offline.
Use package-level behavioral tests through the narrowest stable owner. A small
number of assembled workflow tests should prove that composed profiles and
party-driven families reach the existing pipeline correctly; higher-level
tests should not repeat every parser and validation case.
## Compatibility And Migration
- Existing monolithic pipeline files remain supported.
- Omitting `--profile` retains existing behavior for configurations without
profiles and selects the declared production default for composed bundles.
- Existing explicit concrete Scriptorium artifacts and publish rules remain
valid and may coexist with non-colliding families.
- Legacy opaque party plus players files remain temporarily usable only through
the isolated compatibility mode and cannot power party-driven families.
- Migration consists of converting the campaign party document to
`narratio.party.v1`, removing the separate players file, and then enabling
party-driven families.
- Configuration inspection must make the migration result reviewable before a
session run.
- Compatibility code and documentation must clearly identify the eventual
removal boundary; new features must target canonical party mode rather than
extend legacy semantics.
## Non-Goals And Deferred Work
This feature does not introduce:
- automatic loading of every file in `conf.d`;
- recursive imports, imports in profile overlays, or profile inheritance;
- multiple simultaneously active profiles;
- environment-selected profiles;
- generic YAML patch/delete operations;
- arbitrary string interpolation, expressions, scripting, or loops;
- artifact expansion from arbitrary files, Notarius outputs, or runtime data;
- configurable pipeline stages or a workflow DAG;
- runtime wildcard artifact or publish sources;
- automatic hashing of private external-tool configuration, prompts, modules,
models, or executables; or
- immediate removal of the isolated legacy party/player compatibility path.
Named reusable parameter sets beyond the canonical party roster may be
considered later if a second non-party use case demonstrates a need. Additional
party-member types, campaign-domain fields, or family iteration sources should
be added only through a versioned schema decision rather than an untyped
extension map.
## Target End State
The feature is complete when:
- operators can organize a pipeline as a root file plus explicit additive
imports with deterministic, source-aware conflict errors;
- one production-default or explicitly selected testing profile applies a
deliberate override without duplicating stable configuration;
- every command uses the same resolved profile and reports its identity;
- a campaign owns one strict, versioned party roster containing stable
character IDs, players, character names, optional alias lists, and one or
more classes;
- Narratio derives the existing players input from that roster and supplies the
canonical campaign context to Notarius;
- multiple Scriptorium artifact families expand once per campaign character
into ordinary concrete artifacts, dependencies, variables, output paths, and
optional publish rules;
- adding, changing, or removing a character produces deterministic and
manifest-correct artifact reconciliation;
- profile model changes cannot silently reuse semantically incompatible stage
outputs and do not unnecessarily invalidate unaffected transcript work;
- operators can validate, display, trace, and compare effective configuration
without executing a session;
- existing monolithic and concrete-artifact configurations remain compatible;
and
- current user, operator, integration, architecture, internal, and example
documentation accurately owns the implemented contracts.