From 0926b55eafbb0d1b5d357c476f39ba59f5a3efac Mon Sep 17 00:00:00 2001
From: Erik <erik.nihlen@gmail.com>
Date: Sun, 30 Aug 2026 09:36:51 +0200
Subject: [PATCH] feat(render) Campaign FW1: the walk event vocabulary

WalkEvent mirrors the FW0 oracle-trace vocabulary one-to-one (Landscape,
Building, DrawInside, DrawCells) as the conformance surface RetailFrameWalk
emits; the FW2 ordered draw stream layers on later without changing it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/AcDream.App/Rendering/Walk/WalkEvents.cs | 58 ++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 src/AcDream.App/Rendering/Walk/WalkEvents.cs

diff --git a/src/AcDream.App/Rendering/Walk/WalkEvents.cs b/src/AcDream.App/Rendering/Walk/WalkEvents.cs
new file mode 100644
index 00000000..b3aa43c0
--- /dev/null
+++ b/src/AcDream.App/Rendering/Walk/WalkEvents.cs
@@ -0,0 +1,58 @@
+namespace AcDream.App.Rendering.Walk;
+
+/// <summary>
+/// Campaign FW1 — the frame walk's observable event stream. These events
+/// mirror the FW0 oracle-trace vocabulary one-to-one
+/// (docs/research/2026-08-30-fw-walk-oracle/README.md): the conformance
+/// contract is that <c>RetailFrameWalk</c>, fed the same world state and
+/// camera pose as a capture, emits the identical sequence. Richer draw
+/// commands (mesh/state/stage tuples for the FW2 ordered stream) layer on
+/// later; this vocabulary stays the conformance surface.
+/// </summary>
+public enum WalkEventKind
+{
+    /// <summary><c>LScape::draw</c> @0x00506330 ran (outdoor root, or drawn
+    /// through an interior frame's exit views).</summary>
+    Landscape,
+
+    /// <summary><c>RenderDeviceD3D::DrawBuilding</c> @0x0059f2a0 entered for
+    /// one building (identified by its position cell id).</summary>
+    Building,
+
+    /// <summary><c>PView::DrawInside</c> @0x005a5860 entered — the frame is
+    /// rooted at this interior cell.</summary>
+    DrawInside,
+
+    /// <summary><c>PView::DrawCells</c> @0x005a4840 entered with the flood's
+    /// cell list (far-to-near iteration happens inside; the event carries the
+    /// list in storage order, matching the oracle dump).</summary>
+    DrawCells,
+}
+
+public readonly record struct WalkEvent(
+    WalkEventKind Kind,
+    uint CellId,
+    int OutsideViewCount,
+    IReadOnlyList<uint> Cells)
+{
+    public static WalkEvent Landscape()
+        => new(WalkEventKind.Landscape, 0, 0, Array.Empty<uint>());
+
+    public static WalkEvent Building(uint positionCellId)
+        => new(WalkEventKind.Building, positionCellId, 0, Array.Empty<uint>());
+
+    public static WalkEvent DrawInside(uint cellId)
+        => new(WalkEventKind.DrawInside, cellId, 0, Array.Empty<uint>());
+
+    public static WalkEvent DrawCells(int outsideViewCount, IReadOnlyList<uint> cells)
+        => new(WalkEventKind.DrawCells, 0, outsideViewCount, cells);
+}
+
+/// <summary>
+/// The sink a walk emits into. FW1 conformance tests collect events; FW2's
+/// production sink will additionally receive the ordered draw stream.
+/// </summary>
+public interface IWalkEventSink
+{
+    void Emit(in WalkEvent walkEvent);
+}