106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# 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.
|
|
- `internal/core/workspace`: effective workspace roots, enabled-state helpers,
|
|
safe workspace-relative path construction, atomic workspace artifact writes,
|
|
checkpoint identities, checkpoint path construction, and checkpoint manifest
|
|
types.
|
|
|
|
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/checkpoint`: workspace-backed checkpoint recorder and
|
|
checkpoint payload envelope serialization.
|
|
- `internal/framework/debug`: workspace-backed debug artifact writer.
|
|
- `internal/framework/pipeline`: module registries, module specs, profile
|
|
resolution, capability checks, run orchestration, checkpoint and debug
|
|
recorder boundaries, 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.
|