erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions

fix(runtime): name why a placement is parked and fail closed when it cannot resolve

Browse source 
Fixes #284 (plan S1).

A first-entry placement that could not be prepared returned
RetrySetupUnavailable and was re-Advanced every pump forever. Nothing counted
it, nothing named its cause, and nothing distinguished "waiting for something
that will arrive" from "waiting for something that never can". That is why
#281's 43 test failures presented as four unrelated symptoms across App and
Runtime instead of one cause, and why a stuck entity in the live client simply
never appears with no log line to follow.

Worse, the two causes were conflated: 670f307c's missing-world-frame park
reported itself as RetrySetupUnavailable, sending anyone diagnosing it to the
prepared-asset pipeline rather than to the absent local-player Create that
actually publishes the frame.

- RetryWorldFrameUnavailable splits the two causes. Call sites now ask
  IsRetryable() instead of comparing against one reason, so a future retry
  reason cannot be silently reclassified as a hard rejection - the exact way
  this class of bug hides.
- The operation retains its RuntimeSetPositionParkReason, and
  RuntimeSetPositionOwnershipSnapshot reports parked work by cause
  (ParkedAwaitingSetupCollisionCount / ParkedAwaitingWorldFrameCount /
  ParkedPlacementCount), so parked placements appear wherever ledgers are
  already asserted.
- ObserveLocalPlayerCreate records the accepted local-player Create even when
  it carries no landblock - precisely the case where no frame is ever
  published - and ThrowIfWorldFrameUnreachable makes that contradiction
  terminal. Waiting is legitimate only while that Create is outstanding; after
  it, no later pump can supply the frame. Same shape as 01f4791e, which made a
  violated receipt-ledger invariant terminal rather than resumable.

This is observability plus fail-fast. There is no timeout, no retry cap, and
no grace period anywhere in it; retryable work still retries exactly as before
and no placement behaviour changed.

The parked counts are deliberately NOT folded into IsConverged: #277 documents
a far Create legitimately parking for a whole session, so a parked entry at
teardown is not automatically a defect. Wiring them into the connected gates
is carried with #277's service-window conversion, where "legitimately parked"
becomes definable.

Runtime 1,012/1,012. Complete Release solution: 10,834 passed / 4 skipped /
0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-08-03 13:55:16 +02:00
parent 95ebc03af4
commit 97d11e6c7f
9 changed files with 273 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

71
src/AcDream.Runtime/Physics/RuntimeSetPositionState.cs
View file

