notarius/docs/internal/overview.md

Internal Overview

This document is the implemented component map for Notarius. Normative boundaries and dependency direction belong in Architecture. User and operator contracts belong in the CLI, Configuration, Operations, and integration contracts.

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.
Configuration	internal/core/config	Defaults, strict YAML parsing, environment overrides, structural validation, effective resolution, redaction, and resolved-composition summaries.
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 and D&D Module Internals.
Embedded LLM content	assets	Read-only centralized LLM-facing content, scoped by its consuming package; see LLM Runtime and D&D Module Internals.
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: loading, validation, effective resolution, redaction, and resolved-composition identity.
• CLI Internals: command dispatch, production composition, run orchestration, and terminal reporting.
• Pipeline Internals: resolution, preparation, execution, validation, typed handoff, and framework state hooks.
• Run State Internals: output, cache, debug collaborator composition, and path safety.
• LLM Runtime: structured completion, scheduling, prompt assets, profiles, and secret handling.
• Module Internals: generic extension registration, artifact families, module construction, semantic reconciliation, validation, and reference mechanics.
• D&D Module Internals: shared D&D extractor conventions, generated reference projections, and lane-specific exceptions. Durable D&D and Seriatim data shapes remain in the integration contracts.

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