acdream/tests/AcDream.Core.Tests/Physics/Issue108CellarAscentViewerReplayTests.cs

using System;
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using AcDream.Core.Tests.Conformance;
using DatReaderWriter;
using DatReaderWriter.Options;
using Xunit;
using Xunit.Abstractions;

namespace AcDream.Core.Tests.Physics;

/// <summary>
/// #108-residual vertical exit-walk harness (2026-06-12): the cellar-ascent
/// grass window. Climbing out of the Holtburg corner-building cellar
/// (0xA9B40174 room, floor z≈90 → 0x0175 staircase/lip → 0x0171 main floor at
/// z=94 = outdoor grade), the upstairs exit door is covered with grass until
/// the eye pops above grade. Punch/seal are exonerated (BR-2 experiment +
/// #117); the grass requires the frame to render through the OUTDOOR root —
/// i.e. the VIEWER-CELL resolution demotes to outdoor/null while the eye is
/// still below terrain grade inside the stairwell.
///
/// This harness drives the PRODUCTION viewer-resolution stack headlessly per
/// step of a kinematic ascent (the #118 HouseExitWalkReplayTests pattern,
/// turned vertical):
///   player cell  — CellTransit.FindCellList on the foot-sphere center (the
///                  production controller pick),
///   viewer cell  — the PhysicsCameraCollisionProbe.SweepEye chain mirrored
///                  verbatim (CameraCornerSealReplayTests provenance):
///                  AdjustPosition at the head pivot → ResolveWithTransition
///                  (IsViewer|PathClipped|FreeRotate|PerfectClip, 0.3 m
///                  viewer_sphere) → fallback 1 AdjustPosition at the sought
///                  eye → fallback 2 (player_pos, cell 0).
/// Each step records WHICH branch produced the viewer cell, so a demote
/// self-attributes:
///   A. sweep Ok=false → fallback chain (AdjustPosition's SeenOutside
///      fall-through is an XY-only grid snap — no Z test — so an in-dirt
///      below-grade eye can return an OUTDOOR cell with found=true);
///   B. sweep end-cell pick demotes (exterior-portal straddle + containment
///      miss at the stopped eye);
///   C. the start-cell AdjustPosition at the pivot demotes;
///   D. all healthy here → the bug is upstream (App camera damping /
///      GameWindow TryGetCell consumption).
///
/// Ascent path: fitted from the live captures (cellar-up-capture*.jsonl band
/// centroids, analyze_108_stairline.py): stairs at x≈153.9 ascending +Y,
/// z = 90.0 (y≤5.7) → 0.836·(y−5.73)+90.25 (stairs) → lip 93.25→94 over
/// y 9.3→10.4 → main floor 94.0. The boom (retail defaults: distance 2.61,
/// pitch 0.291, pivot feet+1.5) trails SOUTH into the stairwell — mid-stairs
/// the desired eye sits beyond the cellar's south wall (y≈4.87) and above its
/// ceiling: in no-cell dirt below grade. Stub terrain (−1000) — the membership
/// pick never reads terrain height (XY-column only), which is exactly the
/// mechanism under test.
///
/// ── RESULT (2026-06-12): the MEMBERSHIP/VIEWER LAYER IS EXONERATED ──────
/// 0 grass-window steps, 0 sweep failures, 0 fallback branches across boom
/// distance {2.61, 5.0} × damping lag {0, 0.3 m}. The viewer resolves
/// 0x0174 → 0x0175 (eye z 93.65, below grade) → 0x0171 at eye z 94.01 —
/// the viewer enters the main-floor room EXACTLY as the head pops above
/// grade (the stairwell portal sits at grade), matching the user's wording.
/// The handoff's "it is MEMBERSHIP/VIEWER-side" diagnosis is therefore
/// REFUTED for the current pipeline; #108-residual is RENDER-side: the
/// landscape slice clips terrain by 2D NDC planes only ((nx,ny,0,dw) —
/// ClipFrame.cs:178, terrain_modern.vert:173), so terrain BETWEEN the eye
/// and the exit portal (the grade sheet at z≈94, which from a below-grade
/// eye projects into the aperture band at y 9.8–17) paints the doorway.
/// These tests stay as the characterization pin for the healthy layer.
/// </summary>
public class Issue108CellarAscentViewerReplayTests
{
    private readonly ITestOutputHelper _out;
    public Issue108CellarAscentViewerReplayTests(ITestOutputHelper output) => _out = output;

