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

Update Notarius integration and plan references

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-29 14:41:22 +00:00
parent e433c86203
commit 42ed81cbe1
11 changed files with 1450 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

546
docs/roadmap/implementation.md Normal file
View File

@@ -0,0 +1,546 @@
# Notarius v0.6 CLI References Implementation Plan
## Purpose And Status
This is the executable implementation plan for the accepted target state in
[Notarius v0.6 CLI Reference Integration](notarius-v0.6-cli-references.md). It
is written for a `gpt-5.6-terra` coding agent that will implement exactly one
pending stage per prompt, in order.
The feature roadmap owns user intent, architectural boundaries, settled policy,
and the target end state. This document owns delivery order, concrete changes,
test allocation, and implementation status. Do not restate or change a roadmap
decision here during implementation; if current Notarius v0.6.0 evidence
contradicts the roadmap, stop and record the conflict instead of inventing a
different contract.
| Stage | Outcome | Status |
| ---: | --- | --- |
| 1 | Add the reference-selector and configuration vocabulary, including optional spell-catalog inputs. | Pending |
| 2 | Materialize and inventory the optional spell catalog through the prepare and operator lifecycle. | Pending |
| 3 | Centralize manifest-authoritative prepared-input resolution and migrate analyze to it. | Pending |
| 4 | Add deterministic Notarius v0.6 reference arguments at the subprocess adapter boundary. | Pending |
| 5 | Resolve references in extract and bind fingerprints, resume, and metadata to their identities. | Pending |
| 6 | Prove assembled extraction lifecycle and downstream invalidation behavior. | Pending |
| 7 | Update canonical documentation and maintained examples for the completed feature. | Pending |
| 8 | Perform compatibility, quality, and repository-wide closure validation. | Pending |
## Governing Decisions
The following requirements are settled and are not questions for the
implementing agent:
1. `pipeline.notarius.references` is a map whose key is a Notarius v0.6 CLI
reference selector and whose value is a prepared Narratio source ID. It is
not a map of paths.
2. Every configured binding is required. There is no per-entry `required`
field. An optional Notarius reference is omitted by omitting the map entry.
An empty or omitted map remains valid for custom pipelines and backward
compatibility.
The map is limited by the centrally declared configuration constant
`MaxNotariusReferenceBindings = 256`, which is far above the four-entry
maintained D&D case while bounding argv and manifest growth.
3. The supported prepared reference sources are
`narratio.input.party`, `narratio.input.players`,
`narratio.input.glossary`, and `narratio.input.spell_catalog`.
Arbitrary Notarius slot names and qualified selectors may bind those sources;
direct paths and later-stage artifacts may not.
4. Campaign and session `spell_catalog_file` are optional. A session value
overrides the campaign value; an empty session value inherits the campaign
value. A `narratio.input.spell_catalog` reference binding requires an
effective configured file.
5. Prepared sources are authoritative only when the current session manifest
records the matching canonical input and checksum. Consumers do not fall
back to campaign/session source paths or accept an incidental workspace file.
6. Narratio passes absolute prepared-file paths to Notarius. Fingerprints and
metadata use the canonical workspace-relative path identity together with
selector, source ID, SHA-256 checksum, and size so workspace relocation does
not become the only identity signal.
7. External CLI references are sorted by normalized selector. They override
matching external references in the Notarius configuration. Narratio never
emits `--without-reference`, the deprecated `roster` alias, or CLI bindings
for generated D&D artifact handoffs.
8. Notarius remains authoritative for whether a selected target declares a
slot, accepted reference media types and sizes, generated-handoff collisions,
pipeline topology, and D&D payload schemas. Narratio validates selector
structure and its own source contract only.
9. Notarius v0.6.0 is the minimum supported CLI contract when references are
configured. Do not add version-string parsing or an automatic per-session
`notarius config validate` subprocess.
10. The existing receipt-v2, bundle-confinement, diagnostic, ten-lane selection,
immutable promotion, and analysis-source behavior must remain intact.
11. The default test suite remains offline, deterministic, and independent of
a sibling checkout or installed Notarius binary. A real v0.6.0 smoke run is
useful supplementary evidence when locally available, not a default-suite
dependency.
12. Add no external Go dependency for this feature. Use narrow owner-specific
types and existing file, path, artifact, manifest, adapter, and stage
facilities.
## Instructions For Every Stage
For each implementation prompt, the coding agent must:
1. Read `docs/development.md`, all three files under `docs/policy/`, the feature
roadmap, this plan, and the stage-specific documents and source named below.
Inspect the current tree because earlier stages may have changed names or
ownership boundaries.
2. Use the repository knowledge graph first for code discovery and call tracing;
use text search for documentation, configuration, examples, string literals,
and evidence the graph cannot supply.
3. Confirm the worktree state and preserve unrelated changes. Implement only the
current stage. Do not begin a later stage merely because an adjacent file is
open.
4. Keep production code, focused tests, fakes, and fixtures consistent within
the stage. Remove superseded helpers when their final caller migrates. Do not
retain two competing source maps, path resolvers, fingerprint paths, or
subprocess argument builders.
5. Follow the testing policy's ownership rule. Parser/config tests own selector
and configuration cases; artifact tests own prepared-file identity and
integrity; adapter tests own exact arguments; stage tests own orchestration and
resume; application tests own lifecycle invalidation. Do not repeat every
lower-level case at higher levels.
6. Keep errors actionable and content-free. They may identify a selector,
Narratio source ID, canonical path, or checksum mismatch, but must not include
reference contents. Preserve ordinary group-workspace permissions and
restrictive API-key handling.
7. Run `gofmt` on changed Go files and focused tests while iterating. Before
marking any stage complete, run at minimum:
```sh
go test ./...
go test -race ./...
go vet ./...
go build ./...
go test ./internal/doccheck
go test ./internal/config -run '^TestExamplesLoadAndValidate$'
```
Default tests must not contact live services or require credentials.
8. Compare the final diff against the stage goal and exit criteria. Update only
the current stage's status row from `Pending` to `Completed`. Do not mark a
stage complete while a required check fails or required behavior is absent.
Intermediate commits are implementation-branch state and must not be released
before Stage 7 has reconciled current-behavior documentation.
## Stage 1 — Reference And Configuration Vocabulary
**Read first:** `docs/config.md`, `docs/integrations/notarius.md`,
`internal/config/config.go`, `internal/config/defaults.go`,
`internal/config/load.go`, `internal/config/validate.go`,
`internal/config/notarius_test.go`, `internal/config/campaign_config_test.go`,
and `internal/artifactpolicy/policy.go` and its tests. Read the tagged Notarius
v0.6.0 `docs/cli.md` reference-selector section from `../notarius` when that
checkout is available; otherwise use the canonical link from the feature
roadmap.
**Depends on:** None.
**Goal:** Establish one normalized reference-selector grammar and the strict
configuration model needed by later stages, without adding path-valued Notarius
configuration or making spell catalogs mandatory for every campaign.
**Work:**
- Add a small dependency-free `internal/notariusref` package as the contract
owner for Notarius reference selector normalization. Its exported normalizer
must trim the selector and each component, reject empty components and `=`,
and accept only the v0.6 forms `slot`,
`chunk.slot`, `lane.slot`, `lane.extract.slot`, `lane.merge.slot`, and
`lane.normalize.slot`. A three-component selector accepts only `extract`,
`merge`, or `normalize` in its middle component. Do not check the selector
against a Notarius module or lane registry.
- Add `References map[string]string` with YAML key `references` to
`config.NotariusConfig`. During enabled Notarius validation, sort raw keys,
normalize each selector through the shared contract, trim each source value,
reject empty values and normalized-selector collisions, require each value to
be one of the four prepared reference sources, and replace the config map with
its normalized form. Enforce the named, centrally discoverable
`config.MaxNotariusReferenceBindings` limit of 256 entries with an error that
identifies the field and limit. Keep a nil/empty map valid. Rely on strict YAML
decoding to reject duplicate identical keys, but explicitly reject distinct
raw keys that normalize to one selector.
- Add `SpellCatalogFile string` with YAML key `spell_catalog_file` to campaign
inputs and session inputs, plus `SpellCatalogFile ResolvedInputFile` to
resolved stable inputs. Merge it with the existing session-over-campaign
helper. It is not part of the campaign-required input set. Reject a non-empty
configured scalar that becomes empty after trimming.
- Add `artifactpolicy.SourceInputSpellCatalog` and make the artifact-policy
owner describe all four prepared reference sources, including their canonical
manifest kind and filename. Use that owner for stable-source recognition
instead of adding a second switch in configuration validation. Preserve the
existing three source IDs and their behavior.
- Extend cross-configuration validation so a normalized reference to
`narratio.input.spell_catalog` requires a non-empty effective resolved
`spell_catalog_file`. Existing campaign requirements already guarantee party,
players, and glossary declarations. Do not check filesystem existence during
configuration validation.
- If analyze's current private filename switch must change to keep the tree
behaviorally coherent, make it delegate to the artifact-policy descriptor and
recognize spell catalog; Stage 3 will replace the filesystem-only resolver.
**Tests and exit criteria:** At the contract/config owners, cover every accepted
selector shape; zero, empty, excess, invalid-stage, and `=` forms; whitespace
normalization; normalized collisions; unsupported and empty source IDs; nil and
empty maps; exactly the configured binding limit and limit plus one; strict
unknown fields; campaign inheritance and session override; optional omission;
and the cross-config missing-spell-catalog failure. Prefer table-driven parser
and validator tests over assertions against private helper structure. Existing
configuration and example tests must still pass without adding spell catalogs
to every campaign. The codebase has one selector grammar owner and one
prepared-source descriptor owner.
## Stage 2 — Spell Catalog Prepare And Operator Lifecycle
**Read first:** `docs/internal/stage-prepare.md`, `docs/internal/workspace.md`,
`docs/operations.md`, `internal/stage/prepare.go` and its tests,
`internal/app/operator_inspection.go`, `internal/app/operator_findings.go` and
their focused tests, `internal/manifest/manifest.go`, and the relevant confined
file-operation helpers.
**Depends on:** Stage 1.
**Goal:** Make the effective optional spell catalog a normal prepared session
input with canonical storage, checksum/provenance, safe stale-file handling, and
operator visibility.
**Work:**
- Resolve `StableInputs.SpellCatalogFile` with the same origin-preserving
campaign/session behavior as the five existing stable inputs. When configured,
require a regular readable source, copy it atomically to
`inputs/spell_catalog.json`, preserve ordinary workspace permissions, and add
one manifest input record with kind `spell_catalog`, canonical destination,
checksum, and `campaign_config` or `session_config` source provenance.
- Treat the input as optional when no effective path is configured. Do not call
the required-input path resolver with an empty value and do not create a
manifest record. Remove an obsolete canonical `inputs/spell_catalog.json`
without following it when a forced prepare transitions from configured to
absent; refuse to recursively remove a directory or other ambiguous object at
that exact file path.
- Include a configured spell catalog in operator inspection and validation
findings. Omission is not an error unless Stage 1 cross-configuration policy
says the enabled Notarius reference requires it. Reuse the common resolved
stable-input enumeration where practical instead of extending parallel
hand-written lists in several functions.
- Adjust input-slice capacity, deterministic ordering, test fixtures, and any
manifest assumptions affected by the optional sixth stable file. Do not parse
or schema-validate the JSON payload in Narratio; Notarius owns that contract.
**Tests and exit criteria:** Through prepare and operator package behavior, cover
campaign and session source provenance, canonical destination bytes and
checksum, optional omission, missing configured source, replacement after source
change, safe removal when configuration is removed, rejection of an ambiguous
destination object, deterministic manifest ordering, and operator reporting.
Do not duplicate selector-validation cases from Stage 1. Existing sessions with
no spell catalog remain valid and produce no stale manifest entry.
## Stage 3 — Manifest-Authoritative Prepared Input Resolution
**Read first:** `docs/internal/artifacts.md`, `docs/internal/manifest.md`,
`docs/internal/stage-analyze.md`, `internal/artifacts/artifact_resolver.go`,
`internal/artifacts/resolve.go`, `internal/artifacts/checksum.go`, their tests,
and the prepared stable-input resolution path in `internal/stage/analyze.go` and
`internal/stage/analyze_test.go`.
**Depends on:** Stage 2.
**Goal:** Give analyze and extract one integrity-checked resolver for prepared
stable sources so neither stage trusts incidental files or reconstructs its own
source-to-filename table.
**Work:**
- Add an artifacts-owned `PreparedInputIdentity` contract containing source ID,
manifest kind, absolute canonical path, slash-separated path relative to the
session root, SHA-256 checksum, and byte size. Add one resolver that accepts
session paths, the current session manifest, and a stable source ID. Provide a
typed or sentinel absence classification so callers can distinguish no current
manifest record from corrupt or unsafe recorded evidence.
- Derive kind and filename exclusively from the artifact-policy descriptor. The
resolver must require exactly one current manifest input record with the
expected kind and canonical path; resolve/rebase recorded local paths through
existing session-local path safety helpers; require the result to equal the
canonical file below `inputs/`; reject escapes, symlinks, non-regular files,
empty files, missing checksums, duplicate records, and checksum mismatches; and
calculate size without loading the complete file into memory. Do not fall back
to the configured campaign/session path or accept canonical file presence
without manifest evidence. Zero matching manifest records is the typed absent
case; once a record exists, a missing or invalid file is an integrity error,
not optional absence.
- Return owner-neutral errors from `internal/artifacts`. At stage boundaries,
wrap unavailable or stale prepared inputs with the source ID and actionable
`narratio run-stage prepare <session_id> --force` guidance. Do not include file
contents.
- Replace analyze's private prepared-source filename switch and filesystem-only
resolver with the shared artifact resolver. Preserve required-versus-optional
Scriptorium input behavior: a typed absent optional source is omitted, an
absent required source fails with prepare guidance, and invalid recorded
evidence fails regardless of optionality. Make `narratio.input.spell_catalog`
usable wherever another prepared Scriptorium source is accepted.
**Tests and exit criteria:** Artifact-package tests own valid resolution and the
missing-record, duplicate-record, wrong-kind/path, traversal/rebase, symlink,
non-regular, empty, missing-checksum, and checksum-mismatch boundaries. Analyze
tests need only prove required/optional stage behavior and successful use of the
shared source, including spell catalog; do not repeat the artifact resolver's
full matrix. Remove the old filename/path resolver after its final caller moves.
## Stage 4 — Notarius Adapter Reference Arguments
**Read first:** `docs/internal/adapters.md`, `docs/integrations/notarius.md`,
`internal/adapters/notarius/runner.go`, `fake.go`, `subprocess.go`, and focused
adapter tests. Re-read the Notarius v0.6.0 subprocess and CLI reference-selector
contracts from the tagged sibling checkout when available.
**Depends on:** Stage 1.
**Goal:** Extend the transport-neutral Notarius request and production adapter
to emit safe, exact, repeatable v0.6 `--reference` arguments without changing
receipt or bundle ingestion.
**Work:**
- Add a transport-neutral reference binding containing normalized selector and
absolute path, and add an ordered slice of those bindings to `RunRequest`.
Keep source IDs and manifest identities out of the adapter contract; those are
stage policy.
- Validate each adapter binding before process launch: normalize/validate the
selector through the shared Stage 1 contract, require a non-empty absolute
path, reject duplicate normalized selectors, and avoid mutating the caller's
slice. Do not open or parse the reference file in the adapter.
- Build arguments as repeated pairs `--reference`,
`<normalized-selector>=<absolute-path>` after `--output-dir` and before
`--json`. Preserve one argument for the combined selector/path value so spaces,
additional `=` characters within the path portion, and platform separators do
not involve shell interpretation. The request order is authoritative; Stage 5
will supply sorted bindings.
- Preserve current executable, environment, timeout, cancellation, diagnostic,
receipt-v2, bounded-read, confinement, and bundle-discovery behavior. Do not
add `--without-reference`, generated reference arguments, version probing, or
configuration preflight.
- Update the fake only as required to retain and expose the extended request.
**Tests and exit criteria:** Adapter tests own exact argv with zero and multiple
references, position before `--json`, spaces and `=` in paths, selector
normalization, duplicate/invalid selector rejection, relative/empty path
rejection, and no subprocess start after request-validation failure. Existing
receipt-v2 and bundle fixture tests must remain unchanged in meaning and pass.
Do not assert stage-level source sorting here beyond preserving the request
order.
## Stage 5 — Extract Reference Identity, Invocation, And Resume
**Read first:** `docs/internal/stage-extract.md`,
`docs/integrations/notarius.md`, `docs/internal/manifest.md`,
`internal/stage/extract.go`, `internal/stage/extract_resume.go`, their focused
tests, the Stage 3 prepared-input identity contract, and the Stage 4 Notarius
request contract.
**Depends on:** Stages 3 and 4.
**Goal:** Make configured references part of the actual extraction invocation
and durable reuse contract, using one resolution path for initial execution and
resume validation.
**Work:**
- Add one extract-owned reference-resolution helper used by both `Run` and
`ValidateResume`. Iterate normalized config bindings in lexical selector
order, resolve each source through the Stage 3 manifest-authoritative resolver,
and produce both adapter bindings and immutable reference identities. Resolve
every reference before creating run-local receipt, log, output, or promotion
directories and before invoking the adapter.
- Define the fingerprint/metadata identity as normalized selector, source ID,
canonical session-relative slash path, SHA-256 checksum, and byte size. Do not
include contents or original campaign/session absolute paths. Pass only
selector and absolute prepared path to the adapter.
- Extend the extraction fingerprint document with the sorted reference
identities. Keep all existing binary, config path, pipeline, timeout, working
directory, trimmed-transcript identity, and required-output identities. The
result must be independent of YAML map iteration order and must change for a
selector, source, relative path, checksum, or size change.
- Persist `reference_count` and a bounded deterministic `references` metadata
list on successful extraction. Each entry contains exactly `selector`,
`source_id`, `path`, `checksum`, and `size_bytes`. Empty bindings produce count
zero and an empty list. Do not duplicate Notarius reference payloads or
downstream error messages.
- Make resume recompute current reference identities through the same helper
before comparing the configuration fingerprint. A valid changed prepared
input yields a fingerprint mismatch and a non-resumable result so extraction
reruns. Missing, unsafe, or checksum-inconsistent current input is an error
with prepare-force guidance because immediately rerunning extract cannot
succeed. Do not silently reuse the old bundle.
- Preserve explicit disabled-stage skip without resolving references. Preserve
required lane selection, immutable promotion, receipt identity, and bundle
evidence behavior.
**Tests and exit criteria:** Stage tests own sorted request construction for all
four D&D bindings, zero bindings, failure before adapter invocation for an
unavailable source, content-free metadata, and fingerprint changes for each
identity field while remaining stable across map order. Resume tests must prove
reuse with unchanged references, non-reuse after a valid prepared-reference
change, hard failure for missing or checksum-invalid current evidence, and no
reference resolution when disabled. Use the fake adapter; do not duplicate exact
subprocess argv cases from Stage 4.
## Stage 6 — Assembled Lifecycle And Invalidation Coverage
**Read first:** `docs/internal/overview.md`, `docs/internal/manifest.md`,
`docs/internal/stage-extract.md`, `docs/internal/stage-prepare.md`,
`internal/app/runner.go`,
`internal/app/extract_lifecycle_test.go`, and representative full pipeline and
stage fixtures. Inspect existing downstream invalidation tests before adding
new cases.
**Depends on:** Stage 5.
**Goal:** Prove at the application boundary that prepared campaign context
reaches Notarius and that reference changes cannot leave extraction or later
analysis falsely current.
**Work:**
- Extend the smallest existing assembled runner fixture to execute prepare and
extract with party, players, glossary, and spell catalog bindings. Assert that
the fake Notarius request receives the four canonical prepared absolute paths,
not the original campaign/session source paths, and that the successful
manifest records bounded reference identity.
- Add one lifecycle regression covering a valid reference-content change:
rerun/force prepare so the manifest and prepared checksum change, then verify
extract resume is rejected, Notarius runs again, and succeeded canonical
downstream stages are invalidated according to the existing stage-order
policy. Assert outcomes, not private runner call choreography.
- Add one representative session override case to prove the overridden prepared
bytes/checksum reach extraction. Do not repeat all four configuration merge
cases or artifact-integrity failures already owned by earlier stages.
- Confirm an empty reference map preserves the pre-v0.6 invocation behavior and
that all ten configured D&D lanes remain registered as the same
`narratio.extraction.<key>` sources available to analyze.
- Fix production integration defects exposed by these assembled tests without
broadening the feature or adding a DAG, generic reference workflow, or direct
Notarius payload parsing.
**Tests and exit criteria:** The application-level tests must be deterministic,
offline, and fake only the external Notarius boundary. They must credibly fail
if Narratio passes original paths, omits one configured reference, reuses stale
extraction, or loses a configured lane, while remaining insensitive to private
helper structure and exact non-contractual diagnostics. Earlier focused suites
and the repository baseline remain green.
## Stage 7 — Canonical Documentation And Maintained Examples
**Read first:** `docs/policy/documentation.md`, `docs/config.md`,
`docs/operations.md`, `docs/troubleshooting.md`,
`docs/integrations/notarius.md`, `docs/internal/overview.md`,
`docs/internal/adapters.md`, `docs/internal/artifacts.md`,
`docs/internal/stage-prepare.md`, `docs/internal/stage-extract.md`,
`docs/internal/stage-analyze.md`, `examples/README.md`, and all maintained
pipeline, campaign, and session examples affected by the new fields.
**Depends on:** Stage 6.
**Goal:** Move the completed behavior from roadmap-only future state into its
canonical current-behavior owners and provide valid copyable D&D examples
without duplicating volatile Notarius contracts.
**Work:**
- Update `docs/config.md` with `pipeline.notarius.references`, its selector-to-
source shape, normalization/validation rules, required-by-presence behavior,
supported stable source IDs, and campaign/session `spell_catalog_file`
precedence and optionality. Keep complete copyable YAML in `examples/`.
- Update `docs/integrations/notarius.md` to the v0.6.0 baseline and exact
repeatable-reference invocation boundary. Explain absolute CLI paths,
precedence over configured external paths, the four maintained external D&D
slots, the generated-handoff exclusion, and unchanged receipt-v2/ten-lane
output compatibility. Link to Notarius's canonical v0.6 CLI and D&D consumer
docs instead of copying its target/module matrix.
- Update operations and troubleshooting with prepared input location,
fingerprint/rerun consequences, operator inspection, missing-reference
diagnosis, and Notarius undeclared-slot/generated-collision failures. Update
internal component documents only with implemented ownership and flow; do not
duplicate configuration field definitions there.
- Add a valid, secret-free sample spell catalog following Notarius v0.6's
published overlay schema, add `spell_catalog_file` to the sample campaign, and
configure all four external reference bindings in the complete annotated D&D
pipeline. Add the same bindings to other Notarius-enabled maintained examples
only when their selected pipeline declares them; do not add a Notarius section
to examples that intentionally omit extraction.
- Ensure the maintained command snippets place repeated `--reference` arguments
before `--json`, use `party` rather than `roster`, and never show generated
handoffs on the CLI. Remove stale v0.5 compatibility wording where it refers to
the supported invocation baseline.
**Tests and exit criteria:** Run documentation-link checks and the example
loader explicitly. Verify every changed example is accepted by strict config
validation, contains no credentials or private infrastructure values, and has
one canonical owner for each volatile fact. Search current-behavior docs and
examples for stale v0.5 invocation wording, deprecated `roster` emission, and
generated D&D CLI handoff examples. Do not mark the roadmap itself implemented;
its status remains target-state context until the implementation sprint is
reviewed and closed.
## Stage 8 — Compatibility And Quality Closure
**Read first:** The feature roadmap, every completed stage diff, the final
current-behavior docs, `.woodpecker/verify.yml`, `.woodpecker/release.yml`, and
`.woodpecker/shuffle.yml`. Re-read the tagged Notarius v0.6.0
`docs/consumers/dnd-pipeline.md`, `docs/cli.md`, and linked spell-catalog overlay
contract when the sibling checkout is available.
**Depends on:** Stage 7.
**Goal:** Verify the delivered code matches the accepted boundary, remains
compatible with all ten default D&D artifacts, and is ready for review without
dead compatibility paths or duplicated policy.
**Work:**
- Audit the final diff against every target-state and out-of-scope statement in
the feature roadmap. Confirm only four external prepared sources are exposed,
custom selectors remain possible, every configured binding is required, and
no Notarius pipeline topology or generated-handoff logic moved into Narratio.
- Trace initial extract and resume paths to confirm both use the same prepared
identity and reference resolution, the adapter is the sole argv builder, and
artifact policy is the sole source-to-kind/filename vocabulary. Remove dead
helpers, redundant switches, stale fixtures, and low-value duplicate tests
found during this review.
- Confirm the complete D&D example still declares and validates the exact ten
output lanes and that analyze can consume those sources after reference-
enabled extraction. Confirm empty-reference custom pipelines remain supported.
- If a local Notarius v0.6.0 binary and its required offline/test configuration
are already available, perform a non-credentialed smoke invocation with all
four reference flags and record the result in the implementation handoff. Do
not download tools, contact paid providers, add a default test dependency, or
block completion solely because this supplementary environment is absent.
- Run the repository baseline plus the scheduled shuffled suite and release
cross-build commands:
```sh
go test ./...
go test -race ./...
go test -race -shuffle=on -count=3 ./...
go vet ./...
go build ./...
go test ./internal/doccheck
go test ./internal/config -run '^TestExamplesLoadAndValidate$'
narratio_cross_dir="$(mktemp -d)"
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-linux-amd64" ./cmd/narratio
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-darwin-amd64" ./cmd/narratio
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-windows-amd64.exe" ./cmd/narratio
```
Cross-builds are compilation evidence only; do not claim native macOS or
Windows runtime validation.
**Tests and exit criteria:** Every required command passes, `git diff --check`
is clean, the worktree contains no unintended generated test artifacts, and the
implementation is traceably complete against the roadmap. Summarize any
unavailable supplementary smoke evidence without treating it as a product
question or silently weakening the default suite.
## Open Questions
None. The feature roadmap and governing decisions above are sufficient to
implement the plan without additional product or architecture choices.

274
docs/roadmap/notarius-v0.6-cli-references.md Normal file
View 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.