Refresh native workflow orientation and planning status

This commit is contained in:
2026-11-22 06:57:27 +00:00
parent b76d511571
commit 633ebd282f
7 changed files with 165 additions and 111 deletions

View File

@@ -1,62 +1,64 @@
# Internal Overview
This document is the implemented component map for Notarius. Normative
boundaries and dependency direction belong in
[Architecture](../policy/architecture.md). User and operator contracts belong
in the [CLI](../cli.md), [Configuration](../config.md),
[Operations](../operations.md), and [integration contracts](../integrations/).
This is the implemented component map, not an architecture policy or public
reference. [Architecture](../policy/architecture.md) owns normative boundaries;
[CLI](../cli.md), [Configuration](../config.md), [Operations](../operations.md),
and [integration contracts](../integrations/) own public behavior.
## Execution Path
~~~
cmd/notarius -> internal/cli -> configuration and production composition
-> internal/framework/pipeline -> logical output files
-> internal/cli -> durable output and optional state/debug data
~~~
```text
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 CLI is the application boundary: it discovers configuration, composes
production registries and runtime collaborators, invokes the framework, and
places returned files. The framework resolves and prepares a fixed extraction
pipeline, then returns logical results without owning process behavior or
physical state roots.
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 command boundary | **cmd/notarius**, **internal/cli** | Process entry, command dispatch, configuration discovery, production composition, runtime collaborator setup, durable file placement, and user-facing reporting. |
| Build information | **internal/buildinfo** | Resolves a stable linked release tag or build metadata for the diagnostic root version command. |
| Configuration | **internal/core/config** | ConfigKit document definition, source-aware normalization, runtime conversion, structural validation, safe inspection, effective resolution, and resolved-composition redaction. |
| Generic models | **internal/core/source**, **internal/core/artifacts**, **internal/framework/contracts** | Source documents and chunks, manifests and provenance, plus typed artifact, reference, validation, output, and structured-completion contracts. |
| Pipeline framework | **internal/framework/pipeline** | Registries, profile and reference resolution, typed preparation, validation, retry coordination, ordered execution, handoff, and result assembly. |
| LLM and prompt runtime | **internal/framework/llm**, **internal/framework/promptfs** | Provider-neutral structured completions, scheduling, profile recording, prompt assets, schema registration, and credential-shaped-value redaction. |
| Semantic reconciliation | **internal/framework/semanticreconcile** | Bounded source-backed candidate preparation, request-local handle proposals, deterministic assessment, typed plan application, and reconciliation identity metadata; see [Module Internals](modules.md#semantic-reconciliation) and [D&D Module Internals](dnd.md#semantic-registry-reconciliation). |
| Embedded LLM content | **assets** | Read-only centralized LLM-facing content, scoped by its consuming package; see [LLM Runtime](llm.md#prompt-and-schema-assets) and [D&D Module Internals](dnd.md#prompt-construction). |
| Runtime state | **internal/core/fileio**, **internal/core/debugbundle**, **internal/framework/checkpoint**, **internal/framework/chunkplan**, **internal/framework/chunkmap**, **internal/framework/debug** | Confined atomic files, debug bundles, checkpoint and chunk-plan state, accepted chunk maps, and pipeline-facing debug recording. |
| Production extensions | **internal/modules/generic**, **internal/modules/seriatim**, **internal/modules/dnd** | Domain-neutral extensions, Seriatim input support, and D&D extraction families registered into the production catalog. |
| Executable and native CLI | [cmd/notarius](../../cmd/notarius/), [internal/cli](../../internal/cli/) | Identity, native commands/aliases/suites, invocation-local source/engine selection, registrars, run composition, publication/reporting. |
| Build information | [internal/buildinfo](../../internal/buildinfo/) | Linked release or build metadata supplied to the native version command. |
| Application configuration | [internal/core/config](../../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/core/source/), [internal/framework/contracts](../../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](../../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](../../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](../../internal/framework/semanticreconcile/) | Fixed bounded candidate/window preparation, native request builders, request-local handle/proposal safety, and typed fresh application. |
| Embedded content | [assets](../../assets/) | Content-only native prompt/profile/schema/message files imported with filesystem contexts; no behavioral registry. |
| Accepted-result cache | [internal/framework/artifactcache](../../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/fileio/), [internal/core/debugbundle](../../internal/core/debugbundle/), [internal/framework/debug](../../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/chunkmap/), [internal/framework/evidencecontext](../../internal/framework/evidencecontext/) | Materialized chunk-map and selected citation/source-unit artifacts with intrinsic contracts. |
| Production extensions | [internal/modules/generic](../../internal/modules/generic/), [internal/modules/seriatim](../../internal/modules/seriatim/), [internal/modules/dnd](../../internal/modules/dnd/) | Domain-neutral operations, Seriatim input, D&D typed artifact families/validators/codecs/projections, and registrar policy. |
Generic core and framework packages do not depend on production extensions.
Concrete extensions depend inward on their contracts and are registered only at
the CLI composition boundary.
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](configuration.md): loading, validation, effective
resolution, redaction, and resolved-composition identity.
- [CLI Internals](cli.md): command dispatch, production composition, run
orchestration, and terminal reporting.
- [Pipeline Internals](pipeline.md): resolution, preparation, execution,
validation, typed handoff, and framework state hooks.
- [Run State Internals](state.md): output, cache, debug collaborator
composition, and path safety.
- [LLM Runtime](llm.md): structured completion, scheduling, prompt assets,
profiles, and secret handling.
- [Module Internals](modules.md): generic extension registration, artifact
families, module construction, semantic reconciliation, validation, and
reference mechanics.
- [D&D Module Internals](dnd.md): shared D&D extractor conventions, generated
reference projections, and lane-specific exceptions. Durable D&D and
Seriatim data shapes remain in the [integration contracts](../integrations/).
- [Configuration Internals](configuration.md): definition, original result handoff,
captured contexts, runtime conversion, and selection reuse.
- [CLI Internals](cli.md): lazy declarations, suite/registrar wiring, ordered run
composition, and native outcomes.
- [Pipeline Internals](pipeline.md): typed assessment/continuation, workers,
handoffs, eligibility, and logical output.
- [Run State Internals](state.md): accepted-result store/prepared handles,
publication, capture, and failure retention.
- [LLM Integration](llm.md): shared native engine, request/validator boundaries,
prompt/schema selection, and observations.
- [Module Internals](modules.md) and [D&D Module Internals](dnd.md): typed extension
recipes, fixed normalization inputs, contextual identity/evidence, and domain exceptions.
- [ConfigKit](../integrations/pkg-configkit.md), [PromptKit](../integrations/pkg-promptkit.md),
and [CommandKit](../integrations/pkg-commandkit.md) integration contracts: selected
native public APIs, source/command handoffs, and pinned upstream references.
Use this map to find an owner, then read the focused document and its tests
before changing behavior.
Use this map to find an owner, then inspect its focused source/tests.
[Development](../development.md) owns contributor reading and validation guidance.