Defensive QA tooling for ARK: Survival Ascended inventory consistency testing on private or otherwise authorized environments.

This project is designed as a reproducible Python harness for collecting inventory observations, recording episode evidence, checking invariants, and producing reviewable anomaly reports. It is intentionally scoped for controlled QA work and portfolio demonstration, not public-server exploitation or offensive automation.

This repository is unofficial and is not affiliated with Studio Wildcard, Snail Games, or ARK: Survival Ascended.

Use this project only on systems you own, administer, or have explicit permission to test.

This project does not provide exploit instructions, evasion logic, public-server abuse workflows, bot automation, OCR, RCON/Nitrado integrations, or ML-driven gameplay automation.

• Models inventory snapshots with strict validation.
• Records observations as observations.jsonl and episode results as result.json.
• Runs conservation checks with compare_inventory_totals.
• Supports fixture-backed dry runs for local testing.
• Parses [ASA_QA] inventory observations from text logs.
• Records intended manual inventory actions and validates observed deltas.
• Generates per-episode summaries and export bundles.
• Builds a local SQLite index for querying episodes, actions, checks, and anomalies.
• Provides pytest coverage for models, observers, recorder, runner, CLI, indexing, exporting, and hardening cases.

• runner: orchestrates episodes and maps outcomes to result statuses.
• observers: collect inventory state from fixtures or [ASA_QA] log lines.
• recorder: persists observations, actions, checks, manifests, summaries, and results.
• invariants: validates expected properties such as total inventory conservation.
• reporter: creates human-readable episode summaries.
• db: builds a local SQLite index from generated episode outputs.
• exporter: creates compact evidence bundles for review.
• guided: helps an operator run a manual DevKit episode and then process the log.

Future modules such as adapters, fuzzing, and ML are intentionally not implemented yet.

Requirements:

• Python 3.11+
• uv

Run the test suite:

uv run --with pytest pytest

Run a fixture-backed dry episode:

uv run asa-qa dry-run --episode-id demo_fixture --before data/fixtures/before.json --after data/fixtures/after.json --output-root data

Run a log-backed episode from the sample fixture:

uv run asa-qa log-run --episode-id ep_000001 --log-file data/fixtures/sample_asa_qa.log --output-root data

Create a new episode id:

uv run asa-qa new-episode-id

Rebuild the local SQLite index from generated episodes:

uv run asa-qa rebuild-index --episodes-root data/episodes --db-path data/db.sqlite

Export an episode evidence bundle:

uv run asa-qa export-episode --episode-id ep_000001 --episodes-root data/episodes --output-root data/exports --overwrite

Run the guided manual DevKit workflow:

uv run asa-qa guided-run --episode-id ep_guided_001 --log-file path/to/ShooterGame.log

Generated outputs under data/episodes/, data/exports/, and data/db.sqlite are ignored by git.

Inventory state is represented as locations containing item counts:

{
  "box_a": {
    "metal": 100
  },
  "box_b": {
    "metal": 0
  },
  "player": {
    "metal": 0
  }
}

An episode records a before and after inventory observation, then compares totals by item. If totals differ, the result status becomes ANOMALY; otherwise, the episode can pass while still surfacing action-check review warnings where appropriate.

Allowed result statuses:

• PASS
• FAIL_BOT
• FAIL_OBSERVER
• ANOMALY
• NEEDS_REVIEW
• CRASH
• TIMEOUT

The docs/ directory contains versioned notes for the current probe/log contract, action checks, hardening cases, guided runs, exports, episode manifests, and the SQLite index.

Useful starting points:

• PROJECT_GUIDE.md
• docs/ASA_QA_INVENTORY_PROBE_V0_1.md
• docs/DEVKIT_OPERATION_RECIPE_V0_1.md
• docs/ACTION_CHECKS_V0_1.md
• docs/SQLITE_INDEX_V0_1.md

The current Python harness is test-covered and runs without a real game server by using fixtures and sample logs. At the time of public prep, the local suite passed with:

112 passed

Not implemented yet:

• ArkDevKit Blueprint source in this repository.
• OCR-based inventory reading.
• Bot input or gameplay automation.
• RCON or Nitrado adapters.
• Fuzzing for generated inventory scenarios.
• ML-assisted scenario prioritization.
• Remote dashboarding or hosted reporting.

Near-term improvements for a more polished public project:

• Keep CI green on GitHub Actions.
• Add more sample episodes generated only from sanitized fixtures.
• Document a small end-to-end demo flow with expected output.
• Add contribution guidelines if the project becomes collaborative.