@ -273,8 +273,18 @@ internal readonly record struct RuntimeSetPositionOwnershipSnapshot(
int AcknowledgedPlacementCompletionCount,
int CollisionPrefixQuiescenceCount,
int PendingQuiescenceProjectionCount,
int PooledOperationCount)
int PooledOperationCount,
int ParkedAwaitingSetupCollisionCount = 0,
int ParkedAwaitingWorldFrameCount = 0)
{
/// <summary>
/// #284: placements that could not be prepared on their last attempt and
/// are waiting for a later pump, by cause. Non-zero at a stable
/// checkpoint means work is stuck; the reason names where to look.
/// </summary>
internal int ParkedPlacementCount =>
ParkedAwaitingSetupCollisionCount + ParkedAwaitingWorldFrameCount;
internal bool IndexesConsistent =>
LostDeadlineCount == LostDeadlineNodeCount
&& LostDeadlineCount == LostDeadlineIndexCount
@ -399,6 +409,13 @@ internal sealed class RuntimeSetPositionState : IDisposable
internal bool InheritedLostDeadline { get; set; }
internal bool EnteringWorldFromCelllessResidence { get; set; }
internal bool DormantLocalActivation { get; set; }
/// <summary>
/// #284: why this operation's mover preparation is currently parked,
/// or <see cref="RuntimeSetPositionParkReason.None"/> when it is not.
/// Observability only - it never gates work.
/// </summary>
internal RuntimeSetPositionParkReason ParkReason { get; set; }
internal RuntimeSetPositionCommand? PreparedCommandAwaitingWithdrawalAck
{
get;
@ -464,6 +481,7 @@ internal sealed class RuntimeSetPositionState : IDisposable
InheritedLostDeadline = false;
EnteringWorldFromCelllessResidence = false;
DormantLocalActivation = false;
ParkReason = RuntimeSetPositionParkReason.None;
PreparedCommandAwaitingWithdrawalAck = null;
InPool = false;
}
@ -726,6 +744,8 @@ internal sealed class RuntimeSetPositionState : IDisposable
{
int deferred = 0;
int awaitingPreparation = 0;
int parkedAwaitingSetup = 0;
int parkedAwaitingWorldFrame = 0;
foreach (Operation operation in _operations.Values)
{
if (operation.Stage
@ -735,6 +755,15 @@ internal sealed class RuntimeSetPositionState : IDisposable
}
if (operation.WakeableLostCell)
deferred++;
switch (operation.ParkReason)
{
case RuntimeSetPositionParkReason.AwaitingSetupCollision:
parkedAwaitingSetup++;
break;
case RuntimeSetPositionParkReason.AwaitingWorldFrame:
parkedAwaitingWorldFrame++;
break;
}
}
int pendingQuiescenceProjections = 0;
foreach (CollisionPrefixQuiescence quiescence
@ -764,7 +793,9 @@ internal sealed class RuntimeSetPositionState : IDisposable
_acknowledgedPlacementCompletions.Count,
_collisionPrefixQuiescence.Count,
pendingQuiescenceProjections,
_operationPool.Count);
_operationPool.Count,
parkedAwaitingSetup,
parkedAwaitingWorldFrame);
}
internal int PendingProjectionCount => _pendingProjection.Count;
@ -1518,8 +1549,10 @@ internal sealed class RuntimeSetPositionState : IDisposable
if (!preparation.Setup.IsResolved)
{
return RuntimeSetPositionMoverPreparationStatus
.RetrySetupUnavailable;
return Park(
operation,
RuntimeSetPositionMoverPreparationStatus
.RetrySetupUnavailable);
}
RuntimeSetPositionMoverPreparation effectivePreparation = preparation;
@ -1537,8 +1570,19 @@ internal sealed class RuntimeSetPositionState : IDisposable
out float worldOffsetX,
out float worldOffsetY))
{
return RuntimeSetPositionMoverPreparationStatus
.RetrySetupUnavailable;
// #284: the frame is published once, by the accepted
// local-player Create, and is never withdrawn inside a
// session. If that Create has already been observed, waiting
// is not a wait - no later pump can ever supply the frame, so
// parking here would retry forever in silence. Surface the
// contradiction instead, exactly as 01f4791e made a violated
// receipt-ledger invariant terminal rather than resumable.
_physics.ThrowIfWorldFrameUnreachable(
authority.AcceptedPosition.LandblockId);
return Park(
operation,
RuntimeSetPositionMoverPreparationStatus
.RetryWorldFrameUnavailable);
}
effectivePreparation = preparation with
@ -1569,9 +1613,24 @@ internal sealed class RuntimeSetPositionState : IDisposable
PreparedCommand = command,
};
operation.ParkReason = RuntimeSetPositionParkReason.None;
return RuntimeSetPositionMoverPreparationStatus.Prepared;
}
/// <summary>
/// #284: records why this operation could not be prepared, so parked work
/// is visible in <see cref="CaptureOwnership"/> by cause rather than only
/// as a downstream symptom. Retains the reason on the operation until the
/// preparation succeeds or the operation is retired.
/// </summary>
private static RuntimeSetPositionMoverPreparationStatus Park(
Operation operation,
RuntimeSetPositionMoverPreparationStatus status)
{
operation.ParkReason = status.ParkReason();
return status;
}
/// <summary>
/// C0-3: chains the exact-Setup mover pipeline end-to-end for an
/// authored placement (initial-Create or any other authored-mover