134 lines
7.3 KiB
Markdown
134 lines
7.3 KiB
Markdown
# 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.
|