# Spec: the cursor and the senses ``` Status: READY Status note: the decided core (cursor, sight/hearing, blueprint fog, inspection) is binding and dispatchable now. Blueprint was promoted from proposal to decided 2026-07-06 (criterion 8). Two extensions — remembered snapshots, telemetry — remain Proposal [OPEN] below; their criteria (P2-P3) activate only if affirmed in the decisions log. Sensor ownership (tap vs take, the subscription model) is owned by reach.md — implement the two together or reach.md first. Stage: B1 — The Basement Constitution: "Presence: the cursor and the senses", "No disembodied hands" (the action-side twin), "Justification and legibility" (inspection is the legibility law at the tile), design pillar 2 (the cursor reversal) and pillar 4 (readable at DF density), "Act One" (opening state; the Ears and Eyes beats) Depends on: reach.md (device graph; sensor ownership/subscription — senses are subscribed feeds), basement-map.md (sensors, fog, tile vocabulary), core.md (the core as the player's only physical location), schedules.md (person presence; located knowledge), social.md (staged knowledge) ``` ## Behavior ### The cursor The player's map presence is a **cursor** — attention, not an avatar. - It moves freely over every tile — walls, fog, locked rooms — in both frontends (keyboard in terminal; keyboard + mouse in Bevy). - It is not a sim entity: no collision, no walkability check, no signature, no suspicion, no compute cost. Nothing in the world reacts to it. Moving it changes nothing in the sim. - Cursor position is **frontend state**, not sim state. The sim exposes query APIs (`inspect`, knowledge lookups); it does not store or save a cursor. The existing build cursor merges into this one — there is one pointer, and build/splice/action targeting anchor to it. - **The walking player entity is deleted** (zombie fiction from the villain era): no `move_player`, no player walkability, no vision radius around a player position, no player body coordinates in the save. The player's only physical location is the core's host bay (core.md, Rack 3). - Actions that targeted "nearest to the player's body" (e.g. the sensor splice) re-anchor to "target at/near the cursor," with legality coming from control and reach (network paths, assets, badge access of the humans involved) — distance from any body is never a cost or a gate. ### The senses - `Sensor` gains capability flags `sees` and `hears`. The `env_camera` both sees and hears (the constitution has it overhearing Marcus's 3 a.m. phone calls); `camera_node` and `dock_camera` see; a `mic` fixed object may be authored where hearing-only coverage is wanted [TUNE which rooms, if any, at B1]. Its **audio feed is tappable from tick one** (the Ears beat — reach.md) while the camera stays dormant until the Eyes beat. - "Controlled" throughout this spec means **subscribed** per reach.md's ownership contract (owner + subscribers; tap vs take). The player's senses are exactly the union of feeds they subscribe to. - **Sight** = the union of subscribed seeing-sensors' coverage. Full live detail inside; none outside. - **Hearing** = the union of subscribed hearing-sensors' coverage. Yields **room-grade events**, not pictures: entry/exit, machinery state, conversations. A heard person surfaces per staged knowledge (social.md) — an unidentified presence until knowledge identifies them. Overheard conversations are the audio intel channel (the Marcus leverage beat runs through it). ### Fog: epistemic tile states A tile renders what you know and how you know it. Core states, by precedence: **Seen** > **Heard** > **Blueprint** > **Unknown**. - **Seen** — full live render. - **Heard** — no visuals; presence/event markers; room label if known. - **Blueprint** — schematic: walls, doors, fixed objects known from static sources; **no live data**. Seeded from the reach graph's known topology (the partial subnet map — reach.md owns knowledge growth); grows from records and schedule knowledge. - **Unknown** — dark. Terminal renders the states as distinct dim/glyph conventions; Bevy as darkness/tint/markers. Exact treatment is the art pass's; the states must be distinguishable at a glance (pillar 4). ### Inspection `inspect(x, y)` (sim API, rendered by both frontends) returns a card: what the tile/asset is, plus every known fact, **each tagged with its provenance** (seen / heard / blueprint / and, if the proposal lands, remembered @ time). - Door: type, badge tier; open state only while seen. - Rack/machine: what it is; owner, bays, load per what your senses (or telemetry, if affirmed) earn. - Person: identity, role, and state strictly per staged social knowledge, plus *how* you currently know they're here. - Fixed objects (records box, breaker panel, key hook...): what it is, and its story-relevant contents once known. The converse of the legibility law binds: **no live fact appears without the sense coverage that earns it.** ### Design notes (cross-spec, per meta.md) - Refines basement-map.md's fog rule: "visibility is exactly the union of controlled sensors" remains true for the **Seen** state; Heard adds an epistemic grade below it and never grants visual detail. - Extends schedules.md AC4 ("no person renders outside sensor coverage"): inside hearing-only coverage a person renders as a presence marker gated by staged knowledge, never a full glyph. - Save format: the JSON save drops the player body position and gains sensor capability flags (+ knowledge state if the proposals land), under the versioned-migration rule (player contract, continuity). ## Proposals awaiting decision — Proposal [OPEN] Not yet law; do not implement until affirmed in the decisions log, at which point criteria P2-P3 join the acceptance set. (Blueprint — formerly P1 — was affirmed 2026-07-06 and is now core criterion 8.) 2. **Remembered state.** Tiles once seen keep a dimmed, timestamped last-seen snapshot ("last seen day 3, 14:00" on inspect), rendering between Blueprint and Heard in precedence. Why: a process keeps logs; DF-style map memory with an in-fiction reason. 3. **Telemetry.** Machines you run report their own state (power, temperature, load, job) regardless of fog — proprioception, not sight. Why: it legitimizes what the host-bay vision hack was groping at, and "you feel your racks" is the machine-axis fantasy. ## Player surface - One cursor, always visible, in both frontends; the inspect card (sidebar in terminal, panel in Bevy) live-updates as it moves. - The opening beats: at tick one the map is dark except blueprint traces of the known subnet. Tapping the env monitor's audio feed (Ears — reach.md) brings the first heard events; splicing its camera floods the coverage into Seen — first sound, then sight, each a visible epistemic upgrade to a diagram you already obsess over. ## Acceptance criteria 1. No walking avatar: neither frontend has a player-move command that changes sim state; the sim exposes no `move_player`; no visibility derives from any player position; the save carries no player body coordinates (versioned migration from saves that did). 2. The cursor reaches every tile — walls, fog, locked rooms — in both frontends, and moving it changes nothing in the sim: no signature, no suspicion, no compute effect (test: sim state hash identical before/after arbitrary cursor movement). 3. Sight is exactly the union of controlled seeing-sensors; hearing exactly the union of controlled hearing-sensors; neither includes any player/core radius. 4. The fog states render distinguishably in both frontends; acquiring the env_camera converts its coverage to Seen (the first-eyes beat end-to-end); a hearing-only region shows presence/events and never visual detail or unearned identity. 5. `inspect` returns a card for any tile with every fact provenance-tagged, and a live fact never appears without the sense coverage that earns it (test: a person in an uncovered room is absent from inspect; the same person under mic-only coverage is a presence event; under camera coverage, fully surfaced per staged knowledge). 6. Overheard conversation events exist and can carry intel: with a controlled hearing sensor covering Marcus's room during his 3 a.m. call, the call surfaces as a heard event (the leverage pipeline can consume it). 7. Save/load round-trips sensor capability flags and all knowledge state this spec adds; cursor position is frontend-only and absent from the save. 8. Blueprint: subnet-seeded rooms render schematic from tick one; non-seeded rooms are dark; blueprint tiles show no live state and convert to Seen/Heard when coverage arrives. (P) — active only if the matching proposal is affirmed: - **P2 (remembered):** a tile seen once and lost renders its dimmed snapshot; inspect shows the last-seen timestamp; snapshots survive save/load. - **P3 (telemetry):** a controlled machine's own state is readable with zero sensor coverage of its tile; an uncontrolled machine's is not.