    private const float ViewerSphereRadius = 0.3f;  // retail viewer_sphere (acclient :93314)
    private const float PivotHeight = 1.5f;         // RetailChaseCamera.PivotHeight
    private const float FootRadius = 0.48f;         // player foot sphere
    private const float BoomDistance = 2.61f;       // retail viewer_offset length
    private const float BoomPitch = 0.291f;         // retail default pitch (16.7°)
    private const float GradeZ = 94.0f;             // cottage floor == door sill ≈ outdoor terrain grade

    private const uint Lb = 0xA9B40000u;            // ConformanceDats.HoltburgLandblock
    private const uint CellarRoom = Lb | 0x0174u;   // floor z≈90.0
    private const uint MainFloor = Lb | 0x0171u;    // z=94.0

    // ── fixture ─────────────────────────────────────────────────────────

    private static (PhysicsEngine engine, PhysicsDataCache cache,
        Dictionary<uint, AcDream.Core.World.Cells.EnvCell> envCells)
        BuildEngine(DatCollection dats)
    {
        var cache = new PhysicsDataCache();
        var engine = new PhysicsEngine { DataCache = cache };
        var envCells = new Dictionary<uint, AcDream.Core.World.Cells.EnvCell>();

        // Full A9B4 interior set (Issue112MembershipTests.LoadLandblockInteriors
        // pattern) — the ascent's pick walk may reach cells outside the corner
        // building's 0x016F-0x0175 range.
        for (uint low = 0x0100u; low <= 0x01FFu; low++)
        {
            try { envCells[Lb | low] = ConformanceDats.LoadEnvCell(dats, cache, Lb | low); }
            catch { }
        }

        // Buildings exactly as production registers them (Issue112MembershipTests.
        // RegisterBuildings provenance): portals → BldPortalInfo with sign-extended
        // OtherPortalId; landcell id from the building Frame.Origin (retail
        // row-major grid).
        var lbInfo = dats.Get<DatReaderWriter.DBObjs.LandBlockInfo>(Lb | 0xFFFEu);
        Assert.NotNull(lbInfo);
        foreach (var building in lbInfo!.Buildings)
        {
            if (building.Portals.Count == 0) continue;
            var portals = new List<BldPortalInfo>(building.Portals.Count);
            foreach (var bp in building.Portals)
                portals.Add(new BldPortalInfo(
                    otherCellId: Lb | (uint)bp.OtherCellId,
                    otherPortalId: unchecked((short)bp.OtherPortalId),
                    flags: (ushort)bp.Flags));
            var transform =
                Matrix4x4.CreateFromQuaternion(building.Frame.Orientation) *
                Matrix4x4.CreateTranslation(building.Frame.Origin);
            int gridX = (int)(building.Frame.Origin.X / 24f);
            int gridY = (int)(building.Frame.Origin.Y / 24f);
            uint landcellLow = (uint)(gridX * 8 + gridY + 1);
            cache.CacheBuilding(Lb | landcellLow, portals, transform);
        }

        var heights = new byte[81];
        var heightTable = new float[256];
        for (int i = 0; i < 256; i++) heightTable[i] = -1000f;
        engine.AddLandblock(Lb, new TerrainSurface(heights, heightTable),
            Array.Empty<CellSurface>(), Array.Empty<PortalPlane>(), 0f, 0f);

        return (engine, cache, envCells);
    }

    // ── the probe mirror (PhysicsCameraCollisionProbe.SweepEye, verbatim) ──

    private enum ViewerBranch { Sweep, AdjustFallback, NullFallback }

    private sealed record ViewerResolve(
        Vector3 Eye, uint ViewerCellId, ViewerBranch Branch,
        uint StartCell, bool PivotAdjustFound, ResolveResult Sweep);

    private static ViewerResolve ResolveViewer(
        PhysicsEngine engine, Vector3 pivot, Vector3 desiredEye, uint cellId, Vector3 playerPos)
    {
        // update_viewer (pc:92775): no player cell → snap to player, viewer_cell null.
        if (cellId == 0u)
            return new ViewerResolve(playerPos, 0u, ViewerBranch.NullFallback, 0u, false, default);

        uint startCell = cellId;
        bool pivotFound = false;
        if ((cellId & 0xFFFFu) >= 0x0100u)
        {
            var (pivotCell, found) = engine.AdjustPosition(cellId, pivot);
            pivotFound = found;
            if (found) startCell = pivotCell;
        }

        Vector3 begin = pivot - new Vector3(0f, 0f, ViewerSphereRadius);
        Vector3 end = desiredEye - new Vector3(0f, 0f, ViewerSphereRadius);

        var r = engine.ResolveWithTransition(
            currentPos: begin,
            targetPos: end,
            cellId: startCell,
            sphereRadius: ViewerSphereRadius,
            sphereHeight: 0f,
            stepUpHeight: 0f,
            stepDownHeight: 0f,
            isOnGround: false,
            body: null,
            moverFlags: ObjectInfoState.IsViewer | ObjectInfoState.PathClipped
                      | ObjectInfoState.FreeRotate | ObjectInfoState.PerfectClip,
            movingEntityId: 0);

        Vector3 eye = r.Position + new Vector3(0f, 0f, ViewerSphereRadius);
        if (r.Ok)
            return new ViewerResolve(eye, r.CellId, ViewerBranch.Sweep, startCell, pivotFound, r);

        var (eyeCell, eyeFound) = engine.AdjustPosition(cellId, desiredEye);
        if (eyeFound)
            return new ViewerResolve(desiredEye, eyeCell, ViewerBranch.AdjustFallback, startCell, pivotFound, r);

        return new ViewerResolve(playerPos, 0u, ViewerBranch.NullFallback, startCell, pivotFound, r);
    }

