Simplify D&D combat turn extraction contract
This commit is contained in:
@@ -380,8 +380,8 @@ production validators do not call the LLM and must not set `llm_profile`.
|
||||
| `normalize/dnd/npcs/identity` | deterministic | Rejects invalid canonical IDs and duplicate canonical-name or ID ownership. |
|
||||
| `extract/dnd/combat-turns/shape` | deterministic | Rejects malformed D&D combat-turn artifacts. |
|
||||
| `extract/dnd/combat-turns/source_refs` | deterministic | Rejects missing or invalid D&D combat-turn source references. |
|
||||
| `extract/dnd/combat-turns/source_relatedness` | deterministic | Emits warnings when an actor or declared action is not found near cited source text. |
|
||||
| `normalize/dnd/combat-turns/invariants` | deterministic | Rejects normalized combat-turn identity, target, evidence-order, and chronology violations. |
|
||||
| `extract/dnd/combat-turns/source_relatedness` | deterministic | Emits warnings when an actor is not found near cited source text. |
|
||||
| `normalize/dnd/combat-turns/invariants` | deterministic | Rejects normalized combat-turn identity, evidence-order, and chronology violations. |
|
||||
|
||||
The production default chain for `dnd/spells` is used for both its extract and
|
||||
normalize stages:
|
||||
@@ -495,7 +495,7 @@ explicit ordered step.
|
||||
The `dnd/combat-turns` extractor declares the optional campaign slots and the
|
||||
structured `npcs` slot. Campaign references guide only the LLM extraction
|
||||
stage. The deterministic normalizer declares only `npcs`, whose operation-time
|
||||
registry supports the same actor and target canonicalization. Each `npcs` slot
|
||||
registry supports the same actor canonicalization. Each `npcs` slot
|
||||
accepts exactly one UTF-8 `application/json` artifact no larger than 1 MiB. The
|
||||
registry's source ranges remain provenance for the reference and never become
|
||||
combat evidence. An ordered step binding fans the same generated NPC artifact
|
||||
|
||||
@@ -25,20 +25,8 @@ Each combat turn contains these required fields:
|
||||
| --- | --- |
|
||||
| `actor` | Non-empty string. |
|
||||
| `turn_kind` | One of `turn`, `reaction`, `legendary_action`, `lair_action`, or `other`. |
|
||||
| `round` | Required JSON field containing a positive integer or `null`. |
|
||||
| `actions` | Required array with at least one action. |
|
||||
| `summary` | Non-empty string. |
|
||||
| `source_refs` | Required array with at least one source reference. |
|
||||
|
||||
Each action contains these required fields:
|
||||
|
||||
| Field | Shape |
|
||||
| --- | --- |
|
||||
| `category` | One of `attack`, `spell`, `movement`, `item`, `ability_check`, `saving_throw`, `condition`, or `other`. |
|
||||
| `declaration` | Non-empty string describing what was declared. |
|
||||
| `targets` | Required array of strings; the array may be empty, but entries may not be empty. |
|
||||
| `resolution` | Required JSON field containing a non-empty string or `null`. |
|
||||
|
||||
Source references use the shared source-reference shape:
|
||||
|
||||
```json
|
||||
@@ -58,11 +46,10 @@ boundary.
|
||||
|
||||
The codec exposes two representations of the same typed artifact:
|
||||
|
||||
- Candidate encode/decode preserves invalid enum values, nullable values,
|
||||
required-array presence, required strings, targets, and source references so
|
||||
later validators can report them. Candidate decoding still requires valid
|
||||
JSON, one JSON value, known fields, and the explicitly present `round` and
|
||||
`resolution` keys; `null` is distinct from a missing key.
|
||||
- Candidate encode/decode preserves invalid actor and turn-kind values,
|
||||
collection presence, and source references so later validators can report
|
||||
them. Candidate decoding still requires valid JSON, one JSON value, known
|
||||
fields, and compatible JSON types.
|
||||
- Approved encode/decode enforces the structural rules in this contract.
|
||||
|
||||
The codec owns the durable JSON Schema, whose object layers all set
|
||||
@@ -96,9 +83,9 @@ An external file is validated during preparation. In an ordered pipeline, the
|
||||
same slot may receive the producer's canonical generated artifact at the step
|
||||
handoff.
|
||||
|
||||
The private response envelope has the same fields and JSON types as the durable
|
||||
turn/action shape except that source references contain only `start_unit_id`
|
||||
and `end_unit_id`. It enforces required and nullable field presence, types, and
|
||||
The private response envelope has the same turn fields and JSON types as the
|
||||
durable shape except that source references contain only `start_unit_id`
|
||||
and `end_unit_id`. It enforces required field presence, types, and
|
||||
unknown-field rejection, while deterministic validators own enum membership,
|
||||
non-empty values and collections, and positive-number requirements. The
|
||||
extractor assigns the current source ID, removes exact duplicate ranges, and
|
||||
@@ -113,16 +100,14 @@ The standalone validator keys are:
|
||||
|
||||
| Validator | Responsibility |
|
||||
| --- | --- |
|
||||
| `extract/dnd/combat-turns/shape` | Required arrays, strings, nullable fields, positive rounds, and supported enum values. |
|
||||
| `extract/dnd/combat-turns/shape` | Required list, actor, turn kind, and source references, plus supported turn-kind values. |
|
||||
| `extract/dnd/combat-turns/source_refs` | Source identity, source-unit existence, and range order through the source document. |
|
||||
| `extract/dnd/combat-turns/source_relatedness` | At most one advisory warning per turn when the actor or declared action is not related to cited transcript text. |
|
||||
| `extract/dnd/combat-turns/source_relatedness` | At most one advisory warning per turn when the actor is not related to cited transcript text. |
|
||||
|
||||
Source-reference and relatedness validators defer malformed shape to the shape
|
||||
validator. Relatedness also defers when any cited source range is invalid. It
|
||||
combines overlapping cited ranges once in document order, compares actors with
|
||||
the shared Unicode-aware NPC identity policy, and checks declaration tokens of
|
||||
at least four Unicode code points against complete cited-text tokens. Targets
|
||||
are not checked deterministically.
|
||||
combines overlapping cited ranges once in document order and compares actors
|
||||
with the shared Unicode-aware NPC identity policy.
|
||||
|
||||
The production D&D registrar exposes the extractor and these validators. Its
|
||||
default extraction chain preserves this order: JSON syntax, private response
|
||||
@@ -139,14 +124,12 @@ time handoff. Runtime normalization uses that immutable prepared or handed-off
|
||||
view.
|
||||
|
||||
Normalization policy is `dnd.combat_turns.normalize.v1`. It display-normalizes
|
||||
actor, summary, declarations, targets, and non-null resolutions; canonicalizes
|
||||
exact registry actor and target matches; orders and deduplicates exact source
|
||||
references; stable-sorts records by earliest valid source-document position; and
|
||||
collapses only records with the same actor identity, turn kind, round value, and
|
||||
complete valid evidence set. The first normalized record is retained without
|
||||
merging its actions or prose. Invalid evidence is never eligible for duplicate
|
||||
collapse. Every mutation and collapse emits a bounded warning using the merged
|
||||
input index in its scope.
|
||||
the actor, canonicalizes exact registry actor matches, orders and deduplicates
|
||||
exact source references, stable-sorts records by earliest valid source-document
|
||||
position, and collapses only records with the same actor identity, turn kind,
|
||||
and complete valid evidence set. The first normalized record is retained.
|
||||
Invalid evidence is never eligible for duplicate collapse. Every mutation and
|
||||
collapse emits a bounded warning using the merged input index in its scope.
|
||||
|
||||
The normalizer reports `normalization_policy` and `identity_policy` metadata
|
||||
and fingerprints. An external registry may additionally contribute
|
||||
@@ -154,8 +137,8 @@ and fingerprints. An external registry may additionally contribute
|
||||
in framework handoff provenance and dependency fingerprints. The
|
||||
normalized-invariants validator is
|
||||
`normalize/dnd/combat-turns/invariants`; it defers shape and source-reference
|
||||
failures, then checks display normalization, target identity uniqueness,
|
||||
canonical evidence ordering, chronology, and duplicate identity. It rejects
|
||||
failures, then checks actor display normalization, canonical evidence ordering,
|
||||
chronology, and duplicate identity. It rejects
|
||||
with `invalid_combat_turn_normalization` under policy
|
||||
`dnd.combat_turns.validator.normalized.v1`.
|
||||
|
||||
|
||||
@@ -135,8 +135,8 @@ reusable content follows it.
|
||||
Accordingly, the common prefix of all three extraction prompts is system,
|
||||
extraction evidence, identity, and campaign references. The NPC prompt then
|
||||
renders task, instructions, and transcript. Spell renders the NPC registry,
|
||||
catalog, task, instructions, and transcript. Combat renders
|
||||
immediate resolution, NPC registry, task, instructions, and transcript. The
|
||||
catalog, task, instructions, and transcript. Combat renders the NPC registry,
|
||||
task, instructions, and transcript. The
|
||||
scene chunker is not an extraction lane: it retains its separate system,
|
||||
transcript, campaign-reference, task, and instruction order and marks its
|
||||
transcript and campaign-reference messages ephemeral.
|
||||
|
||||
@@ -265,8 +265,8 @@ source-reference validators.
|
||||
### `internal/modules/dnd/extract/combatturns`
|
||||
|
||||
The combat extractor prepares one structured request per supplied chunk using
|
||||
the shared extraction-evidence, identity, campaign-reference,
|
||||
immediate-resolution, NPC-grounding, and transcript prompt inputs. It
|
||||
the shared extraction-evidence, identity, campaign-reference, NPC-grounding,
|
||||
and transcript prompt inputs. It
|
||||
maps the private response to `dnd.CombatTurnList`, assigns the current source
|
||||
identity, removes exact duplicate source ranges, and orders turns by valid
|
||||
source-document position while preserving malformed candidate fields for
|
||||
@@ -333,8 +333,8 @@ independently for extraction and normalization.
|
||||
|
||||
The combat normalizer prepares an external NPC registry before execution or
|
||||
receives a generated registry at the ordered step handoff, then uses the
|
||||
immutable view during runtime. It display-normalizes combat fields,
|
||||
rewrites exact canonical-name or alias matches for actors and targets, orders
|
||||
immutable view during runtime. It display-normalizes actors,
|
||||
rewrites exact canonical-name or alias matches for actors, orders
|
||||
and deduplicates source references, stable-sorts records by source-document
|
||||
position, and collapses only exact duplicate identities with fully valid
|
||||
evidence. It deep-clones output storage and emits bounded warnings scoped to
|
||||
@@ -414,16 +414,14 @@ production chains.
|
||||
|
||||
## D&D Combat Validators
|
||||
|
||||
Combat shape validation owns required arrays, strings, nullable values, positive
|
||||
rounds, and supported enums. Combat source-reference validation defers invalid
|
||||
Combat shape validation owns the required list, actor, supported turn kind, and
|
||||
non-empty source-reference collection. Combat source-reference validation defers invalid
|
||||
shape, checks source identity, unit existence, and range order, and reports all
|
||||
defects through bounded aggregates. Combat source-relatedness defers invalid
|
||||
shape or ranges, uses the shared traversal to combine overlapping cited units
|
||||
in document order, and emits at most one bounded advisory warning per turn for
|
||||
unrelated actors or declaration text.
|
||||
Actors use normalized consecutive-token matching; declarations retain the
|
||||
minimum four-rune token heuristic. The normalized-invariants
|
||||
validator owns display normalization, comparison-unique targets, canonical
|
||||
an unrelated actor. Actors use normalized consecutive-token matching. The
|
||||
normalized-invariants validator owns actor display normalization, canonical
|
||||
source-reference order, chronology, and exact duplicate identity; it defers
|
||||
shape and source-reference failures. All four validators are deterministic and
|
||||
expose local policy fingerprints. The D&D registrar orders them after generic
|
||||
|
||||
@@ -87,7 +87,7 @@ Configuration. The implemented module packages are:
|
||||
| `internal/modules/seriatim/input/transcript` | Parses the supported Seriatim transcript format into the generic source model. |
|
||||
| `internal/modules/generic/chunk/units` | Splits ordered source units by unit count and overlap. |
|
||||
| `internal/modules/dnd/chunk/scenes` | Produces contiguous D&D scene chunks from structured model output. |
|
||||
| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, combat-turn, and combat-action artifact types. |
|
||||
| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, and combat-turn artifact types. |
|
||||
| `internal/modules/dnd/codec/spells` | Strictly decodes and stably encodes the durable D&D spell-list representation. |
|
||||
| `internal/modules/dnd/codec/npcs` | Strictly decodes and stably encodes the durable D&D NPC-list representation. |
|
||||
| `internal/modules/dnd/codec/combatturns` | Strictly decodes and stably encodes the durable D&D combat-turn-list representation. |
|
||||
|
||||
Reference in New Issue
Block a user