notarius/docs/roadmap/future.md

# Future Work

Current Notarius behavior is documented in the canonical README, CLI,
configuration, operations, internal, and integration docs. This roadmap records
future work only. Items are ordered roughly by current value and specificity,
not as committed release dates.

## Near-Term D&D Pipeline

### Combat Enemy Ledger

- Add a D&D artifact that identifies enemies faced during combat and supports
  an end-of-session encounter ledger.
- Track each enemy's observed state using a small controlled vocabulary such as
  `active`, `killed`, `fled`, `captured`, or `incapacitated`, while preserving
  an explicit unresolved state when the transcript does not establish an
  outcome.
- Preserve the evidence for enemy participation and state changes rather than
  inferring a terminal outcome from combat ending or an enemy disappearing
  from the conversation.
- Define how repeated mentions, groups of unnamed enemies, summoned or allied
  creatures, and the same enemy appearing in multiple combats affect identity
  and ledger entries.
- Evaluate whether the ledger should be extracted directly, derived from
  combat-turn artifacts, or use a sequential pipeline that consumes combat
  turns and the normalized NPC registry as grounding references.

### Location Extraction

- Add a D&D artifact for locations visited by the party or otherwise mentioned
  in the transcript.
- Distinguish observed visits from references, plans, recalled places, and
  uncertain or inferred locations so a mention alone is not reported as a
  visit.
- Preserve transcript evidence for each visit or mention and reconcile aliases,
  nested places, and repeated appearances without collapsing distinct
  locations that share a generic name.
- Define how the location artifact should ground later narrative reports and
  whether future event artifacts should retain canonical location identities.

### Evaluate Spell Extraction And Normalization

- Evaluate ordinary extraction retries and the completed normalization path
  against a human-reviewed transcript set before adding repair-aware retries or
  an LLM-backed semantic validator.
- Maintain a small set of human-reviewed transcripts and outputs for prompt,
  validator, and normalizer development. Treat model-quality review as an
  iterative human evaluation aid, not a deterministic correctness gate.

### Evaluate The Shared D&D Scene Plan

- Reassess whether one shared scene plan provides enough context for NPC,
  spell, combat, interaction, and scene-description lanes after real-world use.
  Add more complex chunking only in response to demonstrated failures.

## Cross-Cutting LLM Runtime

### Deterministic Prompt Session Identity

- Replace the source-document-ID default for prompt sessions with one
  predictable, procedurally generated session ID for the complete
  source-processing workload.
- Preserve an explicit non-empty `--session-id` as the highest-precedence
  override. Otherwise, derive the default only from the effective input module
  identity and the exact raw input bytes.
- Use a versioned, bounded representation such as
  `notarius:v1:<sha256(input-module + NUL + raw-input)>`. The exact encoding
  must fit PromptKit's session length contract and must not embed source
  content.
- Keep the derived session stable across runs, pipelines, selected lanes,
  ordered steps, retries, resume, recomputation, LLM profiles, reasoning
  overrides, and output, debug, or cache settings.
- Do not include file-backed references, generated references, reference
  contents, or the composition of a reference bundle in session derivation.
  References may change between prompt calls within one pipeline without
  changing routing affinity.
- Resolve the authoritative session before checkpoint construction and use the
  same value for checkpoint runtime identity, every prompt-facing module,
  PromptKit's direct session field, the compatibility `session_id` prompt
  variable, run-manifest metadata, and debug metadata.
- Keep routing identity separate from cache and checkpoint content identity.
  Exact prompt prefixes, reference contents, model settings, and other
  generation-affecting inputs must continue to participate in their existing
  hashes and checkpoint fingerprints even though they do not change the
  session.
- Treat the generated value as a provider-visible, stable pseudonymous
  correlation identifier. Do not introduce an installation-specific HMAC or
  secret unless a concrete multi-tenant or privacy requirement justifies
  sacrificing deterministic identity across installations.

### Pipeline-Level LLM Profile Defaults