    // ── the ascent ──────────────────────────────────────────────────────

    /// <summary>Stair-line feet Z for a path y (fitted from the capture bands).</summary>
    private static float FeetZ(float y)
    {
        if (y < 5.73f) return 90.0f;
        if (y < 9.30f) return MathF.Min(90.25f + 0.836f * (y - 5.73f), 93.25f);
        if (y < 10.40f) return 93.25f + (y - 9.30f) * (0.75f / 1.10f);
        return 94.0f;
    }

    private sealed record Step(
        int Index, Vector3 Feet, uint PlayerCell,
        ViewerResolve Viewer, uint EyeContainedIn, bool EyeBelowGrade)
    {
        public bool ViewerOutdoorOrNull =>
            Viewer.ViewerCellId == 0u || (Viewer.ViewerCellId & 0xFFFFu) < 0x0100u;
    }

    private List<Step>? RunAscent(float boomDistance, float pathLagMeters)
    {
        var datDir = ConformanceDats.ResolveDatDir();
        if (datDir is null) { _out.WriteLine("SKIP: dats unavailable"); return null; }

        using var dats = new DatCollection(datDir, DatAccessType.Read);
        var (engine, _, envCells) = BuildEngine(dats);

        const float yStart = 5.2f, yEnd = 16.0f;
        const float stepLen = 0.02f;                 // 2 cm/frame ≈ 1.2 m/s at 60 Hz
        var fwd = new Vector3(0f, 1f, 0f);           // facing up the stairs / at the exit door
        float cosP = MathF.Cos(BoomPitch), sinP = MathF.Sin(BoomPitch);

        // Stairs run at x≈153.9; past the lip the real walk line bends to the
        // exit-door approach at x≈155 (corner-seal capture S1: player
        // (154.93, 16.45)) — walking straight north at 153.9 ends in the wall
        // beside the 0x0170 doorway, which a live player cannot do.
        static float FeetX(float y) =>
            y <= 10.4f ? 153.9f
            : y >= 14.0f ? 155.0f
            : 153.9f + (y - 10.4f) / (14.0f - 10.4f) * (155.0f - 153.9f);

        var steps = new List<Step>();
        uint playerCell = CellarRoom;
        int count = (int)MathF.Round((yEnd - yStart) / stepLen);

        for (int i = 0; i <= count; i++)
        {
            float y = yStart + i * stepLen;
            var feet = new Vector3(FeetX(y), y, FeetZ(y));

            // production controller pick: foot-sphere CENTER, seeded with the carried cell
            playerCell = CellTransit.FindCellList(
                engine.DataCache!, feet + new Vector3(0f, 0f, FootRadius), FootRadius, playerCell);

            // boom target — optionally computed from a lagged path point to model the
            // exponential damping trail (≈0.27 m at climb speed; 0 = converged target)
            float yBoom = MathF.Max(yStart, y - pathLagMeters);
            var boomFeet = new Vector3(FeetX(yBoom), yBoom, FeetZ(yBoom));
            var pivot = feet + new Vector3(0f, 0f, PivotHeight);
            var boomPivot = boomFeet + new Vector3(0f, 0f, PivotHeight);
            var desiredEye = boomPivot - fwd * (boomDistance * cosP)
                           + new Vector3(0f, 0f, boomDistance * sinP);

            var viewer = ResolveViewer(engine, pivot, desiredEye, playerCell, feet);

            uint containedIn = 0u;
            foreach (var (id, env) in envCells)
                if (env.PointInCell(viewer.Eye)) { containedIn = id; break; }

            steps.Add(new Step(i, feet, playerCell, viewer,
                containedIn, viewer.Eye.Z < GradeZ - 0.05f));
        }

        return steps;
    }

