185 Commits
v0.8.1 ... main

Author SHA1 Message Date
7faa4a0506 Remove completed planning documents 2026-11-22 09:51:45 +00:00
f069a10c78 Assemble lane results in chunk order without sorting 2026-11-22 09:49:08 +00:00
c8250089b1 Index debug sensitivity paths once per capture 2026-11-22 09:43:22 +00:00
80148ef7e4 Share a lazy source index across cache hits 2026-11-22 09:42:06 +00:00
2429f0ae6a Index source positions during chunk plan validation 2026-11-22 09:40:42 +00:00
7ee7b997f0 Remove unused legacy LLM error definitions 2026-11-22 09:39:50 +00:00
dd25838589 Keep long fallback reasons from invalidating warnings 2026-11-22 09:38:24 +00:00
9074547e33 Keep cached scene identities aligned with the current plan 2026-11-22 09:37:16 +00:00
8ea96dc7a4 Clarify validation behavior when chains are replaced 2026-11-22 09:32:32 +00:00
581229cd1f Preserve operational timeouts when selecting run failures 2026-11-22 09:32:16 +00:00
e823baf3af Record algorithmic scaling opportunities 2026-11-22 09:28:59 +00:00
fdaf39162b Record native migration integration gaps 2026-11-22 09:00:55 +00:00
fd134e85e5 Record the native migration review findings 2026-11-22 08:15:09 +00:00
75444b8ef3 Verify the native cutover and complete the implementation roadmap 2026-11-22 07:11:50 +00:00
633ebd282f Refresh native workflow orientation and planning status 2026-11-22 06:57:27 +00:00
b76d511571 Document native kit integration contracts and ownership 2026-11-22 06:52:56 +00:00
aa4ce04683 Refresh typed module and D&D contributor recipes 2026-11-22 06:48:55 +00:00
41f6079040 Refresh pipeline execution and run state internal guides 2026-11-22 06:45:28 +00:00
5db09d0203 Refresh native configuration, CLI, and LLM internal guides 2026-11-22 06:41:22 +00:00
2c27695df9 Update native operations, consumer migration, and version checks 2026-11-22 06:32:22 +00:00
5e58327032 Rewrite configuration and CLI references for native commands 2026-11-22 06:20:54 +00:00
3cf389db78 Record native architecture decisions and align ownership policy 2026-11-22 06:11:57 +00:00
5b6854e975 Verify native recovery, fallback reuse boundaries, and operator schemas 2026-11-22 06:00:52 +00:00
854d23b91e Migrate maintained D&D examples to native configuration 2026-11-22 05:45:31 +00:00
3ef55f4668 Finish native migration cleanup and restore whole-tree compilation 2026-11-22 05:37:15 +00:00
4fa437aee8 Migrate ordered enemy event contracts to native providers 2026-11-22 05:29:48 +00:00
936fc1e72a Migrate run state and reference contracts to native execution 2026-11-22 05:24:30 +00:00
5cfcf10a8b Migrate configuration and command tests to native inspection 2026-11-22 05:16:24 +00:00
21bcb4eb3b Migrate assembled spell and catalog contracts to native correction 2026-11-22 05:07:00 +00:00
5e68b74469 Exercise production CLI contracts through native loaders and providers 2026-11-22 05:01:09 +00:00
572b267c5d Migrate combat and grounded pipeline integration tests to native execution 2026-11-22 04:54:27 +00:00
562dfad5cd Migrate ordered NPC and location handoff tests to native execution 2026-11-22 04:45:39 +00:00
0ad73ff575 Exercise spell and NPC integration through native providers and published artifacts 2026-11-22 04:39:55 +00:00
20c0975d9d Move cross-family runner contracts into module integration tests 2026-11-22 04:33:28 +00:00
93d94fdd0a Migrate framework tests to native producer and artifact contracts 2026-11-22 04:28:48 +00:00
0b46f2d37c Remove retired runtime wrappers and persistent cache machinery 2026-11-22 04:19:23 +00:00
a8d256f676 Report completed runs through native presentation and preserve failure outcomes 2026-11-22 04:05:44 +00:00
0cbc2b39cb Wire native pipeline run commands and invocation-wide overrides 2026-11-22 03:51:08 +00:00
2a9c5a6075 Add offline pipeline inspection and shared native resource preflight 2026-11-22 03:32:31 +00:00
9f66421f4f Capture native execution facts and complete scoped debug evidence 2026-11-22 03:19:43 +00:00
8680060400 Record debug evidence in one run-scoped capture session 2026-11-22 02:49:48 +00:00
584b041e57 Publish domain artifacts without reporting sidecars 2026-11-22 02:34:40 +00:00
3b1b4c9bcf Unify chunk-plan caching and remove checkpoint execution paths 2026-11-22 02:24:45 +00:00
36906cb3d1 Cache final typed producer artifacts under the initial native request hash 2026-11-22 02:10:05 +00:00
3ef55b1cf0 Add a best-effort accepted-artifact filesystem cache 2026-11-22 01:52:21 +00:00
37e0753472 Format migrated worker fields in integration fixtures 2026-11-22 01:45:48 +00:00
9a527b77c4 Unify ready pipeline jobs under one worker pool and remove the global LLM scheduler 2026-11-22 01:45:31 +00:00
b47208bd57 Make production registration asset-free and verify direct deterministic execution 2026-11-22 01:35:23 +00:00
433ed420f8 Migrate scene descriptions to native correction with invariant-preserving final fallbacks 2026-11-22 01:26:49 +00:00
3fa593362d Migrate enemy events to native correction with fixed multi-artifact grounding 2026-11-22 01:20:46 +00:00
bb3153c1ad Migrate combat turns to native correction and retain deterministic scene gating 2026-11-22 01:13:57 +00:00
1fe231b6fb Migrate item occurrences to native correction while preserving holder semantics 2026-11-22 01:08:02 +00:00
2c1d727232 Migrate NPC and location occurrences to native correction and explicit empty fallbacks 2026-11-22 01:03:06 +00:00
303d6589c5 Migrate registry extraction to native correction and explicit empty fallbacks 2026-11-22 00:50:54 +00:00
5d3696d4a0 Migrate combat semantics validation to native execution and unavailable assessments 2026-11-22 00:42:20 +00:00
52a1c96327 Migrate scene planning to native continuation and whole-source fallback 2026-11-22 00:34:33 +00:00
4f82d01534 Migrate NPC and location normalization to native correction and explicit fallback handling 2026-11-22 00:27:34 +00:00
772b8619c1 Migrate item normalization to native correction and explicit fallback handling 2026-11-22 00:17:58 +00:00
2348730820 Separate reconciliation preparation and proposal assessment from native execution 2026-11-22 00:07:05 +00:00
92c2382806 Migrate spell extraction to native execution and semantic continuation 2026-11-22 00:02:13 +00:00
923cbe594f Bind runner assessment and propagate fallback reuse eligibility 2026-11-21 23:48:51 +00:00
44e4fb92c2 Run typed producers through native continuation and assessment 2026-11-21 23:30:45 +00:00
c56c7d7ee9 Centralize candidate assessment and explicit producer fallback handling 2026-11-21 23:20:17 +00:00
797320b4da Define typed producer assessment and native execution dependencies 2026-11-21 23:12:01 +00:00
b899ee32a6 Install native PromptKit diagnostics and reusable execution overrides 2026-11-21 23:02:57 +00:00
91869ba191 Compose native application commands and shared configuration scopes 2026-11-21 22:59:46 +00:00
a1c888d2cd Share one native application configuration load and captured engine 2026-11-21 22:56:14 +00:00
a0274e154b Declare embedded prompts profiles and schemas with native kit resources 2026-11-21 22:52:46 +00:00
87d362e2d7 Validate pipeline controls in the typed validation callback 2026-11-21 22:49:53 +00:00
40fbcc61b1 Resolve producer modes turn allowances cache controls and shared workers 2026-11-21 22:49:41 +00:00
cc14a7a5cc Load native PromptKit settings through application configuration version six 2026-11-21 22:42:35 +00:00
bd30e86c0d Select native kit releases and update dependency attribution 2026-11-21 22:39:39 +00:00
c480ad68a1 Plan the native PromptKit and CommandKit migration 2026-11-21 22:24:16 +00:00
b3664d5879 Clarify roadmap consistency before native implementation 2026-11-21 21:58:06 +00:00
3f51764f1e Update native migration roadmap for reviewed upstream releases 2026-11-21 21:51:23 +00:00
5359cba98d Resolve completion reporting and publication contracts 2026-11-21 02:36:14 +00:00
058703abe5 Resolve unified cache configuration and legacy migration 2026-11-20 18:59:02 +00:00
254401e5f6 Resolve shared worker pool and native admission policy 2026-11-20 17:32:50 +00:00
1292ed8c4b Resolve mode precedence and whole-transcript fallback 2026-11-20 16:19:23 +00:00
baec913ef5 Select strict mode as the universal pipeline default 2026-11-20 16:13:27 +00:00
89a5398771 Define strict and permissive outcomes with module fallbacks 2026-11-20 16:07:55 +00:00
498f468f4f Resolve removal of generic non-LLM retries 2026-11-20 15:38:21 +00:00
e737167730 Set semantic turn defaults and delegate structural repair upstream 2026-11-20 15:34:05 +00:00
b904021138 Resolve native correction prompts and validator guidance ownership 2026-11-20 14:42:26 +00:00
2d69c26813 Consolidate migration planning into the master roadmap 2026-11-20 13:06:52 +00:00
f883316d7a Resolve native module execution and pipeline assessment design 2026-11-20 12:57:33 +00:00
0833450c71 Resolve native prompt asset and schema design 2026-11-20 12:45:00 +00:00
2eaea2b1fd Consolidate the native migration roadmap and simplified cache design 2026-11-20 03:42:51 +00:00
c03d0bb987 Simplify the planned artifact output and completion report 2026-11-20 03:28:14 +00:00
305a88e8f4 Replace checkpoint proposals with accepted-artifact caching 2026-11-20 03:10:16 +00:00
98ba7e1f55 Define empty debug directory as disabling capture 2026-11-20 01:10:58 +00:00
1601b535ff Settle debug capture inventory and depth 2026-11-20 00:56:29 +00:00
cbf3d1acc2 Clarify settled CommandKit decisions and remaining choices 2026-11-20 00:51:58 +00:00
3c73ccfad0 Record CommandKit verification and migration plan 2026-11-20 00:48:29 +00:00
d9e1d1e4a7 Prioritize convenient debug representations 2026-11-19 19:07:57 +00:00
5618adea8e Record debug bundle organization and latest symlink 2026-11-19 18:55:24 +00:00
9c4c2fc88d Select temporary debug directory default 2026-11-19 18:47:12 +00:00
d11d379bd4 Clarify debug defaults and operator data handling 2026-11-19 18:38:43 +00:00
a299869fcc Record conditional debug capture and diagnostic design 2026-11-19 18:27:51 +00:00
27081bc0af Record native reporting machine output and outcomes 2026-11-19 18:13:08 +00:00
6fa520f8f3 Record native composition loaders and preflight design 2026-11-19 18:05:41 +00:00
5cdbc5400f Record native run alias for pipeline execution 2026-11-19 17:47:40 +00:00
b038cc1a59 Record native pipeline commands and input conventions 2026-11-19 16:19:48 +00:00
93dd406459 Record CommandKit versions and standard capability scope 2026-11-19 16:04:23 +00:00
b04fe98c9e Record full CommandKit-native CLI cutover direction 2026-11-19 15:55:46 +00:00
8feece01db Start CommandKit migration discussion notepad 2026-11-19 15:51:31 +00:00
d17d261d62 Rewrite roadmap for PromptKit-native architecture 2026-11-19 15:27:08 +00:00
12eeb6369e Record simpler PromptKit-native application design 2026-11-19 15:17:38 +00:00
3fb8cb7392 Record inspection and execution bookkeeping ownership 2026-11-19 14:59:56 +00:00
3e1abc7fbb Record simpler checkpoint reuse policy 2026-11-19 14:49:36 +00:00
40cd4fe97d Record agreement to retire the global LLM scheduler 2026-11-18 20:04:48 +00:00
ae8e3ec698 Record agreement on native continuation and retry ownership 2026-11-18 19:54:55 +00:00
8fb21b7dae Record native continuation direction and retry simplifications 2026-11-18 19:48:00 +00:00
5a527c789d Record Audita PromptKit workflow review and architectural implications 2026-11-18 19:10:53 +00:00
abecb349e4 Record agreement on native prompt assembly and deferred schema decisions 2026-11-18 19:04:45 +00:00
defe123955 Outline native PromptKit asset assembly for discussion 2026-11-18 19:00:55 +00:00
69c4054eea Record the PromptKit-native architectural direction 2026-11-18 18:58:21 +00:00
af250eb72f Add PromptKit architecture discussion notepad 2026-11-18 18:52:49 +00:00
0ef079610e Defer operator diagnostics to CommandKit 2026-11-18 18:38:34 +00:00
d1d2394729 Define the offline preflight boundary 2026-11-18 15:28:38 +00:00
63e26dc203 Use PromptKit companion files and namespaced defaults 2026-11-18 15:21:56 +00:00
fe44b12073 Draft the PromptKit upgrade roadmap 2026-11-18 15:09:05 +00:00
65b8e8f0a2 Retire the completed ConfigKit upgrade plans 2026-11-18 14:31:30 +00:00
76364a7b7e Cache source directories during configuration normalization 2026-11-18 00:36:26 +00:00
1c93aa0947 Verify record inheritance through pipeline resolution 2026-11-18 00:32:13 +00:00
1febd2edfa Clarify native imported step ordering 2026-11-18 00:31:11 +00:00
5e269f9760 Distinguish mapping and record inheritance syntax 2026-11-18 00:30:57 +00:00
fb58aef8c2 Restore the accepted workload profile decision text 2026-11-18 00:30:41 +00:00
3f9727d5e8 Clarify PromptKit capture and preparation behavior 2026-11-18 00:30:24 +00:00
0663fe566a Validate explanation pointers before loading configuration 2026-11-18 00:29:56 +00:00
347ef05b41 Compose application assets in one strict group 2026-11-18 00:28:45 +00:00
068a4b1b5a Record ConfigKit source lookup scaling opportunity 2026-11-18 00:25:26 +00:00
b396581d21 Record ConfigKit inheritance integration findings 2026-11-17 23:52:27 +00:00
6f0a75e7cf Record ConfigKit upgrade review findings 2026-11-17 22:05:49 +00:00
d88a01cec0 Clarify native ConfigKit discovery in the roadmap 2026-11-17 21:59:54 +00:00
c9744ad2e6 Complete ConfigKit upgrade verification 2026-11-17 21:00:27 +00:00
74e0f454e9 Document ConfigKit integration and dependency attribution 2026-11-17 20:58:22 +00:00
244f258413 Document native configuration and toolchain requirements 2026-11-17 20:56:06 +00:00
5bab35f096 Compose the complete example from native step fragments 2026-11-17 20:54:47 +00:00
8136b4814f Verify configuration discovery and provenance 2026-11-17 20:53:07 +00:00
349ace0528 Delegate configuration discovery to ConfigKit 2026-11-17 20:51:06 +00:00
716bc62991 Update configuration fixtures for native composition 2026-11-17 20:50:07 +00:00
61ceab786c Compose pipeline steps using native identities 2026-11-17 20:48:05 +00:00
2d1fa57d9b Preserve source paths during field normalization 2026-11-17 20:44:07 +00:00
6da4d070e5 Migrate application configuration to the new ConfigKit API 2026-11-17 20:42:25 +00:00
ae0e410875 Select the ConfigKit upgrade toolchain and dependencies 2026-11-17 20:39:48 +00:00
79088a3546 Plan the ConfigKit native configuration upgrade 2026-11-17 20:35:04 +00:00
2c8b63187c Adopt native configuration search precedence in the roadmap 2026-11-17 20:27:56 +00:00
2b278c4074 Settle the ConfigKit upgrade scope and decisions 2026-11-17 20:25:26 +00:00
db32d31708 Plan adoption of current ConfigKit configuration semantics 2026-11-17 20:19:32 +00:00
b9899ea3cc Update adopted policies to the current upstream standard 2026-11-17 20:09:48 +00:00
66fa5585c1 Clarify ConfigKit configuration ownership 2026-10-04 18:58:10 +00:00
e690cae24f Record PromptKit migration review findings 2026-10-04 15:24:35 +00:00
6700ed2188 Complete PromptKit migration verification 2026-10-04 14:17:30 +00:00
4aba4f5672 Document PromptKit configuration ownership and capture 2026-10-04 14:12:11 +00:00
169a94f7ea Document PromptKit source composition and deployment 2026-10-04 14:04:32 +00:00
db8acbea43 Add resolved PromptKit profile inspection 2026-10-04 13:54:17 +00:00
79154882b8 Add scoped PromptKit configuration reports 2026-10-04 13:47:00 +00:00
c848befb53 Expose provider-neutral PromptKit inspection 2026-10-04 13:26:54 +00:00
a904e4d841 Verify PromptKit content origins and capture lifetime 2026-10-04 13:15:40 +00:00
7ea9fe12b9 Protect captured PromptKit checkpoint identity 2026-10-04 13:08:56 +00:00
deaa3560bc Capture immutable PromptKit configuration identity 2026-10-04 12:59:29 +00:00
ef504eabb2 Test native PromptKit source composition and credential policy 2026-10-04 12:46:23 +00:00
ec2ac3369b Migrate CLI and module tests to keyed PromptKit sources 2026-10-04 12:29:55 +00:00
8a8ca6d83c Migrate LLM fixtures to keyed PromptKit sources 2026-10-04 12:15:26 +00:00
30509f9d33 Use unified PromptKit sources for execution and preflight 2026-10-04 12:00:15 +00:00
28aab5e9a4 Upgrade PromptKit and assemble native configuration sources 2026-10-04 11:57:31 +00:00
ea403c8094 Migrate PromptKit definition assets to keyed format 2026-10-04 11:48:45 +00:00
f5b066beee Plan the PromptKit upgrade and configuration inspection 2026-10-04 11:38:01 +00:00
aae01a59ce Add operator-facing PromptKit inspection to the roadmap 2026-10-04 11:13:33 +00:00
71cf084e8b Adopt native PromptKit configuration capabilities in the roadmap 2026-10-04 11:11:40 +00:00
e327a5eef7 Plan the PromptKit configuration upgrade 2026-10-04 00:34:43 +00:00
af62b3bacc Include transcript input in the development command example 2026-10-04 00:24:04 +00:00
e1097cc7a5 Make inherited path tests distinguish source directories 2026-10-04 00:22:13 +00:00
3f226c91d0 Record ConfigKit inheritance review findings 2026-10-04 00:18:32 +00:00
64509947df Complete ConfigKit inheritance implementation 2026-10-03 18:17:28 +00:00
29c7c165a5 Add development pipeline inheritance example 2026-10-03 18:15:12 +00:00
4ef69314e1 Exercise inherited pipeline CLI behavior 2026-10-03 18:08:07 +00:00
1d1434b118 Retain inherited configuration inspection provenance 2026-10-03 18:03:40 +00:00
f4779fede9 Preserve inherited reference path origins 2026-10-03 17:58:48 +00:00
01c08ec8e4 Preserve inherited presence and validation 2026-10-03 17:55:58 +00:00
d7ea0fd32d Add pipeline inheritance coverage and guidance 2026-10-03 17:49:28 +00:00
ec99d48619 Upgrade ConfigKit to v0.5.0 2026-10-03 17:44:58 +00:00
9e74df0b6e Plan the ConfigKit inheritance upgrade 2026-10-03 17:33:13 +00:00
6e5e277426 Plan ConfigKit inheritance support 2026-10-03 17:16:41 +00:00
633 changed files with 29785 additions and 46584 deletions

View File

@@ -4,6 +4,6 @@ when:
steps:
- name: validate-release
image: golang:1.25.5
image: golang:1.27.0
commands:
- ./scripts/check-release-source.sh "$CI_COMMIT_TAG"

View File

@@ -8,28 +8,33 @@ and spell casts.
## Quickstart
Provide an OpenRouter API key through the environment, then run the maintained
minimal example:
Set `OPENROUTER_API_KEY` in your environment, then run the maintained
[minimal example](examples/dnd-minimal/config.yml) with its synthetic transcript:
~~~
OPENROUTER_API_KEY=your-api-key \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json
go run ./cmd/notarius run dnd-session \
--config examples/dnd-minimal/config.yml \
--input-file examples/dnd-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,
credentials, and module selection are owned by the
[configuration reference](docs/config.md).
For the complete ordered D&D workflow, use
[the complete configuration](examples/dnd-complete.config.yml) with
[its synthetic transcript](examples/dnd-complete-transcript.json). It
demonstrates all implemented D&D lanes and the supporting campaign references.
[the complete configuration](examples/dnd-complete/config.yml) with
[its synthetic transcript](examples/dnd-complete/transcript.json). It
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
Source builds require Go at or above the consumer minimum declared in
[`go.mod`](go.mod). Go 1.27.0 is required by the selected ConfigKit
dependency.
Install a pinned source release with Go:
~~~
@@ -49,8 +54,10 @@ Releases](docs/release.md).
validation, and module selection.
- [Operations](docs/operations.md) — output, state, recovery, and debug
handling.
- [Integration contracts](docs/integrations/) — Seriatim input and published
artifact formats.
- [Integration contracts](docs/integrations/) — Seriatim input, domain artifacts,
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
from an orchestrator and consume a published result.
- [Complete D&D consumer guide](docs/consumers/dnd-pipeline.md) — run the full
@@ -59,7 +66,9 @@ Releases](docs/release.md).
for maintainers.
- [Developer guide](docs/development.md) — contributor orientation and
validation guidance.
- [Future work](docs/roadmap/future.md) — unimplemented ideas and priorities.
- [Native migration guide](docs/consumers/native-migration.md) — move existing
configurations, invocations, and consumers to the native surface.
- [Future work](docs/roadmap/future.md) — separate backlog of ideas and priorities.
Notarius is licensed under the [GPL v3.0 or later](COPYRIGHT).

View File

@@ -1,24 +1,58 @@
package combat_semantics
package assets_test
import (
"bytes"
"context"
"encoding/json"
"gitea.maximumdirect.net/eric/notarius/assets"
"io/fs"
"strings"
"testing"
"go.maximumdirect.net/promptkit"
"github.com/santhosh-tekuri/jsonschema/v6"
)
func TestLoadResponseSchemaUsesStrictCombatSemanticsContract(t *testing.T) {
schema, err := loadResponseSchema()
func TestCombatSemanticsPromptKeepsItsSceneLocalPolicyAndInput(t *testing.T) {
_, engine := loadNativeAssets(t)
const transcript = `{"sentinel":"combat-semantics-transcript"}`
handle, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.scene_descriptions.validate_combat", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"transcript": promptkit.Inline(transcript)},
})
if err != nil {
t.Fatal(err)
}
defer handle.Discard()
details := handle.Details()
if details.SelectedProfileID != "notarius/dnd-extraction" || details.StructuredOutput == nil {
t.Fatal("native validator defaults/output contract lost")
}
var all string
for _, message := range details.Messages {
all += message.Content
if strings.Contains(message.Content, transcript) && (message.CacheControl == nil || message.CacheControl.Type != promptkit.CacheControlEphemeral) {
t.Fatal("chunk transcript native cache hint lost")
}
}
for _, content := range []string{"substantive active combat materially organizes the", "Do not judge the scene title", transcript} {
if strings.Count(all, content) != 1 {
t.Fatalf("scene-local context not rendered once: %q", content)
}
}
if _, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{PromptID: "notarius/dnd.scene_descriptions.validate_combat", APIKey: "test-only"}); err == nil {
t.Fatal("native validator accepted missing transcript")
}
}
func TestCombatSemanticsResponseSchemaRetainsClassificationAndExplanationRules(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/scene-descriptions/validate/combat-semantics/schemas/dnd_scene_combat_semantics_llm.v1.json")
if err != nil {
t.Fatalf("loadResponseSchema() error = %v, want nil", err)
}
if schema.Key != ResponseSchemaKey || schema.ID != ResponseSchemaID || schema.Version != SchemaVersion || schema.Name != ResponseSchemaName || !strings.HasPrefix(schema.SHA256, "sha256:") || !json.Valid(schema.JSONSchema) {
t.Fatalf("schema = %#v, want private combat-semantics schema identity", schema)
}
for _, classification := range []string{"combat", "non_combat"} {
if err := validateCombatSemanticsSchema(map[string]any{"classification": classification, "explanation": "The chunk contains sustained attack exchanges."}, schema.JSONSchema); err != nil {
if err := validateCombatSemanticsSchema(map[string]any{"classification": classification, "explanation": "The chunk contains sustained attack exchanges."}, schema); err != nil {
t.Fatalf("valid %q classification rejected: %v", classification, err)
}
}
@@ -36,29 +70,11 @@ func TestLoadResponseSchemaUsesStrictCombatSemanticsContract(t *testing.T) {
{name: "oversized explanation", response: map[string]any{"classification": "combat", "explanation": strings.Repeat("a", 513)}},
} {
t.Run(test.name, func(t *testing.T) {
if err := validateCombatSemanticsSchema(test.response, schema.JSONSchema); err == nil {
if err := validateCombatSemanticsSchema(test.response, schema); err == nil {
t.Fatal("invalid private response accepted")
}
})
}
if bytes.Contains(schema.JSONSchema, []byte("uniqueItems")) {
t.Fatalf("schema included unsupported uniqueItems constraint: %s", schema.JSONSchema)
}
}
func TestResponseSchemaIsMutationSafeAndDiagnosticsRedactContent(t *testing.T) {
first, err := loadResponseSchema()
if err != nil {
t.Fatal(err)
}
first.JSONSchema[0] = '['
second, err := loadResponseSchema()
if err != nil || !strings.HasPrefix(second.SHA256, "sha256:") || !json.Valid(second.JSONSchema) || bytes.Equal(first.JSONSchema, second.JSONSchema) {
t.Fatalf("second schema = %s, %v; want defensive copy", second.JSONSchema, err)
}
if diagnostics := second.DiagnosticsMap(); diagnostics["json_schema"] != nil {
t.Fatalf("schema diagnostics included raw content: %#v", diagnostics)
}
}
func validateCombatSemanticsSchema(instance map[string]any, schemaContent []byte) error {

176
assets/combat_turns_test.go Normal file
View File

@@ -0,0 +1,176 @@
package assets_test
import (
"context"
"encoding/json"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/promptkit"
)
func TestCombatPromptPairPreservesNativeContractAndFixedGrounding(t *testing.T) {
_, engine := loadNativeAssets(t)
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.combat_turns", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(`{"units":[{"text":"combat-transcript-marker"}]}`),
"npc_registry": promptkit.Inline(`{"npcs":[{"name":"combat-npc-marker"}]}`),
"party": promptkit.Inline("combat-party-marker"),
"players": promptkit.Inline(" "),
"glossary": promptkit.Inline(" "),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.combat_turns.repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline("Fix the actor citation.")},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || first.SelectedProfileID != next.SelectedProfileID || first.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("combat native pair lost its schema/default profile")
}
var system, all string
for _, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
}
for _, principle := range []string{"Unmatched actors remain permitted.", "Exclude initiative setup without a turn", "Transcript units are the only evidence", "legendary_action", "lair_action"} {
if !strings.Contains(strings.Join(strings.Fields(system), " "), principle) {
t.Fatalf("missing enduring rule %q", principle)
}
}
for _, marker := range []string{"combat-transcript-marker", "combat-npc-marker", "combat-party-marker"} {
if strings.Count(all, marker) != 1 {
t.Fatalf("fixed input repeated: %q", marker)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, "Fix the actor citation.") || strings.Contains(next.Messages[0].Content, "combat-transcript-marker") {
t.Fatal("correction did not contain only findings and a replacement assignment")
}
}
func TestCombatResponseSchemaUsesPrivateShape(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json")
if err != nil {
t.Fatal(err)
}
valid := validCombatResponse()
content, err := json.Marshal(valid)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("valid combat response rejected: %v", err)
}
withSourceID := validCombatResponse()
withSourceID["combat_turns"].([]any)[0].(map[string]any)["source_refs"].([]any)[0].(map[string]any)["source_id"] = "session-alpha"
content, err = json.Marshal(withSourceID)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err == nil {
t.Fatal("response schema accepted source_id, want private source-reference shape")
}
}
func TestCombatResponseSchemaLeavesNonCategoricalSemanticsToValidators(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json")
if err != nil {
t.Fatal(err)
}
semanticCandidate := validCombatResponse()
turn := semanticCandidate["combat_turns"].([]any)[0].(map[string]any)
turn["actor"] = ""
ref := turn["source_refs"].([]any)[0].(map[string]any)
ref["start_unit_id"] = 0
ref["end_unit_id"] = -1
content, err := json.Marshal(semanticCandidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("private schema rejected non-categorical validator-owned semantics: %v", err)
}
turn["source_refs"] = []any{}
content, err = json.Marshal(semanticCandidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("private schema rejected empty validator-owned collections: %v", err)
}
}
func TestCombatResponseSchemaRetainsStructuralBoundary(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, test := range []struct {
name string
mutate func(map[string]any)
}{
{name: "missing actor", mutate: func(turn map[string]any) { delete(turn, "actor") }},
{name: "wrong actor type", mutate: func(turn map[string]any) { turn["actor"] = 1 }},
{name: "unknown field", mutate: func(turn map[string]any) { turn["unexpected"] = true }},
{name: "missing source refs", mutate: func(turn map[string]any) { delete(turn, "source_refs") }},
{name: "unsupported turn kind", mutate: func(turn map[string]any) { turn["turn_kind"] = "unsupported" }},
} {
t.Run(test.name, func(t *testing.T) {
candidate := validCombatResponse()
test.mutate(candidate["combat_turns"].([]any)[0].(map[string]any))
content, err := json.Marshal(candidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err == nil {
t.Fatal("private schema accepted structurally invalid response")
}
})
}
}
func TestCombatResponseSchemaAcceptsEverySupportedTurnKind(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, kind := range []string{"turn", "reaction", "legendary_action", "lair_action", "other"} {
candidate := validCombatResponse()
candidate["combat_turns"].([]any)[0].(map[string]any)["turn_kind"] = kind
content, err := json.Marshal(candidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("supported turn kind %q was rejected: %v", kind, err)
}
}
}
func validCombatResponse() map[string]any {
return map[string]any{
"combat_turns": []any{
map[string]any{
"actor": "Aria",
"turn_kind": "reaction",
"source_refs": []any{map[string]any{"start_unit_id": 1, "end_unit_id": 2}},
},
},
}
}

View File

@@ -0,0 +1,7 @@
Revise the previous combat-turn list using these findings:
{{ input "guidance" }}
Return the complete replacement list using the original transcript and actor
grounding. Preserve transcript chronology and include only established combat
events. Return only JSON matching the original response contract.

View File

@@ -1,45 +1,58 @@
id: dnd.combat_turns
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: false
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./sharedassets/common-dnd-npc-registry.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_combat_turns_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.combat_turns
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: false
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ../../shared/prompts/common-dnd-npc-registry.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json
- id: dnd.combat_turns.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/combat-turns/schemas/dnd_combat_turns_llm.v1.json

View File

@@ -0,0 +1,8 @@
Revise the previous enemy-event list using these findings:
{{ input "guidance" }}
Return the complete replacement event list using the original combat transcript
and fixed contextual grounding. Include only directly established engagements and
outcomes, retaining their source evidence and chronology. Return only JSON
matching the original response contract.

View File

@@ -1,53 +1,66 @@
id: dnd.enemy_events
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: true
content_type: application/json
- name: combat_turns
required: true
content_type: application/json
- name: npc_occurrences
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./sharedassets/common-dnd-npc-registry.md
- role: user
content_file: ./combat-grounding.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_enemy_events_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.enemy_events
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: true
content_type: application/json
- name: combat_turns
required: true
content_type: application/json
- name: npc_occurrences
required: true
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ../../shared/prompts/common-dnd-npc-registry.md
- role: user
content_file: ./combat-grounding.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/enemy-events/schemas/dnd_enemy_events_llm.v1.json
- id: dnd.enemy_events.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/enemy-events/schemas/dnd_enemy_events_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous item occurrence list using these findings:
{{ input "guidance" }}
Return the complete replacement list using the original transcript and registry
context. Preserve stated quantities and possession changes without inventing an
item or holder. Return only JSON matching the original response contract.

View File

@@ -1,45 +1,58 @@
id: dnd.item_occurrences
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: item_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./item-registry.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_item_occurrences_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.item_occurrences
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: item_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ./item-registry.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/item-occurrences/schemas/dnd_item_occurrences_llm.v1.json
- id: dnd.item_occurrences.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/item-occurrences/schemas/dnd_item_occurrences_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous item registry using these findings:
{{ input "guidance" }}
Return the complete replacement registry, not only the changed records. Keep the
original transcript and reference context and return only JSON matching the
original response contract.

View File

@@ -1,40 +1,53 @@
id: dnd.item_registry
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_item_registry_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.item_registry
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../../shared/prompts/common-dnd-extraction-evidence.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/item-registry/extract/schemas/dnd_item_registry_llm.v1.json
- id: dnd.item_registry.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/item-registry/extract/schemas/dnd_item_registry_llm.v1.json

View File

@@ -1,30 +1,43 @@
id: dnd.item_registry.normalize
version: "v1"
default_profile: dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/protocol.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/candidates.md
- role: user
content_file: ./sharedassets/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: semantic_reconciliation_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.item_registry.normalize
default_profile: notarius/dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../../generic/normalize/deduplication/prompts/protocol.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/candidates.md
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json
- id: dnd.item_registry.normalize.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/correction.md
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous location occurrence list using these findings:
{{ input "guidance" }}
Return a complete replacement occurrence list using the original transcript and
registry context. Keep identity-grounding context separate from current-transcript
evidence, and return only JSON matching the original response contract.

View File

@@ -1,45 +1,58 @@
id: dnd.location_occurrences
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: location_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./location-registry.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_location_occurrences_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.location_occurrences
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: location_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ./location-registry.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/location-occurrences/schemas/dnd_location_occurrences_llm.v1.json
- id: dnd.location_occurrences.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/location-occurrences/schemas/dnd_location_occurrences_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous location registry using these findings:
{{ input "guidance" }}
Return the complete replacement registry, not only the changed records. Keep the
original transcript and reference context and return only JSON matching the
original response contract.

View File

@@ -1,40 +1,53 @@
id: dnd.location_registry
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_location_registry_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.location_registry
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../../shared/prompts/common-dnd-extraction-evidence.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/location-registry/extract/schemas/dnd_location_registry_llm.v1.json
- id: dnd.location_registry.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/location-registry/extract/schemas/dnd_location_registry_llm.v1.json

View File

@@ -1,30 +1,43 @@
id: dnd.location_registry.normalize
version: "v1"
default_profile: dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/protocol.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/candidates.md
- role: user
content_file: ./sharedassets/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: semantic_reconciliation_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.location_registry.normalize
default_profile: notarius/dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../../generic/normalize/deduplication/prompts/protocol.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/candidates.md
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json
- id: dnd.location_registry.normalize.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/correction.md
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous NPC occurrence list using these findings:
{{ input "guidance" }}
Return a complete replacement occurrence list using the original transcript and
registry context. Keep identity-grounding context separate from current-transcript
evidence, and return only JSON matching the original response contract.

View File

@@ -1,45 +1,58 @@
id: dnd.npc_occurrences
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./sharedassets/common-dnd-npc-registry.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_npc_occurrences_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.npc_occurrences
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: true
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ../../shared/prompts/common-dnd-npc-registry.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/npc-occurrences/schemas/dnd_npc_occurrences_llm.v1.json
- id: dnd.npc_occurrences.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/npc-occurrences/schemas/dnd_npc_occurrences_llm.v1.json

View File

@@ -0,0 +1,7 @@
Revise the previous NPC registry using these findings:
{{ input "guidance" }}
Return the complete replacement registry, not only the changed records. Keep the
original transcript and reference context and return only JSON matching the
original response contract.

View File

@@ -1,40 +1,53 @@
id: dnd.npc_registry
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_npc_registry_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.npc_registry
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../../shared/prompts/common-dnd-extraction-evidence.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/npc-registry/extract/schemas/dnd_npc_registry_llm.v1.json
- id: dnd.npc_registry.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/npc-registry/extract/schemas/dnd_npc_registry_llm.v1.json

View File

@@ -1,30 +1,43 @@
id: dnd.npc_registry.normalize
version: "v1"
default_profile: dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/protocol.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/candidates.md
- role: user
content_file: ./sharedassets/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: semantic_reconciliation_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.npc_registry.normalize
default_profile: notarius/dnd-extraction
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ../../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../../../generic/normalize/deduplication/prompts/protocol.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/candidates.md
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/transcript-windows.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json
- id: dnd.npc_registry.normalize.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ../../../../generic/normalize/deduplication/prompts/correction.md
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json

View File

@@ -1,5 +1,6 @@
id: dnd-extraction
backend: openrouter
model: openai/gpt-5.6-luna
timeout_seconds: 240
service_tier: flex
profiles:
- id: dnd-extraction
backend: openrouter
model: openai/gpt-5.6-luna
timeout_seconds: 240
service_tier: flex

View File

@@ -0,0 +1,7 @@
Revise the previous scene description using these findings:
{{ input "guidance" }}
Return one complete replacement kind, title, and summary for the original
transcript chunk. Do not change its boundary or invent details to justify a
classification. Return only JSON matching the original response contract.

View File

@@ -1,40 +1,53 @@
id: dnd.scene_descriptions
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-scene-combat-policy.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_scene_descriptions_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.scene_descriptions
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-scene-combat-policy.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/scene-descriptions/schemas/dnd_scene_descriptions_llm.v1.json
- id: dnd.scene_descriptions.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/scene-descriptions/schemas/dnd_scene_descriptions_llm.v1.json

View File

@@ -1,23 +1,22 @@
id: dnd.scene_descriptions.validate_combat
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-scene-combat-policy.md
- role: user
content_file: ./instructions.md
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_scene_combat_semantics_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.scene_descriptions.validate_combat
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ../../../../shared/prompts/common-dnd-system.md
- role: user
content_file: ../../../../shared/prompts/common-dnd-scene-combat-policy.md
- role: user
content_file: ./instructions.md
- role: user
content_file: ../../../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/scene-descriptions/validate/combat-semantics/schemas/dnd_scene_combat_semantics_llm.v1.json

View File

@@ -0,0 +1,8 @@
Revise the previous scene-boundary plan using these findings:
{{ input "guidance" }}
Return a complete replacement scene plan for the original full transcript, not
only the changed ranges. Keep the original source-unit IDs and cover every unit
in document order without gaps or overlaps. Return only JSON matching the original
response contract.

View File

@@ -1,34 +1,47 @@
id: dnd.scenes
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./instructions.md
- role: user
content_file: ./sharedassets/common-dnd-transcript-full.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_scenes_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.scenes
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: system
content_file: ./instructions.md
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-full.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/scenes/schemas/dnd_scenes_llm.v1.json
- id: dnd.scenes.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/scenes/schemas/dnd_scenes_llm.v1.json

View File

@@ -0,0 +1,5 @@
Revise the previous spell-cast list using these findings:
{{ input "guidance" }}
Return the complete replacement spell-cast list under the same output contract.

View File

@@ -1,14 +1 @@
Extract Dungeons & Dragons spell-cast artifacts from the provided transcript.
Include an actual casting event or an unambiguous declared casting attempt.
Exclude spell mentions, hypothetical plans, rules discussion, and catalog
matches that do not establish a casting event in the transcript.
For every extracted cast, the transcript evidence must collectively support the
in-world caster, the spell, and the fact that the cast or declared attempt
occurred.
Attribute every cast to its in-world caster. Map first-person player speech to
the associated player character, and attribute a spell narrated by the GM to
the in-world creature that casts it. If the caster cannot be resolved, use only
the most specific in-world identity supported by the transcript; do not invent
a name.
Extract the spell casts established by the provided transcript chunk. Return the complete spell-cast list, or an empty list when no casting event is supported.

View File

@@ -0,0 +1,18 @@
Extract Dungeons & Dragons spell-cast artifacts from transcript evidence.
Include an actual casting event or an unambiguous declared casting attempt.
Exclude spell mentions, hypothetical plans, rules discussion, and catalog
matches that do not establish a casting event in the transcript.
For every extracted cast, the transcript evidence must collectively support the
in-world caster, the spell, and the fact that the cast or declared attempt
occurred.
Attribute every cast to its in-world caster. Map first-person player speech to
the associated player character, and attribute a spell narrated by the GM to
the in-world creature that casts it. If the caster cannot be resolved, use only
the most specific in-world identity supported by the transcript; do not invent
a name.
The spell catalog lists each spell's canonical_name and recognized aliases.
If the transcript uses an alias, select that entry's canonical_name. Return the
canonical spelling exactly; never return an alias as a spell name.

View File

@@ -1,50 +1,65 @@
id: dnd.spells
version: "v1"
default_profile: dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: spell_catalog
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: false
content_type: application/json
messages:
- role: system
content_file: ./sharedassets/common-dnd-system.md
- role: user
content_file: ./sharedassets/common-dnd-identity.md
- role: user
content_file: ./sharedassets/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: user
content_file: ./sharedassets/common-dnd-extraction-evidence.md
- role: user
content_file: ./sharedassets/common-dnd-npc-registry.md
- role: user
content_file: ./spell-catalog.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd_spells_llm.v1.json
repair_attempts: 1
prompts:
- id: dnd.spells
default_profile: notarius/dnd-extraction
inputs:
- name: transcript
required: true
content_type: application/json
- name: spell_catalog
required: true
content_type: application/json
- name: players
required: false
content_type: text/plain
- name: party
required: false
content_type: text/plain
- name: glossary
required: false
content_type: text/plain
- name: npc_registry
required: false
content_type: application/json
messages:
- role: system
content_file: ../../shared/prompts/common-dnd-system.md
- role: system
content_file: ../../shared/prompts/common-dnd-identity.md
- role: system
content_file: ./principles.md
- role: user
content_file: ../../shared/prompts/common-dnd-references.md
cache_control:
type: ephemeral
- role: user
content_file: ../../shared/prompts/common-dnd-transcript-chunk.md
cache_control:
type: ephemeral
- role: system
content_file: ../../shared/prompts/common-dnd-extraction-evidence.md
- role: user
content_file: ../../shared/prompts/common-dnd-npc-registry.md
- role: user
content_file: ./spell-catalog.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
output:
format: json
validation_mode: json_schema
schema_path: dnd/spells/schemas/dnd_spells_llm.v1.json
- id: dnd.spells.repair
default_profile: notarius/dnd-extraction
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: dnd/spells/schemas/dnd_spells_llm.v1.json

View File

@@ -1,6 +1,3 @@
The spell catalog for this extraction is provided below as JSON. Each entry
lists a `canonical_name` and its recognized `aliases`. If the transcript uses
an alias, select that entry's `canonical_name`. Return spell names using the
canonical spelling exactly; never return an alias as a spell name.
The spell recognition catalog for this operation:
{{ input "spell_catalog" }}

151
assets/enemy_events_test.go Normal file
View File

@@ -0,0 +1,151 @@
package assets_test
import (
"context"
"encoding/json"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/promptkit"
)
func TestEnemyResponseSchemaDefinesPrivateStructuralBoundary(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/enemy-events/schemas/dnd_enemy_events_llm.v1.json")
if err != nil {
t.Fatal(err)
}
valid := validEnemyResponse()
content, err := json.Marshal(valid)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("valid response rejected: %v", err)
}
semantic := validEnemyResponse()
event := semantic["events"].([]any)[0].(map[string]any)
event["name"] = ""
ref := event["source_refs"].([]any)[0].(map[string]any)
ref["start_unit_id"] = 0
ref["end_unit_id"] = -1
content, err = json.Marshal(semantic)
if err != nil || validateJSONSchema(content, schema) != nil {
t.Fatalf("non-categorical validator-owned semantics were rejected: %v", err)
}
}
func TestEnemyResponseSchemaRejectsInvalidStructure(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/enemy-events/schemas/dnd_enemy_events_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, mutate := range []func(map[string]any){
func(event map[string]any) { delete(event, "name") },
func(event map[string]any) { event["kind"] = 1 },
func(event map[string]any) { event["kind"] = "unsupported" },
func(event map[string]any) { event["unexpected"] = true },
func(event map[string]any) { event["source_refs"].([]any)[0].(map[string]any)["source_id"] = "session" },
} {
candidate := validEnemyResponse()
mutate(candidate["events"].([]any)[0].(map[string]any))
content, err := json.Marshal(candidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err == nil {
t.Fatal("private schema accepted structurally invalid response")
}
}
}
func TestEnemyResponseSchemaAcceptsEverySupportedKind(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/enemy-events/schemas/dnd_enemy_events_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, kind := range []string{"engaged", "killed", "fled", "captured", "incapacitated"} {
candidate := validEnemyResponse()
candidate["events"].([]any)[0].(map[string]any)["kind"] = kind
content, err := json.Marshal(candidate)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("supported enemy-event kind %q was rejected: %v", kind, err)
}
}
}
func validEnemyResponse() map[string]any {
return map[string]any{"events": []any{map[string]any{
"name": "Ashfang", "kind": "engaged", "source_refs": []any{map[string]any{"start_unit_id": 1, "end_unit_id": 1}},
}}}
}
func TestEnemyPromptPairRetainsRequiredGroundingAndNativeDefaults(t *testing.T) {
_, engine := loadNativeAssets(t)
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{PromptID: "notarius/dnd.enemy_events", APIKey: "test-only", Inputs: enemyEventPromptInputs()})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.enemy_events.repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline("Combine the duplicate engagement evidence.")},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || first.SelectedProfileID != next.SelectedProfileID || first.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("enemy-event prompt pair lost schema/defaults")
}
var system, all string
for _, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
}
for _, rule := range []string{"Emit at most one", "A hostile creature without a registry entry is allowed.", "Do not infer an engagement or outcome", "Transcript units are the only evidence"} {
if !strings.Contains(strings.Join(strings.Fields(system), " "), rule) {
t.Fatalf("missing enduring rule %q", rule)
}
}
for _, marker := range []string{"enemy-transcript", "enemy-player", "enemy-party", "enemy-glossary", "enemy-npc", "enemy-turn", "enemy-opponent"} {
if strings.Count(all, marker) != 1 {
t.Fatalf("fixed grounding repeated: %q", marker)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, "Combine the duplicate engagement evidence.") || strings.Contains(next.Messages[0].Content, "enemy-transcript") {
t.Fatal("correction repeated fixed inputs or omitted findings")
}
for _, name := range []string{"npc_registry", "combat_turns", "npc_occurrences"} {
missing := enemyEventPromptInputs()
delete(missing, name)
handle, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{PromptID: "notarius/dnd.enemy_events", APIKey: "test-only", Inputs: missing})
if handle != nil {
handle.Discard()
}
if err == nil || !strings.Contains(err.Error(), name) {
t.Fatalf("missing %s input=%v", name, err)
}
}
}
func enemyEventPromptInputs() map[string]promptkit.ArtifactRef {
return map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(`{"value":"enemy-transcript"}`),
"players": promptkit.Inline("enemy-player"),
"party": promptkit.Inline("enemy-party"),
"glossary": promptkit.Inline("enemy-glossary"),
"npc_registry": promptkit.Inline(`{"npcs":[{"name":"enemy-npc"}]}`),
"combat_turns": promptkit.Inline(`{"combat_turns":[{"actor":"enemy-turn","turn_kind":"turn"}]}`),
"npc_occurrences": promptkit.Inline(`{"npc_occurrences":[{"name":"enemy-opponent","kind":"combat_opponent"}]}`),
}
}

View File

@@ -0,0 +1,6 @@
Revise the previous duplicate-entity proposal using these findings:
{{ input "guidance" }}
Return one complete replacement proposal under the original output contract.
Do not return a patch or commentary.

View File

@@ -1,27 +1,39 @@
id: generic.semantic_reconciliation
version: "v1"
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./system.md
- role: user
content_file: ./protocol.md
- role: user
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ./candidates.md
- role: user
content_file: ./transcript-windows.md
output:
format: json
validation_mode: json_schema
schema_path: semantic_reconciliation_llm.v1.json
repair_attempts: 1
prompts:
- id: generic.semantic_reconciliation
inputs:
- name: candidates
required: true
content_type: application/json
- name: transcript
required: true
content_type: application/json
messages:
- role: system
content_file: ./system.md
- role: system
content_file: ./protocol.md
- role: system
content_file: ./instructions.md
cache_control:
type: ephemeral
- role: user
content_file: ./candidates.md
- role: user
content_file: ./transcript-windows.md
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json
- id: generic.semantic_reconciliation.repair
inputs:
- name: guidance
required: true
content_type: text/plain
messages:
- role: user
content_file: ./correction.md
output:
format: json
validation_mode: json_schema
schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json

View File

@@ -0,0 +1,79 @@
package assets_test
import (
"encoding/json"
"io/fs"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
)
func TestItemOccurrenceSchemaIsStrictlyStructuralAndPrivate(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/item-occurrences/schemas/dnd_item_occurrences_llm.v1.json")
if err != nil {
t.Fatal(err)
}
valid := map[string]any{"occurrences": []any{
map[string]any{
"name": "", "kind": "transferred", "quantity": 0, "from": "party", "to": "Party",
"source_refs": []any{map[string]any{"start_unit_id": 0, "end_unit_id": -1}},
},
map[string]any{
"name": "Hidden Cache", "kind": "discovered", "quantity": nil, "from": nil, "to": nil,
"source_refs": []any{map[string]any{"start_unit_id": 1, "end_unit_id": 1}},
},
}}
content, err := json.Marshal(valid)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err != nil {
t.Fatalf("private schema rejected validator-owned values: %v", err)
}
for _, test := range []struct {
name string
value map[string]any
}{
{"missing occurrences", map[string]any{}},
{"missing occurrence name", map[string]any{"occurrences": []any{itemOccurrenceWithoutField(itemOccurrenceRecord(), "name")}}},
{"missing nullable field", map[string]any{"occurrences": []any{itemOccurrenceWithoutField(itemOccurrenceRecord(), "quantity")}}},
{"missing from", map[string]any{"occurrences": []any{itemOccurrenceWithoutField(itemOccurrenceRecord(), "from")}}},
{"missing to", map[string]any{"occurrences": []any{itemOccurrenceWithoutField(itemOccurrenceRecord(), "to")}}},
{"noninteger quantity", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "quantity", 1.5)}}},
{"unsupported kind", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "kind", "unsupported")}}},
{"opaque item identifier", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "item_id", "item:sha256:opaque")}}},
{"unknown occurrence field", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "extra", true)}}},
{"segment-named range", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "source_refs", []any{map[string]any{"start_segment": 1, "end_segment": 1}})}}},
{"opaque source identifier", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "source_refs", []any{map[string]any{"start_unit_id": 1, "end_unit_id": 1, "source_id": "session-alpha"}})}}},
{"unknown reference field", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "source_refs", []any{map[string]any{"start_unit_id": 1, "end_unit_id": 1, "extra": true}})}}},
{"noninteger range", map[string]any{"occurrences": []any{itemOccurrenceWithField(itemOccurrenceRecord(), "source_refs", []any{map[string]any{"start_unit_id": 1.5, "end_unit_id": 1}})}}},
} {
t.Run(test.name, func(t *testing.T) {
content, err := json.Marshal(test.value)
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); err == nil {
t.Fatal("private schema accepted invalid structure")
}
})
}
}
func itemOccurrenceRecord() map[string]any {
return map[string]any{
"name": "Ring", "kind": "acquired", "quantity": nil, "from": nil, "to": "party", "source_refs": []any{},
}
}
func itemOccurrenceWithoutField(value map[string]any, name string) map[string]any {
delete(value, name)
return value
}
func itemOccurrenceWithField(value map[string]any, name string, fieldValue any) map[string]any {
value[name] = fieldValue
return value
}

57
assets/notarius.yml Normal file
View File

@@ -0,0 +1,57 @@
config:
imports:
- path: dnd/combat-turns/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/enemy-events/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/item-occurrences/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/item-registry/extract/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/item-registry/normalize/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/location-occurrences/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/location-registry/extract/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/location-registry/normalize/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/npc-occurrences/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/npc-registry/extract/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/npc-registry/normalize/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/scene-descriptions/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/scene-descriptions/validate/combat-semantics/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/scenes/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/spells/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: generic/normalize/deduplication/prompts/prompt.yaml
destination: [promptkit, collections, notarius]
required: true
- path: dnd/profiles/dnd-extraction.yaml
destination: [promptkit, collections, notarius]
required: true
promptkit:
collections:
notarius:
schema_root: .

View File

@@ -0,0 +1,149 @@
package assets_test
import (
"context"
"encoding/json"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/promptkit"
)
func TestOccurrencePromptPairsPreserveRegistryAndTranscriptBoundaries(t *testing.T) {
_, engine := loadNativeAssets(t)
for _, test := range []struct {
family, registry string
rules []string
}{
{"item", `{"items":[{"name":"occurrence-registry-name"}]}`, []string{
"Return both `from` and `to` for every occurrence.",
"| `discovered` | `null` | `null` |",
"| `acquired` | `null` | `party` or the named party member gaining possession |",
"| `lost` | `party` or the named party member losing possession | `null` |",
"| `consumed` | `party` or the named party member consuming the item | `null` |",
"| `transferred` | one named party member | a different named party member |",
"payments are always `lost`, not `consumed`.",
}},
{"npc", `{"npcs":[{"name":"occurrence-registry-name"}]}`, []string{"Use the supplied canonical NPC", "noncombat_presence", "combat_opponent"}},
{"location", `{"locations":[{"name":"occurrence-registry-name","registry_refs":[{"start_unit_id":7,"end_unit_id":7}],"context":[{"unit_id":7,"text":"registry-context"}]}]}`,
[]string{"context supports that coreference", "must not create a registry location", "provenance must never replace current-chunk evidence", "complete ordered"}},
} {
t.Run(test.family, func(t *testing.T) {
id := "notarius/dnd." + test.family + "_occurrences"
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: id, APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(`{"units":[{"sentinel":"occurrence-transcript"}]}`),
test.family + "_registry": promptkit.Inline(test.registry),
"players": promptkit.Inline("occurrence-players"), "party": promptkit.Inline("occurrence-party"), "glossary": promptkit.Inline("occurrence-glossary"),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: id + ".repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline("Correct the unsupported occurrence.")},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || first.SelectedProfileID != next.SelectedProfileID ||
first.StructuredOutput == nil || next.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("occurrence native pair lost schema/defaults")
}
var system, all string
for _, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
}
for _, rule := range append(test.rules, "Transcript units are the only evidence") {
if !strings.Contains(strings.Join(strings.Fields(system), " "), rule) {
t.Fatalf("missing enduring rule %q", rule)
}
}
for _, content := range []string{"occurrence-registry-name", "occurrence-transcript", "occurrence-players", "occurrence-party", "occurrence-glossary"} {
if strings.Count(all, content) != 1 {
t.Fatalf("input not rendered once: %q", content)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, "Correct the unsupported occurrence.") ||
strings.Contains(next.Messages[0].Content, "occurrence-registry-name") {
t.Fatal("correction repeated fixed inputs")
}
})
}
}
func TestOccurrenceSchemasRetainSupportedKindsAndPrivateSelectors(t *testing.T) {
for _, test := range []struct {
family string
kinds []string
}{
{"npc", []string{"mentioned", "noncombat_presence", "dialogue", "combat_ally", "combat_opponent", "other"}},
{"location", []string{"visited", "planned", "recalled", "mentioned"}},
} {
t.Run(test.family, func(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/"+test.family+"-occurrences/schemas/dnd_"+test.family+"_occurrences_llm.v1.json")
if err != nil {
t.Fatal(err)
}
record := func() map[string]any {
value := map[string]any{"name": "Canonical Name", "kind": test.kinds[0], "source_refs": []any{map[string]any{"start_unit_id": 1, "end_unit_id": 2}}}
if test.family == "location" {
value["registry_refs"] = []any{map[string]any{"start_unit_id": 1, "end_unit_id": 2}}
}
return value
}
check := func(value map[string]any, valid bool) {
t.Helper()
content, err := json.Marshal(map[string]any{"occurrences": []any{value}})
if err != nil {
t.Fatal(err)
}
if err := validateJSONSchema(content, schema); (err == nil) != valid {
t.Fatalf("valid=%t response=%s error=%v", valid, content, err)
}
}
for _, kind := range test.kinds {
value := record()
value["kind"] = kind
check(value, true)
}
semantic := record()
semantic["name"] = ""
semantic["source_refs"] = []any{map[string]any{"start_unit_id": 0, "end_unit_id": -1}}
check(semantic, true)
for _, mutate := range []func(map[string]any){
func(value map[string]any) { delete(value, "name") },
func(value map[string]any) { value["kind"] = 1 },
func(value map[string]any) { value["kind"] = "unsupported" },
func(value map[string]any) { value[test.family+"_id"] = "assigned-later" },
func(value map[string]any) { value["unexpected"] = true },
func(value map[string]any) {
value["source_refs"].([]any)[0].(map[string]any)["source_id"] = "assigned-later"
},
} {
value := record()
mutate(value)
check(value, false)
}
if test.family == "location" {
value := record()
delete(value, "registry_refs")
check(value, false)
value = record()
value["registry_refs"].([]any)[0].(map[string]any)["start_unit_id"] = 0
check(value, false)
}
})
}
}

View File

@@ -6,7 +6,7 @@ import (
"io/fs"
)
//go:embed dnd generic
//go:embed notarius.yml dnd generic
var embedded embed.FS
// FS returns the embedded read-only asset filesystem.

214
assets/package_test.go Normal file
View File

@@ -0,0 +1,214 @@
package assets_test
import (
"context"
"encoding/json"
"errors"
"fmt"
"io/fs"
"path"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/configkit"
"go.maximumdirect.net/promptkit"
"go.yaml.in/yaml/v4"
)
type assetSettings struct {
PromptKit promptkit.Settings `yaml:"promptkit"`
}
type noGeneration struct{ t *testing.T }
func (client noGeneration) Generate(context.Context, promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
client.t.Error("resource preparation unexpectedly invoked generation")
return nil, fmt.Errorf("unexpected generation")
}
func loadNativeAssets(t *testing.T) (*configkit.Result[assetSettings], *promptkit.Engine) {
t.Helper()
filesystem := configkit.NewFilesystem("Notarius assets", assets.FS())
definition := promptkit.Configure(configkit.Definition[assetSettings]{}, func(value *assetSettings) *promptkit.Settings { return &value.PromptKit })
result, err := configkit.LoadLayered(configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[assetSettings]{
Definition: definition,
Underlays: []configkit.Underlay{
promptkit.BundledOpenRouterUnderlay(),
{Inputs: []configkit.Input{{
Source: filesystem.File("notarius.yml"), Imports: true,
Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: "."},
}}},
},
})
if err != nil {
var loadError *configkit.LoadError
if errors.As(err, &loadError) {
for _, diagnostic := range loadError.Diagnostics() {
t.Logf("%+v", diagnostic)
}
}
t.Fatal(err)
}
engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{}, promptkit.WithLLMClient(noGeneration{t}))
if err != nil {
t.Fatal(err)
}
return result, engine
}
func TestEmbeddedPromptsPrepareWithNativeContracts(t *testing.T) {
t.Parallel()
_, engine := loadNativeAssets(t)
// Discover the actual declarations as well as the composed inventory, so an
// accidentally omitted import cannot silently remove a module's coverage.
err := fs.WalkDir(assets.FS(), ".", func(file string, entry fs.DirEntry, err error) error {
if err != nil {
return err
}
if entry.IsDir() || path.Base(file) != "prompt.yaml" {
return nil
}
data, err := fs.ReadFile(assets.FS(), file)
if err != nil {
return err
}
var declared struct {
Prompts []promptkit.PromptSettings `yaml:"prompts"`
}
if err := yaml.Unmarshal(data, &declared); err != nil {
return err
}
if len(declared.Prompts) == 0 {
return fmt.Errorf("%s has no native prompts", file)
}
for _, prompt := range declared.Prompts {
t.Run(prompt.ID, func(t *testing.T) {
inputs := make(map[string]promptkit.ArtifactRef)
for _, input := range prompt.Inputs {
inputs[input.Name] = promptkit.Inline(input.Name + "-fixture")
}
request := promptkit.RunRequest{PromptID: "notarius/" + prompt.ID, Inputs: inputs, APIKey: "fixture-key"}
if prompt.DefaultProfile == nil {
request.ProfileID = "notarius/dnd-extraction"
}
prepared, err := engine.PrepareExecution(context.Background(), request)
if err != nil {
t.Fatal(err)
}
defer prepared.Discard()
details := prepared.Details()
if details.OutputContract.Format != promptkit.FormatJSON || details.OutputContract.ValidationMode != promptkit.ValidationJSONSchema || details.StructuredOutput == nil || details.StructuredOutput.JSONSchema == nil {
t.Fatalf("missing native schema contract: %#v", details.OutputContract)
}
// Preparation must load the real self-contained schema, not merely retain
// a filename or use a separate application schema registry.
schemaBytes, err := fs.ReadFile(assets.FS(), details.OutputContract.SchemaPath)
if err != nil {
t.Fatal(err)
}
var expected any
if err := json.Unmarshal(schemaBytes, &expected); err != nil {
t.Fatal(err)
}
actualBytes, err := json.Marshal(details.StructuredOutput.JSONSchema.Schema)
if err != nil {
t.Fatal(err)
}
var actual any
if err := json.Unmarshal(actualBytes, &actual); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(actual, expected) {
t.Fatal("prepared schema differs from the owned asset")
}
first := prompt.Messages[0]
if first.ContentFile == nil {
t.Fatal("expected a source-relative initial message")
}
content, err := fs.ReadFile(assets.FS(), path.Join(path.Dir(file), *first.ContentFile))
if err != nil {
t.Fatal(err)
}
if first.Role == nil || len(details.Messages) == 0 || details.Messages[0].Role != *first.Role {
t.Fatal("declared message role was not preserved")
}
if !strings.Contains(string(content), "{{") && strings.TrimSpace(details.Messages[0].Content) != strings.TrimSpace(string(content)) {
t.Fatal("source-relative message content was not preserved")
}
})
}
return nil
})
if err != nil {
t.Fatal(err)
}
}
func TestRegistryNormalizationPromptPairsRetainTheirNativeContracts(t *testing.T) {
_, engine := loadNativeAssets(t)
for _, test := range []struct {
id string
guidance string
rules []string
}{
{"notarius/dnd.npc_registry.normalize", "Preserve distinct individuals.", []string{"same individual", "unadorned proper name"}},
{"notarius/dnd.location_registry.normalize", "Keep parent and child places separate.", []string{"same physical place", "parent and child places"}},
} {
t.Run(test.id, func(t *testing.T) {
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: test.id, APIKey: "test-only", Inputs: map[string]promptkit.ArtifactRef{
"candidates": promptkit.Inline(`{"candidate_number_range":{"first":1,"last":2},"candidates":[]}`),
"transcript": promptkit.Inline(`{"windows":[]}`),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: test.id + ".repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline(test.guidance)},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || next.SelectedProfileID != first.SelectedProfileID ||
first.StructuredOutput == nil || next.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("normalization pair lost its shared native defaults/output contract")
}
var system string
for _, message := range first.Messages {
if message.Role == "system" {
system += message.Content
}
}
for _, rule := range append(test.rules, "candidate_number_range", "start_unit_id", "canonical_candidate_number") {
if !strings.Contains(system, rule) {
t.Fatalf("missing enduring system principle %q", rule)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, test.guidance) {
t.Fatal("correction did not supply only the findings and replacement assignment")
}
})
}
}
func TestEmbeddedProfileRetainsSelectedExecutionDefaults(t *testing.T) {
t.Parallel()
_, engine := loadNativeAssets(t)
profile, err := engine.InspectProfile(context.Background(), "notarius/dnd-extraction")
if err != nil {
t.Fatal(err)
}
if profile.Backend == nil || *profile.Backend != "openrouter" ||
profile.Model == nil || *profile.Model != "openai/gpt-5.6-luna" ||
profile.TimeoutSeconds == nil || *profile.TimeoutSeconds != 240 ||
profile.ServiceTier == nil || *profile.ServiceTier != "flex" || profile.ReasoningEffort != nil {
t.Fatalf("changed extraction defaults: %#v", profile)
}
}

View File

@@ -1,24 +1,11 @@
package register
package assets_test
import (
"context"
"reflect"
"strings"
"testing"
"time"
"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
combatextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/combatturns"
enemyeventextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/enemyevents"
itemoccurrenceextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/itemoccurrences"
itemregistryextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/itemregistry"
locationoccurrenceextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/locationoccurrences"
locationextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/locationregistry"
occurrenceextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/npcoccurrences"
npcextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/npcregistry"
scenedescriptionextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/scenedescriptions"
spellextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/spells"
"gitea.maximumdirect.net/eric/promptkit"
"go.maximumdirect.net/promptkit"
)
func TestExtractionPromptComposition(t *testing.T) {
@@ -33,11 +20,7 @@ func TestExtractionPromptComposition(t *testing.T) {
endpointOrderSentinel = "according to transcript order"
combatPolicySentinel = "substantive active combat materially organizes the"
)
registry := llm.NewAssetRegistry()
if err := registerPromptAssets(registry); err != nil {
t.Fatalf("registerPromptAssets() error = %v", err)
}
engine := newPromptCacheEngine(t, registry)
_, engine := loadNativeAssets(t)
commonInputs := map[string]promptkit.ArtifactRef{
"transcript": promptkit.InlineWithURI("file:///session.json", `{"sentinel":"`+transcriptSentinel+`"}`),
"players": promptkit.Inline(playersSentinel),
@@ -47,31 +30,28 @@ func TestExtractionPromptComposition(t *testing.T) {
cases := []struct {
name string
promptID string
promptVersion string
inputs map[string]promptkit.ArtifactRef
suffixGroups [][]string
middleSentinel string
}{
{name: "npcs", promptID: npcextract.PromptID, promptVersion: npcextract.SchemaVersion, inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "locations", promptID: locationextract.PromptID, promptVersion: locationextract.SchemaVersion, inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "item occurrences", promptID: itemoccurrenceextract.PromptID, promptVersion: itemoccurrenceextract.SchemaVersion, inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
{name: "npcs", promptID: "notarius/dnd.npc_registry", inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "locations", promptID: "notarius/dnd.location_registry", inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "item occurrences", promptID: "notarius/dnd.item_occurrences", inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"item_registry": promptkit.Inline(`{"items":[{"id":"item-registry-sentinel","name":"Torch"}]}`),
}), suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}, {"item-registry-sentinel"}}},
{name: "item registry", promptID: itemregistryextract.PromptID, promptVersion: itemregistryextract.SchemaVersion, inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "scene descriptions", promptID: scenedescriptionextract.PromptID, promptVersion: scenedescriptionextract.SchemaVersion, inputs: commonInputs, middleSentinel: combatPolicySentinel},
{name: "item registry", promptID: "notarius/dnd.item_registry", inputs: commonInputs, suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}}},
{name: "scene descriptions", promptID: "notarius/dnd.scene_descriptions", inputs: commonInputs, middleSentinel: combatPolicySentinel},
{
name: "combat turns",
promptID: combatextract.PromptID,
promptVersion: combatextract.SchemaVersion,
name: "combat turns",
promptID: "notarius/dnd.combat_turns",
inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"npc_registry": promptkit.Inline(`{"sentinel":"` + npcSentinel + `"}`),
}),
suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}, {npcSentinel}},
},
{
name: "enemy events",
promptID: enemyeventextract.PromptID,
promptVersion: enemyeventextract.SchemaVersion,
name: "enemy events",
promptID: "notarius/dnd.enemy_events",
inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"npc_registry": promptkit.Inline(`{"sentinel":"` + npcSentinel + `"}`),
"combat_turns": promptkit.Inline(`{"sentinel":"combat-turns-sentinel"}`),
@@ -84,27 +64,24 @@ func TestExtractionPromptComposition(t *testing.T) {
},
},
{
name: "npc occurrences",
promptID: occurrenceextract.PromptID,
promptVersion: occurrenceextract.SchemaVersion,
name: "npc occurrences",
promptID: "notarius/dnd.npc_occurrences",
inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"npc_registry": promptkit.Inline(`{"sentinel":"` + npcSentinel + `"}`),
}),
suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}, {npcSentinel}},
},
{
name: "location occurrences",
promptID: locationoccurrenceextract.PromptID,
promptVersion: locationoccurrenceextract.SchemaVersion,
name: "location occurrences",
promptID: "notarius/dnd.location_occurrences",
inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"location_registry": promptkit.Inline(`{"sentinel":"location-registry-sentinel"}`),
}),
suffixGroups: [][]string{{evidenceSentinel, endpointOrderSentinel}, {"location-registry-sentinel"}},
},
{
name: "spells",
promptID: spellextract.PromptID,
promptVersion: spellextract.SchemaVersion,
name: "spells",
promptID: "notarius/dnd.spells",
inputs: withPromptInputs(commonInputs, map[string]promptkit.ArtifactRef{
"npc_registry": promptkit.Inline(`{"sentinel":"` + npcSentinel + `"}`),
"spell_catalog": promptkit.Inline(`{"sentinel":"` + catalogSentinel + `"}`),
@@ -113,18 +90,19 @@ func TestExtractionPromptComposition(t *testing.T) {
},
}
var sharedPrefix []promptkit.RenderedMessage
for _, testCase := range cases {
t.Run(testCase.name, func(t *testing.T) {
prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
PromptID: testCase.promptID,
PromptVersion: testCase.promptVersion,
ProfileID: "prompt-cache-test-profile",
Inputs: testCase.inputs,
handle, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: testCase.promptID,
APIKey: "test-only",
ProfileID: "notarius/dnd-extraction",
Inputs: testCase.inputs,
})
if err != nil {
t.Fatalf("Prepare() error = %v", err)
t.Fatalf("PrepareExecution() error = %v", err)
}
defer handle.Discard()
prepared := handle.Details()
transcriptIndex := renderedInputMessageIndex(t, prepared.Messages, transcriptSentinel)
referenceIndex := renderedInputMessageIndex(t, prepared.Messages, playersSentinel)
if referenceIndex >= transcriptIndex {
@@ -132,15 +110,6 @@ func TestExtractionPromptComposition(t *testing.T) {
}
assertEphemeralCache(t, prepared.Messages, referenceIndex)
assertEphemeralCache(t, prepared.Messages, transcriptIndex)
prefix := prepared.Messages[:transcriptIndex+1]
if len(prepared.Messages) <= len(prefix) {
t.Fatalf("prepared prompt has %d messages, want lane-specific suffix after transcript", len(prepared.Messages))
}
if sharedPrefix == nil {
sharedPrefix = append([]promptkit.RenderedMessage(nil), prefix...)
} else if !reflect.DeepEqual(prefix, sharedPrefix) {
t.Fatalf("rendered prefix = %#v, want %#v", prefix, sharedPrefix)
}
previousIndex := transcriptIndex
for _, group := range testCase.suffixGroups {
groupIndex := -1
@@ -172,22 +141,6 @@ func TestExtractionPromptComposition(t *testing.T) {
}
}
func newPromptCacheEngine(t *testing.T, registry *llm.AssetRegistry) *promptkit.Engine {
t.Helper()
options, err := registry.PromptKitOptions()
if err != nil {
t.Fatalf("PromptKitOptions() error = %v", err)
}
options = append(options, promptkit.WithProfiles(promptkit.OpenAICompatibleProfile(promptkit.OpenAICompatibleProfileConfig{
ID: "prompt-cache-test-profile", Endpoint: "http://127.0.0.1:1/v1", Model: "prompt-cache-test-model",
})))
engine, err := promptkit.NewEngine(promptkit.Config{Timeout: time.Second}, options...)
if err != nil {
t.Fatalf("NewEngine() error = %v", err)
}
return engine
}
func withPromptInputs(inputs, extras map[string]promptkit.ArtifactRef) map[string]promptkit.ArtifactRef {
merged := make(map[string]promptkit.ArtifactRef, len(inputs)+len(extras))
for name, input := range inputs {

View File

@@ -0,0 +1,120 @@
package assets_test
import (
"context"
"encoding/json"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/promptkit"
)
func TestRegistryExtractionPromptPairsRetainDomainRulesAndContracts(t *testing.T) {
_, engine := loadNativeAssets(t)
for _, test := range []struct {
family, instruction string
rules []string
}{
{"npc", "Revise the NPC citations.", []string{"proper name or a stable, individually distinguishing", "factual third-party mention", "Exclude human players"}},
{"item", "Revise the item citations.", []string{"named unique items", "concrete reusable item types", "currency denomination", "generic weapons", "Do not use capitalization as an eligibility test"}},
{"location", "Revise the location citations.", []string{"stable proper name or unique in-world designation", "the room", "Do not use capitalization as an eligibility test"}},
} {
t.Run(test.family, func(t *testing.T) {
id := "notarius/dnd." + test.family + "_registry"
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: id, APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(`{"units":[{"sentinel":"registry-transcript"}]}`),
"players": promptkit.Inline("registry-players"), "party": promptkit.Inline("registry-party"), "glossary": promptkit.Inline("registry-glossary"),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
next, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: id + ".repair", APIKey: "test-only", Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline(test.instruction)},
})
if err != nil {
t.Fatal(err)
}
defer next.Discard()
first, correction := initial.Details(), next.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || correction.SelectedProfileID != first.SelectedProfileID ||
first.StructuredOutput == nil || correction.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, correction.OutputContract) {
t.Fatal("registry prompt pair lost native schema/defaults")
}
var system, all string
for _, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
if strings.Contains(message.Content, "registry-transcript") || strings.Contains(message.Content, "registry-players") {
if message.CacheControl == nil || message.CacheControl.Type != promptkit.CacheControlEphemeral {
t.Fatal("fixed input cache hint lost")
}
}
}
for _, rule := range append(test.rules, "Transcript units are the only evidence", "Use the most specific supported in-world") {
if !strings.Contains(strings.Join(strings.Fields(system), " "), rule) {
t.Fatalf("missing enduring domain rule %q", rule)
}
}
for _, input := range []string{"registry-transcript", "registry-players", "registry-party", "registry-glossary"} {
if strings.Count(all, input) != 1 {
t.Fatalf("fixed input not rendered once: %q", input)
}
}
if len(correction.Messages) != 1 || correction.Messages[0].Role != "user" || !strings.Contains(correction.Messages[0].Content, test.instruction) ||
strings.Contains(correction.Messages[0].Content, "registry-transcript") {
t.Fatal("correction repeated fixed inputs instead of supplying findings/assignment")
}
})
}
}
func TestRegistryResponseSchemasSeparateStructureFromSemanticValidity(t *testing.T) {
for _, test := range []struct{ family, field string }{
{"npc", "npcs"}, {"item", "items"}, {"location", "locations"},
} {
t.Run(test.family, func(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/"+test.family+"-registry/extract/schemas/dnd_"+test.family+"_registry_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, value := range []struct {
name, record string
valid bool
}{
{"grounded record", `{"name":"Canonical Name","source_refs":[{"start_unit_id":1,"end_unit_id":2}]}`, true},
{"blank name and empty evidence", `{"name":"","source_refs":[]}`, true},
{"nonpositive source candidate", `{"name":"Canonical Name","source_refs":[{"start_unit_id":0,"end_unit_id":-1}]}`, true},
{"missing name", `{"source_refs":[]}`, false},
{"opaque ID", `{"name":"Canonical Name","source_refs":[],"id":"assigned-later"}`, false},
{"wrong name type", `{"name":7,"source_refs":[]}`, false},
{"noninteger source identifier", `{"name":"Canonical Name","source_refs":[{"start_unit_id":1.5,"end_unit_id":2}]}`, false},
} {
t.Run(value.name, func(t *testing.T) {
content := []byte(`{"` + test.field + `":[` + value.record + `]}`)
if err := validateJSONSchema(content, schema); (err == nil) != value.valid {
t.Fatalf("schema validity=%t, error=%v", value.valid, err)
}
})
}
for _, content := range []string{`{"` + test.field + `":[]}`, `{"` + test.field + `":null}`, `{}`} {
var value map[string]any
if err := json.Unmarshal([]byte(content), &value); err != nil {
t.Fatal(err)
}
_, isArray := value[test.field].([]any)
if err := validateJSONSchema([]byte(content), schema); (err == nil) != isArray {
t.Fatalf("collection shape %s: %v", content, err)
}
}
})
}
}

View File

@@ -0,0 +1,120 @@
package assets_test
import (
"context"
"encoding/json"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"go.maximumdirect.net/promptkit"
)
func TestSceneResponseSchemaUsesStrictPrivateContract(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/scene-descriptions/schemas/dnd_scene_descriptions_llm.v1.json")
if err != nil {
t.Fatal(err)
}
valid := map[string]any{"kind": "narrative", "title": "Arrival", "summary": "The party enters the tower."}
if err := validateSceneResponse(t, valid, schema); err != nil {
t.Fatalf("valid private response rejected: %v", err)
}
for _, test := range []struct {
name string
response map[string]any
valid bool
}{
{name: "missing required field", response: map[string]any{"kind": "combat", "title": "Ambush"}},
{name: "unknown framework field", response: map[string]any{"kind": "combat", "title": "Ambush", "summary": "Bandits strike.", "id": "assigned-later"}},
{name: "unknown application field", response: map[string]any{"kind": "combat", "title": "Ambush", "summary": "Bandits strike.", "source_ref": map[string]any{}}},
{name: "collection is not allowed", response: map[string]any{"kind": "combat", "title": "Ambush", "summary": "Bandits strike.", "scenes": []any{}}},
{name: "unsupported kind", response: map[string]any{"kind": "interlude", "title": "Ambush", "summary": "Bandits strike."}},
{name: "empty title", response: map[string]any{"kind": "combat", "title": "", "summary": "Bandits strike."}, valid: true},
{name: "empty summary", response: map[string]any{"kind": "combat", "title": "Ambush", "summary": ""}, valid: true},
{name: "wrong kind type", response: map[string]any{"kind": 7, "title": "Ambush", "summary": "Bandits strike."}},
{name: "wrong title type", response: map[string]any{"kind": "combat", "title": 7, "summary": "Bandits strike."}},
{name: "wrong summary type", response: map[string]any{"kind": "combat", "title": "Ambush", "summary": 7}},
} {
t.Run(test.name, func(t *testing.T) {
err := validateSceneResponse(t, test.response, schema)
if (err == nil) != test.valid {
t.Fatalf("validateJSONSchema() error = %v, want valid=%t", err, test.valid)
}
})
}
if err := validateJSONSchema([]byte(`{"kind":`), schema); err == nil {
t.Fatal("validateJSONSchema() error = nil, want malformed JSON rejected")
}
}
func TestSceneResponseSchemaAcceptsEverySupportedKind(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/scene-descriptions/schemas/dnd_scene_descriptions_llm.v1.json")
if err != nil {
t.Fatal(err)
}
for _, kind := range []string{"combat", "narrative", "recap", "meta"} {
response := map[string]any{"kind": kind, "title": "Title", "summary": "Summary"}
if err := validateSceneResponse(t, response, schema); err != nil {
t.Fatalf("supported scene kind %q was rejected: %v", kind, err)
}
}
}
func validateSceneResponse(t *testing.T, instance map[string]any, schemaContent []byte) error {
t.Helper()
content, err := json.Marshal(instance)
if err != nil {
t.Fatal(err)
}
return validateJSONSchema(content, schemaContent)
}
func TestSceneDescriptionPromptPairRetainsPolicyAndFixedInputs(t *testing.T) {
_, engine := loadNativeAssets(t)
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.scene_descriptions", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(`{"units":[{"text":"scene-description-transcript"}]}`),
"players": promptkit.Inline("scene-description-player"), "party": promptkit.Inline(" "), "glossary": promptkit.Inline(" "),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.scene_descriptions.repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline("Return kind: combat for this scene.")},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || first.SelectedProfileID != next.SelectedProfileID || first.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("scene pair lost schema/defaults")
}
var system, all string
for _, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
}
for _, rule := range []string{"complete chunk is the evidence boundary", "substantive active combat materially organizes the", "must not invent a proper noun"} {
if !strings.Contains(strings.Join(strings.Fields(system), " "), rule) {
t.Fatalf("missing enduring rule %q", rule)
}
}
for _, material := range []string{"scene-description-transcript", "scene-description-player", "substantive active combat materially organizes the"} {
if strings.Count(all, material) != 1 {
t.Fatalf("fixed input/policy repeated: %q", material)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, "Return kind: combat for this scene.") || strings.Contains(next.Messages[0].Content, "scene-description-transcript") {
t.Fatal("correction assignment lost findings or repeated source")
}
}

184
assets/scenes_test.go Normal file
View File

@@ -0,0 +1,184 @@
package assets_test
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io/fs"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/assets"
"github.com/santhosh-tekuri/jsonschema/v6"
"go.maximumdirect.net/promptkit"
)
func TestScenePromptPairPreservesFullTranscriptAndContext(t *testing.T) {
_, engine := loadNativeAssets(t)
const transcript = `{"sentinel":"scene-transcript"}`
initial, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.scenes", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{
"transcript": promptkit.Inline(transcript),
"players": promptkit.Inline("scene-players"),
"party": promptkit.Inline("scene-party"),
"glossary": promptkit.Inline("scene-glossary"),
},
})
if err != nil {
t.Fatal(err)
}
defer initial.Discard()
correction, err := engine.PrepareExecution(context.Background(), promptkit.RunRequest{
PromptID: "notarius/dnd.scenes.repair", APIKey: "test-only",
Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline("Keep the encounter together.")},
})
if err != nil {
t.Fatal(err)
}
defer correction.Discard()
first, next := initial.Details(), correction.Details()
if first.SelectedProfileID != "notarius/dnd-extraction" || next.SelectedProfileID != first.SelectedProfileID ||
first.StructuredOutput == nil || next.StructuredOutput == nil || !reflect.DeepEqual(first.OutputContract, next.OutputContract) {
t.Fatal("scene correction pair lost its shared native defaults/output contract")
}
var system, all string
transcriptIndex := -1
for i, message := range first.Messages {
all += message.Content
if message.Role == "system" {
system += message.Content
}
if strings.Contains(message.Content, transcript) {
transcriptIndex = i
}
if strings.Contains(message.Content, transcript) || strings.Contains(message.Content, "scene-players") {
if message.CacheControl == nil || message.CacheControl.Type != promptkit.CacheControlEphemeral {
t.Fatal("reference/full-transcript native cache hint lost")
}
}
}
if transcriptIndex != len(first.Messages)-1 || !strings.Contains(system, "no gaps or overlaps") || !strings.Contains(system, "coherent unit of play") {
t.Fatal("scene principles or complete final transcript lost")
}
for _, content := range []string{transcript, "scene-players", "scene-party", "scene-glossary"} {
if strings.Count(all, content) != 1 {
t.Fatalf("fixed context not rendered once: %q", content)
}
}
if len(next.Messages) != 1 || next.Messages[0].Role != "user" || !strings.Contains(next.Messages[0].Content, "Keep the encounter together.") ||
strings.Contains(next.Messages[0].Content, "scene-transcript") {
t.Fatal("correction should supply findings and a replacement assignment only")
}
}
func TestResponseSchemaValidatesMinimalSceneResponses(t *testing.T) {
schema, err := fs.ReadFile(assets.FS(), "dnd/scenes/schemas/dnd_scenes_llm.v1.json")
if err != nil {
t.Fatalf("loadResponseSchema() error = %v, want nil", err)
}
valid := validSceneSchemaResponse()
validJSON, err := json.Marshal(valid)
if err != nil {
t.Fatalf("Marshal(validSceneSchemaResponse()) error = %v, want nil", err)
}
if err := validateJSONSchema(validJSON, schema); err != nil {
t.Fatalf("valid scene response rejected: %v", err)
}
tests := []struct {
name string
mutate func(map[string]any)
}{
{
name: "missing scenes",
mutate: func(response map[string]any) {
delete(response, "scenes")
},
},
{
name: "empty scenes",
mutate: func(response map[string]any) {
response["scenes"] = []any{}
},
},
{
name: "non-positive start unit",
mutate: func(response map[string]any) {
response["scenes"].([]any)[0].(map[string]any)["start_unit_id"] = 0
},
},
{
name: "non-positive end unit",
mutate: func(response map[string]any) {
response["scenes"].([]any)[0].(map[string]any)["end_unit_id"] = 0
},
},
{
name: "non-integer endpoint",
mutate: func(response map[string]any) {
response["scenes"].([]any)[0].(map[string]any)["start_unit_id"] = 1.5
},
},
{
name: "unknown top-level field",
mutate: func(response map[string]any) {
response["boundary_caveats"] = []any{}
},
},
{
name: "unknown scene field",
mutate: func(response map[string]any) {
response["scenes"].([]any)[0].(map[string]any)["short_title"] = "Old contract"
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
response := validSceneSchemaResponse()
tt.mutate(response)
content, err := json.Marshal(response)
if err != nil {
t.Fatalf("Marshal() error = %v, want nil", err)
}
if err := validateJSONSchema(content, schema); err == nil {
t.Fatal("validateJSONSchema() error = nil, want rejected response")
}
})
}
}
func validSceneSchemaResponse() map[string]any {
return map[string]any{
"scenes": []any{
map[string]any{
"start_unit_id": 1,
"end_unit_id": 3,
},
},
}
}
func validateJSONSchema(instanceContent, schemaContent []byte) error {
instance, err := jsonschema.UnmarshalJSON(bytes.NewReader(instanceContent))
if err != nil {
return fmt.Errorf("parse instance: %w", err)
}
schemaDocument, err := jsonschema.UnmarshalJSON(bytes.NewReader(schemaContent))
if err != nil {
return fmt.Errorf("parse schema: %w", err)
}
compiler := jsonschema.NewCompiler()
if err := compiler.AddResource("schema.json", schemaDocument); err != nil {
return fmt.Errorf("load schema: %w", err)
}
schema, err := compiler.Compile("schema.json")
if err != nil {
return fmt.Errorf("compile schema: %w", err)
}
return schema.Validate(instance)
}

View File

@@ -1,4 +1,4 @@
package register
package assets_test
import (
"encoding/json"
@@ -8,25 +8,18 @@ import (
"strings"
"testing"
"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
"gitea.maximumdirect.net/eric/notarius/assets"
)
func TestRegisteredResponseSchemasRequireEveryObjectProperty(t *testing.T) {
assets := llm.NewAssetRegistry()
if err := Register(completeRegistries(), assets); err != nil {
t.Fatal(err)
}
schemaFS, err := assets.SchemaFS()
if err != nil {
t.Fatal(err)
}
func TestModelResponseSchemasRequireEveryObjectProperty(t *testing.T) {
schemaFS := assets.FS()
count := 0
err = fs.WalkDir(schemaFS, ".", func(path string, entry fs.DirEntry, walkErr error) error {
err := fs.WalkDir(schemaFS, ".", func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() || !strings.HasSuffix(path, ".json") {
if entry.IsDir() || !strings.HasSuffix(path, "_llm.v1.json") {
return nil
}
content, err := fs.ReadFile(schemaFS, path)
@@ -46,7 +39,7 @@ func TestRegisteredResponseSchemasRequireEveryObjectProperty(t *testing.T) {
t.Fatal(err)
}
if count == 0 {
t.Fatal("no registered response schemas found")
t.Fatal("no model response schemas found")
}
}

View File

@@ -1,11 +1,26 @@
package main
import (
"context"
"fmt"
"os"
"gitea.maximumdirect.net/eric/notarius/internal/buildinfo"
"gitea.maximumdirect.net/eric/notarius/internal/cli"
"go.maximumdirect.net/commandkit"
)
func main() {
os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr))
version, err := buildinfo.Version()
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
app, err := cli.NewApplication(version, cli.Options{})
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
outcome := app.Execute(context.Background(), os.Args[1:], commandkit.Streams{Out: os.Stdout, Err: os.Stderr})
os.Exit(outcome.Status)
}

View File

@@ -1,6 +1,10 @@
# ADR-0004: Package modules by domain, not by stage
**Status:** Accepted — its asset-co-location rule is superseded by [ADR-0011](0011-centralize-llm-assets.md); its domain-first module packaging decision remains accepted.
**Status:** Accepted in part. Asset co-location is superseded by
[ADR-0011](0011-centralize-llm-assets.md), and prompt/schema registration by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
Domain-first packaging, typed domain ownership, and registrar dependency direction
remain accepted.
**Date:** 2026-07-13
## Context

View File

@@ -1,6 +1,9 @@
# ADR-0005: Cache one canonical chunk plan per source
**Status:** Accepted
**Status:** Superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md). Source-addressed plan
semantics and deterministic materialization remain; source-only canonical reuse
and its separate store do not.
**Date:** 2026-07-17
## Context

View File

@@ -1,6 +1,12 @@
# ADR-0006: Separate output, cache, and debug state
**Status:** Superseded by [ADR-0007](0007-separate-checkpoint-recording-from-reuse.md)
**Status:** Accepted in part. The checkpoint invocation policy was superseded by
[ADR-0007](0007-separate-checkpoint-recording-from-reuse.md); the two-cache model
is now superseded by [ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md),
and required output records and the debug summary/trace split by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Independent output/cache/debug surfaces, explicit debug selection, and
operator-owned retention remain accepted.
**Date:** 2026-07-17
## Context

View File

@@ -1,6 +1,8 @@
# ADR-0007: Separate checkpoint recording from reuse
**Status:** Accepted
**Status:** Superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md), which replaces
checkpoint recording/resume with unified accepted-result reuse.
**Date:** 2026-07-19
## Context

View File

@@ -1,6 +1,13 @@
# ADR-0010: Use workload-oriented LLM profile defaults
**Status:** Accepted
**Status:** Accepted in part. Profile source replacement was superseded by
[ADR-0019](0019-adopt-native-promptkit-configuration.md), whose native source
boundary is now superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
Checkpoint identity is superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
Workload-oriented defaults, D&D-owned profile policy, binding exceptions, and
run-wide profile precedence remain accepted.
**Date:** 2026-08-03
## Context

View File

@@ -1,6 +1,11 @@
# ADR-0011: Centralize LLM-facing assets in a content-only package
**Status:** Accepted
**Status:** Accepted in part. Asset manifests, module schema registration, and
scoped source assembly are superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md);
checkpoint fingerprints are superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
The content-only root assets leaf and domain semantic ownership remain accepted.
**Date:** 2026-08-05
## Context

View File

@@ -1,6 +1,9 @@
# ADR-0013: Use request-local candidate handles for semantic reconciliation
**Status:** Accepted
**Status:** Accepted; only the checkpoint-fingerprint requirement is superseded by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md).
Request-local handles, fixed mapping, domain ownership, and safe typed application
remain accepted.
**Date:** 2026-08-09
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0014: Use feedback-aware validation retries
**Status:** Accepted
**Status:** Superseded by
[ADR-0022](0022-use-native-continuation-and-application-assessment.md) for execution,
assessment, and disposition, and
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md) for
diagnostic persistence. Guidance remains separate from operator diagnostics.
**Date:** 2026-08-26
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0015: Separate process warnings from quality diagnostics
**Status:** Accepted
**Status:** Accepted in part. Durable warning/diagnostic files and receipt
presentation are superseded by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Process-warning classification, module-owned meaning, and bounded origin-aware
aggregation remain accepted.
**Date:** 2026-08-27
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0016: Use feedback-aware module-requested retries
**Status:** Accepted
**Status:** Superseded by
[ADR-0022](0022-use-native-continuation-and-application-assessment.md) for execution,
assessment, and fallback, and
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md) for
diagnostic persistence. Module-authored guidance remains distinct from diagnostics.
**Date:** 2026-08-28
## Context

View File

@@ -1,6 +1,10 @@
# ADR-0018: Adopt ConfigKit for configuration loading
**Status:** Accepted
**Status:** Accepted in part. The version 5 and dependency API selection is
superseded by [ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md).
ConfigKit adoption, application semantic ownership, and discovery-only environment
selection remain, as clarified by
[ADR-0020](0020-delegate-configuration-mechanics-to-configkit.md).
**Date:** 2026-09-13
## Context

View File

@@ -0,0 +1,96 @@
# ADR-0019: Adopt native PromptKit configuration sources
**Status:** Superseded by
[ADR-0021](0021-compose-native-kits-and-prompt-declared-resources.md) for native
composition, resource ownership, and execution types, and
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md) for cache identity.
ConfigKit-owned mechanics and captured source contexts remain in force.
**Date:** 2026-10-04
## Context
PromptKit v0.12 replaces its former source options with ConfigKit-backed
configuration sources, keyed documents, recursive overlays, and native
inheritance. Notarius must choose how application-owned prompt and fallback
assets, operator configuration, and the optional local backend reach PromptKit
without recreating source parsing or inheritance in the adapter. Runtime,
preflight, and operator inspection must agree about the effective definitions.
Notarius also captures checkpoint identity for the PromptKit configuration
used by an execution engine. That identity must follow the engine's captured
definition state rather than re-reading mutable source files, and must not
publish credentials, prompt bodies, provider parameters, or source paths.
## Decision
Use PromptKit's public v0.12 native source APIs as the only PromptKit
configuration boundary. Assemble PromptKit catalogs, registered application
prompt and fallback inputs, the optional operator file or recursively selected
directory, and the optional Notarius local backend registration in that order.
Use native ConfigKit imports and PromptKit/ConfigKit composition behavior;
retain each filesystem input's resource context. Inputs within a group compose
strictly, and later groups recursively overlay earlier ones. PromptKit owns
definition parsing, exact-key `extends` inheritance, and final effective-value
validation. Notarius does not provide a legacy parser, compatibility alias,
filename-priority merger, whole-profile replacement shim, or alternate
inheritance engine.
Execution, explicit-profile preflight, and configuration inspection use the
same source construction. Each constructed engine captures its effective
definitions. Edits to source files take effect for a newly constructed engine,
not an existing one. Derive the private versioned
`promptkit_configuration` checkpoint identity from public captured inspection
and definition APIs, including effective configuration, profile targets and
credential-policy metadata, captured prompt hashes, and the PromptKit and
selected catalog identities. Retain only the digest as checkpoint metadata;
keep all digest inputs private. Exclude local-backend concurrency settings
because they affect scheduling rather than execution semantics.
Keep PromptKit types and source assembly inside the LLM integration boundary.
The CLI may project copied profile fields into a Notarius-owned neutral JSON
contract. PromptKit's effective and explanation reports remain upstream
redacted configuration and source-history views. Neither inspection path reads
credential values or contacts a provider.
## Compatibility
The migration to v0.12 keyed configuration is an intentional external file
format change. Operators must migrate `id`/`version` embedded fields and
`base_profile` to native keyed documents and `extends`. Notarius does not
silently accept the former option-based API or file format. Notarius's own
version 5 configuration contract and loader decision in
[ADR-0018](0018-adopt-configkit.md) remain in force; this decision concerns
PromptKit definitions and source composition.
The workload-oriented profile identity and D&D fallback ownership in
[ADR-0010](0010-workload-oriented-llm-profile-defaults.md) remain in force.
Only that ADR's former claim that a matching operator profile completely
replaces the fallback has been superseded: native recursive overlays retain
unspecified inherited fields.
## Alternatives considered
- Keep the removed PromptKit option-based configuration API or add a
compatibility parser. This would fork the supported upstream contract and
preserve legacy format machinery.
- Merge profile documents inside Notarius or restore whole-profile
replacement. This would duplicate upstream composition behavior and make
inspection, preflight, and runtime easier to diverge.
- Re-read and hash source files for checkpoint identity. This could describe
mutable files rather than the definitions captured by the engine and would
duplicate upstream discovery and composition.
- Expose upstream inspection structs directly as CLI output. This would bind
the public Notarius contract to dependency-owned Go types.
## Consequences
PromptKit remains the owner of its native configuration semantics, while
Notarius owns which registered and operator sources are assembled and when an
engine is reconstructed. A valid later overlay can supersede an earlier
definition; validation applies to the final effective definitions rather than
as a separate audit of every superseded value. Configuration reports can
contain ordinary prompt and provider parameters, so operators own the
destination and retention of explicitly requested reports even though
credential-shaped fields are redacted. PromptKit upgrades require review of
the source adapter, captured identity, reports, and the pinned upstream
contracts.

View File

@@ -0,0 +1,49 @@
# ADR-0020: Delegate configuration mechanics to ConfigKit
**Status:** Accepted
**Date:** 2026-10-04
## Context
[ADR-0018](0018-adopt-configkit.md) establishes ConfigKit as Notarius's
configuration loader. This decision clarifies the continuing ownership boundary
as ConfigKit's capabilities evolve.
## Decision
ConfigKit owns configuration mechanics: source loading, parsing, imports,
composition, overlays, inheritance, presence tracking, provenance, and
inspection. Notarius adopts those semantics through ConfigKit's public APIs.
Notarius owns application meaning: its configuration schema, version, defaults,
field normalization, validity checks, and pipeline/module compatibility. It
supplies application-specific defaults, normalization, and validation through
ConfigKit's supported extension points. Source-origin metadata supports
application rules such as declaration-relative filesystem paths.
Notarius selects configuration inputs and options through the public API.
ConfigKit resolves those inputs and delivers the final application document
with source composition and application-field normalization complete. Notarius
converts that document into its runtime configuration and performs
catalog-dependent pipeline resolution and runtime preparation afterward.
Operator-requested effective configuration and setting explanations use
ConfigKit's inspection APIs. Application validation evaluates the resolved
configuration. Changes to general configuration mechanics are pursued upstream
in ConfigKit and adopted through its supported API.
## Alternatives considered
- Application-owned configuration loading provides direct control over source
semantics and assigns parsing, composition, and provenance maintenance to
Notarius.
- Shared ownership of configuration mechanics allows local adaptations and
requires maintaining coordinated semantics across ConfigKit and Notarius.
## Consequences
ConfigKit provides a coherent configuration-resolution and inspection contract.
Notarius's configuration work concentrates on application semantics and operator
integration. Upstream upgrades are evaluated against this ownership boundary
and the application's deliberately selected requirements. This decision
clarifies ADR-0018 while retaining its adoption and application-format decisions.

View File

@@ -0,0 +1,75 @@
# ADR-0021: Compose native kits and prompt-declared resources
**Status:** Accepted
**Date:** 2026-11-22
## Context
Notarius duplicated configuration assembly, resource registration, completion
types, inspection, CLI parsing, and provider scheduling that the adopted kits
now supply. Keeping those wrappers would preserve competing ownership rather
than protect the application's typed artifact boundary.
## Decision
Use ConfigKit, PromptKit, CommandKit, ckconfig, and ckprompt directly at their
respective application boundaries. The composition root owns one application
load per selected configuration and constructs one shared native engine for
all selected model roles from that original result. Runtime and whole-app or
focused inspection share captured sources and native provenance, not a settings
reserialization or a second loader. ConfigKit retains ownership of composition
mechanics under [ADR-0020](0020-delegate-configuration-mechanics-to-configkit.md).
Version 6 replaces version 5 without a compatibility parser.
Assemble bundled provider resources, embedded application resources, and optional
operator companions beside the selected main source through native contexts and
precedence. Native declarations own qualified resources, inheritance, default
output contracts, and schema selections. PromptKit prepares schemas and owns
structural validation and repair. Application modules retain prompt meaning,
interpretation, and static resource-ID dependencies, not manifests, response-schema
registries, asset fingerprints, virtual mounts, or fallback-profile registration.
The root assets package remains an ordinary content-only embedded leaf.
Model-executing code uses native requests, results, exchanges, errors, and
observations. Pure domain models, codecs, source resolution, and deterministic
helpers remain independent. CommandKit and its integrations own standard command
declarations, parsing, inspection, and presentation; Notarius supplies loaders,
pipeline commands, request inputs, and report content. Shared loaders and offline
preflight do not allocate run storage or perform implicit provider probes.
One ready-job worker pool bounds extraction and merge/normalize continuations
together. Prerequisite waits occupy no worker; nested validation and correction
stay inside the current job. Native engine/backend admission is independent.
Inject no backend concurrency/queue defaults, cross-backend ceiling, extra queue,
or application capacity retries. Preserve stable scope ordering and cancellation
draining. A completed turn releases admission before nested assessment.
This supersedes [ADR-0019](0019-adopt-native-promptkit-configuration.md)'s old
source adapter and private-type boundary; its fingerprint policy is replaced by
[ADR-0023](0023-unify-accepted-artifact-and-plan-caching.md). It replaces the asset
registration portions of [ADR-0004](0004-package-modules-by-domain.md) and
[ADR-0011](0011-centralize-llm-assets.md), retaining domain-first packaging,
semantic ownership, and the content-only leaf. It replaces ADR-0018's version 5
selection, not [ConfigKit adoption](0018-adopt-configkit.md) or ADR-0020's ownership.
[ADR-0010](0010-workload-oriented-llm-profile-defaults.md)'s workload-oriented
profile intent remains; native qualified resources replace its older source form.
## Alternatives considered
- Keep private completion, loader, and inspection adapters. This duplicates kit
behavior and obscures the actual execution contract.
- Adopt only PromptKit and defer CommandKit. Temporary command/report wrappers
would need another cutover and could select different configuration.
- Retain a global LLM scheduler above native admission. This adds a second queue
and couples independent backends without a selected product requirement.
## Consequences
The kits are deliberate dependencies at execution and composition boundaries;
typed application assessment and durable domain artifacts remain distinct.
Upstream changes require review of the public APIs actually consumed, rather
than preservation of old wrappers. Workers do not promise a global provider-call
ceiling or backend saturation. CLI and configuration compatibility is intentionally
broken; artifact schemas are not redesigned. Exact public syntax and dependency
integration details belong in the canonical configuration, CLI, and integration
references, not copied library manuals here.

View File

@@ -0,0 +1,82 @@
# ADR-0022: Use native continuation and application assessment
**Status:** Accepted
**Date:** 2026-11-22
## Context
Private retry machinery conflated transient failures, structural repair,
semantic defects, and validator availability. Latest-response replacement also
discarded conversation history while requiring an application replay protocol.
Native execution can own those mechanics without owning domain acceptance.
## Decision
One small typed producer helper connects native execution to module functions
for fixed input preparation, interpretation, correction requests, and supported
fallback construction. The pipeline supplies the operation's typed assessor.
PromptKit owns transient retries, structural repair, growing conversation history,
and semantic turn iteration. Notarius selects the semantic-turn allowance but
does not pin omitted native repair/retry counts or extend exhausted native work
with an outer retry loop. Deterministic operations have no generic retry budget.
Each correctable producer has initial and correction prompts using the same
response schema and bundled default profile. Preserve explicit request selections
and run overrides. Enduring principles and source/reference material are supplied
initially; the correction template adds current findings and a new assignment.
Native coordination carries the exchange, without manual assistant replay or
rerendering original inputs. Each response is a complete replacement, not a patch.
Normalization applies each proposal afresh to fixed originals and candidate
handles; never union groups across turns.
Check native errors and structural validation status before interpretation,
including failed validation returned with nil Go error. A usable typed candidate
receives the complete applicable validator chain once, in configured order.
Earlier rejection does not suppress later guidance. Revisions, unchanged
candidates, and the final permitted response receive the whole chain; there is
no duplicate assessment after the helper returns.
The detecting validator or module authors actionable guidance separately from
reason codes and operator messages. Unavailable assessment is not a semantic
defect; provider failures do not become instructions. LLM validators execute
once per assessment, without their own semantic continuation loop. Native
success, stopped, and exhausted statuses do not imply application acceptance.
Strict is the application default. Explicit permissive mode may construct a
module-supported fallback after terminal nonacceptance. A fallback satisfies
intrinsic artifact and downstream invariants without ordinary semantic approval
or rerunning the normal validator chain. Failure to construct it fails normally.
Caller cancellation and undelivered responses never initiate fallback. A
result-less failed continuation cannot recover an earlier candidate. Reuse
exclusions and disclosure follow ADRs 0023 and 0024. Exact configuration precedence
and defaults belong in [Configuration](../config.md).
This supersedes [ADR-0014](0014-feedback-aware-validation-retries.md) and
[ADR-0016](0016-feedback-aware-module-requested-retries.md)'s budgets, private
candidate transport, latest-only replay, and terminal policies. It retains their
useful separation of actionable guidance from diagnostic prose and of execution
failure from detected defects. Diagnostic persistence is governed by
[ADR-0024](0024-publish-artifacts-with-native-reports-and-debug-evidence.md).
Contextual identity and request-local reconciliation safety under ADRs
[0012](0012-resolve-opaque-entity-identifiers-deterministically.md) and
[0013](0013-use-request-local-candidate-handles-for-semantic-reconciliation.md)
remain in force.
## Alternatives considered
- Retain blanket producer/validator retries. These can extend native budgets
and repeat deterministic work without information capable of fixing it.
- Keep latest-only manual replay. This duplicates conversation mechanics and
discards earlier application-visible turns.
- Let validators decide terminal disposition or revalidate every fallback.
That distributes acceptance policy and confuses qualified recovery with
ordinary validation.
## Consequences
Native execution and application acceptance are separate facts. Accumulated
history uses more context, bounded by the selected allowance. Not every failure
has a supported fallback: an empty scene description, for example, cannot meet
its required artifact shape. Permissive output is explicitly qualified and
reuse-ineligible rather than silently accepted. Paid-model quality and exact
provider-attempt parity with the retired loops are not promised.

View File

@@ -0,0 +1,82 @@
# ADR-0023: Unify accepted artifact and plan caching
**Status:** Accepted
**Date:** 2026-11-22
## Context
Source-keyed plans and fingerprinted checkpoints imposed two recovery models
and substantial identity/provenance machinery. The selected need is narrower:
reuse successful model-backed predecessors after downstream failure without
repeating their complete production and assessment.
## Decision
Use one best-effort filesystem cache for final accepted typed artifacts and
LLM-generated chunk plans. Prepare the initial native request once and use its
opaque MessageContentHash unchanged, with no additional identity dimensions.
Execute that same prepared handle on a miss and discard it on a hit. Corrections
do not change the key. Store the final accepted codec artifact, including applied
normalization, rather than a native response, exchange, or reconciliation proposal.
Message roles, exact text, boundaries, and order select reuse. Model/settings,
session, schema metadata, policy, library versions, and implementation changes
add no key dimensions. Text rendered into the messages participates as content.
Changed policy may therefore reuse old acceptance; operators deliberately choose
bypass or refresh when they want re-execution.
Hits receive ordinary codec and current-source usability checks, not renewed
semantic assessment, replayed exchanges, fabricated execution, or historical
usage. Cached plans are rematerialized against the current source. Unusable
entries miss. Deterministic operations remain uncached without synthetic requests.
Store only final ordinary acceptance. Failed, rejected, incomplete, canceled,
and fallback results cannot be stored. Fallback and actually affected dependent
work skip lookup as well as storage; unrelated accepted predecessors remain
reusable. Eligibility is a small handoff fact, not a dependency fingerprint graph.
Auto reads and stores acceptance; bypass does neither; refresh skips lookup and
replaces only after new acceptance. Failed refresh preserves earlier accepted
bytes. Cache I/O failures produce diagnostics without failing otherwise successful
work or repeating model calls. Records are plain accepted JSON, not envelopes,
manifests, acceptance ledgers, or copied source/execution histories. Exact root,
layout, and control precedence belong in configuration and operations references.
Ignore legacy checkpoint and source-plan records without importing, rewriting,
or deleting them. Remove explicit resume, recomputation barriers, and the separate
canonical-partition guarantee. Matching initial messages may reuse a plan; changed
prompt/reference/input content may select another partition. Retain plan range,
annotation, source-order, and deterministic materialization correctness.
This supersedes [ADR-0005](0005-cache-canonical-chunk-plans-by-source.md) and
[ADR-0007](0007-separate-checkpoint-recording-from-reuse.md), and the two-cache
model in [ADR-0006](0006-separate-output-cache-and-debug-state.md). It replaces
checkpoint/fingerprint clauses in ADRs
[0010](0010-workload-oriented-llm-profile-defaults.md),
[0011](0011-centralize-llm-assets.md),
[0013](0013-use-request-local-candidate-handles-for-semantic-reconciliation.md), and
[0019](0019-adopt-native-promptkit-configuration.md), not their retained domain,
content, or identity boundaries.
Apply [ADR-0017](0017-defer-cache-access-policy-to-deployment.md)'s permission
ownership to this unified cache: deployment umask, setgid, and default ACLs govern
effective access. Retain confined paths, symlink rejection, validation, atomic
publication, and recovery without permission convergence or automatic migration.
Output and debug retain independent roots and lifecycles.
## Alternatives considered
- Keep one canonical partition per source. This ignores changed initial task
content and retains a second lookup/publication mechanism.
- Use comprehensive execution or policy fingerprints. That changes the selected
reuse semantics and restores the removed compatibility bookkeeping.
- Cache native responses or restore conversations. Neither is the accepted typed
application result, and each requires replay or renewed interpretation.
## Consequences
Ordinary reruns recover reusable accepted predecessors without a resume request.
Acceptance under changed model or validation policy is not implied by a hit.
Cache is reconstructible and best effort, not an execution history or a storage
durability guarantee. Legacy data stays available for operator-managed cleanup;
no automatic conversion, expiry service, or garbage collector is introduced.

View File

@@ -0,0 +1,90 @@
# ADR-0024: Publish artifacts with native reports and debug evidence
**Status:** Accepted
**Date:** 2026-11-22
## Context
Required manifests, receipts, indexes, reporting sidecars, and copied execution
ledgers made consumers depend on accounting rather than the domain artifacts.
Split sanitized-summary/detailed-trace machinery also duplicated native evidence
and conflated useful inspection with a stable reporting protocol.
## Decision
Domain artifacts are the primary deliverables, including supported qualified
fallbacks. Preserve intrinsic schemas and existing run-specific logical paths,
including selected chunk-map/evidence auxiliaries. Consumers need no index,
manifest, persisted receipt, warnings/diagnostics sidecars, or execution ledger.
Publish artifacts, finalize requested capture, then submit one small native
completion value and human template through CommandKit. Native formats render
that same value; no separate encoder or universal envelope is introduced.
The completion report identifies the pipeline, deliverable count, publication
directory, available debug directory, and positive fallback count. Count each
operation that emits fallback once, not its affected artifacts or attempts.
Disclose fallback independently of diagnostic verbosity. Standard commands keep
their native values. [CLI Reference](../cli.md) owns exact report fields,
stdout/stderr behavior, and outcome codes.
Preserve native operation causes separately from rendering and delivery failures.
Post-publication capture/report failure returns nonzero with available locations
while retaining valid artifacts and evidence. Failed stdout can be partial;
consumers check status before decoding a successful report. Do not rerun model
work, rewrite history, or remove published files to compensate for delivery failure.
Use one native invocation ExecutionGroup, enrolling actual initial, continuation,
and nested validator executions once. Preserve native IDs, terminal coverage,
and unknown usage without parallel totals, synthetic IDs, or a profile ledger.
Cache hits contribute no execution or historical usage.
Explicit debug selection and a nonempty effective destination enable one run
recorder. A directory alone does not enable it; explicit empty disables capture.
Allocate after configuration/run identity but before engine construction/preflight.
Update the relative latest link at start, never completion. Persist convenient
run/operation evidence incrementally and finalize once before successful reporting.
Requested allocation, recording, or finalization failures fail the invocation,
retaining primary causes and whatever evidence/publication is available.
Capture fixed inputs, configuration/composition, prepared contracts, native events,
available results and full application-visible exchanges, typed candidates,
findings/guidance, correction/normalization material, fallbacks, deterministic
results, and cache decisions. Reuse prepared evidence without another preparation
or provider call. Label undelivered responses unassessed and result-less failures
with available evidence; do not fabricate missing provider bodies. Exact filenames
and serialization remain private diagnostic choices, not a public format.
Use ConfigKit secret-aware inspection and native credential omissions. Do not
directly serialize marked secrets or collect unrelated environment/filesystem
content. Do not heuristically scrub or rewrite selected source, prompts, responses,
or arbitrary strings. A debug bundle may retain sensitive application data; it
is not promised sanitized. Operators own access and retention. Do not automatically
delete output or requested bundles. Output, cache, and debug remain independent.
This replaces [ADR-0006](0006-separate-output-cache-and-debug-state.md)'s required
output records and summary/trace split while retaining its three surfaces and
explicit debug selection. It supersedes durable reporting in
[ADR-0015](0015-separate-process-warnings-from-quality-diagnostics.md), retaining
module-owned diagnostic classification and bounded framework aggregation. It
also replaces the private attempt-record restrictions of ADRs
[0014](0014-feedback-aware-validation-retries.md) and
[0016](0016-feedback-aware-module-requested-retries.md) without moving conversation
state into ordinary artifacts or cache entries.
## Alternatives considered
- Rebuild manifests and receipts with native execution data. This preserves an
unnecessary consumer dependency and another reporting model.
- Retain sanitized summaries beside sensitive traces. Heuristic content rewriting
can alter evidence without establishing a selected sanitized-bundle guarantee.
- Treat capture failures as harmless warnings or retry model work. Requested
capture is required work, but its failure cannot repair model output.
## Consequences
Consumers use configured lane/auxiliary paths and optional native reports rather
than receipt traversal. Diagnostic files can change independently of artifacts.
Debug may duplicate evidence for convenient inspection without a complete provider
transcript guarantee. Quiet presentation does not erase fallback qualification
from the report value or turn delivery failure into success. No new access policy,
automatic retention service, release gate, or release authorization is created.

View File

@@ -1,243 +1,370 @@
# CLI Reference
This is the canonical reference for the implemented Notarius command-line
interface. For the shortest successful run, see the [README](../README.md).
Configuration fields, discovery rules, and selectable module keys are defined
in [Configuration](config.md); runtime state and recovery procedures are
defined in [Operations](operations.md).
This is the canonical reference for Notarius invocation, command inputs, reports,
and outcome codes. [Configuration](config.md) owns fields, defaults, resource
selection, and module keys; [Operations](operations.md) owns runtime state;
integration contracts own domain payloads.
Notarius uses native CommandKit commands with ckconfig and ckprompt. The
[upstream CLI reference][native-cli] owns their general parser, report, inspection,
and smoke semantics. The examples below show Notarius-specific selections.
Use help for every installed command's current options.
For retired command/configuration mappings and receipt-consumer changes, see
[native migration guidance](consumers/native-migration.md).
## Command Summary
~~~
notarius help
notarius --version
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b]
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--json]
~~~text
notarius --help
notarius help pipeline run
notarius version
notarius completion bash
notarius pipeline list
notarius pipeline show PIPELINE_ID
notarius pipeline validate PIPELINE_ID
notarius pipeline run PIPELINE_ID --input-file PATH
notarius run PIPELINE_ID --input-file PATH
notarius config scopes
notarius config validate
notarius config show
notarius config sources
notarius config explain
notarius config diff
notarius promptkit list prompts
notarius promptkit show profile PROFILE_ID
notarius promptkit requirements show PROMPT_ID
notarius promptkit requirements validate PROMPT_ID
notarius promptkit show prepared PROMPT_ID
notarius promptkit test KIND
~~~
Running Notarius without arguments, or with **help**, **--help**, or **-h**,
writes the command summary to standard output and exits with status 0.
Bare invocation, `help`, `--help`, and `-h` display native help. Help also works
on subcommands without their execution-only required inputs. Help, version, and
Bash/Zsh/Fish completion need no configuration, credentials, or run storage.
`notarius --version` is valid only as the sole root argument. It writes exactly
`notarius <version>` followed by a newline to standard output and exits with
status 0. A tagged `go install` build can report its main-module stable tag,
and controlled builds can inject a stable tag at link time through
`gitea.maximumdirect.net/eric/notarius/internal/buildinfo.Override`; an ordinary
unversioned checkout reports `development`. Invalid injected version content is
a runtime error with exit status 1, while extra `--version` arguments are a
syntax error with exit status 2. This diagnostic does not replace the
[run-result](integrations/run-result.md) or artifact contracts for downstream
compatibility decisions.
`version` reports the application identity; `version --scope commandkit` selects
the library identity. Source-tagged installation and release-linked build identity
remain available; an unversioned checkout reports `development`. Version output
uses native report formats, not a custom root flag.
## run
## Syntax And Supplied Values
~~~
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
Put flags after the **complete command path**, optionally interspersed with its
operands. Value flags accept `--name value` or `--name=value`. Boolean flags
accept presence and explicit values such as `--debug=false`. `--` ends option
parsing; later tokens are operands.
Singleton flags may repeat; the last successfully parsed occurrence supplies
the value. Every occurrence is parsed, so a malformed earlier value remains an
error. Repeatable flags retain occurrence order and do not split commas.
Omission differs from supplied empty, false, and zero. Semantic validity still
depends on the selected command and native request. See
[registered syntax][syntax] for the shared rules.
## Configuration Selection
`--config PATH` fixes the main source; explicit empty fails instead of discovering
another file. Omission uses [configuration discovery](config.md#configuration-discovery-and-precedence).
Commands that support `--overlay NAME` select the native application overlay.
Configuration and pipeline commands also expose repeated `--set POINTER=JSON`:
~~~sh
notarius config show --config examples/dnd-minimal/config.yml \
--set /concurrency/workers=1 --path /concurrency/workers --format json
~~~
The **run** command executes the named pipeline for one input file. The
pipeline ID and **--input** are required.
The value is JSON, so strings require JSON quoting. Preserve shell quoting:
| Flag | Meaning |
~~~sh
notarius pipeline validate dnd-session \
--config examples/dnd-minimal/config.yml \
--set '/pipelines/dnd-session/mode="permissive"' \
--set /pipelines/dnd-session/max_additional_turns=0
~~~
Assignments use non-root mapping paths, not sequence indexes. To change a record
inside a steps/resource list, use an appropriate source/overlay or replace the
complete list. Duplicate or overlapping assignments fail. Version and inheritance
controls are not assignment targets. Overrides follow native loading and recorded
resolution; they are not an alternate YAML parser. PromptKit commands expose
their own native selection/request flags; use help rather than assuming every
configuration flag applies to them.
## Pipeline Commands
`pipeline list` lists configured IDs in sorted order without module resolution
or engine construction. `pipeline show PIPELINE_ID` resolves modules, controls,
validator chains, static prompt dependencies, steps/lanes, and reference bindings,
without expanding every LLM profile or reading input/reference content.
`pipeline validate PIPELINE_ID` performs offline domain resolution and known
prompt/profile dependency checks using the shared load and engine when needed.
It requires no input transcript, reference file bytes, credential values,
provider call, or output/cache/debug directories. Partial profiles remain valid.
This is distinct from native configuration validation: request preparation and
dynamic selections are checked when used.
Show and validate accept configuration selection and native report controls.
They inspect the complete configured pipeline; lane selection belongs to run:
~~~sh
notarius pipeline list --config examples/dnd-complete/config.yml --format json
notarius pipeline show dnd-session --config examples/dnd-complete/config.yml
notarius pipeline validate dnd-session --config examples/dnd-complete/config.yml
~~~
### Run
~~~text
notarius run PIPELINE_ID --input-file PATH [flags]
notarius pipeline run PIPELINE_ID --input-file PATH [flags]
~~~
`run` is a native alias for `pipeline run`: both resolve to the same declaration
and handler. One pipeline ID and a nonempty `--input-file` are required.
| Run flag | Meaning |
| --- | --- |
| **--config path** | Use this configuration file. When omitted, configuration discovery applies; see [Configuration](config.md). |
| **--config-overlay name** | Select a ConfigKit configuration overlay. Empty and **default** select the composed base configuration. |
| **--input path** | Source input file to process. Required. |
| **--output-dir path** | Override the configured output root for this run. |
| **--json** | Write the successful run-result receipt as JSON to standard output. |
| **--chunk_cache auto\|bypass\|refresh** | Override chunk-plan cache handling for this run. |
| **--resume** | Reuse compatible recorded checkpoints when checkpoint recording is enabled. |
| **--recompute-step step-id** | With **--resume**, recompute the selected ordered step and its dependent lanes. It cannot be combined with **--only**. |
| **--debug** | Retain a debug bundle for this run. |
| **--debug-dir path** | Override the debug-bundle root. Requires **--debug**. |
| **--only lane-a,lane-b** | Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline. |
| **--llm-profile id** | Highest-precedence configured profile for selected LLM-backed bindings and validators; it replaces binding and [pipeline](config.md#pipelines) defaults. |
| **--session-id id** | Override the generated prompt session identifier with a non-empty value for LLM-backed module calls. |
| **--reasoning-effort value** | Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once. |
| **--clear-reasoning-effort** | Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run. |
| **--reference selector=path** | Add or replace external file reference bindings at pipeline, lane, chunk, or binding scope. Repeatable. |
| **--without-reference selector** | Remove matching configured external reference bindings. Repeatable. |
| `--config PATH`, `--overlay NAME`, `--set POINTER=JSON` | Configuration selection above. |
| `--input-file PATH` | Required source input file. |
| `--lane ID` | Repeat to select literal artifact lane IDs; commas are part of an ID, not separators. |
| `--output-dir PATH` | Nonempty invocation-relative override of the output root. |
| `--cache auto\|bypass\|refresh` | Invocation-wide selection over binding and pipeline cache controls. |
| `--reference SELECTOR=PATH` | Repeatable external reference bind. |
| `--without-reference SELECTOR` | Repeatable external reference unbind. |
| `--debug[=true\|false]` | Native debug verbosity and independent run capture selection. |
| `--debug-dir PATH` | Capture destination override; explicit empty disables capture. |
| `--llm-profile ID`, `--llm-session-id ID` | Native resource/session selections below. |
| `--llm-*` execution controls | Run-wide request overrides below. |
| `--format`, `--quiet`, `--verbose`, `--progress` | Native presentation controls below. |
**--chunk_cache** accepts only **auto**, **bypass**, or **refresh**.
**--debug-dir**, **--output-dir**, **--session-id**, and
**--reasoning-effort**, and **--recompute-step** reject explicit empty values.
**--reasoning-effort** and **--clear-reasoning-effort** are mutually exclusive.
When neither is present, reasoning effort comes from the selected PromptKit
profile. These controls apply to the shared run client, including retries and
LLM-backed validators, and do not modify configuration or profile files.
Persistent reasoning settings remain a PromptKit profile concern.
**--recompute-step** requires **--resume**; checkpoint requirements and reuse
behavior are documented in [Operations](operations.md).
A directory alone does not enable capture. A nonempty debug-directory override
can re-enable capture over an empty configured root, but still needs debug
selection. `--debug --quiet` captures while suppressing stdout; `--quiet --debug`
selects debug visibility and capture. `--debug=false` disables capture. Debug
on inspection commands changes native visibility without allocating a pipeline
bundle. [Configuration](config.md#concurrency-output-cache-and-debug) defines
directory defaults; [Operations](operations.md) owns capture lifecycle.
Every run uses one effective prompt session. Without **--session-id**, Notarius
generates a stable `notarius:v1:` identifier from the trimmed resolved input
module key and the input file's exact raw bytes. The same module and bytes
therefore produce the same identifier, regardless of pipeline, references,
profile, retries, or run settings. An explicit non-empty value replaces that
default. Session identifiers are visible to providers; they are non-secret
correlation identifiers, not credential storage. See
[Operations](operations.md#operational-limits) for privacy and workflow
guidance.
### Reference selectors
Use **--reference** only for reference slots declared by the selected
configured targets. Qualification narrows the scope of an override:
| Form | Target |
| --- | --- |
| slot=path | Every selected target that declares slot. |
| chunk.slot=path | The chunker. |
| lane.slot=path | Every extractor, merger, or normalizer in lane that declares slot. |
| lane.extract.slot=path | The extractor in lane. |
| lane.merge.slot=path | The merger in lane. |
| lane.normalize.slot=path | The normalizer in lane. |
Pipeline- and lane-scoped selectors are expected to match multiple targets and
fail if they match none. A stage-specific selector fails when its lane is not
selected or its target does not declare the slot. There is no stage-wide
`merge.slot` shorthand; name the lane when targeting a merger.
CLI bindings override configured external paths. For overlapping CLI
selectors, a binding-specific or chunk selector overrides a lane selector, and
a lane selector overrides a pipeline selector. The last occurrence wins at
equal scope. Binding and unbinding the same concrete target at equal scope is
an error; a narrower bind or unbind may create an intentional exception to a
broader action.
**--without-reference** uses the same selector forms without `=path` and
removes external bindings only. Neither flag replaces or removes a generated
artifact handoff; an external/generated collision is a resolution error.
Required slots are checked after all effective changes. CLI reference paths
are resolved relative to the process working directory, so subprocess and
service callers should use absolute paths. Slot names, accepted media types,
size limits, requiredness, and configured generated bindings are part of the
[configuration contract](config.md).
For example, one shared campaign reference can reach every compatible target,
with an optional lane-specific exception:
Example using the maintained minimal configuration and input:
~~~sh
notarius run dnd-session --config examples/dnd-minimal/config.yml \
--input-file examples/dnd-minimal/transcript.json --format json
~~~
notarius run dnd-session \
--input /data/transcript.json \
This run uses a configured provider and needs its credentials when required.
Offline validation does not.
### Run-wide LLM Overrides
These canonical ckprompt flags reach initial producers, semantic corrections,
and LLM validators on the shared native engine without mutating configuration:
| Flag | Value |
| --- | --- |
| `--llm-profile` | Exact profile ID; qualified for collection resources. |
| `--llm-session-id` | Session selection. |
| `--llm-endpoint` | Native endpoint override. |
| `--llm-model` | Model override. |
| `--llm-temperature` | Numeric temperature. |
| `--llm-max-tokens` | Integer token limit. |
| `--llm-top-p` | Numeric top-p. |
| `--llm-timeout-seconds` | Integer native request timeout. |
| `--llm-service-tier` | Service tier selection. |
| `--llm-reasoning-effort` | Reasoning selection; explicit empty suppresses inherited reasoning. |
| `--llm-api-key-env` | Credential environment-variable name, not its value. |
| `--llm-transient-retries` | Integer native transient-failure retry selection; explicit zero disables these retries. |
| `--llm-extra-params` | JSON provider-parameter object, preserving false/zero/null values. |
Omitted values remain unspecified, not the display defaults in help.
`--llm-temperature=0` and `--llm-reasoning-effort=` retain their supplied meaning.
Native target validation and provider-map rules apply; this interface does not
add a repair-model selection, structural-repair count, or generic stage retry.
Use application configuration for semantic turns and native prompt configuration
for structural contracts.
Omitted profile selection preserves binding/pipeline/prompt precedence.
Explicit `--llm-profile=` clears the application profile selection so native
prompt default selection applies. Without an explicit session flag, Notarius
generates a stable `notarius:v1:` session from the trimmed resolved input module
key and exact raw input bytes, independent of references and pipeline/profile
settings. An explicit value replaces it; explicit empty clears that generated
selection and leaves native prompt/session behavior in control. Sessions are
provider-visible correlation identifiers, not secret storage.
PromptKit convenience spellings are scoped to `promptkit` commands; run uses
the canonical `--llm-*` names above. [Native request validation][requests]
documents execution controls in detail.
### Reference Selectors
Bind declared slots using `--reference SELECTOR=PATH`:
| Selector | Target |
| --- | --- |
| `slot` | Every selected compatible target declaring the slot. |
| `chunk.slot` | Chunker. |
| `lane.slot` | Compatible extract/merge/normalize bindings in that lane. |
| `lane.extract.slot` | That lane's extractor. |
| `lane.merge.slot` | That lane's merger. |
| `lane.normalize.slot` | That lane's normalizer. |
Pipeline/lane selectors may match several targets and fail if they match none.
A binding-specific selector requires its selected target to declare the slot.
There is no stage-wide merger shorthand. CLI paths override configured external
paths; narrower selectors beat broader ones, with last occurrence winning at
equal scope. Binding and unbinding the same concrete target at equal scope fails;
narrower actions can make intentional exceptions to broader actions.
`--without-reference` uses the selector without `=PATH`. It removes external
bindings only. Neither action replaces/removes generated handoffs; collisions
fail resolution and required slots must remain bound. CLI paths use the invocation
working directory. Configuration defines slot compatibility and path origins in
[References And Ordered Handoffs](config.md#references-and-ordered-handoffs).
For a complete D&D workflow, pipeline-level references are first-class inputs:
~~~sh
notarius run dnd-session --config examples/dnd-complete/config.yml \
--input-file examples/dnd-complete/transcript.json \
--reference party=/data/references/party.txt \
--reference npc-registry.party=/data/references/npc-party-context.txt
--reference glossary=/data/references/glossary.txt \
--output-dir /data/results --format json
~~~
### Run output
### Completion Report
Without **--json**, standard output contains the completed pipeline ID, counts
of normalized and rejected outputs, and the output directory. A debug-enabled
run also prints its debug-bundle path to standard output. A successful run with
actionable process warnings reports their group and occurrence counts to
standard error. When the selected output module publishes `warnings.json`, the
summary also reports that durable file's path. Advisory and observation findings
do not produce a warning line. The published JSON bundle
is defined by the [JSON output contract](integrations/json-output.md).
Successful runs publish domain files and finalize requested capture before
reporting one small value:
With **--json**, successful standard output is exactly one
`notarius.run-result.v2` JSON document followed by a newline, with no
human-oriented status or debug-path line. Its fields and compatibility policy
are defined by the [run-result contract](integrations/run-result.md). A caller
must check for exit status 0 before decoding this output; a failed write can
leave incomplete standard-output bytes that are not a result document.
| Field | Meaning |
| --- | --- |
| `pipeline` | Selected pipeline ID. |
| `artifact_count` | Published deliverable files, including reused artifacts and enabled auxiliaries; excludes intermediates/cache/debug. |
| `output_directory` | Absolute run-specific publication directory, not the configured root. |
| `debug_directory` | Optional absolute run capture directory; omitted when disabled. |
| `fallback_count` | Producer operations that emitted fallback, present only when positive. |
Example:
Text summarizes pipeline, count, and path, appending capture location when
available. Fallback success is explicitly qualified, even when warnings are
hidden. Affected downstream artifacts, attempts, and validators are not extra
fallbacks. JSON/YAML serialize the same value; report format does not change
domain artifact encoding. There is no persisted receipt, execution ledger,
universal envelope, or automatic duplicate report file.
~~~
OPENROUTER_API_KEY=your-api-key \
go run ./cmd/notarius run dnd-session \
--config examples/dnd-minimal.config.yml \
--input examples/seriatim-minimal-transcript.json
Consumers check status, optionally decode the report, and read configured
lane/auxiliary paths. A failed stdout write may leave partial bytes. A failure
after publication can leave valid artifacts; the failure explanation identifies
available paths. [JSON output](integrations/json-output.md) owns logical artifact
paths and payload contracts, not this report.
## Configuration Commands
The native scopes are `app` (default) and `promptkit`. Both inspect the same
application-owned load; the latter focuses native PromptKit settings. Use
`config scopes` for supported operations. No inspection command implicitly runs
a pipeline or provider.
~~~sh
notarius config validate --config examples/dnd-minimal/config.yml
notarius config show --scope app --config examples/dnd-minimal/config.yml
notarius config sources --config examples/dnd-complete/config.yml
notarius config explain --config examples/dnd-minimal/config.yml \
--path /concurrency/workers --format json
notarius config show --scope promptkit --config examples/dnd-minimal/config.yml
notarius config diff --config examples/dnd-minimal/config.yml \
--against-config examples/dnd-complete/config.yml --check
~~~
## config validate
Show supports `--path`; explain supports `--list`, `--path`, and native history/
filter options. Focused PromptKit paths retain the `/promptkit` prefix, for
example `/promptkit/collections/notarius/profiles`. Diff accepts separate
right-side configuration, overlay, and assignment inputs; differences with
`--check` yield status 3. These commands
report native values and secret-aware source evidence, not copied Notarius
inspection objects. Consult [native configuration commands][configuration]
for complete report and comparison semantics. Use `pipeline validate`, not
configuration validation, for production module/reference/resource preflight.
~~~
notarius config validate [--config path/to/config.yml] [--config-overlay name] [--pipeline pipeline-id] [--only lane-a,lane-b]
## PromptKit Commands
The installed native suite includes:
- listings of prompts, profiles, backends, namespaces, and collections;
- inspection of a named prompt, profile, or backend;
- requirements discovery, concrete request validation, and prepared preview;
- explicit smoke tests: `reachability`, `authentication`, `text_inference`,
`structured_output`, or `all`.
~~~sh
notarius promptkit list prompts --config examples/dnd-minimal/config.yml \
--namespace notarius
notarius promptkit show profile notarius/dnd-extraction \
--config examples/dnd-minimal/config.yml --format json
notarius promptkit requirements show notarius/dnd.spells \
--config examples/dnd-minimal/config.yml
~~~
This command loads and validates the selected composed configuration. With **--pipeline**, it also
resolves that pipeline against the production module catalog. **--only** selects
lanes during that resolution and requires **--pipeline**.
Resource/requirements inspection needs no transcript, credential values, or
provider call. Profile reports describe the stored profile before backend
completion and request overrides; partial profiles are valid. Request validation
and `show prepared` actually prepare native requests and may read supplied
resources or require credentials according to the target, but do not call a
model. Prepared reports can contain rendered application data.
Success is written to standard output as either config "<path>" is valid or
config "<path>" is valid for pipeline "<pipeline-id>".
Use `--llm-var KEY=VALUE`, `--llm-input-text NAME=TEXT`, or
`--llm-input-file NAME=PATH` for concrete prompt inputs. These are not the
pipeline's source input. Namespace flags choose namespaces for short IDs;
already-qualified IDs remain unchanged. Native convenience aliases are installed
only on their applicable PromptKit commands; use help to see them.
Examples:
~~~
go run ./cmd/notarius config validate \
--config examples/dnd-minimal.config.yml \
--pipeline dnd-session
OPENROUTER_API_KEY=validation-placeholder \
go run ./cmd/notarius config validate \
--config examples/dnd-complete.config.yml \
--pipeline dnd-session
~~~
The placeholder in the second command is sufficient only for offline
validation; it cannot run a provider-backed pipeline.
## config effective
~~~
notarius config effective [--config path/to/config.yml] [--config-overlay name]
~~~
This command writes the selected composed configuration as deterministic,
redacted YAML. Standard output contains only that YAML: it does not validate a
pipeline, prepare modules, materialize references, or contact a provider.
## config explain
~~~
notarius config explain [--config path/to/config.yml] [--config-overlay name] <json-pointer>
~~~
This command writes ConfigKit's redacted, human-readable explanation for one
canonical JSON Pointer. Supply `""` explicitly to explain the root. A malformed
pointer is a syntax error; a well-formed unknown path is a command failure.
The explanation can describe a value displaced by a selected overlay. Standard
output contains only the explanation.
## pipelines list
~~~
notarius pipelines list [--config path/to/config.yml] [--config-overlay name] [--json]
~~~
This command lists configured pipeline IDs in sorted order. By default, it
writes one ID per line to standard output. **--json** writes an object shaped as
{"pipelines":[...]} instead.
~~~
go run ./cmd/notarius pipelines list \
--config examples/dnd-minimal.config.yml
~~~
Smoke tests are explicit and may contact providers or perform inference.
Read support, applicability, and observation results; status zero alone does
not mean every observation passed. Neither debug nor inspection silently
launches a smoke test. Full native mechanics are documented under
[inspection][inspection], [preview][preview], [requirements][requirements],
[resource listings][catalogs], and [smoke tests][smoke].
## Output Streams And Exit Statuses
Successful commands write their primary result to standard output. Warnings and
errors are written to standard error.
Results go to stdout; failures, native diagnostics, and progress go to stderr.
`--format text|json|yaml` selects report presentation. Default run presentation
uses its human template; other structured native reports ordinarily use YAML.
`--format` does not reformat help, completion scripts, diagnostics, or domain
payloads.
Configuration load errors include ConfigKit's field diagnostics and source
coordinates, followed by a source-ID legend identifying the acquired files or
source labels. This includes imported files and the selected configuration overlay.
Only one visibility mode is active; the last enabled `--quiet`, `--verbose`,
or `--debug` wins. Ordinary mode hides optional warning/info/debug messages;
verbose shows warning/info; debug adds debug and default progress. Explicit
`--progress=false` disables progress, and quiet suppresses it. Quiet suppresses
stdout but retains failure explanations; formatting errors can still fail a
quiet command. Run capture selection remains independent of that final mode.
For **run --json**, actionable process warnings remain on standard error and standard output is a
machine-readable success result only. Syntax and runtime diagnostics remain on
standard error. Parse the result only after the process exits with status 0.
`--format json --verbose` keeps successful stdout report-only JSON while useful
diagnostics go to stderr. No application-wide structured error envelope is
introduced; failed stdout is not a success document.
| Status | Meaning |
| --- | --- |
| 0 | The command completed successfully, including root help. |
| 1 | Command syntax was valid but configuration loading or validation, pipeline resolution or execution, provider use, output, or requested debug handling failed. |
| 2 | The command or flag syntax was invalid, including unknown commands, missing required arguments, invalid flag values, or invalid flag combinations. |
| `0` | Command completed, including supported permissive fallback with report qualification. |
| `1` | Operational failure, cancellation, publication/capture/presentation failure, or an unclassified/mixed failure. |
| `2` | Invalid invocation or identifiable invalid configuration. |
| `3` | Native configuration differences with diff check mode. |
The root help spellings are the supported help path. Invoking **--help** on
**run**, a **config** subcommand, or **pipelines list** is handled by the flag
parser as a usage error: it writes an error to standard error and exits with
status 2.
Native causes and classification remain intact. Not every resource/preflight
failure is identifiable invalid configuration. Rendering or diagnostic delivery
failure can change an otherwise successful result to failure; callers check the
actual process status. See [native outcomes][outcomes] for library conventions.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md
[syntax]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#registered-command-syntax
[configuration]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#configuration-scopes
[requests]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#concrete-request-validation
[inspection]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-definition-inspection
[preview]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-prepared-request-preview
[requirements]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-requirements
[catalogs]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-catalogs
[smoke]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-smoke-testing
[outcomes]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#outcome-status

View File

@@ -1,403 +1,377 @@
# Configuration
This is the canonical reference for Notarius configuration. Configuration files
are YAML and must declare version 5. They select pipelines and their modules;
the [CLI reference](cli.md) owns invocation syntax, and
[Operations](operations.md) owns run-state procedures.
This is the canonical reference for Notarius configuration fields, defaults,
source selection, and selectable modules. The sole application version is
`6` (also accepted as `"6"`). [CLI Reference](cli.md) owns invocation syntax;
[Operations](operations.md) owns physical state and recovery; integration
contracts own artifact payloads.
Upgrading an older deployment or caller? Use the
[native migration guide](consumers/native-migration.md).
## Configuration Discovery And Precedence
Commands that load configuration choose a file in this order:
Configuration-consuming commands select one main file:
1. a non-empty **--config** CLI value;
2. a non-empty **NOTARIUS_CONFIG** environment value;
3. the installed default file at **/usr/local/etc/notarius/config.yml**, when
it exists.
1. Explicit `--config`, which must not be empty.
2. Nonblank `NOTARIUS_CONFIG`.
3. `notarius.yml`, then `notarius.yaml`, in the working directory.
4. Go's user configuration directory: first its `notarius/` subdirectory,
trying `notarius.yml`, `notarius.yaml`, `config.yml`, `config.yaml`,
`main.yml`, `main.yaml`; then the two `notarius.*` names directly beneath it.
5. `/usr/local/etc/notarius/`, then `/etc/notarius/`, with those six names;
finally `/etc/notarius.yml` and `/etc/notarius.yaml`.
The command fails if none of these paths provides a configuration file.
Generic working-directory filenames and home-directory searches are not enabled.
Missing discovery candidates advance the search; a selected missing, unreadable,
or invalid explicit source fails without fallback. Exhausted discovery fails.
Discovery selects a main file rather than layering every candidate.
Use explicit selection for services and subprocesses.
For configuration values, precedence is:
One ConfigKit result contains the application and native PromptKit settings.
Its source layers, from lower to higher priority, are:
1. built-in defaults;
2. composed YAML sources, including imports;
3. the selected ConfigKit overlay; and
4. explicitly supplied configuration-valued run flags.
1. The bundled OpenRouter resource underlay.
2. Embedded Notarius prompts/profiles and their filesystem-backed schema root.
3. Optional operator companions beside the **actual selected main file**:
`prompts.yml` and recursively selected `*.yml`/`*.yaml` files in `prompts/`.
These form one strict peer group: filenames do not confer priority and
conflicting contributions fail.
4. The selected application main source and its native import graph.
5. The selected ConfigKit overlay.
`--config-overlay` selects a ConfigKit overlay from `overlays/<name>.yml`
beneath the selected configuration root. Empty and `default` select no overlay.
`profiles/<name>.yml` is not a fallback location, and `--config-profile` is no
longer accepted. Configuration overlays are distinct from PromptKit LLM profiles selected by
`llm_profile` or `--llm-profile`. The retired operational environment variables
have no effect; `NOTARIUS_CONFIG` remains a source-discovery input.
Companions are wrapperless native PromptKit settings mounted at `/promptkit`.
They are optional only when absent; malformed or unreadable selected content
fails. The loader does not search the invocation directory for substitute
companions. A companion's imports and content-file paths retain its native
source context. Main imports use their declared destinations; main-file native
settings belong beneath `promptkit`.
Source assembly, inheritance, typed defaults/decoding, explicit configuration
overrides, application normalization, and validation use ConfigKit's native
processing order. Overrides cannot repair earlier parse, composition, version,
inheritance, or decoding errors. The same captured result serves inspection and
engine construction, not a separate profile loader.
The overlay selector is a name: `development` selects
`overlays/development.yml` under the selected main source's configuration root.
Empty and exact lowercase `default` select the base. A missing selected overlay
fails; there is no overlay stack or extension fallback. Application overlays are
distinct from PromptKit profiles. See [ConfigKit's selected-overlay contract][overlays].
Only `NOTARIUS_CONFIG` participates in application environment selection.
Credential environment names are native PromptKit settings, not field-level
application environment overlays.
## Maintained Examples
- [Minimal D&D configuration](../examples/dnd-minimal.config.yml) is a
single-lane Seriatim-to-spell pipeline.
- [Complete D&D configuration](../examples/dnd-complete.config.yml) uses
ordered steps, all implemented D&D lanes, generated references, state
settings, bounded LLM concurrency, and the maintained
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) and imports its
pipeline from [a fragment](../examples/pipelines/dnd-session.yml).
- [Minimal](../examples/dnd-minimal/config.yml): embedded resources only, Seriatim
input, generic chunking, and one spell lane.
- [Complete](../examples/dnd-complete/config.yml): ordered steps and all D&D
families, generated references, independent state roots, workers, cache/mode/
turn controls, and selected domain auxiliaries. Its
[companion](../examples/dnd-complete/prompts.yml) demonstrates native profile
and backend inheritance without replacing native queue defaults.
- The complete [pipeline fragment](../examples/dnd-complete/pipelines/dnd-session.yml)
and [first-step fragment](../examples/dnd-complete/pipelines/dnd-session.describe-session.yml)
retain declaration-relative imports and references. Its development pipeline
selects a derived profile and zero semantic correction turns. The
[development overlay](../examples/dnd-complete/overlays/development.yml)
demonstrates serial workers and cache bypass.
Use these complete files as starting points rather than combining the
illustrative fragments in this reference.
The examples use separate directories so complete-example companions do not
alter minimal-example selection. Use these full files as starting points;
the fragments below illustrate individual settings.
## File Shape And Defaults
Unknown fields, duplicate mapping keys, empty identifiers, and identifiers that
become duplicates after trimming whitespace are rejected. Every top-level field
other than **version** is optional.
Application fields are strict. Unknown application fields, duplicate mapping
keys, blank identifiers, and identifiers duplicated after trimming are rejected.
PromptKit-owned resource records use the [native format][formats], including its
extension-field and strict nested-object rules; arbitrary extension fields are
not automatically secret.
| Field | Type | Default | Rules |
| --- | --- | --- | --- |
| **version** | integer or quoted string | none | Required; must be 5. Maintained files use `version: 5`. |
| **promptkit** | object | none | Profile source and optional local-backend configuration. |
| **pipelines** | map | empty | Maps pipeline IDs to pipeline definitions. |
| **concurrency** | object | see below | Global LLM and extraction limits. |
| **output** | object | see below | Published output settings. |
| **cache** | object | see below | Chunk-plan and checkpoint settings. |
| **debug** | object | see below | Debug-bundle root only; it does not enable capture. |
| Root field | Type | Default / meaning |
| --- | --- | --- |
| `version` | integer or quoted string | Required; `6` only, without translation of older versions. |
| `promptkit` | native settings | Embedded and bundled resources, overlaid by selected sources. |
| `pipelines` | map | Empty; maps IDs to pipeline definitions. |
| `concurrency.workers` | positive integer | `64`; one shared ready-job pool. |
| `output.directory` | nonempty path | `./notarius-output`. |
| `cache_directory` | path | Omitted or empty selects `os.UserCacheDir()/notarius`. |
| `debug.directory` | path | Omitted selects `/tmp/notarius-debug`; explicit empty disables capture. |
Built-in defaults are:
Nonempty relative application destinations and reference paths resolve from the
file contributing the surviving declaration, including imported, overlaid, or
inherited values. A child replacement keeps the child's origin. Built-in relative
destinations use the selected main file's directory; invocation path overrides
use the working directory. Absolute paths remain absolute.
| Field | Default |
| --- | --- |
| **concurrency.total_llm** | 16 |
| **concurrency.stage_workers.extract** | Effective **total_llm** |
| **output.directory** | **./notarius-output** |
| **cache.chunk_plans.mode** | **auto** |
| **cache.chunk_plans.directory** | Empty, selecting the per-user chunk-plan root |
| **cache.checkpoints.enabled** | false |
| **cache.checkpoints.directory** | Empty, selecting the per-user checkpoint root |
| **debug.directory** | **./notarius-debug** |
An empty output directory is invalid. Empty cache selection deliberately chooses
the per-user default; on Linux this normally follows `XDG_CACHE_HOME` or
`~/.cache`. Null is not a universal substitute for omission or empty: effective
types and application validation still apply. Directory selection does not
configure filesystem access policy or enable debug. See
[Operations](operations.md) for lifecycle, permissions, and provisioning.
An empty cache directory in YAML deliberately selects the corresponding
per-user root. An explicit empty output or debug directory is invalid.
Selecting a chunk-plan or checkpoint directory does not configure filesystem
access policy. Cache permissions come from deployment provisioning, process
umask, setgid inheritance, and default ACLs; see [Operations](operations.md#cache-provisioning).
## Imports And Sibling Inheritance
Every nonempty relative configured destination or reference path resolves from
the canonical directory of the file that supplies its surviving declaration.
This includes imported fragments and selected configuration overlays. Built-in
relative destinations use the selected main configuration file's directory;
explicit `--output-dir` and `--debug-dir` values use the invocation working
directory. Absolute values remain unchanged.
Root `config` contains native controls such as imports and sequence declarations.
For example:
The root file can use ConfigKit imports to compose disjoint definitions. Imports
and selected overlays remain under the configuration root; they do not merge or
append a pipeline's `steps` sequence. An overlay replaces sequences as defined
by ConfigKit, so changing an individual ordered binding requires supplying the
whole replacement sequence.
~~~yaml
config:
imports:
- path: pipelines/dnd-session.yml
required: true
~~~
Imports are optional by default. Paths, directory selection, destinations,
sequence-item placement, source containment, and dependency-ready assembly order
follow [ConfigKit's import contract][imports]. Imported fragments need not repeat
the application version. A nested application field named `config` is ordinary
data, not another source-control block.
Mapping inheritance names a sibling, such as `extends: production` inside
`pipelines`. Identified-list inheritance uses an identity mapping such as
`extends: {id: parent}`. Parents must survive in the same sibling collection;
these are not paths or cross-namespace references.
Child mappings recursively overlay parents. Scalars and null replace inherited
values; an empty mapping does not clear existing fields. Lists follow their
native registered/declared composition policy. Pipeline steps are identified by
`id`: native upsert replaces a matching **whole record** in place and appends
new IDs. It does not patch fields of a matching step. Unidentified lists replace
as whole values across layers. Explicit replace with `[]` clears a list; empty
append/upsert does not. Validator lists are not automatically identified.
An identified record's `extends` can retain a distinct sibling's fields before
applying child changes. All surviving records remain real validated records,
not template-only definitions. Every final pipeline step executes and lane IDs
must be unique across the pipeline; inheriting a step's lanes does not remove
them. Pipeline-level inheritance with step upsert is suitable for full variants.
Omitted fields inherit; explicit zero, false, and empty collections retain their
presence. Null can clear an inherited value but remains subject to that field's
type and fallback semantics. Omitting `extends` retains a lower relationship;
`extends: null` cancels that relationship rather than independently deleting
other composed fields. `extends` is a reserved native configuration key, not
ordinary module-option data. See [native inheritance][inheritance] and
[sequence composition][sequences] for full rules.
Explicit configuration assignments use native mapping paths. They cannot walk
sequence indexes, assign the version, or introduce inheritance controls. Mapping
values overlay; list values replace the whole decoded list. Inheritance/defaulting
does not run again afterward. [CLI Reference](cli.md#configuration-selection)
owns assignment syntax.
## PromptKit Profiles
The optional **promptkit** object selects one source of profile definitions and
may register one conventional local OpenAI-compatible backend:
Native `promptkit` settings contain identified `backends`, `profiles`, and
`prompts` lists, plus a `collections` mapping. Notarius embeds its resources
in `collections.notarius`. Runtime IDs are qualified, for example
`notarius/dnd-extraction` and `notarius/dnd.spells`; the bundled root backend
is `openrouter`. Resource IDs are literal, not resource-version paths.
A collection's local record ID omits its namespace; references to resources in
that collection use the qualified runtime ID.
A wrapperless companion can add a profile variant:
~~~yaml
version: 5
promptkit:
profile_dir: ./profiles
# profile_file: ./profiles.yml
transient_retries: 2
local_backend:
endpoint: http://localhost:8000/v1
concurrency_limit: 2
collections:
notarius:
profiles:
- id: campaign
extends: {id: dnd-extraction}
model: example-model
~~~
| Field | Type | Rules |
| --- | --- | --- |
| **profile_dir** | string | Non-empty directory containing profile files. |
| **profile_file** | string | Non-empty profile file. |
| **transient_retries** | integer | Non-negative additional built-in HTTP attempts for eligible transient provider failures; defaults to 2. Set 0 to disable these retries. |
| **local_backend** | object | Optional registration for the conventional PromptKit backend ID **local**. |
| **local_backend.endpoint** | string | Required when **local_backend** is present; absolute HTTP or HTTPS URL with a host. |
| **local_backend.concurrency_limit** | integer | Optional non-negative limit; defaults to 0. |
The pipeline can then select `llm_profile: notarius/campaign`. In the main
application file, place that same mapping beneath `promptkit`. The parent
reference is local to the same profile list; profile/backend references otherwise
name their intended exact ID. The [complete companion](../examples/dnd-complete/prompts.yml)
shows a runnable inherited backend/profile combination.
Set at most one of **profile_dir** and **profile_file**. Every nonempty relative
configured filesystem path is resolved from the canonical directory of the
file that supplies it. The complete example's
`./llm-profiles/dnd-extraction.yml` value therefore resolves beside that example.
Use absolute paths for services and containers when their deployment layout is
not configuration-relative.
Later same-ID resources replace complete lower records, not selected fields.
Use a distinct inherited sibling to retain a parent's fields; replacing a record
with only one changed field does not implicitly keep the old definition.
Native `extends`, explicit null, list policy, and source contexts apply to
resources just as to other configuration. See [resource inheritance][resource-inheritance].
An operator source is optional. For a requested ID, PromptKit checks the
configured operator source first, then Notarius's embedded fallback profiles,
then its own built-in catalog. A matching profile is complete: it replaces a
lower-precedence definition rather than merging with it. The maintained
[`dnd-extraction` LLM profile](../examples/llm-profiles/dnd-extraction.yml)
is a secret-free deployment artifact; production, development, and local
deployments can each provide a complete definition with that same workload ID.
Use workload-oriented IDs for new profiles instead of model names.
[Operations](operations.md#promptkit-profile-deployment) owns the deployment
workflow and credential-handling guidance.
The embedded D&D profile selects `openrouter`, model `openai/gpt-5.6-luna`,
a `240` second timeout, and `flex` service tier, leaving reasoning unset.
Initial/correction pairs share their bundled default profile. Explicit application
profile selections and run overrides reach producers, validators, and correction
requests; validators can otherwise select their own profile.
When **local_backend** is present, its endpoint is trimmed and must use HTTP or
HTTPS case-insensitively, be absolute, and have a non-empty host. URL paths are
allowed. User information, queries, and fragments are rejected. A zero
**concurrency_limit** leaves the local backend unrestricted inside PromptKit;
a positive value limits simultaneous local generations. The application-wide
**concurrency.total_llm** limit still applies in both cases. Neither local
backend field has an environment override. Omitting **local_backend** registers
nothing and preserves existing built-in and endpoint-only profile behavior.
A native backend supplies endpoint, credential-environment name, optional
capacity/queue controls, provider parameters, and explicit smoke metadata.
Profiles may supply backend or endpoint, model, sampling/token controls, timeout,
service tier, reasoning, credential policy, and provider parameters. Partial
profiles are valid; preparation must complete the actual target. Resource
inspection is not a backend-completed or run-overridden target prediction.
A file-backed PromptKit profile selects the registration by its case-sensitive
backend ID:
Notarius injects **no backend concurrency or queue defaults**. Native admission
is shared by backend ID within the engine, independently of workers; distinct
IDs do not automatically share capacity even if their endpoints match. An
endpoint-only profile has no backend identity. Configure native backend limits
when desired; the [upstream backend contract][backends] owns defaults and queue
semantics.
~~~yaml
id: local-summary
backend: local
model: example-model
~~~
Profile omission, explicit values, and null differ. For example, native null
`endpoint` or `api_key_env` permits backend fallback, while an explicitly empty
string clears those sources; zero sampling values remain intentional. Blank/null
reasoning suppresses the outbound control. Changing backend/model does not
automatically clear unrelated explicit inherited settings. Use the
[native defaults table][profile-defaults], not inferred old-wrapper behavior.
Keep credentials out of the local-backend object. A PromptKit profile may name
its credential environment variable through `api_key_env`; set that variable
only in the run environment. PromptKit owns the
[pinned profile-file format](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.9.0/docs/formats.md),
including `base_profile` inheritance. Notarius passes profiles through without
merging them. Filesystem profiles cannot express PromptKit's in-memory
`APIKeyRequired` setting; an unset `api_key_env` is optional and may reach the
provider without authorization.
The [PromptKit upstream boundary](integrations/pkg-promptkit.md) identifies the
supported package API, and [Operations](operations.md#operational-limits)
describes the effective concurrency layers.
Only credential environment **names** belong in files, never values. Native
secret-aware inspection preserves marked secret omissions; arbitrary prompt,
source, or extension data is not promised safe to disclose.
`notarius config validate --pipeline <id>` resolves the selected pipeline and
inspects every explicit effective profile without contacting a provider or
requiring credential values. It rejects absent, malformed, or incompatible
profiles before a run prepares modules. Credential availability is checked only
when a generation is prepared.
### Prompt Output Contracts And Schemas
## Version 5 Migration
Prompt declarations select response format, validation mode, and schema. Bundled
initial, correction, and validator prompts omit structural-repair counts:
Notarius inherits the upstream default, not an independent application-pinned
count. Native prompt customization can explicitly change that budget. Transient
provider retries are also native, distinct from application semantic turns.
See [native output contracts][output-contract].
Version 3 and version 4 files are rejected and are not rewritten at load time.
Use `version: 5`, rename the former `scriptorium` section to `promptkit`, and
convert every module binding to an object containing `module`. Convert every
external reference to `{path: ...}` and move any lane-level references to the
corresponding extraction binding. Put durable operational values in YAML or
use the documented explicit run flags; the former field-level environment
variables are not read.
Schemas may be inline, `schema_file` relative to its contributing source, or
`schema_path` within an explicit applicable `schema_root`. Exactly one schema
selection is used for JSON Schema mode. Null clears an alternative; switching
forms can require clearing the inherited selection. Native preparation reads
and compiles schemas; configuration/preflight does not read them.
Embedded Notarius prompts use their collection's filesystem-rooted schemas.
A nonnull collection root takes precedence over the root `promptkit.schema_root`;
absent/null collection roots fall back to that application root. A nonnull blank
root is invalid. Replacing `collections.notarius.schema_root` selects the new
context for its remaining path-based schemas. A missing file does not fall back
to embedded or working-directory roots. Other collections are unaffected.
Schema resources must be self-contained; native schema rules are in
[PromptKit's schema reference][schemas].
## Concurrency, Output, Cache, And Debug
~~~yaml
concurrency:
total_llm: 2
stage_workers:
extract: 2
output:
directory: ./notarius-output
cache:
chunk_plans:
mode: auto
directory: ./notarius-cache/chunk-plans
checkpoints:
enabled: true
directory: ./notarius-cache/checkpoints
debug:
directory: ./notarius-debug
~~~
`concurrency.workers` bounds active ready extraction and lane-completion jobs
together, including their validation/correction. It must be positive, has no
application maximum, and is independent of CPU count and native backend limits.
Explicit `1` gives serial jobs. Waiting for prerequisites occupies no worker;
nested validators do not request another worker. It is not a cross-backend
provider-call ceiling.
**concurrency.total_llm** must be greater than zero. The only supported
**concurrency.stage_workers** key is **extract**; its value must be from 1
through **total_llm**. When omitted, it is recalculated from the effective
**total_llm** after imports, overlay selection, and explicit ConfigKit
overrides.
`output.directory`, `cache_directory`, and `debug.directory` select independent
roots. `/var/cache/notarius` is the convention for an explicitly provisioned
system-wide cache, not the per-user default. No directory setting creates a
permission policy or retention service.
**cache.chunk_plans.mode** accepts **auto**, **bypass**, or **refresh**.
**cache.checkpoints.enabled** is a boolean. The CLI can override the output
directory and chunk-plan mode for one run; see [CLI reference](cli.md#run).
Cache directory fields select only locations; Notarius has no cache permission
field or operational environment override.
A configured debug destination alone does not enable capture. Explicit empty
disables it; a nonempty invocation override can re-enable it. Native debug
selection and presentation modes are independent. See [CLI Reference](cli.md#run)
for invocation controls and [Operations](operations.md) for state handling.
## Pipelines
Each **pipelines** entry has a unique, non-empty ID and the following shape:
Each nonblank `pipelines` key defines a configured pipeline.
~~~yaml
pipelines:
dnd-session:
llm_profile: dnd-extraction
input:
module: seriatim
chunk:
module: generic
output:
module: json
artifacts:
spells:
extract:
module: dnd/spells
merge:
module: appendorder
normalize:
module: dnd/spells
~~~
| Field | Type | Default | Rules |
| --- | --- | --- | --- |
| **llm_profile** | string | none | Optional non-empty default PromptKit profile ID for selected LLM-backed bindings and validators. An explicitly present blank value is invalid. |
| **structured_output_repair_attempts** | integer | prompt-owned (1 in maintained production prompts) | Optional structural-repair limit from 0 through 3 for selected LLM-backed bindings and validators. Omission leaves the prompt's declared policy in control; explicit 0 disables structural repair at that scope. |
| **validation_policy** | object | see below | Optional terminal policy defaults for producer validation. Its fields inherit independently into chunk, extract, merge, and normalize bindings. |
| **input** | module binding | none | Required. |
| **chunk** | module binding | **generic** | Optional. |
| **output** | module binding | **json** | Optional. |
| **artifacts** | map | none | Compact single-step lane map. |
| **steps** | list | none | Ordered lane definitions. Mutually exclusive with **artifacts**. |
| **references** | map | none | External reference defaults for eligible targets. |
Use either **artifacts** or **steps**. The compact **artifacts** form is an
implicit single step. An explicit **steps** list must be non-empty; every step
needs a unique non-empty **id**, an **artifacts** map, and may have
**references**. A lane ID must not appear more than once in a pipeline,
including across explicit steps.
For each selected LLM-backed binding or validator, profile selection occurs
after module, validator, and `--only` lane selection. It uses the
run-level **--llm-profile** value first, then the binding's **llm_profile**,
then the pipeline's **llm_profile**, and finally the PromptKit default.
Deterministic bindings do not receive these defaults or run overrides.
Structural output repair is resolved after module, validator, and `--only` lane
selection. An object's **structured_output_repair_attempts** value takes
precedence over the pipeline value; otherwise, an LLM-backed binding or
validator inherits the pipeline value. If both are omitted, PromptKit uses the
prompt's declared repair policy. The value must be an integer from 0 through 3;
explicit `null` and non-integer values are invalid. An explicit value on a
deterministic binding or validator is invalid, while a pipeline value simply
does not apply to deterministic selections.
`validation_policy` controls terminal disposition for one complete producer
attempt and validator chain. It may appear on a pipeline or a **chunk**,
**extract**, **merge**, or **normalize** module binding; input, output, and
validator bindings reject it. Every field is optional and resolves in binding,
pipeline, then application-default order:
| Field | Values | Default |
| Field | Type | Default / rules |
| --- | --- | --- |
| **producer_structural_failure** | **fail_run**, **reject_output** | **fail_run** |
| **semantic_rejection** | **fail_run**, **reject_output** | **fail_run** |
| **validator_failure** | **warn_continue**, **fail_run** | **warn_continue** |
| `llm_profile` | string | Optional qualified profile selection; explicit blank/null is invalid. |
| `mode` | `strict\|permissive` | Producer terminal mode; see below. |
| `max_additional_turns` | nonnegative integer | Semantic correction allowance excluding the initial response. |
| `cache` | `auto\|bypass\|refresh` | Eligible model-result reuse policy. |
| `input` | binding | Required. |
| `chunk` | binding | Defaults to `generic`. |
| `output` | binding | Defaults to `json`. |
| `artifacts` | lane map | Compact single-step form, mutually exclusive with `steps`. |
| `steps` | ordered list | Nonempty when selected; each record has a unique nonblank `id`, `artifacts`, and optional `references`. |
| `references` | map | External reference defaults for compatible targets. |
The policy object and its fields must be non-null, and unknown fields are
rejected. A deterministic producer may not explicitly set
**producer_structural_failure** on its binding, although a pipeline-level
default remains valid for pipelines that include LLM-backed producers.
A lane ID is unique across all steps. Each lane requires `extract`, defaults
`merge` to `appendorder`, and defaults `normalize` to `noop`. References and
validator overrides belong on eligible bindings, not lane-wide fields.
Ordered steps finish before their generated artifacts feed later steps.
After the producer binding's retry budget is exhausted, an invalid structured
response uses **producer_structural_failure**. One or more semantic validator
rejections use **semantic_rejection**; rejection takes precedence over an
exhausted validator failure or skip. With no rejection, an exhausted validator
failure or skip uses **validator_failure**. `reject_output` records the
terminal rejection without advancing that candidate. `warn_continue` is valid
only for validator execution failure: it advances a structurally valid,
otherwise unrejected result with incomplete-validation provenance and without
making it reusable checkpoint state.
For each selected LLM role, profile precedence is explicit invocation override,
binding `llm_profile`, pipeline `llm_profile`, then native prompt default.
Deterministic roles do not receive LLM defaults/overrides and reject explicit
profile assignments. A supplied empty invocation profile clears the application
selection and lets the prompt default apply; configured blank profiles are invalid.
A lane has these fields:
### Producer Controls
| Field | Type | Default | Rules |
| --- | --- | --- | --- |
| **extract** | module binding | none | Required. |
| **merge** | module binding | **appendorder** | Optional. |
| **normalize** | module binding | **noop** | Optional. |
| **references** | map | none | Not supported at lane scope; place references on the eligible binding. |
| **validators** | list | none | Non-empty lane-level lists are rejected. Set validator overrides on a binding instead. |
Chunk, extract, merge, and normalize bindings resolve controls before execution:
Lane-level **references** are not supported. Put a lane extraction reference
under **extract.references**.
| Control | Precedence, highest first | Default |
| --- | --- | --- |
| `mode` | Binding, pipeline, application | `strict` |
| `max_additional_turns` | Binding, pipeline, application | `2` |
| `cache` | Explicit invocation cache, binding, pipeline, application | `auto` |
Omission inherits. Zero turns disables semantic correction; a positive allowance
is not a requirement to use every turn. The complete applicable validator chain
assesses each usable initial/revised candidate, including the final permitted
response. Native coordination owns conversation/iteration; the allowance does
not count transport retries or structural repair. Deterministic work does not
acquire conversations or generic retries.
Strict requires an accepted result. Permissive explicitly permits only the
module's supported fallback, with intrinsic shape/source/downstream checks,
without claiming ordinary semantic approval or rerunning the normal chain.
A whole-source D&D scene plan, empty extraction collection where valid, or safe
final normalization groups/merged input are supported directions. Scene
descriptions cannot use an invalid empty collection or fabricated description.
Unsupported fallback construction fails; cancellation stops without fallback.
Eligible cacheable work uses `auto` to read/store accepted results, `bypass`
for neither, and `refresh` to skip reads and replace only after new acceptance.
Failures preserve earlier acceptance. Fallback and actually affected dependent
work skip both lookup and storage; unrelated predecessors remain reusable.
Settings/policy changes may still reuse old accepted content; select bypass/
refresh when deliberately applying changed policy. Best-effort cache I/O does
not fail otherwise successful work. [Operations](operations.md) owns recovery
and physical storage, not a checkpoint/resume contract.
## Module Bindings And Validators
Every module and validator binding uses an object, even when it has no fields
beyond its module key:
Every module binding is an object containing `module`, even without options.
~~~yaml
input:
module: seriatim
~~~
| Binding field | Meaning |
| --- | --- |
| `module` | Registered compatible key; required. |
| `llm_profile` | Optional nonblank qualified profile for an LLM-backed role. |
| `mode`, `max_additional_turns`, `cache` | Resolved producer controls above. |
| `options` | Selected module's strict option object. |
| `references` | Declared slots on chunk/extract/merge/normalize bindings. |
| `validators` | Ordered replacement chain on those producer bindings. |
Use an object for fields:
Omitted validators use the production default. `validators: []` replaces it
with an empty chain; a nonempty list replaces it in listed order. Null is not an
empty list. Validator bindings accept only `module`, optional LLM-backed
`llm_profile`, and `options`; they have no separate producer mode, semantic-turn
allowance, references, or nested validators. Each validator executes once per
candidate assessment. Intrinsic codec/schema checks remain with an empty chain,
as do source parsing, plan materialization, and necessary module/fallback/cache
construction checks. Ordinary artifact citation existence/containment checks
are supplied by configured validators and can be omitted by chain replacement.
See [default chains](#production-validator-keys-and-default-chains).
~~~yaml
extract:
module: dnd/spells
llm_profile: dnd-extraction
retries: 2
references:
spell_catalog:
path: ./dnd-spell-catalog.json
~~~
The `json` output options are:
| Binding field | Type | Default | Rules |
| --- | --- | --- | --- |
| **module** | string | none | Required for an object binding. Must be a registered compatible key. |
| **llm_profile** | string | none | Optional non-empty PromptKit profile ID for an LLM-backed binding. It overrides the pipeline default unless the run supplies **--llm-profile**. |
| **structured_output_repair_attempts** | integer | pipeline or prompt-owned (1 in maintained production prompts) | Optional structural-repair limit from 0 through 3 for an LLM-backed binding. It overrides the pipeline value; explicit 0 disables structural repair. |
| **validation_policy** | object | pipeline or application defaults | Optional field-by-field terminal-policy override for a chunk, extract, merge, or normalize binding. |
| **retries** | integer | 0 | Non-negative additional complete producer attempts for chunk, extract, merge, and normalize bindings. This single budget covers operational errors, invalid structured output, module-requested normalization retry, and semantic correction. |
| **options** | object | none | Must satisfy the selected module. |
| **references** | map | none | Valid only on chunk, extract, merge, and normalize bindings. |
| **validators** | list | production chain | Valid only on chunk, extract, merge, and normalize bindings. |
| Option | Default / rules |
| --- | --- |
| `include_chunk_map` | Boolean, default false; publish when enabled and available. |
| `evidence_context` | Omitted disables publication; otherwise a strict object. |
| `evidence_context.enabled` | Required boolean; false permits no other evidence fields. |
| `evidence_context.lanes` | When enabled, required nonempty list of unique trimmed configured lane IDs. |
| `evidence_context.window_units` | When enabled, nonnegative integer, default `3`; zero keeps only directly cited units. |
Omitting **validators** uses the registered chain. **validators: []** selects
an empty chain; a non-empty list replaces the chain in the listed order.
Validator bindings accept only **module**, **llm_profile**,
**structured_output_repair_attempts**, **retries**, and **options**. Their
**retries** value is a non-negative additional validator-execution budget and
is valid only when the selected validator is LLM-backed. A validator retry
rechecks the same immutable candidate; it never regenerates the producer.
They reject
**validation_policy**, **references**, and nested **validators**. Deterministic
validators reject explicit **llm_profile** and
**structured_output_repair_attempts**.
Deterministic module bindings also reject those explicit fields.
An LLM-backed chunk, extract, merge, or normalize producer with both a
non-empty validator chain and positive **retries** must declare the supported
single-response correction capability. Preparation rejects a configuration
that could require semantic correction from a producer that cannot provide an
exact prior response. A deterministic producer, or an LLM attempt that did
not make a model call, cannot consume a semantic retry after rejection.
The **json** output module accepts optional **include_chunk_map** and
**evidence_context** settings:
~~~yaml
output:
module: json
options:
include_chunk_map: true
evidence_context:
enabled: true
window_units: 3
lanes:
- npc-registry
- spells
~~~
**include_chunk_map** is a boolean and defaults to false. It adds the accepted
chunk map when one exists; its wire format is defined in the
[chunk-map contract](integrations/chunk-map.md).
Omitting **evidence_context** disables evidence publication. When present, it
is an object with these strict fields:
| Field | Type | Rules |
| --- | --- | --- |
| **enabled** | boolean | Required. `false` permits no other evidence fields. |
| **lanes** | array of strings | Required and non-empty when enabled. Each value is trimmed and must be unique; every value must name a configured pipeline lane. |
| **window_units** | non-negative integer | Optional when enabled; defaults to 3. Zero retains only directly cited units. |
Unknown outer or nested option fields are rejected, as are incompatible YAML
types. The allowlist remains valid when a run uses lane filtering: a configured
lane that is not active for that invocation simply contributes no evidence.
Evidence publication is opt-in because it can persist source text and metadata.
When enabled, it publishes the selected source-unit excerpt defined by the
[Published Evidence Context contract](integrations/evidence-context.md).
Filtered-out configured lanes contribute no evidence. Unknown or incompatible
options fail. Evidence is opt-in because it can persist source text and metadata.
Logical formats belong to [chunk-map](integrations/chunk-map.md) and
[evidence-context](integrations/evidence-context.md) contracts.
## References And Ordered Handoffs
@@ -431,9 +405,9 @@ steps:
An artifact selector contains only **step** and **lane**. The producer must be
an earlier step and the selected artifact must be compatible with the consumer
slot. A generated binding supplies one accepted normalized artifact; it does
not name a file. A configured generated dependency remains required even when
that consumer slot is otherwise optional.
slot. A generated binding supplies one normalized artifact in memory, including a
supported qualified fallback; it does not name a file. A configured generated
dependency remains required even when that consumer slot is otherwise optional.
Pipeline references are configuration defaults. A matching step-local or
binding-local external path overrides a pipeline default. CLI reference
@@ -488,7 +462,7 @@ normalized combat-turn module may use optional **npc_registry**. Location occurr
require **location_registry** for extraction and normalization. Item occurrences require
**item_registry** for extraction and normalization. Enemy-event extraction requires all
four of its JSON artifact slots; its normalizer requires **npc_registry**.
The [complete example](../examples/dnd-complete.config.yml) shows the ordered
The [complete example](../examples/dnd-complete/config.yml) shows the ordered
generated bindings.
## Production Module Keys
@@ -539,12 +513,12 @@ Available validator keys are:
| Location registry | **extract/dnd/location-registry/shape**, **extract/dnd/location-registry/source_refs**, **extract/dnd/location-registry/source_relatedness**, **normalize/dnd/location-registry/identity** |
| Location occurrences | **extract/dnd/location-occurrences/shape**, **extract/dnd/location-occurrences/registry**, **extract/dnd/location-occurrences/source_refs**, **extract/dnd/location-occurrences/source_relatedness**, **normalize/dnd/location-occurrences/invariants** |
`extract/dnd/scene-descriptions/combat_semantics` is not in a production default chain. To opt in, replace the scene extractor validator chain with the current ordered chain plus the semantic validator last, and set a positive producer retry budget if a rejection should request a corrected scene:
`extract/dnd/scene-descriptions/combat_semantics` is not in a production default chain. To opt in, replace the scene extractor validator chain with the current ordered chain plus the semantic validator last, and retain a positive semantic-turn allowance if a rejection should request a corrected scene:
~~~yaml
extract:
module: dnd/scene-descriptions
retries: 1
max_additional_turns: 1
validators:
- module: generic/valid_json
- module: extract/dnd/scene-descriptions/shape
@@ -552,14 +526,13 @@ extract:
- module: generic/valid_json_schema
- module: extract/dnd/scene-descriptions/source_relatedness
- module: extract/dnd/scene-descriptions/combat_semantics
retries: 1
~~~
An override replaces, rather than extends, the default chain. See [Module Bindings And Validators](#module-bindings-and-validators) for binding, profile, repair, retry, and failure-policy rules.
An override replaces, rather than extends, the default chain. See [Module Bindings And Validators](#module-bindings-and-validators) for binding and profile rules, and [producer controls](#producer-controls) for semantic correction and terminal mode.
The validator retry shown above permits one additional execution against the
same scene candidate when the LLM-backed validator itself fails; it is separate
from both the extractor's producer retry and PromptKit structural repair.
The validator runs once per candidate assessment. Native transient retries and
structural repair remain internal to that execution; there is no separate
validator semantic-turn allowance.
When no override is configured, production D&D bindings use the following
ordered chains. Each row lists extract then normalize; spell chains are the
@@ -582,27 +555,29 @@ Chains are only registered for the D&D extract and normalize modules shown
above; select an explicit override when a different compatible chain is
required.
## Validation
## Validation And Inspection
Validate a file and one pipeline before running it:
Configuration validation checks the selected native application document.
Pipeline validation additionally resolves production modules/options, validator
targets, references, generated handoffs, and statically known prompt/profile
dependencies. It needs no transcript, reference bytes, credential values,
provider calls, or state directories. Partial profiles pass; request-time data
and dynamic selections remain runtime checks. [CLI Reference](cli.md#pipeline-commands)
owns commands for both boundaries.
~~~sh
go run ./cmd/notarius config validate \
--config examples/dnd-minimal.config.yml \
--pipeline dnd-session
~~~
Native whole-app and focused PromptKit inspection use the same selected result
and secret-aware provenance. Profile inspection describes stored fields, not a
prediction of a completed request; prepared preview is the native request boundary.
See [configuration commands](cli.md#configuration-commands) and
[PromptKit commands](cli.md#promptkit-commands).
Configuration validation rejects invalid YAML, unsupported fields, invalid
defaults or explicit CLI overrides, incompatible module keys, unknown options,
invalid reference bindings, missing required reference slots, invalid validator
overrides, and incompatible generated artifact handoffs. Use
[pipelines list](cli.md#pipelines-list) to inspect configured IDs.
## Inspection
Use [config effective](cli.md#config-effective) to write the selected composed
configuration as deterministic, redacted YAML. Use
[config explain](cli.md#config-explain) with a canonical JSON Pointer to inspect
the effective or historical provenance for one path, including a value displaced
by a selected overlay. Neither command resolves a pipeline, prepares modules,
materializes references, or requires provider credentials.
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[backends]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#backend-definitions
[profile-defaults]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#defaults-and-overrides
[resource-inheritance]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#resource-inheritance
[output-contract]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#output-contract
[schemas]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md#schemas
[imports]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#explicit-imports
[overlays]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#selected-overlays
[inheritance]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#sibling-inheritance
[sequences]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#strict-document-composition

View File

@@ -1,142 +1,83 @@
# Consuming The Complete D&D Pipeline
Use this workflow when an orchestrator runs the maintained complete D&D
pipeline and consumes its structured JSON artifacts. The generic
[subprocess consumer guide](subprocess.md) owns process-level responsibilities;
this guide connects that workflow to the complete D&D configuration, its
Seriatim input, and its artifact inventory.
This guide applies the [subprocess workflow](subprocess.md) to the maintained
complete D&D configuration. [CLI Reference](../cli.md) owns invocation and the
native report; [Configuration](../config.md) owns composition;
[Published JSON Output](../integrations/json-output.md) owns logical paths.
[Migration guidance](native-migration.md) covers older orchestrators.
The [CLI reference](../cli.md), [configuration reference](../config.md),
[run-result receipt](../integrations/run-result.md), and
[published JSON output contract](../integrations/json-output.md) remain the
canonical definitions of those public interfaces.
## Prepare The Deployment
## Prepare And Validate The Deployment
Start from [examples/dnd-complete/config.yml](../../examples/dnd-complete/config.yml).
Preserve its imported pipeline fragments, native companion, and reference files,
or update the paths deliberately. It uses every implemented D&D family, ordered
generated handoffs, and selected chunk-map/evidence output.
Start from the maintained
[complete D&D configuration](../../examples/dnd-complete.config.yml). It uses
the `dnd-session` pipeline and demonstrates every implemented D&D lane, ordered
artifact handoffs, campaign references, chunk-map publication, and evidence
context.
Native embedded defaults and the maintained companion already provide profile/
backend definitions. A deployment can supply variants rather than being required
to recreate them. YAML paths retain the contributing declaration's origin;
CLI reference paths use the process working directory. Absolute caller paths
are useful for services. Keep credentials in the intended environment, not
files, arguments, sessions, or logs.
A deployment must provide its own PromptKit profile and campaign reference
files. Use absolute paths for service and subprocess deployments. In
particular, observe these different resolution rules:
Preflight without credentials or inference:
- reference and PromptKit profile paths in YAML are resolved relative to the
file that supplies their surviving declaration;
- reference paths passed with `--reference` are resolved relative to the
Notarius process working directory.
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate dnd-session --config /absolute/path/to/notarius.yml
~~~
Do not copy the repository example's relative profile path into a deployment
without preserving its configuration-relative layout. The complete path and
profile rules are defined in [Configuration](../config.md).
## Supply The Transcript And References
Preflight the deployed configuration before processing sessions and whenever
it changes:
Use the [Seriatim JSON contract](../integrations/seriatim.md). Preserve segment
IDs because artifact citations use those source-unit ranges. If the caller
maintains a final trimmed transcript tier, select that same session content
consistently for later consumers.
```sh
notarius config validate \
--config /absolute/path/to/notarius.yml \
--pipeline dnd-session
```
Run with explicit input/output and pipeline-level references:
Provide credentials through the environment or the documented configuration
mechanism. Do not put credentials in command arguments, generated
configuration, or logs.
## Supply The Transcript
The complete pipeline consumes a Seriatim JSON document. The
[Seriatim input contract](../integrations/seriatim.md) defines its required
metadata, segments, and validation rules. Preserve segment IDs: D&D artifact
citations use those segment IDs as source-unit ranges.
When the caller maintains several transcript tiers, use the final trimmed JSON
transcript so extraction operates on the same session content presented to
later consumers. For example, Narratio identifies this implemented artifact as
`narratio.transcript.final_trimmed` and normally stores it at
`transcripts/final.trimmed.json`.
Notarius generates a stable prompt session from the resolved input module and
the exact input bytes. An ordinary orchestrator should not pass `--session-id`.
Use that override only when intentionally changing the routing relationship
between invocations; it is not a credential or output identity.
## Run Notarius
Invoke the pipeline with explicit absolute paths and request its
machine-readable receipt:
```sh
~~~sh
notarius run dnd-session \
--config /absolute/path/to/notarius.yml \
--input /absolute/path/to/transcripts/final.trimmed.json \
--input-file /absolute/path/to/transcripts/final.trimmed.json \
--output-dir /absolute/path/to/notarius-output \
--reference party=/absolute/path/to/references/party.txt \
--reference players=/absolute/path/to/references/players.txt \
--reference glossary=/absolute/path/to/references/glossary.txt \
--reference spell_catalog=/absolute/path/to/references/spells.json \
--json
```
--format json
~~~
Each unqualified reference is pipeline-scoped: Notarius supplies it to every
selected D&D target that declares the slot. A deployment may omit an optional
reference it does not maintain, and may use the lane- or binding-qualified
forms from the [CLI reference](../cli.md#reference-selectors) for an exceptional
override. The registry, scene-description, combat-turn, and NPC-occurrence
references declared between ordered steps in the complete configuration are
generated artifacts. Do not pass those handoffs on the CLI.
Only supply optional references the deployment maintains. Unqualified selectors
reach every selected target declaring the slot; narrower overrides follow the
[selector contract](../cli.md#reference-selectors). Generated registry, scene,
combat, and NPC-occurrence handoffs stay in pipeline configuration, not CLI file
bindings.
The caller should:
The ordinary input-based session is suitable without an override. Use
`--llm-session-id` only to intentionally change its native selection.
Sessions correlate provider routing; they are not credential or output identities.
- capture stdout and stderr separately;
- propagate cancellation and impose an operator-appropriate timeout;
- wait for process completion before interpreting stdout; and
- retain stderr for diagnosis without copying secrets or transcript content
into other logs.
Capture stdout/stderr separately, propagate cancellation, impose an appropriate
caller deadline, and wait for completion. Parse a successful report only after
status zero; failed writes can leave partial stdout. Nonzero status after
publication can still leave valid artifacts for deliberate recovery.
Only exit status 0 permits decoding stdout as a receipt. Ignore stdout after a
nonzero exit because a failed receipt write can leave partial bytes. The
[CLI reference](../cli.md#output-streams-and-exit-statuses) defines the complete
stream and exit-status contract.
## Locate And Read Artifacts
## Discover The Published Bundle
Use the report's absolute `output_directory`, not a newest-directory scan.
The report's exact fields and fallback qualification belong in
[CLI Reference](../cli.md#completion-report). There is no receipt schema,
index/manifest traversal, or descriptor inventory to load.
Decode the successful stdout document as a supported run-result schema. For
the current contract, `schema_version` is `notarius.run-result.v2`. Tolerate
unknown fields allowed by that version, but reject an unsupported schema
version.
Use the receipt's absolute `output_directory` as the exact run-specific bundle
root. Do not scan the output root for its newest directory, guess a run ID, or
construct a bundle path. Resolve `index_file` beneath `output_directory` and
reject an absolute logical path or any result that escapes the bundle root.
The complete configuration uses the application validation defaults. A caller
that requires fully validated D&D artifacts must also require receipt
`validation_status: approved`; a successful `incomplete` result reflects the
configured validator-failure continuation policy and carries its bounded
validator provenance in `validation_summaries`.
Read `index.json` and locate each requested lane in `output_files` by its exact
`lane_id`. Do not guess a lane filename. Before decoding a payload:
1. resolve its descriptor's relative `file` beneath the bundle root with the
same confinement check;
2. verify the descriptor's media type and schema identity against the linked
artifact contract; and
3. decode the payload according to that contract.
The [published JSON output contract](../integrations/json-output.md) defines
the index and bundle layout. Treat all paths obtained from a decoded external
document as untrusted until confined to their documented root.
The complete configuration uses safe literal lane IDs: each table entry below
is at `lanes/<lane-id>.json` beneath that run directory. Decode the configured
domain contract directly. All ten lane artifacts plus the two enabled/available
auxiliaries give twelve deliverables; a count is not a substitute for checking
the files required by the caller.
## Complete Artifact Inventory
When every configured lane is accepted, the complete example publishes these
lane artifacts:
| Lane ID | Purpose | Canonical contract |
| --- | --- | --- |
| `item-registry` | Canonical registry of encountered items and currency. | [Item registry](../integrations/dnd-item-registry-artifacts.md) |
@@ -150,72 +91,52 @@ lane artifacts:
| `location-occurrences` | Source-grounded location occurrences. | [Location occurrences](../integrations/dnd-location-occurrence-artifacts.md) |
| `enemy-events` | Source-grounded enemy combat events. | [Enemy events](../integrations/dnd-enemy-event-artifacts.md) |
The JSON encoder always publishes these bundle-management files:
The complete configuration also selects two pipeline-wide files:
| File | Purpose |
| --- | --- |
| `index.json` | Discovery document for lane and pipeline-wide artifacts. |
| `manifest.json` | Run provenance and result summaries. |
| `rejected.json` | Rejected pipeline outputs. |
| `warnings.json` | Actionable process-degradation warnings. |
| `diagnostics.json` | Advisory and observation findings for accepted artifacts. |
- [`chunk-map.json`](../integrations/chunk-map.md), the materialized plan/chunks.
- [`evidence-context.json`](../integrations/evidence-context.md), the union of
selected cited units and their configured surrounding window.
The complete configuration also requests two pipeline-wide artifacts:
They are not lanes and need no discovery descriptor. Their intrinsic payload
schemas are unchanged. Evidence is reading context, not authoritative lane
attribution; surrounding units do not widen citations in lane artifacts.
No index, manifest, rejection/warning/diagnostic sidecars are required.
- [`chunk-map.json`](../integrations/chunk-map.md), the accepted chunk plan and
chunk metadata; and
- [`evidence-context.json`](../integrations/evidence-context.md), a reading
excerpt containing the union of selected cited source units and the
configured surrounding window.
## Decide Consumer Acceptance
Discover both from their top-level `index.json` descriptors rather than
treating them as lanes. Evidence context is convenient reading material, not
authoritative provenance; citations in the normalized lane payloads remain the
evidence contract.
Process completion does not establish the caller's required artifact set,
semantic quality, or fresh validation under changed policy. A complete-workflow
caller should check all ten required lane files against their contracts. A
subset consumer can choose a narrower set deliberately. Empty valid domain
collections remain distinguishable from missing/incompatible files.
Every optional or lane file is published only when its corresponding artifact
is available. A successful process does not guarantee that all configured
lanes were accepted.
Explicit permissive execution can complete with qualified fallback. Decide
whether to accept that and inspect positive `fallback_count` when relevant.
The count identifies emitting operations, not individual affected lanes.
Fallbacks satisfy intrinsic/downstream invariants but not ordinary semantic
approval; valid downstream results affected by them also avoid cache reuse.
## Decide What Counts As Consumer Success
Default cache reuse does not repeat semantic assessment. For a deliberate model/
policy experiment requiring fresh inference, select bypass/refresh under
[configuration controls](../config.md#producer-controls). Do not look for retired
validation ledgers or treat optional debug serialization as an API.
Exit status 0 means Notarius completed the pipeline and published its result
bundle. The receipt or bundle may still report warnings, rejected outputs, or
missing lane descriptors. A downstream consumer must define its own required
artifact set explicitly.
A caller that claims to consume the complete D&D workflow should normally
require all ten lane IDs in the table and verify each descriptor's expected
contract. If any required lane is missing, rejected, or incompatible, fail the
caller's extraction step while retaining the Notarius bundle for diagnosis. A
consumer that needs only a subset may define and document a narrower policy.
Keep the successful receipt with the complete published bundle. Retain
`manifest.json`, `rejected.json`, `warnings.json`, and captured process logs as
required by the caller's provenance, diagnosis, and retention policies. Avoid
selectively copying payload files without also preserving enough index and
manifest information to identify their originating run and contracts.
The transcript, lane artifacts, evidence context, manifest, debug data, and
logs can all contain private campaign information. Apply the same access,
publication, and retention controls used for the source transcript.
Retain useful domain files and caller-owned invocation/report evidence. Capture
failure after publication does not invalidate completed artifact writes, but
requires deliberate caller recovery rather than parsing partial success output.
A failed publication can leave an incomplete directory. Transcript-derived
artifacts, evidence, cache, debug, and streams can contain private campaign data;
apply the caller's sharing and retention choices.
## Consumer Checklist
- Validate the deployed Notarius configuration and `dnd-session` pipeline.
- Pass the final trimmed Seriatim JSON transcript with stable segment IDs.
- Use absolute configuration, input, output-root, profile, and reference paths
in service deployments.
- Capture stdout and stderr separately and enforce cancellation and timeout.
- Parse stdout only after exit status 0.
- Accept only supported receipt, index, and artifact schema versions while
tolerating permitted unknown fields.
- Use the receipt's `output_directory`; never guess the run directory.
- Confine `index_file` and every descriptor path to the published bundle root.
- Discover lanes by `lane_id` and verify descriptor compatibility before
decoding payloads.
- Enforce an explicit required-lane policy and inspect rejections and warnings.
- Preserve the receipt and sufficient bundle provenance for every retained
artifact.
- Protect all transcript-derived files and diagnostic streams as sensitive
campaign data.
- Validate application configuration and the selected pipeline offline.
- Preserve Seriatim source-unit IDs.
- Pass source, output root, and optional campaign references as first-class inputs.
- Keep generated handoffs configured; avoid external/generated collisions.
- Separate streams, propagate cancellation, and check status before parsing.
- Use the native report directory and configured domain/auxiliary paths.
- Decode supported payload contracts and check the caller's explicit required set.
- Decide whether qualified fallback and cached acceptance meet caller needs.
- Retain only the artifact/report/evidence records useful to the caller.
- Treat source-derived data as sensitive; do not rely on a sanitized debug bundle.

View File

@@ -0,0 +1,143 @@
# Migrating To Native Configuration And Commands
This guide maps retired Notarius interfaces to the implemented native workflow.
It is migration material: the old spellings below are not accepted aliases.
[Configuration](../config.md), [CLI Reference](../cli.md), and
[Operations](../operations.md) own the current contracts. Domain artifact schemas
and lane filename mapping are unchanged.
## Update Caller Arguments
| Former interface | Current equivalent / intent |
| --- | --- |
| `notarius --version` | `notarius version`. |
| `pipelines list` | `pipeline list`. |
| `config validate --pipeline ID` | `pipeline validate ID`; native `config validate` checks the application document. |
| `config effective` | `config show`; scopes are `app` and `promptkit`. |
| Positional `config explain POINTER` | `config explain --path POINTER`; use native list/history options for discovery. |
| `config profile ID` | `promptkit show profile QUALIFIED_ID`; this reports stored fields, not a copied completed target. |
| `--config-overlay NAME` | `--overlay NAME`. |
| Run `--input PATH` | `--input-file PATH`. |
| `--only a,b` | Repeat literal `--lane a --lane b`; commas are no longer separators. |
| `--json` | `--format json`; YAML/text are also native report formats. |
| `--session-id ID` | `--llm-session-id ID`. |
| `--reasoning-effort VALUE` | `--llm-reasoning-effort VALUE`. |
| `--clear-reasoning-effort` | Explicit `--llm-reasoning-effort=`; omission retains native inheritance. |
| `--resume`, `--recompute-step`, separate `--chunk_cache`/`--chunk-cache` | Ordinary accepted-result reuse, with invocation-wide `--cache auto\|bypass\|refresh`. No explicit resume or selective checkpoint barrier. |
`run` and `pipeline run` are two native routes to the same command. Put flags
after the complete command path. Singleton occurrences are all parsed, with the
last successfully parsed value retained. False/zero/empty supplied values are not
omission. Canonical `--llm-*` execution overrides reach producers, correction,
and validators; shorter ckprompt aliases apply only to their installed PromptKit
commands. Help works offline on subcommands.
## Migrate Configuration And Resources
Version 6 is the sole application version; bumping the header alone does not
translate old fields. Use the maintained
[minimal](../../examples/dnd-minimal/config.yml) or
[complete](../../examples/dnd-complete/config.yml) configuration as a starting point.
- Replace `promptkit.profile_file`, `profile_dir`, and `local_backend` wrappers
with native settings beneath the main file's `promptkit`, or wrapperless
`prompts.yml` / recursive `prompts/` companions beside that selected main file.
Companion files form strict peers, not filename-priority layers.
- Use identified `backends`, `profiles`, and `prompts` lists with literal `id`
values and collections. The embedded profile is
`notarius/dnd-extraction`; initial/correction prompt IDs are also qualified,
for example `notarius/dnd.spells` and `notarius/dnd.spells.repair`.
- The root bundled backend is `openrouter`. Retired external provider catalogs
are not loaded as parallel sources; declare needed backends/profiles through
native resources. Do not infer backend identity from an endpoint or model.
- Use native root `config` imports and preserve declaration-relative paths.
Remove old per-prompt resource-version wrappers such as `v1`; resource IDs no
longer select those versions.
- A later same-ID resource replaces the whole earlier record. Use a distinct
sibling with `extends: {id: parent}` to retain fields, not a partial same-ID
replacement or self-inheritance. Profile/backend references to collection
resources use qualified IDs; sibling inheritance is local to its list.
- Preserve deliberate null/empty/zero choices under native semantics. Null
endpoint/key-environment values can allow backend fallback; empty strings can
clear those sources. Inspect native effective values/history rather than
assuming old wrapper null behavior.
- Keep prompt-declared schemas. Inline schemas, source-relative `schema_file`,
and explicit-root `schema_path` are native alternatives. Replacing a collection
schema root does not retain missing-file fallback to embedded resources.
Review [native resource and schema rules](../config.md#promptkit-profiles) before
reusing an old profile file. The complete example's
[companion](../../examples/dnd-complete/prompts.yml) demonstrates current inheritance.
## Separate Retry Intent, Mode, And Capacity
Producer `retries` intended for semantic correction becomes
`max_additional_turns`, excluding the initial response. Binding overrides pipeline;
omission inherits and explicit zero disables semantic correction. Native growing
continuation replaces latest-only manual replay, and each revised candidate gets
the full applicable assessment chain, including its final permitted turn.
Remove validator `retries`, generic deterministic retries,
`structured_output_repair_attempts`, and the application `promptkit.transient_retries`
wrapper. PromptKit owns transient failures and structural repair. Run-wide
transient customization uses `--llm-transient-retries`; structural customization
belongs in native prompt output contracts. Bundled prompts leave repair counts
unspecified. Former total provider-attempt parity is not promised.
Replace failure-category `validation_policy` and its `fail_run`, `reject_output`,
and `warn_continue` choices with producer `mode: strict|permissive`. Strict is
the default, including normalization. Permissive explicitly requests a supported
module fallback, not incomplete ordinary acceptance. Cancellation does not fall
back; unsupported fallback construction fails. Completion discloses actual
fallback emitters independently of warning visibility.
Replace `concurrency.total_llm` and `concurrency.stage_workers.extract` with
`concurrency.workers`, covering ready extraction and lane completion together.
Choose native backend capacity independently. There is no cross-backend global
LLM ceiling, inferred per-backend translation, or extra capacity queue/retry.
The [configuration reference](../config.md#concurrency-output-cache-and-debug)
owns current defaults and controls.
## Replace Both Legacy Caches
Replace nested `cache.chunk_plans` / `cache.checkpoints` directories and recording
switches with root `cache_directory` and pipeline/binding `cache`. An explicit
invocation `--cache` overrides every binding. Auto reads/stores acceptance;
bypass does neither; refresh skips reads and replaces only after new acceptance.
The initial prepared native message-content hash selects final accepted artifacts
and LLM plans. A hit is decoded/usability-checked, not semantically revalidated.
Model/settings/policy changes can still hit; use refresh/bypass for experiments
requiring fresh work. Source identity alone no longer fixes chunk boundaries.
Fallback and actually affected consumers skip reuse; unaffected predecessors
remain reusable after downstream failure. Failed refresh preserves old acceptance.
Do not copy, convert, or delete legacy records as an upgrade prerequisite. They
remain ignored and untouched, and the new cache populates through ordinary work.
[Operations](../operations.md#accepted-result-cache-and-recovery) owns recovery
and deployment-permission guidance.
## Replace Receipt And Sidecar Traversal
Stop expecting `notarius.run-result.v2`, `index_file`, validation histories,
warning counts, `index.json`, `manifest.json`, or reporting-only rejection/
warning/diagnostic files. Check process status, optionally decode the
[native completion report](../cli.md#completion-report), then read configured
lane/auxiliary [domain paths](../integrations/json-output.md).
Use the report's absolute run directory, not a guessed run ID or newest-folder
scan. Count actual deliverables rather than old normalized-output totals.
The report does not establish fresh validation or model quality; decide whether
positive fallback qualification is acceptable. Failed stdout can be partial,
and post-publication failure can leave valid artifacts with a nonzero status.
Debug remains explicitly selected and independent of native visibility modes.
Directory-only configuration does not enable it; explicit empty disables it.
The relative `latest` link updates at start, not completion. Full selected
evidence replaces the old summary/trace hierarchy; filenames/JSON shapes remain
private and arbitrary application content is not heuristically sanitized.
Do not replace receipt traversal with a debug-layout dependency or a new manifest.
Update callers using the [subprocess guide](subprocess.md) or
[complete D&D workflow](dnd-pipeline.md). These changes do not publish a new release
or rewrite historical release notes.

View File

@@ -1,115 +1,96 @@
# Using Notarius As A Subprocess
Use this workflow when an orchestrator runs Notarius and consumes its published
artifacts. The [CLI reference](../cli.md) owns invocation syntax and exit
statuses, while the [run-result receipt](../integrations/run-result.md) and
[Published JSON Output contract](../integrations/json-output.md) own the
durable result formats.
Use this workflow to run Notarius and consume domain files. [CLI Reference](../cli.md)
owns commands, reports, and statuses; [Published JSON Output](../integrations/json-output.md)
owns logical paths and payload links; [Operations](../operations.md) owns state
and recovery. See the [complete D&D workflow](dnd-pipeline.md) for its inventory
or [migration guidance](native-migration.md) for older callers.
For the maintained complete D&D workflow, including its transcript input,
configured lane inventory, and downstream acceptance checklist, see
[Consuming The Complete D&D Pipeline](dnd-pipeline.md).
## Prepare And Run
## Run And Check The Process
Use an argument vector with explicit paths appropriate to the deployment.
Absolute paths avoid dependence on a service's working directory. Keep stdout
and stderr separate, and choose caller cancellation/deadline behavior.
Optionally preflight a selected configuration and pipeline before work starts:
Validate the application and pipeline offline:
```sh
notarius config validate --config /path/to/notarius.yml --config-overlay production --pipeline pipeline-id
```
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate pipeline-id \
--config /absolute/path/to/notarius.yml --overlay production
~~~
Omit `--config-overlay` when the composed base configuration is the intended
selection; it is independent from any `--llm-profile` run override.
Omit the overlay for the composed base. Pipeline validation needs no transcript,
reference bytes, credentials, provider call, or state directory.
Invoke the run with explicit paths and machine-readable output. Capture
standard output and standard error separately; do not combine them before
processing the result.
Then run with first-class source and output inputs:
```sh
~~~sh
notarius run pipeline-id \
--config /path/to/notarius.yml \
--config-overlay production \
--input /path/to/source.json \
--output-dir /path/to/output-root \
--json
```
--config /absolute/path/to/notarius.yml --overlay production \
--input-file /absolute/path/to/source.json \
--output-dir /absolute/path/to/output-root --format json
~~~
Use absolute paths for supplied input, configuration, output-root, and
reference files. Pass each external reference as its own argument-vector pair;
do not construct and invoke a shell command. An unqualified reference selector
supplies that file to every compatible selected target. Lane and stage
qualification are available for exceptional overrides, while generated
same-run references remain part of configured pipeline composition. The
[CLI reference](../cli.md#reference-selectors) owns the exact selector and
precedence contract.
Pass external references as separate arguments, for example
`--reference party=/absolute/path/to/party.txt`. Unqualified selectors reach
compatible selected targets; narrower selectors are exceptional overrides.
Generated same-run handoffs stay configured, not CLI files. The
[reference selector contract](../cli.md#reference-selectors) owns matching and
precedence.
The maintained D&D subprocess workflow uses this facility for campaign context:
Supply credentials through the intended process environment, not arguments,
session IDs, generated files, or logs. Omitted session selection uses the
input-based default; use the [native override](../cli.md#run-wide-llm-overrides)
only when intentionally changing it.
```sh
notarius run dnd-session \
--config /absolute/path/to/notarius.yml \
--input /absolute/path/to/transcripts/final.trimmed.json \
--output-dir /absolute/path/to/notarius-output \
--reference party=/absolute/path/to/references/party.txt \
--reference players=/absolute/path/to/references/players.txt \
--reference glossary=/absolute/path/to/references/glossary.txt \
--reference spell_catalog=/absolute/path/to/references/spells.json \
--json
```
## Check Completion Before Parsing
Only pass the external references available to and desired by the deployment.
Notarius generates a stable prompt session for the resolved input module and
exact input bytes; reference changes do not change it. Pass **--session-id**
only when intentionally grouping different invocations under a different
session. Supply credentials through Notarius's documented configuration and
environment mechanisms, never as command-line arguments or generated
secret-bearing configuration. In particular, a session identifier is
provider-visible and is not a credential mechanism.
Wait for completion. Only successful status permits interpreting stdout as a
successful native report. Failed delivery can leave partial bytes; retain stderr
and available locations rather than parsing a structured error envelope.
Wait for the process before interpreting standard output. Only an exit status
of 0 permits decoding the receipt. On a nonzero exit, retain standard error for
diagnosis and ignore all standard-output bytes: a failed receipt write may have
left a partial document.
Optionally decode the [small completion report](../cli.md#completion-report).
Its `output_directory` is the exact run root; do not scan for the newest folder
or guess a run ID. The report is not a persisted receipt, schema-version envelope,
index, or validation/execution ledger.
## Discover Required Artifacts
A completed run may contain supported fallback. The caller decides whether that
is acceptable; inspect positive `fallback_count` when relevant. It counts
emitting operations, not affected files. Reuse performs ordinary usability checks,
not fresh semantic assessment. Callers needing new inference/assessment after
policy changes deliberately select bypass/refresh under the
[cache controls](../config.md#producer-controls).
Decode the successful receipt and accept the schema versions supported by the
caller. Use its `output_directory` as the bundle root. For the production JSON
output, resolve `index_file` under that root with a confinement check and reject
an absolute path or a result that escapes the root.
## Read Required Domain Files
Read the resulting `index.json` and locate each artifact by `lane_id`, not by a
guessed filename. Before decoding a selected payload, verify its descriptor's
media type and schema identity against the relevant published artifact
contract. The JSON bundle contract links to the available lane contracts.
Define required/optional lanes from the selected pipeline. Read their
[documented paths](../integrations/json-output.md#bundle-layout) beneath the
report directory and decode using the configured artifact contracts. For custom
lane IDs, apply the unchanged filename mapping; collisions are command failures.
No receipt/index traversal, manifest descriptors, or reporting sidecars are needed.
If `index.json` has an `evidence_context` descriptor, treat it as a
pipeline-wide artifact rather than a lane entry. Verify its six descriptor
fields before decoding the linked file according to the [Published Evidence
Context contract](../integrations/evidence-context.md). Decode its top-level
source-unit array as a reading excerpt. Obtain authoritative citations and lane
provenance from the normalized lane artifacts; the excerpt has neither and its
nearby units do not widen a lane artifact's cited source reference.
Optional chunk-map/evidence files use their documented paths when enabled and
available. Decode supported payload schemas. Evidence is a reading excerpt, not
authoritative lane attribution or a widened citation; normalized lane payloads
retain those contracts.
A zero exit status may still report rejected outputs, warnings, or absent
lanes. The caller decides which lane IDs are required for its own work and
which are optional; it should make that decision explicitly rather than infer
failure from the receipt counts alone.
Process completion, required artifact availability/compatibility, and caller
acceptance requirements are separate checks. A count alone cannot identify
which files were produced.
When complete validation is required, also require receipt
`validation_status: approved` and inspect `validation_summaries`. A successful
run with `validation_status: incomplete` contains a structurally valid result
that advanced after validator execution could not complete under the configured
`warn_continue` policy. It is not reusable checkpoint state and should not be
silently treated as fully reviewed by the caller.
## Preserve Useful Evidence
## Preserve Provenance And Handle Data Carefully
Keep domain files and caller-owned invocation/report records useful for provenance.
Reports can be explicitly redirected; Notarius does not automatically persist a
second report or require a metadata bundle. Debug is optional private evidence,
not a consumer protocol.
Keep the receipt with the published `manifest.json`, and retain
`rejected.json`, `warnings.json`, and `diagnostics.json` when review or later provenance requires
them. Treat the input, output bundle, cache, debug bundle, and captured process
logs as potentially sensitive data. Apply the caller's access controls and
retention policy, and avoid copying secrets into arguments, logs, or
provenance records. An evidence-context artifact contains source-unit text and
metadata and can cover most of an input; preserve and share it only when that
source content is authorized for the recipient.
Post-publication capture/report failure can return nonzero while leaving valid
artifacts. Preserve available files for deliberate recovery, but do not promote
partial stdout or incomplete publication to ordinary consumer success.
[Operations](../operations.md#output-bundles) explains those boundaries.
Inputs, artifacts, evidence, cache, debug, and streams may contain sensitive data.
Apply intended access, sharing, and retention controls. Evidence can cover the
whole source and is not inherently less sensitive.

View File

@@ -40,15 +40,16 @@ implementing changes. It owns implementation discipline and local commit rules.
| --- | --- | --- |
| Finding the package or component that owns current behavior | [Internal Overview](internal/overview.md) | It is the implemented component inventory and routes to focused internals. |
| 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), [Run Result Receipt](integrations/run-result.md), and [CLI Internals](internal/cli.md) | These separate generic caller workflow, the complete D&D workflow, the durable receipt contract, 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. |
| 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. |
| LLM clients, prompts, schemas, profiles, or scheduling | [LLM Runtime](internal/llm.md) | It documents the transport boundary and PromptKit integration. |
| 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. |
| Native execution, prompts, schemas, profiles, or admission | [LLM Integration](internal/llm.md) | It locates shared engine construction, native request/continuation calls, and evidence hooks. |
| 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. |
| Repository-specific release commands or diagnostics | [Source Releases](release.md) | The runbook supplies publication commands and recovery procedures. |
| Proposed or unimplemented behavior | [Roadmap](roadmap/) | Future work belongs only in roadmap documentation until implemented. |
| Future scope and planning | [Future work](roadmap/future.md) | The backlog records proposed work; active feature and implementation plans live alongside it when present. Implemented behavior belongs in canonical documentation. |
For an existing subsystem, also inspect its focused tests and the package-local
types and contracts before changing behavior.

View File

@@ -1,9 +1,9 @@
# Accepted Chunk Map
This document defines the optional durable `chunk-map.json` artifact in a
[published JSON bundle](json-output.md). It describes the accepted,
materialized chunk plan used by one run. It is not a lane payload and is never
an input to a later pipeline step.
[published JSON bundle](json-output.md). It describes the materialized chunk
plan used by one run, including a supported qualified fallback. It is not a lane
payload and is never an input to a later pipeline step.
## Contract Identity
@@ -16,8 +16,8 @@ an input to a later pipeline step.
| Schema name | `notarius_source_chunk_map_v1` |
| Schema version | `v1` |
The optional `chunk_map` descriptor in `index.json` identifies this artifact.
Export is controlled by the JSON output binding described in
Read this logical path directly when enabled and available; no discovery
descriptor is required. Export is controlled by the JSON output binding in
[Configuration](../config.md#module-bindings-and-validators).
## Wire Shape
@@ -30,7 +30,7 @@ Every payload has these required fields:
| `source_digest` | Lower-case `sha256:` digest of that source document. |
| `plan_digest` | Lower-case `sha256:` digest of the logical chunk plan. |
| `requested_chunker` | Chunk module selected by the resolved pipeline. |
| `producer` | Original accepted-plan producer. `input_module` and `chunk_module` are required; `llm_profile` is optional. |
| `producer` | Current run's plan component selections. `input_module` and `chunk_module` are required; `llm_profile` is optional and applies only to an LLM-backed chunker. Not historical cache execution provenance. |
| `plan_annotations` | Plan-level annotation namespace map; `{}` when none are present. |
| `chunks` | Non-empty execution-order chunk collection. |
@@ -47,9 +47,11 @@ valid JSON and are retained without interpreting a module-specific namespace.
`chunks` are in execution order. Their indexes are contiguous, start at zero,
and equal their array positions; chunk IDs are unique. The emitted map is built
only after the selected plan has been accepted and materialized against the
source document, so its ranges, unit counts, annotations, and digests describe
that exact plan.
after the selected plan has been materialized against the source document,
so its ranges, unit counts, annotations, and digests describe that exact plan.
Supported fallback still satisfies those invariants without asserting ordinary
semantic approval; run-level qualification belongs to the
[CLI report](../cli.md#completion-report).
The codec rejects malformed JSON, trailing content, unknown fixed-object
fields, invalid identities or digests, invalid annotations, duplicate chunk
@@ -67,12 +69,13 @@ annotations, producer identity, and ordered chunks.
## Publication And Compatibility
The map is present only when a chunk plan was accepted and its export is
enabled. It remains publishable if a later lane is rejected, but is absent when
chunk-plan validation rejects the plan. `requested_chunker` identifies the
current pipeline selection, while `producer` identifies the component that
originally produced the accepted plan; they may differ when an accepted plan is
reused.
The map is published when export is enabled, a materialized plan is available,
and the run reaches publication. Payload fields and schema are unchanged.
`requested_chunker` and `producer` describe the current composition; unified
cache entries retain the logical plan, not an earlier run's producer/profile
ledger. Reuse rematerializes against the current source without semantic
reassessment or claims of historical model execution. A strict failure does not
publish a successful bundle merely to expose this auxiliary.
The map contains structure rather than source content: it excludes transcript
bytes, source-unit metadata, chunk text, private model output, reference

View File

@@ -65,7 +65,7 @@ are unchanged: discovered has no holder; acquired requires `to`; lost and
consumed require `from`; transferred requires distinct non-`party` holders.
The only current downstream compatibility requirement is its registry handoff;
the normalized occurrence list is otherwise published for callers. See
[Configuration](../config.md#d-d-reference-slots) for the binding and
[Configuration](../config.md#dd-reference-slots) for the binding and
[JSON output](json-output.md) for publication.
See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact

View File

@@ -90,6 +90,6 @@ into the unchanged exact durable ID/name pair. The registry’s source reference
are never occurrence evidence. Unknown or ambiguous selections are rejected by
the occurrence contract. See the
[item-occurrence artifact](dnd-item-occurrence-artifacts.md) for that strict
wire contract, [Configuration](../config.md#d-d-reference-slots) for binding
wire contract, [Configuration](../config.md#dd-reference-slots) for binding
rules and validator selection, and the [JSON output contract](json-output.md)
for publication.

View File

@@ -80,7 +80,7 @@ are rejected rather than guessed or reassigned. The current transcript is the
only evidence source for an occurrence; registry evidence and provenance never
become occurrence evidence.
See [Configuration](../config.md#d-d-reference-slots) for the selectable slot
See [Configuration](../config.md#dd-reference-slots) for the selectable slot
and generated-handoff compatibility, [D&D module internals](../internal/dnd.md)
for implementation behavior, and the [JSON output contract](json-output.md)
for publication.

View File

@@ -86,7 +86,7 @@ Occurrence consumers receive names-only grounding; Notarius resolves the
selected canonical name and writes the unchanged exact durable ID/name pair.
Spells, combat turns, and the [enemy-event artifact](dnd-enemy-event-artifacts.md)
also receive names-only grounding for actor or subject display. None of these
projections supply later-artifact evidence. [Configuration](../config.md#d-d-reference-slots)
projections supply later-artifact evidence. [Configuration](../config.md#dd-reference-slots)
owns the `npc_registry` binding rules.
The [JSON output contract](json-output.md) defines publication, and
[D&D module internals](../internal/dnd.md) owns pipeline mechanics.

View File

@@ -17,7 +17,7 @@ in [Configuration](../config.md#references-and-ordered-handoffs).
| Base catalog | Embedded D&D 5e 2014 SRD catalog |
At most one overlay document may be bound. The maintained example is
[dnd-spell-catalog.json](../../examples/dnd-spell-catalog.json).
[spell-catalog.json](../../examples/dnd-complete/spell-catalog.json).
## Wire Shape

View File

@@ -9,9 +9,8 @@ logical-file discovery is owned by [Published JSON Output](json-output.md).
## Identity And Discovery
When enabled, the JSON bundle contains `evidence-context.json` and an
`index.json` `evidence_context` descriptor with the same six fields as other
pipeline-wide artifact descriptors.
When enabled and available, the JSON bundle contains `evidence-context.json`
at that documented logical path; no index descriptor is required.
| Property | Value |
| --- | --- |
@@ -22,16 +21,16 @@ pipeline-wide artifact descriptors.
| Schema version | `v1` |
| Logical file | `evidence-context.json` |
Consumers must discover the file from the descriptor, verify all six descriptor
fields, and decode only a supported schema version. The descriptor is optional:
its absence means evidence publication was not enabled for that bundle.
Consumers select this path from the configured output policy and decode the
supported payload contract below. Disabled or unavailable evidence is not
published. The identity and JSON shape above remain unchanged.
## Payload
The v1 payload is a top-level JSON array of generic source units. There is no
wrapper, source-level metadata, context grouping, lane identifier, or evidence
reference in the payload. An enabled configuration with no contributing
accepted evidence publishes `[]`.
evidence publishes `[]`.
```json
[
@@ -73,14 +72,16 @@ annotations or reshape source-owned metadata.
## Selection And Citations
The framework obtains direct source references only through typed evidence
projections of accepted normalized artifacts in the configured lane allowlist.
projections of published normalized artifacts in the configured lane allowlist,
including supported fallbacks and reused results.
It validates each reference against the current source document, expands its
range by `window_units` source-unit positions on each side, clamps at document
boundaries, and takes the union of all expanded ranges. The output contains
each selected source unit once in source-document position order, regardless
of numeric unit IDs. Repeated references, overlapping windows, and citations
from multiple lanes do not duplicate a unit. Rejected, failed, absent,
inactive, and unselected lanes contribute nothing.
from multiple lanes do not duplicate a unit. Failed, absent, inactive, and
unselected lane results contribute nothing. Evidence from a supported fallback
does not imply ordinary semantic approval; the completion report qualifies the run.
Normalized lane artifacts remain authoritative for citations and for which lane
cited a range. The excerpt has no lane attribution and must not be used to
@@ -94,10 +95,10 @@ the framework does not truncate the excerpt to meet an arbitrary size limit.
## Consumer Responsibilities And Data Handling
The artifact is additive to the JSON bundle and is not a lane payload,
normalized-output count, checkpoint, or generated reference. Consumers that
do not need it must tolerate an absent descriptor. Consumers that do use it
should validate the descriptor and payload before use, retain the artifact with
The artifact is additive to the JSON bundle and is not a lane payload or
generated reference. It counts as a deliverable when published, not as a lane.
Consumers that do not need it can ignore it. Consumers that do use it should
validate the payload before use, retain the artifact with
its schema identity when needed for a run record, and read citations from the
corresponding normalized lane artifacts.

View File

@@ -1,196 +1,79 @@
# Published JSON Output
This document defines the logical JSON bundle emitted by the production JSON
output encoder. The bundle’s physical destination, atomic publication, and
retention are operational concerns; see [Operations](../operations.md#output-bundles).
Output configuration, including chunk-map and evidence-context publication, belongs in
[Configuration](../config.md#module-bindings-and-validators).
This contract defines logical files emitted by the production JSON output
encoder. [Operations](../operations.md#output-bundles) owns physical placement,
publication failures, permissions, and retention. [Configuration](../config.md#module-bindings-and-validators)
owns output options; the [CLI completion report](../cli.md#completion-report)
identifies a successful run's directory.
## Bundle Layout
All paths below are logical, relative, slash-separated bundle paths. The
encoder always emits the first five JSON files below and adds lane or
pipeline-wide artifact files when their corresponding artifacts are available:
A subprocess caller first obtains the physical bundle root from the
[run-result receipt](run-result.md), then resolves `index.json` beneath that
root for the logical discovery described here.
Paths are relative, slash-separated paths beneath the run-specific directory:
| Path | Purpose |
| --- | --- |
| `index.json` | Entry point that names the other published files and lane payloads. |
| `manifest.json` | Run provenance and result summaries. |
| `rejected.json` | Rejected pipeline outputs. |
| `warnings.json` | Actionable process-degradation warnings. |
| `diagnostics.json` | Accepted-artifact quality advisories and normalization observations. |
| `lanes/<safe-lane-id>.json` | One normalized artifact payload for each lane. |
| `chunk-map.json` | Optional accepted chunk map, when its export is enabled and available. |
| `evidence-context.json` | Optional selected source-unit excerpt, when evidence publication is enabled. |
| `lanes/<safe-lane-id>.json` | One normalized domain artifact per available selected lane, including supported qualified fallback. |
| `chunk-map.json` | Optional materialized chunk map, when enabled and available. |
| `evidence-context.json` | Optional selected source-unit excerpt, when enabled and available. |
JSON files are pretty-printed with a trailing newline. Lane payloads are
accepted only when their media type is `application/json`.
There is no required index, manifest, persisted receipt, rejection file, warning
file, or diagnostic sidecar. Expected lanes come from pipeline configuration;
optional auxiliaries use the paths above. Consumers need no metadata bundle or
debug data to decode artifacts.
## `index.json`
The lane filename mapping is unchanged: trim the ID, replace characters outside
ASCII letters, digits, periods, underscores, and hyphens with underscores,
neutralize `..` sequences, and trim leading/trailing periods and underscores.
An empty resulting name or colliding paths fails encoding. Maintained D&D lane
IDs already map directly to their filenames.
`index.json` is the bundle’s discovery document. An approved run with no
normalized lanes has this valid minimal index:
```json
{
"manifest_file": "manifest.json",
"output_files": [],
"rejected_file": "rejected.json",
"warnings_file": "warnings.json",
"diagnostics_file": "diagnostics.json"
}
```
| Field | Required | Meaning |
| --- | --- | --- |
| `manifest_file` | Yes | Always `manifest.json`. |
| `output_files` | Yes | Lane descriptors sorted by `lane_id`. |
| `rejected_file` | Yes | Always `rejected.json`. |
| `warnings_file` | Yes | Always `warnings.json`. |
| `diagnostics_file` | Yes | Always `diagnostics.json`. |
| `chunk_map` | No | Descriptor for the pipeline-wide `chunk-map.json`; never a lane descriptor. |
| `evidence_context` | No | Descriptor for the pipeline-wide `evidence-context.json`; never a lane descriptor. |
Each lane descriptor has required `lane_id` and `file`. It may also include
`media_type`, `module_key`, `schema_id`, `schema_name`, and `schema_version`
when supplied by the normalized artifact. Each pipeline-wide artifact
descriptor (`chunk_map` or `evidence_context`) contains `artifact_kind`,
`file`, `media_type`, `schema_id`, `schema_name`, and `schema_version`. Their
payloads are defined by the [Accepted Chunk Map contract](chunk-map.md) and
[Published Evidence Context](evidence-context.md), respectively.
The lane path is derived from its lane ID. Characters outside letters, digits,
periods, underscores, and hyphens become underscores; `..` sequences are
neutralized; leading and trailing periods and underscores are removed. A lane
that produces an empty name, or two lanes that produce the same path, makes
output encoding fail.
Files are pretty-printed JSON with a trailing newline. Lane payloads require
`application/json`; the encoder validates the artifact boundary without
wrapping payloads in reporting metadata. Report presentation format does not
change artifact encoding.
## Lane Payloads
Each `lanes/<safe-lane-id>.json` file is the codec-owned normalized JSON for
that lane. Consumers should use the index descriptor’s schema identity rather
than infer a lane schema from its name. The current D&D payload contracts are
[spells](dnd-spell-artifacts.md), [NPC registry](dnd-npc-registry-artifacts.md),
[NPC occurrences](dnd-npc-occurrence-artifacts.md),
[combat turns](dnd-combat-turn-artifacts.md),
[item registry](dnd-item-registry-artifacts.md),
[item occurrences](dnd-item-occurrence-artifacts.md),
[scene descriptions](dnd-scene-description-artifacts.md),
[enemy events](dnd-enemy-event-artifacts.md),
[location registry](dnd-location-registry-artifacts.md), and
[location occurrences](dnd-location-occurrence-artifacts.md).
Each lane file is its codec-owned normalized JSON value. Select the contract
from the configured lane/module, not an absent discovery descriptor. Existing
D&D payload contracts remain unchanged:
## `manifest.json`
- [Spells](dnd-spell-artifacts.md).
- [NPC registry](dnd-npc-registry-artifacts.md) and
[NPC occurrences](dnd-npc-occurrence-artifacts.md).
- [Combat turns](dnd-combat-turn-artifacts.md).
- [Item registry](dnd-item-registry-artifacts.md) and
[item occurrences](dnd-item-occurrence-artifacts.md).
- [Scene descriptions](dnd-scene-description-artifacts.md).
- [Enemy events](dnd-enemy-event-artifacts.md).
- [Location registry](dnd-location-registry-artifacts.md) and
[location occurrences](dnd-location-occurrence-artifacts.md).
`manifest.json` is published provenance, not a copy of lane payloads or a
checkpoint store. Fields without a value may be omitted. Its top-level fields
group into the following externally observable summaries:
Intrinsic fields, identities, source references, and schemas are preserved.
Supported fallback meets intrinsic/downstream invariants without asserting
ordinary semantic approval. Run qualification belongs in the native completion
report, not new payload fields or sidecars.
| Group | Fields |
| --- | --- |
| Run identity and result | `run_id`, `pipeline_id`, `pipeline_digest`, `schema_version`, `validation_status`, `started_at`, `completed_at` |
| Resolved components | `input_module`, `chunker`, `extractors`, `merger`, `normalizer`, `output_encoder`, `artifact_lanes`, `validator_chains`, `module_metadata` |
| Source and references | `source_digests`, `references` |
| Published result summaries | `normalized_outputs`, `rejected_outputs`, `validation_summaries` |
| Execution summaries | `chunk_plan`, `checkpoint_decisions`, `llm_profiles`, `metadata` |
## Auxiliary Artifacts
`references` records provenance such as the target, slot, origin, digest,
media type, size, and generated-artifact identity. It does not contain
reference content. `normalized_outputs` and `rejected_outputs` likewise
summarize results without embedding lane payload bytes. A chunk-plan summary is
provenance for the plan used by this run; cache records, debug artifacts, and
other operational state are not published as bundle files.
[Chunk map](chunk-map.md) and [evidence context](evidence-context.md) are
pipeline-wide artifacts, not lanes. Their existing payload schemas and logical
paths remain; no index descriptor is required.
Each `validation_summaries` entry is a bounded outcome for one producer result.
It has required `status`, `producer_attempt_count`, and `terminal_action`;
the stage and affected step, lane, module, or chunk identity are present when
applicable. `status` is `complete`, `rejected`, or `incomplete`.
`rejecting_validators`, `reason_codes`, and `incomplete_validators` preserve
configured validator order and omit later duplicates. Entries contain no raw
candidate response, correction guidance, validator diagnostic message, or
artifact payload. The same shape may appear as `validation` on an affected
rejection entry.
Enabled, available auxiliaries count as deliverables, including when built
from reused results or supported fallback. Disabled/unavailable auxiliaries are
not published. Evidence can cover the complete source; authoritative citations
remain in normalized lane payloads.
When present, `metadata.session_id` is the effective non-secret routing
correlation identifier used for the run. It can be visible to providers and is
not a substitute for a cache or checkpoint identity. Its generation and
override behavior are defined by the [CLI reference](../cli.md#run).
## Consumer Use And Compatibility
Each `llm_profiles` entry identifies effective, non-secret LLM execution
provenance:
Check process status before decoding a successful native report. Use its absolute
run directory, then the configured lane and selected auxiliary paths. Decode
each file against its domain contract. The [subprocess guide](../consumers/subprocess.md)
and [complete D&D workflow](../consumers/dnd-pipeline.md) explain caller tasks.
| Field | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | Selected PromptKit profile identifier. |
| `provider` | No | Notarius adapter provider identifier. |
| `model` | No | Effective provider model identifier. |
| `backend_id` | No | Effective PromptKit backend registration identifier. Endpoint-only profiles omit it. |
| `reasoning_effort` | No | Effective opaque provider reasoning setting. An empty or explicitly cleared setting is omitted. |
These values describe observed execution; they are not a backend-registration
interface. Entries that differ by backend or effective reasoning remain
distinct even when their profile, provider, and model are otherwise equal.
## Rejections, Warnings, And Diagnostics
`rejected.json` is always an object with a `rejected` array. Each entry has
required `stage` and `message`; `step_id`, `lane_id`, `module_key`, `chunk_id`,
`chunk_index`, `validator_name`, `reason_code`, `attempt_count`, and
`diagnostic_artifact_path` are present only when applicable. An entry may also
contain the bounded `validation` summary described above; the existing singular
validator and reason fields remain the first configured rejection for
compatibility.
`warnings.json` is always the `notarius.warnings.v2` envelope:
```json
{
"schema_version": "notarius.warnings.v2",
"group_count": 0,
"occurrence_count": 0,
"groups": []
}
```
It contains only process warnings. `group_count` is exact, and
`occurrence_count` is the exact sum of its group occurrence counts.
`diagnostics.json` is always the `notarius.diagnostics.v1` envelope:
```json
{
"schema_version": "notarius.diagnostics.v1",
"group_count": 0,
"occurrence_count": 0,
"truncated": false,
"unrepresented_occurrence_count": 0,
"groups": []
}
```
It contains only advisory and observation groups. `group_count` counts groups
represented in `groups`; `occurrence_count` includes both represented and
unrepresented occurrences. When `truncated` is true,
`unrepresented_occurrence_count` is the exact number omitted from group
representation.
Each group has `disposition`, `category`, `reason_code`, framework-owned
`origin`, exact `occurrence_count`, bounded `samples`, and
`omitted_sample_count`. Samples carry safe `scope` and `message`, plus a chunk
ID and zero-based chunk index when applicable. A group retains at most three
distinct samples. The framework fails rather than truncating actionable
warnings beyond 128 groups; it represents at most 256 advisory/observation
groups and records further occurrences through the diagnostic truncation
fields above.
## Compatibility
The index is the authoritative map from a logical lane to its published
payload. Consumers must tolerate omitted optional manifest and descriptor
fields, and should rely on the linked artifact contract for each lane’s JSON
shape. This contract describes the published logical bundle only; it does not
promise a filesystem layout or expose internal state formats.
Removing reporting/discovery files is intentional, not a domain schema or
filename-mapping change. [Migration guidance](../consumers/native-migration.md)
replaces receipt/index traversal. Debug and cache are not public output contracts.
Post-publication failure can leave valid files; failed publication can leave a
partial directory. Neither supplies a successful completion report.

View File

@@ -0,0 +1,111 @@
# CommandKit Integration
Notarius declares its CLI through the selected native modules:
| Module | Selected release | Attribution |
| --- | --- | --- |
| `go.maximumdirect.net/commandkit` | [v0.7.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0) | [CommandKit](../oss/attribution.md#commandkit) |
| `go.maximumdirect.net/ckconfig` | [v0.10.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/README.md) | [ckconfig](../oss/attribution.md#commandkit-ckconfig) |
| `go.maximumdirect.net/ckprompt` | [v0.11.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/README.md) | [ckprompt](../oss/attribution.md#commandkit-ckprompt) |
[go.mod](../../go.mod) owns declared versions. The integrations are independently
versioned modules in the CommandKit repository; their selected tags/source
revisions are not the root module's tag. The [tagged consumer guide][consumer]
and [CLI contract][cli] own native declaration, parser, reporter, and outcome
mechanics. [Notarius CLI Reference](../cli.md) owns the installed product surface.
## Application Construction And Inputs
Notarius supplies identity, declarations, loaders, and domain handlers to
`commandkit.New`. Native help/version and installed shell completion need no
configuration, engine, provider, or run storage. Application pipeline commands
coexist with the full selected configuration/PromptKit suites; adoption is
implemented, not deferred behind a manual dispatcher.
The run convenience route is `commandkit.Alias`, not a forwarding handler.
Typed flags/arguments carry native `Supplied` values, preserving omission and
explicit empty/false/zero. Native parsing, repeated-value handling, mode ordering,
formats, and progress remain CommandKit-owned. The application chooses the
applicable inputs and their domain validation; it does not reconstruct parsing
or recursively execute another command.
## Configuration Scopes
Notarius installs a `ckconfig.Suite` with invocation state and two adapters:
`FromConfigKit` for the application and `FromConfigKitSubtree` for the native
PromptKit subtree. Both use the original successful application result, not
an engine-owned second configuration load. Overrides are enabled because the
loader actually passes native override records into its selected load.
The selected [adapter API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/configkit_adapter.go)
owns acquisition/focused-view semantics. Focused display/discovery retains native
root-relative explicit paths, whole-load validation, and source/findings evidence.
The application owns complete-selection result/engine reuse; comparisons retain
distinct sides including overlay/override presence. Native reports/differences
replace copied effective-configuration DTOs.
[ConfigKit integration](pkg-configkit.md) owns the load boundary and
[Configuration Internals](../internal/configuration.md) locates its implementation.
## PromptKit Suite And Run Overrides
Notarius installs `FromEngine` with request validation, request preparation,
smoke testing, namespace selection, and scoped convenience aliases through
`Declarations`. Standard upstream request builders are used without copied
inspection/probe implementations. The engine loader uses the same original
result and invocation state as configuration inspection/runtime.
Inspection/requirements do not call a provider. Concrete validation/preview
perform native request preparation; explicit smoke tests can perform network or
model work and retain native supported/applicable/result distinctions.
Pipeline validation is separately application-owned offline preflight, not a
mode added to native configuration validation.
Application run inputs reuse `NewResourceFlags` and `NewExecutionFlags`, selecting
profile/session and execution controls while leaving prompt/source inputs
module-owned. Native execution overrides reach initial, continuation, and nested
validator requests without mutating loaded settings. The selected
[request-flag API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/request_flags.go)
owns those reusable values; [PromptKit integration](pkg-promptkit.md) owns engine
execution. Exact installed syntax belongs in [CLI Reference](../cli.md).
## Reports, Diagnostics, And Outcomes
Handlers submit ordinary values through `Invocation.Reporter().Report`, with a
native text template where appropriate. JSON/YAML render the same report value;
there is no Notarius-wide envelope or separate success serializer.
The [completion contract](../cli.md#completion-report) is intentionally small;
domain artifacts, not a saved report, are the durable deliverables.
Native reporting handles result/diagnostic destinations, visibility, progress,
and delivery evidence. Application findings retain process-warning versus
advisory classification. Fallback qualification remains in the report even when
optional warnings are hidden. Requested capture is application work independent
of native verbosity; on success it finishes after publication and before reporting.
Application outcomes retain operation causes separately from native rendering,
output-write, and diagnostic-delivery failures. Post-publication failure retains
valid artifacts/available locations without rerun or repeated terminalization;
failed stdout can be partial. Standard commands keep their native classifications,
including diff differences; [CLI Reference](../cli.md#output-streams-and-exit-statuses)
owns exact statuses/caller behavior. See the upstream
[reporting guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md#invocation-reporting).
## Verification And Ownership
[Application tests](../../internal/cli/application_test.go),
[pipeline/preflight tests](../../internal/cli/pipeline_commands_test.go),
[native override tests](../../internal/cli/execution_overrides_test.go),
[real executable checks](../../internal/cli/native_process_test.go), and
[result-boundary tests](../../internal/cli/run_result_command_test.go) exercise
the actual kits with fake providers and temporary files. [Assembled recovery](../../internal/cli/recovery_contract_test.go)
verifies the same shared load/engine through domain work and publication/capture.
[CLI Internals](../internal/cli.md) locates declarations and orchestration;
[Operations](../operations.md) owns state handling and
[subprocess guidance](../consumers/subprocess.md) owns consumer workflow.
On dependency upgrades, review the core and separately versioned integrations,
installed capabilities, supplied-value/selection behavior, native outcomes,
and notices together rather than assuming root-version parity.
[consumer]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md
[cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md

View File

@@ -1,18 +1,71 @@
# ConfigKit Integration
Notarius uses the public root package
[`gitea.maximumdirect.net/eric/ConfigKit`](https://gitea.maximumdirect.net/eric/ConfigKit)
at v0.4.2 for version 5 configuration acquisition, imports, overlays, explicit
overrides, diagnostics, and safe inspection rendering.
Notarius uses `go.maximumdirect.net/configkit` at `v1.4.0` from
[the selected release](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0).
[go.mod](../../go.mod) owns the declared version; [attribution](../oss/attribution.md#configkit)
owns notices/source revision. The [tagged consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md)
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md)
own native loading, presence, inheritance, inspection, and error semantics.
Notarius owns the typed document, domain defaults and validation, runtime
conversion, catalog-dependent pipeline resolution, source-aware configured
paths, and command discovery. It uses only ConfigKit's public path, result,
diagnostic, and resolution-source APIs. Upstream documentation owns general
ConfigKit semantics; [Configuration](../config.md) owns Notarius's file and
operator contract.
## One Application-Owned Result
The v0.4.2 patch updates upstream release tooling and policy/licensing
documentation without changing configuration behavior or the public API. See
the canonical [ConfigKit attribution](../oss/attribution.md#configkit) for its
license and notices.
Notarius supplies a typed application document containing native
`promptkit.Settings`, and composes its definition with `promptkit.Configure`.
Application version/default/path/normalization/validation rules and native
resource identity/sensitivity rules participate in the same load.
Production composition selects the main source and calls `configkit.LoadLayered`.
It supplies bundled provider, embedded application, and main-relative operator
underlays before the selected main/import/overlay/explicit override layers.
Native filesystem/destination/source contexts remain attached; the application
does not flatten resources or reimplement source composition.
[Configuration](../config.md#configuration-discovery-and-precedence) owns
Notarius's selected sources/precedence; the upstream
[layered-input guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md#native-filesystem-and-layered-input)
owns the library mechanism.
The successful `*configkit.Result[config.Document]` supplies runtime conversion,
inspection, and `promptkit.NewFromConfig`. That handoff performs no second load,
callback run, or YAML round-trip. Runtime pipeline configuration is independently
owned; the original result retains native resource evidence and contexts.
See [PromptKit integration](pkg-promptkit.md) and the upstream
[component handoff](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md#component-handoff).
## Inspection And Invocation Selection
CommandKit's [ckconfig integration](pkg-commandkit.md#configuration-scopes)
adapts the original result for whole-application and focused PromptKit views.
Focused presentation does not load another document: whole-load validation and
source/findings context remain, while explicit metadata/explanation paths retain
native application-root coordinates.
The invocation-owned loader retains complete selections, including supplied
overlay/override values, and lazily builds one engine for each retained result.
Distinct comparison sides cannot accidentally reuse the same selection.
This is not process-global persistent configuration caching.
Inspection delegates to native result views, diagnostics, explanations, and diff.
ConfigKit sensitivity and PromptKit's composed sensitivity apply together.
Do not infer that arbitrary application text is safe, or replace marked-secret
omissions with heuristic content scrubbing. Exact syntax/selection behavior
belongs in [Configuration](../config.md) and [CLI Reference](../cli.md#configuration-commands).
## Application Ownership And Verification
Notarius owns application document meaning, source-aware operational paths,
runtime conversion, catalog-dependent pipeline resolution, and physical runtime
initialization. ConfigKit does not parse transcripts, construct pipeline modules,
materialize execution references, or allocate run storage.
[Configuration Internals](../internal/configuration.md) locates those implementations.
[Native settings tests](../../internal/core/config/native_settings_test.go),
[loader tests](../../internal/cli/native_load_test.go), and
[scope/diff tests](../../internal/cli/application_test.go) verify the real selected
libraries, retained origins/settings, frozen inspection, secret handling, and
selection isolation. [Assembled recovery](../../internal/cli/recovery_contract_test.go)
uses that same handoff through actual domain execution.
There is no parallel old-path ConfigKit integration or translation layer.
When upgrading, review the composed definition, original-result and source-context
handoff, focused views, and selected native command integration against the new
public contracts; do not infer compatibility from a successful module download.

View File

@@ -1,178 +1,125 @@
# PromptKit Integration
Notarius pins
[`gitea.maximumdirect.net/eric/promptkit` v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2)
as its in-process prompt engine. The upstream
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
owns the public engine API, and the upstream
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
owns prompt, profile, and schema file contracts.
Notarius uses `go.maximumdirect.net/promptkit` at `v0.24.0` from
[the selected release](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0).
[go.mod](../../go.mod) owns the version and [attribution](../oss/attribution.md#promptkit)
owns notices/source revision. The [tagged Go consumer guide][consumer] and
[format reference][formats] own native API, resource, and schema mechanics.
## Supported Boundary
## Configuration And Resources
Notarius relies on the root `promptkit` package to:
The application embeds native `promptkit.Settings`, composes rules with
`Configure`, and supplies its successful original ConfigKit result to
`NewFromConfig`. It selects the bundled OpenRouter underlay before loading;
engine construction does not add sources or reinterpret YAML.
[ConfigKit integration](pkg-configkit.md) owns that shared load boundary and
the upstream [application-owned-load guide][handoff] owns the library contract.
- construct an `Engine` with filesystem-backed prompt, schema, and optional
operator and application-fallback profile sources;
- prepare one frozen execution from a `RunRequest` with named inline artifacts,
variables, a direct session ID, prompt identity, profile selection, and
optional appended rendered messages, then
record credential-redacted details and run that exact execution;
- return rendered debug material, validated structured output, selected
profile, backend, effective model metadata, and token usage;
- register the optional conventional `local` backend through `BackendLocal`,
`LocalBackend`, and `WithBackend`;
- distinguish structured-output validation failure from execution failure; and
- identify a missing explicit profile through `ErrProfileNotFound` and backend
admission exhaustion through `ErrCapacityExceeded`.
Ordinary embedded prompt/profile declarations retain native filesystem contexts.
Main-relative operator companions, main imports, overlays, and explicit overrides
participate in the same application result. Qualified resources, whole-record
replacement/inheritance, null/presence, schema roots, and operator selection
belong in [Configuration](../config.md#promptkit-profiles), not a private
profile/catalog parser.
The pinned
[`BackendLocal`, `LocalBackend`, and `WithBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/backends.go)
owns the registration and backend-capacity contract.
Prompt declarations select default output contracts and schemas. Native
preparation resolves the selected schema and performs structural validation/
repair; Notarius does not register response schemas or pin omitted native repair
counts. Intrinsic durable artifact schemas remain application codec contracts.
Native backend/profile configuration is available directly; no conventional
local-backend wrapper or separate operator profile file setting is required.
For one completion, the adapter calls `PrepareExecution`, takes a
caller-owned `Details` snapshot, and calls `RunPrepared` for that same opaque
prepared execution. It defers `Discard` for every unexecuted handle. Explicit
profile preflight uses `Engine.InspectProfile`; it does not prepare a synthetic
prompt. PromptKit's prepared handle, inspection result, and capacity-error
types stay inside the Notarius LLM adapter.
One captured engine serves every model role in an invocation. Runtime-only
client/HTTP settings and an optional native `LLMClient` injection remain native
construction options. Request-specific execution/transient-retry selections remain
requests, not mutation of captured settings. Notarius adds no blanket transport
retry/repair or backend-admission defaults; declared profiles and native policy
control effective values.
When a PromptKit profile and runtime override leave `temperature`, `max_tokens`,
or `top_p` unset, Notarius leaves that control unset as well. Compatible
providers therefore apply their own defaults; an operator that requires a
specific sampling value must select it explicitly in the profile or runtime
override.
## Execution, Interpretation, And Continuation
Notarius does not use PromptKit's optional `ArtifactReader`. It materializes
source and reference content itself and supplies owned inline artifacts at the
adapter boundary. It also retains responsibility for pipeline retries,
scheduling, debug persistence, redaction, profile provenance, and conversion
from private model responses into durable domain artifacts.
Modules build `RunRequest` with selected prompt/profile/session, owned inline
artifacts and variables; they interpret `RunResult` into typed domain values.
Notarius materializes source/references and contextual identity projections
before execution. It uses native session selection rather than a compatibility
prompt variable. [CLI Reference](../cli.md#run-wide-llm-overrides) owns run-wide
controls and [Module Internals](../internal/modules.md) owns the extension recipe.
Notarius sends one stable effective session through PromptKit's direct session
field, which is authoritative for provider session behavior. It also retains
the same value as the `session_id` prompt variable for maintained prompt
compatibility. The generated identifier is 76 ASCII characters, within
PromptKit's 256-code-point session limit. Session IDs are non-secret
correlation identifiers and may be exposed to providers and provider
observability. The CLI contract owns generation and override behavior.
The shared producer path uses ordinary `Run`, or the retained prepared handle
described below. Native error and validation status are checked before
interpretation, including structural failure with no Go error.
The application assesses usable candidates through its complete configured chain.
Notarius records PromptKit's selected backend ID and effective reasoning
setting as optional run-manifest provenance. Endpoint-only profiles have no
backend ID. Debug prompt material also retains the selected backend ID and
PromptKit's stable lower-case `effective_model_params` JSON, which may include
`backend_id`. Notarius production configuration exposes one optional
conventional `local` registration. It does not expose a general user-defined
PromptKit backend registry. Endpoint-only profiles remain supported unchanged.
For actionable semantic correction, native `Coordinate` starts from a captured
exchange. Fixed inputs and prior responses remain in growing native history;
the follow-up adds new findings/assignment, not manually replayed latest-only
messages. Every delivered usable revision, including the final allowed response,
receives complete assessment. Native stopped/exhausted status is not domain
acceptance. Result-less failures do not recover earlier proposals, and undelivered
responses are unassessed. See the [continuation/coordination guide][continuation].
Notarius retains its application-wide scheduled client around the PromptKit
adapter. PromptKit may apply a narrower limit for the selected backend;
endpoint-only profiles have no such backend limit. The adapter translates
PromptKit capacity rejection into the provider-neutral Notarius
`ErrLLMCapacityExceeded` contract. It may include the normalized selected
backend ID in safe diagnostic context, without exposing PromptKit's capacity
error type. PromptKit's built-in client retries eligible transient HTTP failures
with its v0.11.2 default of two additional attempts per generation; Notarius
keeps pipeline-stage retries outside that completion boundary.
LLM validators call the same engine directly and return domain judgments or
unavailable assessment, without a producer turn loop. Native typed errors/causes
remain inspectable; Notarius adds context/disposition rather than a
provider-neutral replacement error taxonomy. Caller cancellation and native
operation timeouts remain distinguishable.
The adapter projects built-in generation failures as the application-owned
`LLMGenerationError`, retaining a safe failure kind, HTTP status when present,
and retry-exhaustion attempt count. Transport, malformed successful envelopes,
provider statuses, and generic generation failures remain distinct without
exposing PromptKit error values to Notarius callers.
## Prepared Reuse, Admission, And Execution Facts
## Profile Sources And Compatibility
For eligible cached producers, `PrepareExecution` supplies initial
`Details().MessageContentHash`; a miss executes that same handle with
`RunPrepared`, and unused handles are discarded. A hit reuses the accepted typed
artifact or checked plan without native execution, exchange restoration,
semantic reassessment, or historical usage. Correction retains the initial key.
Native preparation does not reserve model capacity; the [prepared-handle contract][prepared]
owns lifecycle. [Operations](../operations.md#accepted-result-cache-and-recovery)
owns Notarius reuse policy and [State Internals](../internal/state.md) its implementation.
Notarius gives PromptKit the configured operator profile source, registered
application fallback profile assets, and optional backend registration through
the same construction path for inspection and execution. PromptKit owns the
resulting source precedence and strict profile parsing: a matching operator
profile is a complete replacement for a fallback or built-in profile, while an
invalid matching document fails instead of falling through. The operator
configuration and deployment workflow are defined in
[Configuration](../config.md#promptkit-profiles) and
[Operations](../operations.md#promptkit-profile-deployment).
Native backend admission is independent of application ready-job workers.
No global LLM scheduler, extra admission queue, or application retry extends native
budgets. Completed producer turns release admission before assessment, so nested
validators can use the same limited backend. Strict/permissive terminal handling
and supported fallback remain application choices; [Configuration](../config.md#producer-controls)
owns those controls.
PromptKit owns `base_profile` resolution under its
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. An unset filesystem `api_key_env` is optional and may
reach the provider without authorization, which can result in a 401 or 403.
One invocation `ExecutionGroup` enrolls actual initial, continuation, and nested
validator calls once through composed observers. Native run/parent identity,
terminal coverage, and unknown usage remain native facts, not copied totals or
a durable profile ledger. The upstream [execution-facts guide][observations]
owns grouping semantics.
PromptKit accepts only the `developer`, `system`, `user`, and
`assistant` text-chat roles after normalizing case and surrounding whitespace.
Maintained Notarius prompt definitions use only `system` and `user`.
Optional capture retains available prepared/results/raw response/full exchange
views plus application context, without another preparation or model call.
Native credential omissions and ConfigKit marked-secret views remain intact;
ordinary content is not heuristically rewritten. Debug serialization is private,
not a consumer protocol. [Operations](../operations.md#debug-bundles) owns handling.
For application-owned semantic correction, Notarius uses PromptKit's
`RunRequest.AppendedMessages` after the ordinary rendered prompt. It supplies
exactly two messages in order: the latest validated producer response with
role `assistant`, then deterministic validation guidance with role `user`.
It never exposes a general caller-selected role API, accumulates earlier
correction turns, or changes the ordinary prompt prefix. Ordinary requests
leave appended messages unset.
## Inspection, Preflight, And Verification
PromptKit preserves supplied content but does not own Notarius's correction
bounds. Notarius rejects invalid UTF-8, blank, or oversized assistant material
(at most 1 MiB), guidance (at most 64 KiB), and combined content (at most
1,114,112 bytes) before preparing the request. The transport-neutral
application contract owns defensive copying and these limits. Default request
and terminal summaries retain only safe counts, digests, identities, and usage;
complete appended messages remain limited to the explicitly requested detailed
debug trace.
[CommandKit/ckprompt](pkg-commandkit.md) supplies resource inspection,
requirements, concrete request validation/preparation, namespaces, and explicit
smoke testing through the same loaders. Offline pipeline preflight checks declared
prompts and applicable profiles without synthetic requests, execution input reads,
credential lookup, or provider work. Partial profiles can pass inspection while
concrete preparation remains a later readiness boundary. Smoke execution is explicit.
PromptKit obtains its maintained OpenRouter and Rakestrawhome backend and
profile catalogs from independently versioned transitive modules. Notarius
does not import or register either catalog; PromptKit retains catalog source,
identity, precedence, credential, and capacity ownership.
[Native schema tests](../../internal/cli/native_schema_load_test.go),
[producer tests](../../internal/framework/pipeline/producer_test.go),
[nested assessment](../../internal/framework/pipeline/native_assessment_test.go),
and [assembled recovery](../../internal/cli/recovery_contract_test.go) verify the
selected integration using real libraries and fake providers. They cover custom
contracts, native status/causes, final-turn assessment, same-backend liveness,
initial-key reuse, fallback qualification, and observations without production
model-quality claims.
External catalog profile names and settings can change between dependency
releases, including removal without aliases. Review directly selected IDs and
inherited `base_profile` values when upgrading. An application-owned alias that
inherits an external profile does not freeze that profile's settings.
PromptKit's opt-in `promptkit-openrouter-standard` and
`promptkit-openrouter-auto` names provide name continuity within its
selected-and-tested dependency scope, not a fixed model or provider availability
guarantee. See the upstream
[catalog compatibility policy](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/policy/release.md#catalog-profile-compatibility).
[LLM Integration Internals](../internal/llm.md) locates current call sites.
An upgrade requires reviewing these native contracts, declaration/schema
contexts, command integrations, retained domain behavior, and notices together;
there is no private completion adapter to preserve.
Use a complete operator-owned profile with explicit backend or endpoint, model,
and settings when those choices must remain operator-controlled. The embedded
`dnd-extraction` fallback already follows this model and does not inherit an
external catalog profile. An upgrade updates Notarius's compiled-in catalog
checkpoint identity so prior profile-source checkpoints are not reused.
Notarius supports this boundary against PromptKit v0.11.2. Its fallback source,
prepared-execution, inspection, and typed capacity APIs are used as public
upstream contracts; other PromptKit APIs or file-format behavior are not
implicitly supported. A dependency upgrade requires reviewing the adapter,
profile-source construction, and this compatibility statement against the
pinned upstream documentation.
## Notarius Ownership
[LLM Runtime Internals](../internal/llm.md) describes how Notarius mounts
module assets, maps its transport-neutral completion contract, prepares and
executes requests, validates output, records provenance, captures debug
material, redacts errors, and preserves timeout ownership.
PromptKit provider error details do not cross the ordinary completion boundary.
Notarius exposes a provider-neutral generation category and optional status;
redacted provider details are retained only in requested debug material.
[D&D Module Internals](../internal/dnd.md) owns the embedded
`dnd-extraction` fallback profile and the maintained D&D prompt defaults.
[Configuration](../config.md#promptkit-profiles) defines how a Notarius
configuration selects one PromptKit profile source and optionally registers
the conventional local backend.
PromptKit API or format changes outside this boundary are not implicitly
supported. Updating the pinned version requires reviewing the adapter and
profile/configuration contracts against the upstream documentation. Maintained
production prompts use PromptKit's bounded structural-repair contract; their
current declaration is one additional repair attempt. Notarius retains the
transport-neutral boundary and does not expose PromptKit types to modules.
The v0.11.2 patch updates upstream policy and licensing documentation without
changing runtime APIs, profile settings, or dependency/catalog versions.
See the canonical [PromptKit attribution](../oss/attribution.md#promptkit),
[OpenRouter catalog notice](../oss/attribution.md#promptkit-openrouter-catalog),
and [Rakestrawhome catalog notice](../oss/attribution.md#promptkit-rakestrawhome-catalog).
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[handoff]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load
[continuation]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#coordinate-application-directed-turns
[prepared]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later
[observations]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#collect-selected-execution-facts

View File

@@ -1,93 +0,0 @@
# Run Result Receipt
`notarius run --json` writes this receipt to standard output when a run
completes successfully. It lets a subprocess caller discover the physical root
of the published output bundle without parsing interactive command output.
Command syntax, streams, and exit statuses are defined in the
[CLI reference](../cli.md); logical files within the bundle are defined in the
[Published JSON Output contract](json-output.md).
## Schema
The current schema version is `notarius.run-result.v2`.
| Field | Required | Meaning |
| --- | --- | --- |
| `schema_version` | Yes | Exactly `notarius.run-result.v2`. |
| `run_id` | Yes | The finalized Notarius run identifier. |
| `pipeline_id` | Yes | The effective pipeline identifier. |
| `output_directory` | Yes | Absolute path to the published, run-specific output bundle. |
| `index_file` | For the production JSON output | Logical path `index.json`; omitted for other output modules. |
| `normalized_output_count` | Yes | Number of final normalized outputs. |
| `rejected_output_count` | Yes | Number of recorded rejected outputs. |
| `warning_group_count` | Yes | Exact number of actionable warning groups. |
| `warning_occurrence_count` | Yes | Exact occurrences represented by actionable warning groups. |
| `diagnostic_group_count` | Yes | Number of represented advisory and observation groups. |
| `diagnostic_occurrence_count` | Yes | Advisory and observation occurrences, including unrepresented occurrences. |
| `diagnostics_truncated` | Yes | Whether advisory/observation group representation was truncated. |
| `validation_status` | Yes | The final run manifest validation status. |
| `validation_summaries` | No | Bounded per-producer validation outcomes; present when producer work ran. |
| `debug_directory` | No | Absolute path to the run-specific debug bundle when requested debug capture completed. |
For the production `json` output module, `index_file` is present only when the
completed run returned exactly one logical output file named `index.json`.
For another output module, its absence does not indicate a failed run.
`validation_status` is `approved`, `rejected`, or `incomplete`; `incomplete`
means one or more otherwise accepted results advanced under validator-failure
`warn_continue`.
```json
{
"schema_version": "notarius.run-result.v2",
"run_id": "run-1770000000000000000-0123456789abcdef0123456789abcdef",
"pipeline_id": "dnd-session",
"output_directory": "/work/results/run-1770000000000000000-0123456789abcdef0123456789abcdef",
"index_file": "index.json",
"normalized_output_count": 6,
"rejected_output_count": 2,
"warning_group_count": 1,
"warning_occurrence_count": 2,
"diagnostic_group_count": 3,
"diagnostic_occurrence_count": 5,
"diagnostics_truncated": false,
"validation_status": "incomplete",
"validation_summaries": [
{
"stage": "extract",
"lane_id": "spells",
"status": "incomplete",
"incomplete_validators": ["dnd/spells/source_refs"],
"producer_attempt_count": 1,
"terminal_action": "warn_continue"
}
]
}
```
## Paths And Bundle Discovery
`output_directory` and `debug_directory`, when present, are lexical absolute
paths. They identify the paths used by Notarius and do not resolve symlinks.
`output_directory` is the run-specific bundle, not the configured output root.
The receipt is a summary and discovery document. Its optional validation
summaries contain only stable status, identity, validator names, reason codes,
attempt counts, and terminal actions. It does not contain lane descriptors,
payloads, manifest payloads, rejection messages, warnings, raw model responses,
correction guidance, or file contents.
For the production JSON output, resolve `index_file` beneath
`output_directory`, reject path escapes, and use the
[Published JSON Output contract](json-output.md) to discover logical files and
lane payloads.
## Delivery And Compatibility
Notarius writes the receipt only after the output bundle has been published and
any requested debug terminal reporting has completed. Standard output is not
transactional: a result-write failure returns a nonzero status and can leave
partial bytes. Consumers must ignore standard output unless the process exits
with status 0.
Future versions may add optional fields to this schema. Consumers must tolerate
unknown fields. An incompatible field or semantic change requires a new
`schema_version` value.

View File

@@ -34,7 +34,7 @@ array. This minimal document is valid:
```
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 |
| --- | --- | --- |

View File

@@ -1,188 +1,157 @@
# CLI Internals
This document describes **internal/cli**, Notarius's production composition
root. The [CLI reference](../cli.md) owns command syntax and exit statuses;
[Configuration](../config.md) owns configuration values; and
[Operations](../operations.md) owns filesystem layout, recovery, and operator
procedures.
`internal/cli` is the production composition root. [CLI Reference](../cli.md)
owns syntax, reports, and outcome codes; [Configuration](../config.md) owns
settings; [Operations](../operations.md) owns physical state and recovery.
This guide explains declaration, loading, and orchestration owners, not another
public command manual.
## Inputs, Outputs, And Boundaries
## Native Application Construction
The CLI accepts process arguments, standard streams, and injectable options
used by tests and embedding code. It writes command results to the supplied
streams and returns a process exit status. For a run, it also creates the
production catalog and runtime collaborators, hands a prepared pipeline and
source bytes to the framework, and places the logical files returned by the
runner.
[NewApplication](../../internal/cli/application.go) returns a native
`*commandkit.App` from application identity and injectable options. Construction
declares commands without configuration discovery, engine creation, provider
calls, or run-storage allocation. The executable supplies build identity;
`RunWithOptions` is a convenience execution entry point, not a manual dispatcher.
It is the only boundary allowed to compose concrete registries, LLM clients,
cache/checkpoint collaborators, debug recorders, and physical output paths.
Pipeline modules receive interfaces and request data rather than CLI streams or
filesystem roots. The [Architecture](../policy/architecture.md) defines this
composition-root boundary; [Pipeline Internals](pipeline.md) owns resolution,
preparation, and runner mechanics after their inputs are supplied.
The constructor wires:
## Dispatch And Configuration Handoff
- native help/version and installed shell completion;
- application pipeline declarations and a native run alias;
- ckconfig whole-application and focused PromptKit scopes, sharing one loader;
- ckprompt resource/requirements inspection, concrete request validation,
prepared preview, namespace selection, and explicit smoke testing.
The root dispatcher handles help, version reporting, configuration validation,
effective-configuration inspection, explanation inspection, pipeline listing,
and a pipeline run. Version reporting resolves build
information through `internal/buildinfo` before production composition, so the
diagnostic remains available without configuration or runtime collaborators.
The public syntax, streams, exit classes, and version semantics are defined by
the [CLI reference](../cli.md). Other root commands normalize injectable
options before dispatch so that a missing production dependency fails as a
command error rather than reaching execution.
ckconfig adapters use the original application result and focused native subtree
view. ckprompt uses an engine loader through its standard builders rather than
application-owned copies of inspection DTOs. Ordinary resource inspection does
not become request preparation or an implicit probe. The
[native CLI reference][native-cli] owns parser/report mechanics.
Commands that need configuration use one shared ConfigKit-backed loader. The
CLI discovers the file, passes the requested overlay and only explicit
configuration-valued run overrides, and receives a **LoadedConfig**. The
configured discovery and precedence contract is in
[Configuration](../config.md), while the loading and resolution mechanics are
in [Configuration Internals](configuration.md).
## Invocation-Local Loading
`config effective` and `config explain` only render the loaded ConfigKit view;
they do not resolve pipelines or construct providers. Configuration validation without a selected pipeline checks structural
configuration only. Validation with a selected pipeline also builds the
effective catalog, resolves the pipeline, and verifies every explicit effective
PromptKit profile. Selected LLM-backed input, chunk, lane, output, and validator
profiles are inspected
against the configured PromptKit source and backend registrations without
loading a prompt or performing generation, so an unknown or invalid profile
fails before pipeline preparation. Credential availability remains an
execution-time concern. Pipeline listing validates configuration before
returning normalized, sorted identifiers.
[nativeLoaders](../../internal/cli/configkit_load.go) belongs to one invocation.
It selects the main source and assembles one layered ConfigKit application
result. Engine construction calls `promptkit.NewFromConfig` on that result,
with runtime-only client options; it does not load YAML again.
## Production Composition
The retained selection includes supplied-value state, overlay, and override
values. Repeated identical selections share a result/engine, while distinct
comparison selections cannot be memoized into one side. There is no
process-global loader cache. The selected main's native context anchors companion
imports; source edits do not mutate an existing captured engine.
The production composition helper allocates every framework registry and the
prompt-asset registry, then registers the generic, Seriatim, and D&D module
families in that order. The resulting registries provide both the module
catalog used for resolution and the concrete constructors used for preparation.
Tests may provide a catalog or registries instead; production code must not
silently merge an injected partial catalog with production registrations.
[Configuration Internals](configuration.md) owns definition, normalization,
origins, and conversion. Shared loaders allocate no output/cache/debug data.
The production LLM factory builds one PromptKit-backed client from the resolved
**promptkit.profile_dir** or **promptkit.profile_file** source, attaches the
profile-provenance recorder, creates one scheduler from the effective global
LLM limit, and wraps the client before it reaches modules. Registration and LLM
construction errors are returned before a pipeline is prepared. Configuration
field definitions remain in [Configuration](../config.md#promptkit-profiles);
the D&D registrar's fallback profile assets and the adapter mechanics remain in
[LLM Runtime](llm.md).
## Catalog And Preflight Boundaries
The factory also accepts `LLMRuntimeOverrides`, whose reasoning pointer
preserves inherit, replace, and clear states across the composition boundary.
Run orchestration constructs this value from the mutually exclusive
`--reasoning-effort` and `--clear-reasoning-effort` controls. Absence preserves
a nil pointer, replacement is trimmed, and clear uses a non-nil empty string.
The same override reaches the one shared production client, checkpoint
identity, and debug invocation metadata. Persistent reasoning configuration
remains owned by PromptKit profiles; Notarius configuration has no reasoning
field.
[catalog.go](../../internal/cli/catalog.go) composes generic, Seriatim, and D&D
registrars into typed registries, codecs, evidence projectors, and validator
defaults. Registration does not build an asset/schema registry or an LLM service.
Injected registries/catalogs are alternative sources, not implicitly augmented
with production entries.
[pipeline_commands.go](../../internal/cli/pipeline_commands.go) separates:
- listing: enumerate captured configured IDs without a catalog/engine;
- showing: domain resolution and composition description, without profile expansion;
- validating: domain resolution plus known-resource preflight, supplying the
same captured engine only when model roles require it.
[Preflight](../../internal/preflight/preflight.go) accepts collaborators/data;
it does not load configuration, register/construct modules, read execution
inputs, render CLI reports, or allocate state. Partial profiles pass native
inspection, with concrete request readiness deferred until preparation.
## Run Inputs And Native Overrides
[run_input.go](../../internal/cli/run_input.go) binds typed application inputs
and repeated literal selections. [execution_overrides.go](../../internal/cli/execution_overrides.go)
uses reusable ckprompt resource/execution inputs, preserving omission versus
explicit empty/false/zero. Only profile/session and execution controls needed
by pipeline runs are selected; prompt inputs stay module-owned.
The resolved run-wide profile selection reaches every LLM-backed role. Native
execution overrides travel through operation requests to producers, validators,
and continuation, without mutating loaded settings. The
[public reference](../cli.md#run-wide-llm-overrides) owns exact spellings/semantics.
Reference selectors are expanded at the CLI boundary using registered target
specifications. Pipeline/lane actions become exact binding changes after
specificity/conflict handling. Generic resolution receives exact reference
bindings/unbinds, not CLI selector grammar. External/generated conflicts and
required-slot/type checks remain with domain resolution; materialization follows.
[session.go](../../internal/cli/session.go) resolves the effective session from
explicit supplied input or the input-module/raw-byte policy before runner work.
Framework/model code transports it rather than deriving another session.
## Run Orchestration
After parsing and validating a run invocation, the CLI performs this ordered
handoff:
[pipeline_run.go](../../internal/cli/pipeline_run.go) performs the ordered handoff:
1. load and validate configuration with ConfigKit command overrides;
2. create and validate a safe run identity, then allocate a debug bundle only
when requested;
3. build the effective catalog, resolve requested reference changes, resolve
the effective pipeline, and inspect its explicit effective PromptKit
profiles;
4. materialize external or generated references and record redacted invocation
and resolution provenance when debug capture is enabled;
5. construct registries, the scheduled LLM client, and prepared modules;
6. read the source input once, resolve its effective session from the explicit
override or resolved input module and raw bytes, then construct requested
checkpoint collaborators and invoke the framework runner with that same
value; and
7. write the runner's logical output files only after a successful run, then
complete the command report and user-facing result.
1. Load/validate the selected application result and derive runtime configuration.
2. Generate a safe run identity and allocate requested capture.
3. Capture selected configuration, compose registries, expand reference actions,
and resolve the effective pipeline.
4. Obtain the shared engine when needed and perform offline preflight.
5. Materialize references, construct prepared typed modules, read input bytes,
and resolve the effective session.
6. Construct the accepted-result cache and optional recorder collaborator,
create one native execution group, and invoke the runner with independent
worker and execution selections.
7. Report process diagnostics, publish returned logical files only after runner
success, finalize requested capture, then submit the native completion report.
Preparation happens before source parsing, so module construction and
dependency failures cannot begin stage execution. The CLI also preserves the
framework's result and warning information when it writes summaries and the
final command result. Detailed state lifecycle, resume handling, and physical
path confinement are maintained in [Run State Internals](state.md) and
[Operations](../operations.md).
Modules receive the shared engine, operation data, and explicit collaborators,
not physical roots or CommandKit reporters. Detailed worker, assessment,
eligibility, and cache algorithms belong in [Pipeline Internals](pipeline.md);
physical publication/capture collaborators belong in [Run State Internals](state.md).
The CLI owns the versioned generated-session policy and resolves the sole
effective value before checkpoint construction. It records that value in the
final debug invocation summary when capture is enabled and passes it unchanged
to checkpoint identity and `pipeline.RunInput`. The public flag and stability
contract are defined by the [CLI reference](../cli.md#run); framework and LLM
packages only transport the supplied value.
Requested capture allocates before engine/preflight and finalizes once.
Primary operation causes and additional capture failures remain available.
Later report delivery failure does not rerun model work, remove valid artifacts,
or terminalize capture again.
The CLI also owns the scope grammar for reference flags. It enumerates the
selected chunk and lane targets from registered module specifications, expands
pipeline- and lane-scoped actions into exact stage-and-lane bindings, and
resolves overlapping bind and unbind actions by specificity before calling
configuration resolution. The generic pipeline therefore receives only exact
`ReferenceBinding` and `ReferenceUnbind` values and has no knowledge of CLI
selector syntax. Configuration resolution retains ownership of configured
external/generated conflicts, required slots, and module compatibility; file
materialization still occurs afterward.
## Native Reporting And Outcomes
For `run --json`, the CLI constructs and encodes its private run-result receipt
after a successful runner result is available, before it publishes logical
output files. It writes the prepared receipt to standard output only after
output publication and requested debug terminalization succeed. A receipt-write
failure exits with runtime status 1 and may leave partial standard-output bytes,
but the already-published output bundle remains complete and requested debug
reporting remains successfully terminalized. The CLI reports a bounded
command-owned error and does not repeat terminal reporting. The receipt remains
a CLI reporting concern rather than a framework or output-module responsibility;
its public contract is the
[run-result receipt](../integrations/run-result.md).
[run_result.go](../../internal/cli/run_result.go) submits one small application
value with a native text template. Native serializers render that same value.
Domain files, not a persisted report or ledger, are the deliverables.
Fallback qualification is independent of optional diagnostic visibility.
## Failure Mapping And Terminal Reporting
Warnings/advisories keep their domain classification and use the reporter's
diagnostic channel. Outcome helpers retain native configuration/preflight causes
and distinguish identifiable invalid input from operational/mixed failures.
CommandKit retains rendering/output/diagnostic delivery evidence separately from
the operation cause; quiet mode does not mask such failures.
Argument, flag, and invocation-combination failures are reported to standard
error before runtime composition and use the syntax error class. Once an
invocation is syntactically valid, configuration loading and validation,
resolution, registration, profile checks, reference materialization, module
construction, input reads, runner failures, output publication, and requested
debug handling use the runtime failure class. The public status numbers and
stream contract are defined in the [CLI reference](../cli.md#output-streams-and-exit-statuses).
The [completion report](../cli.md#completion-report) owns fields and
[stream/outcome contract](../cli.md#output-streams-and-exit-statuses) owns process
behavior. There is no universal Notarius envelope or parallel serializer.
When debug capture has been allocated, one command-state value records the
known run result. Guarded terminalization writes a success report once, or
attempts a failure report and error record once. A persistence failure is
reported in addition to the original failure and never replaces it. If a debug
path exists, failure output includes that path so the retained diagnostic data
is discoverable.
## Focused Verification
## Invariants To Preserve
- [Application tests](../../internal/cli/application_test.go) cover lazy built-ins,
shared scopes, selection evidence, and native diff outcomes.
- [Loader tests](../../internal/cli/native_load_test.go) and
[schema tests](../../internal/cli/native_schema_load_test.go) cover native
composition, captured contexts, and operator contracts.
- [Pipeline command tests](../../internal/cli/pipeline_commands_test.go) cover
listing/showing/preflight without execution inputs or state.
- [Override tests](../../internal/cli/execution_overrides_test.go) and
[run tests](../../internal/cli/pipeline_run_test.go) cover supplied values,
routing, references, sessions, and run ordering.
- [Reference tests](../../internal/cli/reference_contract_test.go) cover selector
specificity, generated conflicts, and materialization boundaries.
- [Native executable tests](../../internal/cli/native_process_test.go) cover the
real command routes and fake-provider presentations.
- [Completion tests](../../internal/cli/run_result_command_test.go) and
[recovery contracts](../../internal/cli/recovery_contract_test.go) cover retained
publication, capture/delivery failures, reuse, fallback, and native facts.
- Only the CLI composes production implementations and physical runtime roots.
- Configuration and resolved composition failures occur before module
preparation or source parsing.
- A runner's logical files are published only after a successful run.
- Production registries and a caller-supplied catalog or registries are
alternative composition sources, not an implicit mixture.
- A requested debug bundle has one terminal report attempt; its persistence
errors supplement rather than obscure the primary command error.
- User-facing flags, paths, exit codes, and configuration fields are defined
by their public documentation, not duplicated here.
Use focused CLI tests and pair with configuration/preflight tests when those
boundaries change. [Development](../development.md#validation) owns wider checks.
## Focused Tests
- **internal/cli/command_contract_test.go** covers dispatch, help, syntax and
runtime error classes, discovery, validation, and listing.
- **internal/cli/run_contract_test.go** covers the run handoff, publication,
debug reporting, and command-owned state collaborators.
- **internal/cli/production_contract_test.go** covers registrar composition,
production catalog contents, assets, and representative configuration
validation.
- **internal/cli/reference_contract_test.go** covers scoped CLI reference
expansion, specificity, bind/unbind conflicts, generated-reference
protection, origin separation, and materialization boundaries.
- **internal/cli/state_hardening_test.go** covers safe run identity, state
roots, and failure ordering.
Run **go test ./internal/cli** after changing command composition or command
behavior. Pair it with **go test ./internal/core/config** when the configuration
handoff changes.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md

View File

@@ -1,144 +1,148 @@
# Configuration Internals
This document describes the maintainer-facing configuration boundary in
**internal/core/config**. The [Configuration](../config.md) reference owns the
file format, fields, defaults, precedence contract, and selectable keys. The
[CLI reference](../cli.md) owns command syntax; this document does not redefine
either interface.
This guide explains the maintained configuration boundary and its composition-root
handoff. [Configuration](../config.md) owns source selection, syntax, fields,
defaults, and selectable modules; [CLI Reference](../cli.md) owns invocation.
[Architecture](../policy/architecture.md#configuration-and-provenance) defines
ownership. Do not infer operator contracts from private helper choices here.
## Boundary
## Owners And Handoffs
The configuration package turns a selected ConfigKit-composed YAML document
into a validated, independently owned configuration. It then resolves a
requested pipeline against a module catalog before the framework prepares or
runs anything.
| Owner | Responsibility |
| --- | --- |
| [core/config definition](../../internal/core/config/load.go) | Typed application document, native PromptKit configuration rules, application resolution/validation. |
| [CLI loaders](../../internal/cli/configkit_load.go) | Main-source selection, native underlays, invocation-local result/engine reuse. |
| [LoadedConfig](../../internal/core/config/loaded_config.go) | Retain the original result and derive independently owned runtime pipeline configuration. |
| [Config.Resolve](../../internal/core/config/effective_config.go) | Resolve a selected pipeline against the supplied catalog. |
| [preflight](../../internal/preflight/preflight.go) | Check known native resources from resolved composition and supplied engine. |
| Pipeline preparation | Construct typed execution collaborators from resolved, materialized inputs; see [Pipeline Internals](pipeline.md). |
| Boundary | Inputs | Outputs | Does not own |
| --- | --- | --- | --- |
| Loading | Selected file path, profile, overrides, and invocation directory | **LoadedConfig** with ConfigKit inspection metadata and a populated **Config** | Choosing the file path or reporting a command result. |
| Validation | **Config** | Structural configuration errors with pipeline, lane, or binding context | Module availability, capabilities, or construction. |
| Resolution | Valid **Config**, selected pipeline and lanes, runtime reference changes, LLM override, and module catalog | **EffectiveConfig** with a **ResolvedPipeline** | Materializing reference bytes, preparing modules, execution, or filesystem state. |
| Inspection | **LoadedConfig** and an optional JSON Pointer | Redacted effective YAML or explanation text | Pipeline selection, module preparation, or provider work. |
The production flow keeps one application-owned
`*configkit.Result[config.Document]`. That result feeds runtime conversion,
whole-app/focused inspection, and `promptkit.NewFromConfig`. Rendered YAML is
an operator view, not an interchange format for constructing the engine.
The CLI discovers a configuration file, invokes this package, and supplies the
result to the framework. Configuration never reads an input file, constructs a
module, or creates output, cache, or debug paths. Those responsibilities remain
at their respective [CLI](cli.md), [pipeline](pipeline.md), and
[run-state](state.md) boundaries.
## Definition And Application Meaning
## Loading And Validation
`Document` contains native `promptkit.Settings` at its PromptKit field.
`Definition` composes application defaults, version policy, sensitivity,
identified step lists, resolution, and validation with `promptkit.Configure`.
Native resource rules therefore participate in the same load rather than being
validated by a separate application parser.
ConfigKit acquires the selected root, imports, optional selected overlay, and
explicit CLI overrides in precedence order. Its document definition supplies
typed defaults, source-aware path normalization, and structural validation
before conversion to the independently owned runtime **Config**. Only
`NOTARIUS_CONFIG` participates in discovery; retired field-level environment
variables do not participate in loading. Version 5 decoding rejects scalar
module bindings and scalar external references. ConfigKit retains redacted,
historical inspection metadata while **LoadedConfig** keeps that implementation
detail private behind effective and explanation writers.
Application callbacks normalize pipeline identifiers and operational paths while
retaining presence/source history. The per-load state tracks original coordinates
as map keys move. Paths are resolved before normalization loses their source
coordinates. Inherited values retain their contributing origins; CLI path
assignments use invocation origin. See
[document paths](../../internal/core/config/document_paths.go) and
[pipeline document normalization](../../internal/core/config/pipeline_document.go).
**Config.Validate** checks configuration-only invariants before resolution. It
rejects incompatible profile sources, invalid state-surface values, unsupported
concurrency settings, malformed bindings and references, invalid retries, and
invalid pipeline, step, or lane structure. PromptKit local-backend validation
accepts only an absolute HTTP or HTTPS endpoint with a host and no user
information, query, or fragment, and rejects a negative local concurrency
limit. It also rejects a negative `promptkit.transient_retries` value; decoded
omission resolves to two, while explicit zero remains a distinct opt-out. Its
errors retain the closest known pipeline, lane, and binding context.
It deliberately does not require modules to be registered: that requires a
catalog and belongs to resolution.
ConfigKit owns parsing, imports, overlays, inheritance, typed composition, and
provenance. The application supplies meaning through supported rules. It does
not implement another inheritance resolver or translate retired inputs.
[The public reference](../config.md#imports-and-sibling-inheritance) owns exact
presence/null/list rules and processing order.
The exact user-selectable values and validation rules are defined in
[Configuration](../config.md). Keep document schema, source-aware normalization,
runtime conversion, and that reference aligned in the same change.
`Config.Validate` checks application-only state and pipeline structure without
requiring registered modules. Catalog-dependent compatibility belongs to
resolution. Configuration does not parse a source transcript, materialize
references, construct modules, or allocate run storage.
## Effective Resolution
## Production Source Assembly
**Config.Resolve** derives an absent extraction-worker value in an owned copy
and validates the configuration. A programmatically supplied worker value is
always explicit. It normalizes the requested pipeline ID, copies the selected
profile, and passes the non-empty command-level LLM profile override, requested
lane selection, and reference changes to the framework resolver.
`nativeLoaders.application` selects the main source and uses
`configkit.LoadLayered` with the application definition, native underlays,
selected overlay, and explicit overrides. Underlays come from bundled provider
resources, ordinary embedded application content, and main-relative operator
companions. Native source/filesystem contexts survive the load.
After module and validator selection, the resolver applies the effective
profile policy to LLM-backed bindings only: command override, binding profile,
pipeline profile, then the prompt default. Deterministic bindings remain
profile-free, and no second inheritance decision occurs during execution. The
public field definitions and precedence are owned by
[Configuration](../config.md#pipelines).
The embedded assets package supplies content, not registration behavior.
The operator companion uses a native main-relative context; it follows the
selected main rather than rediscovering the working directory. Strict peers,
optional absence, imports/destinations, and whole-record resource replacement
remain native composition. Source grammar and precedence belong in
[Configuration](../config.md#configuration-discovery-and-precedence).
The resolver retains configured `validation_policy` overrides and derives one
detached concrete terminal policy for the chunk producer and every lane's
extract, merge, and normalize producers. That field-by-field inheritance is
complete before preparation, and the effective values contribute to pipeline
and checkpoint identity; execution does not interpret configuration defaults.
Core `Load`/`LoadSource` entry points support selected sources and the same
definition/conversion for direct consumers and tests. They do not replace the
production composition root's underlay assembly. Do not accidentally introduce
a second production load by combining those paths.
The framework resolver supplies defaults, selects lanes, resolves validator
chains, checks registered module and artifact compatibility, validates module
options, and returns the fixed ordered pipeline shape. Positive validator retry
budgets require an LLM-backed selected validator; deterministic validators are
rejected during resolution. Eligible LLM-backed producer specifications also
contribute their declared correction protocol to the resolved metadata. The
resulting **EffectiveConfig** retains the selected ID, requested selection and reference
changes, a clone of the input configuration, and the resolved pipeline.
Callers may therefore retain or modify their input slices and maps without
changing the resolved result, and later consumers cannot mutate the original
configuration through the effective value. This ownership includes the nested
PromptKit local-backend value.
## Result Lifetime And Runtime Conversion
Resolution failures stop before module construction and source parsing. They
include an error path for an unconfigured pipeline, missing module, missing
capability, incompatible artifact variant, invalid option, invalid reference,
or invalid lane selection. CLI code maps these valid-invocation failures to the
runtime error class described in the [CLI reference](../cli.md#output-streams-and-exit-statuses).
`LoadedConfig.Result()` exposes the original typed result for intentional native
handoff. `FromResult` derives pipeline runtime settings without loading sources
or serializing settings again. `RuntimeConfig` returns a detached copy;
the native PromptKit configuration stays with its owning result/engine rather
than being copied into a private runtime wrapper.
## Resolved Identity And Redaction
`MainSourcePath` reads the retained non-imported main-file evidence. It does not
repeat discovery or assume the first acquired file is the main.
The framework assigns the resolved pipeline a deterministic SHA-256 digest
after defaults, lane selection, module bindings, reference bindings, validator
chains, selected correction protocols, effective LLM profiles, and artifact
schema identity have been resolved. The digest excludes
its own stored value. It identifies resolved composition rather than raw YAML
bytes, a debug payload, or all runtime state. The CLI records it as invocation
provenance before execution; cache and checkpoint identity have additional
owners in [Run State Internals](state.md).
Within one invocation, `nativeLoaders` retains results by complete
`ckconfig.Selection`, including overlay and override presence/values. Captured
override containers are copied. A repeated identical selection returns the
same result; distinct diff sides remain distinct selections. The engine is
constructed lazily once for its retained result. This is invocation state,
not a process-wide persistent loader cache.
Configuration publication uses ConfigKit's redacted effective YAML. Resolved
pipeline publication uses **RedactedResolvedPipelinePayload**, which copies
bindings and nested option containers, replaces credential-shaped values with
**[REDACTED]**, and omits materialized reference content while retaining safe
provenance. This redaction is deliberately narrow and does not authorize
recording arbitrary environment values or provider requests.
`NewFromConfig` consumes the completed result, preserving native contexts and
inspection evidence without rerunning callbacks or adding underlays. Runtime-only
HTTP/client settings and test provider options stay at engine construction.
[PromptKit's application-owned-load contract][handoff] owns the library API.
## Invariants To Preserve
## Effective Resolution And Preflight
- ConfigKit composition applies defaults, imports, an optional overlay, and
explicit overrides in one direction with retained origin metadata.
- A configuration is structurally valid before it is resolved, and a resolved
pipeline is compatible with the supplied catalog before preparation begins.
- Whitespace-normalized identifiers are unique wherever they identify a
pipeline, step, lane, worker, or reference slot.
- Runtime conversion and resolved-pipeline publication return detached data.
- The resolved PromptKit transient-retry budget is always passed to the shared
built-in client; document presence preserves an explicit zero.
- The resolved digest changes when resolved composition changes and never
includes itself.
`Config.Resolve` clones configuration, resolves an empty programmatic cache-root
selection, validates structure, and passes selected pipeline/lanes, profile/cache
overrides, and exact reference changes to `pipeline.ResolvePipeline`.
The framework resolves module/default/validator/type/reference compatibility and
concrete producer controls before execution. Input slices/maps and the original
configuration do not become mutable aliases of the effective result.
## Focused Tests
Presence-aware selections preserve explicit invocation profile clearing, cache
overrides, and zero semantic-turn controls rather than collapsing into omission.
Deterministic bindings remain
separate from LLM roles. A resolved-composition digest is not an accepted-artifact
cache key; [state ownership](state.md) is a different boundary.
- **internal/core/config/document_test.go** and
**operational_document_test.go** cover ConfigKit document loading,
normalization, imports, overlays, and overrides.
- **internal/core/config/validation_contract_test.go** covers configuration
invariants and contextual failures.
- **internal/core/config/effective_config_contract_test.go** covers defaults,
selections, overrides, resolution context, digest changes, and ownership.
- **internal/core/config/loaded_config_test.go** covers safe effective and
explanation rendering; **redaction_test.go** covers resolved-pipeline
redaction and reference-content exclusion.
Preflight consumes resolved data, the catalog, and the captured engine when model
roles are selected. It checks static initial/correction/validator dependencies and
applicable explicit/default profiles. It does not load configuration, construct
modules, read reference/input bytes, or manufacture a request to prove readiness.
Partial profiles remain valid; dynamic request selections are runtime checks.
Run **go test ./internal/core/config** after changing this boundary. Changes to
the handoff or resolved-composition semantics also need the focused framework
pipeline tests.
## Inspection And Sensitive Values
Native whole-app and focused views use retained ConfigKit evidence. Existing
effective/explanation writers delegate to that result rather than walking YAML.
Application sensitivity rules and native resource sensitivity participate in the
same definition. Source/runtime option containers must not be independently
reserialized as an alternative secret-handling mechanism.
Do not infer that arbitrary source, prompt, provider, or module-option strings
are safe to disclose. Capture uses native inspection and exact marked-secret
paths, not heuristic application-text rewriting. See [CLI composition](cli.md)
and [LLM integration](llm.md) for those consumers.
## Focused Verification
- [Document/native settings tests](../../internal/core/config/native_settings_test.go)
prove typed handoff, native rules, source-relative messages, and secret-aware views.
- [Path tests](../../internal/core/config/document_paths_test.go) and
[inheritance tests](../../internal/core/config/inheritance_test.go) cover origins,
explicit presence, overlays, and source/runtime ownership.
- [Control tests](../../internal/core/config/validation_policy_contract_test.go)
cover loaded omission/zero and resolved controls.
- [Effective resolution tests](../../internal/core/config/effective_config_contract_test.go)
cover catalog checks, selection, and detached results.
- [CLI loader tests](../../internal/cli/native_load_test.go) cover actual production
underlays, strict companions, imports, frozen messages, and distinct selections.
[Schema-load tests](../../internal/cli/native_schema_load_test.go) exercise native
operator schema preparation/execution.
Use focused configuration and CLI tests when changing this handoff. The
[development guide](../development.md#validation) owns repository-wide checks.
[handoff]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load

View File

@@ -1,9 +1,10 @@
# D&D Module Internals
This guide records the conventions shared by the production D&D module family.
It complements [Module Internals](modules.md), which owns generic registration
and extension mechanics, and [Configuration](../config.md), which owns the
selectable keys, bindings, reference syntax, and default validator chains.
This guide explains shared D&D implementation conventions.
[Module Internals](modules.md) owns generic typed extension mechanics;
[Configuration](../config.md) owns keys, bindings, reference syntax, and default
validator chains. [Pipeline Internals](pipeline.md) owns assessment/disposition
and [LLM Integration](llm.md) owns native execution.
## Durable Artifact Contracts
@@ -25,317 +26,222 @@ does not repeat their JSON shapes or schemas.
## Family Composition
The D&D registrar registers the family’s artifact codecs, extractors, typed
append-order mergers, normalizers, validators, prompt assets, fallback LLM
profile asset, and default validator chains. Each extractor and normalizer has
a stable module spec, explicit execution class, strict option decoding, and a
typed builder. Scene chunking, every extractor, and NPC, location, and
item-registry normalization are registered as `llm_backed`; the remaining
current D&D mergers and normalizers are `deterministic`. The metadata is
available to catalog inspection and resolved-pipeline debug data and determines
which selected bindings inherit the pipeline profile. The registry normalizers
use `single_response_v1`, forwarding corrections to their reconciliation
completion and retaining the accepted raw proposal only as an owned model
candidate. When deterministic proposal safety or typed application rejects a
group, they provide separate model-facing prose for a corrective module retry;
internal issue categories, reason codes, and operator messages remain
diagnostic-only. Configuration remains the canonical owner of the exact keys,
profile precedence, and validator order.
The [D&D registrar](../../internal/modules/dnd/register/register.go) composes
codecs, evidence projections, typed extractors/append-order mergers/normalizers,
validators, and default chains. Scene planning, extractors, and the three
registry normalizers are model-backed; current mergers and remaining normalizers
are deterministic. A model-backed module can still have an ordinary no-model
branch. Registration does not construct engines or register prompt/schema assets.
Private structured-LLM response schemas are deliberately minimal. They reject
invalid JSON structure, missing required fields, incompatible types, and
unknown fields, while preserving semantic candidates for deterministic
validation. Do not promote a private response envelope into a durable schema;
the contracts above define durable data.
A D&D producer that declares `single_response_v1` forwards any supplied
semantic correction to its structured completion and returns an owned copy of
that completion's exact validated raw response as its model candidate. It does
not serialize normalized artifacts to create that candidate, so deterministic
identity, evidence, warning, and durable-schema behavior remains separate from
the model transport material.
Each model producer receives the shared native engine, prepares fixed operation
inputs, and calls the common producer helper with initial request, interpretation,
correction builder, and supported fallback. Static prompt dependencies match its
request constants. The pipeline supplies complete candidate assessment; returning
from the helper does not trigger a duplicate validator pass.
Pure codecs, identities, reference resolvers, and deterministic transforms remain
separate from execution integration.
## Prompt Construction
D&D LLM-facing content lives beneath `assets/dnd/`. Each module contributes a
local `prompt.yaml` declaration and `instructions.md`; input-specific files
such as a catalog, registry, grounding projection, or candidate collection are
local only when that module needs them. New extractor content uses its feature
subtree, while families with both extraction and normalization content use their
`extract` and `normalize` subtrees. Shared visual-provenance fragments use
the `common-dnd-` prefix. Production lane code belongs with its D&D codec,
extractor, normalizer, and validator packages; registry projections and
identity helpers remain in their owning entity packages rather than in a
consumer lane.
Content lives beneath [assets/dnd](../../assets/dnd/), with ordinary native
declarations imported by [assets/notarius.yml](../../assets/notarius.yml).
The root assets package stays a content-only leaf. Declaration-relative content
paths and the collection schema context replace mounted filesystems/manifests.
Native declarations own output contracts and initial/correction pairs.
[Configuration](../config.md#prompt-output-contracts-and-schemas) owns public
schema-root/replacement behavior.
The owning module’s manifest is the source of truth for which local and shared
assets are selected, their mount paths, their message order, cache controls,
and the files included in its prompt fingerprint. Shared fragments belong to
the D&D shared implementation and are selected by name rather than copied into
module directories. The root `assets` package is a content-only boundary; its
physical ownership and rationale are defined by
[ADR-0011](../adr/0011-centralize-llm-assets.md).
Use the [spell declaration](../../assets/dnd/spells/prompts/prompt.yaml),
[scene declaration](../../assets/dnd/scenes/prompts/prompt.yaml), and
[item-normalization declaration](../../assets/dnd/item-registry/normalize/prompts/prompt.yaml)
as distinct examples. IDs in module constants/static dependencies select their
qualified native resources. Embedded profile content participates in the same
native load as operator resources, not registrar fallback logic.
Put each rule at its narrowest owner:
- universal behavior belongs in the shared system asset;
- D&D-family behavior belongs in a selected `common-dnd-` asset;
- rules for an input projection belong with that input asset;
- lane-specific policy belongs in the module’s `instructions.md`; and
- transport-envelope shape belongs in the private response schema.
- Universal behavior belongs in shared system content.
- D&D-family and input-specific rules belong in selected shared/input files.
- Enduring domain principles belong in the initial system context.
- The initial assignment and correction assignment belong in their own messages.
- Transport shape belongs in the private response schema, not repeated prose.
A rule is eligible for the system prompt only when every D&D LLM prompt needs
it regardless of lane, inputs, or response shape. Module instructions must not
repeat rules selected from shared assets or schemas. Reintroduce such repetition
only after observational evaluation with representative transcripts shows that
it improves results at the intended target models and cost; structural prompt
tests alone are not that evidence.
Initial/correction pairs share schema/profile defaults. Follow-ups supply new
guidance, not a fresh transcript/reference bundle or a manually replayed assistant.
Native coordination retains the growing exchange; structural repair is separate.
Private model schemas keep structure minimal and provider-compatible. Durable
artifact schemas remain codec-owned contracts. Preserve supported semantic
candidates for typed validation instead of silently transforming domain mistakes.
Every maintained D&D LLM prompt selects `dnd-extraction` as its default
profile. The D&D registrar registers the fallback, while an operator can
replace it with a complete profile of the same ID from the configured PromptKit
source. Deployment profile selection is documented in
[Configuration](../config.md#promptkit-profiles).
Shared content is selected by real relative paths rather than copied into modules.
Message ordering/cache hints remain meaningful prompt behavior; inspect the
owning declaration before changing them. Extraction generally separates reusable
campaign/chunk context from lane-specific projections. Scene planning uses the
full transcript; normalization uses fixed generic candidate/window presentation.
Do not force those different roles into a universal prefix or snapshot prose.
Native asset tests check preparation, input placement, paired contracts, and
meaningful cache controls without asserting a provider-quality result.
The D&D transcript assets have distinct consumers. Scene chunking consumes the
complete-session `common-dnd-transcript-full.md`, while extraction prompts
consume the current-chunk `common-dnd-transcript-chunk.md`. NPC, location, and
item normalization instead mount the generic semantic-reconciliation
candidate and transcript-window presentation assets. Player, party, glossary,
and compatible campaign references provide disambiguating context only when
declared by the active prompt; they never establish evidence. Reference
material is canonically ordered before rendering so equivalent inputs remain
stable.
## Representative Extraction And Correction
Extraction prompts render the common system and identity messages first, then
cached campaign references and the cached chunk transcript. Evidence policy and
any lane-specific registry, catalog, or grounding projection follow that
prefix. The final module instructions message is ephemeral. This keeps the
reusable extraction prefix identical while preserving the lane-specific suffix.
The [spell extractor](../../internal/modules/dnd/extract/spells/extractor.go)
uses [PrepareChunkExtraction](../../internal/modules/dnd/shared/extraction_inputs.go)
to validate source/chunk input, resolves catalog/NPC context once, and creates
native artifact inputs. Its interpreter canonicalizes the private response into
the existing durable value. The follow-up adds only aggregated guidance.
Catalog and source validators remain domain rules; accepted empty extraction
and a qualified empty fallback are different outcomes.
Scene chunking intentionally uses a different order: system, cached campaign
references, uncached module instructions, then the final ephemeral full
transcript. Entity normalization also has its own order: D&D system, mandatory
generic protocol, ephemeral domain semantic instructions, generic candidate
presentation, and final ephemeral generic transcript windows. These orders and
cache controls are prompt behavior; change them only through the owning
manifest and prompt declaration.
NPC, item, and location registry reconciliation translate shared proposal
safety categories into bounded prose that references only the response-local
duplicate-group ordinals and candidate handles. Item reconciliation appends its
typed rule that currency may be consolidated only with aliases of the same
denomination and never with non-currency items. The next normalize attempt
receives that prose with the exact defective proposal under the shared
replacement-request protocol. Structurally invalid output has no valid proposal
candidate and receives a fresh feedback-free attempt instead. If the stage
budget is exhausted, safe groups stay applied, unsafe groups stay separate, and
one fallback warning summarizes the final defect without raw model content.
Other extractors keep their own mapping/identity rules rather than consolidating
unlike response envelopes into a generic parser. Unknown/ambiguous contextual
selections produce actionable interpretation guidance without partial output or
guessed identity. Run-wide native selections reach producer, continuation, and
validator requests through the operation, without changing captured configuration.
## Evidence, Candidates, And Normalization
The current transcript is the only durable evidence source. Extractors assign
the current source identity and losslessly order any reversed range whose two
endpoints resolve in that source, using transcript position rather than numeric
unit-ID order. They then canonically order ranges and remove exact duplicates.
This routine canonicalization does not request a retry or emit a warning.
Unresolvable or wrong-source ranges remain unchanged for validators to reject.
Campaign context and generated artifacts may ground names or control routing,
but they never establish evidence for a D&D result.
The current transcript is the sole durable evidence source. Extractors attach
its source identity and canonicalize resolvable reversed endpoints by document
position, not numeric unit-ID order. They order/deduplicate references without
turning ordinary canonicalization into a warning or correction. Wrong-source
or unresolvable citations remain detectable, not silently repaired.
Campaign references and generated context can disambiguate or route work, never
supply new source evidence.
Default chains keep responsibilities separate: structural validators assess the
candidate, source-reference validators resolve cited ranges against the current
source and require extraction evidence to stay within the current chunk,
durable-schema validation checks an approved representation, and
relatedness validators report advisory evidence concerns. The configured order
is documented in
[Configuration](../config.md#production-validator-keys-and-default-chains).
Typed chains retain separate structural, source, identity/domain, durable-schema,
and advisory responsibilities; [Configuration](../config.md#production-validator-keys-and-default-chains)
owns their order and replacement rules. Extraction containment requires the
entire cited span inside the current chunk after ordinary reference validation.
Scene descriptions instead require the exact one-scene identity/range.
The optional `extract/dnd/scene-descriptions/combat_semantics` validator is the
D&D family's LLM-backed review of only combat versus non-combat classification.
It selects the shared combat-policy prompt fragment and asks the model to
classify the current chunk independently as `combat` or `non_combat` without
receiving the proposed scene kind. Deterministic code compares that
classification with the proposed kind and either approves it or produces the
appropriate correction guidance. This keeps every schema-valid classification
interpretable and avoids anchoring the reviewer on the producer's answer. It
does not assess titles, summaries, non-combat subtype, or scene boundaries;
deferred boundary-coherence review remains separate. It is opt-in;
[Configuration](../config.md) owns selection and retry/failure behavior.
Guidance describes all currently detectable model-controlled defects using
contextual names, response fields, and source ranges. It does not copy operator
paths, hashes, validator keys, reason codes, or durable IDs. Shared
[diagnostic helpers](../../internal/modules/dnd/shared/diagnostics/diagnostics.go)
support classified/bounded operator findings and separate model guidance.
Deterministic identity/order invariants do not imply that the model owns those
derived fields.
### Combat-semantics provider evaluation
Item-holder mistakes remain semantic rejections, not synthesized holders or
silent rewrites; guidance states the response's null/non-null relationship and
identifies records contextually. Enemy-event extraction rejects duplicate
engagement observations within one scene result; normalization intentionally
combines across scenes instead. Retain these differences when sharing helpers.
The human-reviewed corpus at
`internal/modules/dnd/validate/scenedescriptions/combat_semantics/testdata/evaluation_cases.json`
owns the proposed kind, expected combat classification, and reviewer rationale
for each synthetic case. Its package test validates the fixture contract only.
Provider evaluation remains an explicit maintainer operation and must not be
added to the default offline test suite.
Use the following protocol before proposing default-chain inclusion:
1. Record the Notarius commit, prompt and schema fingerprints, provider, model,
profile settings, reasoning effort, structural-repair setting, number of
repetitions, and evaluation date before collecting results. Do not revise
expected classifications merely to agree with provider output; a substantive
corpus correction requires independent human review.
2. Exercise the production validator construction and prompt assets from an
explicitly invoked, disposable evaluation driver or test in the validator
package. For each corpus case, construct transcript source units from the
listed IDs and text, assign matching per-unit source references, and use
`source.MaterializeChunkPlan` with one range spanning those units. Construct
exactly one scene whose ID and source range match that chunk and whose kind
is the case's `proposed_kind`; title and summary may use fixed placeholders
because the validator neither receives nor evaluates them. Invoke the typed
validator at extract stage through the production registry and scheduled LLM
client. Do not commit provider credentials, generated source material, or an
always-on live test.
3. Compare the model classification with `expected_classification`, then verify
that its deterministic comparison with `proposed_kind` yields the expected
approval or rejection direction.
Record an unexpected approval of an expected rejection as a false
acceptance, an unexpected rejection of an expected approval as a false
rejection, and any validator execution failure separately from semantic
accuracy. Retain per-case results so repeated trials and systematic failure
modes remain visible.
4. Evaluate producer correction separately with representative complete
scene-description runs configured as shown in
[Configuration](../config.md#production-validator-keys-and-default-chains).
For every initial semantic rejection, record whether the next producer
attempt returns the requested combat status and is approved. Do not count a
PromptKit structural repair as a producer-correction attempt.
5. Run the correction evaluation with debug capture enabled and without reused
extraction checkpoints. Record added validator and producer calls, elapsed
latency, and cumulative prompt, completion, cached, and total token usage
from the debug attempt records. Compare these values with an otherwise
identical run whose scene-description chain omits the semantic validator.
The default-chain review must consider classification error, false acceptance,
false rejection, execution failure, producer-correction success, added calls,
latency, and token use together. A structurally successful provider run alone
is not evidence that the validator should become a default.
Every producer-correctable D&D rejection describes all currently detectable
corrections in transcript-grounded domain terms, using contextual names,
model-owned artifact fields, and source segment ranges when useful. Validators
collect independent record defects in one pass so one retry does not merely
reveal the next issue. Shared D&D diagnostic helpers keep repeated rules and
record descriptions stable, de-duplicated, and bounded; each artifact family
continues to own the semantic rule and its prose.
Operator diagnostics and model guidance are separate products of the same
assessment. Operator messages may use typed paths, reason details, and opaque
application identities. Correction guidance must not copy those messages or
ask the model to reproduce durable entity IDs, hashes, validator module keys,
reason codes, or Go field paths. A registry-normalization rejection instead
speaks in terms of the duplicate-group proposal response the normalizer can
actually revise. Normalization-only deterministic invariants retain useful
operator detail but do not imply that a model controls derived ordering or
identity. Only bounded actionable semantic guidance is eligible for a
correction prompt.
Private LLM schemas use simple enums for closed categorical fields when the
provider-compatible shape can express the rule directly. Deterministic typed
validators retain the same checks as defense in depth and for non-LLM
producers. Private schemas keep every property required and avoid optional
properties, `uniqueItems`, and conditional cross-field logic.
Item-occurrence shape validation groups repeated holder mistakes by occurrence
kind and gives the producer the required JSON null/non-null relationship. It
identifies affected records by contextual item name and cited transcript range,
never by the deterministically attached durable item ID. Holder mistakes remain
semantic rejections rather than silent rewrites because changing a holder can
also change the meaning of the occurrence kind.
Enemy-event extraction additionally rejects a second `engaged` observation for
the same comparison identity within one scene-scoped result. Normalization may
combine results from distinct scenes, so it intentionally does not apply that
rule. Configuration owns the exact validator key and chain position.
Extraction source-reference validators share one full-span chunk-containment
policy. After ordinary reference validity succeeds, the policy resolves both
endpoints through document order and requires every source unit in the
inclusive range to be present in the current chunk. It does not assume numeric
unit-ID ordering, mutate input, or weaken wrong-source and unresolved-reference
validation. Scene descriptions remain separate because their validator owns an
exact one-scene range contract rather than general extraction containment.
Normalizers are deterministic for spells, combat turns, item occurrences, NPC
occurrences, scene descriptions, enemy events, and location occurrences. They
canonicalize display values and evidence, use source-document order for stable
output, and emit bounded normalization observations for changes or collapsed duplicates. NPC,
item, and location registry normalizers are intentional exceptions: each first
produces a deterministic candidate set, then may use a bounded structured-LLM
proposal to reconcile identity groups.
Deterministic normalizers canonicalize display/evidence and source ordering and
can emit cleanup observations. They run directly without synthetic requests.
The three registry normalizers retain their intentional model-assisted exception.
## Semantic Registry Reconciliation
The three registry normalizers instantiate the domain-neutral
`internal/framework/semanticreconcile` engine with default bounds. Each
eligible candidate receives a contiguous, one-based `candidate_number` for that
request, and candidate material declares the exact inclusive range. The model
sees that handle, the candidate label and source-free evidence ranges, plus
bounded transcript windows; it returns only duplicate
groups of supplied handles and one supplied canonical handle per group. It
never returns names, evidence, durable IDs, or replacement records. Identical
labels and evidence remain independently selectable because their handles are
distinct. Transcript unit `id` values and evidence `start_unit_id` and
`end_unit_id` values are source positions in a separate namespace and are
never valid candidate numbers.
[NPC](../../internal/modules/dnd/normalize/npcregistry/normalizer.go),
[item](../../internal/modules/dnd/normalize/itemregistry/normalizer.go), and
[location](../../internal/modules/dnd/normalize/locationregistry/normalizer.go)
normalization use ordinary functions from
[semanticreconcile](../../internal/framework/semanticreconcile/preparation.go),
not a separate reconciliation engine/service.
The generic core owns the mandatory handle protocol, candidate and transcript
presentation, the private response schema, source-reference validation,
candidate and combined-material limits, structured completion, proposal
assessment, stable group ordering, and typed plan-application mechanics. The
D&D prompt contributes its system message and registry-specific semantic
instructions. The generic registrar registers the shared prompt and schema;
the D&D registrar registers each consuming prompt and the fallback profile.
The operation retains the incoming merged artifact separately, preprocesses
fixed originals once, and calls `Prepare` once. Preparation filters unusable
candidate evidence, assigns contiguous one-based request-local handles, declares
their inclusive range, and builds bounded transcript windows/material.
Candidate handles are not transcript unit IDs or durable identity. Identical
labels/evidence remain separately selectable.
Fewer than two eligible candidates skips the LLM without a semantic warning.
An exceeded bound also skips the call and preserves the deterministic
preprocessed registry, adding the registry's bounded fallback warning. Invalid
structured output or discarded proposal groups use the normalizer's existing
retry contract; retry exhaustion preserves the safe deterministic or
partially applied result and emits its bounded fallback warning. Provider,
transport, cancellation, and context-material failures remain execution
errors.
The native model proposes only duplicate groups and a supplied canonical handle.
[Proposal assessment](../../internal/framework/semanticreconcile/proposal.go)
rejects unsafe/unknown/overlapping selections; typed
[application](../../internal/framework/semanticreconcile/application.go) uses
family policies on the original records. Each response is a complete replacement
proposal, applied afresh before pipeline assessment, never a union of prior plans.
Correction uses the same handle mapping/windows and adds domain guidance only.
Application remains typed and registry-owned. All three policies select the
canonical member's normalized display name, union member evidence in source
order, preserve ungrouped records, and derive durable identity only after
consolidation. NPC IDs derive from the final name. Item IDs also derive from
the final name, and a typed guard prevents currency aliases from crossing
denominations or mixing currency with non-currency records. Location IDs
derive from the final name and final evidence, preserving same-name,
parent/child, and distinct physical-place identities. Registry warning scopes,
reason codes, and postconditions remain outside the generic core.
Domain application chooses canonical display, unions evidence in source order,
preserves ungrouped originals, and derives durable identity after consolidation.
NPC/item identity follows the final name; locations also use final evidence to
preserve same-name distinct places. Item guards prevent currency denominations
from crossing or merging with non-currency records. Diagnostics and postconditions
remain registry-owned; model output supplies no replacement names/evidence/IDs.
Insufficient candidates use direct assessment without native execution.
Preparation limits use resolved strict/permissive terminal handling, not implicit
semantic success. For supported permissive output, only compatible safe groups
from the final usable proposal can advance; otherwise the retained merged input
is checked as fallback. A result-less/structurally failed continuation cannot
recover an earlier proposal. Source/codec/identity construction checks still
apply without ordinary semantic revalidation. Strict mode and cancellation do
not silently preserve a result as accepted work.
## Planning, Scene Validation, And Fallback Limits
[Scene planning](../../internal/modules/dnd/chunk/scenes/chunker.go) prepares the
full input once and interprets complete ordered boundaries. The pipeline
materializes/assesses plans before lane work. Supported permissive planning can
construct one unannotated whole-source plan through normal source-addressing;
it does not invent classifications, prose, or bounded request sizes.
[Scene descriptions](../../internal/modules/dnd/extract/scenedescriptions/extractor.go)
have a stricter intrinsic requirement: one usable current-scene artifact.
Permissive construction can use only a final usable candidate satisfying shape,
source identity/range, and downstream invariants. It cannot fabricate a
kind/title/summary, emit an invalid empty list, or retrieve an earlier candidate.
Codec-valid empty collections are supported for the list extraction families,
but do not generalize to every producer.
[Combat semantics](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/validator.go)
is an opt-in independent combat/noncombat review of scene-local transcript input,
without the proposed kind. Deterministic interpretation compares classification
to the candidate. It does not evaluate title, summary, noncombat subtype, or
boundary coherence. One direct native execution returns a judgment or unavailable
assessment with causes; it has no producer continuation loop.
[Configuration](../config.md#production-validator-keys-and-default-chains) owns selection.
### Combat-semantics provider evaluation
The [human-reviewed synthetic corpus](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/testdata/evaluation_cases.json)
records proposed kind, expected classification, and rationale. Offline fixture/
fake-provider tests verify contracts, not production classification quality.
Live evaluation remains explicitly invoked maintainer work, not a default test.
Before proposing default-chain inclusion:
1. Record commit/content revisions, provider/model/profile/execution settings,
actual native repair selection, repetitions, and date. Do not change expected
judgments just to agree with provider output; corpus corrections need independent review.
2. Use a disposable explicit driver with the production typed validator and shared
native engine. Materialize corpus units into one chunk and construct the
matching scene identity/range/proposed kind. Title/summary can be placeholders:
they are not reviewer inputs. Commit no credentials or always-on live test.
3. Compare classification and deterministic approval/rejection separately. Retain
false acceptance, false rejection, and unavailable/execution-failure cases.
4. Evaluate producer correction separately through the configured full chain,
including the final permitted response. Native structural repair is not an
application semantic turn.
5. Use requested capture and explicit bypass/refresh rather than cached acceptance.
Compare added executions, latency, and native usage/terminal coverage with and
without the validator; preserve unknown usage instead of inventing totals.
Default-chain review must weigh quality, correction success, availability, calls,
latency, and cost together. Structural success alone does not justify inclusion.
## Generated References And Grounding
Normalized D&D artifacts can be handed to a later step through a generated
reference binding. The framework verifies artifact compatibility and retains
producer provenance; consumers resolve the handed-off artifact into an
immutable, validated projection for each operation. External files are checked
during preparation, while generated artifacts are resolved at the handoff.
Normalized artifacts reach later steps through typed compatibility-checked
handoffs. Consumers resolve supplied bytes into immutable contextual projections.
Valid fallback context remains usable in the current run but disables reuse for
actual consumers and their dependents; unrelated work is unaffected.
NPC and item registry consumers receive names-only grounding. Location
consumers receive a contextual selector containing the canonical name and the
registry references needed to distinguish same-name places. The calling module
resolves those supplied selections locally and maps them into the unchanged
durable ID/name pair; an unknown or ambiguous selection rejects the complete
occurrence result rather than accepting a partial mapping. The NPC registry
additionally supplies names-only actor grounding to spells, combat turns, and
enemy events.
NPC/item selectors are names-only; location selectors include the name and
ordered registry references needed to distinguish same-name places. Consumers
resolve selections locally to the unchanged durable ID/name pair. Unknown or
ambiguous selections do not yield guessed IDs or partial occurrence results.
Registry evidence disambiguates identity but never replaces each occurrence's
own current-transcript citations.
Registry references establish a registry identity and may disambiguate a
selection, but never become occurrence evidence. Each occurrence keeps its own
current-transcript source references, even when it was grounded through the
same registry record.
Scene descriptions are eligibility-only projections: they retain current-chunk
classification data, not scene prose or evidence, and exist to route combat
extraction. Enemy-event extraction also projects combat turns to `actor` and
`turn_kind` and filters NPC occurrences to `combat_opponent` names and kinds.
These projections are guidance only and never event evidence.
Scene projections route combat without conveying scene prose as evidence.
Combat-turn projections retain actor/turn kind; NPC-occurrence projections select
combat-opponent names/kinds for enemy grounding. These remain guidance, not
event evidence.
## Lane-Specific Rules
@@ -344,14 +250,14 @@ shared helper changes.
Shared D&D text comparison is identified by `dnd.text_comparison.v1`. Any
semantic change requires an explicit policy-version review for every affected
identity, mapping, normalization, and validator policy; helper source is not a
checkpoint fingerprint.
identity, mapping, normalization, and validator policy. This is domain policy,
not accepted-result cache identity.
| Lane | Intentional behavior |
| --- | --- |
| Spells | May use a spell-catalog overlay and optional NPC grounding; the catalog validator supplies domain-specific semantic checks. |
| NPC registry | Establishes transcript-grounded NPC identities, including factual third-party mentions, without assigning occurrence categories. It does not consume an NPC registry, and its normalizer is the LLM-assisted reconciliation exception described above. |
| Combat turns | Requires a scene-description artifact. It calls the LLM only for an exact `combat` classification; exact non-combat classifications return an accepted empty result, while missing or mismatched classifications return an empty result with a bounded warning. Optional NPC grounding never becomes evidence. |
| Combat turns | Requires a scene-description artifact. It calls the LLM only for an exact `combat` classification; non-combat paths directly assess an empty result, while missing or mismatched classifications also retain a bounded warning. Optional NPC grounding never becomes evidence. |
| Item occurrences | Requires the normalized item registry for exact deterministic grounding at extraction and normalization. Campaign context may disambiguate, but the registry never becomes occurrence evidence. |
| Item registry | Produces source-grounded item types and unique designations. Its LLM-assisted reconciliation is proposal-only, preserves distinct currency denominations and item types, and does not create per-instance identities. |
| NPC occurrences | Requires the normalized NPC registry at extraction and normalization, using it for canonical actor grounding only. It separately emits cited current-transcript occurrence facts, including `mentioned`, rather than deriving them from registry provenance. |
@@ -370,11 +276,14 @@ selectable bindings and validation chains.
## Focused Verification
When changing D&D behavior, test the affected codec, extractor, normalizer,
validator, prompt-asset manifest, and registry projection. Also test generated
handoffs at the integration boundary and run the full D&D module suite:
~~~sh
go test ./internal/modules/dnd/...
go test ./internal/modules/integration/...
~~~
Walk extensions through real [spell extraction](../../internal/modules/dnd/extract/spells/extractor_test.go),
[item reconciliation](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
[scene planning](../../internal/modules/dnd/chunk/scenes/chunker_test.go), and
[native semantic validation](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/native_execution_test.go).
Retain family codec/identity/source/holder/eligibility regressions, contextual
registry projection tests, and [assembled handoffs](../../internal/modules/integration/).
[Dependency registration](../../internal/modules/dnd/register/dependencies_test.go)
and [native asset tests](../../assets/) verify static resources and preparation
without behavioral asset registration. Use real kits with native provider fakes;
no ordinary test needs credentials, paid inference, or a private completion API.
[Development](../development.md#validation) owns repository-wide validation.

View File

@@ -1,345 +1,186 @@
# LLM Runtime Internals
# Native LLM Integration Internals
`internal/framework/llm` is Notarius’s provider-independent structured
completion boundary. It adapts framework requests to PromptKit, bounds
provider calls, assembles registered prompt and schema assets, records selected
profiles, and redacts provider errors. The architectural boundary is defined in
[Architecture](../policy/architecture.md#llm-boundary); profile sources,
credentials, and concurrency settings belong in
[Configuration](../config.md#promptkit-profiles) and
[Configuration](../config.md#concurrency-output-cache-and-debug).
Model-executing code uses native PromptKit types directly. This guide explains
Notarius's integration points, not a private completion service or a copied
library manual. [Architecture](../policy/architecture.md#native-execution-boundary)
defines the boundary; [Configuration](../config.md#promptkit-profiles) owns
resources/settings; [CLI Reference](../cli.md#run-wide-llm-overrides) owns request
controls; [Operations](../operations.md) owns state and handling.
## Structured Completion Boundary
## Construction And Ownership
Modules and LLM-backed validators depend only on
`contracts.StructuredLLMClient`. A completion request supplies a prompt ID and
version, optional profile and session IDs, named input material, variables, and
a caller-owned decode target. The successful response returns the validated raw
structured bytes together with non-secret provider, model, profile, and token
metadata.
The [CLI loader](../../internal/cli/configkit_load.go) hands the original completed
ConfigKit application result to `promptkit.NewFromConfig`. One invocation shares
the resulting engine across initial producers, corrections, normalization, and
LLM validators. Runtime-only HTTP/client settings and an injected native
`promptkit.LLMClient` remain construction options, not application YAML.
There is no provider-neutral completion conversion or second engine per role.
The caller owns the domain behavior: it chooses the prompt, prepares inputs,
selects the private response schema, and interprets the decoded result. The
adapter does not own source evidence, artifact conversion, normalization, or
durable schemas. Those responsibilities remain with the module and its
[integration contract](../integrations/).
[Configuration Internals](configuration.md) owns native definition/source assembly
and invocation selection reuse. PromptKit owns captured resources, request
preparation, native validation/repair, provider transport, conversation state,
and backend admission. See the [upstream Go consumer contract][consumer] for those
APIs rather than reproducing their mechanics here.
The calling module also resolves contextual entity selections and attaches any
application identity; PromptKit and this adapter do not own entity identity.
Application contracts remain typed production, candidate assessment, supported
fallback, and artifact encoding. Pure domain models, codecs, source resolution,
and deterministic transforms do not need PromptKit merely because a surrounding
operation invokes a model.
`PromptKitClient` validates the request target and prompt identity, maps each
named material to a PromptKit inline artifact while preserving its origin URI,
passes the supplied request session through to PromptKit's direct per-run
session field, retains the same value as the `session_id` prompt variable for
maintained prompt compatibility, and forwards profile selection. It does not
derive or replace session values; the CLI owns that policy. It then creates one
frozen prepared execution, captures its caller-owned credential-redacted
details for debug material, and executes that exact snapshot through
PromptKit's prepared-execution boundary. The direct field
is authoritative for provider session behavior. A session ID is a stable,
non-secret correlation identifier and may be exposed to providers and provider
observability. The adapter returns PromptKit’s validated raw bytes rather than
re-encoding the decoded target. An empty optional material is represented as
one space so its named input is retained by PromptKit.
## Requests And Fixed Operation Inputs
When a request includes semantic correction material, the adapter validates and
defensively copies it before preparation, then appends exactly two messages
after the ordinarily rendered prompt: the prior response as an assistant
message and the correction guidance as a user message. Requests without a
correction do not add messages or introduce caller roles. Ordinary request
summaries record correction byte counts and digests only; complete messages are
available solely in an explicitly requested debug trace.
Model modules receive the shared engine during typed preparation. A module
prepares transcript, references, contextual identity projections, and any
normalization candidate mapping once. It constructs a `promptkit.RunRequest`
with its selected prompt, profile/session, native artifact inputs, and variables.
Response interpretation consumes `*promptkit.RunResult` and produces the
application's typed candidate.
The adapter leaves the ordinary rendered message prefix, named inputs,
variables, session, profile, execution overrides, prepared-execution path, and
PromptKit repair policy unchanged for a corrected request. It never imports a
PromptKit message type into a module or pipeline contract. PromptKit reports
actual structural repair count and cumulative token usage per completion; the
pipeline's safe terminal debug record projects those values without copying
message content.
[Spell extraction](../../internal/modules/dnd/extract/spells/extractor.go) is a
representative path: fixed transcript/catalog/NPC projections feed an initial
request; native output is decoded and canonically mapped into its durable type.
The correction builder selects a paired prompt and supplies current guidance,
not another copy of original source/reference material.
Client construction may also receive a run-wide reasoning-effort override from
the CLI factory boundary. The adapter copies the caller-owned pointer and
creates a fresh PromptKit execution override for each request: a nil pointer
inherits the selected profile, a non-empty value replaces it, and an empty
value clears inherited reasoning. The CLI's mutually exclusive
`--reasoning-effort` and `--clear-reasoning-effort` controls select those
states. With neither flag, profile behavior remains unchanged. Because
production constructs one shared client, the selected state applies uniformly
to module calls, retries, and LLM-backed validators for the whole run.
Domain identity stays deterministic. Contextual selectors and request-local
normalization handles resolve against fixed supplied records; models do not
acquire authority over durable IDs, citation meaning, or typed artifact shape.
[Module Internals](modules.md) and [D&D Internals](dnd.md) own extension/domain
recipes.
An empty request profile lets the prompt select its configured default. Before a
run begins, the CLI asks the adapter to inspect every explicit profile on the
resolved selected LLM-backed bindings and validators, including inherited
pipeline profiles. Inspection resolves the profile and its selected backend and
target without loading a prompt, reading credentials, admitting capacity, or
contacting a provider, so a missing or invalid explicit profile fails before
stage execution while a valid `api_key_env` may remain unset. Calls record the
profile actually selected by PromptKit. The recorder trims and deduplicates
non-secret profile identity, provider, model, selected backend ID, and
effective reasoning values for manifest use. Entries that differ in backend or
reasoning remain distinct and deterministically ordered. Endpoint-only profiles
retain an empty backend ID, which the published JSON omits. Successful
completion responses and recorded profile manifests identify the adapter
provider as `promptkit`.
Native request overrides preserve supplied values without rewriting configured
profiles. The producer helper's request composition preserves operation-owned
prompt/input/capture fields and existing callbacks; validators pass native
execution options explicitly on their own requests.
The CLI's profile-inspection engine and the production adapter use the same
profile-source construction to apply the configured profile directory or file,
the optional registered fallback profile assets, and the optional conventional
`local` backend. Preflight therefore resolves the same profile sources and
backend membership as runtime without performing generation. Fallback assets
are mounted only when at least one source is registered. The production D&D
registrar contributes its `dnd-extraction` fallback, and the maintained D&D
prompts select that logical ID by default. PromptKit owns source precedence and
profile parsing and inheritance: an operator-provided matching profile takes precedence over a
fallback profile without Notarius merging either document.
When the registration is absent, a profile selecting `backend: local` fails
inspection instead of falling back to a built-in or endpoint-only target.
## Native Production And Application Assessment
Before execution, the adapter also contributes a non-secret checkpoint
fingerprint for the effective PromptKit profile source. It combines the
identity of PromptKit's compiled-in profile catalog with a deterministic digest
of every YAML profile in the configured profile directory, or of the configured
profile file, and a deterministic digest of the flattened fallback profile
assets. The fingerprint contains neither profile content nor source paths. It
covers inherited pipeline profiles, explicit binding profiles, and
prompt-selected defaults, so changing a model or other profile setting cannot
reuse checkpoints created under the
prior profile source. This cache identity is independent of durable
profile provenance: run manifests continue to list only profiles actually
observed during LLM calls. When the local backend is registered, a second
fingerprint hashes its trimmed endpoint behind a stable marker. Changing that
semantic execution target invalidates checkpoint reuse. The raw endpoint is not
stored in checkpoint identity, and the local concurrency limit is excluded
because it changes scheduling rather than execution semantics.
[RunProducer](../../internal/framework/pipeline/producer.go) connects ordinary
module interpretation/correction/fallback functions to the pipeline assessor.
It uses native `Run`, or retained prepared execution on the cache path, then
checks errors and public validation status before interpretation. Failed native
validation can accompany nil Go error and is not a usable semantic candidate.
## Shared Provider-Call Limit
Every usable initial/revised candidate receives the full applicable configured
assessment chain once, including unchanged candidates and the final permitted
response. Native coordination owns history and additional-turn iteration.
Its initial callback uses already collected findings instead of reassessing the
initial result. Module templates own correction assignments; detecting modules/
validators own actionable guidance, separately from diagnostics.
Production construction creates one PromptKit client and wraps it in one
scheduled client. The scheduler has a fixed, positive permit limit, serves
queued calls in FIFO order, and removes a queued call when its context is
cancelled. It rechecks the caller context after admission and before dispatch.
A granted permit is released exactly once on every completion path.
Native execution success is not domain acceptance. Stopped/exhausted outcomes
are control facts. Result-less failed continuation does not recover an earlier
candidate, and an undelivered response is not assessed or accepted. Caller
cancellation stops without fallback. Native timeout/provider/capacity failures
remain distinguishable through context state and typed causes.
The scheduled wrapper surrounds every `CompleteStructured` call, so concurrent
lanes, pipeline retries, and LLM-backed validators share the same provider-call
ceiling. This ceiling is independent of pipeline worker concurrency; changing
worker counts cannot exceed the configured LLM limit. The configuration field
and its effective default are owned by
[Configuration](../config.md#concurrency-output-cache-and-debug).
Resolved producer mode chooses terminal handling. A supported permissive fallback
must preserve intrinsic/source/downstream invariants without repeating ordinary
assessment or claiming semantic approval. Preparation/capture/encoding failures
are not reasons to extend model budgets. Detailed assessment/disposition and
handoff eligibility belong in [Pipeline Internals](pipeline.md).
PromptKit applies a second, independent admission limit when the selected
profile names a limited backend. It sits beneath the Notarius scheduled client,
so it may narrow but cannot expand the application-wide limit. Built-in
OpenRouter profiles select PromptKit's reserved backend and its upstream
capacity policy. A positive configured local-backend limit bounds active local
generations inside PromptKit; zero leaves that backend unlimited there.
Endpoint-only profiles do not select a PromptKit backend and remain limited
only by the Notarius scheduler.
## LLM Validators
The [combat-semantics validator](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/validator.go)
builds one native request with its own profile and scene-local input. It uses
the same engine and run-wide native execution/session selections, then checks
the native error/status before decoding.
Successful interpretation returns a domain judgment and actionable rejection
guidance where appropriate. Execution or interpretation failure is unavailable
assessment with retained causes, not a semantic defect or invented instructions.
Cancellation delivers no judgment. Validators do not coordinate another semantic
conversation or rerun themselves to extend structural repair.
A completed producer/continuation releases native admission before assessment,
so a nested validator can use that same limited backend. Application workers
and native admission remain independent; there is no second scheduler or queue.
Capacity handling follows producer mode, not an additional application retry.
## Prompt And Schema Assets
An `AssetRegistry` collects prompt, schema, and optional fallback-profile
filesystems from production module families. It flattens registered roots into
the corresponding PromptKit filesystems and rejects invalid roots, unreadable
assets, duplicate paths, and missing prompt or schema files during preparation.
Fallback assets receive a safe content digest for checkpoint identity; raw
paths and bytes are never included. The framework’s `promptfs` helper combines
module-selected prompt files with reusable domain fragments without making the
framework depend on D&D content.
[assets/notarius.yml](../../assets/notarius.yml) imports ordinary embedded
initial/correction/validator resources with retained filesystem contexts.
The assets package remains a content-only leaf. Prompt declarations own default
output format, validation, and schema selections; modules own prompt meaning
and small static resource-ID dependencies, not behavioral asset registration.
LLM-facing content is embedded once by the root `assets` package. Each consumer
uses only its scoped subtree, while the module retains ownership of its prompt
declaration, ordered manifest, private response-schema identity, and
registration. Shared D&D fragments are selected by D&D's shared implementation;
the detailed convention is in [D&D Module Internals](dnd.md). This physical
arrangement and its data-only boundary are defined by
[Architecture](../policy/architecture.md) and
[ADR-0011](../adr/0011-centralize-llm-assets.md), rather than by this runtime
guide.
Each producer pair requests a complete replacement response using its shared
schema. Enduring principles live in initial system context; the follow-up
supplies current findings and its domain assignment. Normalization applies
each complete proposal afresh to fixed originals, not a union of prior groups.
The generic registrar is the sole production registration owner for the
semantic-reconciliation default prompt and private response schema. The
domain-neutral reconciliation package also exposes only its mandatory protocol
and candidate/transcript presentation files for domain prompt manifests. D&D
registry normalizers mount those files while retaining ownership and hashing
of their D&D system message, semantic instructions, and complete prompt
declaration. The response schema is therefore registered once even though
several typed normalizers select it.
Native preparation loads selected inline/file/root schemas. Intrinsic durable
artifact schemas remain application-owned codec contracts and are not removed
with duplicate model-response schema machinery. Full source/root/presence rules
belong in [Configuration](../config.md#prompt-output-contracts-and-schemas) and
[PromptKit formats][formats].
Mounted prompt assets determine a module's fingerprint. The fingerprint hashes
only the module and shared files explicitly selected by its manifest, so an
unrelated asset does not invalidate a checkpoint. Schema loaders validate JSON,
attach identity and digest metadata, make defensive copies, and expose
diagnostics without raw schema bytes.
Native structural repair and transient retries remain upstream-owned. Notarius
does not pin omitted counts or wrap them in blanket producer/validator retries.
Application semantic allowance is a separate resolved control, not another
counter around native coordination.
Semantic-reconciliation normalizers extend this identity with the shared
response-schema digest, framework policy version, and complete limit-policy
digest. Their manifest metadata records the same content-free prompt, schema,
policy, and limit identities together with domain identity and normalization
policies. Request-local handles, source material, proposal content, and raw
asset bytes are not checkpoint metadata.
## Prepared Execution And Reuse
Private response schemas validate a model transport envelope. They are not the
durable artifact schema and should not be documented as an external wire
contract. Durable formats and compatibility rules remain in the
[integration contracts](../integrations/).
For eligible cacheable producers, the helper prepares the initial request once,
retains its details and opaque message-content hash, and either discards the
handle on a usable hit or executes that same handle with `RunPrepared`.
Unused handles are discarded on exits. Continuation retains the initial key.
## Prompt Maintenance And Backend Caching
Hits decode the accepted application artifact/plan without semantic reassessment,
exchange restoration, native execution, or historical usage. Normalizers cache
applied artifacts, not proposals. Provider-side prompt-cache hints remain native
request metadata, distinct from accepted-result identity. State layout and
eligibility mechanics belong in [Run State Internals](state.md), not another
LLM cache abstraction. The [prepared execution contract][prepared] owns native
handle lifetime and admission behavior.
Prompt message order and shared asset bytes are runtime behavior. Backend cache
reuse depends on identical preceding roles, rendered bytes, and cache-control
metadata—not merely equivalent meaning. Keep reusable shared assets
byte-identical and preserve each prompt’s declared ordering and cache controls
when editing it.
## Native Evidence And Sensitive Data
For sibling prompts that can reuse the same source material, order universal
shared context first, request source material next, and module-specific
suffixes last. Put a cache boundary at a reusable prefix that is useful to the
backend. Redundant intermediate cache boundaries do not extend that reusable
prefix and add no value.
The runner supplies one invocation execution group. Actual initial, continuation,
and nested validator executions enroll once; group observations preserve native
identity, terminal coverage, and unknown usage without copied totals or a
durable profile inventory.
Prompt-family owners may choose a different sequence when their inputs and
reuse pattern differ. The D&D family’s extraction, scene-chunking, and NPC
normalization policies are maintained in [D&D Module Internals](dnd.md#prompt-construction).
Do not add tests that enforce prompt prose; prompt tests should verify the
meaningful input placement and cache controls of the prompt being changed.
[Native capture](../../internal/framework/pipeline/native_capture.go) composes
observers/preparation callbacks rather than replacing them. Retain prepared
details cheaply during callbacks, then write at normal boundaries. Cache paths
reuse existing details; debug never triggers a second preparation or model call.
Shared callback state is synchronized. Available result-less failure facts and
unassessed undelivered responses remain distinguishable.
## Validation, Repair, And Retries
PromptKit performs prompt rendering, provider execution, and the prompt’s
structured-output validation. The adapter reports an empty result, validation
failure, empty structured body, or decode failure as
`ErrInvalidStructuredOutput`, while retaining the returned raw bytes and debug
material when they exist. Provider failures remain operational errors rather
than output-validation failures. Apart from documented context, capacity, and
invalid-output categories, provider error values and types do not cross the
adapter error chain; callers receive only a credential-redacted diagnostic.
`LLMGenerationError` preserves the provider-neutral failure kind (`transport`,
`provider_status`, `malformed_response`, or generic `generation`) and any HTTP
status. When PromptKit exhausts an eligible transient-status retry budget, it
also records that exhaustion and the attempts in that generation. Those fields
do not include repair generations, and zero attempts means unavailable rather
than proof that no request was sent.
Every execution that reaches PromptKit returns an optional request-local
`execution` summary. It contains only terminal aggregate attempts, retry and
repair counts, durations, outcome and failure classification, status, and
presence-aware token usage. Preparation failures have no summary; later local
decode failures retain the upstream terminal summary without changing it.
When PromptKit rejects backend admission before generation, the adapter maps
`promptkit.ErrCapacityExceeded` to
`contracts.ErrLLMCapacityExceeded`, retaining prompt context and a redacted
upstream diagnostic without exposing the PromptKit sentinel or capacity-error
type as a framework contract. When supplied, the normalized selected backend
ID appears only in that safe application-owned diagnostic context. A canceled
caller context takes precedence. The adapter does not retry capacity failures;
the pipeline's existing binding attempt policy sees the operational error and
decides whether to rerun the complete operation.
PromptKit executes structural repair within its structured-output flow. The
maintained production prompt manifests declare one additional repair attempt.
When a resolved binding supplies a repair value, the adapter inspects the
prompt, copies its complete output contract, changes only the repair limit, and
passes that complete replacement contract to PromptKit. This preserves the
prompt's output format, validation mode, schema, and provider structured-output
settings.
A successful repair is an ordinary successful completion, not a warning. The
adapter reports PromptKit's actual repair count and its cumulative usage
directly, without adding the initial and corrective counts again. Debug prompt
material records the configured complete contract; debug response material
records the repaired response and actual validation result. If the repair
budget is exhausted, the adapter retains the final raw bytes and debug material
and reports `ErrInvalidStructuredOutput`. Generation failures during an initial
or corrective call remain provider-neutral operational errors with the same
redaction boundary.
Structural repair does not replace pipeline retry behavior: a binding's
configured retry count reruns its complete stage attempt after an operational
or structural error, module-requested retry, or actionable semantic rejection.
An actionable module-requested retry and a validator rejection both use the
same correction payload when the producer exposes an exact latest response;
feedback-free module retries reconstruct the ordinary request without appended
messages. The pipeline owns attempt lifecycle, validation chains, and retry
diagnostics; see
[Pipeline Internals](pipeline.md#validation-retries-and-output) and the
[binding reference](../config.md#module-bindings-and-validators).
## Timeout Ownership
The caller context remains the outer cancellation authority. PromptKit applies
a positive effective generation timeout as an inner request deadline for each
built-in generation attempt; an explicit zero disables only that generation
deadline. The HTTP client timeout is a separate transport-wide cap. Notarius
forwards the caller context and does not install another timeout wrapper around
PromptKit.
The selected PromptKit profile owns generation settings. The resolved global
`promptkit.transient_retries` configuration is passed to the shared PromptKit
engine and controls additional built-in attempts for eligible transient HTTP
failures in one generation. It defaults to two; explicit zero disables those
attempts. Notarius binding retries remain outside the adapter and repeat the
complete module operation and validation chain.
Operator-facing behavior is summarized in
[Operations](../operations.md#operational-limits), and the pinned upstream
contract is identified in
[PromptKit Integration](../integrations/pkg-promptkit.md).
## Observability And Redaction
When debug recording is enabled, the pipeline decorates the shared client. The
wrapper records prepared prompt and response material, timing, selected profile
and backend, effective model parameters, and call identifiers in the run’s
debug bundle, including material available from a failed structured completion.
Effective parameters use PromptKit's stable lower-case JSON field names and may
include `backend_id`. For a successful completion, a debug-write failure is
surfaced; when the completion already failed, its call error remains the
result. Debug-bundle location, retention, and handling are operational concerns
documented in [Operations](../operations.md#debug-bundles).
The attempt-terminal summary is a separate safe trace record: it contains
attempt kinds, validator outcome counts and reason codes, effective policy,
terminal action, and repair/usage references. It excludes raw assistant
responses and correction text. Those values can appear only in the explicitly
requested detailed prompt and response artifacts, which require sensitive-data
handling.
Run manifests receive selected profile summaries, including optional effective
backend and reasoning provenance, and component identities—not prompt, schema,
source, reference, or response content. The published field semantics belong
to the [JSON output contract](../integrations/json-output.md#manifestjson).
Provider error text is wrapped with prompt context and bearer credentials are
redacted before it crosses the runtime boundary. Known-secret redaction is
available to other runtime collaborators; it does not make prompt or response
contents safe for general logging.
Generation failures expose an application-owned category and optional HTTP
status. Provider code, type, and message remain debug-only, after redaction.
## Failure Boundaries
- Construction fails for missing asset registries, mutually exclusive profile
sources, invalid asset registration, or a non-positive scheduler limit.
- Preparation failures, unavailable explicit profiles, provider failures, and
context cancellation propagate to the calling stage with context.
- Backend admission exhaustion is a provider-neutral operational error and is
not classified as invalid structured output or validator rejection.
- Malformed or schema-invalid provider output is classified separately as
invalid structured output so the module or pipeline can apply its own retry
and rejection policy.
- Domain semantic checks, evidence decisions, and deterministic normalization
run outside the provider adapter.
[Run capture](../../internal/cli/run_capture.go) uses secret-aware configuration
views and exact marked-secret omissions, while native snapshots preserve credential
omissions. Do not heuristically scrub arbitrary source/prompt/response strings.
Selected full evidence can be sensitive; private debug representations are not
a consumer serialization contract. Recording failures reach application boundaries
without retrying model work. [Operations](../operations.md#debug-bundles) owns
handling and [State Internals](state.md) owns recorder lifecycle.
## Focused Verification
Read the LLM adapter, scheduler, asset registry, schema loader, and redaction
tests when changing this boundary. Prompt changes also require the owning
module’s asset tests, and retry or debug changes require focused pipeline or
CLI coverage. The focused runtime and D&D checks are:
Use real kits with a fake native provider or local fake HTTP server, not a
replacement completion interface. Relevant owners include:
~~~sh
go test ./internal/framework/llm/... ./internal/modules/dnd/...
~~~
- [Native loading](../../internal/cli/native_load_test.go) and
[schema overrides](../../internal/cli/native_schema_load_test.go).
- [Producer/continuation tests](../../internal/framework/pipeline/producer_test.go),
[ordered assessment](../../internal/framework/pipeline/candidate_assessment_test.go),
and [nested native validation](../../internal/framework/pipeline/native_assessment_test.go).
- [Accepted-result reuse](../../internal/framework/pipeline/producer_cache_test.go)
and [native capture](../../internal/framework/pipeline/native_capture_test.go).
- [Representative extraction](../../internal/modules/dnd/extract/spells/extractor_test.go)
and [validator execution](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/native_execution_test.go).
- [Assembled recovery](../../internal/cli/recovery_contract_test.go) and
[real executable checks](../../internal/cli/native_process_test.go).
These verify native status/causes, complete assessment, fixed inputs/history,
override propagation, cancellation/admission, reuse, and evidence. They do not
claim production model quality. Wider checks belong in
[Development](../development.md#validation).
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[prepared]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later

View File

@@ -1,195 +1,165 @@
# Module Internals
This guide owns the mechanics for implementing and registering production
modules. [Configuration](../config.md) owns selectable keys, binding syntax,
reference configuration, and default validator chains. Durable input and output
shapes belong in [integration contracts](../integrations/).
This guide owns typed module construction, registration, and extension recipes.
[Configuration](../config.md#production-module-keys) owns selectable keys,
binding syntax, references, and default chains.
[Integration contracts](../integrations/json-output.md) own durable shapes;
[D&D Module Internals](dnd.md) owns that family's domain conventions.
The D&D family has additional shared conventions and domain-specific
exceptions. See [D&D Module Internals](dnd.md) rather than adding them here.
## Typed Boundary And Registration
## Module Boundary
A module implements one fixed pipeline operation; an artifact family owns the
related domain types, codec, modules, validators, prompts, and reference
projections. Family ownership does not combine extraction/merge/normalization
or turn the pipeline into a workflow language.
A module is a typed implementation registered for one pipeline stage. Its
`ModuleSpec` is the public-to-the-framework declaration of its stable key,
stage, execution class, required and provided capabilities, artifact kind, and
accepted reference slots. The execution class states whether a module is
`deterministic` or `llm_backed`; registries retain it for catalog inspection and
resolved-pipeline debug data without constructing the module. The framework
uses the declaration to resolve a configured binding before it builds the
implementation. After selection, the resolver applies profile inheritance only
to bindings whose declared execution class is `llm_backed` and rejects a
binding-specific profile on a deterministic module. The user-facing precedence
contract belongs in [Configuration](../config.md#pipelines).
[ModuleSpec](../../internal/framework/pipeline/module.go) declares the stable
key, operation, execution class, artifact kind, capabilities, reference slots,
and statically selected prompt IDs. Specs can be inspected without constructing
modules. The resolver applies model-profile selections only to model roles.
Static initial/correction dependencies use the same constants as request builders;
they are preflight declarations, not asset manifests or execution fingerprints.
An eligible LLM-backed chunk, extract, merge, or normalize producer may also
declare correction protocol `single_response_v1`. That declaration is a
promise that the implementation accepts one attempt-local semantic correction
and returns an owned copy of the exact one model response that directly
controlled the candidate. It must forward correction only to its structured
completion request; it must not manufacture prior-response material by
serializing a normalized artifact or expose opaque application IDs. Input,
output, validator, and deterministic specs cannot declare the protocol.
[BuildRequest](../../internal/framework/pipeline/construction.go) supplies the
shared native engine, option values, and prepared references. Option-aware
modules provide a resolver validator and a builder using the same strict decoder.
They do not rediscover configuration or reopen reference files. Generated
references arrive through operation requests, not construction-time file reads.
Implementations that accept options must provide both an option validator and
a builder. The validator is used while resolving configuration; the builder
decodes the same options and constructs the implementation from the prepared
`BuildRequest`. Reject unknown options in both paths. A builder receives only
the dependencies and materialized references that the framework prepared for
that operation, so it must not re-read configuration or files.
Typed helpers retain the exact artifact type at registration:
Registry helpers register the typed builder for a stage-specific registry.
They are preferable to hand-written untyped registration because they retain
the artifact type at the framework boundary. Registrars validate the registries
they need, register each leaf implementation, and add any family-owned assets
or default validator chains. They return contextual errors so production
composition fails at startup rather than at the first run.
- [RegisterExtractorBuilder](../../internal/framework/pipeline/extractor_registry.go),
[RegisterMergerBuilder](../../internal/framework/pipeline/merger_registry.go), and
[RegisterNormalizerBuilder](../../internal/framework/pipeline/normalizer_registry.go)
connect typed production to private framework erasure.
- [Typed validators](../../internal/framework/pipeline/validator_registry.go)
register compatible kind/type-specific assessment.
- [Artifact codecs](../../internal/framework/pipeline/artifact_codec_registry.go)
own durable encoding/decoding and intrinsic schema checks.
- Optional [evidence projectors](../../internal/framework/pipeline/artifact_evidence_registry.go)
copy direct generic source references using the codec's exact Go type.
A validator that returns a completed rejection must supply two separate
bounded values: a stable `ReasonCode` for provenance and actionable
`CorrectionGuidance` for the producer. Guidance identifies the semantic defect
and the constraints on one complete corrected replacement. It must not contain
validator keys, diagnostic paths, opaque application IDs, or other internal
identifiers. An operator-facing `Message` may explain the same event, but the
framework never copies it into a model request. Missing or invalid guidance is
a validator contract failure.
Preparation rejects incompatible types/registrations before parsing source.
Projectors do not inspect arbitrary domain JSON or publish files; the
[evidence contract](../integrations/evidence-context.md) owns the excerpt.
An artifact family can register an optional typed evidence projector alongside
its codec. The projector returns defensive copies of the artifact's direct
generic source references and must use the codec's exact Go type. It does not
interpret surrounding context or publish files; the pipeline validates the
capability during preparation and the output boundary owns publication. See
the [Published Evidence Context contract](../integrations/evidence-context.md)
for the durable source-unit excerpt. Lane artifacts retain citation and lane
provenance; the framework does not add either to that published excerpt.
## Native Producer Recipe
An artifact family is broader than a module: it owns the cohesive domain
feature across its artifact type, codec, stage modules, validators, prompt
policy, schemas, identity helpers, and reference projections. An extractor and
normalizer in one artifact family remain independently registered modules in
their respective pipeline stages. This ownership vocabulary does not create a
new registry or change the fixed pipeline.
Follow the actual [spell extractor](../../internal/modules/dnd/extract/spells/extractor.go)
alongside [typed requests/results](../../internal/framework/contracts/typed_pipeline.go)
and [operation contracts](../../internal/framework/contracts/producer.go):
## Production Composition
1. Validate operation input and prepare owned transcript/reference/contextual
projections once. Retain those fixed bytes and resolution mappings locally.
2. Build the initial `promptkit.RunRequest` using the declared prompt ID,
operation profile/session, native artifacts, and variables.
3. Call [RunProducer](../../internal/framework/pipeline/producer.go) with the shared
engine and the supplied typed operation. Supply ordinary interpretation,
correction-request, and supported fallback functions.
4. Interpret `*promptkit.RunResult` into the typed domain candidate. Attach
deterministic identities and canonical source references here, not by asking
the model to reproduce opaque IDs. Return actionable interpretation guidance
separately from operator diagnostics where the module can correct a selection.
5. Build the follow-up request from new findings/assignment only. Preserve
profile/session selections; native coordination carries prior conversation.
Do not rerender source inputs, serialize a domain artifact as a previous
assistant response, or implement another turn loop.
6. Return the helper's value and outcome in the typed operation result. The
runner has already supplied assessment; do not validate again after the helper.
Production composition is intentionally split by family:
The helper checks native structural status before interpretation, binds native
execution overrides/observers, assesses every delivered usable candidate, and
handles prepared reuse. Modules do not replace its assessor/cache or infer
acceptance from provider success. [Pipeline Internals](pipeline.md) owns the
complete assessment/disposition algorithm; [LLM Integration](llm.md) owns native
execution and [State Internals](state.md) owns storage/capture lifecycle.
- The generic registrar provides the unit chunker, generic JSON validators,
JSON output encoder, and shared semantic-reconciliation prompt and response
schema assets.
- The Seriatim registrar provides the transcript input adapter. Its external
input behavior is defined by the [Seriatim contract](../integrations/seriatim.md).
- The D&D registrar provides its codecs, extractors, mergers, normalizers,
validators, prompt assets, fallback profile asset, and default chains. Its behavioral conventions
are documented in [D&D Module Internals](dnd.md).
Fallback construction is explicit and family-owned. It must satisfy intrinsic
shape/source/downstream invariants, but does not rerun ordinary validators or
claim semantic approval. Unsupported/invalid construction fails. No earlier
candidate is recovered after an unusable continuation; cancellation produces no
fallback. Modules do not pick a permissive default or hide an ordinary operation
error as recovery.
The CLI owns the composition that invokes these registrars. A module package
may register its own family but must not assemble the CLI or make framework
packages depend on production extensions.
## Validators And Deterministic Work
Validators receive native execution options and detached candidate/context views,
not a producer operation or semantic-turn loop. Return approval, or rejection
with separate stable reason and actionable `CorrectionGuidance`. Operator
`Message` is not model feedback. The detecting rule owns guidance about fields
the producer controls, without internal paths/keys/opaque identities.
Invalid rejection guidance is a contract failure.
A model validator calls the shared native engine directly, checks native errors/
validation before interpretation, and distinguishes unavailable judgment from
semantic rejection while preserving causes. See the
[combat validator](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/validator.go).
Do not rerun a validator to extend native repair budgets.
Deterministic modules produce once through ordinary typed interfaces. The runner
assesses the value and can invoke an explicitly supported result fallback after
nonacceptance. Production errors propagate without generic retries. Model-backed
modules with legitimate no-model branches use direct `AssessProducer` on that
value; preparation-limit terminal handling uses `FinishProducerFailure` rather
than synthetic requests. The [noop normalizer](../../internal/modules/generic/normalize/noop/normalizer.go)
and registry normalizers show the distinct paths.
## Prompt And Schema Ownership
[assets/notarius.yml](../../assets/notarius.yml) imports ordinary native prompt
declarations and profiles with their filesystem contexts. The content-only
assets package has no registration behavior. Declarations own ordered messages,
cache hints, default profiles, and output contracts/schema selection. Use real
relative content-file paths; no virtual mounts or Go prompt manifests.
A producer's initial/correction pair requests complete responses with matching
schema/profile defaults. Put enduring rules in initial system context and only
current guidance/new assignment in follow-ups. Native structural repair remains
upstream-owned. Private response envelopes are not durable artifact contracts.
See [schema selection](../config.md#prompt-output-contracts-and-schemas) and the
[D&D prompt recipe](dnd.md#prompt-construction) for concrete examples.
## Semantic Reconciliation
`internal/framework/semanticreconcile` is a domain-neutral strategy used by a
typed normalize module; it is not itself a selectable stage module. A
source-backed artifact-family normalizer projects its deterministic records
into contextual candidates and owned typed record envelopes, supplies its
chosen prompt identity and resolved LLM profile, and constructs an engine with
explicit limits. The core filters invalid evidence, assigns contiguous
one-based request-local candidate numbers, renders bounded candidate and
transcript materials, invokes the structured-completion boundary, and assesses
the returned duplicate groups into a stable non-overlapping plan. Candidate
material declares the exact inclusive number range for the request. Transcript
unit IDs and evidence range endpoints remain source positions in a separate
namespace and are never valid candidate numbers.
The [shared core](../../internal/framework/semanticreconcile/preparation.go)
offers preparation, native request builders, proposal assessment, and typed
application functions, not a replacement execution service.
[Requests](../../internal/framework/semanticreconcile/requests.go) consume one
retained preparation. [Proposal safety](../../internal/framework/semanticreconcile/proposal.go)
resolves request-local handles; [application](../../internal/framework/semanticreconcile/application.go)
clones/preserves originals and applies domain policies.
The normalizer then applies that plan through a typed `ApplicationPolicy`. The
core preserves ungrouped records, contribution order, and provenance while the
artifact family owns group guards, field and evidence consolidation, durable
ID derivation, retry and fallback presentation, classified diagnostics, and
postconditions.
These candidate numbers are the concrete private representation of ADR-0013's
request-local handles; they do not enter the typed value or durable artifact.
Fewer than two eligible candidates skips model invocation; exceeding a
candidate or combined-material bound preserves the deterministic result under
the family's fallback policy. Provider, transport, cancellation, and
context-construction failures remain execution errors.
The [item normalizer](../../internal/modules/dnd/normalize/itemregistry/normalizer.go)
preprocesses fixed originals once, prepares bounded windows/handles once, then
uses the same producer helper as extraction. Each complete proposal is assessed
and applied afresh to originals before pipeline assessment. Domain guards,
identity, evidence, diagnostics, and supported final-only fallback remain with
the artifact family. Do not union plans across turns, reuse prior mutated output,
or introduce module retry/repair protocols. [D&D reconciliation](dnd.md#semantic-registry-reconciliation)
explains the concrete policy differences.
When the engine actually makes a proposal call, its typed result carries the
owned exact proposal response under the same correction contract as other
eligible producers. Deterministic skip, limit, and fallback outcomes carry no
model candidate, so a later rejection applies terminal policy without spending
an ineffective semantic retry.
## Production Composition And Change Checklist
When proposal assessment or typed group application rejects a structurally
valid group, the normalizer may return its safe partial value with a
module-requested retry. A feedback-capable directive supplies bounded
model-facing correction guidance separately from operator diagnostics and
retains the exact proposal response as its candidate. The shared stage retry
mechanism appends that response and guidance to a fresh complete request. A
structurally invalid completion has no valid candidate and therefore requests a
feedback-free fresh attempt. On exhaustion, only the final safe fallback and
its bounded process diagnostic advance to validation.
The CLI invokes generic, Seriatim, and D&D registrars. They register typed modules,
codecs, evidence, and owned validator defaults, not prompts/schemas/profiles.
[Seriatim](../integrations/seriatim.md) retains input-format ownership; generic
operations remain domain-neutral; D&D does not compose process behavior.
The core supplies a conservative generic prompt and the single private
response schema. A domain prompt may substitute its semantic instructions but
mounts the core-owned protocol and candidate/transcript presentation assets.
Prompt, schema, policy, and limit identities participate in manifest metadata
and checkpoint fingerprints. The generic registrar owns production
registration of those shared assets; a consuming domain registrar owns only
its domain prompt.
For an extension, add the typed domain/codec boundary, strict options and spec,
native declarations/static dependencies where needed, stage implementation,
and owning registrar entry. Add default chains only where the family owns them.
Reference slots declare artifact/media/size requirements; generated handoffs
must retain prior-step compatibility. Preserve ownership of request maps/slices
and returned stored data. Modules receive no physical roots or CLI reporters.
## Adding Or Changing A Module
1. Choose the pipeline stage and the typed artifact boundary. Put external
input or durable artifact formats in the relevant integration contract,
not in this guide or in a private LLM response type.
2. Define a stable `ModuleSpec` with an explicit execution class, the exact
capabilities, and reference slots needed for the operation. Model a
producer/consumer handoff as an artifact-compatible slot; configuration
then chooses an external file or a generated binding.
3. Implement strict option decoding, construction, and the typed stage
interface. Preserve caller ownership: do not retain mutable request data
and return defensive copies where an implementation exposes stored data.
If declaring correction capability, forward the request correction and
retain only the exact validated response that controlled the result.
4. Register the module through its typed registry helper and add it to the
owning family registrar. Add a default validator chain only when that
family owns the behavior; otherwise require an explicit compatible chain.
Every rejection path in a validator must provide actionable correction
guidance while retaining its stable internal reason code.
5. Update the selectable-key and chain reference in
[Configuration](../config.md#production-module-keys), the applicable
integration contract, and focused tests. Keep the configuration document
as the sole list of production keys and validator order.
## Validation And References
Validators operate on the value produced at their configured stage. A default
chain is ordered behavior, not a set: JSON parsing, structural checks,
domain-specific checks, durable-schema checks, and advisory checks may have
different responsibilities and failure handling. The active default chains and
override rules are maintained in
[Configuration](../config.md#production-validator-keys-and-default-chains).
Reference slots are part of the module specification. They describe the
accepted artifact kind, media type, size, and whether a binding is required;
the framework validates those constraints before construction. An external
reference is materialized during preparation. A generated reference is a
compatible normalized artifact handed from an earlier pipeline step at
operation time. The configuration reference rules, including precedence and
ordered-handoff requirements, are maintained in
[Configuration](../config.md#references-and-ordered-handoffs).
## Focused Verification
Exercise the leaf implementation and its registration path when changing a
module. Registry and registrar tests cover duplicate keys, required registries,
and typed construction; pipeline resolution tests cover capabilities, options,
and reference compatibility. Domain packages should additionally test their
codecs, validators, normalizers, and any integration handoffs they own.
Run the affected package tests while iterating. The complete module suite is:
~~~sh
go test ./internal/modules/...
~~~
Update canonical [keys/chains](../config.md#production-validator-keys-and-default-chains)
and durable contracts when their behavior changes; complete runnable configurations
belong in [examples](../../examples/). Test the actual leaf and registration path,
exact-type compatibility, domain invariants, fixed-input correction, unavailable/
failed outcomes, supported fallback, and cancellation where applicable.
[Spell tests](../../internal/modules/dnd/extract/spells/extractor_test.go),
[item normalization tests](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
and [registration dependencies](../../internal/modules/dnd/register/dependencies_test.go)
are concrete starting points. Use real kits with native provider fakes, not a
replacement completion mock or full prompt-prose snapshots.
[Development](../development.md#validation) owns wider checks.

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.

View File

@@ -1,279 +1,204 @@
# Pipeline Internals
This document describes the framework-owned pipeline mechanics in
**internal/framework/pipeline**. [Configuration](../config.md) owns selectable
profiles, bindings, and retry settings; [Operations](../operations.md) owns
state lifecycle and recovery; and the [integration contracts](../integrations/)
own durable output shapes. Concrete production extensions are covered by
[Module Internals](modules.md).
This guide explains resolution, typed execution, candidate assessment, and
ordering in `internal/framework/pipeline`.
[Configuration](../config.md#pipelines) owns bindings and producer controls;
[Operations](../operations.md) owns state/recovery workflows;
[integration contracts](../integrations/json-output.md) own deliverable shapes.
[Module Internals](modules.md) owns extension recipes.
## Boundary
## Boundary And Fixed Shape
The pipeline framework accepts a resolved composition, registries, shared
dependencies, input bytes, a supplied prompt session, and state/debug
collaborators. It returns logical output files, normalized artifacts, recorded
rejections, grouped diagnostics, manifest provenance, and checkpoint decisions. The
CLI owns process arguments, configuration discovery, session resolution,
physical roots, and placement of returned output files.
The framework receives prepared composition, source bytes, a supplied session,
native execution options, and explicit cache/capture collaborators. It returns
logical deliverable files, process diagnostics, and fallback count. Normalized
artifacts and reuse eligibility remain private run state for handoffs/evidence;
there is no reporting ledger in the output boundary.
The framework has one fixed shape:
```text
input -> chunk -> ordered steps [extract -> merge -> normalize] -> output
```
~~~
input -> chunk -> extract -> merge -> normalize -> output
~~~
Input and chunking are pipeline-wide. A selected artifact lane owns extract,
merge, and normalize; output aggregates the terminal lane outcomes. A pipeline
is an ordered list of steps, not an arbitrary workflow graph.
Input and chunking are pipeline-wide. Each ordered step contains typed artifact
lanes; the next step waits for the current step and its generated handoffs.
This fixed pipeline is not a general workflow graph. The CLI owns arguments,
configuration loading, session derivation, physical roots, publication, and
native reporting; see [CLI Internals](cli.md).
## Resolve, Materialize, Prepare
Resolution turns a configured pipeline profile into a **ResolvedPipeline**.
It normalizes the pipeline and lane identities, applies stage defaults, selects
requested lanes where that is supported, resolves validator chains, checks
module capabilities and typed artifact compatibility, validates options, and
assigns a deterministic resolved-composition digest. A correction protocol is
selected from each eligible LLM-backed producer specification and becomes part
of that resolved identity; only `single_response_v1` is currently supported.
Preparation rejects an LLM-backed producer that combines a non-empty validator
chain with positive producer retries unless it declares that protocol. Producers
without validators or without retries remain valid without correction support.
The resolved pipeline contains bindings and declared reference targets, not
external reference bytes.
After selection, the resolver applies command, binding, and pipeline profile
precedence to LLM-backed bindings and validators only; prompt defaults remain
an empty resolved binding profile. It resolves structural output repair
separately: a binding's `structured_output_repair_attempts` value wins, then a
pipeline value applies to LLM-backed bindings and validators, and omission
leaves the prompt-owned policy intact. An explicit repair value on a
deterministic binding is rejected. Resolved bindings own copied repair values,
and these effective values are part of the digest, so execution and checkpoint
consumers do not repeat profile inheritance or configuration resolution.
Each LLM request receives its own copy of that resolved value. PromptKit spends
it only for structural correction inside one completion; the runner's binding
retry policy remains the separate outer budget for complete stage attempts.
Configuration resolution supplies the selected overlay and catalog; see
[Configuration Internals](configuration.md).
[ResolvePipeline](../../internal/framework/pipeline/profile.go) selects modules,
capabilities, exact artifact kinds, validators, references, options, and concrete
producer controls. It copies static native prompt dependencies from selected
specifications. Effective profiles apply only to model-backed roles; an empty
profile selection leaves native prompt defaults applicable.
[Control resolution](../../internal/framework/pipeline/validation_policy.go)
settles presence-aware controls before execution; modules do not repeat inheritance.
The composition digest describes resolved composition, not cache identity.
External reference materialization happens before preparation. The materializer
checks that each slot is declared by the selected module, resolves a file path
relative to the correct configuration or working-directory origin, reads
UTF-8 text, verifies media type and size limits, and retains bounded
provenance. For a positive slot limit, it reads at most the limit plus one byte
and rejects overflow before retaining content. A generated-artifact selector
remains declared but has no bytes until its producing step completes.
Resolution receives exact reference bindings/unbinds, not CLI selector grammar.
It preserves required slots, external/generated conflicts, prior-step
dependencies, and artifact compatibility. [Reference materialization](../../internal/framework/pipeline/references.go)
reads selected external bytes with declaration/invocation origins, media/UTF-8
and declared size checks. Generated selections remain declarations until their
producer step completes. Public selection semantics belong in
[References And Ordered Handoffs](../config.md#references-and-ordered-handoffs).
Preparation is the construction boundary. It validates the resolved shape and
registry set, clones the resolved data, then constructs the input adapter,
chunker, stage-local validators, every typed lane, and output encoder. The
prepared producer metadata preserves each selected correction protocol, and
the resolved digest carrying that metadata participates in checkpoint identity.
Each registered builder receives its own cloned build request immediately
before its module-owned code runs. Preparation also collects stable checkpoint
fingerprints. Missing registrations, incompatible typed entries, nil
implementations, and constructor failures are reported before source parsing
or any stage operation begins.
[Prepare](../../internal/framework/pipeline/prepare.go) clones resolved data and
constructs input, chunker, validators, typed lanes, and output through supplied
registries and the shared native engine. Builders receive independently owned
build requests. Exact Go type, codec, evidence-projector, registration, and
constructor checks happen before source parsing. There is no correction transport,
asset registry, or persistent execution identity to collect.
Offline known-resource [preflight](../../internal/preflight/preflight.go) is
a separate composition check, not request execution or module construction.
An output encoder can opt into source-evidence publication through its output
policy. Preparation keeps the configured lane allowlist and active lanes
separate, then verifies an exact typed evidence projector and registered codec
for each active lane. The resulting private plan is immutable; lanes excluded
by invocation filtering remain configured but do not acquire a projector for
that run.
## Typed Operations And Assessment
## Typed Lanes And References
[Typed contracts](../../internal/framework/contracts/typed_pipeline.go) carry
a `ProducerOperation[T]` with resolved controls, one assessor, native execution
options, incoming reuse eligibility, and an optional typed cache binding.
[Runner operation completion](../../internal/framework/pipeline/runner_operation.go)
assesses deterministic production directly. Model modules use
[RunProducer](../../internal/framework/pipeline/producer.go); the runner consumes
its acceptance/fallback outcome without assessing it again.
Each resolved lane has one artifact kind, codec, and exact Go type. The
framework uses private type erasure only around those typed operations; every
handoff checks exact type and codec identity and reports incompatibility as an
error rather than panicking. Encoding through the registered codec is the
boundary for output, checkpoints, debug records, and generated references.
[Candidate assessment](../../internal/framework/pipeline/candidate_assessment.go)
invokes each applicable validator once in configured order. It continues after
rejections and unavailable/failed assessments; caller cancellation and framework/
capture failures interrupt it. Typed candidates are encoded once for assessment,
then decoded separately for each typed validator. Serialized validators receive
owned bytes/schema metadata; chunk validators receive detached materialized
chunks. Source, references, annotations, and metadata views are isolated too.
Reference targets are stage- and lane-specific. External reference bytes are
cloned into the operation request. Generated references are built at the next
step boundary from exactly one accepted normalized producer output. The
framework decodes and re-encodes that output with the registered producer
codec, checks its complete schema and media identity, and records a content
digest plus bounded producer provenance. A missing, ambiguous, invalid, or
incompatible producer prevents the consumer step from starting.
[Assessment values](../../internal/framework/contracts/assessment.go) distinguish
approval, semantic rejection, failure, and unavailable judgment. An empty configured
chain adds no ordinary acceptance criteria. Intrinsic codecs, source parsing,
materialization, and necessary module/fallback/cache checks remain; ordinary
artifact citation checks depend on the [configured chain](../config.md#module-bindings-and-validators).
Rejection guidance is module-authored, ordered, and
deduplicated separately from reason codes/operator messages. Invalid guidance is
a contract failure, not invented correction text. LLM validators execute directly
on the shared engine and do not own another semantic loop.
Resolution receives only exact stage-and-lane operational reference overrides.
The CLI may offer broader pipeline- or lane-scoped selectors, but expands and
arbitrates those before entering the framework. External overrides are applied
after configured external defaults and local bindings. They cannot coexist
with a generated binding for the same target and slot, and external unbinds do
not remove generated handoffs.
## Native Continuation And Terminal Handling
## Execution And Ordering
For executed model work, `RunProducer` checks native errors and structural
validation status before interpretation, including a failed result with no Go
error. Module interpretation produces a usable typed candidate and any actionable
domain guidance. The assessor runs the complete chain on every delivered usable
candidate, including unchanged revisions and the final allowed response.
The runner validates its input, installs no-op state collaborators when none
were supplied, and serially performs source parsing and chunk-plan selection.
It transports the supplied session unchanged to prompt-facing operations and
run-manifest metadata; it neither derives a session nor substitutes a parsed
source document identifier. The public session contract is owned by the
[CLI reference](../cli.md#run).
An accepted plan is materialized into source-addressed chunks and passes the
configured chunk validators before any lane runs. A chunk rejection is a
recorded pipeline outcome: lanes do not start, but the output stage can encode
the terminal result.
When correction is possible, the helper starts native `Coordinate` from the
captured exchange. Its first callback reuses already-collected initial findings.
Native coordination owns turn iteration and growing history; the module builds
only new correction material from fixed operation inputs. Successful native
execution, stopped/exhausted coordination, and domain acceptance are distinct.
Native repair/transient retries are not extended by outer application retries.
[LLM Integration](llm.md) owns the native request/capture integration.
For each ordered step, the runner first builds generated reference sets from
the accepted normalized outputs of earlier steps. It then executes the step's
lanes. Later steps do not begin until the current step is terminal and its
generated handoffs have succeeded.
[Terminal disposition](../../internal/framework/pipeline/producer_outcome.go)
either fails or invokes one supported module fallback. Fallback construction
preserves intrinsic/source/downstream invariants without ordinary reassessment
or semantic-approval claims. It may fail normally. A failed continuation cannot
recover an earlier candidate; caller cancellation and undelivered responses
produce no acceptance/fallback. Native operational timeouts retain typed causes
rather than becoming caller cancellation solely by error spelling.
Within a step, the lane engine dispatches extraction jobs in deterministic
chunk-first, lane-second order to a bounded worker group. When all extraction
jobs for one lane are terminal, a bounded continuation group can run that
lane's merge and normalize work while extraction for other lanes continues.
The framework does not create an unbounded goroutine per chunk or lane.
Deterministic work produces once, then uses direct assessment and any supported
module fallback. An operation/parse/materialization/encoding error remains an
error, not a generic rerun or permissive recovery mechanism.
Completion timing does not determine public results. The coordinator restores
lane and chunk order before merging results, and selects a framework error by
stable stage, lane, and chunk position. A validator rejection records a lane
outcome without cancelling unrelated work. A framework error or parent
cancellation cancels derived work, prevents queued work from starting, waits
for started workers, and prevents output encoding.
## One Ready-Job Worker Pool
## Validation, Retries, And Output
[The lane coordinator](../../internal/framework/pipeline/runner_concurrent.go)
dispatches extraction jobs and ready lane continuations to the same bounded
worker pool. A continuation becomes ready after all extracts for its lane finish;
one worker runs its merge then normalization. Ready continuations can interleave
with unrelated extraction, and prerequisite waits occupy no worker.
Input parsing, chunking, step barriers, and final output remain sequential.
Every chunk, extract, merge, and normalize candidate passes its resolved
validator chain. Validators receive immutable canonical input appropriate to
their target: chunks, codec-decoded typed candidates, or serialized codec
bytes. Each typed validator receives a newly decoded value from the one
candidate serialization for that attempt, while serialized validators receive
separately owned representation bytes and schema metadata. They may approve,
approve with warnings, reject, fail, or be skipped when a runtime prerequisite
is unavailable. The shared executor settles every configured validator in
order. A failed LLM-backed validator retries only itself against the same
immutable candidate; it does not regenerate the producer or alter the
validator request. Rejections stop that validator, while other configured
validators still run. The executor retains ordered results, bounded
deduplicated correction guidance from rejections, and only the final exhausted
failure outcome for each validator. The correction builder keeps first
occurrence order, omits internal reason codes, validator names, and operator
messages, and requests one complete replacement. Missing guidance or an
oversized aggregate is a framework contract error; guidance is never inferred
or truncated.
Results are restored to chunk/lane order before merging. Stable operation/lane/
chunk positions select the scoped terminal error among reported failures rather
than response timing. Parent cancellation takes precedence. On failure/cancellation
the coordinator stops dispatch, drains started results, closes jobs, and joins
workers before returning. Output encoding does not run after terminal failure.
The runner applies the binding's retry policy around a stage operation and its
complete validation chain. It preserves terminal diagnostics only from the final accepted
or rejected attempt, plus one fixed validation-incomplete warning per validator whose execution
budget was exhausted under `warn_continue`. Cancellation stops retries.
Normalizer-specific retry directives consume this same budget and validate any
final safe fallback through the normalizer chain. A directive may carry bounded
correction guidance only when it also exposes the exact latest
`single_response_v1` candidate. The state machine then uses the same replacement
request shape as validator correction. A directive without guidance clears any
prior correction and starts a fresh attempt, which preserves structural retry
behavior when no valid response exists.
Nested validation and correction use the operation's worker, not another worker
permit. Native backend admission is independent and released before candidate
assessment, allowing a nested validator on the same limited backend. Worker
configuration does not create another model scheduler, queue, or retry policy.
The artifact-neutral producer-attempt state machine owns that shared budget,
attempt provenance, semantic-correction material, and terminal-policy
selection. It accepts producer and complete-validation closures, so artifact
materialization, cache handling, checkpoints, and debug output stay at the
operation boundary. It distinguishes operational, structural, module-requested,
and validator-semantic retries. Model feedback from either semantic source is
available only for a valid latest `single_response_v1` candidate. A
deterministic or no-model validator rejection instead settles the semantic
policy immediately, while a feedback-free module directive remains an ordinary
fresh retry. Structural-output errors alone use the structural policy, and
validation failure without rejection settles the validator-failure policy
without regenerating the producer.
## Handoffs And Reuse Eligibility
Chunk planning uses this state machine for generated plans. A rejected or
validation-incomplete automatic cache hit is not model material and therefore
falls through to a fresh initial generation at producer attempt one; it neither
receives a correction, consumes retry budget, promotes cached-candidate
diagnostics, nor overwrites the stored record. An incomplete cache validation
under `fail_run` terminates instead. Only a newly generated, completely
validated plan is published to the chunk-plan store. Rejected plans never
advance, and validation-incomplete plans remain unpublishable.
[Generated handoffs](../../internal/framework/pipeline/handoff.go) locate one
earlier normalized producer, decode/re-encode through its registered codec, check
full artifact/schema/media compatibility, and clone bytes into the consumer's
declared reference set. Valid qualified fallback is usable current-run context;
it does not become ordinary acceptance through a handoff.
After terminal lane work, the runner assembles manifest provenance, normalized
artifacts, rejections, final grouped diagnostics, and an optional accepted chunk map. When an
output policy selected evidence lanes, it decodes accepted serialized normalize
outputs through their registered codecs and invokes the prepared typed
projectors. Rejected or absent lanes contribute nothing. This reconstruction is
also used after normalized-checkpoint reuse, so no second typed output channel
is retained. The runner passes the resulting owned artifact to the output
encoder, which returns logical files and does not choose a physical directory.
The CLI publishes those files only after the runner returns without a framework
error. Logical file names and schemas are defined by the [output integration
contracts](../integrations/).
Eligibility travels separately from artifact bytes:
For every completed producer disposition, the runner projects one bounded
validation summary to the manifest, the affected rejection when present, and
the CLI result receipt. The summary records status, configured-order rejecting
validators and reason codes, incomplete validators, producer-attempt count,
and terminal action. It contains no operator message, correction guidance, or
model response. `complete`, `rejected`, and `incomplete` describe the final
candidate disposition; a run-level `incomplete` status indicates at least one
current-run output advanced under `warn_continue`.
- A chunk fallback disables reuse for all derived lane work.
- An extract fallback disables reuse for its dependent merge/normalization.
- A fallback-derived generated reference disables reuse from the consuming
operation onward; unrelated siblings and earlier accepted work remain eligible.
## Checkpoint And Debug Hooks
An emitting fallback increments the run count once. Merely consuming its data or
inheriting ineligibility adds no fallback. These are transient dependency facts,
not persisted fingerprints or a second recovery protocol.
The runner receives checkpoint and debug interfaces rather than roots. It
records workflow transitions and reuse decisions through the supplied
collaborators, and clones reusable artifacts before they re-enter normal typed
handoff. Generated-reference dependencies participate in checkpoint decisions.
Selective recomputation can require a canonical accepted normalized predecessor
before a dependent lane starts.
[Typed cache bindings](../../internal/framework/pipeline/runner_cache.go) use the
registered durable codec and available exact-type evidence projection for
current-source usability. [Chunk planning](../../internal/framework/pipeline/runner_chunk_plan.go)
uses the same producer cache with plan decoding/rematerialization. Hits do not
run semantic assessment. Deterministic work has no synthetic request/cache key.
[Run State Internals](state.md) owns prepared-handle/store mechanics and recovery.
The runner writes successful checkpoint artifacts only after complete accepted
validation. Chunk plans follow the same rule for publication. A rejection,
invalid structured response, or incomplete validation is never reusable state;
the current run may still hand off an otherwise valid `warn_continue` result
according to its terminal policy. The runner carries private reuse eligibility
through extract, merge, normalize, and generated-reference handoff. Any stage
derived from incomplete validation skips both checkpoint lookup and all
checkpoint publication even when that stage's own validation completes.
External references and fully validated generated references remain eligible.
Attempt debug records retain safe kind,
validator, repair-usage, policy, and terminal-decision provenance. Full
assistant and correction content remains confined to the requested detailed
LLM trace.
## Output And Capture Boundaries
Debug recording is attempt-scoped and application-owned. A failure to persist
required debug data is a framework error. State roots, persistence, reason-code
meanings, resume, and cleanup are intentionally owned by
[Run State Internals](state.md) and [Operations](../operations.md).
Extract-validator trace scopes include the current chunk ordinal so concurrent
chunks cannot overwrite one another's validator attempts or LLM artifacts.
[Runner](../../internal/framework/pipeline/runner.go) parses/validates source,
materializes the final plan, runs ordered steps, aggregates diagnostics, and
builds optional chunk-map/evidence values. Normalized values are codec-checked
before handoff/output. Evidence reconstruction also works from reused artifacts;
it projects selected citations in source order, not a second typed output channel.
[Evidence internals](../../internal/framework/pipeline/evidence_output.go) and
the [evidence contract](../integrations/evidence-context.md) define those owners.
## Invariants To Preserve
The encoder receives owned normalized/auxiliary values and returns logical files.
It does not choose a directory, publish a report, or serialize execution ledgers.
[JSON output](../integrations/json-output.md) owns logical paths and payloads;
[State Internals](state.md) owns physical publication and failure retention.
- The six fixed stages remain explicit; a pipeline is not a general DAG.
- Resolution and preparation reject statically discoverable incompatibility
before parsing or execution.
- Every typed lane uses one compatible artifact kind, codec, and exact Go type.
- Generated references come only from one earlier accepted normalized producer
and carry canonical identity rather than an unverified value.
- Rejections are recorded outcomes; framework errors cancel derived work and
prevent output encoding.
- Public ordering and selected errors are independent of goroutine completion
order.
- Pipeline modules receive collaborators and data, never CLI streams or
physical output, cache, or debug roots.
Optional scoped evidence records inputs, candidates, findings, outcomes, and
cache decisions. Native observers enroll actual executions once in one invocation
group, preserving unknown usage and terminal coverage. Capture failures are
ordinary boundary failures, never semantic feedback or reasons to rerun a model.
Debug layout is private; it is not a recovery source or consumer protocol.
## Focused Tests
## Focused Verification
- **internal/framework/pipeline/profile_test.go** and
**typed_resolution_test.go** cover resolution, defaults, ordered steps,
compatibility, validators, references, and resolved identity.
- **internal/framework/pipeline/preparation_test.go** covers complete
construction before execution and contextual construction failures.
- **internal/framework/pipeline/references_test.go** and **handoff_test.go**
cover external materialization, generated references, provenance, and typed
producer checks.
- **internal/framework/pipeline/runner_concurrency_test.go** covers bounded
execution, ordered steps, stable error selection, rejections, and
cancellation.
- **internal/framework/pipeline/runner_chunk_plan_test.go**,
**runner_typed_checkpoint_test.go**, and
**runner_accepted_checkpoint_test.go** cover state hooks and reuse behavior.
- **internal/framework/pipeline/runner_attempt_debug_test.go** and
**runner_terminal_debug_test.go** cover attempt and terminal debug behavior.
- [Resolution](../../internal/framework/pipeline/typed_resolution_test.go),
[preparation](../../internal/framework/pipeline/preparation_test.go), and
[references](../../internal/framework/pipeline/references_test.go) cover static
compatibility and construction/materialization ownership.
- [Assessment](../../internal/framework/pipeline/candidate_assessment_test.go)
and [producer tests](../../internal/framework/pipeline/producer_test.go) cover
isolation, whole-chain/final-turn assessment, guidance, native status, and cancellation.
- [Runner operations](../../internal/framework/pipeline/runner_operation_test.go)
cover no outer reassessment, deterministic errors, fallback counts/eligibility,
and actual generated consumers.
- [Worker tests](../../internal/framework/pipeline/runner_concurrency_test.go)
and [ready-job tests](../../internal/framework/pipeline/ready_jobs_test.go)
cover mixed jobs, stable order, serial liveness, nested admission, and draining.
- [Producer reuse](../../internal/framework/pipeline/producer_cache_test.go),
[runner reuse](../../internal/framework/pipeline/runner_cache_test.go), and
[plan reuse](../../internal/framework/pipeline/chunk_plan_cache_test.go) cover
initial keys, applied artifacts, no reassessment on hits, and current-source checks.
- [Capture](../../internal/framework/pipeline/native_capture_test.go),
[evidence](../../internal/framework/pipeline/evidence_output_test.go), and
[assembled recovery](../../internal/cli/recovery_contract_test.go) cover
native facts, output reconstruction, and cross-boundary reuse/failure.
Run **go test ./internal/framework/pipeline ./internal/cli** after changing a
pipeline boundary. Use the more focused tests above while iterating.
Use focused pipeline and CLI suites for boundary changes.
[Development](../development.md#validation) owns repository-wide checks.

View File

@@ -1,165 +1,193 @@
# Run State Internals
LLM debug response artifacts and their safe per-call references retain an
optional terminal execution summary when one is available. This metadata is
diagnostic only and does not change receipts, checkpoints, or aggregate usage.
This guide explains physical cache, capture, and publication collaborators.
[Operations](../operations.md) owns layout, permissions, retention, and recovery
procedures; [Configuration](../config.md#concurrency-output-cache-and-debug) owns
settings/defaults; [CLI Reference](../cli.md#completion-report) owns reporting.
[Pipeline Internals](pipeline.md) owns assessment, workers, and dependency eligibility.
This document describes the implementation collaborators behind output, cache,
and debug state. User-visible fields belong in [Configuration](../config.md),
and physical layout, retention, recovery, reason codes, and cleanup belong in
[Operations](../operations.md).
## Composition And Independent State
## Composition
[The run handler](../../internal/cli/pipeline_run.go) is the physical-path
composition root. It obtains loaded configuration and a safe run identity,
allocates requested capture before engine/preflight, resolves/materializes/
prepares, and then constructs the cache/recorder collaborators for the runner.
Shared inspection loaders create no run storage.
`internal/cli` is the only physical-path composition root. It resolves the
effective configuration, selects exact roots, allocates requested debug bundles,
constructs cache collaborators, writes logical output files, and reports paths.
Pipeline modules receive interfaces and request data, never output, cache, or
debug roots.
Modules receive explicit operation/cache/evidence interfaces and data, not roots
or CommandKit reporters. Output, accepted-result cache, and optional capture
remain independent. None is a required metadata bundle for another.
In-memory normalized artifacts support handoffs/evidence; they are not a
persisted resume ledger.
The CLI creates no chunk-plan store in bypass mode. It creates a checkpoint
recorder only when recording is enabled and a checkpoint loader only for a
resume invocation. It allocates debug state only after a safe run identity has
been generated and only when debug capture was requested. These choices keep
the three state families independently composable.
## Prepared Result Reuse
## Output And Cache
[RunProducer](../../internal/framework/pipeline/producer.go) owns native request
selection and cache interaction for an eligible model operation:
The pipeline runner returns logical output files. After validating every
logical name, the CLI exclusively creates the run directory beneath the
selected output root and performs confined, atomic file writes within it.
The runner supplies an accepted chunk map as an optional, defensively owned
output-request artifact. The JSON encoder alone decides whether its explicit
option writes the map and optional index descriptor; neither the map payload
nor its annotations are copied into the run manifest. The durable fields are
owned by the [Accepted Chunk Map contract](../integrations/chunk-map.md).
1. Prepare the initial request once with `PrepareExecution`, retain its detached
details and opaque `MessageContentHash`.
2. For a read-enabled selection, decode a found entry through the expected
durable codec and current-source usability checks. On a usable hit, discard
the prepared handle and return the artifact without model work.
3. On a miss, execute that exact handle with `RunPrepared`, then use ordinary
interpretation, complete assessment, and native continuation.
4. Store only final ordinary acceptance, encoded as the applied typed artifact
or checked logical plan, under the initial key. Dispose of unused
prepared handles on every exit.
`internal/framework/chunkplan` owns source-addressed plan storage, validation,
and atomic publication. Its store is constructed only when the selected mode is
not `bypass`. It preserves rooted entry checks while creating new cache roots
and source-digest directories with requested mode `0777`, then creates an
atomic temporary file through rooted `O_CREATE|O_EXCL` with requested mode
`0666` before sync and rename.
[Typed bindings](../../internal/framework/pipeline/runner_cache.go) attach codec
and source-evidence checks; [chunk-plan bindings](../../internal/framework/pipeline/runner_chunk_plan.go)
decode and rematerialize against the current document. A hit has no ordinary
semantic revalidation, native execution event, restored exchange, or historical
usage. Normalizers store applied domain results, not reconciliation proposals.
Deterministic operations stay uncached without manufactured requests.
`internal/framework/checkpoint` owns checkpoint identity, manifests, payload
codecs, loader, and recorder. The CLI constructs a recorder whenever checkpoint
recording is enabled and constructs a loader only for a `--resume` invocation.
The recorder writes manifest and payload JSON through
`fileio.WriteJSONWithProcessPermissions`, whose confined atomic writer creates
new directories with requested mode `0777` and temporary files with requested
mode `0666` before publication.
Identity incorporates explicit stable semantic fingerprints collected from
prepared modules and validators in addition to configuration, input,
references, runtime overrides, observed LLM profiles, and the LLM runtime's
non-secret effective profile-source identity. A profile source change therefore
causes a cold miss even when the configured profile ID remains unchanged.
The serialized
`workspace_schema_version` identifiers are frozen wire-compatibility fields;
they do not describe a current public state surface.
The key is the native initial message-content value, not a configuration,
policy, model/session, implementation, or source-only fingerprint. Rendered
message changes can change selection; settings-only changes need not.
Correction retains the initial key. Public reuse choices and their consequences
belong in [Operations](../operations.md#accepted-result-cache-and-recovery).
Ordered-step lane checkpoints include the step identity in their storage scope.
Accepted step and lane identities are encoded injectively before becoming
filesystem path components, while ordinary safe identifiers retain their
readable paths.
When a later lane consumes a generated artifact, its dependency fingerprints
include the producer's artifact kind, complete schema identity, media type,
canonical content digest, and size. Ordinary resume compares those fingerprints
when progressively loading consumer stage checkpoints, so changed producer
content produces `dependency_invalidated` rather than stale downstream reuse.
Selective recomputation instead requires each unselected producer's accepted
normalized artifact; invalid accepted state records its specific bounded reason
and stops before the dependent. The selected step and its transitive dependents
record `forced_recompute`.
Reuse eligibility is separate from the selected cache mode. Fallback and actual
dependent work perform neither lookup nor storage, even if they later produce
otherwise accepted output. Bypass/ineligible work uses ordinary native execution
without cache-specific split preparation. Capture reuses available prepared
details; it never adds preparation to explain a hit.
Ordinary resume loads extract, merge, and normalize checkpoints progressively
and may execute later lane stages after an earlier cache miss. Selective
recomputation instead asks the loader for the required producer's accepted
normalize artifact. That lookup reuses the existing normalize files, requires
workspace schema v4 plus an exact non-empty invocation identity, and deliberately
does not require extract or merge checkpoint files or dependency fingerprints.
The runner performs canonical codec and producer-provenance validation before
cloning the artifact into normal step output. Success restores only stored
normalize diagnostics and emits one normalize decision; failure retains the
files, records the decision, and stops without executing the producer or
consumer.
## Filesystem Store And Failure Handling
The loader assigns a typed category and reason code at each validation site;
diagnostic prose is not classified after the fact. The runner then applies
forced-execution policy, validates reusable artifact bytes through the prepared
codec once, returns the canonical hydrated value to the stage, and records the
final decision before enforcing a required-predecessor failure. That failure
names only the step, lane, and stable reason code. Decision detail is selected
from code-owned descriptions by reason code and then UTF-8 normalized and
bounded; callers cannot supply arbitrary diagnostic prose. Typed categories and
codes remain intact through pipeline events and become strings only in manifest
and debug-summary JSON.
[Operations](../operations.md#checkpoint-recording-resume-and-recompute) is the
canonical operator-facing reason-code reference.
[artifactcache.FilesystemStore](../../internal/framework/artifactcache/filesystem.go)
implements the narrow `contracts.ArtifactCache` interface. Construction retains
the exact selected root without creating it. Lookup checks one confined regular
JSON entry; missing data is an ordinary miss. Stored bytes are the unchanged
accepted artifact, without provenance/execution envelopes or alternate key
dimensions. Physical placement belongs in
[Operations](../operations.md#state-surfaces).
`internal/core/fileio` provides confined atomic file writes used by state
collaborators. Its exact-mode writer remains available to output and debug
callers; its process-permission writer is used by checkpoints. The chunk-plan
store retains its stronger rooted entry validation. [Operations](../operations.md#cache-provisioning)
owns cache mode and provisioning guidance.
The store honors the resolved read/write mode. Refresh does not read or remove
previous acceptance in anticipation of execution. Only a newly supplied accepted
value can replace it. Failed refresh execution or a failed cache write preserves
the old entry.
Legacy data is not scanned, converted, rewritten, or deleted.
The CLI constructs selective-recomputation policy from resolved generated
artifact dependencies. It forces the selected step and transitive consumers,
while marking unforced producers as required reusable inputs. The runner owns
the actual hydration and rejection decisions; the [Operations guide](../operations.md#checkpoint-recording-resume-and-recompute)
owns the operator workflow and stable reason-code meanings.
Publication uses [fileio](../../internal/core/fileio/fileio.go)'s confined atomic
process-permission writer. New cache objects use process/deployment creation
permissions; there is no permission convergence on an existing root.
[ADR-0017](../adr/0017-defer-cache-access-policy-to-deployment.md) owns that decision.
## Debug Bundles
[Cache integration](../../internal/framework/pipeline/producer_cache.go) treats
unreadable/malformed/codec-unusable entries as diagnostic misses. Store failures
become scoped process warnings without failing successful production or calling
the provider again. Artifact encoding, caller cancellation, requested evidence,
and observer failures retain their own error boundaries; they are not swallowed
as best-effort storage failures.
`internal/core/debugbundle` allocates an explicitly requested per-run bundle
with `summary/` and `trace/` roots. `SummaryWriter` persists redacted command,
resolution, run, final grouped diagnostic, and failure artifacts. `internal/framework/debug`
implements the pipeline-facing trace recorder under the trace root.
Accepted predecessors can survive downstream failure and be reused by an ordinary
rerun. There is no checkpoint loader, resume barrier, forced-recompute policy, or
canonical partition selected solely by source digest. New message selections
populate independently; an accepted plan is rematerialized, not restored with a
historic execution claim.
The CLI allocates a bundle before pipeline resolution and treats requested
summary or trace persistence failures as command failures. The pipeline's debug
boundaries redact sensitive metadata and credential-shaped bytes while allowing
application-owned trace material. Debug data is never a checkpoint source or
cache input.
## Artifact Publication And Native Reporting
Generated reference bytes exist only in cloned operation requests and are not
written as paths into checkpoints, manifests, or debug summaries. Those state
surfaces retain canonical identities and bounded producer provenance so that a
resume decision can be explained without copying generated campaign content.
The runner returns logical deliverable files only after successful execution/
encoding. The [JSON encoder](../../internal/modules/generic/output/json/encoder.go)
owns domain-file selection and optional auxiliary inclusion.
[JSON output](../integrations/json-output.md),
[chunk maps](../integrations/chunk-map.md), and
[evidence context](../integrations/evidence-context.md) own logical paths/schemas,
not the store or recorder.
After allocation, one CLI-owned state value accumulates the known report paths,
pipeline outcome counts, and validation status. A single guarded terminalization
operation writes the success report, or makes one attempt each to write the
failure report and error log. Terminal persistence failures are reported
separately and never replace the command's primary error.
[writeOutputFiles](../../internal/cli/run_output.go) validates every logical
path before allocating the run directory, refuses an existing destination, and
writes files with confined atomic helpers. This is per-file publication, not
an all-files transaction. A later write can leave a partial new directory;
existing siblings are preserved. No rollback deletes available artifacts.
## Invariants To Preserve
After complete publication, the run handler finalizes requested capture before
[reportRunResult](../../internal/cli/run_result.go) submits the small native
completion value. The report is not automatically persisted or required to decode
domain files. No index, manifest, receipt, or process-diagnostic sidecar is emitted.
Artifact count counts returned deliverables, including selected available auxiliaries,
not cache/debug/intermediate files.
- Modules receive state collaborators and request data, never physical roots.
- Output logical paths are validated before a run directory is allocated, and
files are atomically written within that directory.
- Chunk-plan publication occurs only for accepted plans; bypass does not
construct or touch a plan store.
- Checkpoint recording and checkpoint loading remain separate collaborators.
- Debug state is opt-in, is not cache input, and terminal reporting does not
obscure the command's primary failure.
Post-publication capture/render/delivery failure remains nonzero with available
locations. Valid artifacts remain; model work and capture terminalization are not
repeated. Native delivery evidence is separate from the operation cause, and
failed stdout may be partial. Public outcomes and caller responsibilities belong
in [CLI Reference](../cli.md#output-streams-and-exit-statuses) and the
[subprocess guide](../consumers/subprocess.md).
## Tests To Inspect
## Capture Lifecycle
- `internal/cli/run_contract_test.go`: command-owned state allocation,
terminalization, and output/report boundaries.
- `internal/cli/cache_contract_test.go`: cache-mode precedence, root selection,
and resume collaborator construction.
- `internal/cli/state_hardening_test.go`: independent roots, reuse, failures,
permissions, cleanup, and redaction.
- `internal/cli/recompute_policy_test.go`: forced dependents and required
reusable predecessors for selective recomputation.
- `internal/cli/recompute_execution_contract_test.go`: selective recomputation,
filesystem recovery, deterministic decisions, and failed predecessor state.
- `internal/cli/production_contract_test.go`: production composition and
configuration validation at the CLI boundary.
- `internal/cli/example_contract_test.go`: maintained example ownership.
- `internal/core/debugbundle/*_test.go`: bundle allocation and summary writes.
- `internal/framework/checkpoint/*_test.go`: checkpoint serialization and
reuse.
- `internal/framework/chunkplan/store_test.go`: plan envelope, confinement,
publication, and permissions.
[Debug selection](../../internal/cli/run_debug.go) preserves native boolean and
supplied directory semantics independently of verbosity. The run path alone
calls [debug.Start](../../internal/framework/debug/recorder.go).
[Bundle allocation](../../internal/core/debugbundle/bundle.go) validates identity,
creates a new absolute per-run directory, and atomically updates a relative
latest link at start. Failure can return an available directory for explanation/
retention. Disabled capture creates nothing; completion never retargets the link.
One synchronized recorder writes evidence incrementally, retaining lifecycle
state and the first recording error rather than accumulating whole-run content.
Callback failures are exposed at the next boundary that can return an error.
`Finalize` attempts terminal evidence once, joins primary and capture causes,
and retains its result. Repeated calls do not rewrite evidence or retarget latest.
A later presentation failure does not change capture into another terminal run.
Allocation/link/record/finalization failures never trigger model retries or a
fallback directory. Available files are retained.
## Native And Application Evidence
[Run capture](../../internal/cli/run_capture.go) snapshots the original secret-aware
application/PromptKit configuration and source evidence. Scoped pipeline capture
records source/reference/incoming artifacts, normalization originals/mappings/
proposals, candidates, complete findings/guidance, fallback/deterministic outcomes,
and cache selection/current artifact bytes.
[NativeCapture](../../internal/framework/pipeline/native_capture.go) composes
existing observers and preparation callbacks. Preparation callbacks retain
detached details cheaply; ordinary boundaries write prepared contracts, native
results, raw response text, and full readable exchanges. Events are written
incrementally. Scope includes operation/step/lane/chunk/validator identity to
avoid concurrent evidence collisions.
One invocation `ExecutionGroup` enrolls actual initial, continuation, and nested
validator executions once. Native identity, terminal coverage, and unknown usage
remain native facts, not a copied profile/attempt accounting model.
Hits can retain prepared evidence without execution or usage. Result-less failures
retain availability/cause evidence; undelivered responses are explicitly unassessed.
Native credential omissions and ConfigKit marked-secret paths are preserved.
Arbitrary source/prompt/response text is not heuristically rewritten or made safe
for general logging. Exact evidence names/nesting/serialized forms are private,
not a public protocol or reconstruction requirement. Debug is neither cache
input nor an artifact-discovery interface; [Operations](../operations.md#debug-bundles)
owns handling.
## Focused Verification
- [Filesystem cache](../../internal/framework/artifactcache/filesystem_test.go)
and [permissions](../../internal/framework/artifactcache/filesystem_permissions_unix_test.go)
cover raw bytes, modes, atomic replacement, diagnostics, confinement, deployment
permissions, and unchanged legacy files.
- [Producer cache](../../internal/framework/pipeline/producer_cache_test.go),
[typed runner cache](../../internal/framework/pipeline/runner_cache_test.go), and
[plan cache](../../internal/framework/pipeline/chunk_plan_cache_test.go) cover
initial handles/keys, final acceptance, current-source checks, and failed refresh.
- [Recorder](../../internal/framework/debug/recorder_test.go) and
[allocation](../../internal/core/debugbundle/bundle_test.go) cover incremental
failure retention, concurrent starts, and one terminalization.
- [Native evidence](../../internal/framework/pipeline/native_capture_test.go) and
[configuration capture](../../internal/cli/run_capture_test.go) cover available
content, exact sensitivity, observer composition, and no duplicate preparation.
- [Output writes](../../internal/cli/run_id_test.go) and
[native result boundaries](../../internal/cli/run_result_command_test.go) cover
collisions, partial directories, capture/presentation failure, and retained causes.
- [Assembled recovery](../../internal/cli/recovery_contract_test.go) covers
downstream fix/rerun, initial-key correction reuse, qualified fallback, actual
generated consumers, and debug on hits/failure.
Use focused pipeline/cache/recorder/CLI checks for state-boundary changes.
[Development](../development.md#validation) owns wider validation.

View File

@@ -1,440 +1,292 @@
# Operations
This is the canonical guide for operating Notarius runtime state. The
[CLI reference](cli.md) owns command syntax and exit statuses, while
[Configuration](config.md) owns fields, defaults, and precedence. Maintainers
who need implementation mechanics should read [Run State Internals](internal/state.md).
This guide owns runtime filesystem layout, publication, cache recovery, capture,
provisioning, and retention. [CLI Reference](cli.md) owns invocation and reports;
[Configuration](config.md) owns settings/defaults and source selection.
The [native migration guide](consumers/native-migration.md) maps retired interfaces
to the current workflow.
## Source Deployment
Linux is the supported deployment platform. Install a pinned source release
with the Go version declared in `go.mod` (currently Go 1.25.5):
Linux is supported; macOS is best-effort for development and Windows is
unsupported. Install a pinned source tag with the Go version required by
`go.mod`:
~~~sh
GOWORK=off go install \
gitea.maximumdirect.net/eric/notarius/cmd/notarius@vMAJOR.MINOR.PATCH
notarius version
~~~
Pin the exact tag in deployment automation rather than following a branch.
Use [`notarius --version`](cli.md#command-summary) as a diagnostic after
installation; its syntax and semantics are owned by the [CLI reference](cli.md).
The maintainer publication process, including tag guards and verification,
belongs to [Source Releases](release.md). macOS builds are best-effort for
development, and Windows is unsupported.
Dependency acquisition/private-module access is separate from offline validation.
[Source Releases](release.md) owns maintainer publication commands. This workflow
does not prepare or authorize a release.
## State Surfaces
Each run can use independent roots with different retention and access-control
needs.
Output, cache, and debug have independent roots and lifecycles.
| Surface | Purpose | Created when | Retention |
| --- | --- | --- | --- |
| Output | Durable user-facing result bundle | A pipeline completes and returns logical output files | Keep until consumers no longer need it. |
| Chunk-plan cache | Reconstructible source-addressed plan | The configured cache mode permits cache I/O | Keep while reuse is useful. |
| Checkpoint cache | Reconstructible execution and recovery state | Checkpoint recording is enabled | Keep only while recovery or reuse is useful. |
| Debug bundle | Explicit diagnostic record | A run requests debug collection | Keep only under an intentional sensitive-data retention policy. |
| Surface | Purpose | Allocation / reuse |
| --- | --- | --- |
| Output | Durable domain artifacts | A successful runner result publishes into a new run directory. |
| Accepted-result cache | Reconstructible artifacts and LLM chunk plans | Eligible model-backed work reads/writes according to its resolved mode. |
| Debug | Explicit run/operation evidence | Explicit capture selection with a nonempty effective destination. |
Output, cache, and debug roots are never merged or cleaned automatically. Use
separate locations and permissions for operators or services that must not
share application data.
Directories do not imply one another's enablement or permissions. Configure
separate roots when access or retention needs differ. Notarius performs no
automatic output/debug deletion or cache collection.
## Roots And Permissions
The configured output and debug directories are exact roots. An empty cache
directory selects a per-user root:
Publication and capture use run-specific directories:
~~~
<os.UserCacheDir>/notarius/chunk-plans
<os.UserCacheDir>/notarius/checkpoints
~~~text
<output-root>/<run-id>/
<debug-root>/<run-id>/
<debug-root>/latest -> <run-id>
~~~
The field definitions and configuration examples are in [Configuration](config.md).
On supported Unix systems, output directories and files are created with
requested modes **0755** and **0644**; debug directories and files use
**0700** and **0600**. The operating system's umask may impose stricter output
or debug modes. Chunk-plan and checkpoint caches instead request maximum modes
of **0777** for new directories and **0666** for new files, including atomic
temporary files. The kernel applies the service's umask and applicable default
ACLs when those entries are created.
The unified cache uses its selected exact root independently of run IDs:
## Cache Provisioning
~~~text
<cache-directory>/<opaque-message-content-hash>.json
~~~
Cache locations select where Notarius writes, not who can access them. A
private service can use a restrictive umask:
Omitted/empty cache selection uses the per-user location defined in
[Configuration](config.md#file-shape-and-defaults), normally under Linux's
`XDG_CACHE_HOME` or `~/.cache`. `/var/cache/notarius` is the convention for
an explicitly configured system-wide installation, not an automatically selected
or provisioned root. Output/debug defaults, empty values, and path origins also
belong in that reference.
Output creation requests directory/file modes `0755`/`0644`; debug requests
`0700`/`0600`. The operating system may restrict effective access. Cache creation
requests conventional maxima `0777`/`0666`, including atomic temporary files,
so deployment umask, setgid inheritance, and default ACLs select effective access.
Notarius does not converge existing ownership or modes.
### Cache Provisioning
A private deployment can use a restrictive process umask. A trusted-group
deployment may provision a setgid root or default ACL. These are deployment
choices, not requirements imposed on every operator:
~~~sh
umask 0077
notarius run example --config /etc/notarius/config.yml --input /srv/input.txt
~~~
A trusted-group deployment can provision a setgid cache root and use a
group-oriented umask (or an equivalent default ACL):
~~~sh
install -d -m 2770 -g notarius-operators /srv/notarius/chunk-plans /srv/notarius/checkpoints
# Example provisioning by an authorized administrator.
install -d -m 2770 -g notarius-operators /var/cache/notarius
umask 0007
notarius run example --config /etc/notarius/config.yml --input /srv/input.txt
~~~
Setgid and default ACLs control inherited group ownership and access policy;
Notarius does not copy a parent directory's literal mode bits. Cache state is
reconstructible but can contain source-derived data, so operators own its
access and retention policy. Existing cache inodes retain their prior modes
after an upgrade. Recreate a cache beneath correctly provisioned parents, or
stop writers and perform a deliberate administrative migration when a
whole-tree change is required.
Configure the cache root to use that directory. Setgid/default ACLs govern
inheritance; Notarius does not copy parent literal mode bits, manage accounts/
groups, or chmod/chown old entries. If existing access is unsuitable, operators
can recreate reconstructible state beneath provisioned parents or deliberately
perform an administrative migration.
Cache publication remains atomic and stored records remain validated. Those
guarantees do not add cross-process locking or transactional coordination for
simultaneous writers to one checkpoint identity.
Output bundles can also contain source content when JSON output enables
evidence publication. Apply an appropriate umask and output-root access policy
before enabling that option; the requested output modes alone may not be
suitable for transcript-bearing bundles.
Cache, outputs, and evidence excerpts may contain source-derived data. Select
access and retention accordingly; requested modes alone are not a sharing policy.
Existing confined-path, symlink, atomic-write, and validation boundaries do not
promise cross-process transactions or power-loss durability.
## PromptKit Profile Deployment
Profile deployment has four distinct layers:
One selected application load includes bundled provider resources, embedded
Notarius resources, main-relative operator companions, imports, and an optional
overlay. Resource replacement/inheritance and source origins are defined in
[Configuration](config.md#promptkit-profiles).
| Layer | Owner | Operational role |
| --- | --- | --- |
| Prompts and schemas | Notarius module families | Embedded request and structured-output definitions. They are not deployment profile files. |
| Fallback profiles | Notarius module families | Embedded application defaults, including D&D's `dnd-extraction` profile. |
| Built-in profiles | PromptKit | Upstream catalog entries available when no higher-precedence source defines an ID. |
| Operator profiles | Deployment filesystem | Complete environment-specific definitions selected by `promptkit.profile_file` or `promptkit.profile_dir`. |
Preserve the [complete example's](../examples/dnd-complete/config.yml)
declaration-relative layout or deliberately update paths. Its
[companion](../examples/dnd-complete/prompts.yml) adds native profile/backend
variants; minimal needs no operator companion. Select qualified collection IDs.
Supply credential values through the intended environment, not files, arguments,
session IDs, or logs.
The maintained D&D pipeline uses the workload ID `dnd-extraction`. The
embedded fallback makes that ID usable without an operator file. Production,
development, and local deployments can each install a different complete
definition for the same ID, retaining the pipeline while choosing their own
model, backend, timeout, or reasoning policy. An operator definition wins over
the fallback; it is not merged with it. The configuration field and full
precedence rules are owned by [Configuration](config.md#promptkit-profiles).
Use a profile source owned by the service account, keep it readable only by
the intended operator, and supply provider credentials through the service
environment—not in the Notarius configuration or profile YAML. The maintained
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) is secret-free and
can be copied as a format starting point. Validate a deployment without a
provider call or credentials:
Review the deployment before model work:
~~~sh
notarius config validate --config /etc/notarius/config.yml --pipeline dnd-session
notarius config validate --config /etc/notarius/config.yml
notarius pipeline validate dnd-session --config /etc/notarius/config.yml
notarius config show --scope promptkit --config /etc/notarius/config.yml
notarius promptkit show profile notarius/dnd-extraction \
--config /etc/notarius/config.yml --format json
~~~
An unset optional `api_key_env` reaches the provider without authorization and
may receive a 401 or 403 response.
Offline preflight/inspection needs no credential values or provider calls.
Use sources/explain reports for provenance and prepared preview for rendered
request details. Profile inspection describes stored fields, not a completed
execution target. New invocations observe source edits; captured engines do not
reread configuration/message files. Schema/input reads occur during preparation.
Configured PromptKit profile paths resolve from the file that supplies their
surviving declaration. The complete example's
`./llm-profiles/dnd-extraction.yml` path is therefore relative to that example.
Use absolute paths such as `/etc/notarius/profiles/dnd-extraction.yml` for
services and containers when that is clearer for the deployment.
Reports can contain ordinary prompt/provider data. Secret-aware inspection and
native credential omissions do not make arbitrary content safe to share.
Operators select destinations, access, and retention when redirecting reports.
## Run Lifecycle
Use the [run command](cli.md#run) to start a pipeline. A valid invocation loads
and resolves configuration before module preparation and source parsing. It
then performs any permitted cache lookup, executes the pipeline, and publishes
logical output files only after a successful runner result.
A run loads configuration and obtains its identity. Requested capture allocates
before engine construction/preflight. The run resolves/preflights, materializes
references, prepares modules, parses source, performs chunk/lane work with
eligible reuse, encodes domain files, and publishes into a new run directory.
Requested capture finalizes before successful reporting.
On success, the command reports the output bundle path. A run with actionable
process warnings still succeeds and reports warning-group and occurrence counts
on standard error; advisory and observation findings do not produce a warning
line. Errors and
their exit classes are defined in the [CLI reference](cli.md#output-streams-and-exit-statuses).
Argument/configuration failures may have no capture. Later failures retain
available evidence. Publication, required capture, and presentation are separate
boundaries: later failure does not undo completed publication.
[CLI Reference](cli.md#completion-report) owns the completion value and outcomes.
## Validation Retries And Terminal Outcomes
### Acceptance And Fallback
When debug recording is enabled, per-call response artifacts include the
terminal execution summary for retry, repair, timing, and presence-aware usage
diagnosis. Normal output, receipts, and warnings do not aggregate or publish
this diagnostic metadata.
PromptKit owns transient retries and structural repair. Application semantic
continuation carries a growing conversation and assesses each usable candidate
through the complete chain, including the final allowed response. No outer
producer/validator retry loop extends native budgets.
Each producer binding has one outer **retries** budget. It covers complete
producer attempts for operational failures, invalid structured output,
normalizer fallback retry, and semantic correction. It is independent from
PromptKit's structural-repair calls inside one completion, its configured
`promptkit.transient_retries` built-in HTTP attempts, and an LLM-backed
validator's own retry budget. The transient setting defaults to two additional
attempts for eligible provider statuses; set it explicitly to zero when an
operator needs one HTTP attempt per generation. A semantic correction rebuilds
the ordinary producer request and supplies only the latest rejected model
response plus aggregated validator guidance; it is not a conversation replay.
Explicit permissive handling may publish a supported qualified fallback, not
ordinary semantic acceptance. Construction still checks intrinsic artifact,
source, and downstream invariants. Failure to construct fallback fails normally;
cancellation never initiates it. D&D scene planning can fall back to one
whole-source chunk, preserving coverage without promising bounded downstream
request size.
These budgets multiply only by their declared scopes. With two outer producer
retries, two transient retries, and one structural repair, a single producer
can issue up to 18 HTTP attempts: three producer attempts, each with an initial
generation and one repair generation, each allowing three HTTP attempts. This
is an illustration, not a total-deadline or exactly-once guarantee. Every
built-in HTTP attempt has its own generation timeout; caller cancellation
remains the overall authority and interrupts Retry-After waiting. The shared
Notarius scheduler keeps its permit through those waits, so retry budgets can
increase latency and provider cost. Observed usage can remain incomplete when
providers omit accounting fields.
Fallback and actually affected consumers skip cache lookup/storage; unrelated
accepted predecessors remain reusable. The report discloses emitting operations
even when warnings are hidden; affected files and validator calls are not extra
fallbacks. A hit does not establish fresh acceptance under changed policy.
Consumers needing new inference/assessment deliberately choose bypass/refresh.
After the applicable budgets are exhausted, the resolved
[`validation_policy`](config.md#pipelines) determines the result. Structural
failure and semantic rejection normally fail the run; an explicit
`reject_output` records a rejection and allows unrelated work to finish. A
validator execution failure normally uses `warn_continue`, which keeps an
otherwise accepted result in the current run with `incomplete` validation
provenance. It emits one bounded warning for every validator whose execution
budget was exhausted. A corrected result that later passes validation does not
retain diagnostics from abandoned attempts.
Treat a successful process exit as a completed run, not as proof that every
candidate was fully validated. Inspect the receipt's `validation_status`,
`validation_summaries`, rejection count, and warning group and occurrence
counts when an orchestrator requires complete validation. The durable fields
and their meanings are owned by the
[run-result receipt](integrations/run-result.md) and
[published JSON output contract](integrations/json-output.md).
Process warnings retain native visibility; quality advisories are not promoted
to warnings. [Configuration](config.md#producer-controls) owns selected modes,
turn allowances, defaults, and precedence.
## Output Bundles
Each successful run receives a generated safe run identifier and writes beneath:
The encoder defines [logical artifact files](integrations/json-output.md);
the CLI places them beneath the run directory. It checks paths before allocation
and refuses an existing destination without changing it. Individual writes are
atomic, not an all-files transaction. A later write failure can leave a partial
new directory for inspection.
~~~
<output-root>/<run-id>/
~~~
Artifacts are deliverables, not an index, manifest, persisted receipt, or reporting
sidecar. Read configured lane and auxiliary paths beneath the successful report's
directory; do not scan for the newest folder.
The [JSON output contract](integrations/json-output.md) owns the logical files
and their schemas. Before creating the run directory, Notarius validates every
logical output path. It refuses an existing run directory without changing it.
Files are written atomically; if a later write fails, the newly created partial
run directory remains for inspection and is never removed automatically.
Capture/report failure can occur after publication. The command returns nonzero
with available locations; valid artifacts are not removed or regenerated.
Failed stdout can be partial. Do not treat it as a success report or assume a
failed publication directory is complete.
Treat an output bundle as durable user data. Do not use cache-cleanup policy to
remove it. An optional accepted chunk map is also durable output and can carry
source- or model-derived annotations; its content and compatibility contract
are defined in [Accepted Chunk Map](integrations/chunk-map.md). An optional
[evidence context](integrations/evidence-context.md) contains source-unit text
and metadata. It is not a cache or debug artifact: retain it with the output
bundle only for as long as consumers need it, and apply source-content access
controls to the entire bundle. Its selected source-unit excerpt may include
every source unit once when coverage is broad or its configured window is
large, so do not assume a byte or token reduction or reduced sensitivity.
Output is durable user data. Optional [chunk maps](integrations/chunk-map.md)
and [evidence context](integrations/evidence-context.md) are output, not cache/
debug. Evidence can cover every source unit and is not promised smaller or less
sensitive; retain/share it according to consumer needs.
## Chunk-Plan Cache
## Accepted-Result Cache And Recovery
Chunk plans live beneath the selected chunk-plan root:
The cache stores final accepted typed artifacts, including applied normalization,
and accepted LLM chunk plans, not native responses, conversations, or execution
ledgers. Cheap deterministic work runs normally.
~~~
<chunk-plan-root>/<source-sha256-hex>/plan.json
~~~
The key is the initial native prepared `MessageContentHash`, unchanged through
correction. Matching ordered roles/text/boundaries can reuse final acceptance.
Model, session, schema metadata, policy, and implementation add no dimensions;
text actually rendered into messages participates. Use refresh/bypass when a
model or policy experiment needs new inference/assessment.
One validated canonical plan is active for each source digest. The plan stores
boundaries and provenance, not a second copy of the entire source. This
source-addressed policy is recorded in [ADR-0005](adr/0005-cache-canonical-chunk-plans-by-source.md).
Hits perform ordinary codec/current-source usability checks without semantic
reassessment, provider calls, or historical usage claims. Plans rematerialize
against the current source. Source identity alone no longer selects a canonical
partition; changed initial content can select different boundaries.
The configured cache mode controls one invocation:
- **auto** looks for a valid active plan. Missing or invalid state causes a new
plan to be generated; an accepted new plan is atomically published.
- **refresh** skips lookup, generates a plan with the configured chunker, and
atomically replaces the active plan after it is accepted.
- **bypass** performs no chunk-plan cache I/O. It does not resolve or create a
chunk-plan root.
A reused plan is still materialized and validated against the current source.
If a prior plan no longer gives acceptable results, use a refresh run rather
than editing cache files. Deleting a plan is recoverable but can repeat costly
chunking work. A plan accepted only under incomplete validation is not
published, and a rejected cache hit falls through to ordinary generation rather
than becoming a correction candidate.
## Checkpoint Recording, Resume, And Recompute
Checkpoint recording is an explicit configuration choice and is disabled by
default. When enabled, each run records stage transitions and the state needed
for compatible recovery. A run records checkpoints even when it does not ask
to reuse them. Checkpoint payloads can contain source-derived and intermediate
application data, so treat the entire root as sensitive.
Checkpoint loading is separate: [**--resume**](cli.md#run) asks a run to reuse
compatible recorded work. A resume request fails when checkpoint recording is
disabled. Without **--resume**, a recording-enabled run executes normally and
does not load checkpoint state. Compatibility includes the resolved pipeline,
input, selected lanes, runtime overrides, reference provenance, LLM-profile
provenance, the effective PromptKit profile-source fingerprint, and
prepared-component fingerprints. When a local PromptKit backend is configured,
compatibility also includes a non-secret fingerprint of its endpoint. Changing
profile content or the local endpoint causes a cold miss; changing only the
local concurrency limit does not. A changed identity produces a cold miss;
Notarius does not migrate, rewrite, or delete older checkpoint directories.
Reasoning-effort inheritance, replacement, and explicit clearing are distinct
runtime identities, so checkpoints created under one state are not reused by
either of the others.
Only accepted, completely validated chunk, extract, merge, and normalize
results are checkpointed for reuse. Rejected, structurally invalid, and
validation-incomplete producer results remain non-reusable, even when a
`warn_continue` result advanced during its original run. A resumed invocation
therefore reruns that producer rather than treating degraded state as accepted.
Checkpoint state is confined below an identity-specific path:
~~~
<checkpoint-root>/<pipeline-id>/<input-key>-<source-or-input-digest-prefix>/<pipeline-digest-prefix>/<identity-digest-prefix>/
~~~
### Selective Recompute
[**--recompute-step**](cli.md#run) requires both **--resume** and enabled
checkpoint recording. It forces the selected ordered step and every lane that
depends on it through generated artifact references. Unrelated lanes remain
eligible for reuse.
For an earlier producer required by a forced consumer, Notarius requires a
compatible accepted normalized artifact. It validates that artifact before
hydrating it and does not silently rerun the producer. If that state is
missing, rejected, corrupt, non-canonical, or incompatible, the run stops
before its dependent starts. Rerun the required producer deliberately instead
of copying or editing checkpoint files.
## Checkpoint Decisions And Recovery
Checkpoint events classify work as **executed**, **reused**,
**forced_recompute**, or **dependency_invalidated**. Their stable reason codes
are written to run diagnostics and provenance. Use the code, not a copied
error message, to decide what to repair.
| Reason code | Recovery meaning |
| Mode | Recovery behavior |
| --- | --- |
| **loading_disabled** | This invocation did not permit checkpoint loading. |
| **checkpoint_missing**, **checkpoint_path_invalid**, **checkpoint_read_failed**, **checkpoint_decode_failed** | The stored checkpoint could not be located or read safely; normal resume work can execute again. |
| **workspace_schema_incompatible**, **identity_mismatch**, **stage_mismatch**, **step_mismatch**, **lane_mismatch**, **module_mismatch** | Stored state belongs to a different compatible scope or identity; allow a fresh run to create new state. |
| **status_not_reusable** | The recorded operation did not end in reusable state. |
| **dependency_mismatch** | A dependency changed; dependent work is invalidated rather than reused. |
| **artifact_payload_invalid**, **artifact_digest_mismatch**, **artifact_codec_incompatible**, **artifact_not_canonical** | A stored artifact cannot safely be hydrated; rerun the producer instead of modifying the cache. |
| **checkpoint_reused** | A normal checkpoint passed compatibility checks. |
| **accepted_artifact_reused** | A required predecessor's accepted normalized artifact was safely hydrated. |
| **recompute_step** | Selective recomputation deliberately forced this work. |
| `auto` | Read accepted entries; execute misses and store final acceptance. |
| `bypass` | Neither read nor write; no cache directory creation. |
| `refresh` | Skip reads and replace only after new acceptance. |
Reason detail is bounded code-owned text. It is diagnostic information, not a
path-discovery or data-recovery mechanism, and does not contain checkpoint,
source, reference, credential, or environment content.
[Configuration](config.md#producer-controls) owns precedence. No mode overrides
eligibility: failure/rejection/incomplete/canceled/fallback results are not stored.
Failed refresh preserves previous acceptance. Fallback incompleteness excludes
actual dependent work, not unrelated siblings.
Missing entries are ordinary misses. Unreadable, malformed, or unusable entries
miss with diagnostics. Cache I/O failures warn without failing otherwise successful
work or repeating model calls. Artifact encoding, required capture, and invalid
configuration remain their own failure boundaries.
After fixing failed work, rerun normally: accepted predecessors and the chunk
plan can be reused while unsuccessful work executes. There is no resume request
or checkpoint barrier. Refresh obtains new acceptance; bypass isolates an
invocation without updating cache state.
### Legacy State
Legacy checkpoints and source-keyed chunk plans remain ignored and untouched,
even below the new root. They do not supply content keys. No automatic import,
conversion, rewrite, permission migration, or deletion occurs. New entries
populate through eligible execution. Operators may retain/clean obsolete data
deliberately; see [migration guidance](consumers/native-migration.md).
## Debug Bundles
Only a [debug-enabled run](cli.md#run) creates a bundle:
Capture needs explicit selection and a nonempty effective destination.
Directory configuration alone does not enable it. Explicit empty disables it;
a nonempty invocation override can re-enable it. [Configuration](config.md#file-shape-and-defaults)
owns defaults/origins; [CLI Reference](cli.md#run) owns mode ordering.
~~~
<debug-root>/<run-id>/
summary/
trace/
~~~
Allocation creates the run directory and updates `latest` to a relative link
at session start. It reflects the last successful start link update, including a
run that later fails. Completion never retargets it. Concurrent starts retain
separate directories; disabled capture leaves the link untouched. This link is
not an output-discovery API.
The summary contains redacted invocation and resolution information, including
`effective-config.yml` and the separately redacted resolved pipeline, plus run,
final grouped diagnostic, checkpoint, chunk-plan, and terminal reporting artifacts. Attempt
terminal records contain bounded attempt kinds, validator outcomes, policy,
decision, PromptKit repair count, and usage; they do not contain assistant
responses or complete correction messages. The trace contains allowlisted
application diagnostic records and can include source, model, and correction
content. Neither surface is a cache input. Do not treat a debug bundle as safe
to share merely because its configuration summary is redacted. Invocation
metadata omits reasoning effort when it is inherited, records the replacement
value when one is supplied, and records an empty value when inherited reasoning
was explicitly cleared. It records `config_overlay` only when a non-base
configuration overlay was selected.
One recorder writes available evidence incrementally: configuration/composition,
parsed source/fixed inputs, prepared contracts, native events/results/full
exchanges, typed candidates/findings, correction/normalization material, fallbacks,
and cache decisions. Hits can retain prepared/current artifact evidence without
invented executions. Unknown usage stays unknown. Result-less failures retain
available facts; undelivered responses are unassessed.
Notarius never creates debug state without an explicit request and never
automatically deletes a requested bundle. If allocation succeeds, the command
reports its path on both success and later failure. A summary, trace, or
terminal-report persistence failure fails the command while preserving any
already-written diagnostic data for inspection.
Exact files, nesting, and serialized shapes are private diagnostic choices,
not public contracts or exhaustive provider transcripts. Debug never prepares
or executes another request just to capture it.
Requested capture is required work. Allocation/link failure stops before model
work, recording errors surface at normal boundaries, and finalization failure
fails the invocation even after publication. Available evidence and primary/
additional causes remain; capture failure never retries a model or deletes data.
Bundles can contain full source, reference, prompt, response, and intermediate
data. Preserve marked-secret/native credential omissions, without assuming
sanitized content: arbitrary application text is not heuristically scrubbed.
Operators own access, sharing, and retention as for other application data.
## Cleanup
Cleanup is manual and destructive. First inspect the exact leaf directory,
then remove only that leaf; do not use a glob or a parent root as the target.
Inspect exact targets and coordinate with active writers before administrative
cleanup. Prefer moving evidence aside or recoverable removal where practical.
Target only intended run directories or entries, not globs or broad workspace,
home, or root directories.
~~~
rm -rf -- /srv/notarius/output/run-1721300000000000000-0123456789abcdef0123456789abcdef
rm -rf -- /srv/notarius/chunk-plans/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
rm -rf -- /srv/notarius/checkpoints/example/seriatim-0123456789abcdef/0123456789abcdef/0123456789abcdef
rm -rf -- /srv/notarius/debug/run-1721300000000000000-0123456789abcdef0123456789abcdef
~~~
Deleting output permanently removes user data. Deleting chunk plans or
checkpoints is recoverable but may repeat expensive provider or pipeline work.
Deleting a debug bundle removes troubleshooting evidence and a retained copy of
application data. Notarius has no cache garbage collector, rollback operation,
or automatic cleanup command.
Output deletion loses user data. Cache deletion is reconstructible but may repeat
expensive work. Debug deletion loses evidence and retained application data;
account for its `latest` link when managing old sessions. Notarius supplies
no automatic retention, cache migration, or collection command.
## Operational Limits
Provider execution settings and the generation timeout come from the selected
PromptKit profile. The invocation-only **--reasoning-effort** and
**--clear-reasoning-effort** controls may replace or clear that profile setting
for all LLM-backed calls in one run without changing the profile. PromptKit
also retries eligible transient HTTP failures with its built-in default
of two additional attempts per generation. This retry work is separate from
structural output repair, which happens within one structured-completion call. Its
effective `structured_output_repair_attempts` limit is resolved from the
selected binding, then the pipeline, then the prompt declaration; see
[module bindings](config.md#module-bindings-and-validators). This is distinct
from Notarius binding **retries**, which rerun the complete module operation
and validation chain and do not consume or replenish the structural-repair
limit. The maintained production prompts declare one repair attempt, paid only
after a structural failure. One structured completion with repair budget **R**
contains at most **R + 1** serial generations. Each generation can now contain
more than one provider call when PromptKit retries an eligible transient
failure. LLM-backed validators have their own corresponding invocation and
repair budgets. These are bounds on attempted work, not a promise that every
call reaches a provider.
Choose caller deadlines and native execution settings for the workload.
Cancellation remains authoritative; native timeout/capacity/provider failures
are not interchangeable with caller cancellation. Retry, repair, and continuation
can increase latency/cost without promising old-wrapper attempt parity.
Timeouts are layered. Caller cancellation is the outer authority. A positive
effective generation timeout adds an inner request deadline to each built-in
generation attempt, while zero disables only that generation deadline. The HTTP
client timeout remains a transport-wide cap. Notarius does not add another
timeout around PromptKit. Retries and repairs are serial within the same caller
context, so their worst-case latency and cost can exceed the structural-repair
bound above; provision run deadlines and provider budgets accordingly.
Credentials remain optional unless the selected
PromptKit profile requires one, in which case preparation fails before a
provider call when its configured credential is unavailable.
The pinned upstream boundary and profile-format links are in
[PromptKit Integration](integrations/pkg-promptkit.md).
Workers bound ready jobs; native engine/backend admission governs configured
backend capacity independently. There is no global cross-backend scheduler or
second admission queue. Nested assessment does not hold a completed producer's
native permit. Endpoint-only/unlimited backends gain no inferred application
backend limit. Capacity failure follows producer mode without another backoff.
Concurrency has two independent layers. Notarius **total_llm** defaults to 16
and is the application-wide provider-call limit shared by all backends,
modules, retries, and validators. PromptKit may impose a narrower admission
limit for the selected backend. The effective active-generation bound is the
intersection of the Notarius limit, any PromptKit backend limit, and work made
available by the pipeline. Built-in OpenRouter profiles use PromptKit's
upstream backend limit; endpoint-only profiles have no PromptKit backend limit
and remain bounded by Notarius. For the configured local backend, a zero
**concurrency_limit** leaves only the Notarius scheduler as a call limit. A
positive value makes the effective active local-generation bound the smaller
of **total_llm** and that local limit, so a local limit of four permits no more
than four active local generations.
The Notarius scheduler admits one logical structured completion and holds that
permit while PromptKit performs its serial corrective calls. PromptKit applies
its selected-backend admission to each provider call; Notarius does not
reacquire a permit or add another scheduler for a repair.
For a positive local limit, PromptKit owns its default waiting capacity and
admission behavior. When a PromptKit backend has admitted all active and queued
work, a new call fails as capacity exhaustion before generation. The adapter
maps that failure to Notarius's existing provider-neutral capacity error and
does not retry it. The calling stage's configured retry policy applies
normally, and the run fails if those attempts are exhausted. Caller
cancellation remains authoritative. Configuration contracts are documented
under [PromptKit profiles](config.md#promptkit-profiles) and
[concurrency](config.md#concurrency-output-cache-and-debug). Extract-worker
limits and actual provider-call limits are independent. Notarius writes local
filesystem state only; remote storage, archival, and retention automation are
outside the implemented CLI.
Every run has an effective prompt session used for provider routing and run
provenance. The generated default is stable for the same input module and raw
input bytes; use [**--session-id**](cli.md#run) only when intentionally grouping
different invocations. Both generated and explicit values can be visible to
providers, manifests, checkpoints, and requested debug bundles. Do not put
credentials or other secrets in an explicit session identifier; command-line
values are not a credential mechanism.
Sessions are provider-visible routing correlations, not secrets. Their default
and override semantics belong in [CLI Reference](cli.md#run-wide-llm-overrides).
State is local filesystem data; remote storage, archival, retention automation,
live model-quality guarantees, and release publication are outside this workflow.

View File

@@ -11,14 +11,14 @@ Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## ConfigKit
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.4.2`.
Selected module: `go.maximumdirect.net/configkit` at `v1.4.0`.
Copyright (C) 2026 Eric Rakestraw
@@ -26,103 +26,39 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/LICENSE).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f).
## PromptKit
Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.11.2`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/12d6d80024e80c552d122a076c22429bf6f2f6c2).
## PromptKit OpenRouter Catalog
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2` at `v2.20260926.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/4f731d217e0bc39151c010f50fb5912706e7b6b3).
## PromptKit Rakestrawhome Catalog
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2` at `v2.20260926.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/48918a3ad39fd99843cda94a86133b1b3881d596).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3).
## jsonschema
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2`.
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE).
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/commit/29cbed948d24a04700eb94436416b18a07953b71).
[Source](https://github.com/santhosh-tekuri/jsonschema/commit/b0fc661f4939578bc429f408c18202573dbafcc4).
## Go text
Selected module: `golang.org/x/text` at `v0.40.0`.
Selected module: `golang.org/x/text` at `v0.44.0`.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/golang/text/blob/724af9c35838492dcaacc1ac51a8a0187c994c54/LICENSE) |
[PATENTS](https://github.com/golang/text/blob/724af9c35838492dcaacc1ac51a8a0187c994c54/PATENTS).
[LICENSE](https://github.com/golang/text/blob/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://github.com/golang/text/blob/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
[Source](https://github.com/golang/text/commit/724af9c35838492dcaacc1ac51a8a0187c994c54).
## go-yaml v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1`.
Copyright (c) 2006-2010 Kirill Simonov
Copyright (c) 2006-2011 Kirill Simonov
Copyright (c) 2011-2019 Canonical Ltd
Copyright 2011-2016 Canonical Ltd.
SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT-Kirill-Simonov.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[Source](https://github.com/go-yaml/yaml/commit/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[Source](https://github.com/golang/text/commit/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -134,7 +70,104 @@ SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT-Kirill-Simonov.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/commit/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/commit/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## PromptKit
Selected module: `go.maximumdirect.net/promptkit` at `v0.24.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5ea60e9b96651fd7dfcbc7d05b6f43d131df358f).
## CommandKit
Selected module: `go.maximumdirect.net/commandkit` at `v0.7.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4).
## CommandKit ckconfig
Selected module: `go.maximumdirect.net/ckconfig` at `v0.10.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/eedbd83e7ea7be6a626755a63595f512ccd6fd15/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/eedbd83e7ea7be6a626755a63595f512ccd6fd15/integrations/ckconfig/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/eedbd83e7ea7be6a626755a63595f512ccd6fd15/integrations/ckconfig).
## CommandKit ckprompt
Selected module: `go.maximumdirect.net/ckprompt` at `v0.11.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/54e951e38a404b4338c7967ac39c6c01159bf76d/integrations/ckprompt/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/54e951e38a404b4338c7967ac39c6c01159bf76d/integrations/ckprompt/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/54e951e38a404b4338c7967ac39c6c01159bf76d/integrations/ckprompt).
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.2`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.1.0`.
Copyright (c) 2012 Alex Ogier. All rights reserved.
Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).
## mousetrap
Selected module: `github.com/inconshreveable/mousetrap` at `v1.1.0` (transitive dependency).
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/inconshreveable/mousetrap/blob/4e8053ee7ef85a6bd26368364a6d27f1641c1d21/LICENSE).
[Source](https://github.com/inconshreveable/mousetrap/tree/4e8053ee7ef85a6bd26368364a6d27f1641c1d21).

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
## Purpose

View File

@@ -2,9 +2,12 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-22
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
The source above identifies the adopted baseline. Local native-kit architecture
decisions below are repository adaptations, not a new upstream policy adoption.
## Purpose And Ownership
@@ -12,20 +15,20 @@ The adopted policy defines the application's purpose and the architectural
constraints contributors must follow. It owns system boundaries, responsibility
and dependency rules, established invariants, and explicit non-goals.
Describe the concrete package inventory and implementation mechanics in internal
documentation. Link to canonical public contracts for their exact behavior and
to ADRs for decision rationale.
Describe concrete package inventory and implementation mechanics in internal
documentation. Link to canonical public contracts for exact behavior and to
ADRs for decision rationale.
## Architectural Approach
Hexagonal architecture is strongly recommended, including encapsulating external
integrations and APIs within internal adapters. Keep domain and application
logic independent of external integration details, and make dependency direction
clear in the adopted policy.
Hexagonal architecture is strongly recommended. Keep pure domain logic independent
of external integration details and make dependency direction clear. Native kit
types are an intentional contract for model execution, configuration composition,
and CLI presentation; do not hide them behind a replacement completion API.
Implement that separation with proportionate, idiomatic code. Choose interfaces
and package layout to serve the application's actual boundaries. Use adapters
for collaborators with external integration responsibilities.
Implement separation with proportionate, idiomatic code. Choose interfaces and
package layout to serve demonstrated boundaries. Use adapters where they serve
an integration need, not merely to rename an adopted library's public types.
## Adopted Constraints And Implemented Structure
@@ -38,16 +41,19 @@ Constraints must reflect deliberately selected requirements and decisions.
Do not promote incidental implementation choices into architectural invariants.
Notarius's fixed pipeline, artifact-family boundaries, and deployment-owned
cache permissions are established product decisions. The linked ADRs retain
their rationale; the [internal overview](../internal/overview.md) inventories
their implementation.
cache permissions remain established product decisions. Successor ADRs
[0021](../adr/0021-compose-native-kits-and-prompt-declared-resources.md),
[0022](../adr/0022-use-native-continuation-and-application-assessment.md),
[0023](../adr/0023-unify-accepted-artifact-and-plan-caching.md), and
[0024](../adr/0024-publish-artifacts-with-native-reports-and-debug-evidence.md)
record the native cutover. Earlier accepted bodies remain historical decisions,
with status links identifying superseded portions.
## System Shape
Notarius is a small, dependency-light Go application for extracting structured
artifacts from source material. It is a general extraction platform whose
source formats, extraction domains, validation policies, LLM providers, and
output formats are isolated behind explicit boundaries.
Notarius is a Go application for configured structured extraction workflows.
Source formats, artifact domains, validation, and output encoding remain explicit
boundaries.
The application has one fixed pipeline shape:
@@ -55,337 +61,310 @@ The application has one fixed pipeline shape:
input -> chunk -> extract -> merge -> normalize -> output
```
Pipelines are configured compositions of this shape. They are not arbitrary
DAGs or a general workflow language. Every stage remains explicit; general
chunking, merging, or normalization behavior must not be hidden inside an
extractor.
Pipelines are configured compositions of this shape, not arbitrary DAGs or a
general workflow language. Every stage remains explicit; chunking, merging, or
normalization must not be hidden inside an extractor.
A stage module is one configured implementation of one pipeline stage. An
artifact family is the cohesive domain feature that owns an artifact across
the explicit stages and supporting codecs, validators, prompts, identity
rules, and reference projections. Artifact-family ownership does not combine
stages or alter the fixed pipeline.
A stage module implements one pipeline stage. An artifact family owns a cohesive
domain feature across its stages, codecs, validators, prompts, identity rules,
and reference projections. Family ownership does not combine stages.
Input and chunking are pipeline-wide. Each selected artifact lane owns its
extract, merge, and normalize stages, and the output stage aggregates the run's
lane outcomes.
extract, merge, and normalize stages. Output aggregates the run's domain results.
Ordered steps support generated references without changing the fixed shape.
Notarius is contract-first without being abstraction-heavy. Interfaces and
extension points should protect demonstrated boundaries. New abstraction is not
itself an architectural goal.
Implementation discipline is owned by [Agent Policy](agents.md).
Notarius is contract-first without being abstraction-heavy. Extension points
protect demonstrated boundaries; new abstraction is not itself an architectural
goal. [Agent Policy](agents.md) owns implementation discipline.
## Layers And Dependency Direction
The application boundary is the composition root and may depend on concrete
implementations. Domain-neutral model and framework layers provide reusable
policy, contracts, and orchestration. Concrete input, pipeline, output, and
validation extensions depend inward on those generic layers.
The composition root may depend on concrete implementations. Domain-neutral
models and framework layers provide reusable contracts and orchestration.
Concrete input, pipeline, output, and validation extensions depend inward on
those generic layers. Generic layers must not depend on production extensions;
extensions must not compose the application or own process behavior.
Semantic reconciliation is one such domain-neutral framework mechanism. It
prepares bounded source context, invokes a shared model-judgment protocol,
validates proposals, and applies safe plans through typed policies supplied by
the consuming artifact family. It does not own domain identity, durable IDs,
warning semantics, or artifact construction rules.
Semantic reconciliation is a domain-neutral mechanism for fixed candidate
preparation, native request construction, proposal decoding, and safe typed
application. It does not own domain identity, durable IDs, warning semantics,
or artifact construction rules. Native execution uses the shared producer path.
Generic layers must not depend on production extensions. Concrete extensions
must not compose the application or take ownership of process behavior. The
current packages implementing these layers are inventoried in
[Internal Overview](../internal/overview.md).
The root `assets` package is a content-only dependency leaf. It may expose a
read-only embedded filesystem, but it must contain no business logic and must
not depend on `internal` packages or PromptKit. Consumers scope that filesystem
to the content they own; the root package is not a behavioral registry or a
public extension contract. The rationale and compatibility consequence are
recorded in [ADR-0011](../adr/0011-centralize-llm-assets.md).
The root `assets` package remains a content-only dependency leaf. It may expose
a read-only embedded filesystem but contains no business logic or dependencies
on internal packages or PromptKit. Native source assembly retains its filesystem
context; the package is not a behavioral registry or public extension contract.
This retains [ADR-0011](../adr/0011-centralize-llm-assets.md)'s content boundary.
The following dependency boundaries are mandatory:
- extractors and validators do not depend on concrete input adapters;
- provider-specific types do not cross the LLM runtime boundary;
- external dependency types do not leak across internal package boundaries
unless that dependency is the package's explicit contract.
- provider-specific transport and authentication remain inside PromptKit;
- model-executing framework code, modules, and validators use native PromptKit
requests, results, exchanges, errors, and observations directly;
- pure domain types, codecs, reference resolution, and deterministic helpers do
not acquire PromptKit dependencies merely because surrounding producers use it;
- other external dependency types cross internal boundaries only where that
dependency is an explicit contract.
Shared helpers may support demonstrated common needs, but must not move
source-format or extraction-domain knowledge into generic framework packages.
External dependencies require a clear correctness, security, interoperability,
or complexity benefit.
Shared helpers support demonstrated common needs without moving source-format
or domain knowledge into generic packages. Dependencies require a clear
correctness, security, interoperability, or complexity benefit.
[Internal Overview](../internal/overview.md) owns the concrete package inventory.
## Source And Domain Boundaries
Input modules translate external source formats into the generic source model.
Format-specific schemas, fields, and validation remain with the input module
and its integration contract.
Input modules translate external formats into generic source documents, units,
and references. Format-specific fields, schemas, and validation remain with the
input module and its integration contract.
Framework stages operate on source documents, source units, and source
references rather than format-specific structures. A source reference identifies
an ordered range of generic source units. Framework code preserves those ranges
and does not merge or rewrite them unless a stage module explicitly owns that
behavior. Every source unit carries a validated self-reference to its containing
document and its own unit ID.
A source reference identifies an ordered range of generic units. Framework code
preserves ranges unless a module explicitly owns their transformation. Every
source unit carries a validated self-reference to its document and unit ID.
Auxiliary references provide context or disambiguation, not source evidence;
they must not be converted into source references.
Extract modules own artifact semantics, prompt use, response schemas, and
domain interpretation. Domain-specific concepts remain in the relevant module,
validator, shared domain helper, and artifact contract.
Modules own domain semantics, prompt selection, interpretation, deterministic
identity, and supported fallback construction. Physical asset centralization does
not transfer semantic ownership. Native prompt declarations own default output
contracts and schema selections; PromptKit prepares schemas and performs
structural validation and repair. Modules declare small static resource
dependencies for preflight, not manifests, schema registries, or fingerprints.
Intrinsic durable artifact schemas remain application contracts.
Physical centralization of LLM-facing content does not transfer semantic
ownership from those modules. Modules retain their manifests, response-schema
identities, prompt ordering, and registration, while reading only their scoped
content subtree. Generic framework code remains domain-neutral when it reads
its own scoped generic assets from the shared content container.
Typed artifact registrations declare one stable kind and exact Go type through
extraction, merge, normalization, and semantic validation. Resolution requires a
compatible codec and matching kind-specific variants. Private framework erasure
reports incompatibility as an error rather than a panic.
Typed artifact registrations declare one stable artifact kind and exact Go
type from extraction through merge, normalization, and semantic validation.
Pipeline resolution requires a compatible codec and matching kind-specific
variants before a typed lane can be accepted. Framework-owned erasure remains
private and must report type incompatibility as an error rather than a panic.
A kind may provide a typed evidence projection copying direct generic source
references. Preparation proves its exact codec-type compatibility. Evidence is
reconstructed from serialized normalized artifacts, including supported fallbacks,
without generic code inspecting domain JSON or importing domain types. The output
boundary owns publication.
An artifact kind may additionally provide a typed evidence projection that
copies its direct generic source references. Preparation proves that projection
matches the artifact codec's exact Go type before retaining it for an output
policy. The runner reconstructs evidence only from accepted serialized
normalized artifacts, and the output boundary owns any resulting publication.
Generic framework code never infers evidence by inspecting domain JSON or
depends on domain artifact types.
Auxiliary references provide context or disambiguation. They are not source
evidence and must not be converted into source references.
When a model selects an entity, modules supply contextual selections and attach
opaque application IDs deterministically after exact resolution. Models do not
receive or reproduce opaque application IDs. Reconciliation may expose
request-local candidate handles, resolved before typed application and never
used as durable identity. Retain
[ADR-0012](../adr/0012-resolve-opaque-entity-identifiers-deterministically.md) and
[ADR-0013](../adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md)'s
identity and safety decisions.
## Pipeline Composition And Ownership
Module selection is configuration- and registry-driven. The framework resolves
named pipeline definitions, applies explicit defaults and runtime overrides,
and verifies module availability and capabilities before execution. Structural
pipeline choices must not be scattered through conditionals or hidden behind
ad hoc command flags.
Configuration and registries select modules, explicit defaults, references, and
runtime overrides. Validate selected module and validator options before
execution. Preparation constructs the complete implementation set; the runner
accepts only that prepared set. Construction failures precede source parsing.
Resolution validates every selected module and validator option set. A separate
preparation boundary then constructs the complete input, chunk, lane,
validation, and output implementation set in pipeline order. The runner accepts
only that prepared set, so construction and dependency failures occur before
source parsing or any other module operation.
Stage ownership remains explicit:
Stage ownership is explicit:
- input translates external material into the generic source model;
- chunk produces source-addressed plans;
- extract produces artifacts from chunks;
- merge combines extraction outputs;
- normalize reconciles merged output;
- output encodes domain results and enabled auxiliaries into logical files.
- input modules convert external material into the generic source model;
- chunk modules partition source material for extraction;
- extract modules produce domain artifacts from chunks;
- merge modules combine accepted extraction outputs;
- normalize modules reconcile merged output;
- output modules encode accepted results and run outcomes into logical files.
Chunk modules produce source-addressed chunk plans rather than materialized
chunks. The framework validates and materializes those plans into the generic
chunk representation before chunk validation and lane execution. Plan reuse is
therefore independent of the configured pipeline, module options, references,
lanes, validators, and LLM profile: the canonical source digest selects the
plan, while the current run still applies its configured chunk validators to
the materialized chunks.
The framework materializes plans into chunks before candidate assessment and
lane execution. LLM plans use the accepted-result cache; hits rematerialize
against the current source without new semantic assessment. Source identity alone
does not select a canonical partition. Deterministic chunkers execute normally.
The framework owns orchestration, origin enrichment, aggregation, and handoff
provenance. Modules return logical results and classified diagnostics; they do
not own CLI reporting, physical output, cache, or
debug roots, durable file placement, or checkpoint and debug lifecycle.
provenance. Modules return logical results and classified diagnostics, not CLI
reports, physical roots, durable placement, or capture lifecycle.
After pipeline-wide chunking, extraction uses bounded framework concurrency.
One run-wide worker pool receives chunk-scoped lane jobs in deterministic
chunk-first, lane-second order. A lane may begin its merge and normalize
continuation only after all of its extract jobs are terminal; that continuation
remains serial within the lane, while bounded continuations for different lanes
may overlap. The framework must not create unbounded goroutines per lane or
chunk.
After pipeline-wide chunking, one pool bounds ready extraction and ready
merge/normalize lane-completion jobs together. Extraction dispatch uses stable
chunk-first, lane-second order. A continuation becomes ready after its lane's
extraction finishes; a worker does not wait for prerequisites while holding a
slot. Validation and correction run inside the current job without another
worker acquisition. Ordered steps retain their barriers. Do not create unbounded
goroutines per lane or chunk.
Completion timing does not choose public ordering or errors. The coordinator
orders accepted artifacts, grouped diagnostics, rejections, checkpoint events, and
framework errors by stable pipeline scope. Rejections do not cancel unrelated
work. A framework error cancels derived work, prevents undispatched work from
starting, waits for started work, and prevents output encoding.
Completion timing does not choose public ordering or terminal errors. The
coordinator orders artifacts, grouped diagnostics, and errors by stable scope.
Cancellation stops dispatch, drains started work, and releases workers and native
admission before returning.
Warnings are process-only signals: configuration degradation, approved fallback,
or incomplete configured validation. Quality uncertainty and grounding findings
are advisories; successful canonicalization and cleanup are observations.
Modules choose that semantic classification, while the framework attaches
origin, aggregates groups, enforces bounds, and presents final collections.
An ordinary successful run therefore has zero warnings. See
[ADR-0015](../adr/0015-separate-process-warnings-from-quality-diagnostics.md)
for the decision rationale.
Warnings are process signals: configuration degradation, qualified fallback,
or incomplete configured work. Quality and grounding findings are advisories;
accepted cleanup is observation. Modules own classification, while the framework
adds origin and aggregates bounded groups. A non-degraded successful run has no
actionable warnings. Retain
[ADR-0015](../adr/0015-separate-process-warnings-from-quality-diagnostics.md)'s
classification decision, not its retired durable reporting contracts.
## Validation
## Validation And Disposition
Validation is a framework-managed boundary around outputs from chunk, extract,
merge, and normalize stages. Validators receive immutable stage output and
make an explicit whole-output decision: approve, reject, fail, or skip when a
runtime prerequisite is unavailable.
Validation is a framework-managed boundary around chunk, extract, merge, and
normalize candidates. Validators receive immutable views and return approve,
reject, fail, or unavailable findings. Typed validators receive domain values;
chunk validators receive generic chunks; serialized validators receive bytes
and schema metadata. Incompatible targets or kinds cannot substitute for one
another.
Typed artifact validators receive the domain value directly. Chunk validators
receive source-zone chunks, while serialized validators receive immutable
representation bytes and declared schema metadata. A validator registered for
one target or artifact kind cannot satisfy an incompatible selection.
Assess each usable initial or revised candidate once through every applicable
validator in configured order. Rejections do not short-circuit later validators.
Earlier approvals and unchanged revisions do not excuse reassessment; the final
allowed response also receives the whole chain. Cancellation or fatal framework
failures can interrupt assessment. There is no duplicate final assessment.
The framework runs every applicable validator sequentially in configured order.
It aggregates rejections, exhausted validator failures, and skips before the
producer policy chooses a disposition. A completed rejection never advances.
With no rejection, an exhausted validator failure may fail the run or, under
the configured `warn_continue` policy, advance a structurally valid candidate
with explicit incomplete-validation provenance. Validators report findings;
they do not choose candidate disposition.
Actionable correction guidance is distinct from reason codes, operator messages,
and failures. The detecting validator or module owns it. The pipeline aggregates
it in order; a native module template supplies the correction assignment. Missing
required guidance is a contract failure, not an invitation to invent instructions.
Unavailable assessment is not a semantic defect or ordinary acceptance.
A completed rejection supplies a stable reason code for internal provenance
and bounded actionable correction guidance for the candidate producer. Reason
codes, validator keys, and operator-facing messages remain diagnostic data;
they are not model instructions. The framework constructs model-facing retry
text only from the semantic guidance and fails the contract rather than
inventing or truncating missing guidance.
The producer's resolved mode owns terminal disposition. Strict requires
acceptance; explicitly selected permissive mode may construct a supported
fallback. A fallback must satisfy intrinsic shape and downstream invariants but
does not rerun the ordinary validator chain or claim semantic approval. Unsupported
or invalid fallback construction fails normally. Caller cancellation never
initiates fallback. Exact mode and turn controls belong in [Configuration](../config.md).
An LLM-backed module may also request a feedback-aware retry when its own
deterministic translation or typed safety policy rejects a structurally valid
model response. It must supply model-facing guidance separately from its
reason code, operator message, and fallback diagnostics, together with the
exact `single_response_v1` candidate. A feedback-free module retry remains
valid when no exact candidate exists.
Default validator chains remain central production composition policy.
Configuration can replace a stage-local default, including with an explicit empty
chain. Configured order is authoritative. Intrinsic codec validation, source
parsing, plan materialization, and necessary module/fallback/cache construction
checks remain. Ordinary artifact citation existence/containment checks depend on
the configured chain; see [validator configuration](../config.md#module-bindings-and-validators).
Default validator chains are production composition policy and are registered
centrally by stage and module. Configuration may replace a stage-local default,
including with an explicitly empty chain. Configured validator order is
authoritative; the framework must not silently reorder it.
## Native Execution Boundary
## LLM Boundary
The composition root constructs one shared native PromptKit engine from the
application's ConfigKit result. All model roles use that engine. PromptKit owns
transport, authentication, transient retries, structural validation and repair,
conversation history, turn iteration, and backend admission. Notarius does not
pin omitted native budgets or add outer retries to extend them. Deterministic
operations have no generic retry budget or synthetic model request.
Modules and validators use transport-neutral structured completion contracts.
Provider request and response types, authentication, transport behavior, and
provider error adaptation remain inside the LLM runtime.
One small typed producer helper connects module-owned fixed inputs, native
request builders, interpretation, and supported fallback functions with the
pipeline assessor. Initial/correction pairs use complete replacement responses
and the same declared schema. Enduring principles belong in initial system
context; correction supplies current findings and a new assignment. Native
coordination carries the growing exchange without manual response replay or
regeneration of original references. Normalization applies each proposal afresh
to fixed originals, without cross-turn unions.
The caller of the LLM owns prompt selection, prompt inputs, response schema,
and interpretation of structured output. Provider adapters do not own source-
or domain-specific prompt logic.
Check native errors and validation status before interpretation, including failed
validation with nil Go error. Native success, stopped, or exhausted status alone
does not establish domain acceptance. Do not recover an earlier candidate after
a result-less continuation failure or assess an undelivered response. LLM
validators execute once per assessment, without a separate semantic correction
loop. Calls respect cancellation and applicable native timeouts.
PromptKit owns bounded structural correction within one structured completion.
Notarius owns outer stage attempts, semantic validation, and acceptance policy;
the two budgets must remain separate.
An LLM-backed producer can participate in semantic correction only when it
declares `single_response_v1` and returns the exact one response that directly
controlled its candidate. On an actionable validator rejection or
feedback-capable module retry, the framework rebuilds the ordinary request and
appends only the latest defective response as an `assistant` message plus one
aggregated `user` correction message. This is a fresh replacement request, not
a growing conversation. The retry budgets, terminal policy, and sensitive-data
rationale are recorded in
[ADR-0014](../adr/0014-feedback-aware-validation-retries.md) and
[ADR-0016](../adr/0016-feedback-aware-module-requested-retries.md).
When a model selects an application entity, callers must supply a contextual
selection and deterministically attach the opaque application identity whenever
the selection resolves exactly. Models do not receive or reproduce opaque
application identifiers. Semantic reconciliation may instead expose
contiguous, one-based candidate handles that exist only for one request;
deterministic code resolves them before typed application, and they never
become durable identity. This is the approved request-local-label application
of [ADR-0012](../adr/0012-resolve-opaque-entity-identifiers-deterministically.md)
recorded by
[ADR-0013](../adr/0013-use-request-local-candidate-handles-for-semantic-reconciliation.md).
LLM calls and other external operations accept cancellation and respect
timeouts. Concurrency control belongs in shared runtime plumbing rather than in
individual modules.
The application-wide LLM scheduler bounds actual provider calls independently
of framework worker limits. Every LLM-backed module, retry, and validator uses
the single injected scheduled client, including work performed by overlapping
lanes. Provider runtime adapters may enforce a narrower backend-specific limit
beneath this mandatory application-wide scheduler.
Worker limits and native backend admission are independent. Profiles selecting
one backend ID share its engine capacity; different IDs do not imply an endpoint
limit. Notarius injects no backend concurrency/queue defaults and has no
cross-backend scheduler, second admission queue, or capacity retry loop. Completed
turns release admission before assessment so nested validators can use the same
limited backend. Native failures retain their causes and follow the producer's
mode; they do not become correction guidance.
## Configuration And Provenance
Configuration loading, precedence, defaults, redaction, and validation are
centralized through the ConfigKit-backed boundary. `NOTARIUS_CONFIG` is limited
to discovery; field-level environment overlays are not configuration input.
Named pipeline definitions make structural composition explicit and discoverable.
Explicit command overrides are permitted
when they do not obscure the configured pipeline structure.
ConfigKit owns loading, imports, composition, overlays, inheritance, source
contexts, provenance, and secret-aware inspection. Notarius owns application
meaning through supported definition rules and domain resolution, retaining
[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md).
`NOTARIUS_CONFIG` is discovery only; field-level environment overlays are not
application configuration. Named pipelines keep structural composition explicit.
Run preparation fails before stage execution when statically discoverable
modules, capabilities, reference bindings, or explicitly selected profiles are
invalid or incompatible.
One application-owned result supplies engine construction and whole-app/focused
inspection. Preserve source contexts and captured selection evidence rather than
reparsing settings or maintaining duplicate loaders. Request overrides retain
native supplied-value semantics. CommandKit, ckconfig, and ckprompt own standard
commands, parsing, presentation, and delivery outcomes. Notarius supplies domain
commands and report content, not a universal result envelope.
Run manifests record enough resolved pipeline, module, source, reference, and
LLM provenance to make a run auditable after configuration changes. Manifests
record identities and bounded validation summaries rather than secret, raw
model, correction, or large payload content.
Offline preflight shares domain resolution and checks statically known module,
reference, initial/correction/validator prompt, and applicable profile dependencies
before execution. It requires no transcript, reference bytes, credentials,
provider call, or run storage. Dynamic selections remain runtime checks.
Shared loaders allocate no run storage; capture belongs to the run path.
## Trust Boundaries And Threat Scope
Where useful, state the trust boundaries and threat scenarios relevant to the
application's adopted requirements, along with scenarios it explicitly excludes.
For example, distinguish handling untrusted application input from defending
against a privileged actor concurrently modifying the host filesystem.
Source material and model responses cross application validation boundaries.
Host access policy belongs to deployments. Hypothetical privileged actors
concurrently modifying the filesystem do not justify new application defenses
without an explicit decision. This does not remove adopted correctness boundaries
or claim excluded scenarios cannot occur. Raise new threats or guarantees under
[Agent Policy](agents.md).
Threat exclusions define the scope of the adopted requirements. Base defenses
and guarantees on those requirements and raise unsettled scope for a deliberate
decision under the [agent policy](agents.md).
Keep this discussion proportionate to the application. Configuration,
operations, and internal documents retain ownership of credential supply,
runtime handling, and implementation mechanisms under the documentation policy.
Configuration, operations, and internal documents own credential supply,
runtime handling, and mechanisms under [Documentation Policy](documentation.md).
## State, Output, And Safety
Source material and model responses cross application validation boundaries.
Host access policy belongs to the deployment; hypothetical privileged actors
concurrently changing the filesystem do not justify new application defenses
without an explicit decision. This scope statement does not remove the adopted
correctness boundaries below or claim excluded scenarios cannot occur. Follow
[Agent Policy](agents.md) when a new threat or guarantee needs a decision.
Output, cache, and debug retain independent roots and lifecycles:
Notarius exposes three filesystem surfaces with independent roots and
lifecycle:
- output is durable domain data; modules encode logical files and the CLI places them;
- cache is reconstructible accepted-artifact and LLM-plan state;
- debug is explicitly requested run/operation evidence, not a consumer API.
- output is durable user data; output modules define logical files and the CLI
owns their placement;
- cache is reconstructible state, with separate chunk-plan and checkpoint
families; and
- debug is explicitly requested inspection data, combining a redacted summary
with a detailed trace.
Cache identity is the opaque native initial prepared message-content hash.
Add no configuration, schema, model, session, implementation, or dependency
dimensions. Store only final accepted codec artifacts or materialized/assessed
plans, not responses, exchanges, proposals, provenance envelopes, or historical
usage. Hits perform ordinary decoding/source-usability checks without new
semantic assessment. Policy/settings changes may still hit; explicit
bypass/refresh controls re-execution. Deterministic work is not cached through
manufactured requests.
Chunk plans are keyed only by canonical source digest. Configured checkpoint
recording is independent of checkpoint reuse; checkpoints are loaded only for
an invocation that explicitly requests resume. Debug is never a cache input and
is never created without an explicit request. Pipeline modules receive
collaborator interfaces and never physical roots.
Fallback and affected dependent work skip lookup and storage; unaffected accepted
predecessors remain reusable. Refresh replaces an entry only after new acceptance.
Failure preserves an old entry. Cache I/O is best effort and cannot fail otherwise
successful work. Legacy caches remain unread and unmodified, with no checkpoint
resume, canonical source-only plan store, or automatic migration.
Deployments own cache access policy. Cache writers request conventional maximum
creation modes and let the process umask, setgid inheritance, and default ACLs
determine effective access. Notarius owns the separate safety boundary:
confined paths, symlink rejection, atomic publication, validation, and
recovery. It does not chmod, chown, chgrp, or migrate cache entries to impose
an application policy. This rule applies to chunk-plan and checkpoint cache
only; output and debug retain their separate contracts. [Operations](../operations.md)
owns deployment provisioning and retention guidance.
Deployments own cache access policy. Writers request conventional maximum modes
and let umask, setgid inheritance, and default ACLs select effective access.
Retain confined paths, symlink rejection, atomic publication, validation, and
recovery without chmod/chown/chgrp convergence or cache migration.
[ADR-0017](../adr/0017-defer-cache-access-policy-to-deployment.md)'s boundary now
applies to the unified cache; output and debug retain separate contracts.
Only accepted, completely validated producer output is reusable checkpoint or
chunk-plan state. Rejected, structurally invalid, and validation-incomplete
results cannot become cache or checkpoint inputs, even when a
`warn_continue` result is allowed to advance in the current run. This
ineligibility follows derived merge and normalize results and generated
references for the remainder of the run: current-run handoff remains allowed,
but no dependent cache or checkpoint may be loaded or published.
Preserve intrinsic domain payload schemas and logical paths, including supported
fallbacks. Consumers need no index, manifest, persisted receipt, or reporting
sidecar. Publish artifacts and finish capture before a native completion report.
Disclose fallback use independently of diagnostic verbosity. Delivery failure may
leave partial stdout and valid published artifacts; retain those artifacts,
useful locations, and distinct operation/delivery causes without model retries.
Exact report fields and outcomes belong in [CLI Reference](../cli.md).
Writes are atomic where practical. Paths for writes, moves, overwrites, and
deletion must be narrow and explicit. Notarius never automatically deletes
output or requested debug bundles; cache cleanup is explicit and recoverable.
One native execution group records actual initial, continuation, and nested
validator executions once. Preserve identity, terminal coverage, and
unknown-versus-zero usage without synthetic IDs, copied totals, or historical
execution claims on cache hits.
Secrets must not appear in errors, logs, output, cache, debug summaries,
traces, manifests, documentation, examples, or redacted configuration. Raw
assistant responses and complete correction messages are attempt-local and are
excluded from ordinary durable records and summaries; the requested detailed
debug trace is the sole diagnostic surface allowed to retain them. Debug
collection is allowlisted to application-owned payloads and must not capture
unrelated process environment values or filesystem content. Trace data may
contain application data and therefore inherits its sensitivity; operators own
access controls and retention. Physical layout and operation are defined in
[Operations](../operations.md).
Debug is never a cache input. Capture requires explicit enablement and a nonempty
effective destination; directory configuration alone does not enable it. Requested
capture is required work: allocate before engine construction/preflight, record
incrementally, and finalize once before successful reporting. Capture failures
fail the invocation while retaining available evidence and primary causes.
Update the relative `latest` link at session start, never completion.
Debug reuses prepared details and native evidence without another preparation/
model call or parallel conversation ledger. Representations are private
diagnostics, not stable serialization contracts or exhaustive provider transcripts.
Use ConfigKit secret-aware inspection and preserve native credential omissions.
Do not directly serialize marked secrets, unrelated environment, or unselected
filesystem content. Do not heuristically scan or rewrite source, prompts,
responses, or arbitrary application text. Selected evidence may contain full
source/reference data, responses, and exchanges; it is not a sanitized bundle.
Operators own access and retention as for other application data.
Writes are atomic where practical. Write, move, overwrite, and deletion targets
must be narrow and explicit. Never automatically delete output or requested debug
bundles. Cache cleanup remains explicit and recoverable.
[Operations](../operations.md) owns physical layout, provisioning,
retention, and recovery guidance.
## Platform And Distribution
@@ -404,7 +383,9 @@ Notarius does not aim to provide:
- an arbitrary workflow graph or general workflow language;
- source-format or extraction-domain behavior in generic framework packages;
- provider-specific contracts exposed to modules;
- provider-specific transport contracts exposed to modules;
- structural pipeline composition through ad hoc CLI flags;
- implicit cross-stage behavior that bypasses the fixed pipeline;
- replacement kit APIs, duplicated schedulers, or compatibility parsers;
- a public debug serialization format or mandatory execution ledger;
- abstractions introduced solely for hypothetical future complexity.

View File

@@ -1,10 +1,10 @@
# Documentation Policy
**Base Policy Version:** 1.11
**Base Policy Version:** 1.12
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
## Purpose
@@ -86,8 +86,8 @@ secret values.
| Integration contracts for external components (if applicable) | `docs/integrations/` | External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
@@ -153,8 +153,15 @@ Use sequentially numbered ADR filenames such as
Treat the decision content of an accepted ADR as immutable. When a decision
changes, create a new ADR and update the earlier ADR's status to superseded.
Rejected architectural alternatives belong in the ADR; rejected product ideas
belong in the roadmap.
ADRs should be reserved for major architectural decisions, such as ownership
boundaries, large-scale architectural features, or invariants that rise to
the level of architectural significance. Routine choices, implementation
decisions, and rejected suggestions do not warrant an ADR unless they
otherwise represent a significant architectural decision.
Roadmaps should preserve plausible future work, not rejected product
ideas.
## Maintenance

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.0
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
## Origin And Local Authority

View File

@@ -1,10 +1,10 @@
# Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8
**Base Policy Version:** 1.9
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
## Purpose And Scope
@@ -67,6 +67,9 @@ individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file.
Use the COPYRIGHT examples exactly as provided, except for placeholder
substitutions and changes expressly required or authorized by this policy or
the author.
Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant.

View File

@@ -1,10 +1,10 @@
# Release Policy
**Base Policy Version:** 1.4
**Base Policy Version:** 1.7
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-22
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
## Purpose
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents.
Adopt stronger verification or reproducibility requirements through an explicit
project-specific decision justified by the intended audience and support needs.
The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements.
@@ -52,9 +55,14 @@ requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`:
- a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior; and
- a minor release may add backward-compatible behavior or raise the Go consumer
minimum as described below; and
- a patch release may make backward-compatible fixes.
In this context, "backward-compatible" means only that pre-existing, valid
configurations will continue to work following the relase. Behavior need not
remain strictly identical.
Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must
@@ -64,6 +72,36 @@ Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts.
## Consumer Minimum And Release Toolchain
Distinguish the minimum toolchain supported for consumers from the toolchain
maintainers use to build and validate a release. Record the consumer minimum in
the language's standard metadata and explain its support meaning in canonical
documentation. Define the selected release toolchain and its setup commands in
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
choices.
For Go repositories, normally declare the initial stable release of the selected
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
when a dependency or an identified correctness fix requires it, and document
the reason.
For release-policy purposes, successful build and release validation on the
selected Go patch release are sufficient to presume support across that Go
series, subject to the declared consumer minimum and concrete evidence of
incompatibility. Investigate specific compatibility concerns as they arise.
Use the selected release toolchain for candidate validation and release builds,
including CI jobs performing those tasks. A newer validation patch version alone
leaves the consumer minimum unchanged.
A minor release may raise the Go consumer minimum, including from one Go series
to the next, both before and after `v1.0.0`. This is an explicit exception to the
backward-compatibility requirement for minor releases. Patch releases preserve
the consumer minimum. Explain an increase's impact and required consumer action
in the release note. Other incompatible changes remain subject to the versioning
rules above.
## Release Documentation And Preparation
Every new release must include `docs/releases/<version>.md` in the tagged
@@ -131,8 +169,8 @@ Do not add routine confirmations for checks the command can perform itself.
### Notarius Gate Selection
Run the default offline Go suite once and build the native `cmd/notarius` with
release version injection, checking its `--version` output. The command check
protects the actual executable entry point and linker-supplied version, which
release version injection, checking its native `version` command output. The
command check protects the actual executable entry point and linker-supplied version, which
package tests alone do not verify. Build products are temporary, not published.
Use `GOWORK=off` so a sibling checkout cannot substitute for declared dependencies.
@@ -191,7 +229,8 @@ release without replacing its contents or reusing its version.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify:
1. prerequisites, primary branch, and authoritative remote;
1. prerequisites, selected release toolchain, primary branch, and authoritative
remote;
2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards;
4. source-only delivery, required build targets, and automation responsibilities;

Some files were not shown because too many files have changed in this diff Show More