- Add an optional pipeline-level `llm_profile` default so an operator can
  select one PromptKit execution policy for the pipeline without repeating the
  same profile ID on every LLM-backed module binding.
- Apply the following precedence consistently: an explicit run-wide
  `--llm-profile` override, then a binding-specific `llm_profile`, then the
  pipeline-level default, then the prompt definition's embedded
  `default_profile`.
- Apply inheritance only to bindings whose resolved modules are LLM-backed,
  including applicable chunk, extraction, merge, normalization, and validation
  bindings. Do not attach an inherited profile to deterministic modules or
  weaken existing validation that rejects profiles where generation is not
  supported.
- Resolve inherited profiles before effective-pipeline validation, digest and
  checkpoint construction, execution, and provenance capture. Validate every
  resulting explicit profile ID against the selected PromptKit profile source,
  and ensure manifests and debug output report the profile actually selected
  for each generation target.
- Preserve binding-specific profiles as intentional exceptions for modules
  that require a different quality, latency, cost, provider, or reasoning
  policy. Preserve `--llm-profile` as the convenient highest-precedence
  experiment or incident-response override for an entire run.
- Treat PromptKit profiles as execution-policy configuration and prefer stable,
  workload-oriented IDs such as `dnd-extraction` over model names. A pipeline
  should express the kind of work it performs rather than encode a particular
  provider, model, or deployment environment.
- Establish deployment-managed PromptKit profile files as the recommended
  environment-specific configuration mechanism. Production, development, and
  local deployments may each define the same logical `dnd-extraction` ID with
  different model and generation settings, while retaining one unchanged
  Notarius pipeline definition.
- Keep deployment profiles distinct from both Notarius prompt assets embedded
  in the application binary and PromptKit's built-in profile catalog. Document
  that `promptkit.profile_dir` or `promptkit.profile_file` selects an external
  filesystem source whose definitions overlay PromptKit built-ins, and
  recommend application-owned IDs rather than silently replacing built-in
  profile IDs.
- Document an operator-friendly layout in which the Notarius configuration and
  a profile subdirectory are deployed together. Until profile paths are
  explicitly resolved relative to the configuration file, clearly state that
  relative paths use the process working directory and recommend absolute
  paths for services and containers.
- Update the configuration reference, operations guide, PromptKit integration
  boundary, relevant internal configuration and pipeline documentation, and
  maintained D&D examples together. Include one concrete external-profile
  example and explain the profile precedence and environment-neutral pipeline
  pattern without duplicating PromptKit's complete profile-format reference.

### Raise The Default Application-Wide LLM Limit

- Raise the default `concurrency.total_llm` value from 1 to 16 so ordinary
  single-backend runs can use PromptKit's expected OpenRouter capacity and
  lower-capacity local backends without an unnecessarily narrower Notarius
  limit.
- Keep the Notarius application-wide scheduler mandatory and require
  `total_llm` to remain a positive integer. Do not make the default unlimited:
  endpoint-only profiles, an unrestricted local backend, injected clients, and
  aggregate work across several backends may have no narrower PromptKit limit.
- Continue defaulting `concurrency.stage_workers.extract` to the effective
  `total_llm`, making its default 16 as part of the same change. Preserve an
  explicit lower extract-worker setting when an operator wants less queued or
  concurrent extraction work.
- Define effective provider concurrency as the intersection of the Notarius
  application-wide limit, the selected PromptKit backend limit when present,
  and the work made available by stage execution. A Notarius limit of 16 does
  not narrow a backend already limited to 16, while a local backend limited to
  4 remains bounded at 4.
- Treat the default as an application-wide safety ceiling across profiles,
  backends, modules, retries, and validators. A run that intentionally needs
  the combined capacity of several backends may configure a higher
  `total_llm` and an appropriate extract-worker count explicitly.
- Retain the existing configuration and environment override surfaces. Update
  canonical configuration, operations, and internal documentation together
  when the default changes.
