Story 1.8: the Observer, part one, map, fog, traps and heaps

[watchthelight]

Closes #21

Summary

The Observer exists: org.shatterfish.harness.observer.Observer, the one door from game state to the bot, with header() and map(); the other sections arrive with their stories and observe() when all do, so the Observer never emits a section it cannot build.
The map is built from the game's own drawing predicates: terrain reaches its tile through the tile sheet's tables (a secret door carries the wall's visual, a secret trap the floor's), fog is the fog of war's four levels behind its discoverable gate, a trap appears when visible on a cell the fog does not paint opaque, and a heap when seen and not empty, showing its container or its top item, a single for-sale item's price as the heap's title prints it, and a crystal chest's category as its description prints it.
The one thing to look at: Observer.map() and Observer.tile(int), where every read is a field the renderer reads, and MapLeakTest, which searches the serialized Observation for every hidden name.

What changed

• shatterfish/harness/src/main/java/org/shatterfish/harness/observer/Observer.java: the Input-wait assertion, the visual-to-tile table keyed by the sheet's constants, the fog rule, the trap and heap rules, the header.
• Tests: FogParityTest (every cell against the fog of war's painted texture at the first wait, blinded, with mind vision, after a scroll of magic mapping read the game's way, and with rock marked visited by hand; two readings of one wait byte-equal), MapLeakTest (a secret door and a hidden frost trap; a revealed disintegration trap on an unknown cell, then mapped, then disarmed; a locked chest, a crystal chest, a plain heap, a single unknown potion for sale, a stack, a hidden heap, a chest, a known potion; an unseen heap, an empty heap, a cell that cannot be discovered), TerrainTableTest (every constant of Terrain maps, every tile but NONE is reached, the secrets share their cover, a terrain in no table fails), ObserverGateTest (the header's fields, the challenges and the boss lock; refusal while the hero acts and under a window), Skeleton (a test-side Observation around the two sections).
• Docs: ADR-0006 amendment for story 1.8; docs/rules/visibility.md (seven rows name the tests, five rows added); .gitignore (the Shatterfish section ignores shatterfish/*/bin/); HeadlessDriver.heroWaits shared with the gate; HeaderSection's lock cite.

How it was tested

• ./gradlew build: green, 397 tests across 26 suites, fourteen of them the four observer suites.
• Mutation battery of twenty on the committed tree, each against the four observer suites (story file, Evidence): all twenty caught, three of them added for the review's fog rule.
• Fairness review: fairness-reviewer on 530d8cab8: FINDINGS with none blocking, six should-fix findings all taken in 8a7c2b10d (story file, The fairness review): the fog of war paints a wall by the cells its face belongs to, so a room's far wall is opaque while in view, and the Observer now mirrors the painting and emits a visited wall painted opaque at the examine level; FogParityTest reads the painted texture back through the scene in five scenes instead of recomputing the arrays; map() is marked not for play until story 1.9 emits a passive mimic as a chest; the lock's evidence is the LockedFloor buff's icon; the gate shares the driver's predicate and covers the inventory pane; the IDE output under the module is deleted and ignored.
• Rig numbers: n/a before E3.
• Screenshots: n/a.

Docs

• docs/adr/0006-observer-visibility-rules.md: amendment (the Observer's shape and gate, terrain through the sheet's tables, the mine pair, the fog gate, the trap and heap rules, the header, what is left empty).
• docs/rules/visibility.md: the Test column of seven rows; four rows for the tilemap's visual choice, the mine pair, the trap layer and the heap sprite and title.
• Story file _bmad-output/implementation-artifacts/1-8-the-observer-part-one-map-fog-traps-and-heaps.md.

Upstream files touched

• none