Update Notarius integration and plan references
This commit is contained in:
274
docs/roadmap/notarius-v0.6-cli-references.md
Normal file
274
docs/roadmap/notarius-v0.6-cli-references.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Notarius v0.6 CLI Reference Integration
|
||||
|
||||
## Status
|
||||
|
||||
Accepted target state. Delivery sequencing and implementation status are owned
|
||||
by [implementation.md](implementation.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
Upgrade Narratio's extraction boundary to the Notarius v0.6.0 subprocess
|
||||
contract and supply session reference documents explicitly with repeatable
|
||||
`--reference selector=path` arguments.
|
||||
|
||||
The maintained D&D integration must make the prepared party roster, player
|
||||
context, glossary, and optional spell catalog available to every compatible
|
||||
Notarius target. Notarius must continue to own pipeline topology, reference-slot
|
||||
compatibility, generated artifact handoffs, prompts, and D&D schemas. Narratio
|
||||
owns selection and preparation of its external reference files, exact CLI
|
||||
invocation, provenance, and extraction reuse correctness.
|
||||
|
||||
## Current State And Gap
|
||||
|
||||
Narratio currently invokes Notarius as:
|
||||
|
||||
```text
|
||||
notarius run <pipeline_id> --config <config_path> --input <transcript> --output-dir <staging_dir> --json
|
||||
```
|
||||
|
||||
The `prepare` stage already materializes campaign/session party, players, and
|
||||
glossary files under the session `inputs/` directory, but `extract` does not
|
||||
pass them to Notarius. Narratio also has no stable spell-catalog input. As a
|
||||
result, a Notarius deployment must duplicate these paths in its own
|
||||
configuration, cannot reliably receive session overrides, and may extract
|
||||
without the same campaign context supplied to Narratio's analysis stage.
|
||||
|
||||
Notarius v0.6.0 makes an unqualified CLI selector pipeline-scoped. For example,
|
||||
`--reference party=/absolute/path/party.yml` supplies the file to every
|
||||
selected target that declares `party`. Scoped selectors remain available for
|
||||
exceptional overrides. CLI paths are resolved from the Notarius process working
|
||||
directory, so subprocess callers are expected to provide absolute paths.
|
||||
|
||||
The v0.6.0 receipt, index, warning, diagnostic, and ten-lane D&D artifact
|
||||
contracts remain compatible with Narratio's current v0.5 integration. This
|
||||
feature changes the invocation and input-provenance contract rather than the
|
||||
accepted output inventory.
|
||||
|
||||
## User Outcome
|
||||
|
||||
With the maintained complete D&D configuration, an operator can declare the
|
||||
campaign reference sources once in Narratio. For each extraction Narratio will:
|
||||
|
||||
1. materialize the effective campaign/session files during `prepare`;
|
||||
2. resolve those prepared files by stable Narratio source ID;
|
||||
3. pass absolute paths for `party`, `players`, `glossary`, and, when configured,
|
||||
`spell_catalog` to Notarius through repeatable CLI arguments;
|
||||
4. fail before launching Notarius when a configured reference is unavailable;
|
||||
5. rerun extraction when a selector, source binding, or reference file changes;
|
||||
and
|
||||
6. retain bounded reference identities and checksums for diagnosis and
|
||||
provenance without copying reference contents into manifest metadata.
|
||||
|
||||
Session-level stable-input overrides must flow through the same mechanism. A
|
||||
custom Notarius pipeline may bind different external slots without requiring a
|
||||
Narratio code change.
|
||||
|
||||
## Chosen Architecture
|
||||
|
||||
### Explicit Reference Bindings
|
||||
|
||||
Extend `pipeline.notarius` with an explicit map from a Notarius CLI selector to
|
||||
a prepared Narratio input source:
|
||||
|
||||
```yaml
|
||||
notarius:
|
||||
enabled: true
|
||||
binary: notarius
|
||||
config_path: /usr/local/etc/notarius/config.yml
|
||||
pipeline_id: dnd-session
|
||||
working_directory: /usr/local/etc/notarius
|
||||
references:
|
||||
party: narratio.input.party
|
||||
players: narratio.input.players
|
||||
glossary: narratio.input.glossary
|
||||
spell_catalog: narratio.input.spell_catalog
|
||||
outputs:
|
||||
# Existing required lane contracts remain unchanged.
|
||||
```
|
||||
|
||||
Each configured binding is required. An operator who does not maintain an
|
||||
optional Notarius reference, such as a spell catalog, omits that binding. This
|
||||
keeps missing-input behavior explicit and avoids a second required/optional
|
||||
policy inside each entry.
|
||||
|
||||
The maintained complete D&D example will show all four external reference
|
||||
slots. The three existing campaign context bindings use the canonical `party`,
|
||||
`players`, and `glossary` spellings. Narratio will not emit the deprecated
|
||||
`roster` alias.
|
||||
|
||||
The binding is deliberately source-based rather than path-based. Pipeline
|
||||
configuration should not reconstruct session workspace paths or bypass
|
||||
`prepare`; it names the stable input whose effective campaign/session value is
|
||||
already owned by Narratio. The map also avoids hard-coded behavior keyed to the
|
||||
literal `dnd-session` pipeline ID, preserving custom-pipeline support.
|
||||
|
||||
Narratio accepts the selector forms published by Notarius v0.6.0:
|
||||
|
||||
- `slot`;
|
||||
- `chunk.slot`;
|
||||
- `lane.slot`; and
|
||||
- `lane.extract.slot`, `lane.merge.slot`, or `lane.normalize.slot`.
|
||||
|
||||
Configuration validation will reject empty or structurally invalid selectors,
|
||||
selectors containing `=`, unsupported source IDs, and duplicate YAML keys.
|
||||
Notarius remains authoritative for whether a selected target actually declares
|
||||
the slot and whether a file satisfies that slot's media type and size contract.
|
||||
Narratio will not duplicate the Notarius module registry.
|
||||
|
||||
### Stable Reference Inputs
|
||||
|
||||
Continue to use the existing prepared sources and canonical files:
|
||||
|
||||
| Narratio source | Prepared file | Notarius slot |
|
||||
| --- | --- | --- |
|
||||
| `narratio.input.party` | `inputs/party.yml` | `party` |
|
||||
| `narratio.input.players` | `inputs/players.yml` | `players` |
|
||||
| `narratio.input.glossary` | `inputs/glossary.yml` | `glossary` |
|
||||
| `narratio.input.spell_catalog` | `inputs/spell_catalog.json` | `spell_catalog` |
|
||||
|
||||
Add optional `spell_catalog_file` fields to campaign and session inputs, with
|
||||
the existing campaign-default/session-override resolution behavior. When
|
||||
provided, `prepare` copies it into the session input area and records its
|
||||
origin and checksum consistently with the other stable inputs. The prepared
|
||||
filename remains JSON so Notarius can apply its published spell-catalog media
|
||||
contract.
|
||||
|
||||
The new source must be added everywhere stable inputs are enumerated: strict
|
||||
configuration decoding and merging, validation, prepare materialization,
|
||||
artifact policy/source descriptions, operator inspection, manifest input
|
||||
records, examples, and canonical documentation. It remains optional at the
|
||||
campaign level; a configured Notarius binding makes it mandatory for that
|
||||
extraction.
|
||||
|
||||
Extract and analyze should use one shared prepared-input source resolver rather
|
||||
than maintain separate source-to-filename tables. The resolver must return an
|
||||
absolute, regular, non-empty file beneath the current session workspace and
|
||||
produce actionable `prepare --force` guidance when a configured source is
|
||||
missing. It must not fall back to the original campaign path after preparation.
|
||||
|
||||
### Adapter Request And CLI Construction
|
||||
|
||||
Extend the transport-neutral Notarius run request with an ordered collection of
|
||||
resolved reference bindings. Each binding contains only its selector and
|
||||
absolute prepared-file path. The extraction stage resolves source IDs and file
|
||||
identity; the subprocess adapter validates and serializes the request.
|
||||
|
||||
The production command becomes:
|
||||
|
||||
```text
|
||||
notarius run <pipeline_id>
|
||||
--config <config_path>
|
||||
--input <trimmed_json>
|
||||
--output-dir <staging_dir>
|
||||
--reference party=<absolute_prepared_party_path>
|
||||
--reference players=<absolute_prepared_players_path>
|
||||
--reference glossary=<absolute_prepared_glossary_path>
|
||||
--reference spell_catalog=<absolute_prepared_spell_catalog_path>
|
||||
--json
|
||||
```
|
||||
|
||||
Only configured bindings are emitted. Selectors are sorted before request
|
||||
construction so argument order, tests, logs, and fingerprints are deterministic.
|
||||
Arguments are passed directly to the subprocess without shell interpretation;
|
||||
paths containing spaces or platform-specific separators remain one argument.
|
||||
|
||||
CLI bindings intentionally override matching external paths in the deployed
|
||||
Notarius configuration. Narratio must not pass `--without-reference` and must
|
||||
not synthesize CLI bindings for `location_registry`, `item_registry`,
|
||||
`npc_registry`, `scene_descriptions`, `combat_turns`, or `npc_occurrences`.
|
||||
Those are generated same-run artifact handoffs in the complete D&D pipeline and
|
||||
remain entirely under Notarius configuration and execution control. A custom
|
||||
configuration that collides an external CLI binding with a generated handoff is
|
||||
expected to fail with Notarius's normal resolution error.
|
||||
|
||||
### Fingerprints, Resume, And Provenance
|
||||
|
||||
Reference identity is part of the extraction input contract. The extraction
|
||||
fingerprint and resume validator must include, in deterministic selector order:
|
||||
|
||||
- the selector;
|
||||
- the configured Narratio source ID;
|
||||
- the resolved prepared path identity; and
|
||||
- the prepared file's content checksum and size.
|
||||
|
||||
This is required even though Notarius generates a prompt session ID from the
|
||||
input module and transcript bytes: Notarius intentionally does not include
|
||||
references in that identifier. Narratio must therefore prevent an old
|
||||
extraction from being reused after a roster, player list, glossary, spell
|
||||
catalog, selector, or source mapping changes.
|
||||
|
||||
A changed reference makes the prior `extract` result non-reusable and follows
|
||||
Narratio's normal downstream invalidation rules. A failed reference-resolution
|
||||
or checksum check also prevents reuse; it must not silently accept the prior
|
||||
bundle.
|
||||
|
||||
Successful extract metadata should record a bounded, deterministic list of
|
||||
selector, source ID, workspace-relative path, checksum, and size. It must not
|
||||
record reference contents, original absolute operator paths, or values from the
|
||||
files. Existing receipt and bundle provenance behavior remains unchanged.
|
||||
|
||||
### Error And Compatibility Behavior
|
||||
|
||||
Narratio's documented minimum supported Notarius version becomes v0.6.0 for an
|
||||
enabled reference binding. Compatibility remains contract-based rather than
|
||||
dependent on parsing `notarius --version`: an older or incompatible executable
|
||||
will fail at the CLI boundary with captured diagnostics.
|
||||
|
||||
Errors must identify the responsible selector and Narratio source without
|
||||
including file contents. Configuration errors are reported before pipeline
|
||||
execution. Missing, empty, non-regular, unsafe, or unreadable prepared files
|
||||
fail extraction before the Notarius subprocess starts. Notarius continues to
|
||||
report undeclared slots, media incompatibility, size limits, required-slot
|
||||
failures, and generated-handoff collisions.
|
||||
|
||||
When Notarius is disabled, extraction retains its current explicit skip
|
||||
behavior and does not resolve reference inputs. Receipt v2 ingestion, bundle
|
||||
confinement, ten-lane selection, and downstream artifact source IDs are not
|
||||
otherwise changed by this feature.
|
||||
|
||||
## Target End State
|
||||
|
||||
Narratio and Notarius have a clear orchestration boundary:
|
||||
|
||||
- `prepare` owns the effective, immutable session copies of external campaign
|
||||
context;
|
||||
- `extract` maps configured stable source IDs to Notarius v0.6 CLI selectors,
|
||||
supplies absolute file paths, and owns reuse/provenance policy;
|
||||
- the Notarius adapter owns exact subprocess serialization and supported result
|
||||
decoding;
|
||||
- Notarius owns slot compatibility, reference precedence within its pipeline,
|
||||
generated artifact handoffs, and output schemas; and
|
||||
- `analyze` consumes the resulting ten structured lane artifacts exactly as it
|
||||
does today.
|
||||
|
||||
The maintained complete D&D workflow passes party, players, glossary, and spell
|
||||
catalog context from the same prepared session inputs used elsewhere in
|
||||
Narratio. Updating any of those documents deterministically causes fresh
|
||||
extraction, and operators can diagnose the effective bindings without exposing
|
||||
file contents.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Reproducing Notarius pipeline, lane, binding, or media-type validation in
|
||||
Narratio.
|
||||
- Passing or overriding Notarius generated artifact handoffs.
|
||||
- Adding `--without-reference`, Notarius resume/recompute controls, lane
|
||||
selection, model selection, profile selection, or session-ID overrides.
|
||||
- Changing the ten accepted D&D lane contracts or the Scriptorium analysis
|
||||
design.
|
||||
- Reading reference payloads into Narratio manifests or logs.
|
||||
- Automatically running `notarius config validate` for every session.
|
||||
|
||||
## Settled Policy Choices
|
||||
|
||||
The implementation must preserve these choices unless implementation evidence
|
||||
shows a contract conflict:
|
||||
|
||||
- explicit selector-to-source mappings are preferred over pipeline-ID-specific
|
||||
defaults;
|
||||
- every configured mapping is required;
|
||||
- `spell_catalog_file` is optional until a mapping requests its prepared
|
||||
source;
|
||||
- the complete D&D example demonstrates all four external references; and
|
||||
- Notarius v0.6.0 is the minimum supported CLI contract for reference-enabled
|
||||
extraction.
|
||||
Reference in New Issue
Block a user