Tide Scheduler

Status: Designed — independent review applied
Author: Jeroen + agent panel
Last Updated: 2026-08-26
Independent /design-review: APPROVED WITH CONDITIONS 2026-08-26 — all findings applied same day (H2 recurrence bound restated honestly; B1 signed index ranges; M2 epochIndex diff keys; H1 completion-tick sampling; B2 held-violet ruling; H3/M1/M3/M4 precision; L1–L5 incl. salt constants + RNG pin)
Creative Director Review (CD-GDD-ALIGN): APPROVED 2026-08-26
Implements Pillar: Pillar 1 — The Tide Waits for No One
Spike Reference: prototypes/tide-scheduler-spike-2026-08-25/SPIKE-NOTE.md (contract validated 9/9)

Overview

The Tide Scheduler is the Foundation system that makes Driftlands' world move. It is a pure function — DockedLands(seed, wallClockTime) — that determines, for any moment in real time, which landmasses are docked at the home island's shore sockets, which are approaching, and which are departing. It stores no schedule state: the world's past, present, and future are all computable from the world seed and a clock, which is what lets the game run with no server and lets nothing happen while everyone is offline except time passing. Every other MVP system hangs off it — docked lands are where harvesting, combat, and hauling happen; departure is the deadline that gives them stakes; recurrence is the promise that makes missing a land a story instead of a loss.

Players never interact with the scheduler directly. They experience it as the tide: lands arriving on a learnable rhythm, the shore warming amber before a docking and cooling violet before a departure, and the between-sessions question that drives the group's planning — "what's docking tomorrow?" This GDD defines the tide's cadence and recurrence as rules (per the Creative Director's gate condition: recurrence is Pillar 1's only legal mitigation and cannot stay vague), on top of the deterministic contract validated by the scheduler spike (prototypes/tide-scheduler-spike-2026-08-25/SPIKE-NOTE.md, 9/9 contract tests).

Player Fantasy

The tide is infrastructure the player never touches — the fantasy is **living with it, not controlling it**. Its emotional promise is earned literacy: the quiet competence of someone who reads a system the world treats as chaos. The anchor moment: it's Wednesday night, someone posts a screenshot of the horizon — amber bleeding into the cloudbank at the northeast socket — and types *"tin highlands, tomorrow, before work."* No wiki, no menu. They know, the way a fisherman knows weather from cloud shape, because they've watched that color twenty times and it always meant the same thing next. This is the game's #1 aesthetic (Discovery) applied to the schedule itself, and it is a fantasy that fires every session — most tide moments are one player, logging in alone, glancing at the color of the sky.

Its necessary shadow is legible consequence. Someone logs in Saturday morning and the tin highlands are gone — cooled to violet and departed in the night while everyone slept. The beat of "damn, we missed it" resolves into "it'll come back," and the story told in group chat is fond, not bitter — sailors recounting the storm that scared them, not the one that ruined them. Because players are literate readers of the tide, a missed land is a legible failure ("we knew Thursday was coming and we still missed it"), never an opaque one — which is what keeps Pillar 1's indifference feeling like a living world instead of a punishment. The target emotional arc: **competence → occasional humbling → recurrence restores trust → competence again.**

**Tone constraints this fantasy imposes (binding on all player-facing text and UI):** never punitive language — no "YOU MISSED IT" banners, no loss-framed system messages; departures are stated as world facts, not player failures. And a design test for future tide features: if a proposal optimizes the docking event for spectacle players are expected to gather for (fanfares, forced camera pans, presence bonuses), it serves the wrong fantasy — the communal shore-watch vigil is a key-art and trailer beat, never a mechanic. Rewarding synchronous presence punishes exactly the uneven schedules this game is built for.

Reference anchors: Lineage 2's world-that-moves-without-you (competence over time, not spectacle in the moment); harbor towns — things arriving and leaving on schedules older than you.

Detailed Design

Core Rules

