Refresh native workflow orientation and planning status
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user