Files
notarius/docs/internal/overview.md

5.6 KiB

Internal Overview

This is the implemented component map, not an architecture policy or public reference. Architecture owns normative boundaries; CLI, Configuration, Operations, and integration contracts own public behavior.

Execution Path

cmd/notarius -> internal/cli: native commands, one selected config result/engine
             -> resolve + offline preflight + materialize + typed preparation
             -> pipeline: parse -> chunk -> ordered lane work -> logical files
             -> internal/cli: publication -> requested capture finish -> report

The executable supplies build identity. The composition root owns native command declarations, source acquisition, registrars, shared engine, and physical state. The framework and modules receive explicit collaborators/data rather than process streams or roots. Standard inspection/preflight paths do not become runs.

Components

Area Implemented owners Responsibility
Executable and native CLI cmd/notarius, internal/cli Identity, native commands/aliases/suites, invocation-local source/engine selection, registrars, run composition, publication/reporting.
Build information internal/buildinfo Linked release or build metadata supplied to the native version command.
Application configuration internal/core/config Composed ConfigKit/native settings definition, source-aware normalization, detached runtime conversion, application validation, effective domain resolution.
Generic source and typed contracts internal/core/source, internal/framework/contracts Documents/units/chunks, typed production/assessment, source references, codecs, native execution selections, and small cache/evidence collaborators.
Pipeline framework internal/framework/pipeline Registries, typed resolution/preparation, complete candidate assessment, native producer helper, ready-job workers, ordered handoffs, reuse eligibility, evidence/output assembly.
Offline dependency preflight internal/preflight Known native prompt/profile checks on already resolved composition and supplied engine; no synthetic request or execution input reads.
Semantic reconciliation internal/framework/semanticreconcile Fixed bounded candidate/window preparation, native request builders, request-local handle/proposal safety, and typed fresh application.
Embedded content assets Content-only native prompt/profile/schema/message files imported with filesystem contexts; no behavioral registry.
Accepted-result cache internal/framework/artifactcache Raw accepted artifact/plan bytes under native content keys, confined atomic publication, and deployment-owned creation permissions.
Capture and file placement internal/core/fileio, internal/core/debugbundle, internal/framework/debug Confined writes, run capture allocation/start-time latest link, incremental evidence, one terminalization, and retained causes.
Source auxiliaries internal/framework/chunkmap, internal/framework/evidencecontext Materialized chunk-map and selected citation/source-unit artifacts with intrinsic contracts.
Production extensions internal/modules/generic, internal/modules/seriatim, internal/modules/dnd Domain-neutral operations, Seriatim input, D&D typed artifact families/validators/codecs/projections, and registrar policy.

Native PromptKit requests/results/continuation/observations cross the intentional model-execution boundary directly. There is no private LLM adapter/scheduler, prompt filesystem registry, checkpoint subsystem, or separate source-keyed plan store. Pure source/domain/codecs remain separate from model execution. Generic framework packages do not import concrete production extensions.

Focused Documentation

  • Configuration Internals: definition, original result handoff, captured contexts, runtime conversion, and selection reuse.
  • CLI Internals: lazy declarations, suite/registrar wiring, ordered run composition, and native outcomes.
  • Pipeline Internals: typed assessment/continuation, workers, handoffs, eligibility, and logical output.
  • Run State Internals: accepted-result store/prepared handles, publication, capture, and failure retention.
  • LLM Integration: shared native engine, request/validator boundaries, prompt/schema selection, and observations.
  • Module Internals and D&D Module Internals: typed extension recipes, fixed normalization inputs, contextual identity/evidence, and domain exceptions.
  • ConfigKit, PromptKit, and CommandKit integration contracts: selected native public APIs, source/command handoffs, and pinned upstream references.

Use this map to find an owner, then inspect its focused source/tests. Development owns contributor reading and validation guidance.