• World time. Tide time t is UTC seconds (Unix epoch), owned by the host. Clients never derive tide state from their own clocks — the host replicates t — only t; its computed results are re-derived locally (ADR-0008, 2026-09-11) — on join and on change; clients may re-evaluate the pure function locally only for visual lead, deriving their local visual t as lastReceivedHostT + monotonicLocalElapsed (a monotonic timer, never wall-clock), reset to the host value on every update — presentation only, never an input to any gameplay decision (review M3, locked 2026-08-26). DateTime.Now and local timezones never touch tide math (DST-immune by construction).
• Monotonic time. t never moves backward relative to the save's own history: on load, t = max(lastKnownGoodT, hostUtcNow), with lastKnownGoodT updated at each evaluation. Clock-set-back (accident or cheat) is thereby closed. Clock-skip-forward is possible, permissive, and documented: in a private friends game, skipping the tide is cheating yourself out of anticipation — no anti-cheat machinery.
• The world is computed, never simulated. DockedLands(seed, t, config) is a pure function — no stored schedule state, no accumulation, no offline ticking. Absence of any length costs exactly nothing to evaluate and produces no intermediate events: after a gap, only current state is diffed against last-seen state (a land that came and went entirely unseen produces no notification — by design, per Pillar 1).
• Sockets and the cycle. Each shore socket s has a phase offset φ(s) drawn from evenly-spaced slots (C/N apart) and assigned by seed-shuffle — no two sockets ever in phase; simultaneous all-socket emptiness is impossible when W ≥ C/N — true at locked defaults for N≥2, but NOT structural: tuning W below C/N (possible inside the documented safe range) surrenders this invariant. Config validation warns (AC-42b); review M1, locked 2026-08-26. A socket is Docked iff ((t − φ) mod C) < W, half-open [φ, φ+W). Starting values (tunable, see Tuning Knobs): dock window W = 158,400 s (44 h), gap G = 100,800 s (28 h), cycle C = 259,200 s (72 h). *The spike's literal constants (72,000 / 48,000) were placeholders — never copy them into production.*
• Recurrence: the global deck (Pillar 1's rule). All dockings, across all sockets, in chronological order, deal from a single seed-shuffled deck of the full template pool (seeded Fisher–Yates per (seed, roundIndex)). When the deck is exhausted, it reshuffles for the next round. Guarantees, stated as rules: (a) every land docks exactly once per round — expected wait after a miss ≈ one round length (deckSize·C/N), honest worst case just under two ((2·deckSize−1)·C/N, a land dealt first in round r and last in round r+1 — see F8, corrected per review H2); (b) the same land never docks twice in a row (seam rule: deterministic swap if round N+1's first card equals round N's last); (c) two copies of the same land are never docked simultaneously (within-round uniqueness + a seam-overlap constraint on the first M cards, M = floor(W·N/C)). Deck-counting is a feature: "if the tin highlands just left, it's not next" is exactly the literacy the Player Fantasy promises.
• Return state. A returning land keeps its identity — silhouette, landmarks, and biome read as "the land we know" — with resources fully regrown (harvest diffs for departed dockings are dropped by contract) and light variation seeded by (seed, socket, cycleIndex): node placement, enemy camp positions, minor dressing shift. Variation never alters the recognizable shape.
• Purity of selection. Which land docks is a function of (seed, t, config) and nothing else — never base prosperity, never player state. "Prosperity attracts worse tides" is implemented downstream: enemy strength/count scale at land instantiation (owned by Land Dock/Undock + Enemy AI). The scheduler has no interface to Enemy AI at all — a deliberate non-dependency.
• Arrival. For PreloadLeadTime (default 600 s — see Tuning Knobs) before φ, the land is visible offshore drifting toward the socket — cosmetic only: no collision, not enterable, purely client-side presentation layered on the Addressables preload window. Gameplay existence begins exactly at φ.
• Departure. At φ+W the land soft-closes: all interaction ends, harvest diffs are final, and any player standing on it is deposited at that socket's authored shoreline depositPoint (a fixed point per socket, authored with the socket layout — LDU quick-spec Rule 8; Base Building AC-63b validates it stays inside the socket's no-build radius so walls can never strand a deposited player; pinned 2026-08-27, BB re-review CS-2 — was "nearest home shoreline", a runtime nearest-point with no data artifact to validate against) — carried inventory untouched, no damage, no death risk; presentation is tone-safe ("the tide carries you home", never "YOU MISSED IT"). Hard unload follows after a technical EvictionGrace (~15–30 s) once players are confirmed clear. **Harvesting is legal until the exact undock instant** — the last-tick harvest is intended behavior, not a bug, and no grace period, partial credit, or compensation exists in any form.
• Single source of temporal truth. No system other than the Tide Scheduler ever stores or recomputes φ, C, W, or schedule state. Consumers receive derived pure values only (booleans, floats, IDs). The render/UI layers never receive raw t — making a numeric countdown impossible at the interface level, not just by convention.

States and Transitions

Mechanical states per socket — exactly two; presentation states are derived labels:

Presentation sub-states (render-only, derived from progress p = (t−φ)/W; curve ownership: art bible §4.3):

Transitions fire host-side via NextBoundary(seed, t) (compute the next transition instant, schedule one wake-up — no polling); ±5 s event tolerance is acceptable; suspend/wake recovers by fresh evaluation.

Interactions with Other Systems

Implementation notes flagged → ADR (not GDD scope): TideConfig as an explicit function parameter sourced from data (enables save-compat versioning of tuning changes); NGO time-replication mechanics; stable template ID space (never hash % poolSize).

Formulas

