# Game Data Capture Contracts RG-1 freezes contract version 1 for the taxonomy, workflow states, evidence model, archive manifest, and ISAC handoff boundary. The approved GDC-001 mod-family change extends version 1 with `weapon_mod` and `gear_mod`. ## Files - `domain-contract-v1.json` lists every family/view pair, record type, Gear slot, abstention reason, state, and allowed transition. - `screenshot-classification.schema.json` validates one hierarchical screen classification. - `evidence-archive-manifest-v1.schema.json` validates a private evidence archive manifest. - `isac-handoff-v1.schema.json` validates a bounded draft handoff for authenticated ISAC intake. - `examples/classification/` contains one valid and one invalid classification for each family, including Weapon Mod, Gear Mod, and explicit `unknown` abstention. - `examples/archive/` and `examples/handoff/` exercise each versioned document schema. The schemas use JSON Schema Draft 2020-12, internal `$ref` values, standard formats, and no implementation-specific keywords. Python `jsonschema` and TypeScript validators such as Ajv can compile the files without model conversion. Consumers must reject a document unless `schema_version` equals the schema's `const` value. Consumers must also run semantic reference validation because JSON Schema cannot prove that an ID points to an item in another array. ## Mod Screen Semantics Repository source data and editors establish `weapon_mod` and `gear_mod` as separate canonical aggregates. Each family currently supports only the `detail` view and its same-named record type. A Mod classification never sets the six-slot `gear_slot` field. A Weapon Mod detail screenshot may provide evidence for item-owned slot, primary quality ranges, compatibility, Mod Effects, exotic Attributes, and weapon-lock data. A Gear Mod detail screenshot may provide evidence for its item-owned primary quality ranges. These fields and relationships are not separate screen views or record types. Each mod family has one global canonical secondary Attribute pool configured outside individual item details. The pool stores Level 1 and Level 20 minimum and maximum ranges for Specialized, Superior, and High-end quality. Capacity is zero for Standard, one for Specialized, and two each for Superior and High-end. A secondary roll visible on an item-detail screenshot is evidence for that observed item instance; it does not establish a pool option, canonical range endpoint, or family-wide capacity. The `record_types` array still supports composite screens. No repository evidence establishes another independent canonical record type on a Weapon Mod or Gear Mod detail screen, so these two mappings each contain one record type. A classifier must use `unknown` with an abstention reason for another Mod view, an ambiguous family, or unsupported content. ## Skill Chip Screen Semantics The implemented Skill Chip model assigns each definition to one specialization ability. Each set owns one 2-piece bonus and may own one 3-piece Talent. One shared fixed primary profile serves every definition: Skill Duration, Skill Radius, Skill Cooldown Recovery, and Skill Intensity each store direct minimum and maximum values for Standard, Specialized, Superior, and High-end. These primary values apply to the assigned ability. Current Agent and combat totals exclude them and present them as `NOT YET DEFINED`. One shared secondary Attribute pool also serves every definition. Its entries store direct minimum and maximum values for Specialized, Superior, and High-end. Secondary capacity is zero for Standard, one for Specialized, and two each for Superior and High-end. Skill Chips have no item levels, so workers must not infer level curves or level-based endpoints from Skill Chip evidence. Every equipped quality counts toward the two-piece threshold. Only equipped High-end chips increase `h` in `minimum + (maximum - minimum) * h / 3`, where `h` ranges from zero through three. The unchanged version 1 contract vocabulary uses `skill_chip_roll_pool` for captured roll-profile evidence. Handoff consumers must map that evidence to the shared primary profile or shared secondary pool and must not attach either profile to an individual definition. The JSON schemas remain unchanged. ## Version Decision The approved additive taxonomy change remains schema version 1. The document shapes, trust boundary, bounds, and meanings of every existing value are unchanged, and all existing version 1 labels and documents remain valid. This utility and its payloads are prototype formats; no production-stable archive or handoff version has been declared. A version increment would force a document migration without representing a structural or semantic break. Consumers must update their closed version 1 vocabularies before they accept Mod labels. Older consumers reject the new values, which keeps the boundary fail closed. Existing stored labels need validation against the revised vocabulary but no value rewrite. The capture-label UI, storage regression coverage, classifier, extraction dispatch, evidence export, and ISAC adapter mappings must consume both families and their exact `detail`/record-type pairs before their respective gates can pass. This contract change does not alter those downstream implementations. ## Evidence Rules Capture workers store source text, a normalized value, confidence, engine identity, an image digest, a bounded region, and append-only correction history for each evidence value. A null normalized value requires a `missing_reason`. A present normalized value requires a null `missing_reason`. Each correction's `before` state must match the preceding `after` state. Timestamps must increase, and the final `after` state must match the current evidence value. Workers record the configured item shown on screen under `observed_instances`, including visible values and any applicable quality, tier, upgrade state, or level. Skill Chip observations omit item level because Skill Chips have none. Workers place proposed reusable definitions under `canonical_candidates` and handoff `records`. For Weapon Mods, Gear Mods, and Skill Chips, item-detail evidence remains separate from each family’s shared canonical profiles. A worker must not copy an observed roll, relationship, mechanic, range endpoint, option list, or secondary capacity into a canonical candidate unless evidence establishes that canonical claim. ## Trust Boundary Archive and handoff documents contain content hashes and logical artifact IDs. They exclude host paths and credentials. The handoff declares `mutation_authority: "none"`. Importing or inspecting it grants no permission and performs no mutation. An authenticated ISAC action must revalidate each draft and preserve contributor moderation and audit behavior. Archive images and handoff images allow at most 64 MiB. Private archive videos allow at most 16 GiB, matching the configured capture ceiling. Schema validation enforces media-specific byte limits. Semantic validation enforces unique entity and correction IDs, local references, evidence artifact hashes, correction chains, and normalized image bounds. The contracts assign explicit states or reasons to cancellation, resource exhaustion, ambiguous classification, unsupported content, and extraction failure. Recovery requires a listed transition. Unknown transitions and future schema versions fail closed.