notarius/docs/internal/overview.md

# Internal Overview

This document is the implemented component map for Notarius. Normative
boundaries and dependency direction belong in
[Architecture](../policy/architecture.md). User and operator contracts belong
in the [CLI](../cli.md), [Configuration](../config.md),
[Operations](../operations.md), and [integration contracts](../integrations/).

## Execution Path

~~~
cmd/notarius -> internal/cli -> configuration and production composition
             -> internal/framework/pipeline -> logical output files
             -> internal/cli -> durable output and optional state/debug data
~~~

The CLI is the application boundary: it discovers configuration, composes
production registries and runtime collaborators, invokes the framework, and
places returned files. The framework resolves and prepares a fixed extraction
pipeline, then returns logical results without owning process behavior or
physical state roots.

## Components

| Area | Implemented owners | Responsibility |
| --- | --- | --- |
| Executable and command boundary | **cmd/notarius**, **internal/cli** | Process entry, command dispatch, configuration discovery, production composition, runtime collaborator setup, durable file placement, and user-facing reporting. |
| Build information | **internal/buildinfo** | Resolves a stable linked release tag or build metadata for the diagnostic root version command. |
| Configuration | **internal/core/config** | ConfigKit document definition, source-aware normalization, runtime conversion, structural validation, safe inspection, effective resolution, and resolved-composition redaction. |
| Generic models | **internal/core/source**, **internal/core/artifacts**, **internal/framework/contracts** | Source documents and chunks, manifests and provenance, plus typed artifact, reference, validation, output, and structured-completion contracts. |
| Pipeline framework | **internal/framework/pipeline** | Registries, profile and reference resolution, typed preparation, validation, retry coordination, ordered execution, handoff, and result assembly. |
| LLM and prompt runtime | **internal/framework/llm**, **internal/framework/promptfs** | Provider-neutral structured completions, scheduling, profile recording, prompt assets, schema registration, and credential-shaped-value redaction. |
| Semantic reconciliation | **internal/framework/semanticreconcile** | Bounded source-backed candidate preparation, request-local handle proposals, deterministic assessment, typed plan application, and reconciliation identity metadata; see [Module Internals](modules.md#semantic-reconciliation) and [D&D Module Internals](dnd.md#semantic-registry-reconciliation). |
| Embedded LLM content | **assets** | Read-only centralized LLM-facing content, scoped by its consuming package; see [LLM Runtime](llm.md#prompt-and-schema-assets) and [D&D Module Internals](dnd.md#prompt-construction). |
| Runtime state | **internal/core/fileio**, **internal/core/debugbundle**, **internal/framework/checkpoint**, **internal/framework/chunkplan**, **internal/framework/chunkmap**, **internal/framework/debug** | Confined atomic files, debug bundles, checkpoint and chunk-plan state, accepted chunk maps, and pipeline-facing debug recording. |
| Production extensions | **internal/modules/generic**, **internal/modules/seriatim**, **internal/modules/dnd** | Domain-neutral extensions, Seriatim input support, and D&D extraction families registered into the production catalog. |

Generic core and framework packages do not depend on production extensions.
Concrete extensions depend inward on their contracts and are registered only at
the CLI composition boundary.

## Focused Documentation

- [Configuration Internals](configuration.md): loading, validation, effective
  resolution, redaction, and resolved-composition identity.
- [CLI Internals](cli.md): command dispatch, production composition, run
  orchestration, and terminal reporting.
- [Pipeline Internals](pipeline.md): resolution, preparation, execution,
  validation, typed handoff, and framework state hooks.
- [Run State Internals](state.md): output, cache, debug collaborator
  composition, and path safety.
- [LLM Runtime](llm.md): structured completion, scheduling, prompt assets,
  profiles, and secret handling.
- [Module Internals](modules.md): generic extension registration, artifact
  families, module construction, semantic reconciliation, validation, and
  reference mechanics.
- [D&D Module Internals](dnd.md): shared D&D extractor conventions, generated
  reference projections, and lane-specific exceptions. Durable D&D and
  Seriatim data shapes remain in the [integration contracts](../integrations/).

Use this map to find an owner, then read the focused document and its tests
before changing behavior.