Unit Data Schema — Topic 01: Core Unit/Card Entity — Omega War

Stage 2 · per-topic review · topic 01 of 6 · cycle unit-data-schema · page created 2026-06-14

alignment_status: review — Stage 2 of 3, per-topic research review.
This page reviews topic 01 only — the core card entity, its field table, enum value sets, and the veterancy/trait-tag field shapes — compiled from the working doc research/_working/unit-data-schema/01-core-unit-card-entity.md. The cycle was decomposed (at the user's direction) into six per-topic docs reviewed one by one; the canonical artifact research/unit-data-schema.md is the later synthesis of all six topics, not this page. This page authors no canonical artifact and no glossary output, and it stays review.

Boundary (UD-A1): this topic defines shape, not values — entities, fields, enums, relationships, and a few clearly-marked illustrative rows. It assigns no combat stats, prices, exact counts, trait buff/debuff magnitudes, veterancy level magnitudes, or balance. Phase/era split (UD-A2): match-phase A/B/C (phase_band) and campaign era-band E0/E1/E2 (era_band) are two separate required fields, never conflated; the detailed semantics belong to topic 03 — topic 01 only records that the card carries both.

Stage-1 scope-approval record (read-only) — the unit-data-schema cycle scope was approved at Stage 1 on the hub page unit-data-schema-omega-war.html: deliverable shape-not-values-spec; input sources, entity set, and assumptions (UD-A1…UD-A7) all approved; post-confirm route tactical-vertical-slice-spec. A process addition (UDQ1 approve-with-additions) decomposed Stage 2 into six per-topic docs reviewed one by one — this page is the topic-01 review.

1. Purpose & scope of this topic — card-vs-instance

Section feedback notes

Define the unit/card entity — the single most-referenced object in the schema. Every other topic hangs off it: equipment & variants (02) attach to it, the phase/era split (03) are two of its fields, the deck/band/card-roster (04) references it, the To&E proportions (05) count it by class, and CP/wonder governance (06) constrains which instances deploy when.

Card vs unit instance. In this game a card is the deck-builder unit of selection and a unit is its battlefield instantiation. The arsenal §4A taxonomy is card-level ("WARNO-card style"); divisions §4 counts card-classes. This topic treats card as the schema's primary entity and unit instance as a thin runtime projection of it (an instance carries live state — position, current veterancy progress, suppression — none of which is authored here). The schema authors the card; the engine spawns unit instances.

2. The `card` entity — field table

Section feedback notes

Field types use a deliberately small vocabulary: enum (closed value set defined in §3), string, bool, ref<Entity> / ref<Entity>[] (relationship, resolved in the named topic), ordinal-enum (ordered tiers), deferred (a slot whose value is intentionally not authored this cycle — UD-A1). In the Req? column, required chips mark the authored-required set; optional chips mark optional/attachable fields.

Field	Type	Req?	Shared vs per-faction	Source	Notes
`id`	string (stable key)	required	shared	schema	Stable internal identifier; never a display name.
`display_name`	string	required	per-faction	§4A cells	The historical name shown on the card (e.g. "Rifle Squad '45").
`card_class`	enum `CardClass`	required	shared	§4A	The accepted taxonomy class. Value set in §3.1.
`faction`	ref<Faction>	required	n/a	§3	Owning faction; Faction entity modeled in topic 04/synthesis.
`category`	enum `Category`	required	shared	§3	Coarse arm/role grouping (infantry / armor / support / …). Value set in §3.2. Distinct from `card_class` (finer).
`era_band`	enum `EraBand`	required	shared	§4	Campaign availability axis E0/E1/E2. Full treatment in topic 03.
`phase_band`	enum `PhaseBand`	required	shared	§4	In-match escalation axis A/B/C, authored per card. Topic 03. Never conflated with `era_band` (UD-A2).
`zone`	enum `Zone`	required	shared	§4B	Plausibility/provenance dial: baseline / stretch / what-if. Value set in §3.4. Page copy must never blend zones (§4B rule).
`plausibility_tier`	enum `Tier`	optional	shared	§2/§3	T1–T4 evidence tier where one is recorded; pairs with `zone`. Value set in §3.5.
`veterancy_track`	ref<VeterancyTrack>	required	shared	genre §3	Which in-battle veterancy ladder this card uses. Ladder shape in §4. Persists into campaign (persistence hook only; refit economy deferred, UD-A5).
`transport_options`	ref<Card>[]	optional	per-faction	§4A.1	Nested transport selection (config pattern). Relationship detail in topic 02.
`trait_tags`	ref<TraitTag>[]	optional	shared catalogue	genre §3	Identity buff/debuff tags. Catalogue + magnitudes deferred (Prototype, UD-A4). Tag shape in §5.
`variants`	ref<Variant>[]	optional	per-faction	§4A.1	Separate-card variants / upgrade packages. Modeled in topic 02.
`equipment`	ref<EquipmentItem>[]	optional	per-faction	§3	The kit the card fields. Modeled in topic 02 (separate-entity vs attribute decision lives there).
`framing_note`	string	optional	per-faction	§4B	Provenance/what-if framing surfaced in UI (e.g. "Soviet trophy"). Carries the §4B "never lie about provenance" discipline.
`source_ref`	string	optional	per-faction	all	Citation/claim anchor (e.g. "Claim 4.10").
`reliability`	ordinal-enum `Confidence`	optional	per-faction	all	high / medium / low confidence on the historical basis.

Required-set rationale. A card cannot be authored, placed in a band, or counted in a To&E without id, display_name, card_class, faction, category, both band axes (era_band, phase_band), zone, and a veterancy_track. Everything else is optional/attachable.

Gate — card-model required

Approve the card-as-primary-entity vs unit-instance split (§1) and the field table + required set (§2)?

Approve the card/instance split, the field table, and the required set as written Approve the split, but revise specific fields or the required set (note which) Other / None of the above (describe in notes) Need clarification

Additional notes (optional; required if Other)

3. Enum value sets (these are shape, not values)

Section feedback notes

Enumerating allowed members is schema shape, not balance. Magnitudes attached to these members (cost, stats) stay deferred. Six enum sets follow.

3.1 `CardClass` — accepted §4A taxonomy

Closed enum. The §4A table enumerates the infantry/team classes verbatim:

line_squadassault_eliteengineermg_teammortar_teamat_teamflame_teamsniperreconcommand_logspecialistrecovery

OPEN — synthesis reconciliation headline decision

§4A's explicit table is infantry/team weighted; the vehicle/heavy classes the genre calibration implies (tank / assault-gun, towed & self-propelled artillery, AA/SPAAG, vehicle-recon, air) appear in §4A.1 variants, §3 tables, and the SD2 deck-tab note rather than as named taxonomy rows. The "12+4 card-class set" shorthand on the scope page refers to this infantry-12 + vehicle/heavy set. Synthesis must reconcile the full closed CardClass membership against §4A rather than this doc inventing the vehicle rows. This is the topic's single largest open item — gated separately below as cardclass-open.

3.2 `Category` — coarse arm/role grouping

Proposed members (shape; final set confirmed at synthesis against §3/§4A):

infantryarmorreconsupportanti_tankanti_airartillerycommand_logisticsrecoveryair

support = MG/mortar/engineer/flame. category is the SD2-tab-style coarse grouping; card_class is the finer leaf. A card has exactly one of each.

3.3 Band axes — `EraBand` / `PhaseBand`

Enum	Members	Meaning
`EraBand`	`E0`, `E1`, `E2`	Early / Mid / Late campaign availability axis.
`PhaseBand`	`A`, `B`, `C`	Vanguard / Main Body / Commitment in-match escalation axis.

Two separate required fields, never conflated (UD-A2). Topic 03 owns the detailed semantics, worked example, and the strong-weapons-locked-out-of-A rule; topic 01 only records that the card carries both.

3.4 `Zone` — provenance dial (§4B, ADOPTED)

3.5 `Tier` — plausibility evidence tier

3.6 `Confidence`

Enum	Members	Meaning
`Zone` (required)	`baseline`, `stretch`, `what_if`	Adopted three-zone dial: `baseline` = documented in-window at scale; `stretch` = documented capacity + mobilization argument (flagged); `what_if` = explicit fiction lever, never on by default, UI-labeled counterfactual. Every roster item "sits in exactly one zone."
`Tier` (optional)	`T1`, `T2`, `T3`, `T4`	Plausibility evidence tier (arsenal §2 ARQ2 adopted). Where present it refines `zone`. The tier→zone interaction (e.g. T4 paper at in-window date) is a synthesis note, not authored here.
`Confidence` (ordinal)	`high`, `medium`, `low`	Ordinal confidence on the historical basis of the row.

Gate — enums required

Approve the enum value sets (Category, the band axes, Zone, Tier, Confidence) as defined? (The CardClass membership is gated separately below.)

Approve the enum value sets as defined Approve, but revise specific enum members (note which) Other / None of the above (describe in notes) Need clarification

Additional notes (optional; required if Other)

Gate — cardclass-open required · headline

The full CardClass membership — specifically the vehicle/heavy rows (§3.1 OPEN) — is the topic's single largest open item. Defer it to synthesis as flagged, or resolve it now from §3 / §4A.1?

Defer the full CardClass membership to synthesis, as flagged (reconcile against §4A there) Resolve the vehicle/heavy CardClass rows now, from §3 / §4A.1 (note the intended set) Other / None of the above (describe in notes) Need clarification

Additional notes (optional; required if Other)

4. Entity-relationship diagram

Section feedback notes

Entity	Relationship to `card`	Where modeled
veterancy track	`veterancy_track` (required ref)	Resolved here — topic 01 §4
trait tag	`trait_tags` (optional ref list)	Resolved here — topic 01 §5 (catalogue deferred)
equipment item	`equipment` (optional ref list)	Topic 02 (entity-vs-attribute decision)
variant	`variants` (optional ref list)	Topic 02
transport options	`transport_options` (optional ref list)	Topic 02
faction	`faction` (required ref)	Topic 04 / synthesis
deck / card-roster	references the card (deck × band × card join)	Topic 04
division / To&E	counts the card by class (proportions)	Topic 05
CP / wonder slot	constrains which instances deploy when	Topic 06

5. Veterancy field (genre §3 — must-have, in-battle, persists)

Section feedback notes

Veterancy is a must-have in-battle mechanic that persists into the campaign as a persistence surface; the refit/upgrade economy is a campaign-layer deferral (UD-A5). Shape:

Entity / field	Type	Notes
`VeterancyTrack`	entity	`id`; `levels: VeterancyLevel[]` (ordered).
`VeterancyLevel.rank`	ordinal index	Order within the ladder.
`VeterancyLevel.label`	string	e.g. rookie / trained / veteran / elite — illustrative, count not fixed here.
`VeterancyLevel.modifiers`	`deferred`	No buff numbers — UD-A1/UD-A4.
`card.veterancy_track`	ref<VeterancyTrack>	Which ladder this card uses.
(unit instance) progress	runtime-only	Lives on the unit instance, not the authored card; survives the battle (campaign-persistence hook).

The number of levels and any per-level magnitude are values, not shape — deferred. The schema fixes only that a track is an ordered list of levels with a deferred modifier slot, and that progress is instance state that survives the battle (the campaign-persistence hook).

6. Trait-tag field (genre §3 — Prototype)

Section feedback notes

Prototype trait_tags: ref<TraitTag>[] on the card. The catalogue and magnitudes wait for the Prototype-tier balance pass (UD-A4). The TraitTag entity shape:

Field	Type	Notes
`id`	string	Stable key.
`name`	string	e.g. shock / commando / militia / leader — illustrative catalogue from genre §3, full catalogue deferred (UD-A4).
`polarity`	enum `{buff, debuff, mixed}`	A tag confers buffs, debuffs, or both — shock=buff, militia=debuff, leader=aura/buff, commando=buff.
`effect`	`deferred`	No magnitude, no stacking rules this cycle.

So the schema fixes that a card holds zero-or-more trait-tag references and that a tag declares a polarity, while the catalogue membership and all numbers wait for the Prototype-tier balance pass.

Gate — veterancy-traits required

Approve the veterancy-track field shape (§5, ordered ladder with a deferred modifier slot) and the trait-tag field shape (§6, polarity declared) with magnitudes and catalogue deferred (UD-A4/UD-A5)?

Approve both field shapes with magnitudes/catalogue deferred Approve, but revise the veterancy or trait-tag shape (note which) Other / None of the above (describe in notes) Need clarification

Additional notes (optional; required if Other)

7. Illustrative filled rows (shape demonstration only — NO values)

Section feedback notes

Two rows, marked illustrative. They show field population, not balance — no costs, no stats.

`id`	`display_name`	`card_class`	`faction`	`category`	`era_band`	`phase_band`	`zone`	`trait_tags`	`framing_note`
`us_rifle_squad_45`	Rifle Squad '45	`line_squad`	US	`infantry`	E0	A	`baseline`	—	—
`de_elefant_wonder`	Elefant (Soviet trophy)	(vehicle class — see §3.1 OPEN)	USSR	`armor`	E2	C	`what_if`	—	"two Berlin survivors, Soviet-captured (Claim 4.10)"

The second row deliberately lands on the §3.1 open item (a heavy vehicle card) and on the zone=what_if + framing_note provenance discipline, to surface both during review.

8. Open questions carried to synthesis

Section feedback notes

open Full CardClass membership (§3.1 OPEN) — reconcile the vehicle/heavy classes against §4A; do not invent rows here. (Gated above as cardclass-open.)
open Category final set (§3.2) — confirm the coarse grouping list and the class→category mapping against §3/§4A.
open Equipment as entity vs attribute — resolved in topic 02; topic 01 leaves equipment as a ref list pending that decision.
open card vs unit instance boundary — confirm at synthesis that authored fields (this doc) and runtime state (position, veterancy progress, suppression) stay cleanly separated.
open Veterancy level count & labels — values; deferred but flagged so the prototype pass knows the shape expects an ordered ladder.

The disposition of these open questions is carried by the route gate below.

Gate — route required

How should the cycle proceed? This also disposes the §8 open questions (they carry to synthesis unless you direct otherwise in notes).

Approve topic 01 and proceed to topic 02 (equipment & variant/upgrade) Revise topic 01 first (note what) Hold — do not proceed yet (note why) Other / None of the above (describe in notes) Need clarification

Additional notes (optional; required if Other)

9. Deferred-values register (this topic)

Section feedback notes

Deferred	Why	Where it lands
Combat stats / costs on any card	UD-A1 shape-not-values	later balance pass
Veterancy per-level modifiers	UD-A1/UD-A5	prototype + campaign economy
Trait-tag effect magnitudes & catalogue	UD-A4 Prototype	prototype balance pass
Vehicle-class enum rows	§3.1 OPEN, needs §4A reconcile	synthesis
Per-division card counts	arsenal §4A / divisions §4 explicitly defer	divisions/To&E (topic 05)

10. Source log (topic 01)

Section feedback notes

This is a design-synthesis topic over already-approved internal sources — "evidence" here is the source-section → schema mapping below, not external research.

arsenal-1945 §4A — ACCEPTED unit-type taxonomy table (12 infantry/team classes; vehicle/heavy reconciliation flagged).
arsenal-1945 §4A.1 — variant/upgrade patterns (separate-card / munitions / configuration) — referenced; modeled in topic 02.
arsenal-1945 §4B — adopted three-zone dial (baseline/stretch/what_if) + provenance-honesty discipline.
arsenal-1945 §2/§3 — plausibility tiers T1–T4; per-faction equipment tables (category/faction/tier attributes).
arsenal-1945 §4 — era-band E0/E1/E2 vs in-match phase A/B/C (two-axis), full treatment deferred to topic 03.
game-genre-map §3 — veterancy (must-have, in-battle, persists); unit trait tags (Prototype: shock/commando/militia/leader, magnitudes deferred).
divisions-1945 §4 — To&E → card-class proportions ("schema inputs"); counts deferred to topic 05.

11. Compile Responses

Answer the required gates above, add optional section feedback, then compile and copy the YAML into the next execution message. You may compile partial responses.

Unit Data Schema — Topic 01: Core Unit/Card Entity — Omega War

1. Purpose & scope of this topic — card-vs-instance

2. The card entity — field table

Gate — card-model required

3. Enum value sets (these are shape, not values)

3.1 CardClass — accepted §4A taxonomy

3.2 Category — coarse arm/role grouping

3.3 Band axes — EraBand / PhaseBand

3.4 Zone — provenance dial (§4B, ADOPTED)

3.5 Tier — plausibility evidence tier

3.6 Confidence

Gate — enums required

Gate — cardclass-open required · headline

4. Entity-relationship diagram

5. Veterancy field (genre §3 — must-have, in-battle, persists)

6. Trait-tag field (genre §3 — Prototype)

Gate — veterancy-traits required

7. Illustrative filled rows (shape demonstration only — NO values)

8. Open questions carried to synthesis

Gate — route required

9. Deferred-values register (this topic)

10. Source log (topic 01)

11. Compile Responses

2. The `card` entity — field table

3.1 `CardClass` — accepted §4A taxonomy

3.2 `Category` — coarse arm/role grouping

3.3 Band axes — `EraBand` / `PhaseBand`

3.4 `Zone` — provenance dial (§4B, ADOPTED)

3.5 `Tier` — plausibility evidence tier

3.6 `Confidence`