hatz

Deterministic simulation engine for adversarial multi-agent scenarios: deception and identity uncertainty under partial, information-brokered observations.

Simulation Summary

This project implements the Hats Simulator: a discrete-time world simulation plus an Information Broker interface that charges for uncertain information and accepts limited defensive actions.

World Model

• The world is a bounded 2D grid with integer coordinates.
• Entities:
  • Hats: mobile agents with a hidden “true” affiliation and a set of capabilities.
  • Beacons: fixed locations representing targets; each beacon has a set of vulnerabilities (capability requirements) and an alert level.
  • Organizations: groups of hats. Some are benign; some are terrorist.

Time and Dynamics

• Time advances in discrete ticks.
• Each tick, hats may move and organizations may plan and execute meetings.
• A meeting occurs at a location/time with a set of participating hats and may involve capability trades (capabilities can be transferred among hats).
• Meeting plans are generated by organization “planners” that form taskforces:
  • Resource meetings assemble required capabilities via trades.
  • Decoy meetings add noise for defenders.
  • A taskforce culminates in a final meeting.

Attack Semantics

• A beacon attack occurs when a terrorist taskforce completes its final meeting at a beacon and the taskforce’s available capabilities satisfy the beacon’s vulnerabilities.
• Attacks and defensive decisions contribute to the final score/report.

Defender Role: Information Broker + Actions

The defender (human or agent) interacts only via a formal interface:

1. Simulator controls

• initialize a run (seed + parameters), advance ticks, end run and produce report.

2. Information Broker (IB) requests

• Free requests provide baseline information (e.g., world dimensions, beacon list, capability universe, known terrorist hats, org lists, event history).
• Paid requests provide uncertain/noisy information about hats and meetings (e.g., hat location, hat capabilities, meeting times/locations/participants/trades).
• Paid requests accept a payment; higher payments yield higher probability of correctness (per the IB noise model).

3. Player actions

• alert beacon: set beacon alert level (OFF / LEVEL_ONE / LEVEL_TWO).
• arrest hat: attempt to arrest a hat at a specific location; success depends on simulation state and rules.
• Arrested hats remain in the world but cannot contribute to capability trading or attacks (implementation details per spec).

Information Quality and Cost Model

• Paid IB queries return correct information with probability determined by payment; otherwise a noise process perturbs results (e.g., location perturbation, list element noise).
• Requests may have frequency limits (e.g., once per tick vs once per run), enforced per analyst.

Outputs

• The simulation produces:
  • event history (attacks, arrests, alerts, etc.),
  • a final report including outcomes (attacks/saves), false arrests, alert effectiveness, and total spend.

Determinism

• Runs are seeded; the same seed + parameters + actions yield the same results.

Running

Requirements: Zig 0.15.2+ (per build.zig.zon).

Build the executable:

zig build

Run the demo CLI (prints JSON responses to stdout):

zig build run

Run tests:

zig build test

Contract Fixtures

Golden request/response fixtures live under tools/contract/examples/. See tools/contract/README.md for naming and replay order.