    private void DumpStep(Step s)
    {
        var v = s.Viewer;
        string line = FormattableString.Invariant(
            $"step={s.Index,3} feet=({s.Feet.X:F2},{s.Feet.Y:F2},{s.Feet.Z:F2}) pCell=0x{s.PlayerCell & 0xFFFFu:X4} start=0x{v.StartCell & 0xFFFFu:X4}{(v.PivotAdjustFound ? "" : "!")} branch={v.Branch} ok={v.Sweep.Ok} eye=({v.Eye.X:F2},{v.Eye.Y:F2},{v.Eye.Z:F2}) viewer=0x{v.ViewerCellId & 0xFFFFu:X4} eyeIn=0x{s.EyeContainedIn & 0xFFFFu:X4} belowGrade={(s.EyeBelowGrade ? "Y" : "n")}");
        if (s.EyeBelowGrade && s.ViewerOutdoorOrNull) line += "  << GRASS-WINDOW";
        _out.WriteLine(line);
    }

    // ── diagnostics + pins ──────────────────────────────────────────────

    /// <summary>
    /// Full per-step table of the ascent at retail boom defaults (converged
    /// boom, no lag). Read this first — the GRASS-WINDOW marks name the steps
    /// where the production stack resolves an outdoor/null viewer with the eye
    /// below grade, and the branch column attributes the demote site.
    /// </summary>
    [Fact]
    public void Diagnostic_CellarAscent_PerStepTable()
    {
        var steps = RunAscent(BoomDistance, pathLagMeters: 0f);
        if (steps is null) return;

        uint lastPlayer = 0; uint lastViewer = 0xFFFFFFFFu; var lastBranch = (ViewerBranch)(-1);
        int suspicious = 0;
        foreach (var s in steps)
        {
            bool grass = s.EyeBelowGrade && s.ViewerOutdoorOrNull;
            if (grass) suspicious++;
            if (s.PlayerCell != lastPlayer || s.Viewer.ViewerCellId != lastViewer
                || s.Viewer.Branch != lastBranch || grass || s.Index % 50 == 0)
                DumpStep(s);
            lastPlayer = s.PlayerCell; lastViewer = s.Viewer.ViewerCellId; lastBranch = s.Viewer.Branch;
        }
        _out.WriteLine(FormattableString.Invariant(
            $"--- {suspicious}/{steps.Count} steps in the grass window (viewer outdoor/null while eye below grade) ---"));
    }

    /// <summary>Boom-distance + damping-lag sweep: how wide is the window across poses?</summary>
    [Fact]
    public void Diagnostic_CellarAscent_PoseSweep()
    {
        foreach (float dist in new[] { 2.61f, 5.0f })
            foreach (float lag in new[] { 0f, 0.30f })
            {
                var steps = RunAscent(dist, lag);
                if (steps is null) return;
                int grass = steps.FindAll(s => s.EyeBelowGrade && s.ViewerOutdoorOrNull).Count;
                int okFalse = steps.FindAll(s => !s.Viewer.Sweep.Ok).Count;
                int fb = steps.FindAll(s => s.Viewer.Branch != ViewerBranch.Sweep).Count;
                _out.WriteLine(FormattableString.Invariant(
                    $"dist={dist:F2} lag={lag:F2}: grassWindow={grass}/{steps.Count} sweepOkFalse={okFalse} fallbackBranch={fb}"));
            }
    }

    /// <summary>
    /// THE PIN: while the eye is below terrain grade on the cellar ascent, the
    /// viewer must resolve INTERIOR — an outdoor/null viewer cell roots the
    /// frame at the landscape and sweeps grass across the exit door (#108).
    /// Retail's viewer rides the stairwell cells here (the cellar camera works
    /// in retail); below grade inside the building footprint there is no
    /// legitimate outdoor viewer.
    /// </summary>
    [Fact]
    public void CellarAscent_ViewerStaysInterior_WhileEyeBelowGrade()
    {
        var steps = RunAscent(BoomDistance, pathLagMeters: 0f);
        if (steps is null) return;

        var failures = steps.FindAll(s => s.EyeBelowGrade && s.ViewerOutdoorOrNull);
        if (failures.Count > 0)
        {
            _out.WriteLine($"--- {failures.Count} grass-window steps ---");
            foreach (var s in failures) DumpStep(s);
        }
        Assert.True(failures.Count == 0,
            $"{failures.Count}/{steps.Count} ascent steps resolve an outdoor/null viewer cell while the eye " +
            "is below grade — the #108 grass window (see output for the branch attribution)");
    }
}