Review artifact for the upcoming Deployment Plan prototype field migration. Created 2026-06-23; documentation only.
Purpose: identify stale prototype field names, map them to the canonical schema targets, and recommend a safe migration order before any fixture or runtime rename begins.
This page uses JS-facing camelCase migration names such as matchPhase, deploymentPhase, unitType, and traitTags. The canonical schema source currently spells one persisted field as card_class; this artifact recommends replacing that target with unit_type / unitType before migration.
The Deployment Plan prototype currently uses a compressed fixture/runtime shape. The canonical schema separates authored Card data, deck/decklist card-entry data, and runtime tactical state.
| Source | Alignment relevance |
|---|---|
research/unthinkable/unit-data-schema.md | Defines Card, Deck, Decklist, recommended DecklistUnitEntry naming, match_phase, deployment_phase, current card_class naming proposed here as unit_type, trait_tags, weapon_slots, transport options, and decklist-entry cardCount invariants. |
docs/decklist-rules-alignment.md | Reconciles army organization, deck, decklist, phase labels, facility gates, cardCost / cardCount / unitRequisitionCost tuning boundaries, transport boundaries, trait governance, and fixture audit notes. |
prototypes/unthinkable/tactical-battle/deployment-plan-first/js/data.js | Defines GAME_DATA.units as the player fixture source and derives roster views, detail objects, and prototype cost/count lookups that map to cardCost/cardCount later. |
prototypes/unthinkable/tactical-battle/deployment-plan-first/js/enemy-data.js | Defines read-only ENEMY_UNITS with the same compressed per-card shape plus enemy transport and passenger companion data. |
prototypes/unthinkable/tactical-battle/deployment-plan-first/js/state.js, model.js, roster.js, queue.js | Carry runtime names such as selectedBand, bandFromMeta, data-add-band, serialized band, and selectedBand build-order payload fields. |
GAME_DATA.units and ENEMY_UNITS pack authored identity, deck availability, prototype count/cost aliases, display details, physical render type, tactical role hints, weapons, transport, and companion state into one object per card name.
The derived views are useful for the prototype, but the field names now hide which layer owns each value.
The schema target keeps authored Card identity separate from deck/decklist placement. The tactical battle state owns the current matchPhase, deployed unit position, damage, suppression, current veterancy progress, and other battle facts.
The migration should name fields by ownership before moving values into separate stores.
Use the agreed production vocabulary in player-facing, design-facing, and schema-facing docs. Retire CardRosterEntry as a production schema term and rename that concept to DecklistUnitEntry.
| Term | Locked meaning |
|---|---|
ArmyOrganization | The larger historical force pool a player draws from for a scenario or campaign. |
Deck | Reusable playable force package built from an army organization. |
Decklist | Specific configured version of a deck for a player, scenario, AI force, saved loadout, or fixture. |
DecklistUnitEntry | One configured unit/card entry inside a decklist. |
roster | Derived UI projection only, such as category -> phase -> cards. Do not use as a persisted schema object. |
DecklistUnitEntry owns deploymentPhase, selected loadout, transport/passenger/equipment choices, cardCost, cardCount, unitRequisitionCost, wonder eligibility, and command-post availability metadata. These are configured entry values, not authored unit/card identity.
Do not keep expanding band. The current prototype band field is stale because it conflates the tactical battle state's current phase with the deployment-plan / deck availability axis. Stored phase values still remain A, B, and C.
| Axis | Layer | Meaning | Migration note |
|---|---|---|---|
matchPhasebattle state field | Runtime tactical battle state | The active tactical battle phase: the current in-match escalation window that advances from A to B to C. | Use only when the field answers "which phase is this match in right now?" If a later card-specific phase floor is needed, name it requiredMatchPhase or phaseFloor, not matchPhase. |
deploymentPhaseschema: deployment_phase | DecklistUnitEntry / Deployment Plan data | The out-of-battle decklist-entry and deployment-planning phase bucket that governs phase-based gameplay interactions before tactical battle entry. | Use when the field answers "which deck/planner phase bucket contains this configured entry or unlock surface?" It is availability metadata, not the active battle clock. |
A, B, C | Stored values | The compact phase values stay stable. Player-facing labels can remain Phase A/B/C in deck building and scenario-specific in tactical announcements. | Rename the field family, not the stored values. |
Command-post upgrades do not trigger phase progression. The tactical battle advances matchPhase; that phase progression unlocks or grants command-structure upgrades, which can then change availability for deploymentPhase-bucketed decklist entries.
type is the useful prototype axisThe current prototype type values are infantry, weapon-team, vehicle, tank, aircraft, and structure. They drive popover rendering, stat defaults, selection rows, and visual/type badges while staying broad enough for current design churn.
unitType replaces cardClassUse unitType for this axis because cards are individual decklist entries or offerings of units. unitType describes what kind of unit the card produces without locking the schema into premature tactical leaf classes.
Rename the prototype's type field to unitType and preserve the current broad values. Do not add a granular cardClass / physicalType split until there is a proven content or UI need; if a finer tactical role axis appears later, add it separately as tacticalRole, roleTags, or an equivalent explicit field.
| Current prototype field or use | Canonical target | Priority | Recommended migration action |
|---|---|---|---|
band on units, queue items, roster cards, and enemy cards | deploymentPhase on DecklistUnitEntry; matchPhase only on tactical battle state | urgent | Introduce deploymentPhase in fixture and decklist-entry data, derive legacy band during compatibility, and reserve matchPhase for the active tactical battle state after entry. |
selectedBand, bandOptions, bandFromMeta, data-add-band | Phase-named equivalents such as selectedDeploymentPhase, deploymentPhaseOptions, deploymentPhaseFromMeta, and data-add-deployment-phase | urgent | Rename the UI/runtime family with build-order versioning or alias decoding. This is serialized in build-order payloads, so migrate with backward compatibility. |
type | unitType | urgent | Rename the existing prototype field to unitType and keep the current broad values. Do not add granular cardClass role values until the content model proves a separate axis is needed. |
traits string lists | traitTags / schema trait_tags | medium | Normalize to arrays of stable tag IDs. Keep display labels in the trait registry rather than comma-separated card strings. |
weaponSlots, weaponLayout, and overloaded special slots | Derived display projection from the resolved unit loadout | later | The schema should define the loadout shape; authored/server data should hold the possible loadout records; player/deployment state should hold the selected loadout for each unit or decklist entry. weaponSlots and weaponLayout are then loaded as card-face / popover projections from that resolved loadout, not treated as the source loadout schema itself. The current prototype stores the projection directly because each card effectively has one resolved loadout. |
details mixed card-face strings | Explicit fields over time: requirements, abilities, transport options, framing notes, unlock text, keyword tags | medium | Split high-value prefixes first: Requires:, Abilities:, Transport:, Unlocks:, and Keyword:. Keep derived card-face copy terse. |
count | cardCount on DecklistUnitEntry | medium | Map current prototype count to cardCount: total copies/cards of that unit entry available in the decklist. Resolve effective count from selected loadout, equipment, transport/passenger, veterancy, trait, and balance modifiers. Keep the invariant that playable entries resolve to at least one deployable unit instance. |
cost | cardCost on DecklistUnitEntry | medium | Map current prototype cost to cardCost: tactical cost to deploy one card/unit entry. Resolve final tactical cost from selected-configuration deltas. |
| Future deck-builder budget / slot price | unitRequisitionCost on DecklistUnitEntry | medium | Use unitRequisitionCost for the deck-building cost to include the unit in a decklist in a given phase/configuration. Keep it separate from tactical cardCost. |
tow and transport | Transport options plus equipment mount/carry model | medium | Separate optional lift choices, required tow baselines, and equipment mount/carry capability. Preserve current eligibility derivation while naming the relationships explicitly. |
Enemy desant | Passenger / passengerOptions naming | medium | Rename to passenger language shared with the player-side rider modal and queue item shape. Keep "tank-desant" as historical display copy, not as the schema field name. |
Use these fields to record approval notes, exceptions, blocking concerns, or required edits for each mismatch before the migration pass begins.
band splitReview whether band should migrate to decklist-entry deploymentPhase while reserving matchPhase for the active tactical battle state, including any compatibility aliases needed for existing build orders.
Review the rename path for selectedBand, bandOptions, bandFromMeta, and data-add-band.
type to unitTypeReview the proposed direct rename from prototype type to canonical unitType.
traitsReview the move from comma-separated trait display strings to stable traitTags / trait_tags identifiers.
Review whether weaponSlots and weaponLayout should remain derived display projections of the selected or default unit loadout, rather than becoming the source loadout schema or the persisted loadout selection.
detailsReview the proposed split of mixed card-face strings into requirements, abilities, transport options, framing notes, unlock text, and keyword tags.
count to cardCountReview the ownership of card quantity as DecklistUnitEntry availability data: cardCount plus selected-configuration modifiers, not authored unit identity.
cost splitReview the split between tactical cardCost and deck-building unitRequisitionCost, and how selectable configuration or transport deltas compose.
tow / transportReview how required tow baselines, optional transport choices, carry capacity, and equipment mount capability should be named.
desantReview the rename from enemy-specific desant to shared passenger / passengerOptions naming while preserving historical display copy.
Rename and conform band, selected phase state, DOM data attributes, and build-order payload aliases before moving deeper schema fields. This reduces the highest-risk ambiguity.
type to unitTypeKeep the prototype's broad type values and migrate the field name directly. UI code can then migrate incrementally without forcing premature tactical role classes.
Move deploymentPhase, selected loadout, transport/passenger/equipment choices, cardCost, cardCount, unitRequisitionCost, wonder eligibility, and command-post unlock metadata out of authored unit/card identity and into DecklistUnitEntry.
Convert traits, equipment, transport, passenger, and display-detail strings into named structures once the phase/type ownership split is stable.
This artifact does not implement the migration and does not rename any prototype field. It is the review map for a later data/runtime compatibility pass.
Prototype field mapping for that later pass: cost -> cardCost, count -> cardCount, future deck-builder budget / slot price -> unitRequisitionCost. Derived roster maps remain UI views, not persisted schema.
A later code migration should add compatibility aliases before changing serialized build-order payloads or fixture field names.