All schedule math uses System.Math with long (integer UTC seconds) and double (intensities only). Banned in schedule math: System.Random, GetHashCode(), UnityEngine.Mathf, float, transcendental functions. FloorDiv/FloorMod are explicit floor-division (C#'s % truncates toward zero and is wrong for negative operands). Any change to the hash algorithm or its constants is a save-breaking change and must be versioned.

F0. StableHash64 — canonical hash (foundation for all others)

StableHash64(seed, parts...) = SplitMix64Combine(seed, parts)

Pinned to the spike's exact algorithm (prototypes/tide-scheduler-spike-2026-08-25/Program.cs):

h = seed XOR 0x9E3779B97F4A7C15
for each part p in parts (order-significant):
    h = h XOR (ulong(p) + 0x9E3779B97F4A7C15 + (h << 6) + (h >> 2))
    h = h * 0xBF58476D1CE4E5B9
    h = h XOR (h >> 31)
return h

Variables:

Output Range: full ulong, uniform. Callers never pass empty parts (would degenerate to seed XOR constant and let two call sites collide). Example: StableHash64(123456789, [2, 5]) → a fixed 64-bit value, identical on every platform, session, and runtime.

Salt constants (review L1, locked 2026-08-26): the string salts written in F1/F4/F5 are notational aliases for fixed long constants passed as ordinary parts: SALT_SOCKET_OFFSET = 1, SALT_DECK = 2, SALT_RESEAM = 3, SALT_SEAM_OVERLAP = 4, SALT_VARIATION = 5. Salts are never derived from strings at runtime — string encoding is unspecified across runtimes and any change would be save-breaking.

F1. socketPhaseOffset

φ(s) = slotOf(seed, s, N) · (C / N)

slots    = [0 .. N-1]
shuffled = SeededFisherYates(slots, StableHash64(seed, ["socket_offset_assignment"]))
φ(s)     = shuffled[s] * (C / N)

Variables:

Output Range: [0, C); all offsets distinct (permutation), so no two sockets are ever in phase and simultaneous dock-starts are structurally impossible. Example (Tier 1, N=4): C/N = 64,800. If shuffled = [2,0,3,1]: φ = [129,600, 0, 194,400, 64,800]. MVP (N=1): trivially φ = 0. Constraint: N must divide C evenly — 259,200 = 2⁷·3⁴·5² divides cleanly by 1–6 and 8, never use N=7 without re-tuning C.

F2. dockedState, cycleIndex, progress

dockedState(seed, s, t, config) = FloorMod(t − φ(s), C) < W cycleIndex(s, t, config) = FloorDiv(t − φ(s), C) progress(s, t, config) = FloorMod(t − φ(s), C) / W — defined only while docked

Variables:

Output Range: dockedState clean boolean; cycleIndex monotonically non-decreasing (monotonic clamp guarantees this). API rule: return (bool docked, double progress) as a pair so no consumer reads progress for an Absent socket. Example: φ=0, t=600,000: 600,000 mod 259,200 = 81,600 < 158,400 → docked, cycleIndex = 2, progress = 81,600/158,400 ≈ 0.515.

F3. Global docking sequence — dockingIndex

dockingIndex(s, cycleIndex_s) = cycleIndex_s · N + slotOf(seed, s, N)

Because offsets are exact multiples of C/N, dock-starts occur globally at every multiple of slotWidth = C/N — one docking every C/N seconds, forever, ties structurally impossible. Inverse direction:

globalSlot(t)        = FloorDiv(t, slotWidth)
socketForSlot(g)     = inverse(shuffled)[FloorMod(g, N)]
cycleIndexForSlot(g) = FloorDiv(g, N)
dockingIndex         = globalSlot

Variables:

Output Range: one integer per C/N-second interval, unbounded (long). Defensive tiebreak (unreachable by construction, stated for future config changes): if two dock-starts ever coincide, lower socket index wins. Example (N=4, shuffled=[2,0,3,1]): global order = socket 1, 3, 0, 2, repeating each cycle. dockingIndex 0 → socket 1 cycle 0; dockingIndex 4 → socket 1 cycle 1.

F4. templateForDocking — the global deck

templateForDocking(dockingIndex) = deck_r[FloorMod(dockingIndex, deckSize)] where r = FloorDiv(dockingIndex, deckSize) and deck_r = ApplySeamRules(SeededFisherYates(pool, StableHash64(seed, [r, "deck"])), r)

Seeded Fisher–Yates — RNG pinned per review L2 (locked 2026-08-26): each draw is an independent hash, `j = FloorMod(StableHash64(seed, [SALT_DECK, r, i]), i + 1). The negligible modulo bias at deckSize ≤ 8` is explicitly accepted. Never System.Random, never a stateful stream:

deck = copy(pool)
for i from deckSize-1 down to 1:
    j = FloorMod(StableHash64(seed, [SALT_DECK, r, i]), i + 1)   // inclusive
    swap(deck[i], deck[j])

Negative rounds (review B1): r and dockingIndex may be negative during the first C after world-gen; all deck math uses FloorDiv/FloorMod and is defined for negative inputs. Seam rules apply identically across the r = −1 → 0 boundary (AC-28b).

Seam rule (a) — no consecutive repeat:

if deck_{r+1}[0] == deck_r[deckSize-1]:
    swapIndex = 1 + (StableHash64(seed, [r+1, "reseam"]) mod (deckSize-1))
    swap(deck_{r+1}[0], deck_{r+1}[swapIndex])

Seam rule (b) — no simultaneous duplicates across the round seam, over the overlap window M = FloorDiv(W·N, C) (max concurrently-live dockings drawn from adjacent rounds). Deterministic and order-independent:

tail = last M cards of deck_r ; head = first M cards of deck_{r+1}
for each conflict (tail[i] == head[j]) in canonical order (j asc, then i asc):
    if still conflicting:
        candidates  = indices k ≥ M where deck_{r+1}[k] ∉ tail
        chosenIndex = candidates[StableHash64(seed, [r+1, "seamoverlap", j]) mod |candidates|]
        swap(deck_{r+1}[j], deck_{r+1}[chosenIndex])

Swap targets come from outside the overlap window, so resolving one conflict can never create another within this seam — the pass terminates without retry loops. Precision (review H3, locked 2026-08-26): candidates is recomputed at each iteration against the current mutated deck_{r+1} — a card is never swapped into position twice. Non-emptiness is guaranteed, not assumed: at most M cards of deck_{r+1} positions k ≥ M can appear in tail, so |candidates| ≥ deckSize − 2M ≥ 1 by the strict deckSize > 2M guard (AC-14b asserts this at every iteration). A swap may place the moved card in round r+1's own tail window — that is legal; the next seam's pass handles it under the same guarantee.

Variables:

Output Range: always a valid pool member; every template exactly once per round; never the same land twice in a row; never two copies simultaneously docked. Example (Tier 1): M = FloorDiv(158,400·4, 259,200) = 2 — the last 2 cards of round r and first 2 of round r+1 must be disjoint. At MVP M = 0: the check degenerates safely, no special case needed. Guard: deckSize > 2M must hold or seam resolution could run out of candidates; true for all locked configs, stated in Tuning Knobs.

F5. variationSeed

variationSeed(seed, s, cycleIndex) = StableHash64(seed, [s, cycleIndex, "variation"])

Variables:

Output Range: full ulong, uniform. Distinctly salted from template selection — changing variation logic can never perturb which template docks, and vice versa (stated as a rule, not an accident). The scheduler's contract ends at handing over the seed; layout interpretation is owned downstream. Example: socket 1, cycle 2 → StableHash64(seed, [1, 2, "variation"]).

F6. NextBoundary

NextBoundary(seed, t) = min(nextStart(t), nextEnd(t))

nextStart(t) = (FloorDiv(t, slotWidth) + 1) · slotWidth
nextEnd(t)   = min over sockets s of:
                 e = φ(s) + FloorDiv(t − φ(s), C)·C + W
                 if e ≤ t: e += C

Variables:

Output Range: strictly > t, bounded by t + C (every socket docks and undocks once per cycle). Drives the schedule-one-wake-up evaluation pattern — no polling. PreloadLeadTime never appears here: preload consumers subtract it downstream (NextBoundary(t) − PreloadLeadTime), keeping the Absent|Docked mechanical contract closed. Example: socket 1 (φ=0) docked at t=600,000 → its nextEnd = 676,800; if the global nextStart = 648,000 (next multiple of 64,800), then NextBoundary = 648,000.

F7. Tint ramp inputs — amberIntensity, violetIntensity

Sub-windows of progress p ∈ [0,1) (new tuning knobs; art bible §4.3 owns the color mapping — the scheduler owns only these floats):

arrivalWindowFrac = 0.15 (first ~6.6 h of W) · driftOutWindowFrac = 0.25 (last 11 h of W — raised from 0.20 per review M4 so visible violet 0.4·frac·W = 4.4 h meets the ≥4 h evening-session guarantee)

// Amber: ramps in over first 60% of the arrival window, holds to its end, then neutral
if p < arrivalWindowFrac:
    amberIntensity = Clamp01((p / arrivalWindowFrac) / 0.6)
else: amberIntensity = 0

// Violet: neutral until drift-out begins; ramps 0→1 over the final 40% of the drift-out window
if p ≥ 1 − driftOutWindowFrac:
    localP = (p − (1 − driftOutWindowFrac)) / driftOutWindowFrac
    violetIntensity = Clamp01((localP − 0.6) / 0.4)
else: violetIntensity = 0

Variables:

Output Range: both clamped [0,1]; ~60% of every docking is tint-neutral (the fantasy's "normal sky" majority). Violet peaks exactly at undock. Absent sockets are never evaluated — with exactly one exception (review B2, locked 2026-08-26): **during EvictionGrace the render layer receives violetIntensity = 1.0 held constant with Docked = false** — the only case a non-Docked socket carries tint, so the departure reads continuously through the drift-out instead of cutting to no-signal at the emotional peak. The API surface is unchanged (AC-27 intact); after teardown, no values. Example: p=0.05 → amber Clamp01((0.05/0.15)/0.6) = 0.556, violet 0. p=0.5 → both 0 (steady, the common case). p=0.99 → violet Clamp01(((0.24/0.25)−0.6)/0.4) = 0.9, nearly full; 1.0 at undock, held through EvictionGrace.

F8. Recurrence bounds — the player-facing guarantee

*(Corrected 2026-08-26 per independent review H2: the previous single bound stated the round length as a worst-case guarantee; the honest worst case is just under two rounds. The deck algorithm is unchanged — spike-validated; a tightening seam rule was considered and rejected to avoid new termination proofs. Revisit at Tier 1 if the tail stings — Open Question 5.)*

roundLength = deckSize · (C / N) — time to deal the full deck once recurrenceWorstCase = (2·deckSize − 1) · (C / N) — land dealt first in round r, last in round r+1 recurrenceExpected ≈ roundLength

Variables:

Output Range: both scale as deckSize / N — growing templates and sockets together keeps waits flat-to-improving. Example (MVP, N=1, deckSize=3): roundLength `3 · 259,200 = 777,600 s = 9 days; worst case 5 · 259,200 = 1,296,000 s = 15 days` — the honest player-facing promise: *"a missed land is typically back in about 9 days — never more than 15."* Example (Tier 1, N=4, deckSize=8): roundLength `8 · 64,800 = 518,400 s = 6 days; worst case 15 · 64,800 = 972,000 s = 11.25 days` — Tier 1 has more templates yet recurs faster, because global dockings happen 4× as often.

Edge Cases

Time and clock

• If a player logs in with a saved position on a now-Absent land: placed at that socket's depositPoint before the world renders — identical to Rule 9's deposit; inventory untouched, no loss messaging. *The world doesn't distinguish "departed while you watched" from "departed while you were offline"; identical recovery also closes any logout-timing exploit.*
• If a harvest completes at t = φ+W − 1 (last legal second): succeeds in full. If the completion tick is ≥ φ+W: fails outright — the land no longer exists. Intended behavior, not a bug — the sharp cutoff is the point; never add padding.
• If wall-clock advances ≥ 1 full cycle while nobody plays (suspend, absence, closed app): state is computed fresh at the new t — no backlog replay, no catch-up notifications, no "you missed N lands" summary. A docking that came and went entirely unseen produces **no notification whatsoever**. *The implementation must never iterate elapsed cycles — only evaluate t directly.*
• If the host's clock is set backward: `t = max(lastKnownGoodT, hostUtcNow)` — tide time is a monotonic ratchet that free-runs off the host clock but can only click forward.
• **If a save's lastKnownGoodT is in the future relative to the host clock** (save copied from a faster machine): the future timestamp wins and becomes the new floor; the tide neither waits for real time to catch up nor rolls back. Documented as expected behavior — not a bug to investigate.
• cycleIndex/dockingIndex range: long; 1000 years of continuous play ≈ 121,000 cycles — overflow is a closed question, do not reopen.
• If t < φ(s) (only possible in the first C seconds after world creation): cycleIndex is legitimately negative via floor-division and dockedState/progress remain correct. Constraint: no consumer may assume cycleIndex ≥ 0 (signed key space from day one). *Passes all testing done ≥ 72 h after world-gen, then breaks on a fresh save — test explicitly near t = 0.*

Player-in-world

• **If a player is mid-transition (swimming/loading between home and land) at t = φ+W**: resolved by the host's last-known authoritative position at the soft-close instant — on-land → Rule 9 deposit; already home → no action. Client transition animations are never the authority. **⚑ Flagged for the netcode ADR**: under owner-authoritative movement this reads the host's last received position snapshot — confirm when the ADR is written.
• If clients briefly disagree with the host on docked state (visual lead): host state is authoritative for all gameplay (harvest legality, entry, diffs) without exception; the client's local evaluation drives only tint/cosmetics and reconciles silently on the next host update — no error, no visible correction event. Actions against a state the host rejects fail like any other authority mismatch, with no tide-specific error messaging.
• If the host disconnects mid-session (session ends; host migration is banned): nothing needs finalizing — diffs are written synchronously per-action, never batched, so everything persisted up to the last evaluated t is already final. Next session simply re-evaluates under the monotonic clamp. There is no flush step, deliberately.
• **If EvictionGrace expires with a player still on the soft-closed land** (AFK, alt-tabbed, unresponsive client): server-authoritative force-relocation to that socket's depositPoint (Rule 9) fires immediately at expiry — not deferrable, not dependent on client acknowledgment or animation. *The grace window smooths the common case; the hard teleport is the actual guarantee. It is a technical teardown window, never a gameplay grace period.*
• If a player tries to reach a cosmetic drift-in land before φ (swim, projectile, interaction raycast, camera): no collision, not a valid target for any interaction system, not enterable; camera may view it freely. Gameplay existence begins exactly at φ — no earlier partial availability of any kind.

Configuration changes (rulings locked 2026-08-26)

• If the template pool changes mid-save (update adds/removes a land): the in-flight round completes on the old deck; the new pool takes effect at the next round boundary (TideConfig is versioned). A dealt round never mutates — deck-counting is a feature, and a pool that changes mid-round would break the literacy contract. Harvest diffs are unaffected by construction (keys never reference the pool). recurrenceBound recalculates from the next round and is stated to players as a plain fact.
• If the socket count N changes mid-save (the MVP → Tier 1 upgrade): hard epoch boundary. All offsets φ(s) are recomputed via F1 for the new N (evenly-spaced slots redistributed across all sockets — existing sockets' offsets will change, deliberately); dockingIndex/roundIndex reset to 0 at the epoch (referenced to the config-activation timestamp); **an epochIndex — starting at 0, incremented at every config epoch, never reset — qualifies every diff key `(epochIndex, socket, cycleIndex, nodeId)`, so pre-epoch keys can never collide with post-epoch dockings even if a stale diff somehow survives reconcile** (review M2, locked 2026-08-26; AC-35b); old diffs age out through normal reconcile (their dockings are definitionally no longer live); the recurrence guarantee restarts at the epoch. One honest, visible schedule shift at a content update — never silent drift. *The alternative (preserving old offsets, fitting new sockets into gaps) was rejected: it abandons the evenly-spaced-slot guarantee the global-deck math depends on.*

Degenerate configurations (config-load validation, fail loudly)

• If N = 1 (MVP): M = 0 — the seam-overlap check degenerates to a no-op with no special-case branch. Formal test boundary.
• If deckSize = 1: the anti-repeat seam rule is unsatisfiable and is skipped entirely — same-land-twice is unavoidable and correct. *Implementation landmine: the swap index divides by deckSize − 1 (division by zero if not guarded). Guard and test even though MVP locks ≥ 2 templates.*
• If W = 0 or W ≥ C: invalid config, rejected at load time with a loud error — W = 0 yields a socket that can never dock (silent breakage); W ≥ C yields a permanently docked land (violates Pillar 1's absence requirement). Enforce 0 < W < C.
• If arrivalWindowFrac + driftOutWindowFrac > 1.0: both tint ramps would fire simultaneously with no defined blend. Enforce arrivalWindowFrac + driftOutWindowFrac ≤ 1.0 at config load (locked values sum to 0.40 — wide margin, but the guard must be explicit; was written as 0.35 before the M4 raise of driftOutWindowFrac — corrected 2026-08-27 alongside ADR-0001, matching AC-43 and the Tuning Knobs).

Dependencies

Upstream (this system depends on): none. The Tide Scheduler is Foundation-layer by design — pure, engine-free C# with no gameplay inputs. One soft runtime dependency: the Netcode Session delivers the host's authoritative t to clients (Core Rule 1). The scheduler's math doesn't depend on netcode existing (it runs identically in EditMode tests and a single-player session); only the distribution of t rides the session layer.

Downstream (systems that depend on this one) — hard unless noted; interfaces specified in Interactions:

Bidirectional-consistency obligations: every dependent GDD/quick-spec now exists and lists Tide Scheduler as upstream — verified in the cross-GDD review of 2026-08-27 (status sentence updated same day, W6). Each dependent must consume the interfaces exactly as specified here (in particular: Harvesting must ask for cycleIndex, never recompute it; render/UI must never receive raw t).

Forward references (owned elsewhere, noted here so they aren't lost): whether player-placed structures can exist on drift lands and what departure does to them → Base Building GDD; the host last-known-position snapshot assumption (Edge Case 8) → netcode ADR; TideConfig-as-parameter and config versioning → architecture ADR.

Tuning Knobs

Not tuning knobs (rules, locked by this GDD): the recurrence guarantee (global deck, once per round, no consecutive repeats, no simultaneous duplicates), the monotonic clock, purity of selection, the sharp φ+W cutoff, and the no-compensation ban. Changing any of these is a design change requiring GDD revision + CD review, not a config edit.

Knob-interaction warnings: W and G tune the game's real-life rhythm — retune them against the friend group's actual schedule after the MVP playtest, not in the abstract. Raising N without raising deckSize makes recurrence very fast and repetitive; raising deckSize without N makes missed lands sting — move them together. Two numbers to watch (F8): expected roundLength = deckSize·C/N (target ≈ ≤ 9 days) and recurrenceWorstCase = (2·deckSize−1)·C/N — the honest promise number (≤ ~15 days at MVP). Additionally, keep W ≥ C/N at any N ≥ 2 or the never-all-empty invariant is surrendered (Rule 4, AC-42b). All values live in TideConfig (data-driven, validated at load per Edge Cases 17–18); tuning changes take effect per Edge Case 13's round-boundary rule.

Visual/Audio Requirements

The scheduler's visual contract is fully owned by art bible §4.3 (tide-state palette curves) and the Tide-Tint Render Pipeline: this system only supplies amberIntensity/violetIntensity floats and the Docked boolean. Visual requirements it imposes: the cosmetic drift-in/drift-out presentations (Rules 8–9) must read as the land sailing, never as a loading state — no progress bars, no spinners at the socket; and no numeric countdown may ever exist (enforced at the API surface, AC-27). Audio (per concept, desirable not MVP-blocking): docking and departure stingers — adaptive, tone-safe (arrival = invitation, departure = farewell, never alarm), triggered off the same transition events Land Dock/Undock consumes; ambient beds may shift subtly with tint state. Threat-land arrival gets no special sting beyond the standard docking sting — danger reads on the land itself (crimson), not in the announcement.

📌 *Asset Spec note: stingers and drift-in presentation become concrete asset lines when /asset-spec runs after the GDD set is complete.*

UI Requirements

One HUD element consumes this system: the compass tide-glint (art bible §7) — per-socket glint driven by the derived floats and Docked booleans, warm glint for arriving/docked, cool for departing. Binding constraints on any UI consuming tide data: never a numeric timer (impossible by API), never punitive copy (Player Fantasy tone rules), departure messaging states world facts only. Open UI question routed to the UI/HUD quick-spec: whether the game offers a soft deck-memory aid (e.g., a log of which lands have appeared this round) or leaves deck-counting to player memory and note-taking — the Lineage 2 anchor leans toward not handing it over, preserving "you learned this."

📌 UX Flag — Tide Scheduler: this system contributes to the compass/HUD. In Pre-Production, run /ux-design for the HUD before writing epics; stories should cite design/ux/hud.md, not this GDD.

Acceptance Criteria

[UNIT] = EditMode NUnit over the pure functions (no engine dependency — this is the project's first mandatory unit-test suite). [INTEGRATION] = NGO session / Unity runtime. [MANUAL] = human judgment. All criteria use locked TideConfig defaults unless the vector specifies otherwise.

Determinism & Purity

• AC-1 [UNIT] GIVEN fixed vector seed=123456789, parts=[2,5], WHEN StableHash64 is evaluated, THEN the result equals the hardcoded expected ulong, byte-for-byte, on every platform.
• AC-1b [UNIT] GIVEN StableHash64(seed,[1,2]) and StableHash64(seed,[2,1]), WHEN compared, THEN results differ (order-significance); GIVEN empty parts, THEN the call is rejected by guard, never silently degraded.
• AC-2 [UNIT] GIVEN a table of ≥20 hardcoded (seed, t, config) → (dockedState, cycleIndex, progress, templateForDocking, amberIntensity, violetIntensity) tuples spanning MVP and Tier 1 configs, WHEN DockedLands is evaluated per row, THEN every field matches exactly (integers exact; doubles within 1e-9) — any change to hash constants, floor math, or ramps fails here first.
• AC-3 [UNIT] GIVEN any valid input, WHEN DockedLands is called 1,000× with identical inputs, THEN output is bit-identical every call (no mutable state).
• AC-4 [UNIT] GIVEN the scheduler call graph, WHEN inspected (static analysis/reflection), THEN no path references System.Random, GetHashCode(), UnityEngine.Mathf, float, DateTime.Now, or transcendental functions.
• AC-5 [UNIT] GIVEN negative operands (e.g., FloorMod(−5, 3)), WHEN evaluated, THEN true floor semantics hold (= 1, never C#'s truncating −2).

Schedule Correctness

• AC-6 [UNIT] GIVEN N=4 and a fixed seed, WHEN F1 computes all offsets, THEN they form a permutation of {0, C/4, 2C/4, 3C/4} — all distinct, all exact multiples.
• AC-7 [UNIT] GIVEN N≥2, WHEN dockedState is swept across a full cycle, THEN at every instant at least one socket is Docked.
• AC-8 [UNIT] GIVEN φ=0, t=600,000, WHEN F2 is evaluated, THEN docked=true, cycleIndex=2, progress≈0.515 (GDD worked example).
• AC-9 [UNIT] GIVEN an Absent socket, WHEN the API is queried, THEN progress is unreadable without first checking docked (type-level guard on the returned pair).
• AC-10 [UNIT] GIVEN N=4, shuffled=[2,0,3,1], WHEN F3 maps slots to sockets, THEN the global order is socket 1, 3, 0, 2 repeating (dockingIndex 0 → socket 1 cycle 0; 4 → socket 1 cycle 1).
• AC-11 [UNIT] GIVEN a full simulated year at any N≥2, WHEN dock-start instants are enumerated, THEN no two ever coincide.

Deck & Recurrence

• AC-12 [UNIT] GIVEN any round r, WHEN F4 deals the full round, THEN every pool template appears exactly once.
• AC-13 [UNIT] GIVEN ≥50 consecutive round seams, WHEN seam rule (a) applies, THEN deck_{r+1}[0] ≠ deck_r[last] always.
• AC-14 [UNIT] GIVEN Tier 1 config (M=2), WHEN seam rule (b) applies across ≥50 seams, THEN the last M of round r and first M of round r+1 are always disjoint.
• AC-14b [UNIT] GIVEN any valid config, WHEN seam rule (b) runs at any seam, THEN |candidates| ≥ 1 at every iteration — asserted, not assumed (H3 non-emptiness proof).
• AC-15 [UNIT] GIVEN MVP config (M=0), WHEN seam rule (b) evaluates, THEN it is a clean no-op — no throw, no special branch.
• AC-16 [UNIT] GIVEN the same (seed, socket, cycleIndex), WHEN variationSeed is queried twice, THEN results are identical; GIVEN two different cycleIndexes, THEN seeds differ.
• AC-17 [UNIT] GIVEN MVP config, WHEN F8 computes the bounds, THEN roundLength = 777,600 s (9 days) and recurrenceWorstCase = 1,296,000 s (15 days) exactly.
• AC-18 [UNIT] GIVEN Tier 1 config, WHEN F8 computes the bounds, THEN roundLength = 518,400 s (6 days) and recurrenceWorstCase = 972,000 s (11.25 days) exactly.
• AC-19 [UNIT] GIVEN any specific template, WHEN dockings are tracked, THEN it docks at least once within recurrenceWorstCase of any prior appearance.
• AC-19b [UNIT] GIVEN ≥50 consecutive rounds, WHEN the maximum observed gap between consecutive appearances of any single template is measured, THEN it is ≤ recurrenceWorstCase (empirical check of the corrected bound).
• AC-20 [UNIT] GIVEN deckSize=1 (Edge Case 16), WHEN seam rule (a) evaluates, THEN the check is skipped — no division by zero, no exception; consecutive same-land docking is permitted.

Boundaries & Eviction

• AC-21 [UNIT] GIVEN t within PreloadLeadTime before φ, WHEN arrival state is queried, THEN the land is cosmetic-only (no collision, not enterable, not targetable) and Docked=false until exactly φ.
• AC-22 [UNIT] GIVEN harvest completions at t=φ+W−1 vs t=φ+W, WHEN legality is checked, THEN the first succeeds in full and the second fails outright — no grace tick in either direction.
• AC-22b [UNIT] GIVEN a multi-tick harvest initiated at t < φ+W and completing at t ≥ φ+W, WHEN legality is evaluated at the completion tick, THEN it fails — initiation-time legality is never cached (H1).
• AC-23 [INTEGRATION] GIVEN a player on a land at soft-close, WHEN the transition fires, THEN they are deposited at that socket's authored depositPoint (Rule 9) — inventory unchanged, zero damage, no death-risk state.
• AC-24 [INTEGRATION] GIVEN EvictionGrace expired with a player still present (simulated unresponsive client), WHEN expiry fires, THEN server-authoritative relocation happens immediately, independent of client acknowledgment.
• AC-25 [UNIT] GIVEN any t, WHEN NextBoundary is evaluated, THEN the result is strictly > t and ≤ t + C (worked example: min(648,000, 676,800) = 648,000).
• AC-26 [UNIT] GIVEN a full cycle swept at 1 s resolution using only NextBoundary-scheduled wake-ups, WHEN transitions are enumerated, THEN every Absent↔Docked transition is captured by exactly one wake-up — none missed, none duplicated.
• AC-27 [UNIT] GIVEN the UI/render-facing API surface, WHEN inspected, THEN no signature exposes raw t/φ/C/W — a numeric countdown is unbuildable from the exposed surface.

Persistence

• AC-28 [UNIT] GIVEN a fresh save with t < φ(s), WHEN F2 runs, THEN cycleIndex is negative via floor division and all outputs remain correct — tested explicitly at t=0 and just after world-gen.
• AC-28b [UNIT] GIVEN t = 0 with φ(s) > 0 and N ≥ 2, WHEN templateForDocking is evaluated, THEN a valid pool member is returned and round r = −1's seam rules against r = 0 hold (B1 — negative round space).
• AC-29 [UNIT] GIVEN a diff written while its land is live, WHEN the save round-trips without departure, THEN the diff survives and reconciles as valid.
• AC-30 [UNIT] GIVEN a diff whose docking has ended, WHEN reconcile-on-load runs, THEN the diff is dropped — resources fully regrown at next appearance.
• AC-31 [UNIT] GIVEN a stale diff at cycleIndex=K and a recurrence at K' > K, WHEN the land re-docks, THEN the stale diff never matches the new docking (spike tests 5–7, promoted to production gates).
• AC-32 [UNIT] GIVEN lastKnownGoodT greater than host UTC (Edge Case 5), WHEN the save loads, THEN t = lastKnownGoodT — future value wins, no rollback, no waiting.
• AC-33 [UNIT] GIVEN ≥1 full elapsed cycle since last evaluation, WHEN re-evaluated, THEN a single direct evaluation occurs (zero iteration over elapsed cycles) and zero missed-land notifications are generated.
• AC-34 [UNIT] GIVEN a mid-save pool change (Edge Case 13), WHEN queried before the round boundary, THEN the old deck still deals; after the boundary, the new pool applies and recurrenceBound recalculates.
• AC-35 [UNIT] GIVEN a mid-save socket-count change (Edge Case 14), WHEN the epoch crosses, THEN all offsets recompute for the new N, sequence indices reset to the epoch timestamp, and pre-epoch diffs age out via the reconcile predicate — no crash, no resurrection.
• AC-35b [UNIT] GIVEN a pre-epoch diff at (epoch 0, socket 1, cycle 40) and a post-epoch docking that computes to (socket 1, cycle 40), WHEN reconcile runs, THEN the pre-epoch diff never matches — the epochIndex qualifier makes key collision impossible (M2).

Config Validation (load-time, fail loudly)

• AC-36 [UNIT] N=1 → load succeeds, M=0 no-op path taken.
• AC-37 [UNIT] N=7 with C=259,200 → load rejected with explicit error (does not divide evenly).
• AC-38 [UNIT] deckSize ≤ 2M → load rejected (seam resolution could exhaust candidates) — never reaches runtime.
• AC-39 [UNIT] W=0 → load rejected (socket could never dock).
• AC-40 [UNIT] W ≥ C → load rejected (permanently docked land violates Pillar 1).
• AC-41 [UNIT] 0 < W < C → load succeeds (positive boundary check).
• AC-42 [UNIT] arrivalWindowFrac + driftOutWindowFrac > 1.0 → load rejected.
• AC-42b [UNIT] N ≥ 2 with W < C/N → load emits a documented loud warning (the never-all-empty invariant is explicitly surrendered, not silently lost — M1).
• AC-43 [UNIT] locked defaults (sum 0.40) → load succeeds.

Performance (AC-44/45 hard gates — TD ruling 2026-08-27, ADR-0001; AC-46 advisory)

• AC-44 [UNIT] GIVEN ≥10,000 warmed calls at N≤8, WHEN DockedLands + NextBoundary are profiled, THEN average ≤ 50 µs per combined call, worst case ≤ 200 µs.
• AC-45 [UNIT] GIVEN the hot-path functions, WHEN measured via GC.GetAllocatedBytesForCurrentThread() across ≥10,000 warmed calls, THEN allocation per call is exactly 0 bytes (no boxing, LINQ, or capturing closures).
• AC-46 [INTEGRATION] GIVEN a session spanning a full docking transition, WHEN frame time is profiled, THEN the scheduler contributes ≤ 0.1 ms to any single frame and never appears as a named steady-state cost center.

Multiplayer Consistency

• AC-47 [INTEGRATION] GIVEN host and client evaluating with the same replicated t, WHEN outputs are compared, THEN dockedState, cycleIndex, and templateForDocking are bit-identical.
• AC-48 [INTEGRATION] GIVEN a transient client/host disagreement near a boundary (Edge Case 9), WHEN the next authoritative update arrives, THEN the client reconciles silently — no dialog, no visible correction; rejected actions fail through the generic authority-mismatch path.
• AC-49 [UNIT] GIVEN different locale/culture/thread environments, WHEN DockedLands runs on identical inputs, THEN output is identical (no CultureInfo/parsing/thread-affinity sensitivity).
• AC-50 [INTEGRATION] GIVEN a client joining mid-cycle, WHEN it receives the host's t for the first time, THEN its first local evaluation matches the host's state immediately — no transient desync window.
• AC-50b [INTEGRATION] GIVEN a client extrapolating visual t between host updates (Rule 1), WHEN measured, THEN its extrapolated t never exceeds the host's t by more than one replication interval plus tolerance, and drives presentation only (M3).

Minimum smoke set (run first)

• AC-2 — fixed-vector determinism: if this fails, nothing downstream is trustworthy.
• AC-8 — canonical F2 worked example.
• AC-13 + AC-14 — seam rules: the mechanical expression of Pillar 1's recurrence promise.
• AC-22 — the sharp cutoff: the most likely target of a well-meaning wrong "fix."
• AC-30 + AC-31 — stale diffs cannot resurrect: the highest-blast-radius failure class (save-durable).

All five are [UNIT], run in seconds, no engine boot — a true pre-commit smoke gate.

Deliberately not criteria (and why)

• "Tint reads as weather, not a progress bar" — perception judgment; becomes a [MANUAL] visual-evidence item (screenshot + lead sign-off) once the render system exists.
• "9 days feels fair" — a playtest question; W/G retuning is explicitly deferred to the MVP friend-group playtest.
• Edge Case 8's mid-transition rule — would test an assumption, not a contract; add the AC when the netcode ADR fixes the position-snapshot interface.

Open Questions