- Reconsider decoupling the extract-worker default from `total_llm` only after
  mixed-backend workloads demonstrate a need for a high global emergency
  ceiling with a lower default work-production rate.

## Shared Normalization And Quality Work

### Generic LLM-Assisted Deduplication

- Add a reusable normalizer that asks an LLM to identify duplicate sets in a
  list and propose one replacement element for each set.
- Define the minimum domain-neutral input contract, initially an ordered list
  whose elements have stable unique IDs. Artifact-kind registrations or
  adapters may expose that structure without moving domain rules into the
  generic package.
- Keep mutation deterministic: parse and validate the model's duplicate groups,
  require every referenced ID to exist, reject overlapping or malformed groups,
  prevent unrelated insertion or deletion, and apply only approved replacement
  operations in code.
- Preserve provenance needed for audit and downstream validation, and emit
  warnings describing every collapsed group.
- Evaluate batching and context-window limits before applying the normalizer to
  large artifact collections.

The model may use its own domain knowledge to judge semantic duplication; the
generic implementation is responsible only for the common proposal contract,
safety checks, and deterministic application of accepted changes.

### Validation And Review

- Add domain validators and production default chains alongside each new D&D
  artifact.
- Add production LLM-backed validators only when a concrete review policy
  benefits from model judgment and deterministic checks are insufficient.
- Add validator diagnostics and timing summaries if operators need more detail
  than the current [durable output bundle](../integrations/json-output.md)
  provides.
- Add validator compatibility metadata if deployments need config-time proof
  that a validator is suitable for a particular stage, module, or artifact
  kind.
- Add media-type validators when non-JSON artifact representations are
  introduced.

## Further Reference Evolution

- Make prior-run artifacts easier to bind as references without changing the
  existing module-facing reference-item contract.
- Add structured or parsed references, such as typed NPC registries, rosters,
  or spell catalogs, when opaque UTF-8 prompt material is no longer sufficient.
- Add per-slot or per-chunk inclusion policies so large references are not
  repeated in every prompt unnecessarily.
- Add token budgeting and model context-window management for reference
  content.
- Add reference caching, preprocessing, summarization, embedding, or retrieval
  only when reference size and observed model behavior justify them.
- Extend generated references to prior-run artifacts or derived summaries only
  after same-run ordered handoffs establish the required provenance and
  lifecycle semantics.

## Design Considerations To Revisit

These concerns are relevant to ordered artifact dependencies but are not
committed near-term features.

### Cross-artifact identity links

Evaluate whether downstream D&D artifacts should retain canonical NPC IDs from
the generated NPC reference in addition to normalized display names. Any such
contract must define player-character, unknown-actor, missing-NPC, and
superseded-identity behavior before implementation. Deterministic validation
may confirm that a linked ID exists in the consumed NPC artifact, but the link
must never substitute for transcript evidence that the downstream event
occurred.

### Artifact contract evolution

Define compatibility and migration policy before generated-reference chains
must span multiple schema versions or long-lived historical artifacts. The
policy should address stable identifier semantics, which schema changes permit
checkpoint reuse, when an older artifact may be decoded or adapted, and when a
producer or all dependents must be recomputed. Do not add a general migration
framework until an actual contract change requires one.

## Blue-Sky Platform And Operations

These ideas are intentionally less specified. Promote one into an earlier
section only after a concrete workflow, contract, and priority emerge.

### Platform Extensions

- Additional input adapters, such as Markdown or note-export formats.
- Additional output encoders.
- Concurrent cross-lane entity normalization or broader workflow composition.
- Batching or specialized context-window controls for LLM-backed validators.

### Distribution And Operations

- Packaged release artifacts for alpha distribution.
- A documented versioning and release process.
- Optional generated example-output fixtures with a regeneration procedure.
- Additional diagnostics or reporting views.

### Workspace And Storage

- Default-idempotent run behavior with an explicit force override.
- Remote workspace storage.
- Workspace garbage collection and archival policies.
- Cross-machine checkpoint reuse.