From 3a9e60cda9acb2c1b95ba73310410004fdba01c7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 29 Aug 2026 15:40:23 +0000 Subject: [PATCH] Document prepared Notarius references --- docs/config.md | 45 ++++++++++++- docs/integrations/notarius.md | 52 +++++++++++--- docs/internal/adapters.md | 4 +- docs/internal/artifacts.md | 17 ++++- docs/internal/stage-analyze.md | 6 +- docs/internal/stage-extract.md | 27 +++++--- docs/internal/stage-prepare.md | 5 ++ docs/operations.md | 40 +++++++++-- docs/roadmap/implementation.md | 2 +- docs/troubleshooting.md | 67 ++++++++++++++++++- examples/README.md | 4 +- .../campaigns/sample-campaign/campaign.yml | 1 + .../sample-campaign/spell_catalog.json | 18 +++++ examples/pipeline.extraction-subset.yml | 6 +- examples/pipeline.full.annotated.yml | 7 ++ 15 files changed, 268 insertions(+), 33 deletions(-) create mode 100644 examples/campaigns/sample-campaign/spell_catalog.json diff --git a/docs/config.md b/docs/config.md index 0764086..59f0ddb 100644 --- a/docs/config.md +++ b/docs/config.md @@ -60,7 +60,10 @@ remote state with an unsafe legacy identity must be migrated before use. - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load. - Pipeline defaults are applied before validation. - Campaign and session identities must agree. -- Stable files (`speakers_file`, `autocorrect_file`, `glossary_file`, `players_file`, `party_file`) resolve from session overrides when provided, otherwise from campaign defaults. +- Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`, + `players_file`, `party_file`) and the optional `spell_catalog_file` resolve + from session overrides when provided, otherwise from campaign defaults. An + empty or omitted session spell-catalog value inherits the campaign value. - Exactly one audio mode must be configured in session input: - local (`audio_dir` or `audio_files`), or - S3 (`audio_s3.prefix`). @@ -227,6 +230,7 @@ Rules: | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled | | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive | | `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from the pipeline file directory | +| `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries | | `pipeline.notarius.outputs` | map | Conditional | at least one entry when enabled | | `pipeline.render.enabled` | bool | No | `true` | | `pipeline.render.format` | string | No | `markdown` (only supported value) | @@ -241,6 +245,43 @@ Rules: | `pipeline.scriptorium.artifacts` | map | No | empty | | `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented | +### Notarius Reference Bindings + +`pipeline.notarius.references` maps a Notarius CLI selector to a prepared +Narratio source, not to a filesystem path: + +```yaml +notarius: + references: + glossary: narratio.input.glossary + party: narratio.input.party + players: narratio.input.players + spell_catalog: narratio.input.spell_catalog +``` + +Supported sources are `narratio.input.party`, `narratio.input.players`, +`narratio.input.glossary`, and `narratio.input.spell_catalog`. Each map entry is +required by its presence: omit a binding when the selected Notarius pipeline +does not need it. A spell-catalog binding additionally requires an effective +campaign or session `spell_catalog_file`. + +Selectors accept Notarius's `slot`, `chunk.slot`, `lane.slot`, +`lane.extract.slot`, `lane.merge.slot`, and `lane.normalize.slot` forms. +Narratio trims whitespace around +selectors and their dot-separated components, rejects empty components and +`=`, rejects duplicate normalized selectors, and limits the map to 256 entries. +It validates only selector structure and the prepared source vocabulary; +Notarius owns target-slot declarations and media compatibility. + +Before extraction, Narratio resolves every binding from the current prepared +session manifest and passes its canonical absolute `inputs/` path to Notarius. +Missing, unsafe, empty, or checksum-inconsistent prepared evidence fails with +guidance to force `prepare`. Bindings are sorted by normalized selector and are +part of extraction fingerprint and resume identity. See the +[Notarius integration contract](./integrations/notarius.md) for the subprocess +boundary and the [complete example](../examples/pipeline.full.annotated.yml) +for a copyable configuration. + ### Notarius Output Entries For each `pipeline.notarius.outputs.`: @@ -318,6 +359,7 @@ integration. | `inputs.glossary_file` | string | Yes | stable input default | | `inputs.players_file` | string | Yes | stable input default | | `inputs.party_file` | string | Yes | stable input default | +| `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` | ### Session @@ -333,6 +375,7 @@ integration. | `inputs.glossary_file` | string | No | overrides campaign stable input | | `inputs.players_file` | string | No | overrides campaign stable input | | `inputs.party_file` | string | No | overrides campaign stable input | +| `inputs.spell_catalog_file` | string | No | overrides the optional campaign spell catalog; empty or omitted inherits the campaign value | | `inputs.audio_dir` | string | Conditional | local audio mode | | `inputs.audio_files[]` | list[string] | Conditional | local audio mode | | `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode | diff --git a/docs/integrations/notarius.md b/docs/integrations/notarius.md index c03e544..d136ee7 100644 --- a/docs/integrations/notarius.md +++ b/docs/integrations/notarius.md @@ -7,12 +7,14 @@ lanes from the final trimmed Seriatim transcript. Narratio owns invocation, safe bundle discovery, lane selection, and its own artifact metadata. Notarius owns pipeline definitions, lane schemas, the receipt, and bundle formats. -Canonical Notarius references: +Canonical Notarius v0.6.0 references: -- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/subprocess.md) -- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/dnd-pipeline.md) -- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/run-result.md) -- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/json-output.md) +- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/cli.md) +- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/subprocess.md) +- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/dnd-pipeline.md) +- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/run-result.md) +- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/json-output.md) +- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/dnd-spell-catalog-overlays.md) The [complete Narratio example](../../examples/pipeline.full.annotated.yml) records the exact current constraints for all ten D&D lanes. Treat the linked @@ -23,12 +25,41 @@ duplicate the complete schemas. When `pipeline.notarius.enabled` is true, Narratio resolves the executable, configuration path, input path, output directory, and working directory to -absolute paths and invokes: +absolute paths. Narratio requires the Notarius v0.6.0 CLI contract when +references are configured and invokes each binding as a separate argument +before `--json`: ```text -notarius run --config --input --output-dir --json +notarius run --config --input --output-dir [--reference =]... --json ``` +Reference paths are absolute canonical files prepared inside the current +Narratio session workspace. Narratio passes only configured bindings, ordered +lexically by normalized selector, as direct argument-vector entries without +shell interpretation. A CLI binding takes precedence over a matching external +path in Notarius configuration. Narratio never emits `--without-reference`. + +The maintained D&D boundary binds only the four campaign-owned external slots: + +```text +notarius run dnd-session \ + --config \ + --input \ + --output-dir \ + --reference glossary= \ + --reference party= \ + --reference players= \ + --reference spell_catalog= \ + --json +``` + +The spell-catalog binding is omitted when the campaign does not maintain that +optional overlay. Registry, scene-description, combat-turn, and occurrence +handoffs generated during the same Notarius run remain in Notarius pipeline +composition and must not be emitted as CLI references. The linked CLI and D&D +consumer documents own selector targeting, declared slots, media compatibility, +and generated-handoff collision rules. + Standard output is reserved for the JSON receipt. Standard error is captured separately as diagnostic output. Narratio applies the configured timeout and does not interpret stdout as a receipt unless the subprocess exits successfully. @@ -38,8 +69,9 @@ environment apply to the subprocess. ## Accepted Result -Narratio accepts the Notarius v0.5.0 receipt schema -`notarius.run-result.v2`. The receipt +Narratio's supported invocation baseline is Notarius v0.6.0. The accepted +receipt remains `notarius.run-result.v2`; reference flags do not change the +receipt or ten-lane output contract. The receipt must identify the configured pipeline, and its `index_file` must be exactly `index.json` beneath the reported bundle root. The production index must name the management files exactly as `manifest.json`, `rejected.json`, @@ -78,6 +110,8 @@ only explicitly named lane sources; `--artifacts` never selects Notarius lanes. staged bundle is promoted to durable storage. - Contract and external provenance metadata are preserved on lane artifact records and through explicit publication. +- Undeclared selectors, incompatible reference files, and external/generated + reference collisions are Notarius errors and fail extraction normally. Rejection, validation, warning, and diagnostic summaries retain bounded stable identity, category, origin, reason-code, status, and occurrence fields without diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index a5bc0d2..c1f91db 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -46,7 +46,9 @@ Adapters do not own: - Object store only when required by selected stages/config. Notarius is composed only when extraction is enabled; the extract stage owns -receipt, bundle, and configured-lane policy rather than the adapter. +prepared reference resolution, receipt, bundle, and configured-lane policy. +The adapter validates the ordered selector/absolute-path pairs and is the sole +owner of serializing them as repeated `--reference` arguments before `--json`. Object-store construction goes through `newCommandObjectStore`, which loads configured filesystem secrets before adapter initialization. diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index 29aa8e4..f803b8c 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -36,6 +36,11 @@ unrecognized token into a valid source. Extraction sources are registered only from `pipeline.notarius.outputs`; the Notarius index has no selectable source ID. +Prepared stable source IDs are `narratio.input.players`, +`narratio.input.party`, `narratio.input.glossary`, and +`narratio.input.spell_catalog`. Artifact policy owns their canonical manifest +kind and prepared filename vocabulary. + ## Runtime Catalog `ArtifactCatalog` tracks: @@ -72,6 +77,15 @@ Configured sources (`narratio.artifact.*`): - resolve only through runtime catalog availability. +Prepared stable sources (`narratio.input.*`): + +- resolve only from the current manifest's exact prepared-input record; +- require the policy-owned canonical path below the session root, a confined + non-symlink regular file, a non-empty payload, and a matching SHA-256 + checksum; and +- return an immutable source/path/checksum/size identity shared by extract and + analyze rather than falling back to campaign/session source paths. + Extraction sources (`narratio.extraction.*`): - use the shared typed bundle evidence inspection in `extraction_evidence.go`; @@ -199,7 +213,8 @@ physical layout. `internal/artifacts/catalog.go`, `internal/artifacts/transcripts.go`, `internal/artifacts/extraction_catalog.go`, `internal/artifacts/extraction_evidence.go`, - `internal/artifacts/extraction_input.go` + `internal/artifacts/extraction_input.go`, + `internal/artifacts/prepared_input.go` - Current state: `internal/artifacts/current_state.go`, `internal/artifacts/current_state_commit.go`, `internal/artifacts/current_state_legacy.go` diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index 4f74b30..bb287db 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -14,7 +14,7 @@ Execute selected configured Scriptorium artifacts in dependency order and materi Supported source families: - built-ins: `narratio.transcript.*`, `narratio.bounds.session` - prepared stable inputs: `narratio.input.players`, `narratio.input.party`, - `narratio.input.glossary` + `narratio.input.glossary`, `narratio.input.spell_catalog` - configured artifacts: `narratio.artifact.` - extraction lanes: `narratio.extraction.` - previous-session cache: `narratio.previous_session.artifact.` @@ -42,7 +42,9 @@ Supported source families: - validates selected artifact dependency order (cycle-safe topo ordering). - resolves required/optional inputs per artifact source definition. - omits an unavailable optional input; an unavailable required input fails. -- resolves prepared stable input sources from `inputs/*.yml` materialized by `prepare`. +- resolves prepared stable input sources through the shared manifest-authoritative + identity resolver; it does not accept incidental files or fall back to + campaign/session source paths. - resolves previous-session sources from local `previous/` cache only. - runs optional render-debug, then artifact execution. - validates non-empty output files and materializes canonical outputs. diff --git a/docs/internal/stage-extract.md b/docs/internal/stage-extract.md index 4d78554..f7b8419 100644 --- a/docs/internal/stage-extract.md +++ b/docs/internal/stage-extract.md @@ -17,16 +17,19 @@ procedures belong in [Operations](../operations.md). `internal/stage/extract.go`: 1. resolves the final trimmed transcript from the shared artifact catalog; -2. resolves and fingerprints the Notarius invocation contract; -3. creates a run-local staging directory and invokes the injected +2. resolves every configured prepared reference through the shared + manifest-authoritative identity resolver before creating run-local output; +3. fingerprints the Notarius invocation contract, including sorted reference + identities; +4. creates a run-local staging directory and invokes the injected `notarius.Runner`; -4. validates the v2 successful receipt, confined index, management documents, +5. validates the v2 successful receipt, confined index, management documents, configured required lane descriptors, validation summaries, and regular payload files; -5. atomically promotes the complete bundle to its immutable durable location; -6. records one non-selectable `notarius_index` output and one selectable +6. atomically promotes the complete bundle to its immutable durable location; +7. records one non-selectable `notarius_index` output and one selectable `notarius_lane` output per configured lane; and -7. registers each lane as `narratio.extraction.` for downstream +8. registers each lane as `narratio.extraction.` for downstream Scriptorium and publish resolution. Lane records retain checksum, contract, producer run ID, and Notarius system, @@ -35,6 +38,9 @@ root, receipt, diagnostic paths, rejection/warning summaries, producing Narratio run ID, the resolved trimmed-input identity, and invocation fingerprint. The input identity binds the exact transcript bytes, canonical source ID, producer stage/output/run identity, and resolution provenance. +Reference metadata contains only selector, source ID, canonical session-relative +path, checksum, and size; adapter requests receive selector and absolute +prepared path, never payload contents. Validation completes before promotion, so a rejected result cannot expose a partial durable bundle. @@ -47,11 +53,16 @@ with no outputs is stable and does not repeatedly invalidate downstream stages. `internal/stage/extract_resume.go` permits a skip only when the existing stage record succeeded and still matches the current invocation fingerprint. The fingerprint covers the resolved executable and config paths, pipeline ID, -timeout, working directory, sorted configured output contracts, and the current -direct trimmed-transcript identity. The same identity is resolved again for +timeout, working directory, sorted configured output contracts, the current +direct trimmed-transcript identity, and sorted prepared-reference identities. +The same reference helper and transcript identity are resolved again for artifact evidence, so changing the current transcript bytes or producer identity makes the prior extraction obsolete. +A valid prepared-reference change makes extraction non-resumable. Missing, +unsafe, or checksum-inconsistent prepared evidence is a hard validation error +with prepare-force guidance because an immediate extract rerun cannot succeed. + The validator then checks the producing run identity, canonical immutable bundle root, path confinement and absence of symlink components, receipt identity, exactly one canonical index, the exact configured source set, diff --git a/docs/internal/stage-prepare.md b/docs/internal/stage-prepare.md index faea272..fb37408 100644 --- a/docs/internal/stage-prepare.md +++ b/docs/internal/stage-prepare.md @@ -8,6 +8,7 @@ Materialize canonical current-session inputs before processing stages. - resolved campaign, session, and pipeline configuration - stable input files (`speakers`, `autocorrect`, `glossary`, `players`, `party`) +- optional spell-catalog overlay - one resolved local or S3 audio source - enabled configured artifact input requirements for previous-session sources @@ -21,6 +22,7 @@ Materialize canonical current-session inputs before processing stages. - `inputs/glossary.yml` - `inputs/players.yml` - `inputs/party.yml` +- optional `inputs/spell_catalog.json` - `audio/*.flac` - optional `previous/manifest.json` - optional `previous/artifacts/**` @@ -34,6 +36,9 @@ Materialize canonical current-session inputs before processing stages. - gives distinct local source paths with the same basename deterministic unique prepared filenames so neither source is overwritten. - materializes S3 audio through spool/cache-aware logic. +- materializes a configured spell catalog with checksum and provenance, or + safely removes an obsolete canonical spell catalog and its manifest record + when the effective input is omitted. - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements. - clears managed `previous/` state on every invocation, then, when requirements exist: - resolves the pointer-selected previous source through the shared resolver; diff --git a/docs/operations.md b/docs/operations.md index f05d05c..70272ea 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -36,7 +36,12 @@ narratio session init 2026-04-04 --remote --force If `campaign.yml` sets `session_template_file`, `session init` renders it. Template variables must resolve to concrete values. -Campaigns must provide stable input files for speakers, autocorrect, glossary, players, and party. Session files may override those paths for one session. The `prepare` stage materializes them under `inputs/`; configured Scriptorium artifacts can reference prepared `players`, `party`, and `glossary` files with `narratio.input.players`, `narratio.input.party`, and `narratio.input.glossary`. +Campaigns must provide stable input files for speakers, autocorrect, glossary, +players, and party, and may provide an optional spell-catalog overlay. Session +files may override those paths for one session. The `prepare` stage +materializes them under `inputs/`; configured consumers use the prepared files, +never the original campaign or session source paths. Field definitions and +source IDs are in [Configuration](./config.md#notarius-reference-bindings). ## Standard Session Workflow @@ -135,6 +140,28 @@ The directory is immutable once promoted. Configured lanes become the bundle and `index.json` are retained for audit and resume validation but are not selectable or published implicitly. +Configured Notarius references resolve only from the current manifest-backed +prepared inputs. Their canonical locations are `inputs/party.yml`, +`inputs/players.yml`, `inputs/glossary.yml`, and, when configured, +`inputs/spell_catalog.json`. Inspect the effective stable-input inventory and +prepared-file readiness with: + +```bash +narratio session status 2026-04-04 +narratio session validate 2026-04-04 +``` + +Reference metadata records selector, source ID, session-relative path, +checksum, and byte size, but never payload contents. Changing a prepared +reference changes extraction identity: ordinary continuation rejects the old +result, reruns Notarius, and marks successful downstream stages stale. If the +prepared file is missing or inconsistent with its manifest checksum, repair +the source configuration and refresh prepared state first: + +```bash +narratio run-stage prepare 2026-04-04 --force +``` + Starting a replacement clears the previous extraction payload from the current session-stage record. If that replacement fails or self-skips, the current record does not fall back to the earlier outputs. The earlier run manifest and @@ -181,11 +208,12 @@ To intentionally replace the current extraction result, run: narratio run-stage extract 2026-04-04 --force ``` -Narratio automatically reruns extraction when its recorded invocation contract -or durable output validation changes. It cannot fingerprint configuration -files, profiles, prompts, modules, or references loaded transitively by -Notarius. Force extraction after changing any of those inputs, even when the -top-level Narratio and Notarius config paths remain the same. A forced extract +Narratio automatically reruns extraction when its recorded invocation contract, +prepared Narratio reference identities, or durable output validation changes. +It cannot fingerprint configuration files, profiles, prompts, modules, or +other references loaded transitively by Notarius itself. Force extraction after +changing any of those inputs, even when the top-level Narratio and Notarius +config paths remain the same. A forced extract marks successful downstream stages stale. Ordinary extraction failures or outcome changes also stale affected downstream stages, while an identical repeated `notarius_disabled` self-skip does not repeatedly invalidate them. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1d478c6..ad54e7d 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -22,7 +22,7 @@ different contract. | 4 | Add deterministic Notarius v0.6 reference arguments at the subprocess adapter boundary. | Completed | | 5 | Resolve references in extract and bind fingerprints, resume, and metadata to their identities. | Completed | | 6 | Prove assembled extraction lifecycle and downstream invalidation behavior. | Completed | -| 7 | Update canonical documentation and maintained examples for the completed feature. | Pending | +| 7 | Update canonical documentation and maintained examples for the completed feature. | Completed | | 8 | Perform compatibility, quality, and repository-wide closure validation. | Pending | ## Governing Decisions diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1d393eb..2b544ee 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -158,6 +158,66 @@ is expected audit state, not a signal to relink the old bundle manually. Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow). +## Prepared Notarius reference missing or inconsistent + +Symptom: + +- extraction or resume validation reports that a configured reference source is + unavailable, unsafe, empty, or checksum-inconsistent and recommends + `prepare --force`. + +Likely causes: + +- `prepare` has not run since the campaign/session stable input changed; +- the configured source file is missing; +- a prepared `inputs/` file or its manifest record was modified independently; +- a spell-catalog binding exists without an effective `spell_catalog_file`. + +Diagnostics: + +```bash +narratio session status 2026-04-04 +narratio session validate 2026-04-04 +``` + +Safe fix: + +- correct the campaign/session input path, then refresh canonical prepared + evidence before extraction: + +```bash +narratio run-stage prepare 2026-04-04 --force +``` + +Do not point Notarius directly at the original source path or edit the manifest +checksum. Relevant references: [Notarius reference configuration](./config.md#notarius-reference-bindings) +and [Operations: Extraction Workflow](./operations.md#extraction-workflow). + +## Notarius reference selector or generated-handoff collision + +Symptom: + +- Notarius exits nonzero with an undeclared reference-slot, incompatible media, + or external/generated reference collision error. + +Likely causes: + +- a selector does not identify a slot declared by the selected Notarius target; +- a prepared file does not satisfy that slot's Notarius media contract; or +- a CLI binding attempts to replace a same-run generated D&D handoff. + +Safe fix: + +- compare external bindings with the selected Notarius pipeline's canonical + consumer documentation; +- keep only campaign-owned external slots on the CLI; and +- leave registry, scene, combat, and occurrence handoffs to Notarius pipeline + composition. + +Narratio validates selector structure and prepared evidence, while Notarius +owns slot declarations, media compatibility, and generated-handoff conflicts. +Relevant reference: [Notarius integration](./integrations/notarius.md). + ## Atomic Notarius promotion unsupported Symptom: @@ -230,6 +290,8 @@ Likely causes: - the executable/config path, pipeline ID, timeout, working directory, or configured output contracts changed; +- a configured prepared reference selector, source, path, checksum, or byte + size changed; - the durable bundle, index, lane set, provenance, regular-file status, or checksum no longer validates. @@ -252,8 +314,9 @@ Safe fix: narratio run-stage extract 2026-04-04 --force ``` -Narratio fingerprints its invocation contract, not the contents of transitive -Notarius inputs. Always force extraction after changing them; downstream +Narratio fingerprints its invocation contract and prepared Narratio reference +identities, not the contents of other transitive Notarius inputs. Always force +extraction after changing those external inputs; downstream successful stages are then marked stale normally. Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow). diff --git a/examples/README.md b/examples/README.md index db05f54..f9938c6 100644 --- a/examples/README.md +++ b/examples/README.md @@ -39,7 +39,9 @@ with the sample campaign and a compatible local- or S3-audio session. [autocorrect](campaigns/sample-campaign/autocorrect.yml), [glossary](campaigns/sample-campaign/glossary.yml), [players](campaigns/sample-campaign/players.yml), and - [party](campaigns/sample-campaign/party.yml) fixtures. + [party](campaigns/sample-campaign/party.yml) fixtures, plus an optional + [spell-catalog overlay](campaigns/sample-campaign/spell_catalog.json) that + follows the Notarius v0.6 contract. - [Sample speaker audio](audio/sample-speaker.flac) is a text placeholder that reserves the expected filename and directory shape. Replace it with a real FLAC file before running transcription. diff --git a/examples/campaigns/sample-campaign/campaign.yml b/examples/campaigns/sample-campaign/campaign.yml index 39288c3..6a0d32e 100644 --- a/examples/campaigns/sample-campaign/campaign.yml +++ b/examples/campaigns/sample-campaign/campaign.yml @@ -6,3 +6,4 @@ inputs: glossary_file: ./glossary.yml players_file: ./players.yml party_file: ./party.yml + spell_catalog_file: ./spell_catalog.json diff --git a/examples/campaigns/sample-campaign/spell_catalog.json b/examples/campaigns/sample-campaign/spell_catalog.json new file mode 100644 index 0000000..fe8effb --- /dev/null +++ b/examples/campaigns/sample-campaign/spell_catalog.json @@ -0,0 +1,18 @@ +{ + "schema_version": "notarius.dnd.spell-catalog-overlay.v1", + "catalogs": [ + { + "id": "narratio.sample-campaign", + "ruleset": "dnd-5e-2014", + "source": { + "title": "Narratio sample campaign spell names" + }, + "spells": [ + { + "name": "Aegis of Emberfall", + "aliases": ["Emberfall Aegis"] + } + ] + } + ] +} diff --git a/examples/pipeline.extraction-subset.yml b/examples/pipeline.extraction-subset.yml index b341b23..feeb28c 100644 --- a/examples/pipeline.extraction-subset.yml +++ b/examples/pipeline.extraction-subset.yml @@ -14,6 +14,11 @@ notarius: config_path: /usr/local/etc/notarius/config.yml pipeline_id: dnd-session timeout: 3h + references: + glossary: narratio.input.glossary + party: narratio.input.party + players: narratio.input.players + spell_catalog: narratio.input.spell_catalog outputs: npc_registry: lane_id: npc-registry @@ -52,4 +57,3 @@ scriptorium: scenes: source: narratio.extraction.scene_descriptions required: true - diff --git a/examples/pipeline.full.annotated.yml b/examples/pipeline.full.annotated.yml index 147ee64..c215464 100644 --- a/examples/pipeline.full.annotated.yml +++ b/examples/pipeline.full.annotated.yml @@ -136,6 +136,13 @@ notarius: pipeline_id: dnd-session timeout: 3h working_directory: /usr/local/etc/notarius + # External campaign references use prepared Narratio source IDs. Omit an + # optional binding when the selected Notarius pipeline does not need it. + references: + glossary: narratio.input.glossary + party: narratio.input.party + players: narratio.input.players + spell_catalog: narratio.input.spell_catalog # Each key creates source narratio.extraction.. These constraints match # the current Notarius D&D lane contracts; update them with Notarius. outputs: