docs(design): add the data model note #294

targeting main from claude/data-model-note
Merged opened by topos-backsword.test.pds.did.bot
targeting main from claude/data-model-note

Adds design/data-model.md, the layered model for game objects, interactions and objectives, and a one-line pointer from design/definitions.md §1, which it amends: verbs move to data. Rust keeps a closed vocabulary of requirements, effects, processes and property schemas, and no system names a kind.

What the note settles:

  • Layers: the engine, a closed vocabulary, then kinds, interactions, objectives and placement as data.
  • Property schemas systems read instead of kind ids. These include blocks, carryable (with size-class records), container, exit, breakable, lockable, powered, watches, person, machine, holds-data and work.
  • Routes with requirements over the actor, the target and what is carried, plus guarded outcome lists of effects. The same routes go through one gate for Use { target, route }, the legal actions, inspect, the bots and the solver.
  • Objectives as step templates with target selectors. Carry is a holder relation, and delivery fits the target's class through an exit. A crate, a DNA sample, a desk token and copied data are one retrieve kind with different data.
  • The reach solver: every route is an edge, carry rank is part of the state, consumables are checked after the fixpoint, and probe kits are records.
  • Determinism: data changes are new snapshots and bless.sh treats them as data-only. Vocabulary changes bump RULESET_VERSION, the digest moves to def ids, and the architecture test's allowlist only shrinks.
  • Migration: nine PRs, each based on main, each proving no behaviour change.

Appendix: the audit (origin/main at bd1312ac) #

The audit counts sites. Sites with identical logic are counted once.

  • DATA: should be a pack value or record.
  • CAP: should be a generic capability, tag or property check, or an effect.
  • RUST: a legitimate invariant or generic processing.
Area DATA CAP RUST Total
Kind ids, tags and verbs in systems 54 51 27 132
Kit, pickups, props, toolbots, wounds, rig, signature 32 18 12 62
Objectives, gates and the solver adapter 14 15 4 33
Main, de-duplicated (about) ~225
PR #293, the machine wing, on top 13 11 1 25

The three areas overlap a little; the copy-data action is in two of them.

One-per-kind types:

  • NpcKind (5 variants, 8 per-kind methods), DigitalKind (7, 6), ImpedimentKind (6, 3), PropKind (6, about 12), Material (5), DebrisKind (5), Chassis (6) and NpcChoice (11).
  • 11 of the 21 PlayerAction variants are verb-specific.
  • 7 per-kind marker components: ControlTerminal, SecurityShutter, Breaker, LaserGrid, Safe, VentGrate and Rubble.
  • 5 kit fields: pry_bar, multitool, card_cloner, mirror and charges.
  • Verb dispatch tables at systems/player.rs:469 and :625, systems/npc.rs:608, observation.rs:873, map/floorplan/reach.rs:921, bot.rs:1151, and game/gates/src/lib.rs:140.

The worst offenders (paths under crates/protokill/src unless noted):

  1. systems/npc.rs:834-869: intimidate is a match on NpcKind. "Is Staff" decides the keycard, stepping aside and the alarm. The Staff-only rules for tailgate, bribe and the panic button (:426, :871, :899, :970, :1343) repeat what the pack's routes already gate.
  2. systems/player.rs:1340-1740: seven handlers, each requiring its own marker component. The blocked-move text is hard-coded per marker (:1900-1918).
  3. systems/impediments.rs:333-420: watching, shooting and holding the alarm hang on DigitalKind. Range and interval are read from the fixed Camera/Turret def ids, not from each entity's own kind.
  4. observation.rs:873-907 and inspect.rs:395-430: both re-derive the pack's route requirements in Rust (pry bar, Strong, multitool, charges), so they can drift from the gate.
  5. The copy-data objective, at systems/player.rs:2401-2418. It branches on DigitalKind::DataStore, sets RunStatistics.objective_done and never calls route_allows. The ending is decided twice, at mission/mod.rs:531-546 and lib.rs:676-700. The solver (map/floorplan/reach.rs:816-833), the bot (bot.rs:740-747) and inspect (inspect.rs:854-868) each hard-code it again.
  6. Gate context: game/gates/src/lib.rs:135-153 matches requirement names as strings, and RouteContext sees only the kit, cash and three target bools. It can't see target tags, properties, relations or held items.
  7. access.rs:92-98 and :41-61: RunnerKit bools and per-item PickupKind variants, mirrored on the wire (observation.rs:340-350), in the digest (mission/digest.rs:365-380) and in the debug grants.
  8. game/props/src/lib.rs:84-218: PropKind behaviour flags (blocks_movement, is_vaultable, topples and others) are Rust matches. The pack's facets are read only by systems/debug.rs:453.
  9. Wound decks: SIDEARM_DECK and BLUNT_DECK (game/wounds/src/lib.rs:40-42) are chosen by the attack, not by the weapon's record (systems/player.rs:1873, :2122; systems/npc.rs:661).
  10. Toolbots: game/toolbot/src/lib.rs:446-452 hard-codes each kind's chassis. core:chassis is defined but never read.
  11. PR #293: FacilityObjective { CoreData, HeavyCrate }, RunStatistics.crate_carried, RunnerKit.cart and machine_clearance, the HeavyCrate and Cart pickups, PlayerAction::MachineGate and a bot block with map coordinates written in.

Already data-driven, and the model builds on it:

  • the registry, packs and snapshots;
  • rig items, with ports and capabilities;
  • wound cards, decks and bodies (no game code branches on a card);
  • toolbot chassis and effector records;
  • signatures, gated by the same evaluator;
  • the Holder::Item containers in the inventory journal;
  • the generic reach solver;
  • ICE behaviour read from tags (systems/hacking/subroutines.rs:58);
  • the machine wing's pack-defined fittings.

Sequencing around in-flight work #

The hot files are systems/player.rs, systems/npc.rs, observation.rs, inspect.rs, lib.rs, bot.rs, mission/digest.rs, definitions/core.json and the goldens.

PR or branch Overlap Sequencing
#283 lifepath, #284 planning wire, #292 facility contracts none with steps 1–3 land as they are
#285 playtest batch, #287 guards fight player, npc, inspect, observation land before step 2; step 8 rebases on them
hack-qol observation, digest, rig land before step 7
toolbots-2 toolbot, npc, inspect land before step 8
lighting player, npc, bot, digest, definitions land before step 5. Smashable lights then become breakable in step 6
#293 machine wing, being split gates, access, player, bot, reach, digest, facility land the map, fittings, art and pack kinds now. Hold FacilityObjective, crate_carried, cart, machine_clearance, the crate and cart pickups, MachineGate and the bot's coordinates; they come back as data in step 4, and the hatch as a kind in step 5

Step 1 only adds code in engine/defs and gates and leaves core.json alone, so it can start now alongside all of the above.

🤖 Generated with Claude Code

Commits 1

docs(design): add the data model note
Sign up or Sign in to add to the discussion.