Internal Overview

This directory documents implemented Notarius internals for developers and LLM coding agents. It complements Architecture, 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: artifact candidates, approved artifacts, rejected artifacts, validation decisions, and run manifests.
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.

3.7 KiB Raw Blame History