Compare commits
185 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 7faa4a0506 | |||
| f069a10c78 | |||
| c8250089b1 | |||
| 80148ef7e4 | |||
| 2429f0ae6a | |||
| 7ee7b997f0 | |||
| dd25838589 | |||
| 9074547e33 | |||
| 8ea96dc7a4 | |||
| 581229cd1f | |||
| e823baf3af | |||
| fdaf39162b | |||
| fd134e85e5 | |||
| 75444b8ef3 | |||
| 633ebd282f | |||
| b76d511571 | |||
| aa4ce04683 | |||
| 41f6079040 | |||
| 5db09d0203 | |||
| 2c27695df9 | |||
| 5e58327032 | |||
| 3cf389db78 | |||
| 5b6854e975 | |||
| 854d23b91e | |||
| 3ef55f4668 | |||
| 4fa437aee8 | |||
| 936fc1e72a | |||
| 5cfcf10a8b | |||
| 21bcb4eb3b | |||
| 5e68b74469 | |||
| 572b267c5d | |||
| 562dfad5cd | |||
| 0ad73ff575 | |||
| 20c0975d9d | |||
| 93d94fdd0a | |||
| 0b46f2d37c | |||
| a8d256f676 | |||
| 0cbc2b39cb | |||
| 2a9c5a6075 | |||
| 9f66421f4f | |||
| 8680060400 | |||
| 584b041e57 | |||
| 3b1b4c9bcf | |||
| 36906cb3d1 | |||
| 3ef55b1cf0 | |||
| 37e0753472 | |||
| 9a527b77c4 | |||
| b47208bd57 | |||
| 433ed420f8 | |||
| 3fa593362d | |||
| bb3153c1ad | |||
| 1fe231b6fb | |||
| 2c1d727232 | |||
| 303d6589c5 | |||
| 5d3696d4a0 | |||
| 52a1c96327 | |||
| 4f82d01534 | |||
| 772b8619c1 | |||
| 2348730820 | |||
| 92c2382806 | |||
| 923cbe594f | |||
| 44e4fb92c2 | |||
| c56c7d7ee9 | |||
| 797320b4da | |||
| b899ee32a6 | |||
| 91869ba191 | |||
| a1c888d2cd | |||
| a0274e154b | |||
| 87d362e2d7 | |||
| 40fbcc61b1 | |||
| cc14a7a5cc | |||
| bd30e86c0d | |||
| c480ad68a1 | |||
| b3664d5879 | |||
| 3f51764f1e | |||
| 5359cba98d | |||
| 058703abe5 | |||
| 254401e5f6 | |||
| 1292ed8c4b | |||
| baec913ef5 | |||
| 89a5398771 | |||
| 498f468f4f | |||
| e737167730 | |||
| b904021138 | |||
| 2d69c26813 | |||
| f883316d7a | |||
| 0833450c71 | |||
| 2eaea2b1fd | |||
| c03d0bb987 | |||
| 305a88e8f4 | |||
| 98ba7e1f55 | |||
| 1601b535ff | |||
| cbf3d1acc2 | |||
| 3c73ccfad0 | |||
| d9e1d1e4a7 | |||
| 5618adea8e | |||
| 9c4c2fc88d | |||
| d11d379bd4 | |||
| a299869fcc | |||
| 27081bc0af | |||
| 6fa520f8f3 | |||
| 5cdbc5400f | |||
| b038cc1a59 | |||
| 93dd406459 | |||
| b04fe98c9e | |||
| 8feece01db | |||
| d17d261d62 | |||
| 12eeb6369e | |||
| 3fb8cb7392 | |||
| 3e1abc7fbb | |||
| 40cd4fe97d | |||
| ae8e3ec698 | |||
| 8fb21b7dae | |||
| 5a527c789d | |||
| abecb349e4 | |||
| defe123955 | |||
| 69c4054eea | |||
| af250eb72f | |||
| 0ef079610e | |||
| d1d2394729 | |||
| 63e26dc203 | |||
| fe44b12073 | |||
| 65b8e8f0a2 | |||
| 76364a7b7e | |||
| 1c93aa0947 | |||
| 1febd2edfa | |||
| 5e269f9760 | |||
| fb58aef8c2 | |||
| 3f9727d5e8 | |||
| 0663fe566a | |||
| 347ef05b41 | |||
| 068a4b1b5a | |||
| b396581d21 | |||
| 6f0a75e7cf | |||
| d88a01cec0 | |||
| c9744ad2e6 | |||
| 74e0f454e9 | |||
| 244f258413 | |||
| 5bab35f096 | |||
| 8136b4814f | |||
| 349ace0528 | |||
| 716bc62991 | |||
| 61ceab786c | |||
| 2d1fa57d9b | |||
| 6da4d070e5 | |||
| ae0e410875 | |||
| 79088a3546 | |||
| 2c8b63187c | |||
| 2b278c4074 | |||
| db32d31708 | |||
| b9899ea3cc | |||
| 66fa5585c1 | |||
| e690cae24f | |||
| 6700ed2188 | |||
| 4aba4f5672 | |||
| 169a94f7ea | |||
| db8acbea43 | |||
| 79154882b8 | |||
| c848befb53 | |||
| a904e4d841 | |||
| 7ea9fe12b9 | |||
| deaa3560bc | |||
| ef504eabb2 | |||
| ec2ac3369b | |||
| 8a8ca6d83c | |||
| 30509f9d33 | |||
| 28aab5e9a4 | |||
| ea403c8094 | |||
| f5b066beee | |||
| aae01a59ce | |||
| 71cf084e8b | |||
| e327a5eef7 | |||
| af62b3bacc | |||
| e1097cc7a5 | |||
| 3f226c91d0 | |||
| 64509947df | |||
| 29c7c165a5 | |||
| 4ef69314e1 | |||
| 1d1434b118 | |||
| f4779fede9 | |||
| 01c08ec8e4 | |||
| d7ea0fd32d | |||
| ec99d48619 | |||
| 9e74df0b6e | |||
| 6e5e277426 |
@@ -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"
|
||||
|
||||
35
README.md
35
README.md
@@ -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).
|
||||
|
||||
|
||||
@@ -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
176
assets/combat_turns_test.go
Normal 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}},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
7
assets/dnd/combat-turns/prompts/correction.md
Normal file
7
assets/dnd/combat-turns/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
8
assets/dnd/enemy-events/prompts/correction.md
Normal file
8
assets/dnd/enemy-events/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/item-occurrences/prompts/correction.md
Normal file
7
assets/dnd/item-occurrences/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/item-registry/extract/prompts/correction.md
Normal file
7
assets/dnd/item-registry/extract/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/location-occurrences/prompts/correction.md
Normal file
7
assets/dnd/location-occurrences/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/npc-occurrences/prompts/correction.md
Normal file
7
assets/dnd/npc-occurrences/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/npc-registry/extract/prompts/correction.md
Normal file
7
assets/dnd/npc-registry/extract/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
7
assets/dnd/scene-descriptions/prompts/correction.md
Normal file
7
assets/dnd/scene-descriptions/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
8
assets/dnd/scenes/prompts/correction.md
Normal file
8
assets/dnd/scenes/prompts/correction.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
5
assets/dnd/spells/prompts/correction.md
Normal file
5
assets/dnd/spells/prompts/correction.md
Normal 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.
|
||||
@@ -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.
|
||||
|
||||
18
assets/dnd/spells/prompts/principles.md
Normal file
18
assets/dnd/spells/prompts/principles.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
151
assets/enemy_events_test.go
Normal 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"}]}`),
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
79
assets/item_occurrence_test.go
Normal file
79
assets/item_occurrence_test.go
Normal 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
57
assets/notarius.yml
Normal 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: .
|
||||
149
assets/occurrence_extraction_test.go
Normal file
149
assets/occurrence_extraction_test.go
Normal 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)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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
214
assets/package_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
@@ -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 {
|
||||
120
assets/registry_extraction_test.go
Normal file
120
assets/registry_extraction_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
120
assets/scene_descriptions_test.go
Normal file
120
assets/scene_descriptions_test.go
Normal 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
184
assets/scenes_test.go
Normal 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)
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
96
docs/adr/0019-adopt-native-promptkit-configuration.md
Normal file
96
docs/adr/0019-adopt-native-promptkit-configuration.md
Normal 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
82
docs/adr/0023-unify-accepted-artifact-and-plan-caching.md
Normal file
82
docs/adr/0023-unify-accepted-artifact-and-plan-caching.md
Normal 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.
|
||||
@@ -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.
|
||||
531
docs/cli.md
531
docs/cli.md
@@ -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
|
||||
|
||||
715
docs/config.md
715
docs/config.md
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
143
docs/consumers/native-migration.md
Normal file
143
docs/consumers/native-migration.md
Normal 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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
111
docs/integrations/pkg-commandkit.md
Normal file
111
docs/integrations/pkg-commandkit.md
Normal 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
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
| --- | --- | --- |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user