eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document D&D prompt cache ordering

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-27 20:16:11 +00:00
parent d1eaec4dad
commit de8ed41b34
2 changed files with 40 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/internal/dnd.md
View File

@@ -39,9 +39,31 @@ D&D extractors assemble prompts from an ordered manifest of shared and
module-owned assets. Reuse the shared D&D system, evidence, identity, module-owned assets. Reuse the shared D&D system, evidence, identity,
reference, and transcript assets instead of copying their text into individual reference, and transcript assets instead of copying their text into individual
modules. A manifest’s declared sequence, including cache-control placement, is modules. A manifest’s declared sequence, including cache-control placement, is
part of the prompt behavior, and the chunk transcript is the final message. part of the prompt behavior.
Preserve that order when changing an extractor or its assets so prompt-cache
behavior remains stable. All extraction prompts share this four-message rendered prefix: the system
message without cache control, the identity message without cache control, the
campaign-reference message with ephemeral cache control, and the chunk
transcript message with ephemeral cache control. This gives equivalent
extraction requests the same reusable prefix through their source material.
Extraction-evidence policy, generated NPC registries, spell catalogs, module
tasks, and instructions follow the transcript because they are not universal
across all extraction lanes. The final instructions message carries ephemeral
cache control; evidence, registry, catalog, and task messages do not. Preserve
this division when changing an extractor or its assets so prompt-cache behavior
remains stable.
The other D&D LLM prompts intentionally follow different patterns. Scene
chunking has no sibling extraction lane with which to share its full transcript,
so it renders campaign references before its task and instructions, then places
the cacheable full transcript last. NPC normalization keeps its task and
cacheable instructions before the candidate collection, followed by the
cacheable transcript windows: candidates must be available before their
supporting evidence is evaluated, and those windows are not a cross-lane
prefix. Mounted assets and their declared message order determine the prompt
fingerprint, so intentional prompt edits continue to invalidate stale
checkpoints.
All extractors use the shared prompt-input preparation rules. The current chunk All extractors use the shared prompt-input preparation rules. The current chunk
is copied into transcript material; player, party, glossary, and compatible is copied into transcript material; player, party, glossary, and compatible

27
docs/internal/llm.md
View File

@@ -76,19 +76,22 @@ contract. Durable formats and compatibility rules remain in the
## Prompt Maintenance And Backend Caching ## Prompt Maintenance And Backend Caching
Prompt message order and shared asset bytes are runtime behavior. Backend cache Prompt message order and shared asset bytes are runtime behavior. Backend cache
reuse depends on the same preceding messages and content, not merely equivalent reuse depends on identical preceding roles, rendered bytes, and cache-control
meaning. Keep reusable shared assets byte-identical and keep stable material metadata—not merely equivalent meaning. Keep reusable shared assets
before the inputs that vary per request wherever a prompt’s declared sequence byte-identical and preserve each prompt’s declared ordering and cache controls
supports caching. Preserve the existing manifest order and cache-control hints when editing it.
when editing a prompt.
D&D extraction manifests place the changing chunk transcript at the end of the For sibling prompts that can reuse the same source material, order universal
prompt after their reusable context. Scene chunking and NPC normalization use shared context first, request source material next, and module-specific
their own declared message sequences because their inputs and work differ. The suffixes last. Put a cache boundary at a reusable prefix that is useful to the
family-specific asset and ordering rules belong in [D&D Module Internals](dnd.md). backend. Redundant intermediate cache boundaries do not extend that reusable
Do not add tests that enforce a fixed message-prefix length; prompt-asset tests prefix and add no value.
should instead verify the meaningful asset sequence, inputs, and cache controls
of the prompt being changed. 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.
## Validation, Repair, And Retries ## Validation, Repair, And Retries