acdream/src/AcDream.Headless/Hosting/HeadlessRuntimePlacementProjectionSink.cs

using AcDream.Runtime;
using AcDream.Runtime.Entities;
using AcDream.Runtime.Physics;
using AcDream.Runtime.World;

namespace AcDream.Headless.Hosting;

/// <summary>
/// Validation-only no-window observer for canonical Runtime SetPosition
/// receipts. A headless host has no graphical sidecar to move or hide, so a
/// valid receipt is acknowledged without re-running placement or mutating
/// Runtime's body, controller, shadows, clocks, or worksets.
/// </summary>
internal sealed class HeadlessRuntimePlacementProjectionSink
    : IRuntimePlacementProjectionSink
{
    private readonly GameRuntime _runtime;

    internal HeadlessRuntimePlacementProjectionSink(GameRuntime runtime)
    {
        _runtime = runtime ?? throw new ArgumentNullException(nameof(runtime));
    }

    public bool TryApply(
        in RuntimePlacementProjectionSnapshot projection)
    {
        if (projection.Kind is RuntimePlacementProjectionKind.Discard)
        {
            // Discard cancels only an unacknowledged observation. It is valid
            // even after its entity/session authority has been superseded.
            return true;
        }

        if (projection.Kind is RuntimePlacementProjectionKind.ExecutorCompleted)
        {
            // F1: acknowledge-and-ignore, same as Discard - ExecutorCompleted
            // is not a placement to project (a headless host has no
            // presentation to bind off the completed initial drain; the
            // executor's own drain already committed every canonical fact).
            // It must NOT fall through to the record-lookup gate below: that
            // gate can validly reject an unrelated entity/session mismatch,
            // and this sink's caller (RuntimePlacementProjectionSubscription)
            // treats a false return as "leave at the FIFO head" - a rejected
            // ExecutorCompleted would permanently wedge the entire ordered
            // placement stream behind it.
            return true;
        }

        if (projection.Kind
            is RuntimePlacementProjectionKind.WithdrawalRestored)
        {
            // Acknowledge-and-ignore for the same reason: the receipt rolls
            // back the PRESENTATION half of a cancelled park's withdrawal, and
            // a headless host has no graphical sidecar, plugin world state,
            // effect poses, or visibility sinks to restore - Runtime already
            // restored every canonical fact before publishing it. Refusing it
            // would wedge the whole ordered stream.
            return true;
        }

        RuntimePlacementProjectionToken token = projection.Token;
        RuntimeEntityDirectory directory = _runtime.EntityObjects.Entities;
        if (projection.Kind is RuntimePlacementProjectionKind.Place
            or RuntimePlacementProjectionKind.Withdraw
            && token.IsValid
            && directory.TryGetByLocalId(
                token.Entity.LocalEntityId,
                out RuntimeEntityRecord residenceCandidate)
            && directory.IsCurrent(residenceCandidate)
            && residenceCandidate.Key == token.Entity
            && _runtime.EntityObjects.TryGetInitialCreateResidence(
                residenceCandidate,
                out _))
        {
            // C3c: a Place/Withdraw for an entity still holding its
            // initial-create residence belongs to the first-entry conductor
            // machinery, which acknowledges its own receipts at the exact
            // FIFO head. Leave it there for the drive pump; validating or
            // acknowledging it here would starve the conductor forever.
            return false;
        }
        if (!token.IsValid
            || token.SessionLifetimeVersion
                != directory.SessionLifetimeVersion
            || !directory.TryGetByLocalId(
                token.Entity.LocalEntityId,
                out RuntimeEntityRecord record)
            || !directory.IsCurrent(record)
            || record.Key != token.Entity
            || !HasValidPortalShape(token))
        {
            return false;
        }

        if (projection.Kind is RuntimePlacementProjectionKind.Withdraw)
            return true;
        if (projection.Kind is not RuntimePlacementProjectionKind.Place)
            return false;

        if (record.PositionAuthorityVersion != token.PositionAuthorityVersion
            || record.SpatialAuthorityVersion != token.SpatialAuthorityVersion
            || record.PlacementCommitVersion != token.PlacementCommitVersion
            || record.FullCellId != token.ExactCellId)
        {
            return false;
        }

        if (!_runtime.TransitOwner.IsCurrentPlacementAuthority(
                token.Portal,
                token.ExactCellId))
        {
            // B2 review fix (2026-08-05): acknowledge-and-ignore, the same
            // shape and reasoning as the graphical sink's identical fix
            // (RuntimePlacementPresentationSink.TryApply) — a stale portal
            // authority must not wedge the ordered FIFO for every entity.
            return true;
        }

        return true;
    }

    private static bool HasValidPortalShape(
        in RuntimePlacementProjectionToken token)
    {
        RuntimePortalPlacementAuthority portal = token.Portal;
        if (!portal.Present)
            return portal.IsEmpty;

        return portal.IsValid
            && portal.Projection.DestinationCell == token.ExactCellId;
    }
}