ADR-0001: Tide Scheduler as a Pure Engine-Free Assembly

Status

Accepted

Accepted 2026-08-28 — architecture-review-2026-08-28.md (verdict CONCERNS; review amendments applied before acceptance).

Date

2026-08-27

Engine Compatibility

ADR Dependencies

Context

Problem Statement

Driftlands has no server. The world's past, present and future are DockedLands(seed, t, config) — a pure function every machine evaluates identically (tide GDD Core Rule 3, concept Pillar 1). If that function ever reads engine time, a random source, a float, or any mutable field, the host and a client can disagree on whether a land is docked, harvest diffs can key against the wrong cycle, and the "nothing happens while nobody plays" promise breaks silently. The tide GDD makes purity a rule (AC-3, AC-4, AC-49) and the spike proved the math; this ADR decides how the Unity project makes that purity a compile-time fact rather than a discipline, and where the one impure input — wall-clock UTC — enters.

Constraints

• Tide GDD Formulas: System.Math, long UTC seconds, double intensities only; banned: System.Random, GetHashCode(), UnityEngine.Mathf, float, transcendental functions, DateTime.Now inside schedule math (AC-4). Hash algorithm and salt constants are save-breaking if changed (F0). Locked tint fractions sum to 0.40 (0.15 + 0.25, AC-43 / Tuning Knobs — the GDD's Edge Case 18 still says 0.35, a stale figure from before the M4 raise; corrected in the GDD alongside this ADR).
• Tide GDD AC-27: no signature on the UI/render-facing surface may expose raw t, φ, C, W.
• Tide GDD AC-44/45 (hard gates, TD ruling 2026-08-27): ≤ 50 µs average per combined DockedLands + NextBoundary call at N ≤ 8, 0 bytes allocated per call; AC-46 (advisory): ≤ 0.1 ms per frame.
• Technical preferences: 80 % coverage on pure-logic systems, tide scheduler is "the first mandatory unit-test target"; [SerializeField] fields-only (6.3).
• Forbidden Patterns: no offline simulation — the implementation must never iterate elapsed cycles (tide EC3, AC-33).
• Architecture principle 3 (Rules are engine-free) and the approved assembly layout (Driftlands.Tide has no Unity references).

Requirements

• Must implement tide F0–F8 exactly as specified (StableHash64 splitmix, F1 offsets, F2 docked/cycle/progress, F3 dockingIndex, F4 global deck + seam rules, F5 variationSeed, F6 NextBoundary, F7 tint floats, F8 recurrence bounds).
• Must expose the ITideClock boundary from the architecture document unchanged.
• Must be evaluable in EditMode NUnit with no scene, no NetworkManager, no MonoBehaviour.
• Must accept TideConfig as an explicit parameter (data-driven, versioned, load-validated per tide EC 15–18).
• Must provide t to clients from the host only; client-local evaluation is presentation-only (tide Rule 1, EC9, AC-50b).
• Must persist and restore lastKnownGoodT through Save (tide Rule 2, AC-32).

Decision

Alternative A: a dedicated Driftlands.Tide assembly with noEngineReferences: true, consumed through ITideClock; a thin TideClockAdapter in Driftlands.Runtime owns the only impure input (host UTC) and its replication.

• Assembly Assets/Driftlands/Tide/Driftlands.Tide.asmdef — "noEngineReferences": true, "references": [], "autoReferenced": false. Because the asmdef excludes UnityEngine, any Mathf/Time/Random reference is a compile error, not a code-review catch. Who references it (Driftlands.Rules, Driftlands.Runtime, Driftlands.Tests.EditMode) is ADR-0003's decision; this ADR only fixes the node. Note that noEngineReferences is a property of the referenced assembly and does not propagate: the EditMode test asmdef is an ordinary engine-referencing test assembly (NUnit + UnityEngine.TestRunner) that references Driftlands.Tide.
• Namespace layout inside the assembly:
• Driftlands.Tide.Math — StableHash64, FloorDiv, FloorMod, SeededFisherYates (static, pure, long/ulong/double only).
• Driftlands.Tide.Config — TideConfig record (W, G, C = W + G, N, PreloadLeadTime, EvictionGrace, ArrivalWindowFrac, DriftOutWindowFrac, Pool: TemplateId[], ConfigVersion) + TideConfigValidator (EC 15–18 → ValidationResult with named errors/warnings; AC-36..43).
• Driftlands.Tide.Schedule — TideSchedule (the pure evaluator: F1–F8) taking (seed, TideConfig) at construction and t per call. It precomputes the per-socket offsets and the current round's deck lazily; both are cached by key ((seed, config) for offsets, roundIndex for a deck) so repeated evaluation allocates nothing (AC-45) while remaining a pure function of its inputs (AC-3: same inputs → same outputs; the cache is an implementation detail invisible to callers).
• Driftlands.Tide.Clock — TideClock : ITideClock wrapping a TideSchedule plus the monotonic guard: Advance(hostUtcNow) sets t = max(lastKnownGoodT, hostUtcNow) and fires edge events by comparing the previous and current evaluation; Restore(TideState); State for Save. NextBoundary() drives the wake-up.
• Epoch state is an input, not a derivation (TD-ADR C2). Tide EC14 defines epochIndex as a counter "incremented at every config epoch, never reset" and rebases dockingIndex/roundIndex to the config-activation timestamp; neither is computable from (seed, config, t). They travel in TideState { LastKnownGoodT, EpochIndex, EpochActivationT }, persisted by Save (ADR-0004), restored into the clock, and passed to TideSchedule as pure inputs. TideClock.AdvanceEpoch(newConfig, activationT) is the only writer (called by GameData/Save on a config epoch — N change), and the schedule stays a pure function of (seed, config, state, t). architecture.md's "derives epoch/cycle purely (nothing stored)" is true only in this sense: the cycle is derived, the epoch is restored.
• Cache invariants: the keyed caches are instance-scoped, never static (a disabled domain reload would otherwise carry stale state across Play Mode sessions), evicted when roundIndex advances (at most two rounds resident — current and the seam neighbour), and the clock is main-thread only (AC-49's thread-affinity clause).
• The only impure input is a long hostUtcNow passed into Advance. Nothing in the assembly reads a clock. The TideClockAdapter (Driftlands.Runtime, a NetworkBehaviour) samples DateTimeOffset.UtcNow.ToUnixTimeSeconds() on the host, calls Advance, and replicates t as a host-written NetworkVariable<long> ⚠️; clients construct their own TideClock from the replicated (seed, config, t) and call Advance(lastReceivedT + monotonicLocalElapsed) for presentation only — their TideClock instance is tagged Presentation and its events are never wired to gameplay (tide Rule 1, EC9). Wire details (write permission API, send cadence, join-time delivery) belong to ADR-0008.
• Events (DockStarted, SoftClose, PreloadDue) are plain C# events raised from Advance on the host clock only. Advance has exactly one caller (amended 2026-08-28 — architecture review C1, exercising the ADR-0008 override clause early): HostTickOrchestrator step 1, once per NetworkTickSystem.Tick (ADR-0015). Direct call order guarantees SoftClose-first for that tick's drain (ADR-0002), the ±5 s tolerance holds trivially (one tick), and a boundary tick can never call Advance twice — which matters because LandNet spawn/despawn hang off these events (ADR-0005). The Awaitable.WaitForSecondsAsync timer (the 6.3-idiomatic default per current-best-practices.md; never Invoke/coroutines) is retained only for the Presentation-role clock and IPreloadSchedule wake-ups at NextBoundary() / NextBoundary() − PreloadLeadTime (clients have no host tick) and never calls the Authority clock's Advance; it is a hint, not the truth — every wake re-samples UTC, so whether WaitForSecondsAsync honours Time.timeScale (UNVERIFIED) cannot matter. Per-tick Advance is one ≤ 50 µs evaluation, not schedule polling. Suspend/wake recovers by calling Advance with the fresh UTC — a single evaluation, never a replay (AC-33).
• Config source: TideConfig is loaded by GameData (ADR-0006) from assets/data/tide.json and validated before the clock is constructed; the tide assembly never touches files. ConfigVersion participates in Save's version gate (ADR-0004); a version change mid-save follows tide EC 13/14 (round-boundary pool change; hard epoch on N change) — implemented inside TideSchedule as the epochIndex term of the diff key.
• Tests: Driftlands.Tests.EditMode/Tide/ holds tide AC-1..45 and AC-49 as NUnit tests over the pure types. The AC-2 fixed-vector table is a checked-in JSON fixture (≥ 20 rows spanning MVP and Tier 1 configs) generated once from the production implementation with production constants, hand-checked against the GDD's worked examples (AC-8: φ=0, t=600,000 → docked, cycle 2, progress ≈ 0.515; AC-25: min(648,000, 676,800); AC-17/18 recurrence bounds) and then pinned — the spike cannot produce production-constant vectors without modification and is throwaway by its own note. AC-44/45 run as benchmark tests with GC.GetAllocatedBytesForCurrentThread() and a stopwatch, gated hard in CI (Editor profile). AC-46/47/48/50/50b are PlayMode tests against the adapter and belong to ADR-0008's suite.

Architecture Diagram

Driftlands.Tide (asmdef, noEngineReferences)          Driftlands.Runtime
┌───────────────────────────────────────────┐          ┌──────────────────────────────────┐
│ Math: StableHash64 · FloorDiv/Mod · FY    │          │ TideClockAdapter : NetworkBehaviour│
│ Config: TideConfig · TideConfigValidator  │          │  host: UtcNow → clock.Advance(t)  │
│ Schedule: TideSchedule (F1–F8, keyed cache)│◄─────────│        t → NetworkVariable<long> ⚠️│
│ Clock: TideClock : ITideClock             │          │  client: replicated t + local     │
│   Advance(hostUtcNow) · Restore · events   │          │        elapsed → presentation clock│
└───────────────┬───────────────────────────┘          │  timer at NextBoundary()          │
                │ ITideClock (derived values only)      └──────────────────────────────────┘
   ┌────────────┼─────────────┬───────────────┬──────────────┐
   ▼            ▼             ▼               ▼              ▼
 Harvesting   Combat      LandLifecycle   SavePersistence  TideTint / UIHUD
 (CycleIndex, (Evaluate    (PreloadDue,   (LastKnownGoodT, (TintFloats,
  Evaluate)    at resolve)  DockStarted,   Restore)          Evaluate.docked)
                            SoftClose)

Key Interfaces

namespace Driftlands.Tide
{
    public readonly record struct TemplateId(int Value);

    public sealed record TideConfig(
        long W, long G, int N, long PreloadLeadTime, long EvictionGrace,
        double ArrivalWindowFrac, double DriftOutWindowFrac,
        TemplateId[] Pool, int ConfigVersion)   // ConfigVersion is POPULATED FROM manifest.configVersion by the tide reader — one value, one writer (ADR-0006); never authored in tide.json
    { public long C => W + G; }

    public static class TideConfigValidator {          // tide EC 15–18, AC-36..43
        public static ValidationResult Validate(TideConfig c);  // errors: W=0, W>=C, N!C, deckSize<=2M, frac sum>1; warning: N>=2 && W<C/N
    }

    public readonly record struct TideState(long LastKnownGoodT, int EpochIndex, long EpochActivationT);

    public interface ITideClock {
        (bool docked, double progress) Evaluate(int socket);   // progress only meaningful when docked
        long  CycleIndex(int socket);
        int   EpochIndex { get; }
        ulong VariationSeed(int socket, long cycleIndex);
        TemplateId TemplateFor(int socket, long cycleIndex);
        long  NextBoundary();                                   // > t, <= t + C
        (float amber, float violet) TintFloats(int socket);     // (0,1) held during EvictionGrace
        bool  IsDockingLive(int epochIndex, int socket, long cycleIndex);  // the reconcile validity predicate the scheduler OWNS (tide Interactions row / save AC): true iff that epoch-qualified docking is the one currently live at t
        event Action<int, TemplateId> PreloadDue;
        event Action<int> DockStarted;
        event Action<int> SoftClose;
    }

    public sealed class TideClock : ITideClock {
        public TideClock(ulong seed, TideConfig config, TideClockRole role);   // role: Authority | Presentation
        public void Restore(TideState state);                                  // Save → clock: LastKnownGoodT, EpochIndex, EpochActivationT
        public void Advance(long hostUtcNow);                                  // t = max(lastKnownGoodT, hostUtcNow); raises edge events (Authority only); ±5 s tolerance
        public void AdvanceEpoch(TideConfig newConfig, long activationT);      // the only method that INCREMENTS EpochIndex; Restore(TideState) ASSIGNS the persisted value (epoch is an input, not a derivation — §2). Throws unless activationT == t (ADR-0006 §5 TD-ADR C2b, enforced). Caller: GameData/Save on an N change
        public void ApplyPoolChange(in TideConfig newConfig);                  // tide EC13: pool change at the next round boundary. Refuses an N change (→ AdvanceEpoch) and a W/G change (not a pool change). Declared 2026-09-07 (review C6)
        // Reached only through the seams below — TideClock implements both explicitly, so neither is callable off the concrete type:
        //   public interface IEpochAdvancer { long T { get; } void AdvanceEpoch(TideConfig newConfig, long activationT); }   (Driftlands.Tide)
        //   public interface ISaveClock : IEpochAdvancer { TideState State { get; } void Restore(TideState s); void Advance(long hostUtcNow); }
        public TideState State { get; }                                        // clock → Save
        // Never exposes t, φ, C, W (AC-27). Recurrence bounds (F8) via TideSchedule.RecurrenceBounds(config) for tooling only.
    }
}

Invariants callers must respect: never cache Evaluate() across ticks (re-sample at resolution — architecture principle 4); never construct a second Authority clock; Advance is called only by the adapter. Guarantees to callers: identical outputs for identical (seed, config, t) on every platform (AC-1/2/3/49); zero allocation on the hot path after warm-up (AC-45); events fire exactly once per transition (AC-26).

Alternatives Considered

Alternative B: Pure static class inside Driftlands.Runtime

• Description: Same math and interface, but living in the main game assembly; purity enforced by code review and a reflection test (AC-4's static-analysis check).
• Pros: No asmdef setup; one fewer assembly to reference from tests.
• Cons: UnityEngine is in scope — a Mathf.FloorToInt or Time.time compiles fine and passes until AC-4's reflection test catches it (if it does); EditMode tests must reference the whole Runtime assembly, pulling NGO into the test domain; contradicts architecture principle 3 and the spike's explicit instruction.
• Rejection Reason: Turns a compile-time guarantee into a review discipline for the single most determinism-critical code in the project.

Alternative C: External class library (.csproj → DLL in Plugins/)

• Description: Build the scheduler as a standalone .NET library (like the spike), drop the DLL into the Unity project, share it with CI tooling / a future companion site.
• Pros: Strongest isolation; reusable outside Unity; the spike is already this shape.
• Cons: A second build pipeline for a solo part-time developer; Unity's Mono/IL2CPP target profile can differ from the dotnet build (the 0-alloc guarantee must be measured in-editor anyway); debugging through a prebuilt DLL is worse; asmdef gives the same compile-time isolation without leaving Unity.
• Rejection Reason: The isolation benefit is fully captured by noEngineReferences: true; the extra pipeline is YAGNI until a non-Unity consumer exists (revisit if a companion tool is ever scoped).

Consequences

Positive

• Purity is a compile error, not a convention — UnityEngine cannot be referenced from the scheduler.
• The entire tide AC suite (AC-1..45, 49) runs in EditMode in seconds with no scene; it becomes the project's pre-commit smoke gate.
• One impure input (hostUtcNow) at one call site (Advance) — auditable in a single file.
• Consumers program against ITideClock and never see raw time (AC-27 by construction).

Negative

• Two clock instances per client (the host's authority clock, replicated t; the client's presentation clock) — a small duplication that must be kept clearly labelled.
• A keyed cache inside TideSchedule is state; it must be provably invisible to outputs (covered by AC-3's 1,000× identical-call test and a dedicated cache-invalidation test on config/seed change).
• Round-deck computation on a cold cache allocates once per round; the 0-alloc gate applies to warmed calls (as the GDD's AC-45 already says).

Risks

• double results differ between Mono (Editor/host dev build) and an IL2CPP player build — the real cross-machine risk in host-and-play → mitigated by asserting the AC-2 fixture on at least one IL2CPP standalone player build, not two Mono editors; any drift fails AC-2 first.
• IL2CPP stripping of a pure assembly nothing visibly calls → reachable only via ITideClock from Runtime; normal call-graph analysis keeps it, no link.xml expected — verified by the IL2CPP smoke build below.
• 0-alloc measured under dotnet, not Mono/IL2CPP → verification item; AC-45 runs in the Unity EditMode profile and in the CI batch run.
• Presentation clock drives a gameplay decision by mistake → TideClockRole.Presentation clocks throw if a gameplay consumer subscribes to their events (guard), and AC-50b bounds their lead. Amended by ADR-0005 (2026-08-28): TideClock additionally implements the narrow IPreloadSchedule { NextPreloadInstant(socket); NextTemplate(socket) } in both roles — the one Presentation-role surface a non-tint/HUD consumer (LandLifecycle.SchedulePreload, asset loading only) may read by pull; the event guard is unchanged.
• NetworkVariable<long> API differs on NGO 2.x → adapter is ~30 lines; the API name is an ADR-0008 verification item, not a design risk.

GDD Requirements Addressed

Performance Implications

• CPU: ≤ 50 µs per combined evaluation at N ≤ 8 (hard gate); evaluation happens on state change and per-frame only for tint floats (a few multiplies).
• Memory: one TideSchedule per clock (two per client); offsets array (N longs) + one deck array per cached round (deckSize ints); no per-call allocation after warm-up.
• Load Time: negligible — config parse + validation + one deck shuffle.
• Network: one long replicated on change/join (ADR-0008 owns cadence).

Migration Plan

No existing production code. The spike (prototypes/tide-scheduler-spike-2026-08-25/Program.cs) is the reference for algorithms and the AC-2 fixture generator; per its own note it is never refactored into production. Steps: (1) create the asmdef + namespaces, (2) port F0–F8 against the GDD text (not the spike's placeholder constants), (3) generate the AC-2 fixture from the spike with production constants, (4) land the EditMode suite, (5) write the adapter stub with a fake t source; NGO replication lands with ADR-0008.

Validation Criteria

• All tide [UNIT] criteria (AC-1..45, 49) pass in EditMode CI; the AC-2 fixture is byte-identical on a Mono Editor run and on one IL2CPP standalone player build.
• AC-44/45 pass in the Unity Editor profile (not only dotnet); 0-alloc is an Editor-measured claim — one IL2CPP standalone build exercises ITideClock.Evaluate before Alpha (stripping + profile smoke).
• Every Absent↔Docked transition fires within ±5 s of its computed instant over a simulated cycle (AC-26 + the GDD tolerance).
• Cache invariants hold: no static cache in the assembly (reflection test); at most two rounds resident; config/seed change invalidates.
• A deliberate using UnityEngine; in the tide assembly fails to compile.
• A presentation-role clock rejects gameplay subscribers.
• /architecture-review shows TR-tide-001..010 covered by this ADR.

Amendments

• 2026-08-28, ADR-0005 — IPreloadSchedule. TideClock implements the narrow IPreloadSchedule { NextPreloadInstant(socket); NextTemplate(socket) } in both roles — the one Presentation-role surface a non-tint/HUD consumer (LandLifecycle.SchedulePreload, asset loading only) may read by pull. The gameplay-subscriber guard is unchanged (see Risks).
• 2026-08-28, architecture review C1 (via ADR-0015) — single Advance caller. Decision item 4 amended: the Authority clock's Advance is called only by HostTickOrchestrator step 1, once per NetworkTickSystem.Tick; the Awaitable timer serves only Presentation-role / IPreloadSchedule wake-ups. Consequence recorded in ADR-0004 §3 (tide table dirties once per second). Verification added: (5) the orchestrator is the sole Advance call site (reflection test, with ADR-0015's sole-Tick-subscriber test).

Related Decisions

• docs/architecture/architecture.md — Layer Map (Foundation: TideScheduler), Assembly layout, API Boundaries (ITideClock), Required ADRs #1
• Future: ADR-0002 (host commit model), ADR-0004 (save), ADR-0005 (land lifecycle), ADR-0008 (netcode wire — t replication), ADR-0013 (tide tint)
• design/gdd/tide-scheduler.md (Reviewed) · prototypes/tide-scheduler-spike-2026-08-25/SPIKE-NOTE.md

Amendment notes

• 2026-09-03 (foundation-game-data story-009) — IEpochAdvancer. Folded 2026-09-07 (review C6): IEpochAdvancer and ISaveClock are now declared in §Key Interfaces; TideClock exists and implements both explicitly. TideConfig shipped as a readonly struct, not a record (story-003 ruling — equally immutable, no polyfill in Tide), with validation in TideConfigValidator rather than the constructor.
• 2026-09-07 (review C6) — "only writer" corrected. AdvanceEpoch is the only method that increments EpochIndex; Restore(TideState) assigns the persisted value. ApplyPoolChange (tide EC13) is a declared clock method with its own pending-schedule switch, not "implemented inside TideSchedule" as §5 previously implied.
• 2026-09-07 (review #12) — risk registered. Deck chaining (story-002's seam anchor) is O(r − anchor) on a cold cache. Not an EC3 violation (rounds, not elapsed cycles; Advance stays a single evaluation) but unbounded in principle for a far-future resume. Owed: a cold-cache benchmark at t = now + 10 y inside AC-44's 50 µs, or a chain cap.

Amendments — 2026-09-11 (ADR-0008 netcode wire)

• t replication decided: TideClockAdapter holds one NetworkVariable<long> T with NetworkVariableWritePermission.Server (API verified against NGO 2.13.2 source), default update traits — t changes once per second by construction. Only t travels; every derived value is recomputed locally (netcode quick-spec Rule 4 and tide Rule 1 wording aligned). The ADR-0008 override clause on the timer mechanism is exercised as already recorded (2026-08-28: Advance runs from HostTickOrchestrator at 50 Hz).