97 lines
5.0 KiB
Markdown
97 lines
5.0 KiB
Markdown
# D&D Source-Reference Endpoint Canonicalization
|
|
|
|
## Purpose
|
|
|
|
Make model-supplied D&D evidence ranges resilient to reversed endpoints without
|
|
spending producer retries on a losslessly repairable representation error.
|
|
|
|
## Problem
|
|
|
|
The shared extraction-evidence prompt requires `start_unit_id` and
|
|
`end_unit_id`, but does not state that start means the earlier unit in
|
|
transcript order. The private LLM schemas cannot express that cross-field
|
|
relationship. Current extraction adapters sort and de-duplicate ranges but
|
|
preserve reversed endpoints, so deterministic source-reference validators
|
|
reject otherwise useful candidates and may exhaust the producer retry budget.
|
|
|
|
## Target State
|
|
|
|
- The shared D&D extraction-evidence prompt states that `start_unit_id` is the
|
|
earlier endpoint and `end_unit_id` is the same or a later endpoint according
|
|
to transcript order.
|
|
- The existing LLM-facing and durable `start_unit_id`/`end_unit_id` shapes stay
|
|
unchanged. No unordered-pair schema or compatibility migration is introduced.
|
|
- One helper owned by `internal/modules/dnd/shared` orders the endpoints of a
|
|
source reference using `source.DocumentIndex` positions. It never assumes
|
|
that numerically smaller unit IDs occur earlier.
|
|
- The helper swaps endpoints only when the reference belongs to the current
|
|
source and both endpoint IDs resolve in that source. Forward and single-unit
|
|
ranges remain unchanged. Wrong-source, missing, non-positive, or otherwise
|
|
unresolved endpoints remain unchanged for deterministic validators to reject.
|
|
- Every D&D extraction adapter that consumes model-supplied evidence ranges
|
|
applies this endpoint operation before its existing range sorting,
|
|
de-duplication, earliest-evidence calculation, and validation. The covered
|
|
artifact families are spells, NPC registry, NPC occurrences, item registry,
|
|
item occurrences, location registry, location occurrences, combat turns, and
|
|
enemy events.
|
|
- Successful endpoint swapping is ordinary deterministic canonicalization. It
|
|
does not emit a warning, quality diagnostic, or retry request.
|
|
- The exact raw model response remains available through existing model-candidate
|
|
and debug provenance. Only the typed candidate presented to validators and
|
|
later stages receives the canonical endpoint order.
|
|
- Source-reference validators remain strict and continue rejecting reversed
|
|
ranges that reach them from another producer or indicate an application bug.
|
|
Normalizers do not become a fallback repair boundary for invalid extraction
|
|
candidates.
|
|
|
|
## Required Work
|
|
|
|
1. Clarify endpoint ordering in
|
|
`assets/dnd/shared/prompts/common-dnd-extraction-evidence.md`, preserving one
|
|
byte-identical shared instruction for every consuming prompt.
|
|
2. Extend the shared source-reference ordering utility with a mutation-safe
|
|
endpoint-ordering operation that uses document position and preserves
|
|
unresolvable references.
|
|
3. Integrate the shared operation into all nine model-response-to-candidate
|
|
mappings listed above. Do not duplicate endpoint comparison logic in the
|
|
individual artifact packages.
|
|
4. Update `docs/internal/dnd.md` to distinguish lossless endpoint ordering from
|
|
malformed-reference validation. External artifact documentation and schemas
|
|
require no change because their contract already requires ordered ranges.
|
|
5. Add lean regression coverage for forward, reversed, single-unit,
|
|
non-monotonic-ID, wrong-source, and unresolved endpoint cases. Add enough
|
|
adapter-level coverage to prove the shared operation is wired into every
|
|
affected extraction family without duplicating the helper's full case
|
|
matrix in each package.
|
|
6. Update prompt-asset and fingerprint expectations affected by the shared
|
|
prompt revision, while avoiding exact token-, byte-length-, or prose-snapshot
|
|
change-detector tests.
|
|
|
|
## Non-Goals
|
|
|
|
- Changing durable source-reference schemas or replacing named endpoints with
|
|
an unordered LLM response shape.
|
|
- Weakening source-reference validation or silently repairing missing,
|
|
out-of-source, or out-of-chunk evidence.
|
|
- Applying this policy to scene chunk-plan ranges, which are not extraction
|
|
evidence references and have a separate ownership and validation boundary.
|
|
- Adding warnings or durable normalization observations for routine endpoint
|
|
ordering.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- A D&D extraction candidate whose two resolvable evidence endpoints are
|
|
reversed reaches validation as the equivalent forward range without a
|
|
producer retry.
|
|
- Ordering follows document position even when unit IDs are not numerically
|
|
increasing.
|
|
- Every affected D&D extractor uses the shared implementation; no module-local
|
|
endpoint-swap implementation remains.
|
|
- References that cannot be safely ordered remain unchanged and are rejected by
|
|
the existing deterministic validators where applicable.
|
|
- Raw model-candidate provenance remains byte-faithful to the provider response.
|
|
- LLM-facing and durable schemas, validator strictness, module keys, default
|
|
chains, and output contracts remain unchanged.
|
|
- Focused package tests, repository-wide tests, `go vet ./...`, and
|
|
`go build ./cmd/notarius` pass.
|