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

@@ -8,25 +8,26 @@ and spell casts.
## Quickstart ## Quickstart
Provide an OpenRouter API key through the environment, then run the maintained Set `OPENROUTER_API_KEY` in your environment, then run the maintained
minimal example: [minimal example](examples/dnd-minimal/config.yml) with its synthetic transcript:
~~~ ~~~
OPENROUTER_API_KEY=your-api-key \ go run ./cmd/notarius run dnd-session \
go run ./cmd/notarius run dnd-session \ --config examples/dnd-minimal/config.yml \
--config examples/dnd-minimal.config.yml \ --input-file examples/dnd-minimal/transcript.json
--input examples/seriatim-minimal-transcript.json
~~~ ~~~
The command publishes a JSON output bundle. Its command syntax and exit This makes model calls and publishes domain JSON artifacts. Command syntax and exit
behavior are documented in the [CLI reference](docs/cli.md); configuration, behavior are documented in the [CLI reference](docs/cli.md); configuration,
credentials, and module selection are owned by the credentials, and module selection are owned by the
[configuration reference](docs/config.md). [configuration reference](docs/config.md).
For the complete ordered D&D workflow, use For the complete ordered D&D workflow, use
[the complete configuration](examples/dnd-complete.config.yml) with [the complete configuration](examples/dnd-complete/config.yml) with
[its synthetic transcript](examples/dnd-complete-transcript.json). It [its synthetic transcript](examples/dnd-complete/transcript.json). It
demonstrates all implemented D&D lanes and the supporting campaign references. demonstrates all implemented D&D lanes, ordered generated references, native
resource customization, and optional source auxiliaries. See the
[complete workflow](docs/consumers/dnd-pipeline.md) for invocation and discovery.
## Install A Source Release ## Install A Source Release
@@ -53,8 +54,10 @@ Releases](docs/release.md).
validation, and module selection. validation, and module selection.
- [Operations](docs/operations.md) — output, state, recovery, and debug - [Operations](docs/operations.md) — output, state, recovery, and debug
handling. handling.
- [Integration contracts](docs/integrations/) — Seriatim input and published - [Integration contracts](docs/integrations/) — Seriatim input, domain artifacts,
artifact formats. and native [ConfigKit](docs/integrations/pkg-configkit.md),
[PromptKit](docs/integrations/pkg-promptkit.md), and
[CommandKit](docs/integrations/pkg-commandkit.md) boundaries.
- [Subprocess consumer guide](docs/consumers/subprocess.md) — invoke Notarius - [Subprocess consumer guide](docs/consumers/subprocess.md) — invoke Notarius
from an orchestrator and consume a published result. from an orchestrator and consume a published result.
- [Complete D&D consumer guide](docs/consumers/dnd-pipeline.md) — run the full - [Complete D&D consumer guide](docs/consumers/dnd-pipeline.md) — run the full
@@ -63,8 +66,8 @@ Releases](docs/release.md).
for maintainers. for maintainers.
- [Developer guide](docs/development.md) — contributor orientation and - [Developer guide](docs/development.md) — contributor orientation and
validation guidance. validation guidance.
- [Native migration roadmap](docs/roadmap/promptkit.md) — the planned PromptKit, - [Native migration guide](docs/consumers/native-migration.md) — move existing
ConfigKit, and CommandKit cutover. configurations, invocations, and consumers to the native surface.
- [Future work](docs/roadmap/future.md) — separate backlog of ideas and priorities. - [Future work](docs/roadmap/future.md) — separate backlog of ideas and priorities.
Notarius is licensed under the [GPL v3.0 or later](COPYRIGHT). Notarius is licensed under the [GPL v3.0 or later](COPYRIGHT).

View File

