# Internal Overview

This directory documents implemented Notarius internals for developers and LLM
coding agents. It complements [Architecture](../policy/architecture.md), which
is the durable policy for boundaries and invariants.

## Executable And CLI

`cmd/notarius` calls the CLI package. `internal/cli` owns:

- command parsing and usage;
- config discovery and loading;
- production module catalog and registry wiring;
- production LLM client construction;
- run directory creation;
- durable output writes;
- user-facing stdout, stderr, and exit codes.

The CLI should stay thin around framework contracts. Domain extraction behavior
belongs in modules, not in command handlers.

## Core Packages

- `internal/core/artifacts`: run manifests and legacy artifact serialization
  shapes retained while pipeline handoff contracts use raw outputs.
- `internal/core/config`: defaults, YAML config parsing, environment overrides,
  validation, redaction, and resolved pipeline config.
- `internal/core/diagnostics`: per-run diagnostics directory creation,
  diagnostics artifact writers, atomic writes, and retention decisions.
- `internal/core/source`: source documents, source units, source references, and
  validation.

Core packages should remain deterministic and concrete. They should not import
production modules.

## Framework Packages

- `internal/framework/contracts`: interfaces and request/result structs for
  input adapters, chunkers, extractors, mergers, normalizers, validators, output
  encoders, and structured LLM clients.
- `internal/framework/pipeline`: module registries, module specs, profile
  resolution, capability checks, run orchestration, warnings, validation, and
  manifest population.
- `internal/framework/llm`: Scriptorium-backed structured-output client,
  prompt/schema asset registry, scheduler, schema registry, and secret
  redaction.
- `internal/framework/validate`: validator decision helpers and cardinality
  enforcement.

Framework code should stay source-agnostic and domain-agnostic.

## Module Packages

Production module packages live under `internal/modules`:

- `input/seriatim`
- `chunk/generic`
- `chunk/dnd/scenes`
- `extract/dnd/spells`
- `merge/appendorder`
- `normalize/noop`
- `output/json`

Each module package owns its contract implementation, module spec,
registration, options, focused tests, and module-specific errors.

Module-owned prompts and schemas live in each module's shallow `assets/prompts`
and `assets/schemas` directories. Generic shared prompt filesystem composition
lives in `internal/modules/sharedassets`; shared D&D prompt fragments and
reference helpers live in `internal/modules/sharedassets/dnd`.

Shared asset package: `internal/modules/sharedassets`
Shared D&D helper package: `internal/modules/sharedassets/dnd`

## Fixtures And Tests

The repository uses focused package tests plus a fixture-driven CLI workflow.

- CLI acceptance tests cover maintained examples under `examples/`.
- Pipeline tests cover registry composition and end-to-end framework behavior
  with fakes.
- Module tests cover implemented module contracts without requiring real
  provider calls.
- LLM tests use local test servers and fakes.

Do not use real external services in tests. Use fakes, fixtures, or local test
servers.

## Boundary Reminders

- Source-format details stay in input modules and integration docs.
- Extraction-domain details stay in extract modules and artifact docs.
- Generic shared prompt plumbing stays in `internal/modules/sharedassets`;
  domain-specific shared prompt behavior stays with the relevant module helper
  package.
- Provider wire details stay in the LLM runtime and provider integration docs.
- Durable output contracts belong in integration docs.
- Operator procedures belong in `docs/operations.md`, not internal docs.