Document prepared Notarius references

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.

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`

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.<key>`
 - extraction lanes: `narratio.extraction.<key>`
 - previous-session cache: `narratio.previous_session.artifact.<key>`
@@ -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.

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.<output_key>` for downstream
+8. registers each lane as `narratio.extraction.<output_key>` 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,

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;