feat: expand ISAC content modeling

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

@@ -1,40 +1,133 @@
 # 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`.
+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.
+- `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.
+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. The Weapon Mod slot, quality, compatibility, secondary-option, Mod Effect, exotic-attribute, and weapon-lock data and the Gear Mod quality and secondary-option data remain evidence-backed fields or relationships on the owning aggregate. They are not separate screen views or record types.
+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.
 
-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.
+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.
+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.
+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.
+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 its visible level, quality, tier, upgrade state, and values. Workers place proposed reusable definitions under `canonical_candidates` and handoff `records`. A worker must not copy an observed roll, relationship, mechanic, range endpoint, or option list into a canonical candidate unless evidence establishes that canonical claim.
+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 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.
+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.
+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.