@@ -42,13 +42,14 @@ implementing changes. It owns implementation discipline and local commit rules.
| CLI composition or command behavior | [CLI Internals](internal/cli.md) and [CLI Reference](cli.md) | The internal guide owns composition and command flow; the reference owns public syntax. | | CLI composition or command behavior | [CLI Internals](internal/cli.md) and [CLI Reference](cli.md) | The internal guide owns composition and command flow; the reference owns public syntax. |
| Building a subprocess caller or changing its result protocol | [Subprocess Consumer Guide](consumers/subprocess.md), [Complete D&D Consumer Guide](consumers/dnd-pipeline.md), [Native Completion Report](cli.md#completion-report), and [CLI Internals](internal/cli.md) | These separate generic caller workflow, the complete D&D workflow, the native completion report, and CLI implementation behavior. | | Building a subprocess caller or changing its result protocol | [Subprocess Consumer Guide](consumers/subprocess.md), [Complete D&D Consumer Guide](consumers/dnd-pipeline.md), [Native Completion Report](cli.md#completion-report), and [CLI Internals](internal/cli.md) | These separate generic caller workflow, the complete D&D workflow, the native completion report, and CLI implementation behavior. |
| Configuration loading, resolution, or user-visible configuration behavior | [Configuration Internals](internal/configuration.md) and [Configuration](config.md) | The internal guide owns loading and resolution mechanics; the reference owns the configuration contract. | | Configuration loading, resolution, or user-visible configuration behavior | [Configuration Internals](internal/configuration.md) and [Configuration](config.md) | The internal guide owns loading and resolution mechanics; the reference owns the configuration contract. |
| Pipeline resolution or execution | [Pipeline Internals](internal/pipeline.md) | It documents profiles, references, validation, retries, checkpoints, and runner behavior. | | Pipeline resolution or execution | [Pipeline Internals](internal/pipeline.md) | It documents typed preparation, complete assessment, native continuation, workers, and handoff eligibility. |
| Production modules or validators | [Module Internals](internal/modules.md), [D&D Module Internals](internal/dnd.md), and [D&D integration contracts](integrations/) | The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes. | | Production modules or validators | [Module Internals](internal/modules.md), [D&D Module Internals](internal/dnd.md), and [D&D integration contracts](integrations/) | The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes. |
| LLM clients, prompts, schemas, profiles, or scheduling | [LLM Runtime](internal/llm.md) | It documents the transport boundary and PromptKit integration. | | Native execution, prompts, schemas, profiles, or admission | [LLM Integration](internal/llm.md) | It locates shared engine construction, native request/continuation calls, and evidence hooks. |
| Output, cache, resume, or debug artifacts | [Run State Internals](internal/state.md), [Operations](operations.md), and [Configuration](config.md) | These separate implementation details, operator behavior, and configuration contracts. | | Kit API, source handoff, or standard-suite integration | [ConfigKit](integrations/pkg-configkit.md), [PromptKit](integrations/pkg-promptkit.md), and [CommandKit](integrations/pkg-commandkit.md) | These define the selected upstream integration boundaries and link pinned native contracts. |
| Output, accepted-result reuse, or debug artifacts | [Run State Internals](internal/state.md), [Operations](operations.md), and [Configuration](config.md) | These separate implementation details, operator behavior, and configuration contracts. |
| External input formats, artifact schemas, or durable output files | [Integration Contracts](integrations/) | Integration documents define external and durable data contracts. | | External input formats, artifact schemas, or durable output files | [Integration Contracts](integrations/) | Integration documents define external and durable data contracts. |
| Repository-specific release commands or diagnostics | [Source Releases](release.md) | The runbook supplies publication commands and recovery procedures. | | Repository-specific release commands or diagnostics | [Source Releases](release.md) | The runbook supplies publication commands and recovery procedures. |
| Proposed or unimplemented behavior | [Native migration roadmap](roadmap/promptkit.md) and [separate backlog](roadmap/future.md) | The master roadmap owns the native cutover; the backlog holds other future work. Implemented behavior belongs in its canonical documentation. | | Implementation status or future scope | [Implementation plan](roadmap/implementation.md), [native migration target](roadmap/promptkit.md), and [separate backlog](roadmap/future.md) | The plan records verified work and remaining acceptance; the target owns cutover requirements and the backlog keeps other work separate. Implemented behavior belongs in canonical documentation. |
For an existing subsystem, also inspect its focused tests and the package-local For an existing subsystem, also inspect its focused tests and the package-local
types and contracts before changing behavior. types and contracts before changing behavior.

View File

@@ -34,7 +34,7 @@ array. This minimal document is valid:
``` ```
The maintained two-segment input is The maintained two-segment input is
[seriatim-minimal-transcript.json](../../examples/seriatim-minimal-transcript.json). [minimal transcript](../../examples/dnd-minimal/transcript.json).
| Field | Required | Meaning and constraints | | Field | Required | Meaning and constraints |
| --- | --- | --- | | --- | --- | --- |

View File

@@ -1,62 +1,64 @@
# Internal Overview # Internal Overview
This document is the implemented component map for Notarius. Normative This is the implemented component map, not an architecture policy or public
boundaries and dependency direction belong in reference. [Architecture](../policy/architecture.md) owns normative boundaries;
[Architecture](../policy/architecture.md). User and operator contracts belong [CLI](../cli.md), [Configuration](../config.md), [Operations](../operations.md),
in the [CLI](../cli.md), [Configuration](../config.md), and [integration contracts](../integrations/) own public behavior.
[Operations](../operations.md), and [integration contracts](../integrations/).
## Execution Path ## Execution Path
~~~ ```text
cmd/notarius -> internal/cli -> configuration and production composition cmd/notarius -> internal/cli: native commands, one selected config result/engine
-> internal/framework/pipeline -> logical output files -> resolve + offline preflight + materialize + typed preparation
-> internal/cli -> durable output and optional state/debug data -> 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 The executable supplies build identity. The composition root owns native command
production registries and runtime collaborators, invokes the framework, and declarations, source acquisition, registrars, shared engine, and physical state.
places returned files. The framework resolves and prepares a fixed extraction The framework and modules receive explicit collaborators/data rather than process
pipeline, then returns logical results without owning process behavior or streams or roots. Standard inspection/preflight paths do not become runs.
physical state roots.
## Components ## Components
| Area | Implemented owners | Responsibility | | 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. | | 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** | Resolves a stable linked release tag or build metadata for the diagnostic root version command. | | Build information | [internal/buildinfo](../../internal/buildinfo/) | Linked release or build metadata supplied to the native version command. |
| Configuration | **internal/core/config** | ConfigKit document definition, source-aware normalization, runtime conversion, structural validation, safe inspection, effective resolution, and resolved-composition redaction. | | 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 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. | | 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** | Registries, profile and reference resolution, typed preparation, validation, retry coordination, ordered execution, handoff, and result assembly. | | 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. |
| 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. | | 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** | 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). | | 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 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). | | Embedded content | [assets](../../assets/) | Content-only native prompt/profile/schema/message files imported with filesystem contexts; no behavioral registry. |
| 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. | | 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. |
| 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. | | 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. Native PromptKit requests/results/continuation/observations cross the intentional
Concrete extensions depend inward on their contracts and are registered only at model-execution boundary directly. There is no private LLM adapter/scheduler,
the CLI composition boundary. 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 ## Focused Documentation
- [Configuration Internals](configuration.md): loading, validation, effective - [Configuration Internals](configuration.md): definition, original result handoff,
resolution, redaction, and resolved-composition identity. captured contexts, runtime conversion, and selection reuse.
- [CLI Internals](cli.md): command dispatch, production composition, run - [CLI Internals](cli.md): lazy declarations, suite/registrar wiring, ordered run
orchestration, and terminal reporting. composition, and native outcomes.
- [Pipeline Internals](pipeline.md): resolution, preparation, execution, - [Pipeline Internals](pipeline.md): typed assessment/continuation, workers,
validation, typed handoff, and framework state hooks. handoffs, eligibility, and logical output.
- [Run State Internals](state.md): output, cache, debug collaborator - [Run State Internals](state.md): accepted-result store/prepared handles,
composition, and path safety. publication, capture, and failure retention.
- [LLM Runtime](llm.md): structured completion, scheduling, prompt assets, - [LLM Integration](llm.md): shared native engine, request/validator boundaries,
profiles, and secret handling. prompt/schema selection, and observations.
- [Module Internals](modules.md): generic extension registration, artifact - [Module Internals](modules.md) and [D&D Module Internals](dnd.md): typed extension
families, module construction, semantic reconciliation, validation, and recipes, fixed normalization inputs, contextual identity/evidence, and domain exceptions.
reference mechanics. - [ConfigKit](../integrations/pkg-configkit.md), [PromptKit](../integrations/pkg-promptkit.md),
- [D&D Module Internals](dnd.md): shared D&D extractor conventions, generated and [CommandKit](../integrations/pkg-commandkit.md) integration contracts: selected
reference projections, and lane-specific exceptions. Durable D&D and native public APIs, source/command handoffs, and pinned upstream references.
Seriatim data shapes remain in the [integration contracts](../integrations/).
Use this map to find an owner, then read the focused document and its tests Use this map to find an owner, then inspect its focused source/tests.
before changing behavior. [Development](../development.md) owns contributor reading and validation guidance.

View File

@@ -7,12 +7,18 @@ PromptKit/ConfigKit/CommandKit adoption, continuation, admission, cache, output,
and debug decisions. Items below are ordered roughly by value and specificity, and debug decisions. Items below are ordered roughly by value and specificity,
not as committed release dates or prerequisites for that migration. not as committed release dates or prerequisites for that migration.
Native shared loading/commands, complete assessment/continuation, concurrent
ready lane completion, accepted-result reuse, and private capture are implemented;
see the [implementation evidence](implementation.md) for final acceptance status.
They are not deferred platform work. Human model-quality evaluation, broader
reference/context policies, and storage/distribution extensions below remain separate.
## Near-Term D&D Pipeline ## Near-Term D&D Pipeline
### Evaluate Spell Extraction And Normalization ### Evaluate Spell Extraction And Normalization
- Evaluate extraction, normalization, and correction quality against a - Evaluate extraction, normalization, and correction quality against a
human-reviewed transcript set before and after the native migration. human-reviewed transcript set, comparing retained baselines with the native path.
- Maintain a small set of human-reviewed transcripts and outputs for prompt, - Maintain a small set of human-reviewed transcripts and outputs for prompt,
validator, and normalizer development. Treat model-quality review as an validator, and normalizer development. Treat model-quality review as an
iterative human evaluation aid, not a deterministic correctness gate. iterative human evaluation aid, not a deterministic correctness gate.
@@ -78,9 +84,9 @@ The sections below keep broader extensions deferred.
benefits from model judgment and deterministic checks are insufficient. benefits from model judgment and deterministic checks are insufficient.
- Consider additional validator diagnostic views only if a concrete need remains - Consider additional validator diagnostic views only if a concrete need remains
after the selected [native observations and debug capture](promptkit.md#inspection-and-execution-bookkeeping). after the selected [native observations and debug capture](promptkit.md#inspection-and-execution-bookkeeping).
- Add validator compatibility metadata if deployments need config-time proof - Existing typed resolution already checks validator target, artifact kind,
that a validator is suitable for a particular stage, module, or artifact and exact Go-type compatibility. Add further semantic suitability metadata
kind. only if a deployment needs a contract beyond those implemented checks.
- Add media-type validators when non-JSON artifact representations are - Add media-type validators when non-JSON artifact representations are
introduced. introduced.
@@ -88,8 +94,9 @@ The sections below keep broader extensions deferred.
- Make prior-run artifacts easier to bind as references without changing the - Make prior-run artifacts easier to bind as references without changing the
existing module-facing reference-item contract. existing module-facing reference-item contract.
- Add structured or parsed references, such as typed NPC registries, rosters, - Existing registry/catalog consumers already parse and validate typed contextual
or spell catalogs, when opaque UTF-8 prompt material is no longer sufficient. projections. Consider a framework-level parsed-reference facility only when
concrete consumers need shared behavior beyond those module-owned resolvers.
- Add per-slot or per-chunk inclusion policies so large references are not - Add per-slot or per-chunk inclusion policies so large references are not
repeated in every prompt unnecessarily. repeated in every prompt unnecessarily.
- Add token budgeting and model context-window management for reference - Add token budgeting and model context-window management for reference
@@ -146,7 +153,8 @@ section only after a concrete workflow, contract, and priority emerge.
- Additional input adapters, such as Markdown or note-export formats. - Additional input adapters, such as Markdown or note-export formats.
- Additional output encoders. - Additional output encoders.
- Concurrent cross-lane entity normalization or broader workflow composition. - Broader workflow composition only when a concrete need justifies revisiting
the fixed-shape pipeline decision; ready cross-lane completion already runs concurrently.
- Batching or specialized context-window controls for LLM-backed validators. - Batching or specialized context-window controls for LLM-backed validators.
### Distribution And Operations ### Distribution And Operations

View File

@@ -5,9 +5,10 @@
Implement the complete target in [Native PromptKit And CommandKit Migration](promptkit.md). Implement the complete target in [Native PromptKit And CommandKit Migration](promptkit.md).
That feature roadmap owns product choices, defaults, ownership, and acceptance That feature roadmap owns product choices, defaults, ownership, and acceptance
semantics. This document owns execution order and stage completion. Completion semantics. This document owns execution order and stage completion. Completion
markers below record finished stages. The inspected application baseline is Notarius commit markers below record finished stages. The inspected pre-migration application
`b3664d587914b1d7b0377f25fa377b57fa97c815`; its recent roadmap commits have not baseline was Notarius commit `b3664d587914b1d7b0377f25fa377b57fa97c815`.
implemented the migration. The completed stages below record the landed implementation and checks;
the final whole-roadmap acceptance audit remains pending until Stage 46.
Each numbered stage is one implementation prompt for a Luna coding agent. Each numbered stage is one implementation prompt for a Luna coding agent.
Execute stages in integer order as one end-to-end sprint. Intermediate stages Execute stages in integer order as one end-to-end sprint. Intermediate stages
@@ -2187,6 +2188,30 @@ compare claims with Stage 37's assembled boundary tests.
## Stage 45: Refresh Orientation And Reconcile Planning Status ## Stage 45: Refresh Orientation And Reconcile Planning Status
**Status:** Complete. README now uses the maintained minimal configuration and
transcript with native required input syntax and links both examples, current
contracts, kit integration, and migration guidance. Updated contributor routing
and the internal package map for the shared native load/engine, preflight, typed
producer/assessment, ready workers, accepted-result store, evidence, and recorder;
removed navigation to deleted adapter/reporting/checkpoint packages.
Reconciled backlog wording for implemented compatibility checks, typed reference
projections, and concurrent lane completion while retaining human quality review,
larger reconciliation/context, distribution, and storage work separately. The
feature roadmap now distinguishes implemented choices/evidence from the still
pending final acceptance audit; retained its target/removal/acceptance scope and
historical baseline/comparison. Native library navigation is release-pinned.
Found and repaired one current Seriatim fixture link during the stale-name search.
Both actual example pipelines pass direct offline preflight with credentials
unset; maintained minimal/complete/development example and shared-reference tests
pass using native provider fakes. All 149 local links/anchors and 16 selected
upstream destinations/anchors in the changed documents resolve; eleven dated
Audita comparison links remain classified historical evidence, not current owner
navigation. Current-doc/example removal searches leave only explicit migration
guidance; `git diff --check` passes. No code, schema, release, archive, or runtime
data changed. Stage 46 and full-goal acceptance remain unmarked/pending.
**Goal:** entry points lead to current docs and preserve separate future scope. **Goal:** entry points lead to current docs and preserve separate future scope.
**Inspect/change:** `docs/internal/overview.md`, `docs/development.md`, `README.md`, **Inspect/change:** `docs/internal/overview.md`, `docs/development.md`, `README.md`,

View File

@@ -13,8 +13,12 @@ accepted-artifact caching, and artifact-first output. It owns the selected targe
decision status, removal inventory, acceptance criteria, and supporting evidence. decision status, removal inventory, acceptance criteria, and supporting evidence.
The earlier discussion documents are retired; Git history preserves the discussion. The earlier discussion documents are retired; Git history preserves the discussion.
The [implementation plan](implementation.md) owns the ordered, prompt-sized stages. The [implementation plan](implementation.md) owns the ordered, prompt-sized stages.
The migration is pending; recording these decisions has not changed application The native cutover and canonical documentation are implemented, with completion
behavior. Unrelated future work remains in the [separate backlog](future.md). evidence recorded in that plan. The final whole-roadmap acceptance audit remains
pending; implementation markers do not substitute for that verification.
Current behavior belongs in [Configuration](../config.md), [CLI Reference](../cli.md),
[Operations](../operations.md), and [native migration guidance](../consumers/native-migration.md).
Unrelated future work remains in the [separate backlog](future.md).
Notarius predates many modern PromptKit capabilities: the library grew out of Notarius predates many modern PromptKit capabilities: the library grew out of
mechanics shared by Notarius and related applications. Historical duplication mechanics shared by Notarius and related applications. Historical duplication
@@ -36,7 +40,7 @@ adapters while those boundaries are already being replaced.
## Baseline And Dependency Target ## Baseline And Dependency Target
At Notarius revision `12eeb6369e40746b2c18c55397a289a1e1b5908d`, the application At Notarius revision `12eeb6369e40746b2c18c55397a289a1e1b5908d`, the application
uses configuration version 5 and Go 1.27. Its dependencies include old-path used configuration version 5 and Go 1.27. Its dependencies included old-path
PromptKit v0.12.0 and ConfigKit v0.5.0, new-path ConfigKit v1.2.0, go-yaml PromptKit v0.12.0 and ConfigKit v0.5.0, new-path ConfigKit v1.2.0, go-yaml
v4.0.0-rc.6, and two external PromptKit provider catalogs. v4.0.0-rc.6, and two external PromptKit provider catalogs.
@@ -56,9 +60,10 @@ Published tags and dependency manifests were verified, and the modules resolved
together without local replacements in an isolated consumer module. Maintained together without local replacements in an isolated consumer module. Maintained
composed-CLI and offline-preparation examples and focused message-hash, composed-CLI and offline-preparation examples and focused message-hash,
configuration-handoff, and schema tests passed without live provider calls. configuration-handoff, and schema tests passed without live provider calls.
These checks verify the upstream combination, not the unfinished Notarius Those checks established the upstream baseline; subsequent Notarius implementation
migration. See the evidence is recorded in the plan, with final acceptance pending. See the
[integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection) [current integration boundary](../integrations/pkg-commandkit.md) and
[integration version guidance](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md#module-selection)
and tagged [release notes][release], [migration guide][migration], and tagged [release notes][release], [migration guide][migration],
[format reference][formats], and [Go consumer guide][consumer]. [format reference][formats], and [Go consumer guide][consumer].
@@ -152,8 +157,9 @@ can be refined against representative extraction and normalization during
implementation; ownership and placement are settled. U4 selects prompt roles and implementation; ownership and placement are settled. U4 selects prompt roles and
guidance ownership below; U5 selects retry controls and the correction budget. guidance ownership below; U5 selects retry controls and the correction budget.
U6 selects strict-by-default handling and module-owned fallbacks below; U6 selects strict-by-default handling and module-owned fallbacks below;
configuration precedence and fallback behavior are resolved. Implementation is configuration precedence and fallback behavior are implemented. See
pending. [Pipeline Internals](../internal/pipeline.md) and the plan's completed operation/
module work; final acceptance remains pending.
Retain the fixed `input -> chunk -> extract -> merge -> normalize -> output` Retain the fixed `input -> chunk -> extract -> merge -> normalize -> output`
shape, ordered steps and generated references, typed artifact-family boundaries, shape, ordered steps and generated references, typed artifact-family boundaries,
@@ -431,7 +437,8 @@ contracts. Retire private schema keys, registration records, hashes, and copied
identity/version/name metadata whose only consumers were adapters, checkpoints, identity/version/name metadata whose only consumers were adapters, checkpoints,
or reporting. No independent schema metadata system replaces them. or reporting. No independent schema metadata system replaces them.
Implementation is pending. Verify native preparation of embedded and operator Native preparation is implemented and covered by asset/operator-schema tests
recorded in the plan. Final verification must confirm embedded and operator
prompt definitions, shared-file paths, schema selection from embedded and external prompt definitions, shared-file paths, schema selection from embedded and external
roots, source-relative/inline selection, and complete request-contract replacement roots, source-relative/inline selection, and complete request-contract replacement
where actually used. Missing or invalid schemas follow native preparation where actually used. Missing or invalid schemas follow native preparation
@@ -519,8 +526,9 @@ apply U6's strict/permissive handling when no acceptable result is obtained.
Ownership, response contracts, and default profile behavior are resolved. Refine Ownership, response contracts, and default profile behavior are resolved. Refine
exact template prose, correction IDs, and necessary operation-specific inputs exact template prose, correction IDs, and necessary operation-specific inputs
while implementing representative workflows. Implementation is pending; U5 selects within implemented module boundaries. The plan records producer/prompt/assessment
semantic budgets and U6 selects strict-by-default terminal handling and fallbacks. coverage; final verification remains pending. U5 selects semantic budgets and U6
selects strict-by-default terminal handling and fallbacks.
#### Execution And Assessment Flow #### Execution And Assessment Flow
@@ -647,7 +655,8 @@ for semantic correction becomes `max_additional_turns`; native transport control
and prompt-owned structural customization cover their own concerns. Remove and prompt-owned structural customization cover their own concerns. Remove
non-LLM retry settings without a replacement generic allowance. Do not promise non-LLM retry settings without a replacement generic allowance. Do not promise
equivalent total provider-attempt counts. U5 is resolved; U6 selects strict-by-default equivalent total provider-attempt counts. U5 is resolved; U6 selects strict-by-default
handling and module-owned fallbacks. Implementation is pending. handling and module-owned fallbacks. Native producer/assessment integration and
removal of outer retries are implemented; see the plan's completion evidence.
#### Terminal Outcomes And Module Fallbacks (U6 Resolved) #### Terminal Outcomes And Module Fallbacks (U6 Resolved)
@@ -809,7 +818,8 @@ new shared limit, but its scope now includes lane completion. Do not automatical
translate a cross-backend ceiling into per-backend limits or preserve worker translate a cross-backend ceiling into per-backend limits or preserve worker
inheritance/caps from that field. Provide a native limited-backend example with inheritance/caps from that field. Provide a native limited-backend example with
usable queue capacity, without requiring operators to override the upstream usable queue capacity, without requiring operators to override the upstream
queue default. U7 is resolved; implementation remains pending. queue default. U7 is implemented with focused worker/admission and assembled
coverage recorded in the plan; final acceptance remains pending.
### Accepted-Artifact Cache (U8 Resolved) ### Accepted-Artifact Cache (U8 Resolved)
@@ -955,8 +965,8 @@ source partition to request-content-based plan reuse.
Remove checkpoint identities, dependency fingerprints, invocation-wide barriers, Remove checkpoint identities, dependency fingerprints, invocation-wide barriers,
recovery bookkeeping, and the separate canonical-plan lookup/publication policy. recovery bookkeeping, and the separate canonical-plan lookup/publication policy.
Retain domain plan interpretation and materialization without retaining a second Retain domain plan interpretation and materialization without retaining a second
cache mechanism. U8 is resolved; implementation remains pending using U1's cache mechanism. U8 is implemented using U1's selected upstream hash capability;
selected upstream hash capability. store, producer/plan, and assembled recovery coverage is recorded in the plan.
### Inspection And Execution Bookkeeping ### Inspection And Execution Bookkeeping
@@ -1219,29 +1229,32 @@ support, applicability, and outcome distinctions.
## Decision Status ## Decision Status
U1–U10 are resolved. There are no remaining open architectural or dependency U1–U10 are resolved. There are no remaining open architectural or dependency
choices in this roadmap. Observer wiring, debug filenames, routine API placement, choices in this roadmap. Native loading/execution/commands, accepted-result reuse,
and serialization details remain implementation work within the selected designs. artifact-first reporting, capture, examples, and documentation are implemented.
IDs retain continuity with the earlier roadmap. Implementation status and ordered Observer wiring, private debug representations, and routine API placement are
stages are tracked in the [implementation plan](implementation.md). concrete implementation choices, not deferred architecture. The final assembled
acceptance/removal/link audit remains pending in the [implementation plan](implementation.md).
IDs retain continuity with the earlier roadmap.
**U1 resolved:** The [reviewed dependency set](#baseline-and-dependency-target) **U1 resolved:** The [reviewed dependency set](#baseline-and-dependency-target)
selects PromptKit v0.24.0, ConfigKit v1.4.0, ckconfig v0.10.0, ckprompt v0.11.0, selects PromptKit v0.24.0, ConfigKit v1.4.0, ckconfig v0.10.0, ckprompt v0.11.0,
and CommandKit v0.7.0. Native `MessageContentHash` satisfies the cache requirement; and CommandKit v0.7.0. Native `MessageContentHash` satisfies the cache requirement;
typed result handoff and focused inspection enable one application-owned load. typed result handoff and focused inspection enable one application-owned load.
The native resource layout, schema selections, and `OutputContractInput` The native resource layout, schema selections, and `OutputContractInput`
API are part of the selected target. Upstream combination checks API are implemented. Upstream and focused assembled checks passed as recorded
passed; assembled Notarius acceptance remains implementation work. in the plan; the final full acceptance audit remains pending.
**U2 resolved:** Ordinary embedded assets, prompt-declared output contracts, **U2 resolved:** Ordinary embedded assets, prompt-declared output contracts,
native schema-source selection, and removal of duplicate schema/filesystem native schema-source selection, and removal of duplicate schema/filesystem
machinery are selected in [the schema design](#prompt-assets-and-response-schemas-u2-resolved). machinery are selected in [the schema design](#prompt-assets-and-response-schemas-u2-resolved).
Implementation remains pending; U4 selects prompt roles and contracts, and U5 The native assets and schema selection are implemented with preparation and
operator-contract coverage in the plan. U4 selects prompt roles/contracts, and U5
selects native repair delegation and the application correction allowance. selects native repair delegation and the application correction allowance.
**U3 resolved:** Typed stage boundaries, composition-root engine construction, **U3 resolved:** Typed stage boundaries, composition-root engine construction,
and the shared pipeline producer helper with module functions and a pipeline and the shared pipeline producer helper with module functions and a pipeline
assessment callback are selected in [the execution design](#module-execution-and-assessment-u3-resolved). assessment callback are selected in [the execution design](#module-execution-and-assessment-u3-resolved).
Concrete signatures remain implementation details within that ownership. The typed operation/helper signatures are implemented within that ownership.
U4/U5 select prompt/guidance and retry behavior; U6 selects terminal U4/U5 select prompt/guidance and retry behavior; U6 selects terminal
handling, configuration precedence, and module-owned fallbacks. handling, configuration precedence, and module-owned fallbacks.
@@ -1249,8 +1262,8 @@ handling, configuration precedence, and module-owned fallbacks.
schemas, default profile behavior, validator-owned guidance, and complete schemas, default profile behavior, validator-owned guidance, and complete
applicable-chain assessment are selected in applicable-chain assessment are selected in
[the prompt and guidance design](#prompt-roles-and-correction-guidance-u4-resolved). [the prompt and guidance design](#prompt-roles-and-correction-guidance-u4-resolved).
Exact template prose and operation-specific inputs remain implementation work Native prompt pairs and operation-specific inputs are implemented within that
within that ownership. U5 selects budgets; U6 selects strict/permissive handling. ownership. U5 selects budgets; U6 selects strict/permissive handling.
**U5 resolved:** `max_additional_turns` defaults to `2`, with binding over **U5 resolved:** `max_additional_turns` defaults to `2`, with binding over
pipeline precedence and explicit zero disabling correction. Native transient and pipeline precedence and explicit zero disabling correction. Native transient and
@@ -1269,7 +1282,8 @@ application default, including normalization; there are no module-declared
defaults. `mode` resolves module binding, then pipeline, then that default. defaults. `mode` resolves module binding, then pipeline, then that default.
Chunking falls back to one whole-transcript chunk; spell extraction uses its empty Chunking falls back to one whole-transcript chunk; spell extraction uses its empty
artifact, and normalization uses safe final-response groups or merged input. artifact, and normalization uses safe final-response groups or merged input.
Module-specific construction details remain implementation work. Module-owned construction and terminal-mode coverage are implemented; see the
plan and [D&D guide](../internal/dnd.md#planning-scene-validation-and-fallback-limits).
**U7 resolved:** [One pipeline worker pool and native admission](#admission-and-pipeline-workers-u7-resolved) **U7 resolved:** [One pipeline worker pool and native admission](#admission-and-pipeline-workers-u7-resolved)
replace the separate worker pools and application LLM scheduler. replace the separate worker pools and application LLM scheduler.
@@ -1297,10 +1311,11 @@ fallbacks. Preserve run-specific domain artifact paths and schemas; retire index
manifest, and reporting-only sidecars and migrate consumers to documented paths. manifest, and reporting-only sidecars and migrate consumers to documented paths.
Observer wiring and [debug filenames/layout](#inventory-and-depth) are explicitly Observer wiring and [debug filenames/layout](#inventory-and-depth) are explicitly
implementation choices, not unresolved architecture or stable debug contracts. implementation choices, not unresolved architecture or stable debug contracts.
Implementation remains pending. Implemented native observations/capture/publication and reporting tests are
recorded in the plan; final acceptance remains pending.
**U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight, **U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight,
output, debug policy, and coordinated cutover sequencing are selected above. output, and debug policy are implemented as selected above.
CommandKit belongs to the coordinated cutover. CLI compatibility is a non-goal; CommandKit belongs to the coordinated cutover. CLI compatibility is a non-goal;
existing artifact schemas remain domain contracts. Any actual artifact-format existing artifact schemas remain domain contracts. Any actual artifact-format
change discovered during implementation needs an explicit compatibility decision, change discovered during implementation needs an explicit compatibility decision,
@@ -1444,22 +1459,22 @@ tagged PromptKit links below preserve the reviewed baseline.
### Native Library Guidance ### Native Library Guidance
- [CommandKit consumer guide](../../../commandkit/docs/consumers/guide.md) and - [CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md) and
[CLI conventions](../../../commandkit/docs/cli.md): module selection, native [CLI conventions](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md): module selection, native
aliases/inputs, shared loaders, reporting modes, outcomes, and delivery failures. aliases/inputs, shared loaders, reporting modes, outcomes, and delivery failures.
- [ckconfig](../../../commandkit/integrations/ckconfig/README.md) and - [ckconfig](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/README.md) and
[ckprompt](../../../commandkit/integrations/ckprompt/README.md): standard suites [ckprompt](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/README.md): standard suites
supplied with application loaders and request builders. supplied with application loaders and request builders.
- [ConfigKit v1.4.0 release notes][configkit-release]: typed result handoff and - [ConfigKit v1.4.0 release notes][configkit-release]: typed result handoff and
focused inspection over the original load's provenance and resource contexts. focused inspection over the original load's provenance and resource contexts.
- [ckconfig v0.10.0][ckconfig-release] and [ckprompt v0.11.0][ckprompt-release]: - [ckconfig v0.10.0][ckconfig-release] and [ckprompt v0.11.0][ckprompt-release]:
the selected integration compatibility and API changes. the selected integration compatibility and API changes.
- [Shared-loading guidance][consumer-loading] and the - [Shared-loading guidance][consumer-loading] and the
[composed CLI example](../../../commandkit/integrations/ckprompt/examples/composed/main.go): [composed CLI example](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/examples/composed/main.go):
composed rules, explicit bundled resources, one application result, native composed rules, explicit bundled resources, one application result, native
engine construction, and focused standard scopes. engine construction, and focused standard scopes.
- [PromptKit consumer guide][consumer] and - [PromptKit consumer guide][consumer] and
[capacity behavior](../../../promptkit/docs/internal/capacity.md): native [capacity behavior](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/internal/capacity.md): native
preparation/execution, continuation, observations, and admission. preparation/execution, continuation, observations, and admission.
### Audita Comparison ### Audita Comparison
@@ -1494,5 +1509,5 @@ completion of Notarius's migration acceptance checks.
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md [consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[consumer-loading]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load [consumer-loading]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load
[configkit-release]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md [configkit-release]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md
[ckconfig-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/docs/releases/v0.10.0.md [ckconfig-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/docs/releases/v0.10.0.md
[ckprompt-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/docs/releases/v0.11.0.md [ckprompt-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/docs/releases/v0.11.0.md