Refactor and clean up documentation
This commit is contained in:
@@ -1,105 +1,127 @@
|
||||
# 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.
|
||||
This document maps the implemented Notarius components and their ownership. It
|
||||
complements the durable invariants in [Architecture](../policy/architecture.md)
|
||||
and links to focused internal documentation for deeper behavior.
|
||||
|
||||
## Executable And CLI
|
||||
## Execution Path
|
||||
|
||||
`cmd/notarius` calls the CLI package. `internal/cli` owns:
|
||||
The executable delegates to the CLI, which resolves configuration and wires the
|
||||
production application around the framework runner:
|
||||
|
||||
- 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.
|
||||
```text
|
||||
cmd/notarius
|
||||
-> internal/cli
|
||||
-> config resolution + production registries + LLM client
|
||||
-> input -> chunk -> extract -> merge -> normalize -> output
|
||||
-> durable output writes
|
||||
|
||||
The CLI should stay thin around framework contracts. Domain extraction behavior
|
||||
belongs in modules, not in command handlers.
|
||||
Pipeline side channels:
|
||||
diagnostics checkpoints debug artifacts
|
||||
```
|
||||
|
||||
Pipeline execution is serial. Configuration selects modules for the fixed stage
|
||||
shape; registries construct them after profile, capability, validator, and
|
||||
reference resolution.
|
||||
|
||||
## Application Boundary
|
||||
|
||||
`cmd/notarius` contains the executable entry point and delegates process exit
|
||||
behavior to `internal/cli`.
|
||||
|
||||
`internal/cli` owns command parsing, configuration discovery, production module
|
||||
and validator registration, prompt asset collection, production LLM client
|
||||
construction, reference preparation, workspace recorder setup, durable output
|
||||
writes, and user-facing stdout, stderr, and exit codes. It is the composition
|
||||
root for concrete production packages.
|
||||
|
||||
## 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.
|
||||
| Package | Implemented responsibility |
|
||||
| --- | --- |
|
||||
| `internal/core/artifacts` | Run manifests and artifact serialization shapes. |
|
||||
| `internal/core/config` | Defaults, YAML parsing, environment overrides, validation, redaction, and effective pipeline configuration. |
|
||||
| `internal/core/diagnostics` | Diagnostics run directories, artifact writers, atomic writes, and retention decisions. |
|
||||
| `internal/core/source` | Generic source documents, units, references, and validation. |
|
||||
| `internal/core/workspace` | Workspace settings, safe paths and writes, checkpoint identities, and checkpoint manifest types. |
|
||||
|
||||
Core packages should remain deterministic and concrete. They should not import
|
||||
production modules.
|
||||
These packages provide concrete, deterministic models and policy. Production
|
||||
module registration occurs at the CLI boundary rather than in core packages.
|
||||
|
||||
## 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.
|
||||
| Package | Implemented responsibility |
|
||||
| --- | --- |
|
||||
| `internal/framework/contracts` | Stage, validator, reference, output, and structured LLM interfaces and request/result types. |
|
||||
| `internal/framework/pipeline` | Module registries, profile resolution, capability checks, reference materialization, validation chains, retries, orchestration, warnings, and manifest population. |
|
||||
| `internal/framework/validate` | Shared validator decision and cardinality helpers. |
|
||||
| `internal/framework/llm` | Scriptorium-backed structured completions, prompt/schema asset registration, scheduling, profile recording, and secret redaction. |
|
||||
| `internal/framework/checkpoint` | Workspace-backed checkpoint loading, recording, and payload envelopes. |
|
||||
| `internal/framework/debug` | Workspace-backed framework and LLM debug artifacts. |
|
||||
|
||||
Framework code should stay source-agnostic and domain-agnostic.
|
||||
Framework contracts carry raw stage outputs between modules. The runner owns
|
||||
provenance, validation sequencing, rejection handling, checkpoint boundaries,
|
||||
debug boundaries, and final manifest assembly.
|
||||
|
||||
## Module Packages
|
||||
## Production Modules
|
||||
|
||||
Production module packages live under `internal/modules`:
|
||||
Production implementations live under `internal/modules` and register through
|
||||
the CLI catalog.
|
||||
|
||||
- `input/seriatim`
|
||||
- `chunk/generic`
|
||||
- `chunk/dnd/scenes`
|
||||
- `extract/dnd/spells`
|
||||
- `merge/appendorder`
|
||||
- `normalize/noop`
|
||||
- `output/json`
|
||||
| Stage | Module key | Package | Role |
|
||||
| --- | --- | --- | --- |
|
||||
| Input | `seriatim` | `internal/modules/input/seriatim` | Converts Seriatim transcript JSON into the generic source model. |
|
||||
| Chunk | `generic` | `internal/modules/chunk/generic` | Splits ordered source units by configured unit counts and overlap. |
|
||||
| Chunk | `dnd/scenes` | `internal/modules/chunk/dnd/scenes` | Uses structured LLM output to create contiguous D&D scene chunks. |
|
||||
| Extract | `dnd/spells` | `internal/modules/extract/dnd/spells` | Extracts source-grounded D&D spell-cast artifacts. |
|
||||
| Merge | `appendorder` | `internal/modules/merge/appendorder` | Combines accepted extract outputs in chunk order. |
|
||||
| Normalize | `noop` | `internal/modules/normalize/noop` | Preserves accepted merged output unchanged. |
|
||||
| Output | `json` | `internal/modules/output/json` | Encodes manifests, indexes, warnings, rejections, and accepted lane payloads as logical JSON files. |
|
||||
|
||||
Each module package owns its contract implementation, module spec,
|
||||
registration, options, focused tests, and module-specific errors.
|
||||
`internal/modules/sharedassets` composes shared prompt filesystems.
|
||||
`internal/modules/sharedassets/dnd` owns shared D&D prompt fragments, reference
|
||||
slots, prompt input assembly, and source-unit reference helpers.
|
||||
|
||||
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`.
|
||||
## Validators
|
||||
|
||||
Shared asset package: `internal/modules/sharedassets`
|
||||
Shared D&D helper package: `internal/modules/sharedassets/dnd`
|
||||
Concrete validators live under `internal/validators` and register separately
|
||||
from stage modules. Generic validators cover unconditional test decisions, JSON
|
||||
syntax, and JSON Schema. D&D spell validators cover artifact shape, source
|
||||
reference validity, and source relatedness.
|
||||
|
||||
## Fixtures And Tests
|
||||
The production default chain for `dnd/spells` extract output is registered
|
||||
centrally in `internal/cli`; module packages produce raw output but do not own
|
||||
the production approve/reject policy.
|
||||
|
||||
The repository uses focused package tests plus a fixture-driven CLI workflow.
|
||||
## Files And Run State
|
||||
|
||||
- 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.
|
||||
Notarius keeps distinct output and inspection surfaces:
|
||||
|
||||
Do not use real external services in tests. Use fakes, fixtures, or local test
|
||||
servers.
|
||||
| Surface | Owner | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Durable output | Output module and CLI writer | User-consumable run files. |
|
||||
| Diagnostics | `internal/core/diagnostics` and CLI | Redacted run inspection, reports, warnings, and failures. |
|
||||
| Checkpoints | `internal/framework/checkpoint` | Validated stage reuse for explicit resume. |
|
||||
| Debug artifacts | `internal/framework/debug` and pipeline instrumentation | Sensitive framework-boundary and LLM call inspection. |
|
||||
|
||||
## Boundary Reminders
|
||||
Workspace settings determine whether and where diagnostics, checkpoints, and
|
||||
debug artifacts are written. Concrete stage modules do not receive workspace
|
||||
paths.
|
||||
|
||||
- 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.
|
||||
## Focused Internal Documentation
|
||||
|
||||
- [Pipeline Internals](pipeline.md): resolution, execution, validators,
|
||||
references, retries, checkpoints, outputs, and manifests.
|
||||
- [Module Internals](modules.md): production module contracts, capabilities,
|
||||
options, prompts, schemas, and registration.
|
||||
- [LLM Runtime](llm.md): structured completion contracts, Scriptorium adapter,
|
||||
assets, scheduling, profile recording, and redaction.
|
||||
- [Diagnostics Internals](diagnostics.md): diagnostics files, retention,
|
||||
failure behavior, and path safety.
|
||||
|
||||
## Test Surfaces
|
||||
|
||||
The repository uses focused package tests, registry and pipeline composition
|
||||
tests, a fake-backed walking skeleton, fixture-driven CLI coverage, and local
|
||||
test servers for LLM integration behavior. Tests do not require real provider
|
||||
calls.
|
||||
|
||||
Reference in New Issue
Block a user