shd.build/tools/game-data-capture/contracts/README.md

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.