fix: harden engine across casino, economy, concurrency, security, and content

2 files changed, 24 insertions, 11 deletions

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 4eaa843..ffe4f7b 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -332,9 +332,21 @@ casino configurations. Raw file editing is not a validated save endpoint.
   the room's tables and machines (including legacy slots table entries).
 - Supported table games are `blackjack` and `baccarat`; machines use `slots`
   with the optional variant `huff_and_even_more_puff`.
+- Only one table/machine per game is addressable: a room is addressed by game
+  name (`play blackjack`), so a second entry for the same game, or the same
+  machine variant (including a legacy slots table alongside a slots machine),
+  is rejected as unreachable content.
 - Omitted/zero numeric values keep their existing defaults. Negative bets,
   timers, seat counts, split counts, decks, and payouts are rejected.
 - An explicit `max_bet` must be at least `min_bet`; zero still means no cap.
+- A blackjack table that offers `surrender` must set `min_bet` to at least 2:
+  a surrendered hand returns half the bet, which rounds down to zero below
+  that (the omitted default of 1 is rejected too).
+- Shoe coverage is best-effort, not a hard floor. The shoe reshuffles at the
+  start of a round when it is smaller than the heuristic round size (eleven
+  cards per hand--an all-ace hand can exceed that), and `draw()` rebuilds an
+  exhausted shoe in place. A small `decks` value therefore never invalidates
+  a table or darkens the room's other casino games.
 - `decks` is capped at 64 to bound shoe allocation. An explicit `shuffle_at`
   must be greater than zero and less than one.
 - Payouts and shuffle fractions must be finite (no NaN/infinity). Slots `payout`
diff --git a/building_guide/tick_order.md b/building_guide/tick_order.md
index b4d1f1e..b1246dd 100644
--- a/building_guide/tick_order.md
+++ b/building_guide/tick_order.md
@@ -107,9 +107,10 @@ stores initialized (`World`, `MobStore`, `Hub`, `queue`, etc. via
 
 - Systems that touch the hub: guard with `if g.Hub == nil { return }` at the
   top, *or* guard each `Hub.*` call with `if g.Hub != nil`. Either is fine.
-  (Note: `Ticks.Start` runs *before* `SetHub` in `main.go`, so the master
-  subscriber can fire with `Hub == nil` during startup — guards are not
-  optional.)
+  (`main.go` now calls `SetHub` *before* `Ticks.Start`, so the production
+  server never ticks with a nil hub; the guards are belt-and-braces for a
+  `*Game` that tests construct without `SetHub`, such as
+  `newRunTickSystemsTestGame`.)
 - Systems that iterate over maps/slices held on `*Game` (`sequences`,
   `restTimers`, `guardWatchTimers`, `hackingStates`, …) must tolerate empty
   / freshly-initialized maps. `game.New` initializes all of them; tests that
@@ -126,16 +127,16 @@ When writing content that depends on per-tick ordering (a trigger that
 should fire *after* regen, a sequence whose step messages should appear
 *before* the move completes, etc.), consult the table above and remember:
 
-- `MoveTick` (step 2) runs before `SequenceTick` (step 3) — the table
+- `MoveTick` (table #3) runs before `SequenceTick` (table #4) — the table
   fires top-to-bottom, so a move that completes this tick will have its
-  enter-room knock-on triggers fire (inside step 1 or step 2) before
-  trigger `sequences` advance in step 3.
+  enter-room knock-on triggers fire (inside `ProcessQueuedCommands`, #1, or
+  `MoveTick`, #3) before trigger `sequences` advance in #4.
 - `on_enter` / `on_exit` room triggers fire from command execution, not
-  from a per-tick system; they run inside `ProcessQueuedCommands` (step 1)
-  or `MoveTick` (step 2) when the move actually completes.
-- Shop restock (step 6) happens *before* `RegenTick` (step 7) and *before*
-  `AdvanceActions` (step 13); if a gathering action completes this tick
-  it does so in step 13, by which point shop state for this tick has
+  from a per-tick system; they run inside `ProcessQueuedCommands` (#1)
+  or `MoveTick` (#3) when the move actually completes.
+- Shop restock (`MobStore.Tick`, #7) happens *before* `RegenTick` (#8) and
+  *before* `AdvanceActions` (#14); if a gathering action completes this tick
+  it does so in #14, by which point shop state for this tick has
   already advanced.
 
 When in doubt, the test in `tick_systems_test.go` is the executable