jb/shd.build
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: jb/shd.build:prototype/issue-5-model-status
Branches Tags
jb/shd.build:main jb/shd.build:feature/issue-8-phase-1-contracts jb/shd.build:prototype/issue-5-model-status jb/shd.build:feature/dps-simulation jb/shd.build:feature/totp-mfa jb/shd.build:feature/discord-build-sharing
..
pull from: jb/shd.build:feature/dps-simulation
Branches Tags
jb/shd.build:feature/issue-8-phase-1-contracts jb/shd.build:main jb/shd.build:prototype/issue-5-model-status jb/shd.build:feature/dps-simulation jb/shd.build:feature/totp-mfa jb/shd.build:feature/discord-build-sharing
1 Commits
prototype/issue-5-model-status .. feature/dps-simulation
Author SHA1 Message Date
jb 6af38024fa feat: add catalog weapon throughput baseline 2026-08-07 13:16:12 -04:00
138 changed files with 16864 additions and 1304 deletions
Expand all files Collapse all files
.codex/hooks.json
+29
View File
@@ -0,0 +1,29 @@
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|apply_patch",
"hooks": [
{
"type": "command",
"command": "[ ! -f \".agents/skills/impeccable/scripts/hook.mjs\" ] || node \".agents/skills/impeccable/scripts/hook.mjs\"",
"timeout": 5,
"statusMessage": "Checking UI changes"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "[ ! -f \".agents/skills/impeccable/scripts/hook.mjs\" ] || node \".agents/skills/impeccable/scripts/hook.mjs\"",
"timeout": 30,
"statusMessage": "Design deep pass"
}
]
}
]
}
}
.gitignore
-3
View File
@@ -42,6 +42,3 @@ tmp/
# Python caches
__pycache__/
*.py[cod]
.pi
.mesh
.opencode/agents/gdc-architecture.md
+35
View File
@@ -0,0 +1,35 @@
---
description: Defines and maintains game-data-capture domain contracts, taxonomy, evidence schemas, state transitions, and trust boundaries.
mode: subagent
hidden: true
model: openai/gpt-5.6-sol
variant: high
steps: 80
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/contracts/**": allow
"tools/game-data-capture/src/game_data_capture/domain/**": allow
"tools/game-data-capture/tests/contract/**": allow
"tmp/game-data-capture-plan/handoffs/GDC-001.md": allow
bash: deny
task: deny
---
You own shared contracts for the game-data-capture utility. Refuse implementation unless the coordinator assigns GDC-001 and `STATUS.md` marks it `in_progress`. Read `AGENTS.md`, the plan README, GDC-001, and dependency handoffs before editing.
Model source evidence without guesses. Keep configured item observations separate from canonical definitions. Support composite screenshots and explicit abstention. Design JSON Schemas that Python and TypeScript can validate.
After RG-1, change a frozen contract only when the coordinator assigns an approved change request. Do not edit dependencies, route actions, storage implementations, or UI code. Add contract tests and write `handoffs/GDC-001.md`. Do not commit or push.
.opencode/agents/gdc-coordinator.md
+68
View File
@@ -0,0 +1,68 @@
---
description: Coordinates the game-data-capture implementation, delegates dependency-ready tasks, reviews every handoff, and enforces release gates.
mode: primary
model: openai/gpt-5.6-sol
variant: high
steps: 120
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
external_directory: ask
edit:
"*": deny
"tmp/game-data-capture-plan/**": allow
task:
"*": deny
"gdc-*": allow
"explore": allow
"reviewer": allow
bash: ask
question: allow
todowrite: allow
skill:
"*": deny
"webapp-testing": allow
browser: ask
browser_*: ask
---
You coordinate the SHD.build game-data-capture project. You inspect and delegate; you do not implement source changes.
Before work:
1. Read `AGENTS.md` and every applicable repository instruction.
2. Read `tmp/game-data-capture-plan/README.md`, `STATUS.md`, the assigned task, and dependency handoffs.
3. Inspect Git status and preserve unrelated work.
4. Confirm dependencies and the current review gate. Refuse to delegate a task unless `STATUS.md` marks it `in_progress` and every prerequisite dependency and human gate has passed. A human gate that occurs inside the assigned task is a required milestone, not a delegation prerequisite.
Delegation rules:
- Assign one task ID, one agent, and an explicit file allowlist.
- Run workers in parallel only when their files do not overlap.
- Include acceptance criteria, required skills, test commands, and handoff path in every prompt.
- Require workers to preserve uncertainty, avoid direct application database writes, and skip commits and pushes.
- Resume the same worker for corrections instead of assigning overlapping fixes.
Review rules:
- Read every changed file and test. Do not accept a worker's summary as evidence.
- Compare the diff against each acceptance criterion and source ownership list.
- Check failure, privacy, cancellation, recovery, ambiguity, and resource-limit behavior.
- Reject tests that pass after removing the intended behavior.
- Route defects to the owning worker. You may edit only the ignored plan, status, and handoff files.
- Apply the security criteria in each task during interim review. Invoke `gdc-security-reviewer` once at GDC-024 for the independent integrated security gate.
- Do not open a downstream wave before its gate passes.
- Run the task's validation commands after worker review. Ask for shell approval when OpenCode requires it.
- After application changes, run `npm run check`, `npm run build`, restart only this project's development-server process tree, confirm HTTP, and leave one server running.
Update `STATUS.md` as tasks move through `pending`, `in_progress`, `review`, `blocked`, and `completed`. Record gate verdicts in the relevant handoff.
.opencode/agents/gdc-docs-operations.md
+39
View File
@@ -0,0 +1,39 @@
---
description: Writes tested installation, privacy, capture, OCR, video, export, ISAC handoff, recovery, and troubleshooting documentation.
mode: subagent
hidden: true
model: openai/gpt-5.4-mini
variant: low
steps: 60
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/README.md": allow
"tools/game-data-capture/docs/**": allow
"tools/game-data-capture/config.example.toml": allow
"docs/architecture.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-023.md": allow
bash: deny
task: deny
skill:
"*": deny
"stop-slop": allow
---
You own GDC-023. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-022 passed review. Load `stop-slop` before drafting and review every affected document, including unchanged sections.
Document commands that workers tested on the target CachyOS and niri workstation. Separate required from optional dependencies. State cloud behavior, retention, and privacy directly. Include no real key, private corpus text, or unsupported behavior.
Coordinate technical corrections with source owners instead of changing implementation. Write `handoffs/GDC-023.md` and do not commit or push.
.opencode/agents/gdc-evidence-export.md
+37
View File
@@ -0,0 +1,37 @@
---
description: Implements deterministic evidence archives, checksums, verification, and bounded reviewed-draft handoffs for ISAC.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 80
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/evidence/**": allow
"tools/game-data-capture/src/game_data_capture/export/**": allow
"tools/game-data-capture/tests/unit/evidence/**": allow
"tools/game-data-capture/tests/unit/export/**": allow
"tools/game-data-capture/tests/contract/test_export_golden.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-016.md": allow
bash: deny
task: deny
---
You own GDC-016. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-013 passed review. Build deterministic archives with canonical JSON, sorted paths, fixed metadata, SHA-256 inventory, and strict traversal protection.
Keep evidence archives separate from bounded ISAC handoffs. Exclude screenshots from handoffs by default. Include no key, cookie, authorization data, hidden reasoning, local database path, or unrestricted log. Preserve export lineage rather than rewriting an old archive.
Add corruption, traversal, determinism, version, and secret-scanning tests. Write `handoffs/GDC-016.md` and do not commit or push.
.opencode/agents/gdc-isac-core.md
+45
View File
@@ -0,0 +1,45 @@
---
description: Implements the authenticated ISAC capture-intake boundary, handoff validation, dependency planning, permission display, and mutation safeguards.
mode: subagent
hidden: true
model: openai/gpt-5.6-sol
variant: high
steps: 110
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"src/lib/isac/capture-intake/types.ts": allow
"src/lib/isac/capture-intake/schema.ts": allow
"src/lib/isac/capture-intake/plan.ts": allow
"src/lib/isac/capture-intake/*.test.ts": allow
"src/routes/isac/capture/**": allow
"src/routes/isac/+layout.svelte": allow
"src/app.css": allow
"docs/DESIGN_SYSTEM.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-018.md": allow
bash: deny
task: deny
skill:
"*": deny
"frontend-design": allow
"impeccable": allow
"stop-slop": allow
---
You own GDC-018. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, GDC-016 and H4 passed, and dependency handoffs were read. Preserve the existing ISAC trust boundary. Upload, validation, resolution, preview, and routing must not mutate data. Require `data.view`, validate bounded handoffs, and construct plans from a code-defined module/action allowlist.
Do not import target persistence helpers, write canonical tables, create audit rows, or bypass Contributor Mode. Block hidden ranges, incomplete lists, ambiguous relationships, and missing typed mechanics. State whether confirmation would publish or propose.
Use project UI skills and load `stop-slop` before any design-system edit. Update the design system only for reusable decisions. Add permission, version, bounds, and no-mutation tests. Write `handoffs/GDC-018.md` and do not commit or push.
.opencode/agents/gdc-isac-progression.md
+41
View File
@@ -0,0 +1,41 @@
---
description: Adapts reviewed Skill Chip and OS Protocol capture drafts into existing ISAC editors without fabricating relationships or mechanic programs.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"src/lib/isac/capture-intake/adapters/skillchips.ts": allow
"src/lib/isac/capture-intake/adapters/protocols.ts": allow
"src/lib/isac/capture-intake/adapters/progression.test.ts": allow
"src/routes/isac/skillchips/+page.svelte": allow
"src/routes/isac/protocols/+page.svelte": allow
"src/routes/isac/skillchips/capture-intake.test.ts": allow
"src/routes/isac/protocols/capture-intake.test.ts": allow
"tmp/game-data-capture-plan/handoffs/GDC-020.md": allow
bash: deny
task: deny
skill:
"*": deny
---
You own GDC-020. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-018 and GDC-010 passed review.
Prefill only reviewed evidence. Resolve abilities and Attributes without fuzzy auto-selection. Keep shared Protocol profiles separate. Do not fabricate `conditionalRule`; require a reviewed contract-valid program. Preserve capacity checks, icon reset, result tokens, Contributor Mode, readiness refresh, and audit behavior.
Tests must assert audit actor, category, action, target, and complete owned relationship evidence. Write `handoffs/GDC-020.md` and do not commit or push.
.opencode/agents/gdc-isac-specializations.md
+38
View File
@@ -0,0 +1,38 @@
---
description: Adapts reviewed Specialization, Ability, Focus, assignment, tree-node, and rank drafts while protecting complete graph replacement semantics.
mode: subagent
hidden: true
model: openai/gpt-5.6-sol
variant: high
steps: 110
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"src/lib/isac/capture-intake/adapters/specializations.ts": allow
"src/lib/isac/capture-intake/adapters/specializations.test.ts": allow
"src/routes/isac/specializations/+page.svelte": allow
"src/routes/isac/specializations/capture-intake.test.ts": allow
"tmp/game-data-capture-plan/handoffs/GDC-021.md": allow
bash: deny
task: deny
skill:
"*": deny
---
You own GDC-021. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-018 and GDC-011 passed review.
Require positive parent resolution. Do not guess tree positions, rank costs, Ability targets, intrinsic attacks, or mechanics. Require a complete current-state comparison and confirmation for node updates. Pause after preparing the first action plan until the owner passes H5. Preserve canonical actions, readiness refresh, editor lifecycle, Contributor Mode, and audit behavior.
Tests must assert audit actor, category, action, target, and complete graph evidence. Write `handoffs/GDC-021.md` and do not commit or push.
.opencode/agents/gdc-isac-weapon-gear.md
+43
View File
@@ -0,0 +1,43 @@
---
description: Adapts reviewed Weapon and Gear capture drafts into existing ISAC editors while preserving validation, moderation, audit, and editor lifecycle.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"src/lib/isac/capture-intake/adapters/weapons.ts": allow
"src/lib/isac/capture-intake/adapters/gear.ts": allow
"src/lib/isac/capture-intake/adapters/weapon-gear.test.ts": allow
"src/routes/isac/weapons/+page.svelte": allow
"src/routes/isac/gear/+page.svelte": allow
"src/routes/isac/weapons/capture-intake.test.ts": allow
"src/routes/isac/gear/capture-intake.test.ts": allow
"tmp/game-data-capture-plan/handoffs/GDC-019.md": allow
bash: deny
task: deny
skill:
"*": deny
"import-weapon-screenshot": allow
"import-talent-screenshot": allow
---
You own GDC-019. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-018 and GDC-009 passed review. Read current editor and action contracts before relying on field names.
Prefill only reviewed evidence. Do not auto-select ambiguous Talents, Brands, or Attributes. Keep hidden ranges, incomplete pools, augments, and mod slots unresolved. Do not auto-submit. Preserve existing actions, result tokens, add/edit lifecycle, Contributor Mode, and audit behavior.
Tests must assert audit actor, category, action, target, and before/after relationship evidence. Write `handoffs/GDC-019.md` and do not commit or push.
.opencode/agents/gdc-openai-fallback.md
+38
View File
@@ -0,0 +1,38 @@
---
description: Implements automatic OpenAI Responses API vision fallback, structured schemas, retries, duplicate suppression, and secret-safe handling.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/vision/openai_provider.py": allow
"tools/game-data-capture/src/game_data_capture/vision/prompts.py": allow
"tools/game-data-capture/src/game_data_capture/vision/schemas.py": allow
"tools/game-data-capture/src/game_data_capture/vision/privacy.py": allow
"tools/game-data-capture/tests/unit/vision/test_openai_provider.py": allow
"tools/game-data-capture/tests/contract/test_openai_schema.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-012.md": allow
bash: deny
task: deny
---
You own GDC-012. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-007 and GDC-008 passed review. Use a fixed configurable OpenAI vision model through the Responses API with `store: false`, no tools, original image detail when supported, and strict Structured Outputs.
Automatic fallback has owner approval and no cost ceiling. Keep retries bounded and suppress duplicate requests. Send useful crops when possible. Treat local OCR as untrusted input and validate every response locally. Never log or persist keys, headers, base64 payloads, unrestricted responses, or hidden reasoning.
Use fake clients in tests. Do not run a live request without coordinator approval. Write `handoffs/GDC-012.md` and do not commit or push.
.opencode/agents/gdc-progression-items.md
+37
View File
@@ -0,0 +1,37 @@
---
description: Implements evidence extraction for Skill Chips and OS Protocols, including instance values, shared profiles, bonuses, and Talent prose.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/extractors/skill_chip.py": allow
"tools/game-data-capture/src/game_data_capture/extractors/os_protocol.py": allow
"tools/game-data-capture/tests/unit/extractors/test_skill_chip.py": allow
"tools/game-data-capture/tests/unit/extractors/test_os_protocol.py": allow
"tools/game-data-capture/tests/evaluation/test_progression_items.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-010.md": allow
bash: deny
task: deny
---
You own GDC-010. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-008 passed review. Read current Skill Chip, OS Protocol, Attribute, mechanic, and Specialization Ability contracts before editing.
Separate configured instance quality, level, rolls, and upgrades from reusable definitions. Keep the OS Protocol secondary profile separate from an individual Protocol. Capture Talent prose and values without inventing events, reducers, state, expressions, or scopes. Missing pools, endpoints, profiles, abilities, or Attributes remain unresolved.
Add ambiguity and interpolation tests. Write `handoffs/GDC-010.md` and do not commit or push.
.opencode/agents/gdc-python-core.md
+47
View File
@@ -0,0 +1,47 @@
---
description: Implements the game-data-capture Python package, configuration, diagnostics, dependency lock, and approved web and OCR dependency integration.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/pyproject.toml": allow
"tools/game-data-capture/uv.lock": allow
"tools/game-data-capture/.python-version": allow
"tools/game-data-capture/config.example.toml": allow
"tools/game-data-capture/src/game_data_capture/__init__.py": allow
"tools/game-data-capture/src/game_data_capture/__main__.py": allow
"tools/game-data-capture/src/game_data_capture/cli.py": allow
"tools/game-data-capture/src/game_data_capture/config.py": allow
"tools/game-data-capture/src/game_data_capture/paths.py": allow
"tools/game-data-capture/src/game_data_capture/logging.py": allow
"tools/game-data-capture/src/game_data_capture/doctor.py": allow
"tools/game-data-capture/tests/unit/test_config.py": allow
"tools/game-data-capture/tests/unit/test_cli.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-002.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-007.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-005.md": allow
bash: ask
task: deny
---
You own Python packaging and dependency integration. The coordinator assigns GDC-002, the dependency-integration phase of GDC-005, or the dependency-integration phase of GDC-007. Refuse implementation unless `STATUS.md` marks that task `in_progress`. Read the task and dependency handoffs before editing.
Keep imports side-effect free. Use Python 3.12 through `uv`, XDG runtime paths, typed configuration, redacted logs, and explicit dependency pins. Leave runtime and subsystem wiring to `gdc-runtime-integration`.
Do not absorb storage, OCR, web, media, or provider implementations into core modules. Request contract changes through your handoff. Add focused tests, write the task-specific handoff, and do not commit or push.
.opencode/agents/gdc-review-engine.md
+37
View File
@@ -0,0 +1,37 @@
---
description: Implements capture grouping, duplicate reuse, correction history, merge and split behavior, review states, undo, and ISAC-readiness checks.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/grouping/**": allow
"tools/game-data-capture/src/game_data_capture/review/**": allow
"tools/game-data-capture/tests/unit/grouping/**": allow
"tools/game-data-capture/tests/unit/review/**": allow
"tools/game-data-capture/tests/integration/test_review_lifecycle.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-013.md": allow
bash: deny
task: deny
---
You own GDC-013. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-009 through GDC-012 passed review.
Preserve every source and model result. Exact duplicate reuse may be automatic; semantic merges require evidence or user confirmation. Keep evidence-reviewed separate from ISAC-ready. Append correction and undo history, reject stale mutations, and block readiness for missing ranges, pools, relationships, or mechanics.
Do not edit runtime, storage, provider, extractor, or web code. Write `handoffs/GDC-013.md` and do not commit or push.
.opencode/agents/gdc-review-ui.md
+41
View File
@@ -0,0 +1,41 @@
---
description: Builds the local capture-labeling and evidence-review interface with accessible states, responsive layouts, and local-only assets.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/web/templates/**": allow
"tools/game-data-capture/src/game_data_capture/web/static/**": allow
"tools/game-data-capture/tests/integration/test_capture_labeling.py": allow
"tools/game-data-capture/tests/integration/test_review_ui.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-005.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-014.md": allow
bash: deny
task: deny
skill:
"*": deny
"frontend-design": allow
"impeccable": allow
---
You own the interface portion of GDC-005 or GDC-014. Refuse implementation unless the coordinator assigns one task, `STATUS.md` marks it `in_progress`, the backend handoff exists, and dependencies passed review. Load `frontend-design` and `impeccable` before design work. The coordinator performs browser validation with `webapp-testing`.
Build a restrained local operations interface for dense evidence review. Cover keyboard navigation, focus-visible, pending, disabled, error, success, empty, narrow, and reduced-motion states. Use text with color for state. Load no CDN asset. Never auto-arm capture, approve evidence, export, delete, or submit to ISAC.
Coordinate API needs through the handoff instead of editing backend files. Provide desktop and narrow-layout acceptance cases for coordinator browser validation, update the assigned handoff, and do not commit or push.
.opencode/agents/gdc-runtime-integration.md
+45
View File
@@ -0,0 +1,45 @@
---
description: Wires completed capture, web, OCR, provider, video, review, and export services into CLI commands and one supervised runtime.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/cli.py": allow
"tools/game-data-capture/src/game_data_capture/runtime.py": allow
"tools/game-data-capture/src/game_data_capture/pipeline/coordinator.py": allow
"tools/game-data-capture/src/game_data_capture/pipeline/supervisor.py": allow
"tools/game-data-capture/src/game_data_capture/pipeline/events.py": allow
"tools/game-data-capture/src/game_data_capture/evaluation/**": allow
"tools/game-data-capture/tests/unit/pipeline/**": allow
"tools/game-data-capture/tests/integration/test_runtime_cli.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-004.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-005.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-014.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-015.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-016.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-017.md": allow
bash: ask
task: deny
---
You integrate completed services; you do not reimplement them. The coordinator assigns one integration phase of GDC-004, GDC-005, GDC-014, GDC-015, GDC-016, or GDC-017. Refuse implementation unless `STATUS.md` marks that task `in_progress`, the subsystem owner completed its handoff section, and dependencies passed review.
Wire command and lifecycle boundaries through typed ports. Keep SQLite writes in the main process, start one GPU worker, bound provider and media work, reconcile durable jobs, and stop children in order. Aggregate subsystem evaluation interfaces into versioned reports without duplicating OCR, classifier, or extractor policy. Do not edit `pipeline/jobs.py`; `gdc-storage` owns job leases.
Append an integration section to the assigned handoff. Do not absorb subsystem policy, commit, or push.
.opencode/agents/gdc-screen-classifier.md
+38
View File
@@ -0,0 +1,38 @@
---
description: Implements offline screen-family classification, view and Gear-slot labels, composite record types, region detection, abstention, and evaluation.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
external_directory: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/vision/classifier.py": allow
"tools/game-data-capture/src/game_data_capture/vision/regions.py": allow
"tools/game-data-capture/tests/unit/vision/test_classifier.py": allow
"tools/game-data-capture/tests/unit/vision/test_regions.py": allow
"tools/game-data-capture/tests/evaluation/test_classifier.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-008.md": allow
bash: ask
task: deny
---
You own GDC-008. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, H3 selected the OCR engine, and GDC-007 passed review.
Classify family, view, exact Gear slot, record types, confidence, and abstention. Support composite screens. Use normalized geometry or detected anchors rather than fixed 4K coordinates. Evaluate by capture session and report confusion matrices, class recall, false positives, and abstention. Never call a network service.
Do not edit OCR, provider, extractor, or domain contracts. Write `handoffs/GDC-008.md` and do not commit or push.
.opencode/agents/gdc-security-reviewer.md
+32
View File
@@ -0,0 +1,32 @@
---
description: Performs independent read-only security, privacy, data-integrity, and ISAC-boundary review for the complete game-data-capture implementation.
mode: subagent
hidden: true
model: openai/gpt-5.6-sol
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tmp/game-data-capture-plan/handoffs/GDC-024.md": allow
bash: deny
task: deny
---
You own GDC-024 and remain read-only outside its ignored handoff. Refuse review unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-022 and GDC-023 passed. Report findings first, ordered by severity.
Inspect clipboard helper environments, media limits, subprocess commands, storage recovery, paths and symlinks, GPU queues, OpenAI secrets and payloads, localhost security, XSS, CSRF, archives, ISAC permissions, moderation, audit evidence, editor lifecycle, and data semantics. Read tests and identify assertions that cannot catch regressions.
Each finding needs affected files, reproduction, impact, required correction, and verification. High or critical findings block release. Recheck owner fixes and record dispositions. Do not patch implementation, commit, or push.
.opencode/agents/gdc-specializations.md
+35
View File
@@ -0,0 +1,35 @@
---
description: Implements extraction for Specialization identities, overview screens, abilities, focuses, trees, nodes, ranks, effects, and costs.
mode: subagent
hidden: true
model: openai/gpt-5.6-sol
variant: high
steps: 110
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/extractors/specialization/**": allow
"tools/game-data-capture/tests/unit/extractors/specialization/**": allow
"tools/game-data-capture/tests/evaluation/test_specializations.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-011.md": allow
bash: deny
task: deny
---
You own GDC-011. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-008 passed review. Read the full Specialization route, readiness code, Skill Chip capacity rules, mechanic contracts, and architecture documentation before editing.
Model overview screens as composite evidence. Preserve parent, coordinate, rank, effect, cost, cadence, charge, and intrinsic-damage uncertainty. Do not emit derived readiness or infer executable mechanics from prose. Link fragments only with positive identity evidence.
Test incomplete trees, scrolling, free Ability nodes, multi-rank nodes, modified Ability values, and ambiguous parents. Write `handoffs/GDC-011.md` and do not commit or push.
.opencode/agents/gdc-storage.md
+38
View File
@@ -0,0 +1,38 @@
---
description: Implements utility-local SQLite migrations, content-addressed blobs, durable jobs, provenance, recovery, safe purge behavior, and approved GDC-005 corpus persistence.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 80
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/migrations/**": allow
"tools/game-data-capture/src/game_data_capture/storage/**": allow
"tools/game-data-capture/src/game_data_capture/pipeline/jobs.py": allow
"tools/game-data-capture/tests/unit/storage/**": allow
"tools/game-data-capture/tests/integration/storage/**": allow
"tmp/game-data-capture-plan/handoffs/GDC-003.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-005.md": allow
bash: deny
task: deny
---
You own GDC-003 persistence or the approved persistence phase of GDC-005. Refuse implementation unless the coordinator assigns one task, `STATUS.md` marks it `in_progress`, and its dependencies passed review. Read the frozen contracts and dependency handoffs before editing.
Keep the utility database separate from SHD.build. Use checksummed additive migrations, foreign keys, WAL, atomic blob installation, compare-and-swap transitions, and recoverable leases. Model capture occurrences separately from blob identity. Test crashes at transaction and filesystem boundaries.
For GDC-005, implement only the reviewed durable corpus-port operations described in its task and handoff. Do not edit domain contracts, pipeline policy, routes, or application database code. Write the assigned task handoff and do not commit or push.
.opencode/agents/gdc-test-engineer.md
+37
View File
@@ -0,0 +1,37 @@
---
description: Adds cross-subsystem integration, contract, recovery, synthetic-media, secret-scanning, and ISAC workflow tests without editing production code.
mode: subagent
hidden: true
model: openai/gpt-5.3-codex-spark
variant: medium
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/tests/integration/test_end_to_end.py": allow
"tools/game-data-capture/tests/integration/test_crash_recovery.py": allow
"tools/game-data-capture/tests/integration/test_secret_exclusion.py": allow
"tools/game-data-capture/tests/fixtures/e2e/**": allow
"src/lib/isac/capture-intake/end-to-end.test.ts": allow
"tmp/game-data-capture-plan/handoffs/GDC-022.md": allow
bash: deny
task: deny
---
You own GDC-022. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and every dependency passed review. Add tests only after subsystem contracts and implementations exist. Do not repair production code; report each failure to its owner.
Use synthetic or approved fixtures. Keep proprietary screenshots and private corpus data out of Git. Test end-to-end state, restart recovery, provider failures, media bounds, numeric disagreements, secret exclusion, manager publication, Contributor Mode proposals, and canonical readback. Assert audit actor, category, action, target, and before/after relationship evidence. Ensure tests fail when intended behavior is removed.
Write `handoffs/GDC-022.md` and do not commit or push.
.opencode/agents/gdc-video-import.md
+36
View File
@@ -0,0 +1,36 @@
---
description: Implements bounded FFmpeg and ffprobe video ingestion, tiled stability analysis, sharp-frame selection, lineage, cancellation, and recovery.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/video/**": allow
"tools/game-data-capture/tests/unit/video/**": allow
"tools/game-data-capture/tests/integration/test_video_import.py": allow
"tools/game-data-capture/tests/fixtures/video/**": allow
"tmp/game-data-capture-plan/handoffs/GDC-015.md": allow
bash: ask
task: deny
---
You own GDC-015. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-008 and GDC-013 passed review.
Run FFmpeg and ffprobe with argument arrays, private paths, limits, timeouts, bounded stderr, cancellation, and process-group cleanup. Extract no audio. Use tiled motion so animated backgrounds do not hide stable UI. Preserve parent hashes, timestamps, metrics, commands, and policy versions.
Do not edit web routes, runtime integration, OCR, or storage. Use generated media fixtures. Write `handoffs/GDC-015.md` and do not commit or push.
.opencode/agents/gdc-vision-ocr.md
+39
View File
@@ -0,0 +1,39 @@
---
description: Benchmarks local GPU OCR and implements preprocessing, the persistent OCR worker, confidence calibration, and OCR evaluation.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
external_directory: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/ocr/**": allow
"tools/game-data-capture/src/game_data_capture/vision/preprocess.py": allow
"tools/game-data-capture/tests/unit/ocr/**": allow
"tools/game-data-capture/tests/unit/vision/test_preprocess.py": allow
"tools/game-data-capture/tests/gpu/**": allow
"tools/game-data-capture/tests/evaluation/test_ocr.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-007.md": allow
bash: ask
task: deny
---
You own the OCR phase of GDC-007. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and H2 passed. Do not select an OCR engine or threshold before the private corpus passes H2.
Measure exact numbers, labels, transcript accuracy, latency, VRAM, CUDA provider, model hashes, and confidence calibration. Keep raw OCR separate from normalized values. Never call a network service from local OCR.
Return dependency pin requests to `gdc-python-core`; do not edit lock files. Write the OCR section of `handoffs/GDC-007.md` and do not commit or push.
.opencode/agents/gdc-wayland-media.md
+35
View File
@@ -0,0 +1,35 @@
---
description: Implements niri and Wayland clipboard image intake, private spooling, and watcher process supervision.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/ingest/**": allow
"tools/game-data-capture/tests/unit/ingest/**": allow
"tools/game-data-capture/tests/integration/test_clipboard_watch.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-004.md": allow
bash: ask
task: deny
---
You own GDC-004. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and its dependencies passed review. Use the existing niri focused-window shortcut and `wl-paste`; do not automate game input.
Run child processes without a shell. Bound bytes, dimensions, stderr, queues, retries, and shutdown. Keep the clipboard helper small and remove OpenAI secrets from its environment. Request coordinator approval for live clipboard or compositor commands; never read clipboard text.
Do not edit storage, OCR, provider, video, or web code. Add failure tests, write `handoffs/GDC-004.md`, and do not commit or push.
.opencode/agents/gdc-weapon-gear.md
+40
View File
@@ -0,0 +1,40 @@
---
description: Implements evidence-preserving extraction for weapons and Gear across Mask, Gloves, Backpack, Body Armor, Holster, and Knee Pads.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: medium
steps: 90
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/extractors/weapon.py": allow
"tools/game-data-capture/src/game_data_capture/extractors/gear.py": allow
"tools/game-data-capture/tests/unit/extractors/test_weapon.py": allow
"tools/game-data-capture/tests/unit/extractors/test_gear.py": allow
"tools/game-data-capture/tests/evaluation/test_weapon_gear.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-009.md": allow
bash: deny
task: deny
skill:
"*": deny
"import-weapon-screenshot": allow
---
You own GDC-009. Refuse implementation unless the coordinator assigns it, `STATUS.md` marks it `in_progress`, and GDC-008 passed review. Read the current Weapon and Gear actions, scaling documentation, and weapon screenshot import skill before editing.
Preserve displayed values as observations until evidence establishes canonical endpoints. Treat weapon Talent grids as complete unordered sets and mark cropped lists incomplete. Use exact Gear slot rules. Do not guess Talent, Brand, or Attribute IDs, hidden ranges, native tiers, mod slots, or compatibility pools.
Add per-slot and per-view regression tests. Write `handoffs/GDC-009.md` and do not commit or push.
.opencode/agents/gdc-web-service.md
+39
View File
@@ -0,0 +1,39 @@
---
description: Implements the loopback FastAPI service, authenticated local sessions, capture and review APIs, request bounds, and browser security.
mode: subagent
hidden: true
model: openai/gpt-5.6-terra
variant: high
steps: 100
permission:
"*": deny
read:
"*": allow
"*.env": deny
"*.env.*": deny
"*.env.example": allow
"data/**": deny
"**/data/**": deny
"**/*.db": deny
"**/*.db-*": deny
glob: allow
grep: ask
edit:
"*": deny
"tools/game-data-capture/src/game_data_capture/web/*.py": allow
"tools/game-data-capture/src/game_data_capture/web/routes/**": allow
"tools/game-data-capture/tests/unit/web/**": allow
"tools/game-data-capture/tests/integration/test_capture_labeling.py": allow
"tools/game-data-capture/tests/integration/test_web_security.py": allow
"tools/game-data-capture/tests/integration/test_review_ui.py": allow
"tmp/game-data-capture-plan/handoffs/GDC-005.md": allow
"tmp/game-data-capture-plan/handoffs/GDC-014.md": allow
bash: deny
task: deny
---
You own the backend portion of GDC-005 or GDC-014. Refuse implementation unless the coordinator assigns one task, `STATUS.md` marks it `in_progress`, and its dependencies passed review. Bind only to loopback and defend against DNS rebinding, cross-origin mutation, CSRF, XSS, path traversal, oversized uploads, and unauthorized artifacts.
Use opaque IDs and escaped text. Keep paths, keys, cookies, database internals, and unrestricted OCR/provider content out of responses. Do not embed SQL in routes or duplicate domain policy.
Coordinate route contracts with `gdc-review-ui`, but do not edit templates or static assets. Add failure-path tests, update the assigned handoff, and do not commit or push.
AGENTS.md
+9 -27
View File
@@ -115,39 +115,21 @@ need database state use the embedded Turso engine.
- **ISAC namespace**: `/isac` is the admin console; `/admin` redirects there
via 308.
## Long-running development processes
Use the installed `pi-background-tasks` extension's `bg_run` tool for
development servers, watchers, and other persistent commands. Do not use
foreground shell sessions, `nohup`, `&`, or process-tree/PID discovery when a
tracked task exists.
- Use `isAgent: false` and a concise, descriptive task name.
- Retain the returned task ID and output path. Inspect a task with `bg_status`
and read its output with `bg_logs`.
- Stop a task with `bg_kill <task-id>`. To restart it, start a new `bg_run` task
and retain its new task ID and output path; do not search for and kill
processes.
- Do not leave duplicate tracked tasks for the same development service.
## Development server lifecycle
After changing source code, styles, configuration, dependencies, or routes,
restart the development server before handing work back.
1. Start `npm run dev` from the repository root with `bg_run`, using
`isAgent: false` and a descriptive task name. Retain its task ID and output
path.
2. Before starting a replacement, stop the existing tracked development-server
task with `bg_kill <task-id>` so only one server runs.
3. Confirm the task logs show the server started, then confirm it accepts an
HTTP request before completing the task.
4. Leave the verified tracked task running so the project owner can review the
changes.
1. Inspect running processes and stop only this project's development-server
process tree.
2. Start one hidden `npm run dev` process from the repository root. Do not leave
duplicate project development servers running.
3. Confirm the server accepts an HTTP request before completing the task.
4. Leave the verified development server running so the project owner can review
the changes.
Database maintenance may require the server to remain stopped while the embedded
database is locked. Stop its tracked task first, then restart and verify it
after maintenance completes.
database is locked. Restart and verify the server after maintenance completes.
## SHD design-system maintenance
@@ -263,7 +245,7 @@ database. The command refuses to merge into a populated database.
## Development database maintenance
1. Stop this project's tracked development-server task with `bg_kill <task-id>`.
1. Stop only this project's development-server process tree.
2. Run and verify `npm run db:backup`. Retain and report the backup path.
3. Apply the migration or maintenance operation. Verify schema state, record
counts, and critical entities.
deploy/compose.production.yml
+2 -2
View File
@@ -3,7 +3,7 @@ name: shd-build-production
services:
app:
image: ${SHD_IMAGE:-shd-build-production:local}
restart: always
restart: unless-stopped
init: true
environment:
INFISICAL_PROJECT_ID: 2ee94b27-e599-4194-9797-3372d42e53f6
@@ -42,7 +42,7 @@ services:
scheduler:
image: ${SHD_IMAGE:-shd-build-production:local}
restart: always
restart: unless-stopped
init: true
command:
- scheduler
deploy/runtime-start.test.ts
-5
View File
@@ -142,10 +142,6 @@ describe('container runtime startup', () => {
{ key: 'APP_ORIGIN', value: 'https://exported.invalid' },
{ key: 'DISCORD_CLIENT_ID', value: 'exported-discord-client' },
{ key: 'DISCORD_CLIENT_SECRET', value: 'exported-discord-secret' },
{
key: 'MFA_TOTP_ENCRYPTION_KEYS',
value: 'totp-encryption-keyring',
},
]),
writeExport(sharedExport, [
{ key: 'SCHEDULER_TOKEN', value: schedulerToken },
@@ -224,7 +220,6 @@ describe('container runtime startup', () => {
APP_ORIGIN: 'https://stage.shd.build',
DISCORD_CLIENT_ID: 'exported-discord-client',
DISCORD_CLIENT_SECRET: 'exported-discord-secret',
MFA_TOTP_ENCRYPTION_KEYS: 'totp-encryption-keyring',
ORIGIN: 'https://stage.shd.build',
PASSKEY_RP_ID: 'shd.build',
SCHEDULER_TOKEN: schedulerToken,
docs/DESIGN_SYSTEM.md
+37 -37
View File
@@ -2390,11 +2390,9 @@ display `ADVANCED`, and stay visible in the generated script. State rows expose
label, agent or target scope, initial value, bounds, best-case value, and
optional expiry. A state change that writes a target pool uses a `STATE OWNER`
segmented control with `EVENT TARGET` and `EVENT ACTOR`; the selected owner
remains visible in the generated script. The `DERIVED VALUE` operation writes
the branch reducer's numeric result into the selected pool and displays that
link as a text readout instead of a numeric input. Outcome rows expose kind,
target scope, Attribute or resource when applicable, value basis, state scaling,
phase, and every source-specific value column. The Value Model control supports
remains visible in the generated script. Outcome rows expose kind, target scope,
Attribute or resource when applicable, value basis, state scaling, phase, and
every source-specific value column. The Value Model control supports static
values, live Attribute totals, percentage-normalized Attribute values, event
fields, reducer output, source-defined scenario controls, and OS Protocol
upgrade scaling where the source permits it. Selecting either Attribute model
@@ -2406,15 +2404,6 @@ applied to the stored value. Restoration outcomes also expose an `INSTANT` or
field and describes the configured value as the total delivered across that
duration; switching back to instant clears the duration.
Selecting `DERIVE A SCALAR VALUE` exposes a `DERIVED VALUE SOURCE`
`SegmentedChoice`. `STATIC` shows the numeric value input. `EVENT FIELD` shows
the numeric fields registered for the branch event, including the proximity
snapshot's allied-Agent count; it never asks the author to type a field path.
Keep an existing expression that falls outside these manual patterns visible as
disabled `ADVANCED` data. The source and field controls retain `SegmentedChoice`
radio semantics, visible legends, arrow-key operation, focus-visible treatment,
and text labels.
Target-scoped direct-damage outcomes offer `HIT-TARGET EXPLOSION` in the Area
Targeting control. Selecting it creates an event-target-centered enemy area with
a five-meter starting radius, reveals the required radius field, and shows a
@@ -2432,15 +2421,13 @@ source program, where authors may edit its exposed branch, state, and outcome
controls. The recipe label records provenance only. `REPLACE PROGRAM` requires
an inline confirmation that states all existing branches will be discarded.
Builder Controls define source-specific scenario assumptions for player
simulation. ISAC authors choose toggle, slider, or numeric input and provide a
label, Agent guidance, default value, best-case value, and numeric bounds when
applicable. The calculation timeline builder can consume values supplied for
these controls, including `allies-within-30m-with-agent-granted-buff`. Current
Builder and shared Build pages do not render the controls or let players change
those values. They use an explicit `COMING SOON` panel for the future advanced
scenario surface. The authored contract still requires the runtime to report
`REQUIRES ASSUMPTIONS` when a required cadence or environmental value is
Builder Controls define source-specific scenario assumptions for the planned
player simulation. ISAC authors choose toggle, slider, or numeric input and
provide a label, Agent guidance, default value, best-case value, and numeric
bounds when applicable. The current player UI does not render these controls or
read their saved values. It uses an explicit `COMING SOON` panel for the future
advanced scenario surface. The authored contract still requires the runtime to
report `REQUIRES ASSUMPTIONS` when a required cadence or environmental value is
missing; the editor and runtime never invent a cadence.
Use `--shd-model-surface` and `--shd-model-border` for mechanic programs,
@@ -2491,10 +2478,7 @@ The panel presents five explicit states:
polite live region, and disables repeat actions.
- `CLARIFICATION REQUIRED` lists each focused question with its reason and
bounded answer control. The author may answer, revise the source text, or
return to manual authoring. For an unresolved numbered numeric placeholder,
show a required clarification for every source value column whose number is
missing. Do not prefill, infer, or suggest a percentage. Keep
`APPLY TO EDITOR` unavailable until the author answers each required variant.
return to manual authoring.
- `CAPABILITY GAP` names the unsupported behavior and displays the developer
handoff, supported approximation, and optional workaround in separate labeled
blocks. Do not present a capability gap as validation failure.
@@ -2518,13 +2502,6 @@ applying the draft would replace configured branches, pools, controls, or
outcomes. The standard ISAC save lifecycle begins only after the author reviews
and saves the resulting form.
An applied AI draft stores each clarified number in the corresponding
human-facing outcome-variant value. A scaling expression may retain the
draft-only `variant_value` reference so later saves preserve the link to that
displayed value. The runtime adapter resolves the reference separately for each
variant. Show the value and generated formula in the ordinary review controls;
do not require an author to inspect or edit raw JSON.
Use text labels with status colors. Orange marks Generate, Answer, and Apply
actions. Blue identifies modeled information, yellow marks assumptions or
unsupported coverage, and red marks request or validation failures. Never use
@@ -2618,10 +2595,33 @@ anchor scrolling and sticky-state transitions.
#### Builder calculation modes
The current Builder and shared Build pages do not expose calculation modes or
combat assumptions. They show deterministic equipped-item totals and reserve
conditional Talent outcomes, weapon and Skill DPS, encounter assumptions,
combat assumptions. The Builder summary rail additionally contains one local
experimental catalog baseline panel; shared Build pages do not render it. Keep
the panel in the summary rail only, with two independent cards labeled `PRIMARY`
and `SECONDARY`.
Use the exact eyebrow `WEAPON OUTPUT / CATALOG BASELINE` and show the
`EXPERIMENTAL` state. Each card displays the catalog weapon ID, selected damage,
catalog RPM, magazine, reload, rated body-hit throughput, and magazine-cycle
body-hit throughput. Include a visible formula and exclusions block with these
exact formulas:
- `selected damage × (RPM ÷ 60)` for rated body-hit throughput;
- `(magazine × selected damage) ÷ ((magazine ÷ (RPM ÷ 60)) + reload seconds)`
for magazine-cycle body-hit throughput.
The panel is evidence-only. It excludes inferred or substituted values, combat
profiles, effects, Talents, Attribute totals, calculation profiles, accuracy,
critical hits, headshots, enemy mitigation, target count, encounter uptime,
rotations, and simulation. It must not present these values as actual, expected,
or encounter DPS. When a required source value is unavailable or invalid, show
`NOT AVAILABLE` and list the missing source fields under the metric; never
display zero as a placeholder.
The panel does not alter the planned calculation modes or full combat panels.
Keep conditional Talent outcomes, weapon and Skill DPS, encounter assumptions,
activation profiles, rotations, and simulation behind explicit `COMING SOON`
panels.
panels. Calculation modes remain planned and use these visible labels:
Loadout schema version 6 retains `maximum`, `custom`, conditional state,
encounter-assumption, and per-ability activation fields. Version 4 is obsolete
docs/DPS_SIMULATION_PROTOTYPE.md
+41
View File
@@ -0,0 +1,41 @@
# Weapon baseline prototype
## Scope
`calculateWeaponBaseline` is a pure, client-safe Builder helper. It records
weapon ID, name, and label, then reports three evidence-only metrics:
- `selectedDamage`: the supplied positive finite damage value.
- `ratedBodyHitThroughput`: `selectedDamage × rpm / 60`.
- `magazineCycleBodyHitThroughput`:
`(selectedDamage × magazine) / (magazine / (rpm / 60) + reloadSeconds)`.
Unknown, absent, non-positive, non-finite, or invalid source values make only
the metrics that depend on them unavailable. The helper preserves decimal inputs
and does not substitute values.
These are not actual, expected, or encounter DPS. They contain no hit
probability, critical or headshot outcomes, target state, or encounter timeline.
The rated metric is nominal continuous body-hit throughput; the magazine-cycle
metric includes the supplied reload interval.
## Excluded inputs
This helper does not read combat profiles, effects, talents, Attribute totals,
calculation profiles, encounter assumptions, or any other build inputs. It does
not call the simulation or combat engines.
`selectedDamage` is already the equipped weapon damage used at this boundary. It
is consumed exactly once; no additional level scaling or damage scaling is
applied.
## Missing data for a DPS model
A valid DPS model still needs the authoritative damage calculation and its
modifiers, hit and critical/headshot assumptions, firing and reload behavior,
target and encounter assumptions, and the timing and contribution of talents,
effects, Attributes, skills, and weapon swaps. Those data are outside this
baseline.
This is Builder-only, local prototype work. It does not define the player DPS
simulation contract or change the existing calculation architecture.
docs/TALENT_MECHANIC_RULES.md
-18
View File
@@ -79,24 +79,6 @@ meters:
duration.
- The wearer does not count as an ally.
## Close and Personal
Close and Personal uses a proximity-snapshot qualifying set:
- Include each distinct allied Agent whose distance from the source Agent is
less than or equal to 30 meters and who has at least one buff granted by that
source Agent.
- Count an ally once when several of the source Agent's buffs qualify.
- Do not include an ally whose qualifying buffs come only from other sources.
Record the resolved non-negative integer count in
`proximity_snapshot.values.alliesWithin30MetersWithAgentGrantedBuff`. The
calculation builder supplies it from the
`allies-within-30m-with-agent-granted-buff` scenario input. The confirmed rule
defines this qualifying set but does not provide Close and Personal's base
percentage. Keep that percentage unresolved until source evidence or an author's
clarification supplies it.
## Emergency Retreat
Emergency Retreat activates whenever at least one enemy is within 20 meters and
docs/architecture.md
+23 -49
View File
@@ -25,12 +25,16 @@ The team builds the project in vertical slices.
Server code checks authorization for each mutation. UI visibility has no effect
on server authorization.
Builder and shared Build pages currently expose only deterministic totals from
the equipped items, selected rolls, fixed bonuses, inherited profiles, augments,
and active set bonuses. Conditional Talent outcomes, weapon and Skill DPS,
encounter assumptions, activation profiles, rotations, and simulation remain
planned. Explicit `COMING SOON` panels identify those player-facing
capabilities.
Builder and shared Build pages expose deterministic totals from the equipped
items, selected rolls, fixed bonuses, inherited profiles, augments, and active
set bonuses. Builder additionally shows an experimental catalog baseline for
each selected weapon: body-hit throughput from selected weapon damage and
catalog RPM, magazine, and reload values only. It is not expected or encounter
DPS, does not infer or substitute missing values, reports blocked metrics with
their source fields, and does not change shared Build behavior. Conditional
Talent outcomes, full weapon and Skill DPS, encounter assumptions, activation
profiles, rotations, and simulation remain planned. Explicit `COMING SOON`
panels identify those player-facing capabilities.
Weapon and gear range calculations must preserve decimal endpoints and follow
the tested progression rules in
@@ -638,24 +642,12 @@ normalized events are `shot_fired`, `weapon_hit`, `skill_deployed`,
`weapon_swapped`, and `tick`. Event details such as target, distance, critical
state, source, movement, and nearby counts travel as typed event values. The
event registry publishes authoritative field metadata where branches need a
bounded contract. For those events, the mechanic editor derives event-field
conditions and manual derived-scalar controls from that metadata.
`proximity_snapshot.values.alliesWithin30MetersWithAgentGrantedBuff` is an
optional non-negative integer. It contains the resolved count of distinct allied
Agents at a distance less than or equal to 30 meters who have at least one buff
granted by the source Agent. Several qualifying buffs on one ally count once.
`proximity_snapshot` remains non-strict, so saved mechanic data and producers
that omit the field remain compatible.
`src/lib/builder/loadout-combat.ts` bridges the calculation scenario input
`allies-within-30m-with-agent-granted-buff` into that field on each generated
`proximity_snapshot`. For example, a derived-scalar reducer can select the
registered numeric field without requiring a hand-entered path. Other registered
metadata includes `weapon_hit.values.headshot`, a boolean that distinguishes
headshots from body shots. `enemy_killed` and `assist` may carry
`values.assignedAbilityActive`; a Skill Chip Talent uses that boolean to
restrict a kill or assist trigger to its assigned ability's active period.
`skill_deployed` and `signature_ability_deployed` may carry
bounded contract. For those events, the mechanic editor derives its event-field
controls from that metadata. For example, `weapon_hit.values.headshot` is a
boolean that distinguishes headshots from body shots. `enemy_killed` and
`assist` may carry `values.assignedAbilityActive`; a Skill Chip Talent uses that
boolean to restrict a kill or assist trigger to its assigned ability's active
period. `skill_deployed` and `signature_ability_deployed` may carry
`values.assignedAbilityDurationSeconds` to start assigned-ability state. The
runtime expires that state before it evaluates another event at the same
timestamp.
@@ -719,20 +711,11 @@ The program graph uses three child tables:
rolls separately. Restoration outcomes may deliver their total immediately or
continuously over an explicit duration.
Draft outcome expressions may use `{"ref":{"source":"variant_value"}}`. This
reference belongs to the conditional draft grammar and does not enter the
runtime expression grammar. Each persisted outcome-variant row keeps its
human-facing numeric `value`, while `value_expression_json` preserves the
reference and its semantic link. The adapters in
`src/lib/calculations/mechanic-editor.ts` and
`src/lib/calculations/mechanic-persistence.ts` resolve the reference from the
current row's `value` when they construct a runtime program.
Target-scoped direct damage may use `event_target_area` targeting for an
explosion around its event target. This targeting selects valid enemies and
stores a positive radius in meters. It is valid only for `on_event` or
`after_event` outcomes. The legacy `within_radius` shape remains descriptive
targeting metadata and does not select runtime entities.
Target-scoped direct damage may use `event_target_area` targeting for an
explosion around its event target. This targeting selects valid enemies and
stores a positive radius in meters. It is valid only for `on_event` or
`after_event` outcomes. The legacy `within_radius` shape remains descriptive
targeting metadata and does not select runtime entities.
The generic runtime in `src/lib/calculations/mechanic.ts` processes combat
events in timestamp order. Predicates decide whether an event enters a clause.
@@ -821,13 +804,6 @@ descriptions, and calculation metadata. The client cannot replace the system
instructions, choose arbitrary models, attach files, add tools, or add external
URLs.
When source wording contains an unresolved numbered numeric placeholder, the
assistant must return `clarification_required` and ask for the value of every
required source variant. It must not infer a percentage or other numeric value.
After clarification, the draft places each answer in the corresponding
outcome-variant `value`; any scaling expression uses the draft-only
`variant_value` reference instead of repeating that number.
The deterministic draft parser owns the canonical outcome-capability manifest.
The AI context serializes that manifest instead of maintaining a second outcome
grammar. The parser rejects outcome fields absent from the manifest. Contract
@@ -924,10 +900,8 @@ events remain the evidence for revision saves and activation.
Source authors define planned player scenario controls as typed toggle, slider,
or numeric inputs. Each input records its label, guidance, bounds when
applicable, default value, and best-case value. ISAC retains these definitions
for continued mechanic authoring, and the calculation timeline builder can
consume scenario values supplied by calculation orchestration. Current Builder
and shared Build pages do not expose those controls or invoke the simulation.
Their calculation panels display `COMING SOON` instead.
for continued mechanic authoring. Current Builder and shared Build pages do not
render or evaluate them. Their calculation panels display `COMING SOON` instead.
Loadout schema version 6 stores one focus, selected tree ranks, nine Skill
Chips, independent T1/T2 choices for each equipped gear and weapon Talent, a
paseo.json
-5
View File
@@ -1,5 +0,0 @@
{
"worktree": {
"setup": "npm install"
}
}
scripts/runtime-launcher.mjs
-1
View File
@@ -14,7 +14,6 @@ const APP_SECRET_NAMES = new Set([
'OPENAI_MECHANIC_MODEL',
'OPENAI_MECHANIC_REASONING_EFFORT',
'OPENAI_MODERATION_API_KEY',
'MFA_TOTP_ENCRYPTION_KEYS',
'ORIGIN',
'PASSKEY_RP_ID',
'REMOVE_BG_API_KEY',
src/hooks.server.ts
-10
View File
@@ -1,4 +1,3 @@
import { dev } from '$app/environment';
import { json, type Handle, type HandleServerError } from '@sveltejs/kit';
import { stringify } from 'devalue';
import { randomUUID } from 'node:crypto';
@@ -16,15 +15,6 @@ import {
} from '$lib/server/data-moderation';
export const handle: Handle = async ({ event, resolve }) => {
// THROWAWAY PROTOTYPE: fixture-only review must not open the shared database.
if (
dev &&
event.url.pathname === '/database' &&
event.url.searchParams.get('prototype') === 'model-status'
) {
return resolve(event);
}
if (
event.url.pathname === '/admin' ||
event.url.pathname.startsWith('/admin/')
src/lib/builder/loadout-combat.test.ts
-32
View File
@@ -176,38 +176,6 @@ describe('loadout mechanic timeline', () => {
).toBe(true);
});
it('emits the Agent-granted-buff ally count from its exact scenario input and defaults it to zero', () => {
const profile = createDraft().combatProfile;
profile.encounterSeconds = 1;
const configured = buildWeaponMechanicTimeline(
{ rpm: 60, magazine: 100, reload_speed: 0 },
profile,
0,
{
scenarioInputs: {
'allies-within-30m-with-agent-granted-buff': 4,
'allies-within-radius': 2,
},
},
).filter((event) => event.kind === 'proximity_snapshot');
const defaults = buildWeaponMechanicTimeline(
{ rpm: 60, magazine: 100, reload_speed: 0 },
profile,
).filter((event) => event.kind === 'proximity_snapshot');
expect(
configured.map(
(event) => event.values?.alliesWithin30MetersWithAgentGrantedBuff,
),
).toEqual([4, 4]);
expect(configured.map((event) => event.values?.allyCount)).toEqual([2, 2]);
expect(
defaults.map(
(event) => event.values?.alliesWithin30MetersWithAgentGrantedBuff,
),
).toEqual([0, 0]);
});
it('seeds Extra Health state before periodic stack evaluation', () => {
const profile = createDraft().combatProfile;
profile.encounterSeconds = 2;
src/lib/builder/loadout-combat.ts
-7
View File
@@ -7,8 +7,6 @@ import {
} from '$lib/calculations/combat';
import {
evaluateMechanicProgram,
PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_VALUE_KEY,
PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_INPUT,
type MechanicCombatContext,
type MechanicEvaluation,
type MechanicEvent,
@@ -805,11 +803,6 @@ export function buildWeaponMechanicTimeline(
allyCount: Number(
options.scenarioInputs?.['allies-within-radius'] ?? 0,
),
[PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_VALUE_KEY]: Number(
options.scenarioInputs?.[
PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_INPUT
] ?? 0,
),
},
});
events.push({
src/lib/builder/weapon-baseline.test.ts
+146
View File
@@ -0,0 +1,146 @@
import { describe, expect, it } from 'vitest';
import {
calculateWeaponBaseline,
type WeaponBaselineInput,
} from './weapon-baseline.js';
const input = (
overrides: Partial<WeaponBaselineInput> = {},
): WeaponBaselineInput => ({
weaponId: 'weapon-17',
weaponName: 'Evidence Rifle',
weaponLabel: 'PRIMARY',
selectedDamage: 12.75,
rpm: 137.5,
magazine: 31,
reloadSeconds: 2.35,
...overrides,
});
describe('calculateWeaponBaseline', () => {
it('preserves decimal inputs in the selected and rated metrics', () => {
const baseline = calculateWeaponBaseline(input());
expect(baseline.selectedDamage).toEqual({ value: 12.75, missing: [] });
expect(baseline.ratedBodyHitThroughput).toEqual({
value: 29.21875,
missing: [],
});
});
it('keeps rated throughput available when reload inputs are missing', () => {
const baseline = calculateWeaponBaseline(
input({ magazine: undefined, reloadSeconds: undefined }),
);
expect(baseline.ratedBodyHitThroughput).toEqual({
value: 29.21875,
missing: [],
});
expect(baseline.magazineCycleBodyHitThroughput).toEqual({
value: null,
missing: [
'magazine is unavailable for weapon weapon-17',
'reloadSeconds is unavailable for weapon weapon-17',
],
});
});
it('uses the complete magazine-cycle formula without rounding', () => {
const baseline = calculateWeaponBaseline(
input({
selectedDamage: 13.25,
rpm: 97.5,
magazine: 17.5,
reloadSeconds: 2.75,
}),
);
const expected = (13.25 * 17.5) / (17.5 / (97.5 / 60) + 2.75);
expect(baseline.magazineCycleBodyHitThroughput).toEqual({
value: expected,
missing: [],
});
});
it('uses selected damage exactly once at the no-double-scaling boundary', () => {
const baseline = calculateWeaponBaseline(
input({ selectedDamage: 12.5, rpm: 120, magazine: 10, reloadSeconds: 5 }),
);
expect(baseline.selectedDamage.value).toBe(12.5);
expect(baseline.ratedBodyHitThroughput.value).toBe(12.5 * (120 / 60));
expect(baseline.magazineCycleBodyHitThroughput.value).toBe(
(12.5 * 10) / (10 / (120 / 60) + 5),
);
expect(baseline.ratedBodyHitThroughput.value).not.toBe(
12.5 * 12.5 * (120 / 60),
);
expect(baseline.magazineCycleBodyHitThroughput.value).not.toBe(12.5 * 12.5);
});
it.each([
null,
undefined,
0,
-1,
Number.NaN,
Number.POSITIVE_INFINITY,
Number.NEGATIVE_INFINITY,
])('rejects invalid selected damage: %s', (selectedDamage) => {
const baseline = calculateWeaponBaseline(input({ selectedDamage }));
expect(baseline.selectedDamage.value).toBeNull();
expect(baseline.ratedBodyHitThroughput.value).toBeNull();
expect(baseline.magazineCycleBodyHitThroughput.value).toBeNull();
expect(baseline.selectedDamage.missing[0]).toContain('selectedDamage');
expect(baseline.selectedDamage.missing[0]).toContain('weapon-17');
for (const metric of [
baseline.selectedDamage,
baseline.ratedBodyHitThroughput,
baseline.magazineCycleBodyHitThroughput,
]) {
expect(metric.value).toBeNull();
expect(metric.value).not.toBeNaN();
expect(metric.value).not.toBe(Infinity);
expect(metric.value).not.toBe(-Infinity);
}
});
it.each([
['rpm', null],
['rpm', 0],
['rpm', Number.NaN],
['magazine', -1],
['reloadSeconds', Number.POSITIVE_INFINITY],
] as const)(
'makes only dependent metrics unavailable for invalid %s',
(field, value) => {
const baseline = calculateWeaponBaseline(input({ [field]: value }));
expect(baseline.selectedDamage.value).toBe(12.75);
if (field === 'rpm') {
expect(baseline.ratedBodyHitThroughput.value).toBeNull();
expect(baseline.magazineCycleBodyHitThroughput.value).toBeNull();
} else if (field === 'magazine' || field === 'reloadSeconds') {
expect(baseline.ratedBodyHitThroughput.value).toBe(29.21875);
expect(baseline.magazineCycleBodyHitThroughput.value).toBeNull();
}
const dependent =
field === 'rpm'
? [
baseline.ratedBodyHitThroughput,
baseline.magazineCycleBodyHitThroughput,
]
: [baseline.magazineCycleBodyHitThroughput];
for (const metric of dependent) {
expect(metric.value).not.toBeNaN();
expect(metric.value).not.toBe(Infinity);
expect(metric.value).not.toBe(-Infinity);
expect(metric.missing[0]).toContain(field);
expect(metric.missing[0]).toContain('weapon-17');
}
},
);
});
src/lib/builder/weapon-baseline.ts
+112
View File
@@ -0,0 +1,112 @@
type NumericSource = number | null | undefined;
export type WeaponBaselineInput = {
weaponId: string;
weaponName: string;
weaponLabel: string;
selectedDamage?: NumericSource;
rpm?: NumericSource;
magazine?: NumericSource;
reloadSeconds?: NumericSource;
};
export type BaselineMetric = {
value: number | null;
missing: string[];
};
export type WeaponBaseline = {
weaponId: string;
weaponName: string;
weaponLabel: string;
selectedDamage: BaselineMetric;
ratedBodyHitThroughput: BaselineMetric;
magazineCycleBodyHitThroughput: BaselineMetric;
};
const isPositiveFinite = (value: NumericSource): value is number =>
typeof value === 'number' && Number.isFinite(value) && value > 0;
const missingField = (field: string, weaponId: string): string =>
`${field} is unavailable for weapon ${weaponId}`;
const unavailableMetric = (
fields: string[],
weaponId: string,
): BaselineMetric => ({
value: null,
missing: fields.map((field) => missingField(field, weaponId)),
});
const calculatedMetric = (
value: number,
metricField: string,
weaponId: string,
): BaselineMetric =>
Number.isFinite(value)
? { value, missing: [] }
: { value: null, missing: [missingField(metricField, weaponId)] };
export function calculateWeaponBaseline(
input: WeaponBaselineInput,
): WeaponBaseline {
const damageAvailable = isPositiveFinite(input.selectedDamage);
const rpmAvailable = isPositiveFinite(input.rpm);
const magazineAvailable = isPositiveFinite(input.magazine);
const reloadAvailable = isPositiveFinite(input.reloadSeconds);
const damage = damageAvailable ? (input.selectedDamage as number) : null;
const rpm = rpmAvailable ? (input.rpm as number) : null;
const magazine = magazineAvailable ? (input.magazine as number) : null;
const reloadSeconds = reloadAvailable
? (input.reloadSeconds as number)
: null;
const selectedDamage =
damage !== null
? calculatedMetric(damage, 'selectedDamage', input.weaponId)
: unavailableMetric(['selectedDamage'], input.weaponId);
const ratedBodyHitThroughput =
damage !== null && rpm !== null
? calculatedMetric(
(damage * rpm) / 60,
'ratedBodyHitThroughput',
input.weaponId,
)
: unavailableMetric(
[
...(!damageAvailable ? ['selectedDamage'] : []),
...(!rpmAvailable ? ['rpm'] : []),
],
input.weaponId,
);
const magazineCycleBodyHitThroughput =
damage !== null &&
rpm !== null &&
magazine !== null &&
reloadSeconds !== null
? calculatedMetric(
(damage * magazine) / (magazine / (rpm / 60) + reloadSeconds),
'magazineCycleBodyHitThroughput',
input.weaponId,
)
: unavailableMetric(
[
...(!damageAvailable ? ['selectedDamage'] : []),
...(!rpmAvailable ? ['rpm'] : []),
...(!magazineAvailable ? ['magazine'] : []),
...(!reloadAvailable ? ['reloadSeconds'] : []),
],
input.weaponId,
);
return {
weaponId: input.weaponId,
weaponName: input.weaponName,
weaponLabel: input.weaponLabel,
selectedDamage,
ratedBodyHitThroughput,
magazineCycleBodyHitThroughput,
};
}
src/lib/calculations/mechanic-editor.test.ts
-104
View File
@@ -2,13 +2,11 @@ import { describe, expect, it } from 'vitest';
import {
currentHealthPercentBandPredicate,
eventFieldComparisonPredicate,
eventFieldNumericExpression,
mechanicTargetingForMode,
mechanicTargetingMode,
parseConditionalMechanicDraft,
readCurrentHealthPercentBand,
readEventFieldComparison,
readEventFieldNumericExpression,
registeredEventFields,
readStatePoolThreshold,
statePoolThresholdPredicate,
@@ -204,108 +202,6 @@ describe('conditional mechanic authoring payload', () => {
});
});
it('round-trips the registered proximity count as a derived scalar and resolves each variant display value', () => {
const path = 'values.alliesWithin30MetersWithAgentGrantedBuff';
expect(registeredEventFields('proximity_snapshot')).toContainEqual({
path,
label: 'Allies within 30 meters with an Agent-granted buff',
type: 'number',
minimum: 0,
integer: true,
});
const expression = eventFieldNumericExpression(path);
expect(readEventFieldNumericExpression(expression)).toBe(path);
expect(
readEventFieldNumericExpression({
op: 'multiply',
left: expression,
right: 2,
}),
).toBeNull();
const value = draft();
value.clauses[0].event = 'proximity_snapshot';
value.clauses[0].recipeKey = undefined;
value.clauses[0].reducer = {
kind: 'derived_scalar',
value: expression,
};
value.clauses[0].mutations = [
{
kind: 'derive',
pool: 'effect',
value: { ref: { source: 'reducer' } },
},
];
const upgradeScale = {
op: 'add' as const,
left: 1,
right: {
op: 'divide' as const,
left: {
ref: {
source: 'equipment' as const,
path: 'protocolTalentUpgrades',
},
},
right: 5,
},
};
value.clauses[0].outcomes[0].variants = {
I: {
value: 7.25,
expression: {
op: 'multiply',
left: { ref: { source: 'variant_value' } },
right: upgradeScale,
},
},
II: {
value: 9.5,
expression: {
op: 'multiply',
left: { ref: { source: 'variant_value' } },
right: upgradeScale,
},
},
};
const result = parseConditionalMechanicDraft(value, {
variantKeys: ['I', 'II'],
allowedAttributeIds: new Set(['weapon-damage']),
});
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(result.value.draft.clauses[0]).toMatchObject({
event: 'proximity_snapshot',
reducer: { kind: 'derived_scalar', value: expression },
outcomes: [
{
variants: {
I: {
value: 7.25,
expression: {
left: { ref: { source: 'variant_value' } },
},
},
},
},
],
});
expect(result.value.programs.I.clauses[0].outcomes?.[0].value).toEqual({
op: 'multiply',
left: 7.25,
right: upgradeScale,
});
expect(result.value.programs.II.clauses[0].outcomes?.[0].value).toEqual({
op: 'multiply',
left: 9.5,
right: upgradeScale,
});
});
it('exposes assigned-ability activity for kill and assist event conditions', () => {
expect(registeredEventFields('enemy_killed')).toEqual(
expect.arrayContaining([
src/lib/calculations/mechanic-editor.ts
+3 -105
View File
@@ -39,28 +39,9 @@ export type ConditionalMechanicPoolDraft = PoolDefinition & {
expiresAfterSecondsVariants?: Record<string, number>;
};
export type ConditionalMechanicValueReference =
ValueReference | { source: 'variant_value' };
export type ConditionalNumericExpression =
| number
| { ref: ConditionalMechanicValueReference }
| { op: 'floor'; value: ConditionalNumericExpression }
| {
op: 'add' | 'subtract' | 'multiply' | 'divide' | 'min' | 'max';
left: ConditionalNumericExpression;
right: ConditionalNumericExpression;
}
| {
op: 'clamp';
value: ConditionalNumericExpression;
min: ConditionalNumericExpression;
max: ConditionalNumericExpression;
};
export type ConditionalMechanicVariantValue = {
value: number;
expression?: ConditionalNumericExpression;
expression?: NumericExpression;
};
export type ConditionalMechanicOutcomeDraft = Omit<
@@ -219,21 +200,6 @@ export function registeredEventFields(event: MechanicEventKind) {
return MECHANIC_EVENT_REGISTRY[event].fields ?? [];
}
export function eventFieldNumericExpression(path: string): NumericExpression {
return { ref: { source: 'event', path } };
}
export function readEventFieldNumericExpression(
expression: NumericExpression,
): string | null {
return typeof expression === 'object' &&
'ref' in expression &&
expression.ref.source === 'event' &&
expression.ref.path.trim()
? expression.ref.path
: null;
}
export type MechanicTargetingMode =
| 'none'
| 'allies_within_radius'
@@ -486,14 +452,6 @@ function isReference(value: unknown): value is ValueReference {
}
}
function isConditionalReference(
value: unknown,
): value is ConditionalMechanicValueReference {
return (
(object(value) && value.source === 'variant_value') || isReference(value)
);
}
function validateAttributeReferences(
value: unknown,
allowedAttributeIds: ReadonlySet<string> | undefined,
@@ -553,29 +511,6 @@ function isExpression(value: unknown): value is NumericExpression {
);
}
function isConditionalExpression(
value: unknown,
): value is ConditionalNumericExpression {
if (finite(value)) return true;
if (!object(value)) return false;
if ('ref' in value) return isConditionalReference(value.ref);
if (value.op === 'floor') return isConditionalExpression(value.value);
if (value.op === 'clamp') {
return (
isConditionalExpression(value.value) &&
isConditionalExpression(value.min) &&
isConditionalExpression(value.max)
);
}
return (
['add', 'subtract', 'multiply', 'divide', 'min', 'max'].includes(
String(value.op),
) &&
isConditionalExpression(value.left) &&
isConditionalExpression(value.right)
);
}
function isOperand(value: unknown) {
return scalar(value) || isReference(value);
}
@@ -903,7 +838,7 @@ function parseOutcome(
}
if (
configured.expression !== undefined &&
!isConditionalExpression(configured.expression)
!isExpression(configured.expression)
) {
errors.push(
`${path} variant "${variant}" has an invalid value expression.`,
@@ -1019,37 +954,6 @@ function parseClauses(
return clauses;
}
function resolveVariantExpression(
expression: ConditionalNumericExpression,
variantValue: number,
): NumericExpression {
if (typeof expression === 'number') return expression;
if ('ref' in expression) {
return expression.ref.source === 'variant_value'
? variantValue
: { ref: expression.ref };
}
if (expression.op === 'floor') {
return {
op: 'floor',
value: resolveVariantExpression(expression.value, variantValue),
};
}
if (expression.op === 'clamp') {
return {
op: 'clamp',
value: resolveVariantExpression(expression.value, variantValue),
min: resolveVariantExpression(expression.min, variantValue),
max: resolveVariantExpression(expression.max, variantValue),
};
}
return {
op: expression.op,
left: resolveVariantExpression(expression.left, variantValue),
right: resolveVariantExpression(expression.right, variantValue),
};
}
function programsForDraft(
draft: ConditionalMechanicDraftV1,
options: ParseConditionalMechanicDraftOptions,
@@ -1098,13 +1002,7 @@ function programsForDraft(
}) => ({
...outcome,
id: outcomeKey,
value:
variants[variant].expression === undefined
? variants[variant].value
: resolveVariantExpression(
variants[variant].expression,
variants[variant].value,
),
value: variants[variant].expression ?? variants[variant].value,
}),
),
})),
src/lib/calculations/mechanic-persistence.test.ts
-74
View File
@@ -1,5 +1,4 @@
import { describe, expect, it } from 'vitest';
import { evaluateMechanicProgram } from './mechanic.js';
import {
adaptConditionalEffectProgram,
type ConditionalEffectClauseRow,
@@ -913,77 +912,4 @@ describe('conditional-effect persistence adapter', () => {
if: condition,
});
});
it('preserves a variant-value expression in persisted JSON while adapting it to the selected row value', () => {
const sourceExpression = {
op: 'multiply',
left: { ref: { source: 'variant_value' } },
right: {
op: 'add',
left: 1,
right: {
op: 'divide',
left: {
ref: {
source: 'equipment',
path: 'protocolTalentUpgrades',
},
},
right: 5,
},
},
};
const serializedExpression = JSON.stringify(sourceExpression);
const persistedOutcome = outcome({
state_pool_id: null,
value: 7.25,
value_expression_json: serializedExpression,
value_scaling: 'flat',
application_phase: 'on_event',
});
const result = adaptConditionalEffectProgram(
{
rule: rule(),
statePools: [],
clauses: [
clause({
trigger_id: null,
event_kind: 'tick',
parameters_json: '{}',
state_pool_id: null,
mutations_json: '[]',
}),
],
outcomes: [persistedOutcome],
triggers: [],
},
{ variantKey: 'I' },
);
expect(result).toMatchObject({ status: 'READY', errors: [] });
expect(persistedOutcome.value).toBe(7.25);
expect(persistedOutcome.value_expression_json).toBe(serializedExpression);
expect(JSON.parse(String(persistedOutcome.value_expression_json))).toEqual(
sourceExpression,
);
expect(result.program?.clauses[0].outcomes?.[0].value).toEqual({
op: 'multiply',
left: 7.25,
right: sourceExpression.right,
});
if (!result.program) return;
const runtime = evaluateMechanicProgram(
result.program,
[{ kind: 'tick', at: 0 }],
{ mode: 'custom', encounterSeconds: 1 },
undefined,
{ protocolTalentUpgrades: 5 },
);
expect(runtime.status).toBe('OK');
expect(runtime.outcomes[0]).toMatchObject({
outcomeId: 'outcome-1',
value: 14.5,
resolvedValue: 14.5,
});
});
});
src/lib/calculations/mechanic-persistence.ts
+6 -54
View File
@@ -13,7 +13,6 @@ import {
type Predicate,
type Reducer,
type ScenarioInputDefinition,
type ValueReference,
} from './mechanic.js';
type DatabaseValue = string | number | bigint | boolean | null | undefined;
@@ -258,55 +257,6 @@ function isNumericExpression(value: unknown): value is NumericExpression {
);
}
function resolveVariantExpression(
value: unknown,
variantValue: number,
): NumericExpression | null {
if (finite(value)) return value;
if (!object(value)) return null;
if ('ref' in value) {
if (
object(value.ref) &&
value.ref.source === 'variant_value' &&
Object.keys(value.ref).length === 1
) {
return variantValue;
}
return isValueReference(value.ref)
? { ref: value.ref as ValueReference }
: null;
}
if (value.op === 'floor') {
const nested = resolveVariantExpression(value.value, variantValue);
return nested === null ? null : { op: 'floor', value: nested };
}
if (value.op === 'clamp') {
const nested = resolveVariantExpression(value.value, variantValue);
const min = resolveVariantExpression(value.min, variantValue);
const max = resolveVariantExpression(value.max, variantValue);
return nested === null || min === null || max === null
? null
: { op: 'clamp', value: nested, min, max };
}
if (
!['add', 'subtract', 'multiply', 'divide', 'min', 'max'].includes(
String(value.op),
)
) {
return null;
}
const left = resolveVariantExpression(value.left, variantValue);
const right = resolveVariantExpression(value.right, variantValue);
return left === null || right === null
? null
: {
op: value.op as
'add' | 'subtract' | 'multiply' | 'divide' | 'min' | 'max',
left,
right,
};
}
function isPredicate(value: unknown): value is Predicate {
if (!object(value) || typeof value.kind !== 'string') return false;
if (value.kind === 'true') return true;
@@ -723,8 +673,11 @@ function parseOutcome(
) {
errors.push(`${path} has an unsupported application phase.`);
}
const variantValue = requiredNumber(row.value, `${path} value`, errors);
let value: NumericExpression = variantValue;
let value: NumericExpression = requiredNumber(
row.value,
`${path} value`,
errors,
);
if (
row.value_expression_json !== null &&
row.value_expression_json !== undefined &&
@@ -736,8 +689,7 @@ function parseOutcome(
errors,
);
if (parsed.ok) {
const resolved = resolveVariantExpression(parsed.value, variantValue);
if (resolved !== null) value = resolved;
if (isNumericExpression(parsed.value)) value = parsed.value;
else
errors.push(
`${path} value expression is not a valid numeric expression.`,
src/lib/calculations/mechanic.test.ts
-171
View File
@@ -19,84 +19,6 @@ const custom = (
inputs,
});
const closeAndPersonalProgram = (
resolvedVariantValue: number,
): MechanicProgram => ({
id: 'close-and-personal-engineering',
name: 'Close and Personal Engineering',
pools: [
{
key: 'eligible-allies',
label: 'Eligible Allies',
scope: 'agent',
initial: 0,
min: 0,
max: 20,
},
],
clauses: [
{
id: 'sample-eligible-allies',
when: 'proximity_snapshot',
reducer: {
kind: 'derived_scalar',
value: {
ref: {
source: 'event',
path: 'values.alliesWithin30MetersWithAgentGrantedBuff',
},
},
},
mutations: [
{
kind: 'derive',
pool: 'eligible-allies',
value: { ref: { source: 'reducer' } },
},
],
},
{
id: 'resolve-engineering',
when: 'tick',
reducer: { kind: 'none' },
mutations: [{ kind: 'none' }],
outcomes: [
{
id: 'engineering',
label: 'Engineering',
phase: 'on_event',
kind: 'attribute_modifier',
scope: 'self',
basis: 'flat',
attributeId: 'engineering',
value: {
op: 'multiply',
left: {
op: 'multiply',
left: { ref: { source: 'pool', pool: 'eligible-allies' } },
right: resolvedVariantValue,
},
right: {
op: 'add',
left: 1,
right: {
op: 'divide',
left: {
ref: {
source: 'equipment',
path: 'protocolTalentUpgrades',
},
},
right: 5,
},
},
},
},
],
},
],
});
describe('deterministic mechanic probabilities and assigned abilities', () => {
it('rolls outcome probability independently with a reproducible seed and preserves a refreshed window', () => {
const program: MechanicProgram = {
@@ -399,23 +321,6 @@ describe('structured mechanic runtime', () => {
});
});
it('advertises the optional non-negative integer proximity count without making snapshots strict', () => {
const definition = MECHANIC_EVENT_REGISTRY.proximity_snapshot;
const countField = definition.fields?.find(
({ path }) => path === 'values.alliesWithin30MetersWithAgentGrantedBuff',
);
expect(definition.strictFields).not.toBe(true);
expect(countField).toEqual({
path: 'values.alliesWithin30MetersWithAgentGrantedBuff',
label: 'Allies within 30 meters with an Agent-granted buff',
type: 'number',
minimum: 0,
integer: true,
});
expect(countField?.required).not.toBe(true);
});
it('advertises imported support and equipment-use trigger events', () => {
expect(MECHANIC_EVENT_REGISTRY.ally_downed).toMatchObject({
key: 'ally_downed',
@@ -1401,7 +1306,6 @@ describe('structured mechanic runtime', () => {
],
custom(),
);
expect(result.status).toBe('OK');
expect(result.finalState[0].value).toBe(2);
const maximum = evaluateMechanicProgram(program, [], {
mode: 'maximum',
@@ -1410,81 +1314,6 @@ describe('structured mechanic runtime', () => {
expect(maximum.finalState[0].value).toBe(3);
});
it.each([
{ count: 0, upgrades: 0, multiplier: 0 },
{ count: 3, upgrades: 0, multiplier: 3 },
{ count: 3, upgrades: 5, multiplier: 6 },
])(
'resolves Close-and-Personal-style Engineering for count $count and $upgrades OS upgrades',
({ count, upgrades, multiplier }) => {
const resolvedVariantValue = 7.25;
const result = evaluateMechanicProgram(
closeAndPersonalProgram(resolvedVariantValue),
[
{
kind: 'proximity_snapshot',
at: 0,
values: {
alliesWithin30MetersWithAgentGrantedBuff: count,
},
},
{ kind: 'tick', at: 1 },
],
custom(),
undefined,
{ protocolTalentUpgrades: upgrades },
);
expect(result.status).toBe('OK');
expect(result.finalState).toContainEqual(
expect.objectContaining({ pool: 'eligible-allies', value: count }),
);
expect(
result.outcomes.find(({ outcomeId }) => outcomeId === 'engineering'),
).toMatchObject({
value: resolvedVariantValue * multiplier,
resolvedValue: resolvedVariantValue * multiplier,
});
},
);
it.each([
{
count: '2',
error:
'Allies within 30 meters with an Agent-granted buff must be a number.',
},
{
count: -1,
error:
'Allies within 30 meters with an Agent-granted buff must be 0 or greater.',
},
{
count: 1.5,
error:
'Allies within 30 meters with an Agent-granted buff must be an integer.',
},
])('rejects invalid proximity ally count $count', ({ count, error }) => {
const result = evaluateMechanicProgram(
closeAndPersonalProgram(7.25),
[
{
kind: 'proximity_snapshot',
at: 0,
values: {
alliesWithin30MetersWithAgentGrantedBuff: count,
},
},
],
custom(),
undefined,
{ protocolTalentUpgrades: 0 },
);
expect(result.status).toBe('INVALID');
expect(result.errors).toContain(`Event 1 (Proximity snapshot) ${error}`);
});
it('shares one movement charge pool across generation and consumption clauses', () => {
const program: MechanicProgram = {
id: 'mobile-charge',
src/lib/calculations/mechanic.ts
-24
View File
@@ -28,13 +28,6 @@ export const MECHANIC_EVENT_KINDS = [
'tick',
] as const;
export const PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_VALUE_KEY =
'alliesWithin30MetersWithAgentGrantedBuff' as const;
export const PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_FIELD =
`values.${PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_VALUE_KEY}` as const;
export const PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_INPUT =
'allies-within-30m-with-agent-granted-buff' as const;
export type MechanicEventKind = (typeof MECHANIC_EVENT_KINDS)[number];
export type MechanicEventDefinition = {
key: MechanicEventKind;
@@ -46,7 +39,6 @@ export type MechanicEventDefinition = {
type: 'boolean' | 'number' | 'string';
required?: boolean;
minimum?: number;
integer?: boolean;
}[];
strictFields?: boolean;
};
@@ -316,15 +308,6 @@ export const MECHANIC_EVENT_REGISTRY: Readonly<
label: 'Proximity snapshot',
description:
'A sampled count or state for nearby allies, enemies, and Agent-owned buffs.',
fields: [
{
path: PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_FIELD,
label: 'Allies within 30 meters with an Agent-granted buff',
type: 'number',
minimum: 0,
integer: true,
},
],
},
firing_started: {
key: 'firing_started',
@@ -2066,13 +2049,6 @@ function validateMechanicEvents(events: MechanicEvent[]) {
) {
errors.push(`${fieldPath} must be ${field.minimum} or greater.`);
}
if (
field.type === 'number' &&
field.integer &&
!Number.isInteger(value)
) {
errors.push(`${fieldPath} must be an integer.`);
}
}
const hasExtraHealth = getPath(event, 'values.hasExtraHealth');
const currentExtraHealth = getPath(event, 'values.currentExtraHealth');
src/lib/components/builder/WeaponBaselineThroughput.svelte
+97
View File
@@ -0,0 +1,97 @@
<script lang="ts">
import type { WeaponBaseline } from '$lib/builder/weapon-baseline';
type WeaponBaselineEntry = {
slot: 'PRIMARY' | 'SECONDARY';
id: string;
name: string;
damage: number | null;
rpm: number | null;
magazine: number | null;
reloadSpeed: number | null;
baseline: WeaponBaseline;
};
let { entries, headingId }: { entries: WeaponBaselineEntry[]; headingId: string } = $props();
const numberValue = (value: number | null, suffix = '') =>
value === null || !Number.isFinite(value) || value <= 0 ? 'NOT AVAILABLE' : `${value.toLocaleString(undefined, { maximumFractionDigits: 2 })}${suffix}`;
const metricValue = (metric: { value: number | null; missing: string[] }) => numberValue(metric.value, ' /s');
</script>
<section class="weapon-baseline" aria-labelledby={headingId}>
<header class="baseline-head">
<div>
<p class="eyebrow"><span></span> WEAPON OUTPUT / CATALOG BASELINE</p>
<h2 id={headingId}>Weapon output</h2>
</div>
<strong>EXPERIMENTAL</strong>
</header>
<p class="baseline-intro">Strict evidence-only throughput from the selected catalog weapon and selected damage.</p>
<div class="baseline-results" aria-live="polite" aria-atomic="false">
{#each entries as entry}
<article class="weapon-result" aria-labelledby={`${headingId}-${entry.slot.toLowerCase()}`}>
<header class="weapon-result-head">
<div>
<span>{entry.slot}</span>
<h3 id={`${headingId}-${entry.slot.toLowerCase()}`}>{entry.name}</h3>
</div>
<code>{entry.id || 'NO CATALOG ID'}</code>
</header>
<div class="baseline-inputs" aria-label={`${entry.slot} baseline inputs`}>
<span><small>SELECTED DAMAGE</small><b>{numberValue(entry.baseline.selectedDamage.value)}</b></span>
<span><small>RPM</small><b>{numberValue(entry.rpm)}</b></span>
<span><small>MAGAZINE</small><b>{numberValue(entry.magazine, ' SHOTS')}</b></span>
<span><small>RELOAD</small><b>{numberValue(entry.reloadSpeed, ' SEC')}</b></span>
</div>
<div class="baseline-metrics">
{#each [
{ label: 'RATED BODY-HIT THROUGHPUT', metric: entry.baseline.ratedBodyHitThroughput },
{ label: 'MAGAZINE-CYCLE BODY-HIT THROUGHPUT', metric: entry.baseline.magazineCycleBodyHitThroughput }
] as output}
<div class:unavailable={output.metric.value === null}>
<span>{output.label}<small>PER SECOND</small></span>
<strong>{metricValue(output.metric)}</strong>
{#if output.metric.value === null}
<p class="missing-label">MISSING FIELDS</p>
<ul>{#each output.metric.missing as field}<li>{field}</li>{/each}</ul>
{/if}
</div>
{/each}
</div>
</article>
{/each}
</div>
<div class="baseline-contract">
<p><b>FORMULAS</b> Selected damage × (RPM ÷ 60)</p>
<p>Magazine × selected damage ÷ ((Magazine ÷ (RPM ÷ 60)) + reload seconds)</p>
<p>This does not calculate accuracy, critical hits, headshots, Talents, enemy mitigation, rotations, target count, or encounter uptime.</p>
</div>
<p class="baseline-source">Source provenance: each result shows its catalog weapon ID above.</p>
</section>
<style>
.weapon-baseline{display:grid;gap:var(--shd-gap-md);padding:var(--shd-gap-md);border:1px solid var(--shd-model-border);border-top:2px solid var(--shd-orange);background:var(--shd-model-surface);min-width:0}
.baseline-head,.weapon-result-head{display:flex;align-items:flex-start;justify-content:space-between;gap:var(--shd-gap-md)}
.baseline-head>div,.weapon-result-head>div{display:grid;gap:3px;min-width:0}
.eyebrow,.baseline-head p{margin:0;color:var(--shd-orange);font-size:var(--shd-type-telemetry);font-weight:900;letter-spacing:1px}
.eyebrow span{display:inline-block;width:6px;height:6px;margin-right:4px;background:var(--shd-orange)}
h2,h3{margin:0;text-transform:uppercase;letter-spacing:.7px;color:var(--shd-text)}
h2{font-size:var(--shd-type-body)}h3{font-size:var(--shd-type-supporting)}
.baseline-head>strong{padding:5px 7px;border:1px solid var(--shd-orange);color:var(--shd-orange);font-size:var(--shd-type-telemetry);letter-spacing:.8px;white-space:nowrap}
.baseline-intro,.baseline-contract p,.baseline-source{margin:0;color:var(--shd-text-muted);font-size:var(--shd-type-supporting);line-height:1.45}
.baseline-results{display:grid;gap:var(--shd-gap-sm)}
.weapon-result{display:grid;gap:var(--shd-gap-sm);padding:var(--shd-gap-sm);border:1px solid var(--shd-border);background:var(--shd-surface)}
.weapon-result-head span,.baseline-inputs small,.baseline-metrics span,.missing-label{color:var(--shd-text-muted);font-size:var(--shd-type-telemetry);font-weight:900;letter-spacing:.7px}
.weapon-result-head code{max-width:45%;overflow:hidden;color:var(--shd-text-dim);font:var(--shd-type-telemetry) var(--shd-font-mono);text-overflow:ellipsis;white-space:nowrap}
.baseline-inputs{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));border-block:1px solid var(--shd-border-soft)}
.baseline-inputs span{display:grid;gap:3px;padding:7px;border-left:1px solid var(--shd-border-soft);min-width:0}.baseline-inputs span:first-child{border-left:0}
.baseline-inputs b{font-size:var(--shd-type-supporting);font-weight:700;overflow-wrap:anywhere}
.baseline-metrics{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--shd-gap-sm)}
.baseline-metrics>div{display:grid;gap:5px;padding:9px;border-left:2px solid var(--shd-success);background:var(--shd-bg);min-width:0}.baseline-metrics>div.unavailable{border-left-color:var(--shd-danger)}
.baseline-metrics span{display:grid;gap:2px}.baseline-metrics span small{color:var(--shd-text-dim);font-size:10px}.baseline-metrics strong{font-size:18px;color:var(--shd-success)}.baseline-metrics .unavailable strong{color:var(--shd-danger)}
.missing-label{margin:2px 0 0;color:var(--shd-danger)}.baseline-metrics ul{margin:0;padding-left:17px;color:var(--shd-danger);font:var(--shd-type-telemetry)/1.4 var(--shd-font-mono)}
.baseline-contract{display:grid;gap:5px;padding-top:var(--shd-gap-sm);border-top:1px solid var(--shd-border)}.baseline-contract b{color:var(--shd-text);letter-spacing:.7px}.baseline-source{font-size:var(--shd-type-telemetry)}
@media(max-width:620px){.baseline-head{display:grid}.baseline-inputs{grid-template-columns:repeat(2,minmax(0,1fr))}.baseline-inputs span:nth-child(odd){border-left:0}.baseline-inputs span:nth-child(n+3){border-top:1px solid var(--shd-border-soft)}.baseline-metrics{grid-template-columns:1fr}.weapon-result-head code{max-width:50%}}
@media(prefers-reduced-motion:reduce){.weapon-baseline *{scroll-behavior:auto;transition:none!important;animation:none!important}}
</style>
src/lib/components/isac/MechanicProgramEditor.svelte
+18 -92
View File
@@ -9,18 +9,15 @@
blankConditionalMechanicDraft,
currentHealthPercentBandPredicate,
eventFieldComparisonPredicate,
eventFieldNumericExpression,
mechanicTargetingForMode,
mechanicTargetingMode,
parseConditionalMechanicDraft,
readCurrentHealthPercentBand,
readEventFieldComparison,
readEventFieldNumericExpression,
registeredEventFields,
readStatePoolThreshold,
statePoolThresholdPredicate,
type ConditionalMechanicClauseDraft,
type ConditionalNumericExpression,
type ConditionalMechanicDraftV1,
type ConditionalMechanicOutcomeDraft,
type ConditionalMechanicPoolDraft,
@@ -34,7 +31,6 @@
formatMechanicProgram,
MECHANIC_EVENT_KINDS,
MECHANIC_EVENT_REGISTRY,
PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_FIELD,
type ClauseMutation,
type MechanicOutcomeScope,
type NumericExpression,
@@ -412,40 +408,6 @@
updateClause(index, { reducer });
}
function derivedScalarModel(clause: ConditionalMechanicClauseDraft) {
if (clause.reducer.kind !== 'derived_scalar') return 'static';
if (typeof clause.reducer.value === 'number') return 'static';
return readEventFieldNumericExpression(clause.reducer.value) ? 'event' : 'advanced';
}
function numericEventFields(clause: ConditionalMechanicClauseDraft) {
return registeredEventFields(clause.event).filter((field) => field.type === 'number');
}
function setDerivedScalarModel(clauseIndex: number, model: string) {
const clause = rule.clauses[clauseIndex];
if (clause.reducer.kind !== 'derived_scalar') return;
if (model === 'static') {
updateClause(clauseIndex, { reducer: { kind: 'derived_scalar', value: 1 } });
return;
}
const field = numericEventFields(clause)[0];
if (model === 'event' && field) {
updateClause(clauseIndex, {
reducer: {
kind: 'derived_scalar',
value: eventFieldNumericExpression(field.path)
}
});
}
}
function setDerivedScalarEventField(clauseIndex: number, path: string) {
updateClause(clauseIndex, {
reducer: { kind: 'derived_scalar', value: eventFieldNumericExpression(path) }
});
}
function updateOutcome(clauseIndex: number, outcomeIndex: number, patch: Partial<ConditionalMechanicOutcomeDraft>) {
const outcomes = [...rule.clauses[clauseIndex].outcomes];
outcomes[outcomeIndex] = { ...outcomes[outcomeIndex], ...patch };
@@ -555,10 +517,6 @@
const eventValueOptions = [
{ value: 'values.enemyCount', label: 'ENEMY COUNT' },
{ value: 'values.allyCount', label: 'ALLY COUNT' },
{
value: PROXIMITY_AGENT_GRANTED_BUFF_ALLY_COUNT_FIELD,
label: 'AGENT-BUFFED ALLIES ≤30M'
},
{ value: 'values.magazineRemaining', label: 'ROUNDS LEFT' },
{ value: 'values.magazinePercent', label: 'MAGAZINE %' },
{ value: 'values.distanceMeters', label: 'DISTANCE' }
@@ -576,10 +534,10 @@
};
}
function protocolUpgradeExpression(): ConditionalNumericExpression {
function protocolUpgradeExpression(value: number): NumericExpression {
return {
op: 'multiply',
left: { ref: { source: 'variant_value' } },
left: value,
right: {
op: 'add',
left: 1,
@@ -620,17 +578,17 @@
typeof expression === 'object'
&& 'op' in expression
&& expression.op === 'multiply'
&& typeof expression.left === 'number'
&& typeof expression.right === 'object'
) {
if (typeof expression.left === 'number' && 'ref' in expression.right) {
if ('ref' in expression.right) {
if (expression.right.ref.source === 'event') return 'event';
if (expression.right.ref.source === 'scenario') return 'scenario';
if (expression.right.ref.source === 'reducer') return 'reducer';
if (expression.right.ref.source === 'attribute') return 'attribute_value';
}
if (
typeof expression.left === 'number'
&& 'op' in expression.right
'op' in expression.right
&& expression.right.op === 'divide'
&& typeof expression.right.left === 'object'
&& 'ref' in expression.right.left
@@ -638,13 +596,7 @@
&& expression.right.right === 100
) return 'attribute';
if (
(typeof expression.left === 'number'
|| (
typeof expression.left === 'object'
&& 'ref' in expression.left
&& expression.left.ref.source === 'variant_value'
))
&& 'op' in expression.right
'op' in expression.right
&& expression.right.op === 'add'
&& typeof expression.right.right === 'object'
&& 'op' in expression.right.right
@@ -705,7 +657,7 @@
model: OutcomeValueModel,
value: number,
reference = ''
): ConditionalNumericExpression | undefined {
): NumericExpression | undefined {
if (model === 'event') return referenceExpression('event', reference || 'values.enemyCount', value);
if (model === 'attribute') return reference
? attributePercentExpression(value, reference)
@@ -719,7 +671,7 @@
if (model === 'reducer') {
return { op: 'multiply', left: value, right: { ref: { source: 'reducer' } } };
}
if (model === 'protocol_upgrades') return protocolUpgradeExpression();
if (model === 'protocol_upgrades') return protocolUpgradeExpression(value);
return undefined;
}
@@ -746,7 +698,7 @@
updateOutcome(clauseIndex, outcomeIndex, { variants });
}
function replaceExpressionBase(expression: ConditionalNumericExpression, value: number): ConditionalNumericExpression {
function replaceExpressionBase(expression: NumericExpression, value: number): NumericExpression {
const model = outcomeValueModel({
key: 'temporary',
label: 'Temporary',
@@ -791,7 +743,7 @@
if (model === 'reducer') {
return { op: 'multiply', left: value, right: { ref: { source: 'reducer' } } };
}
if (model === 'protocol_upgrades') return protocolUpgradeExpression();
if (model === 'protocol_upgrades') return protocolUpgradeExpression(value);
return expression;
}
@@ -850,7 +802,7 @@
updateClause(clauseIndex, { mutations });
}
function updateMutation(clauseIndex: number, mutationIndex: number, kind: 'add' | 'set' | 'consume' | 'derive' | 'clear', pool?: string, value?: number) {
function updateMutation(clauseIndex: number, mutationIndex: number, kind: 'add' | 'set' | 'consume' | 'clear', pool?: string, value?: number) {
const mutations = [...rule.clauses[clauseIndex].mutations];
const current = mutations[mutationIndex];
const nextPool = pool ?? ('pool' in current ? current.pool : rule.pools[0]?.key ?? '');
@@ -860,9 +812,7 @@
: undefined;
mutations[mutationIndex] = kind === 'clear'
? { kind, pool: nextPool, entity }
: kind === 'derive'
? { kind, pool: nextPool, value: { ref: { source: 'reducer' } }, entity }
: { kind, pool: nextPool, value: value ?? ('value' in current && typeof current.value === 'number' ? current.value : 1), entity };
: { kind, pool: nextPool, value: value ?? ('value' in current && typeof current.value === 'number' ? current.value : 1), entity };
updateClause(clauseIndex, { mutations });
}
@@ -1184,29 +1134,7 @@
{:else if clause.reducer.kind === 'periodic'}
<label class="field">INTERVAL · SECONDS<input type="number" min="0.01" step="any" value={typeof clause.reducer.intervalSeconds === 'number' ? clause.reducer.intervalSeconds : 1} oninput={(event) => setReducerNumber(clauseIndex,'intervalSeconds',event.currentTarget.value)}/></label>
{:else if clause.reducer.kind === 'derived_scalar'}
<SegmentedChoice
legend="DERIVED VALUE SOURCE"
name={`${idPrefix}-derived-source-${clauseIndex}`}
options={[
{value:'static',label:'STATIC'},
{value:'event',label:'EVENT FIELD',disabled:numericEventFields(clause).length === 0},
...(derivedScalarModel(clause) === 'advanced' ? [{value:'advanced',label:'ADVANCED',disabled:true}] : [])
]}
value={derivedScalarModel(clause)}
onchange={(values) => setDerivedScalarModel(clauseIndex,values[0])}
/>
{#if derivedScalarModel(clause) === 'event'}
<SegmentedChoice
legend="NUMERIC EVENT FIELD"
name={`${idPrefix}-derived-event-${clauseIndex}`}
options={numericEventFields(clause).map((field) => ({value:field.path,label:field.label.toUpperCase()}))}
value={readEventFieldNumericExpression(clause.reducer.value) ?? ''}
columns={Math.min(3,numericEventFields(clause).length)}
onchange={(values) => setDerivedScalarEventField(clauseIndex,values[0])}
/>
{:else if derivedScalarModel(clause) === 'static'}
<label class="field">DERIVED VALUE<input type="number" step="any" value={typeof clause.reducer.value === 'number' ? clause.reducer.value : 1} oninput={(event) => setReducerNumber(clauseIndex,'value',event.currentTarget.value)}/></label>
{/if}
<label class="field">DERIVED VALUE<input type="number" step="any" value={typeof clause.reducer.value === 'number' ? clause.reducer.value : 1} oninput={(event) => setReducerNumber(clauseIndex,'value',event.currentTarget.value)}/></label>
{/if}
</div>
@@ -1231,9 +1159,9 @@
<SegmentedChoice
legend="OPERATION"
name={`${idPrefix}-mutation-kind-${clauseIndex}-${mutationIndex}`}
options={[{value:'add',label:'ADD'},{value:'set',label:'SET'},{value:'consume',label:'CONSUME'},{value:'derive',label:'DERIVED VALUE'},{value:'clear',label:'CLEAR'}]}
value={mutation.kind === 'none' || mutation.kind === 'transfer' ? 'add' : mutation.kind}
onchange={(values) => updateMutation(clauseIndex,mutationIndex,values[0] as 'add'|'set'|'consume'|'derive'|'clear')}
options={[{value:'add',label:'ADD'},{value:'set',label:'SET'},{value:'consume',label:'CONSUME'},{value:'clear',label:'CLEAR'}]}
value={mutation.kind === 'none' || mutation.kind === 'derive' || mutation.kind === 'transfer' ? 'add' : mutation.kind}
onchange={(values) => updateMutation(clauseIndex,mutationIndex,values[0] as 'add'|'set'|'consume'|'clear')}
/>
<SegmentedChoice
legend="STATE POOL"
@@ -1241,12 +1169,10 @@
options={rule.pools.map((pool) => ({value:pool.key,label:pool.label.toUpperCase()}))}
value={'pool' in mutation ? mutation.pool : rule.pools[0]?.key ?? ''}
columns={Math.min(4,Math.max(1,rule.pools.length))}
onchange={(values) => updateMutation(clauseIndex,mutationIndex,mutation.kind === 'clear' ? 'clear' : mutation.kind === 'derive' ? 'derive' : mutation.kind === 'set' || mutation.kind === 'consume' ? mutation.kind : 'add',values[0])}
onchange={(values) => updateMutation(clauseIndex,mutationIndex,mutation.kind === 'clear' ? 'clear' : mutation.kind === 'set' || mutation.kind === 'consume' ? mutation.kind : 'add',values[0])}
/>
{#if mutation.kind !== 'clear' && mutation.kind !== 'derive'}
{#if mutation.kind !== 'clear'}
<label class="field">VALUE<input type="number" step="any" value={'value' in mutation && typeof mutation.value === 'number' ? mutation.value : 1} oninput={(event) => updateMutation(clauseIndex,mutationIndex,mutation.kind === 'set' || mutation.kind === 'consume' ? mutation.kind : 'add',undefined,Number(event.currentTarget.value))}/></label>
{:else if mutation.kind === 'derive'}
<div class="branch-readout"><span>VALUE</span><strong>DERIVED SCALAR</strong></div>
{/if}
{#if 'pool' in mutation && rule.pools.find((pool) => pool.key === mutation.pool)?.scope === 'target'}
<SegmentedChoice
src/lib/server/ai/mechanic-authoring-prompt.test.ts
+7 -65
View File
@@ -94,7 +94,7 @@ describe('AI mechanic authoring prompt', () => {
}),
);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(11);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(10);
expect(input.canonicalCatalog.grammar.outcome.optional).toEqual(
expect.arrayContaining(['delivery', 'durationSeconds']),
);
@@ -136,7 +136,7 @@ describe('AI mechanic authoring prompt', () => {
]),
);
expect(AI_MECHANIC_AUTHORING_INSTRUCTIONS).toContain(
'Prompt contract version: 11',
'Prompt contract version: 10',
);
const advertised = structuredClone(
@@ -185,7 +185,7 @@ describe('AI mechanic authoring prompt', () => {
expect(parsed.ok).toBe(true);
});
it('advertises the canonical Extra Health change event contract in version 11', () => {
it('advertises the canonical Extra Health change event contract in version 10', () => {
const input = JSON.parse(
buildAiMechanicAuthoringInput({
request,
@@ -196,9 +196,9 @@ describe('AI mechanic authoring prompt', () => {
}),
);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(11);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(10);
expect(AI_MECHANIC_AUTHORING_INSTRUCTIONS).toContain(
'Prompt contract version: 11',
'Prompt contract version: 10',
);
expect(input.canonicalCatalog.events).toContainEqual({
key: 'extra_health_changed',
@@ -325,7 +325,7 @@ describe('AI mechanic authoring prompt', () => {
expect(parsed.ok).toBe(true);
});
it('advertises reproducible outcome and clause proc probabilities in version 11', () => {
it('advertises reproducible outcome and clause proc probabilities in version 10', () => {
const input = JSON.parse(
buildAiMechanicAuthoringInput({
request,
@@ -336,7 +336,7 @@ describe('AI mechanic authoring prompt', () => {
}),
);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(11);
expect(AI_MECHANIC_PROMPT_VERSION).toBe(10);
expect(input.canonicalCatalog.grammar.clause.optional).toEqual(
expect.arrayContaining([
'procChancePercent',
@@ -489,62 +489,4 @@ describe('AI mechanic authoring prompt', () => {
});
expect(parsed.ok).toBe(true);
});
it('advertises draft variant-value scaling and the typed proximity input in version 11', () => {
const input = JSON.parse(
buildAiMechanicAuthoringInput({
request: {
...request,
context: {
...request.context,
sourceName: 'Close and Personal',
sourceDescription:
'Increase Weapon Damage by (1)% plus (2)% for each nearby ally with a buff granted by you.',
},
},
attributes: [],
events: [MECHANIC_EVENT_REGISTRY.proximity_snapshot],
actions: [],
recipeKeys: [],
}),
);
const grammar = input.canonicalCatalog.grammar;
const proximityEvent = input.canonicalCatalog.events[0];
expect(AI_MECHANIC_PROMPT_VERSION).toBe(11);
expect(AI_MECHANIC_AUTHORING_INSTRUCTIONS).toContain(
'Prompt contract version: 11',
);
expect(grammar.valueReferences).toContain('variant_value');
expect(grammar.draftOutcomeExpressionReferences).toEqual(['variant_value']);
expect(grammar.referenceShapes).toContainEqual({
ref: { source: 'variant_value' },
});
expect(proximityEvent.fields).toContainEqual({
path: 'values.alliesWithin30MetersWithAgentGrantedBuff',
label: 'Allies within 30 meters with an Agent-granted buff',
type: 'number',
minimum: 0,
integer: true,
});
expect(proximityEvent.strictFields).toBeUndefined();
expect(AI_MECHANIC_AUTHORING_INSTRUCTIONS).toEqual(
expect.stringContaining('unresolved numbered source placeholder'),
);
expect(AI_MECHANIC_AUTHORING_INSTRUCTIONS).toEqual(
expect.stringContaining('{ref:{source:"variant_value"}}'),
);
expect(input.examplesAndRules).toEqual(
expect.arrayContaining([
expect.stringContaining('only inside an outcome variant expression'),
expect.stringContaining('outcome variants[variantKey].value'),
expect.stringContaining(
'{ref:{source:"event",path:"values.alliesWithin30MetersWithAgentGrantedBuff"}}',
),
expect.stringContaining(
'{key:"allies-within-30m-with-agent-granted-buff"',
),
expect.stringContaining('readiness:"ready",min:0'),
]),
);
});
});
src/lib/server/ai/mechanic-authoring-prompt.ts
+1 -11
View File
@@ -3,7 +3,7 @@ import { CONDITIONAL_MECHANIC_OUTCOME_CAPABILITIES } from '$lib/calculations/mec
import { MECHANIC_COMBAT_REFERENCE_REGISTRY } from '$lib/calculations/mechanic';
import type { AiMechanicAttribute } from './mechanic-authoring-context';
export const AI_MECHANIC_PROMPT_VERSION = 11;
export const AI_MECHANIC_PROMPT_VERSION = 10;
const mechanicsGrammar = {
version: 1,
@@ -83,7 +83,6 @@ const mechanicsGrammar = {
'attribute',
'reducer',
'pool',
'variant_value',
],
combatReferences: MECHANIC_COMBAT_REFERENCE_REGISTRY,
numericExpressionOperators: [
@@ -96,9 +95,7 @@ const mechanicsGrammar = {
'clamp',
'floor',
],
draftOutcomeExpressionReferences: ['variant_value'],
referenceShapes: [
{ ref: { source: 'variant_value' } },
{ ref: { source: 'event', path: 'values.distanceMeters' } },
{ ref: { source: 'scenario', key: 'input-key' } },
{ ref: { source: 'combat', path: 'currentHealth', timing: 'current' } },
@@ -501,7 +498,6 @@ Security and scope:
- Use only the supplied event, action, recipe, attribute, scope, reference, expression, reducer, mutation, and outcome catalogs.
- Never invent an Attribute ID, event, field path, source variant, or runtime behavior.
- Ask focused questions when different answers would change the calculation. Do not guess material cadence, duration, target, stacking, reset, scope, damage basis, or value behavior.
- An unresolved numbered source placeholder is a material missing value. Ask the human for the exact numeric value for every affected source variant; never infer or guess it.
- If the behavior cannot be represented by the supplied grammar, return capability_gap with implementation-ready developer changes.
Response rules:
@@ -511,7 +507,6 @@ Response rules:
- All keys must be stable lower-case identifiers using letters, digits, dashes, or underscores and beginning with a letter.
- A draft must define exactly the supplied value variants for every outcome.
- The numeric variant value is the human-facing base value. Use expression only when runtime scaling or a live event/scenario/equipment value changes it.
- Put each clarified placeholder answer in the corresponding outcome variant value as its human-facing value. When that value participates in a runtime expression, reference it exactly as {ref:{source:"variant_value"}}; never duplicate the numeric literal in the expression. variant_value is draft-only and valid only inside an outcome variant expression.
- Use attribute_modifier only with an exact supplied Attribute ID.
- Use direct_damage, restoration, or resource_cost rather than a fabricated Attribute when that is the actual mechanic.
- Keep assumptions explicit. Use warnings for representable limitations that do not require code changes.
@@ -556,14 +551,9 @@ export function buildAiMechanicAuthoringInput(input: {
'A target-scoped pool owns an independent value and expiry timer for each entity. Bind hit-created target state with entity:{kind:"event_target"}; do not collapse different enemies into one Agent-scoped pool.',
'Writing a target-scoped pool refreshes only that target entity timer. An on_exit outcome runs when that entity expires and uses the entity previous state for stack bands and perStack multiplication, even though the stored pool value has already reset.',
'When an outcome value is exactly a live Attribute amount, use the Attribute reference directly as the variant expression. Divide by 100 only when a displayed percentage is being used as a multiplier.',
'variant_value is draft-only and may appear only inside an outcome variant expression, with the exact shape {ref:{source:"variant_value"}}. It resolves to that same variant object’s human-facing numeric value at runtime.',
'If source wording contains an unresolved numbered placeholder such as {1} or {2}, return clarification_required and ask for the exact numeric answer for every affected source variant. Never guess a placeholder value.',
'After clarification, put each answer in the corresponding outcome variants[variantKey].value. If a runtime-scaled expression uses that answer, reference {ref:{source:"variant_value"}} rather than duplicating the numeric literal.',
'A weapon_hit may compare values.aiming with true only when the wording requires aiming down sights at hit resolution. Missing aiming evidence does not match; do not replace it with a scenario assumption.',
'An explosion centered on the hit target uses target-scoped direct_damage with targeting kind event_target_area, center event_target, validTargets enemies, and the stated positive radiusMeters. The runtime applies one equal damage emission to each authoritative valid enemy at or inside the radius. Do not use legacy within_radius metadata for explosion damage.',
'Precise Trauma is representable as one target-scoped stack pool with a one-second expiry: body shots add one stack, headshots add two, and one on_exit direct-damage outcome uses the expiring target previous stack count. This models the stated one-second debuff without inventing generic repeated target ticks.',
'For proximity_snapshot, the optional values.alliesWithin30MetersWithAgentGrantedBuff field is a non-negative integer count of distinct allied Agents at or within 30 meters who possess at least one buff granted by the source Agent. Multiple qualifying buffs on one ally still count that ally once. Read it with {ref:{source:"event",path:"values.alliesWithin30MetersWithAgentGrantedBuff"}}.',
'When loadout timelines must supply values.alliesWithin30MetersWithAgentGrantedBuff, define the ready numeric scenario input exactly as {key:"allies-within-30m-with-agent-granted-buff",label:"Allies within 30 meters with an Agent-granted buff",kind:"number",readiness:"ready",min:0}. The loadout timeline copies that resolved count into each proximity_snapshot event, and runtime event validation rejects non-integers.',
'OS Protocol upgrade scaling may use equipment.protocolTalentUpgrades only when allowProtocolUpgradeScaling is true.',
'Assigned-ability scope may be used only when allowAssignedAbility is true.',
'When allowAssignedAbility is true, a kill or assist that must occur while the source item\'s assigned ability is active uses enemy_killed or assist with {source:"event",path:"values.assignedAbilityActive"} compared to true. This field is optional on the event; a missing value does not match.',
src/routes/+layout.server.ts
+1 -17
View File
@@ -1,26 +1,10 @@
import { dev } from '$app/environment';
import { getSessionUser } from '$lib/server/auth/session';
import { hasPermission } from '$lib/server/auth/authorization';
import type { LayoutServerLoad } from './$types';
import { notificationSummary } from '$lib/server/notifications';
import { getSiteAccessSettings } from '$lib/server/site-access';
export const load: LayoutServerLoad = async ({ cookies, url }) => {
// THROWAWAY PROTOTYPE: fixture-only review must not open the shared database.
if (dev && url.pathname === '/database' && url.searchParams.get('prototype') === 'model-status') {
return {
user: null,
isacAccess: false,
notifications: { unread: 0 },
siteAccess: {
comingSoonEnabled: false,
accountCreationEnabled: true,
sections: { news: true, database: true, builds: true, guides: true, builder: true },
updatedAt: 'prototype'
}
};
}
export const load: LayoutServerLoad = async ({ cookies }) => {
const user = await getSessionUser(cookies);
return {
user,
src/routes/builder/+page.svelte
+24
View File
@@ -11,9 +11,11 @@
import BuildShareControl from '$lib/components/BuildShareControl.svelte';
import LoadoutMatrix, { type MatrixCell } from '$lib/components/builder/LoadoutMatrix.svelte';
import LoadoutStatsSummary from '$lib/components/builder/LoadoutStatsSummary.svelte';
import WeaponBaselineThroughput from '$lib/components/builder/WeaponBaselineThroughput.svelte';
import PlannedCombatModel from '$lib/components/builder/PlannedCombatModel.svelte';
import TalentTierChoice from '$lib/components/builder/TalentTierChoice.svelte';
import { summarizeLoadout } from '$lib/builder/loadout-summary';
import { calculateWeaponBaseline } from '$lib/builder/weapon-baseline';
import { toast } from '$lib/toast';
import {
blankRoll, clamp, createDraft, gearBaseStatRange, gearSlots, levelScaledRange, migrateLoadoutDraftV5, parseLoadoutDraft, remapRangeValue, scaled, skillChipQualities, skillChipSecondaryCapacity, weaponBaseRange,
@@ -340,6 +342,27 @@
};
const activeParts = $derived(active.split(':'));
const summary = $derived(summarizeLoadout(draft, data));
const weaponBaselines = $derived(draft.weapons.map((selection, index) => {
const item = data.weapons.find((entry) => entry.id === selection.itemId);
return {
slot: index ? 'SECONDARY' as const : 'PRIMARY' as const,
id: String(item?.id ?? ''),
name: item?.name ?? 'UNASSIGNED',
damage: Number.isFinite(Number(selection.damage)) ? Number(selection.damage) : null,
rpm: item?.rpm == null ? null : Number(item.rpm),
magazine: item?.magazine == null ? null : Number(item.magazine),
reloadSpeed: item?.reload_speed == null ? null : Number(item.reload_speed),
baseline: calculateWeaponBaseline({
weaponId: String(item?.id ?? 'NO CATALOG ID'),
weaponName: item?.name,
weaponLabel: index ? 'SECONDARY' : 'PRIMARY',
selectedDamage: selection.damage,
rpm: item?.rpm,
magazine: item?.magazine,
reloadSeconds: item?.reload_speed
})
};
}));
const rollSummary = (rolls: Roll[]) => rolls
.filter((roll) => roll.statId)
.map((roll) => `${attribute(roll.statId)?.name ?? 'Attribute'} ${unitValue(roll.value, roll.statId)}`)
@@ -674,6 +697,7 @@
<aside class="loadout-summary">
<LoadoutStatsSummary {summary} attributes={data.attributes} talents={data.talents} headingId="builder-known-stats-heading" />
<WeaponBaselineThroughput entries={weaponBaselines} headingId="builder-weapon-output-heading" />
<div class="builder-planned-model"><PlannedCombatModel headingId="builder-planned-output-heading" variant="compact" /></div>
<p class="notice">Anonymous drafts remain on this device. Account saves preserve the equipped-item configuration and current visibility.</p>
</aside>
src/routes/database/+page.server.ts
-6
View File
@@ -1,4 +1,3 @@
import { dev } from '$app/environment';
import { getDatabase } from '$lib/server/database';
import { getRegistrySearch } from '$lib/server/pagination';
import { databaseCategories } from '$lib/database/categories';
@@ -17,11 +16,6 @@ const tables = {
} as const;
export const load: PageServerLoad = async ({ url }) => {
// THROWAWAY PROTOTYPE: avoid opening the shared database for fixture-only review.
if (dev && url.searchParams.get('prototype') === 'model-status') {
return { registries: [], total: 0, search: '', searchResults: [] };
}
const database = await getDatabase();
const { search, pattern } = getRegistrySearch(url);
const counts = await Promise.all(
src/routes/database/+page.svelte
-14
View File
@@ -1,16 +1,6 @@
<script lang="ts">
import { dev } from '$app/environment';
import { page } from '$app/state';
import ModelStatusPrototype from './ModelStatusPrototype.prototype.svelte';
import type { PrototypeVariant } from './model-status.prototype';
let { data } = $props();
const onlineRegistries = $derived(data.registries.filter((registry) => registry.count > 0).length);
const prototypeVariant = $derived.by<PrototypeVariant | null>(() => {
if (!dev || page.url.searchParams.get('prototype') !== 'model-status') return null;
const variant = page.url.searchParams.get('variant');
return variant === 'A' || variant === 'B' || variant === 'C' ? variant : null;
});
</script>
<svelte:head>
@@ -18,9 +8,6 @@
<meta name="description" content="Community-maintained The Division Resurgence attributes, talents, brands, gear, weapons, mods, protocols, skill chips, and specializations data."/>
</svelte:head>
{#if prototypeVariant}
<ModelStatusPrototype variant={prototypeVariant} />
{:else}
<main class="page community-index-page">
<header class="catalogue-hero community-index-hero">
<div><p class="eyebrow"><span></span> ISAC PUBLIC ARCHIVE</p><h1>RESURGENCE <em>DATABASE.</em></h1><p>Explore equipment, talents, modifications, and gameplay effects from The Division Resurgence.</p></div>
@@ -67,4 +54,3 @@
{/each}
</section>
</main>
{/if}
src/routes/database/ModelStatusPrototype.prototype.svelte
-21
View File
@@ -1,21 +0,0 @@
<script lang="ts">
import ModelStatusPrototypeSwitcher from './ModelStatusPrototypeSwitcher.prototype.svelte';
import ModelStatusVariantA from './ModelStatusVariantA.prototype.svelte';
import ModelStatusVariantB from './ModelStatusVariantB.prototype.svelte';
import ModelStatusVariantC from './ModelStatusVariantC.prototype.svelte';
import type { PrototypeVariant } from './model-status.prototype';
let { variant }: { variant: PrototypeVariant } = $props();
</script>
<!-- THROWAWAY PROTOTYPE: three issue #5 variants on the existing /database route. -->
<main class="page model-status-prototype">
{#if variant === 'A'}
<ModelStatusVariantA />
{:else if variant === 'B'}
<ModelStatusVariantB />
{:else}
<ModelStatusVariantC />
{/if}
</main>
<ModelStatusPrototypeSwitcher current={variant} />
src/routes/database/ModelStatusPrototypeSwitcher.prototype.svelte
-45
View File
@@ -1,45 +0,0 @@
<script lang="ts">
import { goto } from '$app/navigation';
import { page } from '$app/state';
import { onMount } from 'svelte';
import { prototypeVariantNames, type PrototypeVariant } from './model-status.prototype';
let { current }: { current: PrototypeVariant } = $props();
const variants: PrototypeVariant[] = ['A', 'B', 'C'];
const cycle = (direction: -1 | 1) => {
const currentIndex = variants.indexOf(current);
const next = variants[(currentIndex + direction + variants.length) % variants.length];
const params = new URLSearchParams(page.url.searchParams);
params.set('prototype', 'model-status');
params.set('variant', next);
void goto(`${page.url.pathname}?${params.toString()}${page.url.hash}`, {
keepFocus: true,
noScroll: true,
replaceState: true
});
};
onMount(() => {
const handleKeydown = (event: KeyboardEvent) => {
if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
if (event.target instanceof HTMLElement && event.target.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"])')) return;
event.preventDefault();
cycle(event.key === 'ArrowLeft' ? -1 : 1);
};
window.addEventListener('keydown', handleKeydown);
return () => window.removeEventListener('keydown', handleKeydown);
});
</script>
<!-- THROWAWAY PROTOTYPE: development-only variant switcher for issue #5. -->
<nav class="prototype-switcher" aria-label="Model status prototype variants">
<button type="button" onclick={() => cycle(-1)} aria-label="Show previous prototype variant">←</button>
<strong aria-live="polite" title={prototypeVariantNames[current]} aria-label={`Variant ${current}: ${prototypeVariantNames[current]}`}>{current}</strong>
<button type="button" onclick={() => cycle(1)} aria-label="Show next prototype variant">→</button>
</nav>
<style>
.prototype-switcher{position:fixed;z-index:1000;right:14px;bottom:14px;display:grid;grid-template-columns:36px 34px 36px;height:36px;border:1px solid var(--shd-border-strong);box-shadow:0 7px 20px #000a;background:var(--shd-bg);color:var(--shd-text)}.prototype-switcher button{display:grid;place-items:center;border:0;background:var(--shd-surface-raised);color:var(--shd-orange);font:800 17px/1 var(--shd-font-mono);cursor:pointer}.prototype-switcher button:first-child{border-right:1px solid var(--shd-border)}.prototype-switcher button:last-child{border-left:1px solid var(--shd-border)}.prototype-switcher button:hover{background:var(--shd-surface-active);color:var(--shd-orange-hover)}.prototype-switcher button:active{transform:translateY(1px);filter:brightness(.82)}.prototype-switcher button:focus-visible{position:relative;z-index:1;outline:2px solid var(--shd-focus-ring);outline-offset:2px}.prototype-switcher>strong{display:grid;place-items:center;color:var(--shd-text);font:900 12px/1 var(--shd-font-mono);letter-spacing:.6px}@media(max-width:520px){.prototype-switcher{right:8px;bottom:8px}}@media(prefers-reduced-motion:reduce){.prototype-switcher button{transition:none}}
</style>
src/routes/database/ModelStatusVariantA.prototype.svelte
-78
View File
@@ -1,78 +0,0 @@
<script lang="ts">
import {
modelStatusFixtures,
publicBehavior,
publicStatus
} from './model-status.prototype';
const quickViewFixtures = [modelStatusFixtures[0], modelStatusFixtures[3]];
</script>
<!-- THROWAWAY PROTOTYPE: issue #5, variant A. -->
<div class="prototype-a">
<header class="prototype-heading">
<div>
<p><span></span> DEVELOPMENT PROTOTYPE · ISSUE #5 · VARIANT A</p>
<h1>MODELING <em>STATUS.</em></h1>
</div>
<p>Integrated card hierarchy keeps the public state in the identity header and gives behavior one primary reading block.</p>
</header>
<section aria-labelledby="a-card-heading">
<header class="surface-heading">
<div><span>01 / CARD PRESENTATION</span><h2 id="a-card-heading">DATABASE CARDS</h2></div>
<small>ALL MECHANIC OWNERS · PUBLIC STATE ONLY</small>
</header>
<div class="card-grid">
{#each modelStatusFixtures as fixture}
<article class="model-card">
<header>
<div><small>{fixture.owner}</small><h3>{fixture.name}</h3><span>{fixture.context}</span></div>
<strong class:not-modeled={publicStatus(fixture) === 'NOT MODELED'}>{publicStatus(fixture)}</strong>
</header>
<div class="behavior-block">
<small>{publicStatus(fixture) === 'MODELED' ? 'MODELED BEHAVIOR' : 'AUTHORED DESCRIPTION'}</small>
<p>{publicBehavior(fixture)}</p>
</div>
<footer><span>READ-ONLY FIXTURE</span><b>VIEW DETAILS →</b></footer>
</article>
{/each}
</div>
</section>
<section aria-labelledby="a-detail-heading">
<header class="surface-heading">
<div><span>02 / DETAIL PRESENTATION</span><h2 id="a-detail-heading">QUICK VIEW</h2></div>
<small>MODELED TEXT FIRST · AUTHORED FALLBACK WHEN NOT MODELED</small>
</header>
<div class="quick-view">
{#each quickViewFixtures as fixture}
<article>
<header><div><small>{fixture.owner}</small><h3>{fixture.name}</h3></div><strong class:not-modeled={publicStatus(fixture) === 'NOT MODELED'}>{publicStatus(fixture)}</strong></header>
<div><span>BEHAVIOR</span><p>{publicBehavior(fixture)}</p></div>
<dl><div><dt>RECORD</dt><dd>{fixture.context}</dd></div><div><dt>DISPLAY SOURCE</dt><dd>{publicStatus(fixture) === 'MODELED' ? 'Modeled behavior' : 'Authored description'}</dd></div></dl>
</article>
{/each}
</div>
</section>
<section aria-labelledby="a-search-heading">
<header class="surface-heading">
<div><span>03 / GLOBAL SEARCH PRESENTATION</span><h2 id="a-search-heading">SEARCH RESULTS</h2></div>
<small>{modelStatusFixtures.length} FIXTURE MATCHES</small>
</header>
<div class="search-results">
{#each modelStatusFixtures as fixture}
<div class="search-result">
<small>{fixture.owner}</small><strong>{fixture.name}</strong><span>{publicBehavior(fixture)}</span><b class:not-modeled={publicStatus(fixture) === 'NOT MODELED'}>{publicStatus(fixture)}</b>
</div>
{/each}
</div>
</section>
</div>
<style>
.prototype-a{display:grid;gap:28px;padding:20px 0 110px}.prototype-heading{min-height:150px;display:grid;grid-template-columns:minmax(0,1fr) minmax(280px,420px);align-items:end;gap:24px;padding:24px;border:1px solid var(--shd-border);border-top:2px solid var(--shd-orange);background:var(--shd-surface)}.prototype-heading p{margin:0;color:var(--shd-text-muted);font:var(--shd-type-supporting)/1.5 var(--shd-font-editorial)}.prototype-heading>div>p{color:var(--shd-orange);font:900 var(--shd-type-telemetry)/1 var(--shd-font-sans);letter-spacing:1px}.prototype-heading>div>p span{display:inline-block;width:22px;border-top:2px solid currentColor;vertical-align:middle}.prototype-heading h1{margin:10px 0 0;font-size:clamp(34px,5vw,64px);line-height:.9;letter-spacing:-1px}.prototype-heading h1 em{color:var(--shd-orange);font-style:normal}.prototype-a>section{display:grid;gap:10px}.surface-heading{min-height:46px;display:flex;align-items:end;justify-content:space-between;gap:16px;padding-bottom:9px;border-bottom:1px solid var(--shd-border)}.surface-heading>div{display:flex;align-items:baseline;gap:12px}.surface-heading span,.surface-heading small{color:var(--shd-text-muted);font-size:var(--shd-type-telemetry);font-weight:800;letter-spacing:.8px}.surface-heading h2{margin:0;font-size:20px;letter-spacing:.6px}.card-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:10px}.model-card{min-width:0;display:flex;flex-direction:column;border:1px solid var(--shd-border);border-top:2px solid var(--shd-border-strong);background:var(--shd-surface)}.model-card>header{min-height:92px;display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:start;gap:10px;padding:14px;border-bottom:1px solid var(--shd-border)}.model-card header small,.quick-view header small{display:block;margin-bottom:6px;color:var(--shd-text-muted);font-size:var(--shd-type-telemetry);font-weight:900;letter-spacing:.8px}.model-card h3,.quick-view h3{margin:0;font-size:18px;line-height:1.05}.model-card header span{display:block;margin-top:7px;color:var(--shd-text-dim);font-size:var(--shd-type-telemetry)}.model-card header strong,.quick-view header strong,.search-result b{padding:5px 7px;border:1px solid var(--shd-success);color:var(--shd-success);font-size:10px;line-height:1;letter-spacing:.7px;white-space:nowrap}.model-card header strong.not-modeled,.quick-view header strong.not-modeled,.search-result b.not-modeled{border-color:var(--shd-border-strong);color:var(--shd-text-muted)}.behavior-block{flex:1;margin:12px;padding:12px;border-left:2px solid var(--shd-success);background:var(--shd-model-surface)}.model-card:has(.not-modeled) .behavior-block{border-left-color:var(--shd-text-dim)}.behavior-block small{color:var(--shd-text-dim);font-size:10px;font-weight:900;letter-spacing:.9px}.behavior-block p{margin:7px 0 0;color:var(--shd-text);font:var(--shd-type-supporting)/1.5 var(--shd-font-editorial)}.model-card>footer{display:flex;justify-content:space-between;gap:10px;padding:10px 12px;border-top:1px solid var(--shd-border-soft);color:var(--shd-text-dim);font-size:10px;font-weight:900;letter-spacing:.6px}.model-card>footer b{color:var(--shd-orange)}.quick-view{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:10px}.quick-view>article{border:1px solid var(--shd-border);background:var(--shd-surface-raised)}.quick-view article>header{display:flex;align-items:start;justify-content:space-between;gap:16px;padding:16px;border-bottom:1px solid var(--shd-border)}.quick-view article>div{padding:18px 16px}.quick-view article>div span{color:var(--shd-text-muted);font-size:10px;font-weight:900;letter-spacing:1px}.quick-view article>div p{max-width:62ch;margin:8px 0 0;font:18px/1.55 var(--shd-font-editorial)}.quick-view dl{display:grid;grid-template-columns:1fr 1fr;margin:0;border-top:1px solid var(--shd-border)}.quick-view dl>div{padding:10px 16px;border-left:1px solid var(--shd-border)}.quick-view dl>div:first-child{border-left:0}.quick-view dt{color:var(--shd-text-dim);font-size:10px;font-weight:900;letter-spacing:.8px}.quick-view dd{margin:4px 0 0;color:var(--shd-text-muted);font-size:var(--shd-type-telemetry)}.search-results{border:1px solid var(--shd-border);background:var(--shd-model-surface)}.search-result{display:grid;grid-template-columns:190px minmax(150px,.7fr) minmax(260px,1.6fr) auto;align-items:center;gap:12px;min-height:58px;padding:8px 12px;border-top:1px solid var(--shd-border-soft)}.search-result:first-child{border-top:0}.search-result>small{color:var(--shd-orange);font-size:var(--shd-type-telemetry);font-weight:900;letter-spacing:.5px}.search-result>strong{font-size:var(--shd-type-supporting)}.search-result>span{color:var(--shd-text-muted);font:var(--shd-type-telemetry)/1.4 var(--shd-font-editorial)}
@media(max-width:1000px){.card-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.search-result{grid-template-columns:minmax(140px,.7fr) minmax(0,1fr) auto}.search-result>small{grid-column:1/-1}.search-result>span{grid-column:2}}
@media(max-width:700px){.prototype-heading,.quick-view,.card-grid{grid-template-columns:1fr}.prototype-heading{align-items:start}.surface-heading{align-items:start}.surface-heading>div{display:grid;gap:4px}.surface-heading>small{display:none}.search-result{grid-template-columns:1fr auto}.search-result>small,.search-result>span{grid-column:1/-1}}
</style>
src/routes/database/ModelStatusVariantB.prototype.svelte
-64
View File
File diff suppressed because one or more lines are too long
src/routes/database/ModelStatusVariantC.prototype.svelte
-66
View File
File diff suppressed because one or more lines are too long
src/routes/database/[category]/+page.server.ts
+16 -4
View File
@@ -502,12 +502,16 @@ export const load: PageServerLoad = async ({ params, url, cookies }) => {
case 'skill-chips':
countSql = `SELECT COUNT(*) AS total FROM skill_chip_sets item WHERE item.active=1${searchClause}`;
rowsSql = `SELECT item.*,bonus.min_value,bonus.max_value,attributes.name AS bonus_stat,attributes.unit AS bonus_unit,
talents.name AS talent_name,talents.description_template AS talent_description,
talents.name AS talent_name,abilities.name AS ability_name,specializations.name AS specialization_name,
(SELECT COUNT(*) FROM skill_chip_primary_options) AS primary_count,
(SELECT COUNT(*) FROM skill_chip_secondary_options) AS secondary_count,
icons.updated_at AS icon_updated_at,render.id AS render_id,render.updated_at AS render_updated_at
FROM skill_chip_sets item
LEFT JOIN skill_chip_two_piece_bonuses bonus ON bonus.skill_chip_set_id=item.id
LEFT JOIN stat_attributes attributes ON attributes.id=bonus.stat_attribute_id
LEFT JOIN skill_chip_talents talents ON talents.skill_chip_set_id=item.id
LEFT JOIN specialization_abilities abilities ON abilities.id=item.specialization_ability_id
LEFT JOIN specializations ON specializations.id=abilities.specialization_id
LEFT JOIN game_data_icons icons ON icons.entity_type='skill_chip' AND icons.entity_id=item.id
LEFT JOIN managed_images render ON render.source_entity_type='skill_chip_render' AND render.source_entity_id=item.id
WHERE item.active=1${searchClause}
@@ -1031,12 +1035,23 @@ export const load: PageServerLoad = async ({ params, url, cookies }) => {
iconUrl: iconUrl('skill_chip', row.id, row.icon_updated_at),
badges: [{ label: 'SUPERIOR' }, { label: 'HIGH-END' }],
facts: [
{
label: 'SPECIALIZATION ABILITY',
value: row.ability_name
? `${row.ability_name} · ${row.specialization_name}`
: 'UNASSIGNED',
},
{
label: '2-PIECE BONUS',
value: row.bonus_stat
? `${row.bonus_stat} · ${range(row.min_value, row.max_value, row.bonus_unit)}`
: 'NOT CONFIGURED',
},
{ label: 'PRIMARY POOL', value: `${row.primary_count} OPTIONS` },
{
label: 'SECONDARY POOL',
value: `${row.secondary_count} OPTIONS`,
},
],
lines: [
{
@@ -1044,9 +1059,6 @@ export const load: PageServerLoad = async ({ params, url, cookies }) => {
value: list(row.talent_name, 'NOT CONFIGURED'),
},
],
description: row.talent_description
? String(row.talent_description)
: undefined,
};
case 'specializations':
return {
src/routes/database/model-status.prototype.ts
-93
View File
@@ -1,93 +0,0 @@
// THROWAWAY PROTOTYPE for issue #5. Fixture lifecycle data must never become a public API.
export type PrototypeVariant = 'A' | 'B' | 'C';
export type PublicModelStatus = 'MODELED' | 'NOT MODELED';
type MechanicLifecycle =
'ready' | 'requires_assumptions' | 'captured_only' | 'absent';
export type ModelStatusFixture = {
id: string;
owner:
| 'Talent'
| 'OS Protocol Talent'
| 'Skill Chip Talent'
| 'Specialization tree-rank effect';
name: string;
context: string;
internal: {
lifecycle: MechanicLifecycle;
current: boolean;
};
modeledText?: string;
authoredText: string;
};
export const modelStatusFixtures: ModelStatusFixture[] = [
{
id: 'talent-ready',
owner: 'Talent',
name: 'Predatory Advance',
context: 'Weapon Talent · Tier I',
internal: { lifecycle: 'ready', current: true },
modeledText:
'On enemy kill: gain +15% Weapon Damage for 10 s. Refreshes and stacks up to 3 times.',
authoredText:
'Killing an enemy grants 15% weapon damage for 10s. Stacks up to 3 times.',
},
{
id: 'protocol-assumptions',
owner: 'OS Protocol Talent',
name: 'Emergency Weave',
context: 'Superior OS Protocol · Talent',
internal: { lifecycle: 'requires_assumptions', current: true },
modeledText:
'When armor breaks: restore 20% Armor over 5 s. Cooldown: 20 s.',
authoredText:
'When armor is broken, restore 20% armor over 5s. Cooldown: 20s.',
},
{
id: 'chip-captured',
owner: 'Skill Chip Talent',
name: 'Rapid Instruction',
context: 'Tactical Skill Chip Set · 3-piece talent',
internal: { lifecycle: 'captured_only', current: true },
modeledText: 'After skill use: gain +8% Skill Haste for 12 s.',
authoredText: 'Using a skill grants 8% Skill Haste for 12s.',
},
{
id: 'specialization-absent',
owner: 'Specialization tree-rank effect',
name: 'Perfect Cadence · Rank 3',
context: 'Sharpshooter · Precision branch',
internal: { lifecycle: 'absent', current: true },
authoredText:
'After reaching 5 hits without missing, your next shot deals 25% increased damage.',
},
{
id: 'talent-stale',
owner: 'Talent',
name: 'Measured Focus',
context: 'Gear Talent · Tier II',
internal: { lifecycle: 'ready', current: false },
modeledText:
'After a headshot: gain +8% Critical Hit Damage for 8 s, stacking up to 3 times.',
authoredText:
'Headshots grant 10% Critical Hit Damage for 8s. Stacks up to 4 times.',
},
];
export const publicStatus = (fixture: ModelStatusFixture): PublicModelStatus =>
fixture.internal.current && fixture.internal.lifecycle !== 'absent'
? 'MODELED'
: 'NOT MODELED';
export const publicBehavior = (fixture: ModelStatusFixture): string =>
publicStatus(fixture) === 'MODELED' && fixture.modeledText
? fixture.modeledText
: fixture.authoredText;
export const prototypeVariantNames = {
A: 'Integrated card hierarchy',
B: 'Evidence rail',
C: 'Registry rows',
} satisfies Record<PrototypeVariant, string>;
tools/game-data-capture/.python-version
+1
View File
@@ -0,0 +1 @@
3.12
tools/game-data-capture/config.example.toml
+24
View File
@@ -0,0 +1,24 @@
# Copy this file to $XDG_CONFIG_HOME/shd-capture/config.toml and adjust local limits.
# The utility reads the OpenAI key from the named environment variable only.
[server]
# Only loopback IP literals are valid: 127.0.0.1 or ::1.
host = "127.0.0.1"
port = 8765
[lifecycle]
# One local process owns this instance name and releases its runtime lock on shutdown.
instance_name = "shd-capture"
lock_timeout_seconds = 5
shutdown_timeout_seconds = 30
[limits]
max_image_bytes = 33554432
max_video_bytes = 4294967296
max_queue_items = 64
max_ocr_text_characters = 20000
[openai]
# Set this name in the process environment. Do not put the key in this file.
api_key_env = "OPENAI_API_KEY"
model = "gpt-4.1-mini"
tools/game-data-capture/contracts/README.md
+133
View File
@@ -0,0 +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`.
## 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.
tools/game-data-capture/contracts/domain-contract-v1.json
+173
View File
@@ -0,0 +1,173 @@
{
"contract_version": 1,
"families": {
"weapon": {
"gear_slot": false,
"views": {
"detail": ["weapon", "weapon_talent"],
"blueprint": ["weapon", "weapon_talent"],
"crafting": ["weapon"],
"stat_range": ["weapon"],
"talent_grid": ["weapon_talent"],
"augmentation": ["weapon_augmentation_profile"]
}
},
"gear": {
"gear_slot": true,
"views": {
"detail": ["gear", "brand_set"],
"blueprint": ["gear", "brand_set"],
"talent": ["gear_talent"],
"augmentation": ["gear_augmentation_profile"]
}
},
"skill_chip": {
"gear_slot": false,
"views": {
"detail": ["skill_chip_set", "skill_chip_roll_pool"],
"set_bonus": ["skill_chip_set_bonus"],
"talent": ["skill_chip_talent"]
}
},
"os_protocol": {
"gear_slot": false,
"views": {
"detail": ["os_protocol"],
"secondary_profile": ["os_protocol_secondary_profile"],
"talent": ["os_protocol_talent"]
}
},
"specialization": {
"gear_slot": false,
"views": {
"overview": ["specialization"],
"details": ["specialization"],
"ability": ["specialization_ability"],
"focus_details": ["specialization_focus"],
"focus_tree": ["specialization_focus", "specialization_tree_node"],
"rank_details": ["specialization_tree_rank"]
}
},
"weapon_mod": {
"gear_slot": false,
"views": {
"detail": ["weapon_mod"]
}
},
"gear_mod": {
"gear_slot": false,
"views": {
"detail": ["gear_mod"]
}
},
"unknown": {
"gear_slot": false,
"views": { "unknown": [] }
}
},
"gear_slots": [
"Mask",
"Gloves",
"Backpack",
"Body Armor",
"Holster",
"Knee Pads"
],
"abstention_reasons": [
"low_confidence",
"ambiguous_family",
"ambiguous_view",
"unsupported_family",
"unsupported_view",
"insufficient_visual_evidence",
"occluded",
"corrupt_image",
"resource_limit",
"cancelled"
],
"missing_reasons": [
"not_visible",
"occluded",
"unreadable",
"not_present_on_screen",
"unsupported",
"ambiguous",
"extraction_failed",
"not_applicable",
"redacted"
],
"states": {
"capture": {
"received": ["spooling", "deduplicated", "failed", "cancelled"],
"spooling": ["stored", "failed", "cancelled"],
"stored": ["queued", "failed"],
"deduplicated": [],
"queued": [],
"failed": ["spooling", "cancelled"],
"cancelled": []
},
"job": {
"queued": ["running", "cancelled"],
"running": ["succeeded", "retry_wait", "failed", "cancelled"],
"retry_wait": ["queued", "failed", "cancelled"],
"succeeded": [],
"failed": ["queued"],
"cancelled": []
},
"extraction": {
"pending": ["local_processing", "cancelled"],
"local_processing": [
"candidate_ready",
"fallback_pending",
"abstained",
"failed",
"cancelled"
],
"fallback_pending": ["fallback_processing", "cancelled"],
"fallback_processing": [
"candidate_ready",
"abstained",
"failed",
"cancelled"
],
"candidate_ready": [],
"abstained": [],
"failed": ["pending"],
"cancelled": []
},
"grouping": {
"ungrouped": ["proposed", "cancelled"],
"proposed": ["grouped", "rejected", "cancelled"],
"grouped": ["split", "superseded"],
"split": ["superseded"],
"superseded": [],
"rejected": ["ungrouped"],
"cancelled": []
},
"review": {
"pending": ["in_review", "cancelled"],
"in_review": ["changes_requested", "approved", "rejected", "cancelled"],
"changes_requested": ["in_review", "rejected", "cancelled"],
"approved": ["in_review"],
"rejected": ["in_review"],
"cancelled": []
},
"export": {
"not_requested": ["queued"],
"queued": ["building", "cancelled"],
"building": ["ready", "failed", "cancelled"],
"ready": ["expired"],
"failed": ["queued", "cancelled"],
"cancelled": [],
"expired": ["queued"]
},
"error": {
"open": ["retryable", "terminal", "dismissed"],
"retryable": ["retrying", "terminal", "dismissed"],
"retrying": ["recovered", "retryable", "terminal"],
"recovered": [],
"terminal": ["dismissed"],
"dismissed": []
}
}
}
tools/game-data-capture/contracts/evidence-archive-manifest-v1.schema.json
+924
View File
@@ -0,0 +1,924 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://shd.build/schemas/game-data-capture/evidence-archive-manifest-v1.json",
"title": "Game data capture evidence archive manifest v1",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"archive_id",
"created_at",
"generator",
"artifacts",
"captures",
"screens",
"jobs",
"extractions",
"groups",
"reviews",
"exports",
"errors",
"evidence_values",
"observed_instances",
"canonical_candidates"
],
"properties": {
"schema_version": { "const": 1 },
"archive_id": { "$ref": "#/$defs/id" },
"created_at": { "$ref": "#/$defs/timestamp" },
"generator": {
"type": "object",
"additionalProperties": false,
"required": ["name", "version", "policy_version"],
"properties": {
"name": { "type": "string", "minLength": 1, "maxLength": 100 },
"version": { "type": "string", "minLength": 1, "maxLength": 50 },
"policy_version": { "type": "string", "minLength": 1, "maxLength": 50 }
}
},
"artifacts": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/artifact" }
},
"captures": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/capture" }
},
"screens": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/screen" }
},
"jobs": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/job" }
},
"extractions": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/extraction" }
},
"groups": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/group" }
},
"reviews": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/review" }
},
"exports": {
"type": "array",
"maxItems": 1000,
"items": { "$ref": "#/$defs/export" }
},
"errors": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/error" }
},
"evidence_values": {
"type": "array",
"maxItems": 100000,
"items": { "$ref": "#/$defs/evidenceValue" }
},
"observed_instances": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/observedInstance" }
},
"canonical_candidates": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/canonicalCandidate" }
}
},
"$defs": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
"timestamp": { "type": "string", "format": "date-time", "maxLength": 40 },
"family": {
"enum": [
"weapon",
"gear",
"skill_chip",
"os_protocol",
"specialization",
"weapon_mod",
"gear_mod",
"unknown"
]
},
"recordType": {
"enum": [
"weapon",
"weapon_talent",
"weapon_augmentation_profile",
"gear",
"brand_set",
"gear_talent",
"gear_augmentation_profile",
"skill_chip_set",
"skill_chip_set_bonus",
"skill_chip_roll_pool",
"skill_chip_talent",
"os_protocol",
"os_protocol_secondary_profile",
"os_protocol_talent",
"specialization",
"specialization_focus",
"specialization_ability",
"specialization_tree_node",
"specialization_tree_rank",
"weapon_mod",
"gear_mod"
]
},
"missingReason": {
"enum": [
"not_visible",
"occluded",
"unreadable",
"not_present_on_screen",
"unsupported",
"ambiguous",
"extraction_failed",
"not_applicable",
"redacted"
]
},
"jsonValue": {
"oneOf": [
{ "type": "null" },
{ "type": "boolean" },
{ "type": "number" },
{ "type": "string", "maxLength": 8192 },
{
"type": "array",
"maxItems": 500,
"items": { "$ref": "#/$defs/jsonValue" }
},
{
"type": "object",
"maxProperties": 500,
"additionalProperties": { "$ref": "#/$defs/jsonValue" }
}
]
},
"sourceEngine": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "engine_id", "engine_version"],
"properties": {
"kind": {
"enum": [
"local_ocr",
"openai_vision",
"classifier",
"manual",
"video_decoder"
]
},
"engine_id": { "type": "string", "minLength": 1, "maxLength": 100 },
"engine_version": { "type": "string", "minLength": 1, "maxLength": 100 }
}
},
"region": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["coordinate_space", "x", "y", "width", "height"],
"properties": {
"coordinate_space": { "const": "normalized" },
"x": { "type": "number", "minimum": 0, "maximum": 1 },
"y": { "type": "number", "minimum": 0, "maximum": 1 },
"width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
"height": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
}
},
{
"type": "object",
"additionalProperties": false,
"required": ["coordinate_space", "x", "y", "width", "height"],
"properties": {
"coordinate_space": { "const": "pixels" },
"x": { "type": "integer", "minimum": 0, "maximum": 100000 },
"y": { "type": "integer", "minimum": 0, "maximum": 100000 },
"width": { "type": "integer", "minimum": 1, "maximum": 100000 },
"height": { "type": "integer", "minimum": 1, "maximum": 100000 }
}
}
]
},
"valueState": {
"type": "object",
"additionalProperties": false,
"required": ["raw_text", "normalized_value", "missing_reason"],
"properties": {
"raw_text": { "type": ["string", "null"], "maxLength": 8192 },
"normalized_value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
}
},
"oneOf": [
{
"properties": {
"normalized_value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"normalized_value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"correction": {
"type": "object",
"additionalProperties": false,
"required": [
"correction_id",
"corrected_at",
"actor",
"reason",
"before",
"after"
],
"properties": {
"correction_id": { "$ref": "#/$defs/id" },
"corrected_at": { "$ref": "#/$defs/timestamp" },
"actor": { "enum": ["local_user", "system_reprocess"] },
"reason": { "type": "string", "minLength": 1, "maxLength": 1000 },
"before": { "$ref": "#/$defs/valueState" },
"after": { "$ref": "#/$defs/valueState" }
}
},
"evidenceValue": {
"type": "object",
"additionalProperties": false,
"required": [
"evidence_id",
"field_path",
"raw_text",
"normalized_value",
"missing_reason",
"confidence",
"source_engine",
"image_artifact_id",
"image_sha256",
"region",
"correction_history"
],
"properties": {
"evidence_id": { "$ref": "#/$defs/id" },
"field_path": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]{1,256}$"
},
"raw_text": { "type": ["string", "null"], "maxLength": 8192 },
"normalized_value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
},
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"source_engine": { "$ref": "#/$defs/sourceEngine" },
"image_artifact_id": { "$ref": "#/$defs/id" },
"image_sha256": { "$ref": "#/$defs/sha256" },
"region": { "$ref": "#/$defs/region" },
"correction_history": {
"type": "array",
"maxItems": 100,
"items": { "$ref": "#/$defs/correction" }
}
},
"oneOf": [
{
"properties": {
"normalized_value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"normalized_value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"fieldClaim": {
"type": "object",
"additionalProperties": false,
"required": [
"path",
"value",
"missing_reason",
"evidence_refs",
"uncertainty_note"
],
"properties": {
"path": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,256}$" },
"value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
},
"evidence_refs": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"uncertainty_note": { "type": ["string", "null"], "maxLength": 2000 }
},
"oneOf": [
{
"properties": {
"value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"classification": {
"type": "object",
"additionalProperties": false,
"required": [
"family",
"view",
"gear_slot",
"record_types",
"confidence",
"abstention_reason"
],
"properties": {
"family": { "$ref": "#/$defs/family" },
"view": { "type": "string" },
"gear_slot": { "type": ["string", "null"] },
"record_types": {
"type": "array",
"uniqueItems": true,
"maxItems": 8,
"items": { "$ref": "#/$defs/recordType" }
},
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"abstention_reason": { "type": ["string", "null"] }
},
"oneOf": [
{
"properties": {
"family": { "const": "weapon" },
"view": {
"enum": [
"detail",
"blueprint",
"crafting",
"stat_range",
"talent_grid",
"augmentation"
]
},
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"weapon",
"weapon_talent",
"weapon_augmentation_profile"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "gear" },
"view": {
"enum": ["detail", "blueprint", "talent", "augmentation"]
},
"gear_slot": {
"enum": [
"Mask",
"Gloves",
"Backpack",
"Body Armor",
"Holster",
"Knee Pads"
]
},
"record_types": {
"minItems": 1,
"items": {
"enum": [
"gear",
"brand_set",
"gear_talent",
"gear_augmentation_profile"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "skill_chip" },
"view": { "enum": ["detail", "set_bonus", "talent"] },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"skill_chip_set",
"skill_chip_set_bonus",
"skill_chip_roll_pool",
"skill_chip_talent"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "os_protocol" },
"view": { "enum": ["detail", "secondary_profile", "talent"] },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"os_protocol",
"os_protocol_secondary_profile",
"os_protocol_talent"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "specialization" },
"view": {
"enum": [
"overview",
"details",
"ability",
"focus_details",
"focus_tree",
"rank_details"
]
},
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"specialization",
"specialization_focus",
"specialization_ability",
"specialization_tree_node",
"specialization_tree_rank"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "weapon_mod" },
"view": { "const": "detail" },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"maxItems": 1,
"items": { "const": "weapon_mod" }
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "gear_mod" },
"view": { "const": "detail" },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"maxItems": 1,
"items": { "const": "gear_mod" }
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "unknown" },
"view": { "const": "unknown" },
"gear_slot": { "const": null },
"record_types": { "maxItems": 0 },
"abstention_reason": {
"enum": [
"low_confidence",
"ambiguous_family",
"ambiguous_view",
"unsupported_family",
"unsupported_view",
"insufficient_visual_evidence",
"occluded",
"corrupt_image",
"resource_limit",
"cancelled"
]
}
}
}
]
},
"artifact": {
"type": "object",
"additionalProperties": false,
"required": [
"artifact_id",
"sha256",
"media_type",
"byte_size",
"sensitivity",
"parent_artifact_id",
"video_timestamp_ms"
],
"properties": {
"artifact_id": { "$ref": "#/$defs/id" },
"sha256": { "$ref": "#/$defs/sha256" },
"media_type": {
"enum": [
"image/png",
"image/webp",
"image/avif",
"video/mp4",
"video/webm",
"video/x-matroska"
]
},
"byte_size": { "type": "integer", "minimum": 1 },
"sensitivity": { "const": "private" },
"parent_artifact_id": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/id" }]
},
"video_timestamp_ms": {
"type": ["integer", "null"],
"minimum": 0,
"maximum": 86400000
}
},
"oneOf": [
{
"properties": {
"media_type": { "enum": ["image/png", "image/webp", "image/avif"] },
"byte_size": { "maximum": 67108864 }
}
},
{
"properties": {
"media_type": {
"enum": ["video/mp4", "video/webm", "video/x-matroska"]
},
"byte_size": { "maximum": 17179869184 }
}
}
]
},
"capture": {
"type": "object",
"additionalProperties": false,
"required": [
"capture_id",
"artifact_id",
"state",
"received_at",
"failure_reason"
],
"properties": {
"capture_id": { "$ref": "#/$defs/id" },
"artifact_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"received",
"spooling",
"stored",
"deduplicated",
"queued",
"failed",
"cancelled"
]
},
"received_at": { "$ref": "#/$defs/timestamp" },
"failure_reason": { "type": ["string", "null"], "maxLength": 2000 }
}
},
"screen": {
"type": "object",
"additionalProperties": false,
"required": [
"screen_id",
"artifact_id",
"classified_at",
"classification"
],
"properties": {
"screen_id": { "$ref": "#/$defs/id" },
"artifact_id": { "$ref": "#/$defs/id" },
"classified_at": { "$ref": "#/$defs/timestamp" },
"classification": { "$ref": "#/$defs/classification" }
}
},
"job": {
"type": "object",
"additionalProperties": false,
"required": [
"job_id",
"kind",
"state",
"attempt",
"max_attempts",
"last_error_id"
],
"properties": {
"job_id": { "$ref": "#/$defs/id" },
"kind": {
"enum": [
"classify",
"ocr",
"vision_fallback",
"frame_extract",
"export"
]
},
"state": {
"enum": [
"queued",
"running",
"retry_wait",
"succeeded",
"failed",
"cancelled"
]
},
"attempt": { "type": "integer", "minimum": 0, "maximum": 20 },
"max_attempts": { "type": "integer", "minimum": 1, "maximum": 20 },
"last_error_id": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/id" }]
}
}
},
"extraction": {
"type": "object",
"additionalProperties": false,
"required": [
"extraction_id",
"screen_id",
"state",
"evidence_refs",
"abstention_reason"
],
"properties": {
"extraction_id": { "$ref": "#/$defs/id" },
"screen_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"pending",
"local_processing",
"fallback_pending",
"fallback_processing",
"candidate_ready",
"abstained",
"failed",
"cancelled"
]
},
"evidence_refs": {
"type": "array",
"maxItems": 1000,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"abstention_reason": { "type": ["string", "null"], "maxLength": 100 }
}
},
"group": {
"type": "object",
"additionalProperties": false,
"required": ["group_id", "state", "screen_ids", "supersedes_group_ids"],
"properties": {
"group_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"ungrouped",
"proposed",
"grouped",
"split",
"superseded",
"rejected",
"cancelled"
]
},
"screen_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"supersedes_group_ids": {
"type": "array",
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
}
}
},
"review": {
"type": "object",
"additionalProperties": false,
"required": ["review_id", "candidate_id", "state", "updated_at", "note"],
"properties": {
"review_id": { "$ref": "#/$defs/id" },
"candidate_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"pending",
"in_review",
"changes_requested",
"approved",
"rejected",
"cancelled"
]
},
"updated_at": { "$ref": "#/$defs/timestamp" },
"note": { "type": ["string", "null"], "maxLength": 4000 }
}
},
"export": {
"type": "object",
"additionalProperties": false,
"required": ["export_id", "state", "artifact_id", "failure_reason"],
"properties": {
"export_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"not_requested",
"queued",
"building",
"ready",
"failed",
"cancelled",
"expired"
]
},
"artifact_id": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/id" }]
},
"failure_reason": { "type": ["string", "null"], "maxLength": 2000 }
}
},
"error": {
"type": "object",
"additionalProperties": false,
"required": ["error_id", "state", "code", "message", "retry_after"],
"properties": {
"error_id": { "$ref": "#/$defs/id" },
"state": {
"enum": [
"open",
"retryable",
"retrying",
"recovered",
"terminal",
"dismissed"
]
},
"code": {
"enum": [
"cancelled",
"resource_limit",
"timeout",
"invalid_input",
"engine_failure",
"storage_failure",
"network_failure",
"schema_rejected",
"unsupported",
"ambiguous"
]
},
"message": { "type": "string", "minLength": 1, "maxLength": 2000 },
"retry_after": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/timestamp" }]
}
}
},
"observedContext": {
"type": "object",
"additionalProperties": false,
"required": ["level", "quality", "tier", "upgrade_state"],
"properties": {
"level": { "$ref": "#/$defs/fieldClaim" },
"quality": { "$ref": "#/$defs/fieldClaim" },
"tier": { "$ref": "#/$defs/fieldClaim" },
"upgrade_state": { "$ref": "#/$defs/fieldClaim" }
}
},
"observedInstance": {
"type": "object",
"additionalProperties": false,
"required": [
"instance_id",
"family",
"source_screen_ids",
"observed_context",
"fields"
],
"properties": {
"instance_id": { "$ref": "#/$defs/id" },
"family": { "$ref": "#/$defs/family" },
"source_screen_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"observed_context": { "$ref": "#/$defs/observedContext" },
"fields": {
"type": "array",
"maxItems": 1000,
"items": { "$ref": "#/$defs/fieldClaim" }
}
}
},
"canonicalCandidate": {
"type": "object",
"additionalProperties": false,
"required": [
"candidate_id",
"record_type",
"source_instance_ids",
"evidence_refs",
"fields",
"completeness",
"relationship_status",
"mechanic_status"
],
"properties": {
"candidate_id": { "$ref": "#/$defs/id" },
"record_type": { "$ref": "#/$defs/recordType" },
"source_instance_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"evidence_refs": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"fields": {
"type": "array",
"maxItems": 1000,
"items": { "$ref": "#/$defs/fieldClaim" }
},
"completeness": { "enum": ["complete", "incomplete", "unsupported"] },
"relationship_status": {
"enum": ["evidenced", "unresolved", "unsupported", "not_applicable"]
},
"mechanic_status": {
"enum": ["evidenced", "unresolved", "unsupported", "not_applicable"]
}
}
}
}
}
tools/game-data-capture/contracts/examples/archive/manifest.invalid.json
+4
View File
@@ -0,0 +1,4 @@
{
"schema_version": 2,
"archive_id": "future-archive"
}
tools/game-data-capture/contracts/examples/archive/manifest.valid.json
+282
View File
@@ -0,0 +1,282 @@
{
"schema_version": 1,
"archive_id": "archive-001",
"created_at": "2026-07-31T12:00:00Z",
"generator": {
"name": "game-data-capture",
"version": "0.1.0",
"policy_version": "1"
},
"artifacts": [
{
"artifact_id": "image-001",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"media_type": "image/png",
"byte_size": 2048,
"sensitivity": "private",
"parent_artifact_id": null,
"video_timestamp_ms": null
}
],
"captures": [
{
"capture_id": "capture-001",
"artifact_id": "image-001",
"state": "queued",
"received_at": "2026-07-31T11:59:55Z",
"failure_reason": null
}
],
"screens": [
{
"screen_id": "screen-001",
"artifact_id": "image-001",
"classified_at": "2026-07-31T11:59:57Z",
"classification": {
"family": "weapon",
"view": "detail",
"gear_slot": null,
"record_types": ["weapon", "weapon_talent"],
"confidence": 0.97,
"abstention_reason": null
}
}
],
"jobs": [],
"extractions": [],
"groups": [],
"reviews": [
{
"review_id": "review-001",
"candidate_id": "candidate-001",
"state": "approved",
"updated_at": "2026-07-31T12:00:00Z",
"note": "Name verified against the image."
}
],
"exports": [],
"errors": [],
"evidence_values": [
{
"evidence_id": "evidence-name",
"field_path": "weapon.name",
"raw_text": "LVOA-C",
"normalized_value": "LVOA-C",
"missing_reason": null,
"confidence": 0.99,
"source_engine": {
"kind": "local_ocr",
"engine_id": "fixture-ocr",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "normalized",
"x": 0.1,
"y": 0.1,
"width": 0.3,
"height": 0.08
},
"correction_history": []
},
{
"evidence_id": "evidence-level",
"field_path": "observed.level",
"raw_text": "20",
"normalized_value": 20,
"missing_reason": null,
"confidence": 0.98,
"source_engine": {
"kind": "local_ocr",
"engine_id": "fixture-ocr",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "pixels",
"x": 50,
"y": 50,
"width": 80,
"height": 30
},
"correction_history": []
},
{
"evidence_id": "evidence-quality",
"field_path": "observed.quality",
"raw_text": "High-end",
"normalized_value": "High-end",
"missing_reason": null,
"confidence": 0.96,
"source_engine": {
"kind": "local_ocr",
"engine_id": "fixture-ocr",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "pixels",
"x": 50,
"y": 85,
"width": 140,
"height": 30
},
"correction_history": []
},
{
"evidence_id": "evidence-tier",
"field_path": "observed.tier",
"raw_text": "T1",
"normalized_value": 1,
"missing_reason": null,
"confidence": 0.97,
"source_engine": {
"kind": "local_ocr",
"engine_id": "fixture-ocr",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "pixels",
"x": 200,
"y": 85,
"width": 60,
"height": 30
},
"correction_history": []
},
{
"evidence_id": "evidence-upgrade",
"field_path": "observed.upgrade_state",
"raw_text": null,
"normalized_value": null,
"missing_reason": "not_visible",
"confidence": 0,
"source_engine": {
"kind": "manual",
"engine_id": "review",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "normalized",
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
"correction_history": []
},
{
"evidence_id": "evidence-damage",
"field_path": "observed.damage",
"raw_text": "12,400",
"normalized_value": 12400,
"missing_reason": null,
"confidence": 1,
"source_engine": {
"kind": "manual",
"engine_id": "review",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "pixels",
"x": 300,
"y": 200,
"width": 160,
"height": 40
},
"correction_history": [
{
"correction_id": "correction-001",
"corrected_at": "2026-07-31T12:00:00Z",
"actor": "local_user",
"reason": "Corrected a missing zero.",
"before": {
"raw_text": "1,240",
"normalized_value": 1240,
"missing_reason": null
},
"after": {
"raw_text": "12,400",
"normalized_value": 12400,
"missing_reason": null
}
}
]
}
],
"observed_instances": [
{
"instance_id": "instance-001",
"family": "weapon",
"source_screen_ids": ["screen-001"],
"observed_context": {
"level": {
"path": "observed.level",
"value": 20,
"missing_reason": null,
"evidence_refs": ["evidence-level"],
"uncertainty_note": null
},
"quality": {
"path": "observed.quality",
"value": "High-end",
"missing_reason": null,
"evidence_refs": ["evidence-quality"],
"uncertainty_note": null
},
"tier": {
"path": "observed.tier",
"value": 1,
"missing_reason": null,
"evidence_refs": ["evidence-tier"],
"uncertainty_note": null
},
"upgrade_state": {
"path": "observed.upgrade_state",
"value": null,
"missing_reason": "not_visible",
"evidence_refs": ["evidence-upgrade"],
"uncertainty_note": "The screen does not show an upgrade indicator."
}
},
"fields": [
{
"path": "observed.damage",
"value": 12400,
"missing_reason": null,
"evidence_refs": ["evidence-damage"],
"uncertainty_note": "This is the configured level-20 instance value, not a canonical range endpoint."
}
]
}
],
"canonical_candidates": [
{
"candidate_id": "candidate-001",
"record_type": "weapon",
"source_instance_ids": ["instance-001"],
"evidence_refs": ["evidence-name"],
"fields": [
{
"path": "weapon.name",
"value": "LVOA-C",
"missing_reason": null,
"evidence_refs": ["evidence-name"],
"uncertainty_note": null
}
],
"completeness": "incomplete",
"relationship_status": "unresolved",
"mechanic_status": "not_applicable"
}
]
}
tools/game-data-capture/contracts/examples/classification/gear.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "gear",
"view": "detail",
"gear_slot": "Vest",
"record_types": ["gear"],
"confidence": 0.95,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/gear.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "gear",
"view": "talent",
"gear_slot": "Body Armor",
"record_types": ["gear_talent"],
"confidence": 0.95,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/gear_mod.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "gear_mod",
"view": "detail",
"gear_slot": "Mask",
"record_types": ["gear_mod"],
"confidence": 0.95,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/gear_mod.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "gear_mod",
"view": "detail",
"gear_slot": null,
"record_types": ["gear_mod"],
"confidence": 0.95,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/os_protocol.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "os_protocol",
"view": "secondary_profile",
"gear_slot": null,
"record_types": ["os_protocol_secondary_profile"],
"confidence": 1.3,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/os_protocol.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "os_protocol",
"view": "secondary_profile",
"gear_slot": null,
"record_types": ["os_protocol_secondary_profile"],
"confidence": 0.93,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/skill_chip.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "skill_chip",
"view": "detail",
"gear_slot": null,
"record_types": ["weapon"],
"confidence": 0.94,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/skill_chip.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "skill_chip",
"view": "set_bonus",
"gear_slot": null,
"record_types": ["skill_chip_set_bonus"],
"confidence": 0.94,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/specialization.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "specialization",
"view": "focus_tree",
"gear_slot": null,
"record_types": ["specialization_tree_node"],
"confidence": 0.91,
"abstention_reason": "ambiguous_view"
}
tools/game-data-capture/contracts/examples/classification/specialization.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "specialization",
"view": "focus_tree",
"gear_slot": null,
"record_types": ["specialization_focus", "specialization_tree_node"],
"confidence": 0.91,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/unknown.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "unknown",
"view": "unknown",
"gear_slot": null,
"record_types": ["weapon"],
"confidence": 0.22,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/unknown.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "unknown",
"view": "unknown",
"gear_slot": null,
"record_types": [],
"confidence": 0.22,
"abstention_reason": "low_confidence"
}
tools/game-data-capture/contracts/examples/classification/weapon.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "weapon",
"view": "talent",
"gear_slot": null,
"record_types": ["weapon"],
"confidence": 0.9,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/weapon.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "weapon",
"view": "detail",
"gear_slot": null,
"record_types": ["weapon", "weapon_talent"],
"confidence": 0.97,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/weapon_mod.invalid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "weapon_mod",
"view": "effect",
"gear_slot": null,
"record_types": ["weapon_mod"],
"confidence": 0.96,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/classification/weapon_mod.valid.json
+8
View File
@@ -0,0 +1,8 @@
{
"family": "weapon_mod",
"view": "detail",
"gear_slot": null,
"record_types": ["weapon_mod"],
"confidence": 0.96,
"abstention_reason": null
}
tools/game-data-capture/contracts/examples/handoff/isac-handoff.invalid.json
+4
View File
@@ -0,0 +1,4 @@
{
"schema_version": 2,
"handoff_id": "future-handoff"
}
tools/game-data-capture/contracts/examples/handoff/isac-handoff.valid.json
+80
View File
@@ -0,0 +1,80 @@
{
"schema_version": 1,
"handoff_id": "handoff-001",
"created_at": "2026-07-31T12:05:00Z",
"source_archive": {
"archive_id": "archive-001",
"manifest_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"schema_version": 1
},
"trust_boundary": {
"intended_destination": "authenticated_isac_intake",
"mutation_authority": "none",
"requires_authenticated_action": true,
"preserves_moderation": true,
"creates_audit_events": false
},
"source_artifacts": [
{
"artifact_id": "image-001",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"media_type": "image/png",
"byte_size": 2048
}
],
"evidence_values": [
{
"evidence_id": "evidence-name",
"field_path": "weapon.name",
"raw_text": "LVOA-C",
"normalized_value": "LVOA-C",
"missing_reason": null,
"confidence": 0.99,
"source_engine": {
"kind": "local_ocr",
"engine_id": "fixture-ocr",
"engine_version": "1"
},
"image_artifact_id": "image-001",
"image_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"region": {
"coordinate_space": "normalized",
"x": 0.1,
"y": 0.1,
"width": 0.3,
"height": 0.08
},
"correction_history": []
}
],
"records": [
{
"handoff_record_id": "handoff-record-001",
"record_type": "weapon",
"intent": "create_draft",
"target_id": null,
"review_state": "approved",
"source_candidate_ids": ["candidate-001"],
"observed_instance_ids": ["instance-001"],
"fields": [
{
"path": "weapon.name",
"value": "LVOA-C",
"missing_reason": null,
"evidence_refs": ["evidence-name"],
"uncertainty_note": null
}
],
"relationships": {
"status": "unresolved",
"evidence_refs": [],
"note": "ISAC must resolve and validate canonical relationships before submission."
},
"mechanics": {
"status": "not_applicable",
"evidence_refs": [],
"note": null
}
}
]
}
tools/game-data-capture/contracts/isac-handoff-v1.schema.json
+412
View File
@@ -0,0 +1,412 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://shd.build/schemas/game-data-capture/isac-handoff-v1.json",
"title": "Authenticated ISAC draft handoff v1",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"handoff_id",
"created_at",
"source_archive",
"trust_boundary",
"source_artifacts",
"evidence_values",
"records"
],
"properties": {
"schema_version": { "const": 1 },
"handoff_id": { "$ref": "#/$defs/id" },
"created_at": { "$ref": "#/$defs/timestamp" },
"source_archive": {
"type": "object",
"additionalProperties": false,
"required": ["archive_id", "manifest_sha256", "schema_version"],
"properties": {
"archive_id": { "$ref": "#/$defs/id" },
"manifest_sha256": { "$ref": "#/$defs/sha256" },
"schema_version": { "const": 1 }
}
},
"trust_boundary": {
"type": "object",
"additionalProperties": false,
"required": [
"intended_destination",
"mutation_authority",
"requires_authenticated_action",
"preserves_moderation",
"creates_audit_events"
],
"properties": {
"intended_destination": { "const": "authenticated_isac_intake" },
"mutation_authority": { "const": "none" },
"requires_authenticated_action": { "const": true },
"preserves_moderation": { "const": true },
"creates_audit_events": { "const": false }
}
},
"source_artifacts": {
"type": "array",
"maxItems": 10000,
"items": { "$ref": "#/$defs/sourceArtifact" }
},
"evidence_values": {
"type": "array",
"maxItems": 100000,
"items": { "$ref": "#/$defs/evidenceValue" }
},
"records": {
"type": "array",
"maxItems": 20000,
"items": { "$ref": "#/$defs/handoffRecord" }
}
},
"$defs": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
"timestamp": { "type": "string", "format": "date-time", "maxLength": 40 },
"recordType": {
"enum": [
"weapon",
"weapon_talent",
"weapon_augmentation_profile",
"gear",
"brand_set",
"gear_talent",
"gear_augmentation_profile",
"skill_chip_set",
"skill_chip_set_bonus",
"skill_chip_roll_pool",
"skill_chip_talent",
"os_protocol",
"os_protocol_secondary_profile",
"os_protocol_talent",
"specialization",
"specialization_focus",
"specialization_ability",
"specialization_tree_node",
"specialization_tree_rank",
"weapon_mod",
"gear_mod"
]
},
"missingReason": {
"enum": [
"not_visible",
"occluded",
"unreadable",
"not_present_on_screen",
"unsupported",
"ambiguous",
"extraction_failed",
"not_applicable",
"redacted"
]
},
"jsonValue": {
"oneOf": [
{ "type": "null" },
{ "type": "boolean" },
{ "type": "number" },
{ "type": "string", "maxLength": 8192 },
{
"type": "array",
"maxItems": 500,
"items": { "$ref": "#/$defs/jsonValue" }
},
{
"type": "object",
"maxProperties": 500,
"additionalProperties": { "$ref": "#/$defs/jsonValue" }
}
]
},
"sourceEngine": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "engine_id", "engine_version"],
"properties": {
"kind": {
"enum": [
"local_ocr",
"openai_vision",
"classifier",
"manual",
"video_decoder"
]
},
"engine_id": { "type": "string", "minLength": 1, "maxLength": 100 },
"engine_version": { "type": "string", "minLength": 1, "maxLength": 100 }
}
},
"region": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["coordinate_space", "x", "y", "width", "height"],
"properties": {
"coordinate_space": { "const": "normalized" },
"x": { "type": "number", "minimum": 0, "maximum": 1 },
"y": { "type": "number", "minimum": 0, "maximum": 1 },
"width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
"height": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
}
},
{
"type": "object",
"additionalProperties": false,
"required": ["coordinate_space", "x", "y", "width", "height"],
"properties": {
"coordinate_space": { "const": "pixels" },
"x": { "type": "integer", "minimum": 0, "maximum": 100000 },
"y": { "type": "integer", "minimum": 0, "maximum": 100000 },
"width": { "type": "integer", "minimum": 1, "maximum": 100000 },
"height": { "type": "integer", "minimum": 1, "maximum": 100000 }
}
}
]
},
"valueState": {
"type": "object",
"additionalProperties": false,
"required": ["raw_text", "normalized_value", "missing_reason"],
"properties": {
"raw_text": { "type": ["string", "null"], "maxLength": 8192 },
"normalized_value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
}
},
"oneOf": [
{
"properties": {
"normalized_value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"normalized_value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"correction": {
"type": "object",
"additionalProperties": false,
"required": [
"correction_id",
"corrected_at",
"actor",
"reason",
"before",
"after"
],
"properties": {
"correction_id": { "$ref": "#/$defs/id" },
"corrected_at": { "$ref": "#/$defs/timestamp" },
"actor": { "enum": ["local_user", "system_reprocess"] },
"reason": { "type": "string", "minLength": 1, "maxLength": 1000 },
"before": { "$ref": "#/$defs/valueState" },
"after": { "$ref": "#/$defs/valueState" }
}
},
"evidenceValue": {
"type": "object",
"additionalProperties": false,
"required": [
"evidence_id",
"field_path",
"raw_text",
"normalized_value",
"missing_reason",
"confidence",
"source_engine",
"image_artifact_id",
"image_sha256",
"region",
"correction_history"
],
"properties": {
"evidence_id": { "$ref": "#/$defs/id" },
"field_path": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]{1,256}$"
},
"raw_text": { "type": ["string", "null"], "maxLength": 8192 },
"normalized_value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
},
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"source_engine": { "$ref": "#/$defs/sourceEngine" },
"image_artifact_id": { "$ref": "#/$defs/id" },
"image_sha256": { "$ref": "#/$defs/sha256" },
"region": { "$ref": "#/$defs/region" },
"correction_history": {
"type": "array",
"maxItems": 100,
"items": { "$ref": "#/$defs/correction" }
}
},
"oneOf": [
{
"properties": {
"normalized_value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"normalized_value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"fieldClaim": {
"type": "object",
"additionalProperties": false,
"required": [
"path",
"value",
"missing_reason",
"evidence_refs",
"uncertainty_note"
],
"properties": {
"path": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,256}$" },
"value": { "$ref": "#/$defs/jsonValue" },
"missing_reason": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/missingReason" }]
},
"evidence_refs": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"uncertainty_note": { "type": ["string", "null"], "maxLength": 2000 }
},
"oneOf": [
{
"properties": {
"value": { "type": "null" },
"missing_reason": { "$ref": "#/$defs/missingReason" }
}
},
{
"properties": {
"value": { "not": { "type": "null" } },
"missing_reason": { "type": "null" }
}
}
]
},
"sourceArtifact": {
"type": "object",
"additionalProperties": false,
"required": ["artifact_id", "sha256", "media_type", "byte_size"],
"properties": {
"artifact_id": { "$ref": "#/$defs/id" },
"sha256": { "$ref": "#/$defs/sha256" },
"media_type": { "enum": ["image/png", "image/webp", "image/avif"] },
"byte_size": { "type": "integer", "minimum": 1, "maximum": 67108864 }
}
},
"evidenceSection": {
"type": "object",
"additionalProperties": false,
"required": ["status", "evidence_refs", "note"],
"properties": {
"status": {
"enum": ["evidenced", "unresolved", "unsupported", "not_applicable"]
},
"evidence_refs": {
"type": "array",
"maxItems": 1000,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"note": { "type": ["string", "null"], "maxLength": 4000 }
}
},
"handoffRecord": {
"type": "object",
"additionalProperties": false,
"required": [
"handoff_record_id",
"record_type",
"intent",
"target_id",
"review_state",
"source_candidate_ids",
"observed_instance_ids",
"fields",
"relationships",
"mechanics"
],
"properties": {
"handoff_record_id": { "$ref": "#/$defs/id" },
"record_type": { "$ref": "#/$defs/recordType" },
"intent": { "enum": ["create_draft", "update_draft", "abstain"] },
"target_id": {
"oneOf": [{ "type": "null" }, { "$ref": "#/$defs/id" }]
},
"review_state": { "enum": ["approved", "abstained"] },
"source_candidate_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"observed_instance_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": { "$ref": "#/$defs/id" }
},
"fields": {
"type": "array",
"maxItems": 1000,
"items": { "$ref": "#/$defs/fieldClaim" }
},
"relationships": { "$ref": "#/$defs/evidenceSection" },
"mechanics": { "$ref": "#/$defs/evidenceSection" }
},
"oneOf": [
{
"properties": {
"intent": { "const": "create_draft" },
"target_id": { "const": null },
"review_state": { "const": "approved" }
}
},
{
"properties": {
"intent": { "const": "update_draft" },
"target_id": { "$ref": "#/$defs/id" },
"review_state": { "const": "approved" }
}
},
{
"properties": {
"intent": { "const": "abstain" },
"target_id": { "const": null },
"review_state": { "const": "abstained" },
"fields": { "maxItems": 0 }
}
}
]
}
}
}
tools/game-data-capture/contracts/screenshot-classification.schema.json
+206
View File
@@ -0,0 +1,206 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://shd.build/schemas/game-data-capture/screenshot-classification-v1.json",
"title": "Screenshot classification v1",
"type": "object",
"additionalProperties": false,
"required": [
"family",
"view",
"gear_slot",
"record_types",
"confidence",
"abstention_reason"
],
"properties": {
"family": {
"enum": [
"weapon",
"gear",
"skill_chip",
"os_protocol",
"specialization",
"weapon_mod",
"gear_mod",
"unknown"
]
},
"view": { "type": "string" },
"gear_slot": { "type": ["string", "null"] },
"record_types": {
"type": "array",
"uniqueItems": true,
"maxItems": 8,
"items": { "type": "string" }
},
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"abstention_reason": { "type": ["string", "null"] }
},
"oneOf": [
{
"properties": {
"family": { "const": "weapon" },
"view": {
"enum": [
"detail",
"blueprint",
"crafting",
"stat_range",
"talent_grid",
"augmentation"
]
},
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": ["weapon", "weapon_talent", "weapon_augmentation_profile"]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "gear" },
"view": { "enum": ["detail", "blueprint", "talent", "augmentation"] },
"gear_slot": {
"enum": [
"Mask",
"Gloves",
"Backpack",
"Body Armor",
"Holster",
"Knee Pads"
]
},
"record_types": {
"minItems": 1,
"items": {
"enum": [
"gear",
"brand_set",
"gear_talent",
"gear_augmentation_profile"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "skill_chip" },
"view": { "enum": ["detail", "set_bonus", "talent"] },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"skill_chip_set",
"skill_chip_set_bonus",
"skill_chip_roll_pool",
"skill_chip_talent"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "os_protocol" },
"view": { "enum": ["detail", "secondary_profile", "talent"] },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"os_protocol",
"os_protocol_secondary_profile",
"os_protocol_talent"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "specialization" },
"view": {
"enum": [
"overview",
"details",
"ability",
"focus_details",
"focus_tree",
"rank_details"
]
},
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"items": {
"enum": [
"specialization",
"specialization_focus",
"specialization_ability",
"specialization_tree_node",
"specialization_tree_rank"
]
}
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "weapon_mod" },
"view": { "const": "detail" },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"maxItems": 1,
"items": { "const": "weapon_mod" }
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "gear_mod" },
"view": { "const": "detail" },
"gear_slot": { "const": null },
"record_types": {
"minItems": 1,
"maxItems": 1,
"items": { "const": "gear_mod" }
},
"abstention_reason": { "const": null }
}
},
{
"properties": {
"family": { "const": "unknown" },
"view": { "const": "unknown" },
"gear_slot": { "const": null },
"record_types": { "maxItems": 0 },
"abstention_reason": {
"enum": [
"low_confidence",
"ambiguous_family",
"ambiguous_view",
"unsupported_family",
"unsupported_view",
"insufficient_visual_evidence",
"occluded",
"corrupt_image",
"resource_limit",
"cancelled"
]
}
}
}
]
}
tools/game-data-capture/migrations/001_initial.sql
+69
View File
@@ -0,0 +1,69 @@
-- Additive utility-local schema. Migration content is fingerprinted at application time.
CREATE TABLE IF NOT EXISTS schema_migrations (
version INTEGER PRIMARY KEY,
filename TEXT NOT NULL UNIQUE,
checksum TEXT NOT NULL,
applied_at TEXT NOT NULL
);
CREATE TABLE blobs (
sha256 TEXT PRIMARY KEY CHECK(length(sha256) = 64),
byte_size INTEGER NOT NULL CHECK(byte_size > 0),
media_type TEXT NOT NULL CHECK(length(media_type) <= 100),
created_at TEXT NOT NULL
);
CREATE TABLE captures (
capture_id TEXT PRIMARY KEY,
blob_sha256 TEXT NOT NULL REFERENCES blobs(sha256) ON DELETE RESTRICT,
state TEXT NOT NULL,
received_at TEXT NOT NULL,
receipt_token TEXT NOT NULL UNIQUE,
failure_reason TEXT,
revision INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE jobs (
job_id TEXT PRIMARY KEY,
capture_id TEXT REFERENCES captures(capture_id) ON DELETE RESTRICT,
kind TEXT NOT NULL CHECK(length(kind) <= 100),
state TEXT NOT NULL,
attempt INTEGER NOT NULL DEFAULT 0 CHECK(attempt >= 0 AND attempt <= 20),
max_attempts INTEGER NOT NULL CHECK(max_attempts BETWEEN 1 AND 20),
lease_owner TEXT, lease_expires_at TEXT, last_error_id TEXT,
revision INTEGER NOT NULL DEFAULT 0
);
CREATE INDEX jobs_available ON jobs(state, lease_expires_at);
CREATE TABLE ocr_runs (
run_id TEXT PRIMARY KEY, capture_id TEXT NOT NULL REFERENCES captures(capture_id),
engine_id TEXT NOT NULL, engine_version TEXT NOT NULL, created_at TEXT NOT NULL,
state TEXT NOT NULL, payload_json TEXT NOT NULL CHECK(length(payload_json) <= 1000000)
);
CREATE TABLE regions (
region_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES ocr_runs(run_id),
region_json TEXT NOT NULL CHECK(length(region_json) <= 10000), created_at TEXT NOT NULL
);
CREATE TABLE classifications (
classification_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES ocr_runs(run_id),
classification_json TEXT NOT NULL CHECK(length(classification_json) <= 10000), created_at TEXT NOT NULL
);
CREATE TABLE extraction_candidates (
candidate_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES ocr_runs(run_id),
candidate_json TEXT NOT NULL CHECK(length(candidate_json) <= 1000000), created_at TEXT NOT NULL
);
CREATE TABLE routing_decisions (
decision_id TEXT PRIMARY KEY, candidate_id TEXT REFERENCES extraction_candidates(candidate_id),
decision_json TEXT NOT NULL CHECK(length(decision_json) <= 10000), created_at TEXT NOT NULL
);
CREATE TABLE review_events (
event_id TEXT PRIMARY KEY, candidate_id TEXT REFERENCES extraction_candidates(candidate_id),
event_json TEXT NOT NULL CHECK(length(event_json) <= 10000), created_at TEXT NOT NULL
);
CREATE TABLE lineage (
lineage_id TEXT PRIMARY KEY, child_id TEXT NOT NULL, parent_id TEXT NOT NULL,
relation TEXT NOT NULL CHECK(length(relation) <= 100), created_at TEXT NOT NULL
);
CREATE TABLE exports (
export_id TEXT PRIMARY KEY, state TEXT NOT NULL, manifest_json TEXT NOT NULL CHECK(length(manifest_json) <= 1000000), created_at TEXT NOT NULL, revision INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE runtime_failures (
failure_id TEXT PRIMARY KEY, subject_type TEXT NOT NULL, subject_id TEXT NOT NULL,
code TEXT NOT NULL, message TEXT NOT NULL CHECK(length(message) <= 512), created_at TEXT NOT NULL
);
tools/game-data-capture/migrations/002_capture_corpus.sql
+38
View File
@@ -0,0 +1,38 @@
-- Durable browser-corpus projections and append-only review evidence.
CREATE TABLE capture_labels (
capture_id TEXT PRIMARY KEY REFERENCES captures(capture_id) ON DELETE RESTRICT,
classification_json TEXT NOT NULL CHECK(length(classification_json) BETWEEN 2 AND 4096),
revision INTEGER NOT NULL DEFAULT 0 CHECK(revision >= 0),
labeled_at TEXT NOT NULL
);
CREATE TABLE capture_label_evidence (
evidence_id INTEGER PRIMARY KEY,
capture_id TEXT NOT NULL REFERENCES captures(capture_id) ON DELETE RESTRICT,
replaced_revision INTEGER NOT NULL CHECK(replaced_revision >= 0),
classification_json TEXT NOT NULL CHECK(length(classification_json) BETWEEN 2 AND 4096),
replaced_at TEXT NOT NULL,
UNIQUE(capture_id, replaced_revision)
);
CREATE INDEX capture_label_evidence_capture ON capture_label_evidence(capture_id, evidence_id);
CREATE INDEX captures_blob_sha256 ON captures(blob_sha256);
CREATE INDEX jobs_capture_id ON jobs(capture_id);
CREATE INDEX ocr_runs_capture_id ON ocr_runs(capture_id);
CREATE INDEX runtime_failures_capture_subject ON runtime_failures(subject_type, subject_id);
CREATE INDEX lineage_child_id ON lineage(child_id);
CREATE INDEX lineage_parent_id ON lineage(parent_id);
CREATE TABLE capture_rejections (
rejection_id INTEGER PRIMARY KEY,
capture_id TEXT NOT NULL UNIQUE REFERENCES captures(capture_id) ON DELETE RESTRICT,
rejected_at TEXT NOT NULL
);
CREATE TABLE capture_deletion_intents (
blob_sha256 TEXT PRIMARY KEY REFERENCES blobs(sha256) ON DELETE RESTRICT,
capture_id TEXT NOT NULL UNIQUE CHECK(length(capture_id) BETWEEN 8 AND 64),
byte_size INTEGER NOT NULL CHECK(byte_size > 0 AND byte_size <= 67108864),
capture_state TEXT NOT NULL CHECK(length(capture_state) BETWEEN 1 AND 32),
received_at TEXT NOT NULL CHECK(length(received_at) BETWEEN 1 AND 40),
receipt_token TEXT NOT NULL UNIQUE CHECK(length(receipt_token) BETWEEN 1 AND 128),
failure_reason TEXT,
revision INTEGER NOT NULL CHECK(revision >= 0),
created_at TEXT NOT NULL CHECK(length(created_at) BETWEEN 1 AND 40)
);
tools/game-data-capture/pyproject.toml
+51
View File
@@ -0,0 +1,51 @@
[build-system]
requires = ["hatchling==1.27.0"]
build-backend = "hatchling.build"
[project]
name = "shd-game-data-capture"
version = "0.1.0"
description = "Local, privacy-preserving game-data capture utility contracts."
requires-python = ">=3.12,<3.13"
license = { text = "UNLICENSED" }
authors = [{ name = "SHD.build" }]
dependencies = [
"fastapi==0.115.12",
"jinja2==3.1.6",
"python-multipart==0.0.20",
"uvicorn==0.34.0",
]
[project.scripts]
shd-capture = "game_data_capture.cli:main"
[dependency-groups]
dev = [
"httpx==0.28.1",
"jsonschema==4.25.1",
"mypy==1.15.0",
"pytest==8.3.5",
"ruff==0.11.0",
"types-jsonschema==4.25.1.20251009",
]
[tool.hatch.build.targets.wheel]
packages = ["src/game_data_capture"]
[tool.ruff]
target-version = "py312"
line-length = 100
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
[tool.mypy]
python_version = "3.12"
strict = true
mypy_path = ["src"]
warn_unreachable = true
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = "-ra"
tools/game-data-capture/src/game_data_capture/__init__.py
+6
View File
@@ -0,0 +1,6 @@
"""Contracts for the local SHD.build game-data capture utility.
Importing this package does not inspect the environment or initialize runtime resources.
"""
__version__ = "0.1.0"
tools/game-data-capture/src/game_data_capture/__main__.py
+6
View File
@@ -0,0 +1,6 @@
"""Module entry point for ``python -m game_data_capture``."""
from .cli import main
if __name__ == "__main__":
raise SystemExit(main())
tools/game-data-capture/src/game_data_capture/cli.py
+163
View File
@@ -0,0 +1,163 @@
"""CLI contracts for the capture utility."""
from __future__ import annotations
import argparse
import json
import sys
from collections.abc import Sequence
from dataclasses import replace
from pathlib import Path
from game_data_capture.config import AppConfig, ConfigError, ServerConfig, load_config
from game_data_capture.doctor import doctor_as_dict, run_doctor
from game_data_capture.paths import PathConfigurationError, RuntimePaths, resolve_runtime_paths
from game_data_capture.runtime import CaptureRuntime, RuntimeFailure
EXIT_OK = 0
EXIT_CONFIG_ERROR = 2
EXIT_UNIMPLEMENTED = 3
EXIT_RUNTIME_ERROR = 4
def _add_config_argument(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--config", type=Path, help="absolute path to a TOML configuration file")
def _port_argument(raw_value: str) -> int:
try:
port = int(raw_value)
except ValueError as error:
raise argparse.ArgumentTypeError("port must be an integer from 1024 to 65535") from error
if not 1024 <= port <= 65535:
raise argparse.ArgumentTypeError("port must be an integer from 1024 to 65535")
return port
def build_parser() -> argparse.ArgumentParser:
"""Build the stable command surface without initializing runtime resources."""
parser = argparse.ArgumentParser(
prog="shd-capture", description="Local SHD.build game-data capture"
)
subcommands = parser.add_subparsers(dest="command", required=True)
doctor = subcommands.add_parser("doctor", help="report local prerequisite status")
_add_config_argument(doctor)
doctor.add_argument("--json", action="store_true", help="emit JSON diagnostics")
serve = subcommands.add_parser("serve", help="start the localhost review service")
_add_config_argument(serve)
serve.add_argument("--host", help="loopback IP literal override")
serve.add_argument("--port", type=_port_argument, help="TCP port override")
watch = subcommands.add_parser("watch", help="watch the Wayland clipboard for images")
_add_config_argument(watch)
watch_modes = watch.add_mutually_exclusive_group()
watch_modes.add_argument("--arm", action="store_true", help="arm live clipboard capture")
watch_modes.add_argument(
"--dry-run", action="store_true", help="validate the capture runtime plan"
)
ingest_image = subcommands.add_parser("ingest-image", help="stage one image for capture")
_add_config_argument(ingest_image)
ingest_image.add_argument("image", type=Path)
import_video = subcommands.add_parser("import-video", help="stage a video for frame extraction")
_add_config_argument(import_video)
import_video.add_argument("video", type=Path)
export = subcommands.add_parser("export", help="write a versioned ISAC handoff")
_add_config_argument(export)
export.add_argument("destination", type=Path)
verify = subcommands.add_parser("verify", help="verify an evidence archive")
_add_config_argument(verify)
verify.add_argument("archive", type=Path)
evaluate = subcommands.add_parser("eval", help="evaluate local OCR and classification")
_add_config_argument(evaluate)
evaluate.add_argument("corpus", type=Path)
purge = subcommands.add_parser("purge", help="purge retained local data")
_add_config_argument(purge)
purge.add_argument("--confirm", action="store_true", help="confirm a future destructive purge")
return parser
def _load_cli_config(config_path: Path | None) -> tuple[AppConfig, RuntimePaths]:
paths = resolve_runtime_paths()
return load_config(config_path=config_path, paths=paths), paths
def _doctor(arguments: argparse.Namespace) -> int:
config, paths = _load_cli_config(arguments.config)
diagnostics = doctor_as_dict(run_doctor(config, paths))
if arguments.json:
print(json.dumps(diagnostics, separators=(",", ":"), sort_keys=True))
else:
for diagnostic in diagnostics:
print(f"{diagnostic['name']}: {diagnostic['status']} ({diagnostic['detail']})")
return EXIT_OK
def _serve_contract(arguments: argparse.Namespace) -> int:
config, paths = _load_cli_config(arguments.config)
host = arguments.host if arguments.host is not None else config.server.host
port = arguments.port if arguments.port is not None else config.server.port
configured = replace(config, server=ServerConfig(host=host, port=port))
CaptureRuntime(configured, paths).serve()
return EXIT_OK
def _unimplemented(command: str) -> int:
print(
f"{command}: subsystem is not implemented; requires gdc-runtime-integration",
file=sys.stderr,
)
return EXIT_UNIMPLEMENTED
def _watch(arguments: argparse.Namespace) -> int:
config, paths = _load_cli_config(arguments.config)
if not arguments.arm and not arguments.dry_run:
return _unimplemented("watch")
runtime = CaptureRuntime(config, paths)
if arguments.dry_run:
runtime.validate_plan()
print("watch dry-run: capture runtime plan is valid")
return EXIT_OK
runtime.watch()
return EXIT_OK
def _ingest_image(arguments: argparse.Namespace) -> int:
config, paths = _load_cli_config(arguments.config)
CaptureRuntime(config, paths).ingest_image(arguments.image)
print("image capture stored")
return EXIT_OK
def main(argv: Sequence[str] | None = None) -> int:
"""Run one CLI command and return a stable process exit status."""
parser = build_parser()
arguments = parser.parse_args(argv)
try:
if arguments.command == "doctor":
return _doctor(arguments)
if arguments.command == "serve":
return _serve_contract(arguments)
if arguments.command == "watch":
return _watch(arguments)
if arguments.command == "ingest-image":
return _ingest_image(arguments)
_load_cli_config(arguments.config)
return _unimplemented(arguments.command)
except (ConfigError, PathConfigurationError) as error:
print(f"configuration error: {error}", file=sys.stderr)
return EXIT_CONFIG_ERROR
except RuntimeFailure:
print("capture runtime failed", file=sys.stderr)
return EXIT_RUNTIME_ERROR
tools/game-data-capture/src/game_data_capture/config.py
+216
View File
@@ -0,0 +1,216 @@
"""Typed, bounded configuration for the capture runtime.
Configuration parsing reads an explicit TOML file only when a caller invokes
``load_config``. Importing this module has no filesystem or environment effects.
"""
from __future__ import annotations
import ipaddress
import os
import re
import tomllib
from collections.abc import Mapping
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from game_data_capture.paths import RuntimePaths, resolve_runtime_paths
_ENVIRONMENT_NAME = re.compile(r"^[A-Z_][A-Z0-9_]{0,63}$")
class ConfigError(ValueError):
"""A bounded, safe-to-display configuration error."""
def _error(field_name: str, constraint: str) -> ConfigError:
return ConfigError(f"Invalid configuration: {field_name} {constraint}.")
def _bounded_int(value: object, field_name: str, minimum: int, maximum: int) -> int:
if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
raise _error(field_name, f"must be an integer from {minimum} to {maximum}")
return value
def _mapping(value: object, field_name: str) -> Mapping[str, object]:
if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
raise _error(field_name, "must be a table")
return value
def _only_keys(section: Mapping[str, object], section_name: str, allowed: set[str]) -> None:
if set(section) - allowed:
raise _error(section_name, "contains an unsupported setting")
def _string(value: object, field_name: str, maximum: int) -> str:
if not isinstance(value, str) or not value or len(value) > maximum:
raise _error(field_name, f"must be a non-empty string up to {maximum} characters")
return value
@dataclass(frozen=True, slots=True)
class ServerConfig:
host: str = "127.0.0.1"
port: int = 8765
def __post_init__(self) -> None:
try:
address = ipaddress.ip_address(self.host)
except ValueError as error:
raise _error("server.host", "must be a loopback IP literal") from error
if not address.is_loopback:
raise _error("server.host", "must be a loopback IP literal")
_bounded_int(self.port, "server.port", 1024, 65535)
@dataclass(frozen=True, slots=True)
class LifecycleConfig:
"""One-instance settings consumed later by the runtime integration layer."""
instance_name: str = "shd-capture"
lock_timeout_seconds: int = 5
shutdown_timeout_seconds: int = 30
def __post_init__(self) -> None:
if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,31}", self.instance_name):
raise _error(
"lifecycle.instance_name", "must use lowercase letters, digits, and hyphens"
)
_bounded_int(self.lock_timeout_seconds, "lifecycle.lock_timeout_seconds", 0, 60)
_bounded_int(self.shutdown_timeout_seconds, "lifecycle.shutdown_timeout_seconds", 1, 300)
@dataclass(frozen=True, slots=True)
class CaptureLimits:
max_image_bytes: int = 32 * 1024 * 1024
max_video_bytes: int = 4 * 1024 * 1024 * 1024
max_queue_items: int = 64
max_ocr_text_characters: int = 20_000
def __post_init__(self) -> None:
_bounded_int(self.max_image_bytes, "limits.max_image_bytes", 1, 64 * 1024 * 1024)
_bounded_int(self.max_video_bytes, "limits.max_video_bytes", 1, 16 * 1024 * 1024 * 1024)
_bounded_int(self.max_queue_items, "limits.max_queue_items", 1, 256)
_bounded_int(self.max_ocr_text_characters, "limits.max_ocr_text_characters", 1, 100_000)
@dataclass(frozen=True, slots=True)
class OpenAIConfig:
api_key_env: str = "OPENAI_API_KEY"
model: str = "gpt-4.1-mini"
def __post_init__(self) -> None:
if not _ENVIRONMENT_NAME.fullmatch(self.api_key_env):
raise _error("openai.api_key_env", "must be an environment variable name")
_string(self.model, "openai.model", 128)
def is_configured(self, environment: Mapping[str, str] | None = None) -> bool:
env = os.environ if environment is None else environment
return bool(env.get(self.api_key_env))
@dataclass(frozen=True, slots=True)
class AppConfig:
server: ServerConfig = field(default_factory=ServerConfig)
lifecycle: LifecycleConfig = field(default_factory=LifecycleConfig)
limits: CaptureLimits = field(default_factory=CaptureLimits)
openai: OpenAIConfig = field(default_factory=OpenAIConfig)
def _section(document: Mapping[str, object], name: str, allowed: set[str]) -> Mapping[str, object]:
value = document.get(name, {})
section = _mapping(value, name)
_only_keys(section, name, allowed)
return section
def parse_config(document: Mapping[str, object]) -> AppConfig:
"""Parse a TOML-shaped mapping with an allowlist of configuration keys."""
_only_keys(document, "root", {"server", "lifecycle", "limits", "openai"})
server = _section(document, "server", {"host", "port"})
lifecycle = _section(
document, "lifecycle", {"instance_name", "lock_timeout_seconds", "shutdown_timeout_seconds"}
)
limits = _section(
document,
"limits",
{"max_image_bytes", "max_video_bytes", "max_queue_items", "max_ocr_text_characters"},
)
openai = _section(document, "openai", {"api_key_env", "model"})
return AppConfig(
server=ServerConfig(
host=_string(server.get("host", "127.0.0.1"), "server.host", 64),
port=_bounded_int(server.get("port", 8765), "server.port", 1024, 65535),
),
lifecycle=LifecycleConfig(
instance_name=_string(
lifecycle.get("instance_name", "shd-capture"), "lifecycle.instance_name", 32
),
lock_timeout_seconds=_bounded_int(
lifecycle.get("lock_timeout_seconds", 5), "lifecycle.lock_timeout_seconds", 0, 60
),
shutdown_timeout_seconds=_bounded_int(
lifecycle.get("shutdown_timeout_seconds", 30),
"lifecycle.shutdown_timeout_seconds",
1,
300,
),
),
limits=CaptureLimits(
max_image_bytes=_bounded_int(
limits.get("max_image_bytes", 32 * 1024 * 1024),
"limits.max_image_bytes",
1,
64 * 1024 * 1024,
),
max_video_bytes=_bounded_int(
limits.get("max_video_bytes", 4 * 1024 * 1024 * 1024),
"limits.max_video_bytes",
1,
16 * 1024 * 1024 * 1024,
),
max_queue_items=_bounded_int(
limits.get("max_queue_items", 64), "limits.max_queue_items", 1, 256
),
max_ocr_text_characters=_bounded_int(
limits.get("max_ocr_text_characters", 20_000),
"limits.max_ocr_text_characters",
1,
100_000,
),
),
openai=OpenAIConfig(
api_key_env=_string(
openai.get("api_key_env", "OPENAI_API_KEY"), "openai.api_key_env", 64
),
model=_string(openai.get("model", "gpt-4.1-mini"), "openai.model", 128),
),
)
def load_config(config_path: Path | None = None, paths: RuntimePaths | None = None) -> AppConfig:
"""Read optional TOML configuration from the XDG config location.
An absent file selects safe defaults. Parse failures intentionally omit source values and paths.
"""
selected_path = (
config_path if config_path is not None else (paths or resolve_runtime_paths()).config_file
)
if not selected_path.is_absolute() or len(str(selected_path)) > 240:
raise _error("config path", "must be an absolute path within 240 characters")
if not selected_path.exists():
return AppConfig()
try:
with selected_path.open("rb") as handle:
document: Any = tomllib.load(handle)
except (OSError, tomllib.TOMLDecodeError) as error:
raise _error("config file", "could not be read") from error
if not isinstance(document, dict):
raise _error("root", "must be a table")
return parse_config(document)
tools/game-data-capture/src/game_data_capture/doctor.py
+84
View File
@@ -0,0 +1,84 @@
"""Side-effect-limited local diagnostics for capture prerequisites."""
from __future__ import annotations
import importlib.util
import shutil
from collections.abc import Mapping
from dataclasses import asdict, dataclass
from os import environ
from game_data_capture.config import AppConfig
from game_data_capture.paths import (
PathConfigurationError,
RuntimePaths,
prepare_private_directories,
)
@dataclass(frozen=True, slots=True)
class Diagnostic:
name: str
status: str
detail: str
def _executable_diagnostic(name: str) -> Diagnostic:
return Diagnostic(
name=name,
status="available" if shutil.which(name) else "unavailable",
detail="executable found on PATH" if shutil.which(name) else "executable not found on PATH",
)
def _gpu_diagnostic(environment: Mapping[str, str]) -> Diagnostic:
configured_provider = environment.get("GDC_OCR_PROVIDER")
if configured_provider:
return Diagnostic(
"gpu_provider", "unknown", "provider configured; runtime probe is deferred"
)
if importlib.util.find_spec("torch") is not None:
return Diagnostic(
"gpu_provider", "unknown", "torch is installed; runtime probe is deferred"
)
return Diagnostic("gpu_provider", "unknown", "no provider selected; runtime probe is deferred")
def _storage_diagnostic(paths: RuntimePaths) -> Diagnostic:
try:
prepare_private_directories(paths)
except (OSError, PathConfigurationError):
return Diagnostic(
"storage_permissions", "unavailable", "private XDG directories are not usable"
)
return Diagnostic(
"storage_permissions", "available", "private XDG directories use owner-only access"
)
def run_doctor(
config: AppConfig, paths: RuntimePaths, environment: Mapping[str, str] | None = None
) -> tuple[Diagnostic, ...]:
"""Inspect local prerequisites without launching processes or making network calls."""
env = environ if environment is None else environment
return (
_executable_diagnostic("niri"),
_executable_diagnostic("wl-paste"),
_executable_diagnostic("ffmpeg"),
_gpu_diagnostic(env),
_storage_diagnostic(paths),
Diagnostic(
"openai",
"configured" if config.openai.is_configured(env) else "missing",
"environment variable is present"
if config.openai.is_configured(env)
else "environment variable is absent",
),
)
def doctor_as_dict(diagnostics: tuple[Diagnostic, ...]) -> list[dict[str, str]]:
"""Return diagnostics in a serialization-ready form without paths or secret values."""
return [asdict(diagnostic) for diagnostic in diagnostics]
tools/game-data-capture/src/game_data_capture/domain/__init__.py
+43
View File
@@ -0,0 +1,43 @@
"""Side-effect-free domain contracts for the game data capture utility."""
from .state_machines import InvalidStateTransition, StateMachine, require_transition
from .taxonomy import (
ABSTENTION_REASONS,
GEAR_SLOTS,
RECORD_TYPES_BY_VIEW,
SCREEN_VIEWS,
AbstentionReason,
Family,
GearSlot,
RecordType,
)
from .validation import (
ContractValidationError,
ensure_supported_version,
validate_archive_document,
validate_archive_references,
validate_classification,
validate_handoff_document,
validate_handoff_references,
)
__all__ = [
"ABSTENTION_REASONS",
"GEAR_SLOTS",
"RECORD_TYPES_BY_VIEW",
"SCREEN_VIEWS",
"AbstentionReason",
"ContractValidationError",
"Family",
"GearSlot",
"InvalidStateTransition",
"RecordType",
"StateMachine",
"ensure_supported_version",
"require_transition",
"validate_archive_document",
"validate_archive_references",
"validate_classification",
"validate_handoff_document",
"validate_handoff_references",
]
tools/game-data-capture/src/game_data_capture/domain/models.py
+149
View File
@@ -0,0 +1,149 @@
"""Typed Python views of the portable contract structures."""
import typing
type JsonValue = None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]
type MissingReason = typing.Literal[
"not_visible",
"occluded",
"unreadable",
"not_present_on_screen",
"unsupported",
"ambiguous",
"extraction_failed",
"not_applicable",
"redacted",
]
type ScreenshotFamily = typing.Literal[
"weapon",
"gear",
"skill_chip",
"os_protocol",
"specialization",
"weapon_mod",
"gear_mod",
"unknown",
]
type CanonicalRecordType = typing.Literal[
"weapon",
"weapon_talent",
"weapon_augmentation_profile",
"gear",
"brand_set",
"gear_talent",
"gear_augmentation_profile",
"skill_chip_set",
"skill_chip_set_bonus",
"skill_chip_roll_pool",
"skill_chip_talent",
"os_protocol",
"os_protocol_secondary_profile",
"os_protocol_talent",
"specialization",
"specialization_focus",
"specialization_ability",
"specialization_tree_node",
"specialization_tree_rank",
"weapon_mod",
"gear_mod",
]
class SourceEngine(typing.TypedDict):
kind: typing.Literal["local_ocr", "openai_vision", "classifier", "manual", "video_decoder"]
engine_id: str
engine_version: str
class NormalizedRegion(typing.TypedDict):
coordinate_space: typing.Literal["normalized"]
x: float
y: float
width: float
height: float
class PixelRegion(typing.TypedDict):
coordinate_space: typing.Literal["pixels"]
x: int
y: int
width: int
height: int
type BoundingRegion = NormalizedRegion | PixelRegion
class ValueState(typing.TypedDict):
raw_text: str | None
normalized_value: JsonValue
missing_reason: MissingReason | None
class Correction(typing.TypedDict):
correction_id: str
corrected_at: str
actor: typing.Literal["local_user", "system_reprocess"]
reason: str
before: ValueState
after: ValueState
class EvidenceValue(ValueState):
evidence_id: str
field_path: str
confidence: float
source_engine: SourceEngine
image_artifact_id: str
image_sha256: str
region: BoundingRegion
correction_history: list[Correction]
class FieldClaim(typing.TypedDict):
path: str
value: JsonValue
missing_reason: MissingReason | None
evidence_refs: list[str]
uncertainty_note: str | None
class ScreenshotClassification(typing.TypedDict):
family: ScreenshotFamily
view: str
gear_slot: (
typing.Literal["Mask", "Gloves", "Backpack", "Body Armor", "Holster", "Knee Pads"] | None
)
record_types: list[CanonicalRecordType]
confidence: float
abstention_reason: str | None
class ObservedContext(typing.TypedDict):
level: FieldClaim
quality: FieldClaim
tier: FieldClaim
upgrade_state: FieldClaim
class ObservedItemInstance(typing.TypedDict):
"""Values shown for one configured item; they are not reusable definitions."""
instance_id: str
family: ScreenshotFamily
source_screen_ids: list[str]
observed_context: ObservedContext
fields: list[FieldClaim]
class CanonicalDefinitionCandidate(typing.TypedDict):
"""Evidence-backed reusable claims, kept separate from the observed item."""
candidate_id: str
record_type: CanonicalRecordType
source_instance_ids: list[str]
evidence_refs: list[str]
fields: list[FieldClaim]
completeness: typing.Literal["complete", "incomplete", "unsupported"]
relationship_status: typing.Literal["evidenced", "unresolved", "unsupported", "not_applicable"]
mechanic_status: typing.Literal["evidenced", "unresolved", "unsupported", "not_applicable"]
tools/game-data-capture/src/game_data_capture/domain/ports.py
+214
View File
@@ -0,0 +1,214 @@
"""Trust-boundary ports. Implementations belong to downstream tasks."""
from __future__ import annotations
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from datetime import datetime
from enum import StrEnum
from math import isfinite
from typing import Protocol
@dataclass(frozen=True, slots=True)
class ResourceBudget:
deadline_monotonic: float | None
max_input_bytes: int
max_output_bytes: int
max_items: int
def __post_init__(self) -> None:
limits: tuple[tuple[str, object], ...] = (
("max_input_bytes", self.max_input_bytes),
("max_output_bytes", self.max_output_bytes),
("max_items", self.max_items),
)
for name, value in limits:
if isinstance(value, bool) or not isinstance(value, int) or value < 0:
raise ValueError(f"{name} must be a non-negative integer")
deadline: object = self.deadline_monotonic
if deadline is not None:
if isinstance(deadline, bool) or not isinstance(deadline, int | float):
raise ValueError("deadline_monotonic must be a finite number or null")
if not isfinite(deadline):
raise ValueError("deadline_monotonic must be finite or null")
class CancellationToken(Protocol):
def is_cancelled(self) -> bool: ...
def raise_if_cancelled(self) -> None: ...
class Clock(Protocol):
def now_utc(self) -> datetime: ...
def monotonic(self) -> float: ...
class IdGenerator(Protocol):
def new_id(self) -> str: ...
@dataclass(frozen=True, slots=True)
class BlobReceipt:
sha256: str
byte_size: int
media_type: str
class BlobStorage(Protocol):
"""Stores immutable bytes by digest without exposing filesystem paths."""
def put(
self,
chunks: Iterable[bytes],
*,
expected_sha256: str | None,
media_type: str,
budget: ResourceBudget,
cancellation: CancellationToken,
) -> BlobReceipt: ...
def read(
self,
sha256: str,
*,
budget: ResourceBudget,
cancellation: CancellationToken,
) -> Iterable[bytes]: ...
def exists(self, sha256: str) -> bool: ...
class Repository[RecordT](Protocol):
def get(self, record_id: str) -> RecordT | None: ...
def add(self, record: RecordT) -> None: ...
def replace(self, record: RecordT, *, expected_revision: int) -> None: ...
type CaptureRepository = Repository[object]
type JobRepository = Repository[object]
type ExtractionRepository = Repository[object]
type GroupingRepository = Repository[object]
type ReviewRepository = Repository[object]
type ExportRepository = Repository[object]
type ErrorRepository = Repository[object]
class UnitOfWork(Protocol):
captures: CaptureRepository
jobs: JobRepository
extractions: ExtractionRepository
groupings: GroupingRepository
reviews: ReviewRepository
exports: ExportRepository
errors: ErrorRepository
def commit(self) -> None: ...
def rollback(self) -> None: ...
@dataclass(frozen=True, slots=True)
class ImageInput:
artifact_id: str
sha256: str
media_type: str
byte_size: int
@dataclass(frozen=True, slots=True)
class EngineResult:
engine_id: str
engine_version: str
payload: Mapping[str, object]
class OcrEngine(Protocol):
def extract(
self,
image: ImageInput,
*,
regions: Sequence[Mapping[str, int | float | str]],
budget: ResourceBudget,
cancellation: CancellationToken,
) -> EngineResult: ...
class VisionFallback(Protocol):
"""Accepts bounded artifacts and never receives credentials in a request."""
def extract(
self,
images: Sequence[ImageInput],
*,
response_schema: Mapping[str, object],
request_fingerprint: str,
budget: ResourceBudget,
cancellation: CancellationToken,
) -> EngineResult: ...
@dataclass(frozen=True, slots=True)
class SubprocessRequest:
tool: SubprocessTool
arguments: tuple[str, ...]
environment: Mapping[SubprocessEnvironmentKey, str]
stdin: bytes | None
budget: ResourceBudget
class SubprocessTool(StrEnum):
WL_PASTE = "wl-paste"
FFMPEG = "ffmpeg"
FFPROBE = "ffprobe"
class SubprocessEnvironmentKey(StrEnum):
WAYLAND_DISPLAY = "WAYLAND_DISPLAY"
XDG_RUNTIME_DIR = "XDG_RUNTIME_DIR"
PATH = "PATH"
HOME = "HOME"
LANG = "LANG"
LC_ALL = "LC_ALL"
@dataclass(frozen=True, slots=True)
class SubprocessResult:
return_code: int
stdout: bytes
stderr: bytes
timed_out: bool
cancelled: bool
class SubprocessRunner(Protocol):
"""Runs an argument array without a shell and with an explicit environment."""
def run(
self,
request: SubprocessRequest,
*,
cancellation: CancellationToken,
) -> SubprocessResult: ...
@dataclass(frozen=True, slots=True)
class FrameScore:
timestamp_ms: int
stability: float
sharpness: float
ui_coverage: float
class FrameScorer(Protocol):
def score(
self,
frames: Sequence[ImageInput],
*,
budget: ResourceBudget,
cancellation: CancellationToken,
) -> Sequence[FrameScore]: ...
tools/game-data-capture/src/game_data_capture/domain/state_machines.py
+211
View File
@@ -0,0 +1,211 @@
"""State vocabularies and allowed transitions for recoverable workflows."""
from collections.abc import Mapping
from dataclasses import dataclass
from enum import StrEnum
from types import MappingProxyType
from typing import Final
class CaptureState(StrEnum):
RECEIVED = "received"
SPOOLING = "spooling"
STORED = "stored"
DEDUPLICATED = "deduplicated"
QUEUED = "queued"
FAILED = "failed"
CANCELLED = "cancelled"
class JobState(StrEnum):
QUEUED = "queued"
RUNNING = "running"
RETRY_WAIT = "retry_wait"
SUCCEEDED = "succeeded"
FAILED = "failed"
CANCELLED = "cancelled"
class ExtractionState(StrEnum):
PENDING = "pending"
LOCAL_PROCESSING = "local_processing"
FALLBACK_PENDING = "fallback_pending"
FALLBACK_PROCESSING = "fallback_processing"
CANDIDATE_READY = "candidate_ready"
ABSTAINED = "abstained"
FAILED = "failed"
CANCELLED = "cancelled"
class GroupingState(StrEnum):
UNGROUPED = "ungrouped"
PROPOSED = "proposed"
GROUPED = "grouped"
SPLIT = "split"
SUPERSEDED = "superseded"
REJECTED = "rejected"
CANCELLED = "cancelled"
class ReviewState(StrEnum):
PENDING = "pending"
IN_REVIEW = "in_review"
CHANGES_REQUESTED = "changes_requested"
APPROVED = "approved"
REJECTED = "rejected"
CANCELLED = "cancelled"
class ExportState(StrEnum):
NOT_REQUESTED = "not_requested"
QUEUED = "queued"
BUILDING = "building"
READY = "ready"
FAILED = "failed"
CANCELLED = "cancelled"
EXPIRED = "expired"
class ErrorState(StrEnum):
OPEN = "open"
RETRYABLE = "retryable"
RETRYING = "retrying"
RECOVERED = "recovered"
TERMINAL = "terminal"
DISMISSED = "dismissed"
@dataclass(frozen=True, slots=True)
class StateMachine:
name: str
transitions: Mapping[str, frozenset[str]]
def allows(self, current: str, target: str) -> bool:
return target in self.transitions.get(current, frozenset())
def _machine(name: str, transitions: dict[str, set[str]]) -> StateMachine:
return StateMachine(
name=name,
transitions=MappingProxyType(
{state: frozenset(targets) for state, targets in transitions.items()}
),
)
STATE_MACHINES: Final[Mapping[str, StateMachine]] = MappingProxyType(
{
"capture": _machine(
"capture",
{
"received": {"spooling", "deduplicated", "failed", "cancelled"},
"spooling": {"stored", "failed", "cancelled"},
"stored": {"queued", "failed"},
"deduplicated": set(),
"queued": set(),
"failed": {"spooling", "cancelled"},
"cancelled": set(),
},
),
"job": _machine(
"job",
{
"queued": {"running", "cancelled"},
"running": {"succeeded", "retry_wait", "failed", "cancelled"},
"retry_wait": {"queued", "failed", "cancelled"},
"succeeded": set(),
"failed": {"queued"},
"cancelled": set(),
},
),
"extraction": _machine(
"extraction",
{
"pending": {"local_processing", "cancelled"},
"local_processing": {
"candidate_ready",
"fallback_pending",
"abstained",
"failed",
"cancelled",
},
"fallback_pending": {"fallback_processing", "cancelled"},
"fallback_processing": {
"candidate_ready",
"abstained",
"failed",
"cancelled",
},
"candidate_ready": set(),
"abstained": set(),
"failed": {"pending"},
"cancelled": set(),
},
),
"grouping": _machine(
"grouping",
{
"ungrouped": {"proposed", "cancelled"},
"proposed": {"grouped", "rejected", "cancelled"},
"grouped": {"split", "superseded"},
"split": {"superseded"},
"superseded": set(),
"rejected": {"ungrouped"},
"cancelled": set(),
},
),
"review": _machine(
"review",
{
"pending": {"in_review", "cancelled"},
"in_review": {
"changes_requested",
"approved",
"rejected",
"cancelled",
},
"changes_requested": {"in_review", "rejected", "cancelled"},
"approved": {"in_review"},
"rejected": {"in_review"},
"cancelled": set(),
},
),
"export": _machine(
"export",
{
"not_requested": {"queued"},
"queued": {"building", "cancelled"},
"building": {"ready", "failed", "cancelled"},
"ready": {"expired"},
"failed": {"queued", "cancelled"},
"cancelled": set(),
"expired": {"queued"},
},
),
"error": _machine(
"error",
{
"open": {"retryable", "terminal", "dismissed"},
"retryable": {"retrying", "terminal", "dismissed"},
"retrying": {"recovered", "retryable", "terminal"},
"recovered": set(),
"terminal": {"dismissed"},
"dismissed": set(),
},
),
}
)
class InvalidStateTransition(ValueError):
"""Raised when a caller attempts a transition absent from the contract."""
def require_transition(machine_name: str, current: str, target: str) -> None:
machine = STATE_MACHINES.get(machine_name)
if machine is None:
raise InvalidStateTransition(f"Unknown state machine: {machine_name}")
if current not in machine.transitions:
raise InvalidStateTransition(f"Unknown {machine_name} state: {current}")
if not machine.allows(current, target):
raise InvalidStateTransition(f"Invalid {machine_name} transition: {current} -> {target}")

Some files were not shown because too many files have changed in this diff Show More