@forgeax/engine-physics-rapier3d 0.1.26 → 0.1.28

package/src/rapier-physics-world-3d.ts

@@ -22,21 +22,44 @@ import { defineSystem } from '@forgeax/engine-ecs';
 import { componentId } from '@forgeax/engine-ecs/internal';
 import { readStructuralEvidence } from '@forgeax/engine-ecs/projection';
 import { mat4, quat, type Vec3, vec3 } from '@forgeax/engine-math';
-import type { PhysicsWorld, RaycastHit } from '@forgeax/engine-physics';
 import {
   CharacterController,
   Collider,
   CollidingEntities,
+  cloneDerivedPhysicsInput,
   colliderShapeFromF32,
+  DERIVED_PHYSICS_LIMITS,
+  type DerivedPhysicsCandidate,
+  type DerivedPhysicsCandidateInput,
+  type DerivedPhysicsCandidateState,
+  DerivedPhysicsError,
+  type DerivedPhysicsFailure,
+  type DerivedPhysicsMotion,
+  type DerivedPhysicsPublication,
+  type DerivedPhysicsSnapshot,
+  type DerivedShapeSeamInput,
+  type DerivedShapeState,
+  estimateDerivedPhysicsInputBytes,
   PHYSICS_ERROR_HINTS,
+  type PhysicsConstraintInput,
+  type PhysicsContactObservation,
   PhysicsError,
+  type PhysicsMassProperties,
+  type PhysicsQuaternion,
   PhysicsSet,
+  type PhysicsVector,
+  type PhysicsWorld,
+  preserveCenterOfMassVelocity,
+  type RaycastHit,
   RIGID_BODY_TYPE_STATIC,
   RigidBody,
   registerPhysicsComponents,
   rigidBodyTypeFromF32,
+  type VoxelShapeInput,
+  validateMassProperties,
 } from '@forgeax/engine-physics';
 import { ChildOf } from '@forgeax/engine-scene';
+import { err, ok, type Result } from '@forgeax/engine-types';
 import type { Rapier3DModule } from './wasm-loader';
 
 interface Rapier3DKinematicControllerState {
@@ -50,6 +73,12 @@ interface Rapier3DKinematicControllerState {
  */
 interface PhysicsEntityRecord {
   bodyHandle: number;
+  /** Authored additional mass used to restore automatic derived policy. */
+  additionalMass: number;
+  /** Additional mass currently applied to Rapier's automatic mass policy. */
+  automaticAdditionalMass: number;
+  /** Base collider density before an explicit derived mass override. */
+  authoredDensity: number | undefined;
 }
 
 interface PhysicsTransform3D {
@@ -90,7 +119,7 @@ interface PhysicsSyncState {
   readonly world: World;
   readonly transformComponent: Component;
   readonly globalTransformComponent: Component;
-  readonly query: PhysicsSyncQuery;
+  readonly queries: readonly PhysicsSyncQuery[];
   readonly changeQueries: readonly PhysicsChangeQuery[];
   structuralCursor: number;
   structureEpoch: number;
@@ -113,7 +142,7 @@ interface PhysicsSyncDescriptor {
     readonly gravityScale: number;
     readonly ccdEnabled: number;
   };
-  readonly collider: PhysicsCollider3D;
+  readonly collider: PhysicsCollider3D | undefined;
   readonly hasCharacterController: boolean;
   readonly characterControllerOffset: number | undefined;
 }
@@ -167,6 +196,51 @@ export interface Rapier3DCollisionEvent {
   readonly type: 'started' | 'stopped';
   readonly entityA: number;
   readonly entityB: number;
+  readonly fixedStep?: number;
+  readonly shapeA?: string;
+  readonly shapeB?: string;
+}
+
+interface DerivedShapeRecord {
+  readonly input: VoxelShapeInput & {
+    readonly cells: Int32Array;
+    readonly origin: PhysicsVector;
+    readonly rotation: PhysicsQuaternion;
+  };
+  readonly colliderHandle: number;
+}
+
+interface DerivedBodyRecord {
+  readonly entity: number;
+  readonly sourceKey: string;
+  readonly generation: number;
+  readonly revision: number;
+  readonly bodyType: 'static' | 'dynamic' | 'kinematic' | undefined;
+  readonly velocityPolicy: 'preserve' | 'reset' | undefined;
+  readonly candidateId: string;
+  readonly shapes: readonly DerivedShapeRecord[];
+  readonly seams: readonly DerivedShapeSeamInput[];
+  readonly massProperties: PhysicsMassProperties | undefined;
+  readonly constraints: readonly PhysicsConstraintInput[];
+}
+
+interface DerivedCandidateRecord {
+  token: DerivedPhysicsCandidate;
+  readonly nativeColliders: readonly { readonly handle: number }[];
+  readonly input: DerivedPhysicsCandidateInput;
+  readonly bytes: number;
+  state: DerivedPhysicsCandidateState;
+  commitGeometry?: () => Result<void, Error>;
+}
+
+interface DerivedConstraintRecord {
+  readonly input: PhysicsConstraintInput;
+  readonly handle: number;
+}
+
+interface DerivedBodySource {
+  readonly sourceKey: string;
+  readonly revision: number;
 }
 
 // biome-ignore lint/suspicious/noExplicitAny: Rapier types from dynamically loaded module
@@ -215,13 +289,78 @@ function applyKccTuning(ctrl: any, cc: CharacterControllerTuning): void {
  * Map a Rapier RigidBodyType enum value to the engine's string union for the
  * `controller-requires-kinematic` error detail.
  */
-// biome-ignore lint/suspicious/noExplicitAny: Rapier module enum from dynamic module
-function rapierBodyTypeToString(rapier: any, bodyType: number): string {
+function rapierBodyTypeToString(
+  rapier: { readonly RigidBodyType: { readonly Dynamic: number; readonly Fixed: number } },
+  bodyType: number,
+): 'static' | 'dynamic' | 'kinematic' {
   if (bodyType === rapier.RigidBodyType.Dynamic) return 'dynamic';
   if (bodyType === rapier.RigidBodyType.Fixed) return 'static';
   return 'kinematic';
 }
 
+function validateConstraintInput(
+  input: PhysicsConstraintInput,
+): Result<PhysicsConstraintInput, DerivedPhysicsError> {
+  const finiteVector = (value: readonly number[]): boolean =>
+    value.length === 3 && value.every(Number.isFinite);
+  if (
+    typeof input.id !== 'string' ||
+    input.id.trim().length === 0 ||
+    !Number.isInteger(input.revision) ||
+    input.revision < 0 ||
+    !Number.isInteger(input.bodyA) ||
+    !Number.isInteger(input.bodyB) ||
+    input.bodyA === input.bodyB ||
+    !finiteVector(input.anchorA) ||
+    !finiteVector(input.anchorB)
+  ) {
+    return err(
+      new DerivedPhysicsError(
+        'derived-constraint-invalid',
+        'constraint identity, revision, endpoint bodies, and anchors are valid',
+        'supply two distinct live bodies and finite local anchors',
+        { constraintId: input.id },
+      ),
+    );
+  }
+  if (input.kind === 'spring') {
+    if (
+      !Number.isFinite(input.restLength) ||
+      input.restLength < 0 ||
+      !Number.isFinite(input.stiffness) ||
+      input.stiffness < 0 ||
+      !Number.isFinite(input.damping) ||
+      input.damping < 0
+    ) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-constraint-invalid',
+          'spring rest length, stiffness, and damping are finite and non-negative',
+          'repair spring tuning before native creation',
+          { constraintId: input.id },
+        ),
+      );
+    }
+  } else if (
+    !finiteVector(input.axis) ||
+    Math.hypot(input.axis[0], input.axis[1], input.axis[2]) < 1e-6 ||
+    (input.limits !== undefined &&
+      (!Number.isFinite(input.limits[0]) ||
+        !Number.isFinite(input.limits[1]) ||
+        input.limits[0] > input.limits[1]))
+  ) {
+    return err(
+      new DerivedPhysicsError(
+        'derived-constraint-invalid',
+        'hinge axis is non-zero and optional limits are ordered finite values',
+        'normalize the hinge axis and set minLimit <= maxLimit',
+        { constraintId: input.id },
+      ),
+    );
+  }
+  return ok(input);
+}
+
 /**
  * RapierPhysicsWorld3D — Rapier 3D WASM backend implementing the PhysicsWorld
  * interface.
@@ -254,6 +393,27 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
 
   private readonly collisionEventHistory: Rapier3DCollisionEvent[] = [];
 
+  /** One backend owns every derived shape; these maps are not a second world. */
+  private readonly derivedBodies = new Map<number, DerivedBodyRecord>();
+  private readonly derivedCandidates = new Map<string, DerivedCandidateRecord>();
+  private readonly pendingDerivedCandidates = new Set<string>();
+  private readonly retiredDerivedBodies: DerivedBodyRecord[] = [];
+  private readonly derivedColliderToShape = new Map<number, { entity: number; id: string }>();
+  private readonly derivedConstraints = new Map<string, DerivedConstraintRecord>();
+  private readonly derivedBodySources = new Map<number, DerivedBodySource>();
+  private readonly derivedPublications = new Map<number, DerivedPhysicsPublication>();
+  private readonly derivedFailures = new Map<number, DerivedPhysicsFailure>();
+  private readonly derivedContacts: PhysicsContactObservation[] = [];
+  private readonly derivedPoisonedEntities = new Set<number>();
+  private readonly physicsOwner = {};
+  private candidateSequence = 0;
+  private derivedCandidateBytes = 0;
+  private backendGeneration = 1;
+  private fixedStep = 0;
+  private derivedPublicationPending = false;
+  private worldIdentity: object | undefined;
+  private activeDerivedAdmission: DerivedCandidateRecord | undefined;
+
   private currentGravity: { x: number; y: number; z: number };
 
   /**
@@ -315,6 +475,14 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     filterMask?: number,
   ): RaycastHit | undefined {
     this.assertActive('raycast');
+    if (this.recoveryBlocked()) {
+      throw new DerivedPhysicsError(
+        'derived-recovery-invalid',
+        'raycasts observe a complete healthy physics state',
+        'rebuild the PhysicsWorld before querying after an unrecoverable admission',
+        {},
+      );
+    }
     const RAPIER = this.rapierModule;
     // biome-ignore lint/suspicious/noExplicitAny: Rapier Ray constructor comes from a namespace module
     const RayCtor = (RAPIER as any).Ray as new (
@@ -369,9 +537,46 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   step(deltaTime: number): void {
     this.assertActive('step');
     void deltaTime;
-    // biome-ignore lint/suspicious/noExplicitAny: Rapier World.step
-    (this.raw as any).step(this.eventQueue);
-    this.drainRapierCollisionEvents();
+    try {
+      this.processDerivedCandidates();
+      // A failed native rollback is an explicit rebuild boundary. Physics does
+      // not advance or publish a mixed state after this point.
+      if (this.derivedPoisonedEntities.size > 0) return;
+      // biome-ignore lint/suspicious/noExplicitAny: Rapier World.step
+      (this.raw as any).step(this.eventQueue);
+      this.fixedStep = this.syncState?.world.getResource(FixedTime).tick ?? this.fixedStep + 1;
+      this.drainRapierCollisionEvents();
+      this.derivedPublicationPending = true;
+      // Direct PhysicsWorld consumers do not have ECS writeback systems. Keep
+      // that public path useful while ECS-bound worlds finalize after writeback
+      // and collision component synchronization below.
+      if (this.syncState === undefined) this.finalizeDerivedFixedStep();
+    } catch (cause) {
+      // A native step or contact drain may have advanced before throwing.
+      // Geometry may already be committed; neither domain can claim LKG.
+      const error = new DerivedPhysicsError(
+        'derived-backend-failed',
+        'native fixed-step execution and publication complete together',
+        'rebuild the World and PhysicsWorld from the last committed snapshot',
+        { reason: cause instanceof Error ? cause.message : String(cause) },
+      );
+      for (const entity of this.entityMap.keys()) this.derivedPoisonedEntities.add(entity);
+      this.derivedPublicationPending = false;
+      this.derivedPublications.clear();
+      for (const record of this.derivedCandidates.values()) {
+        this.rememberDerivedFailure(record, error, 'rebuild-required');
+      }
+      throw error;
+    }
+  }
+
+  /** Publish only after the fixed-step ECS writeback/contact boundary. */
+  finalizeDerivedFixedStep(): void {
+    if (!this.derivedPublicationPending) return;
+    this.derivedPublicationPending = false;
+    if (this.derivedPoisonedEntities.size > 0) return;
+    this.publishDerivedCandidates();
+    this.retireDerivedBodies();
   }
 
   /**
@@ -386,16 +591,75 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
       const a = this.colliderHandleToEntity(handle1);
       const b = this.colliderHandleToEntity(handle2);
       if (a === undefined || b === undefined) return;
+      const shapeA = this.derivedColliderToShape.get(handle1);
+      const shapeB = this.derivedColliderToShape.get(handle2);
+      this.recordContactObservation(
+        {
+          phase: started ? 'started' : 'stopped',
+          fixedStep: this.fixedStep,
+          entityA: a,
+          entityB: b,
+          ...(shapeA === undefined ? {} : { shapeA: shapeA.id }),
+          ...(shapeB === undefined ? {} : { shapeB: shapeB.id }),
+        },
+        handle1,
+        handle2,
+      );
       const changed = started ? this.addPair(a, b) : this.removePair(a, b);
       if (!changed) return;
       this.pushCollisionEvent({
         type: started ? 'started' : 'stopped',
         entityA: a,
         entityB: b,
+        fixedStep: this.fixedStep,
+        ...(shapeA === undefined ? {} : { shapeA: shapeA.id }),
+        ...(shapeB === undefined ? {} : { shapeB: shapeB.id }),
       });
     });
   }
 
+  private recordContactObservation(
+    observation: PhysicsContactObservation,
+    handleA: number,
+    handleB: number,
+  ): void {
+    let point: PhysicsVector | undefined;
+    let normal: PhysicsVector | undefined;
+    try {
+      const colliderA = (this.raw as RapierWorld).getCollider(handleA);
+      const colliderB = (this.raw as RapierWorld).getCollider(handleB);
+      if (colliderA !== null && colliderB !== null) {
+        (this.raw as RapierWorld).contactPair(
+          colliderA,
+          colliderB,
+          (manifold: RapierWorld, flipped: boolean) => {
+            if (manifold.numSolverContacts?.() > 0) {
+              const contact = manifold.solverContactPoint(0);
+              const n = manifold.normal();
+              if (contact !== null && contact !== undefined) {
+                point = [contact.x, contact.y, contact.z];
+              }
+              if (n !== null && n !== undefined) {
+                const direction = flipped ? -1 : 1;
+                normal = [n.x * direction, n.y * direction, n.z * direction];
+              }
+            }
+          },
+        );
+      }
+    } catch {
+      // Contact events remain useful without optional manifold sampling. The
+      // public type makes point/normal optional rather than inventing values.
+    }
+    this.derivedContacts.push({
+      ...observation,
+      ...(point === undefined ? {} : { point }),
+      ...(normal === undefined ? {} : { normal }),
+    });
+    if (this.derivedContacts.length > 256)
+      this.derivedContacts.splice(0, this.derivedContacts.length - 256);
+  }
+
   /** Resolve a Rapier collider handle to its owning ECS entity, or undefined. */
   private colliderHandleToEntity(colliderHandle: number): number | undefined {
     // getCollider(handle).parent() returns the owning RigidBody (compat build),
@@ -437,7 +701,14 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     const ordered =
       event.entityA <= event.entityB
         ? event
-        : { ...event, entityA: event.entityB, entityB: event.entityA };
+        : {
+            type: event.type,
+            entityA: event.entityB,
+            entityB: event.entityA,
+            ...(event.fixedStep === undefined ? {} : { fixedStep: event.fixedStep }),
+            ...(event.shapeB === undefined ? {} : { shapeA: event.shapeB }),
+            ...(event.shapeA === undefined ? {} : { shapeB: event.shapeA }),
+          };
     this.pendingCollisionEvents.push(ordered);
     this.collisionEventHistory.push(ordered);
   }
@@ -469,6 +740,1521 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     return [...this.collisionEventHistory];
   }
 
+  /** Detached fixed-step contact facts; no Rapier manifolds or handles escape. */
+  getContactObservations(): readonly PhysicsContactObservation[] {
+    if (this.recoveryBlocked()) return [];
+    return this.derivedContacts.map((contact) => ({
+      ...contact,
+      ...(contact.point === undefined ? {} : { point: [...contact.point] as PhysicsVector }),
+      ...(contact.normal === undefined ? {} : { normal: [...contact.normal] as PhysicsVector }),
+    }));
+  }
+
+  /** Prepare disabled native Voxels for one entity without changing queries. */
+  prepareDerivedShapeCandidate(
+    input: DerivedPhysicsCandidateInput,
+  ): ReturnType<NonNullable<PhysicsWorld['prepareDerivedShapeCandidate']>> {
+    this.assertActive('prepareDerivedShapeCandidate');
+    if (input.worldIdentity !== undefined && input.worldIdentity !== this.worldIdentity) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-world-mismatch',
+          'candidate belongs to the ECS World bound to this PhysicsWorld',
+          'submit the candidate to the PhysicsWorld that owns its entity',
+          { entity: input.entity },
+        ),
+      );
+    }
+    if (!this.entityMap.has(input.entity)) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-body-not-found',
+          'candidate entity has a committed body in this PhysicsWorld',
+          'wait for physics reconciliation before preparing derived shapes',
+          { entity: input.entity },
+        ),
+      );
+    }
+    if (this.derivedPoisonedEntities.has(input.entity)) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-recovery-invalid',
+          'the entity has a recoverable committed native PhysicsWorld state',
+          'rebuild the PhysicsWorld from the last portable snapshot before retrying',
+          { entity: input.entity },
+        ),
+      );
+    }
+    const active = this.derivedBodies.get(input.entity);
+    if (active !== undefined && input.revision <= active.revision) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-stale',
+          'candidate revision is newer than the committed derived shape revision',
+          'read the latest publication and advance the consumer revision',
+          { entity: input.entity, actual: input.revision, expected: `>${active.revision}` },
+        ),
+      );
+    }
+    for (const pendingId of this.pendingDerivedCandidates) {
+      const pending = this.derivedCandidates.get(pendingId);
+      if (pending?.input.entity === input.entity) {
+        return err(
+          new DerivedPhysicsError(
+            'derived-candidate-pending',
+            'one body has at most one queued derived-shape candidate',
+            'cancel or let the current candidate publish before preparing another',
+            { entity: input.entity, candidateId: pendingId },
+          ),
+        );
+      }
+    }
+    const copied = cloneDerivedPhysicsInput(input);
+    if (!copied.ok) return copied;
+    const mass = validateMassProperties(copied.value.massProperties);
+    if (!mass.ok) return mass;
+    const body = this.bodyForEntity(input.entity);
+    if (body === undefined) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-body-not-found',
+          'candidate entity resolves to a live native body',
+          'wait for the next ECS physics sync',
+          { entity: input.entity },
+        ),
+      );
+    }
+    if (this.derivedCandidates.size >= DERIVED_PHYSICS_LIMITS.maxCandidates) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-budget-exceeded',
+          `this PhysicsWorld keeps at most ${DERIVED_PHYSICS_LIMITS.maxCandidates} candidates`,
+          'cancel or publish an existing candidate before preparing another',
+          { entity: input.entity, actual: this.derivedCandidates.size },
+        ),
+      );
+    }
+    const candidateInput = Object.freeze({
+      ...copied.value,
+      ...(mass.value === undefined ? {} : { massProperties: mass.value }),
+    });
+    // Keep the public token's copied POD separate from the private record. A
+    // readonly typed-array field is still writable at runtime; admission must
+    // never consume caller mutations made after prepare() returned.
+    const privateInput = cloneDerivedPhysicsInput(candidateInput);
+    if (!privateInput.ok) return privateInput;
+    const publicInput = cloneDerivedPhysicsInput(privateInput.value);
+    if (!publicInput.ok) return publicInput;
+    const nativeColliders: { handle: number }[] = [];
+    try {
+      for (const shape of privateInput.value.shapes) {
+        const collider = this.createDerivedCollider(body, shape);
+        nativeColliders.push({ handle: collider.handle });
+      }
+    } catch (cause) {
+      for (const collider of nativeColliders) this.removeNativeCollider(collider.handle);
+      return err(
+        new DerivedPhysicsError(
+          'derived-backend-failed',
+          'Rapier can create every candidate voxel collider while it remains disabled',
+          'reduce the candidate or rebuild the PhysicsWorld after a native failure',
+          { entity: input.entity, reason: cause instanceof Error ? cause.message : String(cause) },
+        ),
+      );
+    }
+    const candidateBytes = estimateDerivedPhysicsInputBytes(privateInput.value);
+    if (this.derivedCandidateBytes + candidateBytes > DERIVED_PHYSICS_LIMITS.maxCandidateBytes) {
+      for (const collider of nativeColliders) this.removeNativeCollider(collider.handle);
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-budget-exceeded',
+          `staged candidate bytes remain within ${DERIVED_PHYSICS_LIMITS.maxCandidateBytes}`,
+          'cancel or retire an in-flight candidate before retrying',
+          { entity: input.entity, actual: this.derivedCandidateBytes + candidateBytes },
+        ),
+      );
+    }
+    const candidateId = `derived:${this.backendGeneration}:${input.entity}:${++this.candidateSequence}:${input.revision}`;
+    const token: DerivedPhysicsCandidate = Object.freeze({
+      candidateId,
+      generation: this.backendGeneration,
+      owner: this.physicsOwner,
+      input: publicInput.value,
+      state: 'ready',
+    });
+    this.derivedCandidates.set(candidateId, {
+      token,
+      nativeColliders,
+      input: privateInput.value,
+      bytes: candidateBytes,
+      state: 'ready',
+    });
+    this.derivedCandidateBytes += candidateBytes;
+    return ok(token);
+  }
+
+  /** Queue a prepared candidate for the next call to `step()`. */
+  admitDerivedShapeCandidate(
+    candidate: DerivedPhysicsCandidate,
+    commitGeometry?: () => Result<void, Error>,
+  ): ReturnType<NonNullable<PhysicsWorld['admitDerivedShapeCandidate']>> {
+    const admitted = this.admitDerivedShapeCandidateInternal(candidate);
+    if (admitted.ok && commitGeometry !== undefined) {
+      const record = this.derivedCandidates.get(candidate.candidateId);
+      if (record !== undefined) record.commitGeometry = commitGeometry;
+    }
+    return admitted;
+  }
+
+  getDerivedAdmission(
+    entity?: number,
+  ):
+    | { readonly entity: number; readonly revision: number; readonly fixedStep: number }
+    | undefined {
+    const record = this.activeDerivedAdmission;
+    if (record === undefined || (entity !== undefined && record.input.entity !== entity))
+      return undefined;
+    return {
+      entity: record.input.entity,
+      revision: record.input.revision,
+      fixedStep: this.syncState?.world.getResource(FixedTime).tick ?? this.fixedStep + 1,
+    };
+  }
+
+  private admitDerivedShapeCandidateInternal(
+    candidate: DerivedPhysicsCandidate,
+    sourceOverrides?: ReadonlyMap<number, DerivedBodySource>,
+  ): ReturnType<NonNullable<PhysicsWorld['admitDerivedShapeCandidate']>> {
+    this.assertActive('admitDerivedShapeCandidate');
+    const record = this.derivedCandidates.get(candidate.candidateId);
+    if (
+      record === undefined ||
+      candidate.owner !== this.physicsOwner ||
+      record.token.owner !== candidate.owner ||
+      candidate.generation !== this.backendGeneration
+    ) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-not-found',
+          'candidate belongs to the current PhysicsWorld generation',
+          'discard stale candidate credentials and prepare from committed input again',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    if (this.derivedPoisonedEntities.has(record?.input.entity ?? -1)) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-recovery-invalid',
+          'the candidate entity is stopped after an unrecoverable native admission failure',
+          'rebuild the PhysicsWorld from its portable snapshot before retrying',
+          { entity: record?.input.entity, candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    if (record.state === 'cancelled' || record.state === 'invalidated') {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-cancelled',
+          'candidate has not been cancelled or invalidated',
+          'prepare a new candidate from the latest committed revision',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    if (record.state !== 'ready') {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-pending',
+          'a prepared candidate is admitted at most once',
+          'retain the returned queued receipt and wait for fixed-step publication',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    const pendingSources = this.pendingDerivedSources();
+    if (sourceOverrides !== undefined) {
+      for (const [entity, source] of sourceOverrides) pendingSources.set(entity, source);
+    }
+    pendingSources.set(record.input.entity, {
+      sourceKey: record.input.sourceKey,
+      revision: record.input.revision,
+    });
+    const admissionError = this.validateDerivedAdmission(record.input, pendingSources);
+    if (admissionError !== undefined) {
+      this.rejectPreparedCandidate(record, admissionError);
+      return err(admissionError);
+    }
+    const active = this.derivedBodies.get(record.input.entity);
+    if (active !== undefined && record.input.revision <= active.revision) {
+      const stale = new DerivedPhysicsError(
+        'derived-candidate-stale',
+        'candidate revision is newer than the committed shape revision',
+        'advance the consumer revision before admission',
+        { entity: record.input.entity, candidateId: candidate.candidateId },
+      );
+      this.rejectPreparedCandidate(record, stale);
+      return err(stale);
+    }
+    const newestPendingRevision = this.newestPendingRevision(record.input.entity);
+    if (newestPendingRevision !== undefined && record.input.revision <= newestPendingRevision) {
+      const stale = new DerivedPhysicsError(
+        'derived-candidate-stale',
+        'candidate revision advances every already queued revision for the body',
+        'admit only the newest body revision at a fixed-step boundary',
+        {
+          entity: record.input.entity,
+          candidateId: candidate.candidateId,
+          expected: `>${newestPendingRevision}`,
+          actual: record.input.revision,
+        },
+      );
+      this.rejectPreparedCandidate(record, stale);
+      return err(stale);
+    }
+    record.state = 'queued';
+    this.pendingDerivedCandidates.add(candidate.candidateId);
+    const queued = Object.freeze({ ...record.token, state: 'queued' as const });
+    record.token = queued;
+    // Revalidate the complete queued dependency projection after every
+    // admission.  A dependent candidate may have been queued before a newer
+    // endpoint revision arrived; allowing it to survive until process() would
+    // make the result depend on queue order and could silently bind the old
+    // endpoint source.
+    let changed = true;
+    while (changed) {
+      changed = false;
+      const projectedSources = new Map(sourceOverrides ?? []);
+      for (const [entity, source] of this.pendingDerivedSources()) {
+        const current = projectedSources.get(entity);
+        if (current === undefined || source.revision > current.revision)
+          projectedSources.set(entity, source);
+      }
+      for (const queuedId of [...this.pendingDerivedCandidates]) {
+        const queuedRecord = this.derivedCandidates.get(queuedId);
+        if (queuedRecord?.state !== 'queued') continue;
+        const projected = projectedSources.get(queuedRecord.input.entity);
+        const staleRevision =
+          projected !== undefined && queuedRecord.input.revision < projected.revision;
+        const dependencyError = staleRevision
+          ? new DerivedPhysicsError(
+              'derived-candidate-stale',
+              'queued candidates publish only the final revision submitted for an entity',
+              'discard the older queued candidate and submit one complete revision',
+              {
+                entity: queuedRecord.input.entity,
+                candidateId: queuedRecord.token.candidateId,
+                expected: `>=${projected.revision}`,
+                actual: queuedRecord.input.revision,
+              },
+            )
+          : this.validateDerivedAdmission(queuedRecord.input, projectedSources);
+        if (dependencyError === undefined) continue;
+        this.rejectPreparedCandidate(queuedRecord, dependencyError);
+        changed = true;
+        if (queuedId === candidate.candidateId) return err(dependencyError);
+      }
+    }
+    return ok(queued);
+  }
+
+  /** Cancel candidate-native resources; the committed state remains untouched. */
+  cancelDerivedShapeCandidate(
+    candidate: DerivedPhysicsCandidate,
+  ): ReturnType<NonNullable<PhysicsWorld['cancelDerivedShapeCandidate']>> {
+    this.assertActive('cancelDerivedShapeCandidate');
+    const record = this.derivedCandidates.get(candidate.candidateId);
+    if (record === undefined || candidate.owner !== this.physicsOwner) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-not-found',
+          'candidate belongs to the current PhysicsWorld',
+          'ignore already-retired credentials and prepare again when needed',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    if (record.state === 'published') {
+      return err(
+        new DerivedPhysicsError(
+          'derived-candidate-cancelled',
+          'a published candidate remains the committed result until replaced',
+          'submit a newer candidate instead of cancelling committed state',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    }
+    this.pendingDerivedCandidates.delete(candidate.candidateId);
+    for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
+    record.state = 'cancelled';
+    this.releaseDerivedCandidate(candidate.candidateId);
+    return ok(undefined);
+  }
+
+  /** Reject all in-flight derived work while preserving the last publication. */
+  invalidateDerivedShapeCandidates(reason = 'consumer-invalidated'): void {
+    const committedCandidateIds = new Set(
+      [...this.derivedBodies.values()].map((body) => body.candidateId),
+    );
+    for (const [id, record] of this.derivedCandidates) {
+      if (record.state === 'published' || committedCandidateIds.has(id)) continue;
+      record.state = 'invalidated';
+      for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
+      this.releaseDerivedCandidate(id);
+    }
+    this.pendingDerivedCandidates.clear();
+    void reason;
+  }
+
+  getDerivedPublication(entity: number): DerivedPhysicsPublication | undefined {
+    this.assertActive('getDerivedPublication');
+    if (this.recoveryBlocked()) return undefined;
+    const publication = this.derivedPublications.get(entity);
+    return publication === undefined
+      ? undefined
+      : { ...publication, shapeIds: [...publication.shapeIds] };
+  }
+
+  getDerivedFailure(entity: number): DerivedPhysicsFailure | undefined {
+    const failure = this.derivedFailures.get(entity);
+    return failure === undefined ? undefined : { ...failure };
+  }
+
+  getDerivedBodyType(entity: number): 'static' | 'dynamic' | 'kinematic' | undefined {
+    this.assertActive('getDerivedBodyType');
+    if (this.recoveryBlocked()) return undefined;
+    const body = this.bodyForEntity(entity);
+    if (body === undefined) return undefined;
+    return rapierBodyTypeToString(this.rapierModule, body.bodyType());
+  }
+
+  getDerivedBodyMass(entity: number): number | undefined {
+    this.assertActive('getDerivedBodyMass');
+    if (this.recoveryBlocked()) return undefined;
+    const body = this.bodyForEntity(entity);
+    return body === undefined ? undefined : body.mass();
+  }
+
+  getDerivedMotion(entity: number): DerivedPhysicsMotion | undefined {
+    this.assertActive('getDerivedMotion');
+    if (this.recoveryBlocked() || !this.derivedBodies.has(entity)) return undefined;
+    const body = this.bodyForEntity(entity);
+    if (body === undefined) return undefined;
+    const com = body.worldCom();
+    const linear = body.linvel();
+    const angular = body.angvel();
+    return Object.freeze({
+      centerOfMass: [com.x, com.y, com.z] as PhysicsVector,
+      linearVelocity: [linear.x, linear.y, linear.z] as PhysicsVector,
+      angularVelocity: [angular.x, angular.y, angular.z] as PhysicsVector,
+    });
+  }
+
+  getDerivedRecoveryState(): 'ready' | 'rebuild-required' {
+    return this.recoveryBlocked() ? 'rebuild-required' : 'ready';
+  }
+
+  getDerivedShapes(entity: number): readonly DerivedShapeState[] {
+    this.assertActive('getDerivedShapes');
+    if (this.recoveryBlocked()) return [];
+    const body = this.derivedBodies.get(entity);
+    if (body === undefined) return [];
+    return body.shapes.map((shape) => ({
+      id: shape.input.id,
+      revision: shape.input.revision,
+      entity,
+      voxelSize: [...shape.input.voxelSize] as PhysicsVector,
+      origin: [...shape.input.origin] as PhysicsVector,
+      rotation: [...shape.input.rotation] as PhysicsQuaternion,
+      generation: body.generation,
+    }));
+  }
+
+  captureDerivedPhysicsState(): DerivedPhysicsSnapshot {
+    this.assertActive('captureDerivedPhysicsState');
+    return Object.freeze({
+      generation: this.backendGeneration,
+      fixedStep: this.fixedStep,
+      bodies: Object.freeze(
+        [...this.derivedBodies.values()].map((body) => ({
+          entity: body.entity,
+          revision: body.revision,
+          sourceKey: body.sourceKey,
+          ...(body.bodyType === undefined ? {} : { bodyType: body.bodyType }),
+          ...(body.velocityPolicy === undefined ? {} : { velocityPolicy: body.velocityPolicy }),
+          shapes: Object.freeze(
+            body.shapes.map((shape) => ({
+              ...shape.input,
+              cells: new Int32Array(shape.input.cells),
+              voxelSize: [...shape.input.voxelSize] as PhysicsVector,
+              origin: [...shape.input.origin] as PhysicsVector,
+              rotation: [...shape.input.rotation] as PhysicsQuaternion,
+            })),
+          ),
+          seams: Object.freeze(
+            body.seams.map((seam) => ({ ...seam, offset: [...seam.offset] as PhysicsVector })),
+          ),
+          ...(body.massProperties === undefined ? {} : { massProperties: body.massProperties }),
+          ...(() => {
+            const motion = this.getDerivedMotion(body.entity);
+            return motion === undefined ? {} : { motion };
+          })(),
+          constraints: Object.freeze(this.constraintsForBody(body.entity)),
+        })),
+      ),
+    });
+  }
+
+  restoreDerivedPhysicsState(
+    snapshot: DerivedPhysicsSnapshot,
+  ): ReturnType<NonNullable<PhysicsWorld['restoreDerivedPhysicsState']>> {
+    this.assertActive('restoreDerivedPhysicsState');
+    const snapshotSources = new Map<number, DerivedBodySource>();
+    for (const body of snapshot.bodies) {
+      if (snapshotSources.has(body.entity)) {
+        return err(
+          new DerivedPhysicsError(
+            'derived-candidate-invalid',
+            'a portable snapshot contains one committed body row per entity',
+            'capture the snapshot from one PhysicsWorld without duplicate entities',
+            { entity: body.entity },
+          ),
+        );
+      }
+      snapshotSources.set(body.entity, {
+        sourceKey: body.sourceKey,
+        revision: body.revision,
+      });
+    }
+    const preparedCandidates: DerivedPhysicsCandidate[] = [];
+    const restoredConstraintIds = new Set<string>();
+    for (const body of snapshot.bodies) {
+      const prepared = this.prepareDerivedShapeCandidate({
+        entity: body.entity,
+        revision: body.revision,
+        sourceKey: body.sourceKey,
+        shapes: body.shapes,
+        ...(body.seams === undefined || body.seams.length === 0 ? {} : { seams: body.seams }),
+        ...(body.bodyType === undefined ? {} : { bodyType: body.bodyType }),
+        ...(body.velocityPolicy === undefined ? {} : { velocityPolicy: body.velocityPolicy }),
+        ...(body.motion === undefined ? {} : { motion: body.motion }),
+        ...(body.massProperties === undefined ? {} : { massProperties: body.massProperties }),
+        constraints: body.constraints.filter((constraint) => {
+          if (restoredConstraintIds.has(constraint.id)) return false;
+          restoredConstraintIds.add(constraint.id);
+          return true;
+        }),
+      });
+      if (!prepared.ok) {
+        for (const candidate of preparedCandidates) this.cancelDerivedShapeCandidate(candidate);
+        return prepared;
+      }
+      preparedCandidates.push(prepared.value);
+    }
+    const candidates: DerivedPhysicsCandidate[] = [];
+    for (const prepared of preparedCandidates) {
+      const admitted = this.admitDerivedShapeCandidateInternal(prepared, snapshotSources);
+      if (!admitted.ok) {
+        // Admission may have created disabled native colliders before a later
+        // body/constraint row fails.  Cancel every prepared credential, not
+        // only rows that reached the local `candidates` list: the rejected
+        // row and any rows after it also own native staging state.
+        for (const candidate of preparedCandidates) this.cancelDerivedShapeCandidate(candidate);
+        return admitted;
+      }
+      candidates.push(admitted.value);
+    }
+    return ok(candidates);
+  }
+
+  createDerivedConstraint(
+    input: PhysicsConstraintInput,
+  ): ReturnType<NonNullable<PhysicsWorld['createDerivedConstraint']>> {
+    return this.installDerivedConstraint(input, false);
+  }
+
+  updateDerivedConstraint(
+    input: PhysicsConstraintInput,
+  ): ReturnType<NonNullable<PhysicsWorld['updateDerivedConstraint']>> {
+    return this.installDerivedConstraint(input, true);
+  }
+
+  removeDerivedConstraint(
+    id: string,
+  ): ReturnType<NonNullable<PhysicsWorld['removeDerivedConstraint']>> {
+    this.assertActive('removeDerivedConstraint');
+    const existing = this.derivedConstraints.get(id);
+    if (existing === undefined) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-constraint-not-found',
+          'constraint identity is currently committed',
+          'ignore repeated cleanup or reconcile the owning constraint set',
+          { constraintId: id },
+        ),
+      );
+    }
+    this.removeNativeConstraint(existing.handle);
+    this.derivedConstraints.delete(id);
+    return ok(undefined);
+  }
+
+  private createDerivedCollider(
+    body: RapierRigidBody,
+    shape: VoxelShapeInput,
+  ): { readonly handle: number } {
+    const RAPIER = this.rapierModule as RapierWorld;
+    const desc = RAPIER.ColliderDesc.voxels(
+      shape.cells instanceof Int32Array
+        ? new Int32Array(shape.cells)
+        : new Int32Array(shape.cells.flat()),
+      { x: shape.voxelSize[0], y: shape.voxelSize[1], z: shape.voxelSize[2] },
+    )
+      .setTranslation(shape.origin?.[0] ?? 0, shape.origin?.[1] ?? 0, shape.origin?.[2] ?? 0)
+      .setRotation({
+        x: shape.rotation?.[0] ?? 0,
+        y: shape.rotation?.[1] ?? 0,
+        z: shape.rotation?.[2] ?? 0,
+        w: shape.rotation?.[3] ?? 1,
+      })
+      .setFriction(shape.friction ?? 0.5)
+      .setRestitution(shape.restitution ?? 0)
+      // Disabled colliders still contribute native mass. Staging must be
+      // massless; admission assigns density only to its committed shape set.
+      .setDensity(0)
+      .setCollisionGroups(shape.collisionGroups ?? 0xffffffff)
+      .setSolverGroups(shape.solverGroups ?? 0xffffffff)
+      .setActiveEvents(RAPIER.ActiveEvents.COLLISION_EVENTS)
+      .setActiveCollisionTypes(RAPIER.ActiveCollisionTypes.ALL)
+      .setEnabled(false);
+    if (shape.isSensor === true) desc.setSensor(true);
+    const collider = this.raw.createCollider(desc, body);
+    this.derivedColliderToShape.set(collider.handle, { entity: body.userData, id: shape.id });
+    return collider;
+  }
+
+  private removeNativeCollider(handle: number): void {
+    this.derivedColliderToShape.delete(handle);
+    try {
+      const collider = (this.raw as RapierWorld).getCollider(handle);
+      if (collider !== null && collider !== undefined) {
+        (this.raw as RapierWorld).removeCollider(collider, false);
+      }
+    } catch {
+      // Native removal is idempotent from the Engine lifecycle perspective.
+    }
+  }
+
+  private createNativeConstraint(
+    input: PhysicsConstraintInput,
+  ): Result<{ readonly handle: number }, DerivedPhysicsError> {
+    let native: RapierWorld | undefined;
+    try {
+      const RAPIER = this.rapierModule as RapierWorld;
+      const bodyA = this.bodyForEntity(input.bodyA);
+      const bodyB = this.bodyForEntity(input.bodyB);
+      if (bodyA === undefined || bodyB === undefined) {
+        return err(
+          new DerivedPhysicsError(
+            'derived-body-not-found',
+            'both constraint endpoints have committed bodies in this PhysicsWorld',
+            'reconcile both entities before creating the constraint',
+            { constraintId: input.id },
+          ),
+        );
+      }
+      const anchorA = { x: input.anchorA[0], y: input.anchorA[1], z: input.anchorA[2] };
+      const anchorB = { x: input.anchorB[0], y: input.anchorB[1], z: input.anchorB[2] };
+      const jointData =
+        input.kind === 'spring'
+          ? RAPIER.JointData.spring(
+              input.restLength,
+              input.stiffness,
+              input.damping,
+              anchorA,
+              anchorB,
+            )
+          : RAPIER.JointData.revolute(anchorA, anchorB, {
+              x: input.axis[0],
+              y: input.axis[1],
+              z: input.axis[2],
+            });
+      native = this.raw.createImpulseJoint(jointData, bodyA, bodyB, true);
+      if (input.kind === 'hinge' && input.limits !== undefined)
+        native.setLimits(input.limits[0], input.limits[1]);
+      return ok({ handle: native.handle });
+    } catch (cause) {
+      if (native !== undefined) this.removeNativeConstraint(native.handle);
+      return err(
+        new DerivedPhysicsError(
+          'derived-backend-failed',
+          'the selected Rapier joint can be created for both endpoint bodies',
+          'repair endpoint state or use a supported spring/hinge input',
+          {
+            constraintId: input.id,
+            reason: cause instanceof Error ? cause.message : String(cause),
+          },
+        ),
+      );
+    }
+  }
+
+  private rememberDerivedFailure(
+    record: DerivedCandidateRecord,
+    error: DerivedPhysicsError,
+    recovery: DerivedPhysicsFailure['recovery'],
+  ): void {
+    record.state = 'failed';
+    this.pendingDerivedCandidates.delete(record.token.candidateId);
+    this.derivedFailures.set(
+      record.input.entity,
+      Object.freeze({
+        candidateId: record.token.candidateId,
+        entity: record.input.entity,
+        revision: record.input.revision,
+        fixedStep: this.fixedStep,
+        error,
+        recovery,
+      }),
+    );
+    this.releaseDerivedCandidate(record.token.candidateId);
+  }
+
+  private rejectPreparedCandidate(
+    record: DerivedCandidateRecord,
+    error: DerivedPhysicsError,
+  ): void {
+    for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
+    this.rememberDerivedFailure(record, error, 'old-state-retained');
+  }
+
+  private processDerivedCandidates(): void {
+    if (this.pendingDerivedCandidates.size === 0) return;
+    const pendingRecords = [...this.pendingDerivedCandidates]
+      .map((id) => this.derivedCandidates.get(id))
+      .filter((record): record is DerivedCandidateRecord => record?.state === 'queued');
+    const pendingByEntity = new Map<number, DerivedCandidateRecord>();
+    for (const record of pendingRecords) {
+      const current = pendingByEntity.get(record.input.entity);
+      if (current === undefined || record.input.revision > current.input.revision) {
+        pendingByEntity.set(record.input.entity, record);
+      }
+    }
+    // A candidate that names a queued endpoint must be processed after that
+    // endpoint. This turns a queue-time source projection into a final
+    // committed-source check: if the endpoint fails natively, its dependent
+    // candidate sees the old source on the next iteration and is rejected.
+    const ordered: DerivedCandidateRecord[] = [];
+    const visiting = new Set<string>();
+    const visited = new Set<string>();
+    const visit = (record: DerivedCandidateRecord): void => {
+      if (visited.has(record.token.candidateId)) return;
+      if (visiting.has(record.token.candidateId)) return;
+      visiting.add(record.token.candidateId);
+      for (const constraint of record.input.constraints ?? []) {
+        for (const endpoint of [
+          [constraint.bodyA, constraint.bodyASource],
+          [constraint.bodyB, constraint.bodyBSource],
+        ] as const) {
+          const dependency = endpoint[1];
+          const target = pendingByEntity.get(endpoint[0]);
+          if (
+            target !== undefined &&
+            target.input.sourceKey === dependency.sourceKey &&
+            target.input.revision === dependency.revision
+          ) {
+            visit(target);
+          }
+        }
+      }
+      visiting.delete(record.token.candidateId);
+      visited.add(record.token.candidateId);
+      ordered.push(record);
+    };
+    for (const record of pendingRecords) visit(record);
+
+    for (const record of ordered) {
+      const id = record.token.candidateId;
+      if (!this.pendingDerivedCandidates.has(id) || record.state !== 'queued') continue;
+      const pendingSources = this.pendingDerivedSources();
+      const projected = pendingSources.get(record.input.entity);
+      if (projected !== undefined && record.input.revision < projected.revision) {
+        this.rejectPreparedCandidate(
+          record,
+          new DerivedPhysicsError(
+            'derived-candidate-stale',
+            'fixed-step admission publishes only the newest queued body revision',
+            'discard the older queued candidate and submit the latest complete input',
+            {
+              entity: record.input.entity,
+              candidateId: record.token.candidateId,
+              expected: `>=${projected.revision}`,
+              actual: record.input.revision,
+            },
+          ),
+        );
+        continue;
+      }
+      const admissionError = this.validateDerivedAdmission(record.input, pendingSources);
+      if (admissionError !== undefined) {
+        this.rejectPreparedCandidate(record, admissionError);
+        continue;
+      }
+      const old = this.derivedBodies.get(record.input.entity);
+      if (this.derivedPoisonedEntities.has(record.input.entity)) {
+        for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
+        this.rememberDerivedFailure(
+          record,
+          new DerivedPhysicsError(
+            'derived-recovery-invalid',
+            'the entity is stopped after an unrecoverable native admission failure',
+            'rebuild the PhysicsWorld from the last portable snapshot before retrying',
+            { entity: record.input.entity, candidateId: record.token.candidateId },
+          ),
+          'rebuild-required',
+        );
+        continue;
+      }
+      const body = this.bodyForEntity(record.input.entity);
+      if (body === undefined) {
+        for (const collider of record.nativeColliders) this.removeNativeCollider(collider.handle);
+        this.rememberDerivedFailure(
+          record,
+          new DerivedPhysicsError(
+            'derived-body-not-found',
+            'candidate entity remains a live native body at fixed-step admission',
+            'reconcile the entity and submit a fresh candidate',
+            { entity: record.input.entity, candidateId: record.token.candidateId },
+          ),
+          'old-state-retained',
+        );
+        continue;
+      }
+      const oldBodyType = body.bodyType();
+      const oldBodyEnabled = body.isEnabled();
+      const oldVelocity = body.linvel();
+      const oldAngularVelocity = body.angvel();
+      const oldTranslation = body.translation();
+      const oldRotation = body.rotation();
+      const oldCom = body.worldCom();
+      const oldMass = body.mass();
+      const oldAutomaticAdditionalMass =
+        this.entityMap.get(record.input.entity)?.automaticAdditionalMass ?? 0;
+      const oldAutomaticRecordMass = this.entityMap.get(
+        record.input.entity,
+      )?.automaticAdditionalMass;
+      const oldSource = this.derivedBodySources.get(record.input.entity);
+      const oldPublication = this.derivedPublications.get(record.input.entity);
+      const oldDensities = this.bodyColliders(body).map((collider) => ({
+        collider,
+        density: typeof collider.density === 'function' ? collider.density() : undefined,
+        enabled: typeof collider.isEnabled === 'function' ? collider.isEnabled() : true,
+      }));
+      const oldConstraints = new Map(this.derivedConstraints);
+      const stagedConstraints = new Map<string, DerivedConstraintRecord>();
+      let geometryCommitUncertain = false;
+      try {
+        for (const constraint of record.input.constraints ?? []) {
+          const created = this.createNativeConstraint(constraint);
+          if (!created.ok) throw created.error;
+          stagedConstraints.set(constraint.id, {
+            input: { ...constraint },
+            handle: created.value.handle,
+          });
+        }
+        if (record.input.bodyType !== undefined) {
+          const RAPIER = this.rapierModule as RapierWorld;
+          const bodyType =
+            record.input.bodyType === 'static'
+              ? RAPIER.RigidBodyType.Fixed
+              : record.input.bodyType === 'kinematic'
+                ? RAPIER.RigidBodyType.KinematicPositionBased
+                : RAPIER.RigidBodyType.Dynamic;
+          body.setBodyType(bodyType, true);
+        }
+        for (const native of record.nativeColliders) {
+          const collider = (this.raw as RapierWorld).getCollider(native.handle);
+          if (collider === null || collider === undefined)
+            throw new Error('candidate collider disappeared');
+          collider.setEnabled(true);
+        }
+        const nativeById = new Map(
+          record.input.shapes.map((shape: VoxelShapeInput, index: number) => [
+            shape.id,
+            record.nativeColliders[index]?.handle as number,
+          ]),
+        );
+        for (const seam of record.input.seams ?? []) {
+          const firstHandle = nativeById.get(seam.shapeA);
+          const secondHandle = nativeById.get(seam.shapeB);
+          const first =
+            firstHandle === undefined
+              ? undefined
+              : (this.raw as RapierWorld).getCollider(firstHandle);
+          const second =
+            secondHandle === undefined
+              ? undefined
+              : (this.raw as RapierWorld).getCollider(secondHandle);
+          if (first === undefined || second === undefined || first === null || second === null) {
+            throw new Error(`derived seam references missing shape ${seam.shapeA}`);
+          }
+          first.combineVoxelStates(second, seam.offset[0], seam.offset[1], seam.offset[2]);
+        }
+        this.applyDerivedMass(
+          body,
+          record.input.massProperties,
+          oldCom,
+          record.input.velocityPolicy ?? 'preserve',
+          this.entityMap.get(record.input.entity)?.additionalMass ?? 0,
+          record.input.entity,
+          record.input.shapes,
+          record.nativeColliders,
+        );
+        if (record.input.motion !== undefined) {
+          const currentCom = body.worldCom();
+          const targetCom = record.input.motion.centerOfMass;
+          const translation = body.translation();
+          body.setTranslation(
+            {
+              x: translation.x + targetCom[0] - currentCom.x,
+              y: translation.y + targetCom[1] - currentCom.y,
+              z: translation.z + targetCom[2] - currentCom.z,
+            },
+            true,
+          );
+          body.setLinvel(
+            {
+              x: record.input.motion.linearVelocity[0],
+              y: record.input.motion.linearVelocity[1],
+              z: record.input.motion.linearVelocity[2],
+            },
+            true,
+          );
+          body.setAngvel(
+            {
+              x: record.input.motion.angularVelocity[0],
+              y: record.input.motion.angularVelocity[1],
+              z: record.input.motion.angularVelocity[2],
+            },
+            true,
+          );
+        }
+        // A body revision invalidates any committed joint that still names
+        // that body's previous source/revision. Keep this tied to the body
+        // that is actually committing: a different queued endpoint may still
+        // fail, in which case its old joint remains valid and must not be
+        // removed speculatively.
+        const committedSources = new Map(this.derivedBodySources);
+        committedSources.set(record.input.entity, {
+          sourceKey: record.input.sourceKey,
+          revision: record.input.revision,
+        });
+        const replacementConstraintIds = new Set(
+          (record.input.constraints ?? []).map((constraint) => constraint.id),
+        );
+        for (const [constraintId, current] of [...this.derivedConstraints]) {
+          if (
+            replacementConstraintIds.has(constraintId) ||
+            this.constraintDependenciesMatch(current.input, committedSources)
+          )
+            continue;
+          this.removeNativeConstraint(current.handle);
+          this.derivedConstraints.delete(constraintId);
+        }
+        if (old !== undefined) {
+          for (const shape of old.shapes) {
+            const collider = (this.raw as RapierWorld).getCollider(shape.colliderHandle);
+            if (collider !== null && collider !== undefined) collider.setEnabled(false);
+          }
+          this.retiredDerivedBodies.push(old);
+        }
+        for (const constraint of record.input.constraints ?? []) {
+          const previous = this.derivedConstraints.get(constraint.id);
+          if (previous !== undefined) this.removeNativeConstraint(previous.handle);
+          const staged = stagedConstraints.get(constraint.id);
+          if (staged !== undefined) this.derivedConstraints.set(constraint.id, staged);
+        }
+        const shapes: DerivedShapeRecord[] = record.input.shapes.map(
+          (shape: VoxelShapeInput, index: number) => ({
+            input: shape as DerivedShapeRecord['input'],
+            colliderHandle: record.nativeColliders[index]?.handle as number,
+          }),
+        );
+        const committed: DerivedBodyRecord = {
+          entity: record.input.entity,
+          sourceKey: record.input.sourceKey,
+          generation: this.backendGeneration,
+          revision: record.input.revision,
+          bodyType: record.input.bodyType,
+          velocityPolicy: record.input.velocityPolicy,
+          candidateId: record.token.candidateId,
+          shapes,
+          seams: [...(record.input.seams ?? [])],
+          massProperties: record.input.massProperties,
+          constraints: [...(record.input.constraints ?? [])],
+        };
+        // The sole cross-domain observation boundary: no native operation
+        // follows a successful geometry commit before recording this body.
+        // A refused commit takes the same complete native rollback below.
+        if (record.commitGeometry !== undefined) {
+          this.activeDerivedAdmission = record;
+          try {
+            geometryCommitUncertain = true;
+            const geometry = record.commitGeometry();
+            geometryCommitUncertain = false;
+            if (!geometry.ok) throw geometry.error;
+          } finally {
+            this.activeDerivedAdmission = undefined;
+          }
+          delete record.commitGeometry;
+        }
+        this.derivedBodies.set(record.input.entity, committed);
+        const entityRecord = this.entityMap.get(record.input.entity);
+        if (entityRecord !== undefined) {
+          entityRecord.automaticAdditionalMass =
+            record.input.massProperties?.mode === 'explicit' ? 0 : entityRecord.additionalMass;
+        }
+        this.derivedBodySources.set(record.input.entity, {
+          sourceKey: record.input.sourceKey,
+          revision: record.input.revision,
+        });
+        this.derivedFailures.delete(record.input.entity);
+        record.state = 'queued';
+        this.pendingDerivedCandidates.delete(id);
+      } catch (cause) {
+        for (const staged of stagedConstraints.values()) this.removeNativeConstraint(staged.handle);
+        // The commit path may already have removed/replaced a native joint
+        // before a later body mutation fails. Clear every current native joint
+        // now; the old records are recreated after the body state is restored
+        // instead of leaving a stale JS handle that no longer exists in
+        // Rapier.
+        for (const current of this.derivedConstraints.values())
+          this.removeNativeConstraint(current.handle);
+        this.derivedConstraints.clear();
+        if (old !== undefined) {
+          for (const shape of old.shapes) {
+            const collider = (this.raw as RapierWorld).getCollider(shape.colliderHandle);
+            if (collider !== null && collider !== undefined) collider.setEnabled(true);
+          }
+          const retiredIndex = this.retiredDerivedBodies.indexOf(old);
+          if (retiredIndex >= 0) this.retiredDerivedBodies.splice(retiredIndex, 1);
+          this.derivedBodies.set(record.input.entity, old);
+          this.derivedBodySources.set(record.input.entity, {
+            sourceKey: old.sourceKey,
+            revision: old.revision,
+          });
+        }
+        for (const native of record.nativeColliders) {
+          const collider = (this.raw as RapierWorld).getCollider(native.handle);
+          if (collider !== null && collider !== undefined) collider.setEnabled(false);
+        }
+        // Remove staged colliders before restoring mass. Rapier defers some
+        // mass-property recomputation until a collider mutation; restoring
+        // while a disabled candidate is still attached can leave an explicit
+        // override behind for the next fixed step.
+        for (const native of record.nativeColliders) this.removeNativeCollider(native.handle);
+        for (const { collider, density, enabled } of oldDensities) {
+          if (this.raw.getCollider(collider.handle) === null) continue;
+          if (density !== undefined && typeof collider.setDensity === 'function')
+            collider.setDensity(density);
+          if (typeof collider.setEnabled === 'function') collider.setEnabled(enabled);
+        }
+        let restored = true;
+        try {
+          body.setBodyType(oldBodyType, true);
+          this.restoreCommittedMass(body, old, oldAutomaticAdditionalMass);
+          body.setTranslation(oldTranslation, true);
+          body.setRotation(oldRotation, true);
+          body.setLinvel(oldVelocity, true);
+          body.setAngvel(oldAngularVelocity, true);
+          body.setEnabled(oldBodyEnabled);
+        } catch {
+          restored = false;
+        }
+        if (restored && !this.restoreNativeConstraints(oldConstraints)) restored = false;
+        if (restored) {
+          const currentMass = body.mass();
+          const currentCom = body.worldCom();
+          const currentVelocity = body.linvel();
+          const currentAngularVelocity = body.angvel();
+          restored =
+            Number.isFinite(currentMass) &&
+            Math.abs(currentMass - oldMass) <= 1e-6 * Math.max(1, Math.abs(oldMass)) &&
+            Math.abs(currentCom.x - oldCom.x) <= 1e-6 &&
+            Math.abs(currentCom.y - oldCom.y) <= 1e-6 &&
+            Math.abs(currentCom.z - oldCom.z) <= 1e-6 &&
+            Math.abs(currentVelocity.x - oldVelocity.x) <= 1e-6 &&
+            Math.abs(currentVelocity.y - oldVelocity.y) <= 1e-6 &&
+            Math.abs(currentVelocity.z - oldVelocity.z) <= 1e-6 &&
+            Math.abs(currentAngularVelocity.x - oldAngularVelocity.x) <= 1e-6 &&
+            Math.abs(currentAngularVelocity.y - oldAngularVelocity.y) <= 1e-6 &&
+            Math.abs(currentAngularVelocity.z - oldAngularVelocity.z) <= 1e-6 &&
+            body.bodyType() === oldBodyType &&
+            body.isEnabled() === oldBodyEnabled;
+        }
+        if (old === undefined) this.derivedBodies.delete(record.input.entity);
+        else this.derivedBodies.set(record.input.entity, old);
+        if (oldSource === undefined) this.derivedBodySources.delete(record.input.entity);
+        else this.derivedBodySources.set(record.input.entity, oldSource);
+        if (oldPublication === undefined) this.derivedPublications.delete(record.input.entity);
+        else this.derivedPublications.set(record.input.entity, oldPublication);
+        const entityRecord = this.entityMap.get(record.input.entity);
+        if (entityRecord !== undefined && oldAutomaticRecordMass !== undefined)
+          entityRecord.automaticAdditionalMass = oldAutomaticRecordMass;
+        const error =
+          cause instanceof DerivedPhysicsError
+            ? cause
+            : new DerivedPhysicsError(
+                'derived-backend-failed',
+                'derived admission either commits completely or preserves the prior body state',
+                'inspect the failure receipt and rebuild the PhysicsWorld if recovery is required',
+                {
+                  entity: record.input.entity,
+                  candidateId: record.token.candidateId,
+                  reason: cause instanceof Error ? cause.message : String(cause),
+                },
+              );
+        // A thrown consumer callback may already have changed its ECS domain.
+        // Native rollback alone cannot certify the combined state in that case.
+        if (geometryCommitUncertain) restored = false;
+        if (!restored) {
+          this.derivedPoisonedEntities.add(record.input.entity);
+          this.derivedBodies.delete(record.input.entity);
+          this.derivedPublications.delete(record.input.entity);
+        }
+        this.rememberDerivedFailure(
+          record,
+          error,
+          restored ? 'old-state-retained' : 'rebuild-required',
+        );
+      }
+    }
+  }
+
+  private publishDerivedCandidates(): void {
+    for (const body of this.derivedBodies.values()) {
+      const candidate = this.derivedCandidates.get(body.candidateId);
+      if (candidate?.state !== 'queued') continue;
+      this.derivedPublications.set(
+        body.entity,
+        Object.freeze({
+          candidateId: body.candidateId,
+          entity: body.entity,
+          revision: body.revision,
+          fixedStep: this.fixedStep,
+          shapeIds: Object.freeze(body.shapes.map((shape) => shape.input.id)),
+          generation: body.generation,
+        }),
+      );
+      candidate.state = 'published';
+    }
+  }
+
+  private retireDerivedBodies(): void {
+    for (const body of this.retiredDerivedBodies.splice(0)) {
+      for (const shape of body.shapes) this.removeNativeCollider(shape.colliderHandle);
+      this.releaseDerivedCandidate(body.candidateId);
+    }
+  }
+
+  private applyDerivedMass(
+    body: RapierRigidBody,
+    properties: PhysicsMassProperties | undefined,
+    previousWorldCom: { x: number; y: number; z: number },
+    velocityPolicy: 'preserve' | 'reset',
+    authoredAdditionalMass: number,
+    entity: number,
+    candidateShapes: readonly VoxelShapeInput[],
+    candidateColliders: readonly { readonly handle: number }[],
+  ): void {
+    const oldVelocity = body.linvel();
+    const oldAngularVelocity = body.angvel();
+    if (properties?.mode === 'explicit') {
+      // Explicit mass is the sole source for this body. Zero every ordinary
+      // and derived collider density first so Rapier does not add a hidden
+      // density contribution to the authored value.
+      this.rememberAuthoredDensity(entity, body);
+      for (const collider of this.bodyColliders(body)) {
+        if (typeof collider.setDensity === 'function') collider.setDensity(0);
+      }
+      const frame = properties.principalInertiaLocalFrame ?? [0, 0, 0, 1];
+      body.setAdditionalMassProperties(
+        properties.mass,
+        {
+          x: properties.centerOfMass[0],
+          y: properties.centerOfMass[1],
+          z: properties.centerOfMass[2],
+        },
+        {
+          x: properties.principalInertia[0],
+          y: properties.principalInertia[1],
+          z: properties.principalInertia[2],
+        },
+        { x: frame[0], y: frame[1], z: frame[2], w: frame[3] },
+        true,
+      );
+    } else {
+      this.restoreAutomaticDensities(
+        entity,
+        body,
+        properties?.mode === 'automatic' ? properties.density : undefined,
+        candidateShapes,
+        candidateColliders,
+      );
+      this.restoreAutomaticMass(body, authoredAdditionalMass);
+    }
+    if (velocityPolicy === 'reset') {
+      body.setLinvel({ x: 0, y: 0, z: 0 }, true);
+      body.setAngvel({ x: 0, y: 0, z: 0 }, true);
+      return;
+    }
+    const nextWorldCom = body.worldCom();
+    const next = preserveCenterOfMassVelocity(
+      [oldVelocity.x, oldVelocity.y, oldVelocity.z],
+      [oldAngularVelocity.x, oldAngularVelocity.y, oldAngularVelocity.z],
+      [previousWorldCom.x, previousWorldCom.y, previousWorldCom.z],
+      [nextWorldCom.x, nextWorldCom.y, nextWorldCom.z],
+    );
+    body.setLinvel({ x: next[0], y: next[1], z: next[2] }, true);
+    body.setAngvel(oldAngularVelocity, true);
+  }
+
+  /** Restore the complete committed mass policy after a failed admission. */
+  private restoreCommittedMass(
+    body: RapierRigidBody,
+    previous: DerivedBodyRecord | undefined,
+    automaticAdditionalMass: number,
+  ): void {
+    if (previous?.massProperties?.mode === 'explicit') {
+      const frame = previous.massProperties.principalInertiaLocalFrame ?? [0, 0, 0, 1];
+      body.setAdditionalMassProperties(
+        previous.massProperties.mass,
+        {
+          x: previous.massProperties.centerOfMass[0],
+          y: previous.massProperties.centerOfMass[1],
+          z: previous.massProperties.centerOfMass[2],
+        },
+        {
+          x: previous.massProperties.principalInertia[0],
+          y: previous.massProperties.principalInertia[1],
+          z: previous.massProperties.principalInertia[2],
+        },
+        { x: frame[0], y: frame[1], z: frame[2], w: frame[3] },
+        true,
+      );
+      return;
+    }
+    this.restoreAutomaticMass(body, automaticAdditionalMass);
+  }
+
+  /**
+   * Rapier keeps `setAdditionalMassProperties` as native state even after a
+   * collider recompute. Clear that override explicitly before recomputing so
+   * automatic candidates and rollback really return to the authored policy.
+   */
+  private restoreAutomaticMass(body: RapierRigidBody, additionalMass: number): void {
+    body.setAdditionalMass(Math.max(0, additionalMass), true);
+    body.recomputeMassPropertiesFromColliders();
+  }
+
+  private rememberAuthoredDensity(entity: number, body: RapierRigidBody): void {
+    const record = this.entityMap.get(entity);
+    if (record === undefined || record.authoredDensity !== undefined) return;
+    const authored = this.bodyColliders(body).find(
+      (collider) => !this.derivedColliderToShape.has(collider.handle),
+    );
+    const density =
+      authored !== undefined && typeof authored.density === 'function'
+        ? authored.density()
+        : undefined;
+    if (density !== undefined && Number.isFinite(density) && density >= 0)
+      record.authoredDensity = density;
+  }
+
+  private restoreAutomaticDensities(
+    entity: number,
+    body: RapierRigidBody,
+    overrideDensity: number | undefined,
+    candidateShapes: readonly VoxelShapeInput[],
+    candidateColliders: readonly { readonly handle: number }[],
+  ): void {
+    const record = this.entityMap.get(entity);
+    const candidateDensityByHandle = new Map<number, number>();
+    for (const [index, collider] of candidateColliders.entries()) {
+      const shape = candidateShapes[index];
+      if (shape !== undefined) candidateDensityByHandle.set(collider.handle, shape.density ?? 1);
+    }
+    const authoredDensity = record?.authoredDensity ?? 1;
+    for (const collider of this.bodyColliders(body)) {
+      const candidateDensity = candidateDensityByHandle.get(collider.handle);
+      const density =
+        candidateDensity !== undefined
+          ? (overrideDensity ?? candidateDensity)
+          : this.derivedColliderToShape.has(collider.handle)
+            ? 0
+            : (overrideDensity ?? authoredDensity);
+      if (typeof collider.setDensity === 'function') collider.setDensity(density);
+    }
+  }
+
+  private restoreNativeConstraints(
+    previous: ReadonlyMap<string, DerivedConstraintRecord>,
+  ): boolean {
+    for (const [constraintId, record] of previous) {
+      const recreated = this.createNativeConstraint(record.input);
+      if (!recreated.ok) {
+        for (const current of this.derivedConstraints.values())
+          this.removeNativeConstraint(current.handle);
+        this.derivedConstraints.clear();
+        return false;
+      }
+      this.derivedConstraints.set(constraintId, {
+        input: { ...record.input },
+        handle: recreated.value.handle,
+      });
+    }
+    return true;
+  }
+
+  private bodyColliders(body: RapierRigidBody): RapierWorld[] {
+    const result: RapierWorld[] = [];
+    for (let index = 0; index < body.numColliders(); index += 1) {
+      const collider = body.collider(index);
+      if (collider !== null && collider !== undefined) result.push(collider);
+    }
+    return result;
+  }
+
+  private releaseDerivedCandidate(candidateId: string): void {
+    const record = this.derivedCandidates.get(candidateId);
+    if (record === undefined) return;
+    this.derivedCandidateBytes = Math.max(0, this.derivedCandidateBytes - record.bytes);
+    this.derivedCandidates.delete(candidateId);
+  }
+
+  private sourceForEntity(entity: number): DerivedBodySource {
+    return (
+      this.derivedBodySources.get(entity) ?? {
+        sourceKey: `entity:${entity}`,
+        revision: 0,
+      }
+    );
+  }
+
+  /**
+   * Project the final source revision of every queued body. Constraint
+   * dependencies are checked against this projection, not against whichever
+   * queued candidate happens to be processed first.
+   */
+  private pendingDerivedSources(): Map<number, DerivedBodySource> {
+    const sources = new Map<number, DerivedBodySource>();
+    for (const candidateId of this.pendingDerivedCandidates) {
+      const record = this.derivedCandidates.get(candidateId);
+      if (record === undefined || record.state !== 'queued') continue;
+      const current = sources.get(record.input.entity);
+      if (current === undefined || record.input.revision > current.revision) {
+        sources.set(record.input.entity, {
+          sourceKey: record.input.sourceKey,
+          revision: record.input.revision,
+        });
+      }
+    }
+    return sources;
+  }
+
+  private newestPendingRevision(entity: number): number | undefined {
+    return this.pendingDerivedSources().get(entity)?.revision;
+  }
+
+  private recoveryBlocked(): boolean {
+    return (
+      this.derivedPoisonedEntities.size > 0 || this.syncState?.world.execution.health === 'poisoned'
+    );
+  }
+
+  private validateConstraintDependencies(
+    input: PhysicsConstraintInput,
+    candidate?: DerivedPhysicsCandidateInput,
+    sourceOverrides?: ReadonlyMap<number, DerivedBodySource>,
+  ): DerivedPhysicsError | undefined {
+    const endpoints = [
+      [input.bodyA, input.bodyASource],
+      [input.bodyB, input.bodyBSource],
+    ] as const;
+    for (const [entity, dependency] of endpoints) {
+      if (this.derivedPoisonedEntities.has(entity)) {
+        return new DerivedPhysicsError(
+          'derived-recovery-invalid',
+          'constraint endpoints belong to a healthy PhysicsWorld state',
+          'rebuild the PhysicsWorld before recreating constraints',
+          { constraintId: input.id, entity },
+        );
+      }
+      if (!this.entityMap.has(entity)) {
+        return new DerivedPhysicsError(
+          'derived-body-not-found',
+          'both constraint endpoint entities have committed bodies',
+          'reconcile both endpoint entities before creating or migrating a constraint',
+          { constraintId: input.id, entity },
+        );
+      }
+      const expected =
+        candidate !== undefined && entity === candidate.entity
+          ? { sourceKey: candidate.sourceKey, revision: candidate.revision }
+          : (sourceOverrides?.get(entity) ?? this.sourceForEntity(entity));
+      if (
+        dependency.sourceKey !== expected.sourceKey ||
+        dependency.revision !== expected.revision
+      ) {
+        return new DerivedPhysicsError(
+          'derived-constraint-stale',
+          'constraint endpoint sourceKey and revision match the committed endpoint',
+          'refresh both endpoint dependencies and retry the complete candidate',
+          {
+            constraintId: input.id,
+            entity,
+            expected: `${expected.sourceKey}@${expected.revision}`,
+            actual: `${dependency.sourceKey}@${dependency.revision}`,
+          },
+        );
+      }
+    }
+    return undefined;
+  }
+
+  private constraintDependenciesMatch(
+    input: PhysicsConstraintInput,
+    sourceOverrides: ReadonlyMap<number, DerivedBodySource>,
+  ): boolean {
+    for (const [entity, dependency] of [
+      [input.bodyA, input.bodyASource],
+      [input.bodyB, input.bodyBSource],
+    ] as const) {
+      if (!this.entityMap.has(entity)) return false;
+      const expected = sourceOverrides.get(entity) ?? this.sourceForEntity(entity);
+      if (dependency.sourceKey !== expected.sourceKey || dependency.revision !== expected.revision)
+        return false;
+    }
+    return true;
+  }
+
+  private validateDerivedAdmission(
+    input: DerivedPhysicsCandidateInput,
+    sourceOverrides?: ReadonlyMap<number, DerivedBodySource>,
+  ): DerivedPhysicsError | undefined {
+    if (
+      input.bodyType !== undefined &&
+      input.bodyType !== 'static' &&
+      input.bodyType !== 'dynamic' &&
+      input.bodyType !== 'kinematic'
+    ) {
+      return new DerivedPhysicsError(
+        'derived-candidate-invalid',
+        'candidate bodyType is one of static, dynamic, or kinematic',
+        'repair the motion type before admission',
+        { entity: input.entity, actual: input.bodyType },
+      );
+    }
+    const seen = new Set<string>();
+    for (const constraint of input.constraints ?? []) {
+      const validation = validateConstraintInput(constraint);
+      if (!validation.ok) return validation.error;
+      if (seen.has(constraint.id)) {
+        return new DerivedPhysicsError(
+          'derived-constraint-invalid',
+          'candidate contains one constraint update per identity',
+          'merge duplicate updates before admission',
+          { entity: input.entity, constraintId: constraint.id },
+        );
+      }
+      seen.add(constraint.id);
+      const dependencyError = this.validateConstraintDependencies(
+        constraint,
+        input,
+        sourceOverrides,
+      );
+      if (dependencyError !== undefined) return dependencyError;
+      const existing = this.derivedConstraints.get(constraint.id);
+      if (existing !== undefined && constraint.revision <= existing.input.revision) {
+        return new DerivedPhysicsError(
+          'derived-constraint-stale',
+          'migrated constraint revision advances the committed revision',
+          'submit both endpoint dependencies and a newer constraint revision',
+          {
+            entity: input.entity,
+            constraintId: constraint.id,
+            expected: `>${existing.input.revision}`,
+            actual: constraint.revision,
+          },
+        );
+      }
+    }
+    return undefined;
+  }
+
+  private constraintsForBody(entity: number): readonly PhysicsConstraintInput[] {
+    return [...this.derivedConstraints.values()]
+      .filter(
+        (constraint) => constraint.input.bodyA === entity || constraint.input.bodyB === entity,
+      )
+      .map((constraint) => ({ ...constraint.input }));
+  }
+
+  private installDerivedConstraint(
+    input: PhysicsConstraintInput,
+    updating: boolean,
+  ): ReturnType<NonNullable<PhysicsWorld['createDerivedConstraint']>> {
+    this.assertActive(updating ? 'updateDerivedConstraint' : 'createDerivedConstraint');
+    const validation = validateConstraintInput(input);
+    if (!validation.ok) return validation;
+    const dependencyError = this.validateConstraintDependencies(
+      input,
+      undefined,
+      this.pendingDerivedSources(),
+    );
+    if (dependencyError !== undefined) return err(dependencyError);
+    const existing = this.derivedConstraints.get(input.id);
+    if (existing !== undefined && !updating) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-constraint-stale',
+          'constraint identity is not already committed when creating it',
+          'call updateDerivedConstraint with a newer revision',
+          { constraintId: input.id },
+        ),
+      );
+    }
+    if (existing !== undefined && input.revision <= existing.input.revision) {
+      return err(
+        new DerivedPhysicsError(
+          'derived-constraint-stale',
+          'constraint revision advances monotonically',
+          'submit a newer constraint revision',
+          {
+            constraintId: input.id,
+            actual: input.revision,
+            expected: `>${existing.input.revision}`,
+          },
+        ),
+      );
+    }
+    const native = this.createNativeConstraint(input);
+    if (!native.ok) return native;
+    if (existing !== undefined) this.removeNativeConstraint(existing.handle);
+    this.derivedConstraints.set(input.id, { input: { ...input }, handle: native.value.handle });
+    return ok({ id: input.id, revision: input.revision });
+  }
+
+  private removeNativeConstraint(handle: number): void {
+    try {
+      const joint = (this.raw as RapierWorld).getImpulseJoint(handle);
+      if (joint !== null && joint !== undefined)
+        (this.raw as RapierWorld).removeImpulseJoint(joint, true);
+    } catch {
+      // Cleanup is idempotent across backend teardown and entity removal.
+    }
+  }
+
   getPendingTeleports(): readonly [
     number,
     { readonly x: number; readonly y: number; readonly z: number },
@@ -484,6 +2270,22 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
 
   dispose(): void {
     if (this.disposed) return;
+    this.assertActive('dispose');
+    this.invalidateDerivedShapeCandidates('physics-dispose');
+    this.derivedCandidates.clear();
+    this.pendingDerivedCandidates.clear();
+    this.derivedBodies.clear();
+    this.derivedBodySources.clear();
+    this.derivedPublications.clear();
+    this.derivedFailures.clear();
+    this.derivedConstraints.clear();
+    this.derivedContacts.length = 0;
+    this.derivedPublicationPending = false;
+    this.derivedPoisonedEntities.clear();
+    this.derivedColliderToShape.clear();
+    this.retiredDerivedBodies.length = 0;
+    this.derivedCandidateBytes = 0;
+    this.backendGeneration += 1;
     this.syncState = undefined;
     this.moveContext = undefined;
     if (typeof this.raw.free === 'function') this.raw.free();
@@ -514,12 +2316,14 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   setMoveContext(world: World, transform: Component, characterController: Component): void {
     this.assertActive('setMoveContext');
     this.moveContext = { world, transform, characterController };
+    this.worldIdentity = world;
   }
 
   /** Release the persistent ECS readers owned by one system registration. */
   clearEcsContext(world: World): void {
     if (this.syncState?.world === world) this.syncState = undefined;
     if (this.moveContext?.world === world) this.moveContext = undefined;
+    if (this.worldIdentity === world) this.worldIdentity = undefined;
   }
 
   moveAndSlide(entity: number, desiredDelta: Vec3): Vec3 {
@@ -528,6 +2332,14 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   }
 
   private assertActive(operation: string): void {
+    if (this.activeDerivedAdmission !== undefined) {
+      throw new DerivedPhysicsError(
+        'derived-candidate-pending',
+        'physics queries and mutations observe only complete fixed-step states',
+        'finish the paired geometry commit before querying or mutating physics',
+        { entity: this.activeDerivedAdmission.input.entity, reason: operation },
+      );
+    }
     if (this.disposed) {
       throw new Error(`RapierPhysicsWorld3D.${operation} cannot run on a disposed instance`);
     }
@@ -726,18 +2538,21 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   private fullReconcilePhysicsState(state: PhysicsSyncState): void {
     const descriptors: PhysicsSyncDescriptor[] = [];
     const transformlessStatic = new Set<number>();
-    for (const row of state.query) {
-      if (!row.has(state.transformComponent)) {
-        if (physicsRowIsStatic(row)) transformlessStatic.add(row.entity);
-        continue;
+    const committedDerived =
+      this.derivedBodies.size > 0 ? this.captureDerivedPhysicsState() : undefined;
+    for (const query of state.queries)
+      for (const row of query) {
+        if (!row.has(state.transformComponent)) {
+          if (physicsRowIsStatic(row)) transformlessStatic.add(row.entity);
+          continue;
+        }
+        const descriptor = readPhysicsSyncDescriptor(
+          row,
+          state.transformComponent,
+          state.globalTransformComponent,
+        );
+        if (descriptor !== undefined) descriptors.push(descriptor);
       }
-      const descriptor = readPhysicsSyncDescriptor(
-        row,
-        state.transformComponent,
-        state.globalTransformComponent,
-      );
-      if (descriptor !== undefined) descriptors.push(descriptor);
-    }
 
     this.resetForFullReconcile(transformlessStatic);
     for (const descriptor of descriptors) {
@@ -748,6 +2563,25 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
         descriptor.collider,
       );
     }
+    if (committedDerived !== undefined) {
+      const restorableBodies = committedDerived.bodies.filter(
+        (body) => this.entityMap.has(body.entity) && !this.derivedBodies.has(body.entity),
+      );
+      if (restorableBodies.length > 0) {
+        const restorable = Object.freeze({
+          ...committedDerived,
+          bodies: Object.freeze(restorableBodies),
+        });
+        const restored = this.restoreDerivedPhysicsState(restorable);
+        if (!restored.ok) {
+          // A full ECS rebuild has already replaced native bodies. Keep the
+          // rebuilt ordinary state queryable, but do not expose a mixed derived
+          // result: pending candidates are invalidated and the next consumer
+          // submission is the explicit recovery boundary.
+          this.invalidateDerivedShapeCandidates('full-reconcile-restore-failed');
+        }
+      }
+    }
     drainPhysicsChangeQueries(state.changeQueries);
     state.structuralCursor = readStructuralEvidence(state.world, state.structuralCursor).cursor;
     state.structureEpoch = state.world.getStructureEpoch();
@@ -759,7 +2593,7 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     entity: EntityHandle,
     delta: PhysicsEntityDelta,
   ): void {
-    const row = state.query.at(entity);
+    const row = state.queries.map((query) => query.at(entity)).find((entry) => entry !== undefined);
     if (row === undefined) {
       this.removeEntity(entity);
       return;
@@ -787,10 +2621,14 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     }
 
     if (this.hasBody(entity) && (delta.colliderChanged || delta.rigidBodyChanged)) {
-      // Collider/RigidBody lifecycle is reconciled by replacement from the final
-      // ECS combination. This deliberately resets velocity/contact state for an
-      // affected dynamic body; no descriptor mirror is introduced in M1.
-      this.removeEntity(entity);
+      // Derived shapes share this body and must survive ordinary authored
+      // component changes. Update the base collider/body in place; entities
+      // without a derived publication retain the legacy replacement path.
+      if (this.derivedBodies.has(entity)) {
+        this.syncDerivedCompatibleEcsMutation(entity, descriptor);
+      } else {
+        this.removeEntity(entity);
+      }
     }
     if (!this.hasBody(entity)) {
       this.ensureBody(entity, descriptor.transform, descriptor.rigidBody, descriptor.collider);
@@ -828,6 +2666,53 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     }
   }
 
+  private syncDerivedCompatibleEcsMutation(
+    entity: number,
+    descriptor: PhysicsSyncDescriptor,
+  ): void {
+    const body = this.bodyForEntity(entity);
+    if (body === undefined) return;
+    const bodyType = rigidBodyTypeFromF32(descriptor.rigidBody.type);
+    const RAPIER = this.rapierModule as RapierWorld;
+    // The native body is shared, but authored and derived colliders have
+    // distinct owners. Never address an authored collider by array position.
+    for (const collider of this.bodyColliders(body)) {
+      if (!this.derivedColliderToShape.has(collider.handle)) {
+        (this.raw as RapierWorld).removeCollider(collider, true);
+      }
+    }
+    const committed = this.derivedBodies.get(entity);
+    const record = this.entityMap.get(entity);
+    if (record !== undefined) record.authoredDensity = descriptor.collider?.density;
+    if (descriptor.collider !== undefined) {
+      this.createAuthoredCollider(body, descriptor.transform, {
+        ...descriptor.collider,
+        density: committed?.massProperties?.mode === 'explicit' ? 0 : descriptor.collider.density,
+      });
+    }
+    if (bodyType === 'static') {
+      body.setBodyType(RAPIER.RigidBodyType.Fixed, true);
+      this.syncAuthoredPose(entity, descriptor.transform, descriptor.collider, 'static');
+    } else if (bodyType === 'kinematic') {
+      body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);
+      this.syncAuthoredPose(entity, descriptor.transform, descriptor.collider, 'kinematic');
+    } else {
+      body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+      if (record !== undefined) record.additionalMass = Math.max(0, descriptor.rigidBody.mass);
+      if (committed?.massProperties?.mode !== 'explicit') {
+        this.restoreAutomaticMass(body, record?.additionalMass ?? 0);
+        if (record !== undefined) record.automaticAdditionalMass = record.additionalMass;
+      }
+      body.setGravityScale(descriptor.rigidBody.gravityScale, true);
+      body.setLinearDamping(descriptor.rigidBody.linearDamping);
+      body.setAngularDamping(descriptor.rigidBody.angularDamping);
+    }
+    body.enableCcd(Boolean(descriptor.rigidBody.ccdEnabled));
+    if (committed?.massProperties?.mode === 'explicit') {
+      this.restoreCommittedMass(body, committed, 0);
+    }
+  }
+
   /** @internal ECS system bridge; consumers should register PhysicsSyncBackend. */
   _syncFromEcs(
     world: World,
@@ -835,6 +2720,7 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     globalTransformComponent = world.components.resolve('GlobalTransform'),
   ): void {
     this.assertActive('syncFromEcs');
+    this.worldIdentity = world;
     if (globalTransformComponent === undefined) return;
     let state = this.syncState;
     if (
@@ -854,11 +2740,17 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
         ],
       });
       if (!queryResult.ok) return;
+      const bodyQuery = world.query({
+        read: [RigidBody],
+        without: [Collider],
+        optional: [transformComponent, globalTransformComponent, CharacterController, ChildOf],
+      });
+      if (!bodyQuery.ok) throw bodyQuery.error;
       state = {
         world,
         transformComponent,
         globalTransformComponent,
-        query: queryResult.value as unknown as PhysicsSyncQuery,
+        queries: [queryResult.value, bodyQuery.value] as unknown as readonly PhysicsSyncQuery[],
         changeQueries: createPhysicsChangeQueries(world, [
           transformComponent,
           globalTransformComponent,
@@ -1001,7 +2893,7 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
       gravityScale: number;
       ccdEnabled: number;
     },
-    collider: PhysicsCollider3D,
+    collider: PhysicsCollider3D | undefined,
   ): void {
     this.assertActive('ensureBody');
     if (this.entityMap.has(entity)) return; // M1 idempotent guard (D-2)
@@ -1058,8 +2950,27 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     }
 
     body.userData = entity;
-    this.registerBody(entity, body.handle);
+    this.registerBody(
+      entity,
+      body.handle,
+      rbType === 'dynamic' ? Math.max(0, rigidBody.mass) : 0,
+      collider?.density,
+    );
+    if (collider === undefined) {
+      const record = this.entityMap.get(entity);
+      if (record !== undefined) record.automaticAdditionalMass = record.additionalMass;
+      return;
+    }
+
+    this.createAuthoredCollider(body, transform, collider);
+  }
 
+  private createAuthoredCollider(
+    body: RapierRigidBody,
+    transform: PhysicsTransform3D,
+    collider: PhysicsCollider3D,
+  ): void {
+    const RAPIER = this.rapierModule;
     // ── Create ColliderDesc ──
     const scaleX = Math.abs(transform.scale.x);
     const scaleY = Math.abs(transform.scale.y);
@@ -1138,7 +3049,7 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   syncAuthoredPose(
     entity: number,
     transform: PhysicsTransform3D,
-    collider: PhysicsCollider3D,
+    collider: PhysicsCollider3D | undefined,
     bodyType: 'static' | 'kinematic',
   ): void {
     this.assertActive('syncAuthoredPose');
@@ -1156,7 +3067,10 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
       body.setNextKinematicRotation(transform.rotation);
     }
 
-    const rapierCollider = body.collider(0);
+    if (collider === undefined) return;
+    const rapierCollider = this.bodyColliders(body).find(
+      (shape) => !this.derivedColliderToShape.has(shape.handle),
+    );
     if (!rapierCollider) return;
     const scaleX = Math.abs(transform.scale.x);
     const scaleY = Math.abs(transform.scale.y);
@@ -1184,8 +3098,31 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   /**
    * Register an ECS entity with its Rapier body handle.
    */
-  registerBody(entity: number, bodyHandle: number): void {
-    this.entityMap.set(entity, { bodyHandle });
+  registerBody(
+    entity: number,
+    bodyHandle: number,
+    additionalMass = 0,
+    authoredDensity?: number,
+  ): void {
+    this.entityMap.set(entity, {
+      bodyHandle,
+      additionalMass: Math.max(0, additionalMass),
+      // `ensureBody` registers before its authored collider is attached.
+      // Rapier recomputes the body from that collider and clears the
+      // descriptor-only additional mass, so the native baseline is zero.
+      // A later automatic derived admission records the actual additional
+      // contribution after it has been applied. Keeping this separate from
+      // `additionalMass` lets rollback restore native state rather than an
+      // authored value that Rapier has not applied yet.
+      automaticAdditionalMass: 0,
+      authoredDensity:
+        authoredDensity !== undefined && Number.isFinite(authoredDensity) && authoredDensity >= 0
+          ? authoredDensity
+          : undefined,
+    });
+    if (!this.derivedBodySources.has(entity)) {
+      this.derivedBodySources.set(entity, { sourceKey: `entity:${entity}`, revision: 0 });
+    }
   }
 
   /**
@@ -1253,6 +3190,26 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
   removeEntity(entity: number): void {
     const record = this.entityMap.get(entity);
     if (!record) return;
+    const derived = this.derivedBodies.get(entity);
+    if (derived !== undefined) {
+      for (const shape of derived.shapes) this.removeNativeCollider(shape.colliderHandle);
+      this.derivedBodies.delete(entity);
+      this.derivedPublications.delete(entity);
+    }
+    this.derivedFailures.delete(entity);
+    this.derivedPoisonedEntities.delete(entity);
+    for (const [id, constraint] of this.derivedConstraints) {
+      if (constraint.input.bodyA === entity || constraint.input.bodyB === entity) {
+        this.removeNativeConstraint(constraint.handle);
+        this.derivedConstraints.delete(id);
+      }
+    }
+    for (const [id, candidate] of this.derivedCandidates) {
+      if (candidate.input.entity !== entity) continue;
+      for (const collider of candidate.nativeColliders) this.removeNativeCollider(collider.handle);
+      this.pendingDerivedCandidates.delete(id);
+      this.releaseDerivedCandidate(id);
+    }
     const ownPairs = [...(this.collisionPairs.get(entity) ?? [])];
     for (const other of ownPairs) {
       if (this.removePair(entity, other)) {
@@ -1263,6 +3220,7 @@ export class RapierPhysicsWorld3D implements PhysicsWorld {
     // biome-ignore lint/suspicious/noExplicitAny: Rapier World.removeRigidBody
     (this.raw as any).removeRigidBody({ handle: record.bodyHandle } as RapierRigidBody);
     this.entityMap.delete(entity);
+    this.derivedBodySources.delete(entity);
     // Clear the despawned entity from every overlap set so a collected Core does
     // not linger in the player's CollidingEntities (Rapier emits no `stopped`
     // event when a collider is removed mid-overlap).
@@ -1313,7 +3271,7 @@ function readPhysicsSyncDescriptor(
   const globalTransformData = row.get(globalTransformComponent) as
     | { readonly world: Float32Array }
     | undefined;
-  const colliderData = row.get(Collider) as
+  const colliderData = (row.has(Collider) ? row.get(Collider) : undefined) as
     | {
         readonly shape: number;
         readonly halfExtents: Float32Array;
@@ -1327,7 +3285,8 @@ function readPhysicsSyncDescriptor(
         readonly solverGroups: number;
       }
     | undefined;
-  if (transformData === undefined || colliderData === undefined) return undefined;
+  if (transformData === undefined || (colliderData === undefined && !row.has(RigidBody)))
+    return undefined;
 
   // Root-local TRS is already a world pose. A ChildOf row, however, must use
   // Scene's derived GlobalTransform world matrix. Matrix contents cannot be a
@@ -1404,22 +3363,25 @@ function readPhysicsSyncDescriptor(
             gravityScale: rigidBodyData.gravityScale,
             ccdEnabled: Number(rigidBodyData.ccdEnabled),
           },
-    collider: {
-      shape: colliderData.shape,
-      halfExtents: [
-        colliderData.halfExtents[0] ?? 0,
-        colliderData.halfExtents[1] ?? 0,
-        colliderData.halfExtents[2] ?? 0,
-      ],
-      radius: colliderData.radius,
-      halfHeight: colliderData.halfHeight,
-      friction: colliderData.friction,
-      restitution: colliderData.restitution,
-      density: colliderData.density,
-      isSensor: Number(colliderData.isSensor),
-      collisionGroups: colliderData.collisionGroups,
-      solverGroups: colliderData.solverGroups,
-    },
+    collider:
+      colliderData === undefined
+        ? undefined
+        : {
+            shape: colliderData.shape,
+            halfExtents: [
+              colliderData.halfExtents[0] ?? 0,
+              colliderData.halfExtents[1] ?? 0,
+              colliderData.halfExtents[2] ?? 0,
+            ],
+            radius: colliderData.radius,
+            halfHeight: colliderData.halfHeight,
+            friction: colliderData.friction,
+            restitution: colliderData.restitution,
+            density: colliderData.density,
+            isSensor: Number(colliderData.isSensor),
+            collisionGroups: colliderData.collisionGroups,
+            solverGroups: colliderData.solverGroups,
+          },
     hasCharacterController: row.has(CharacterController),
     characterControllerOffset: characterControllerData?.offset,
   };
@@ -1549,6 +3511,7 @@ export const PhysicsCollisionSync: SystemHandle<readonly []> = defineSystem({
       return; // C-2: safe early out
     }
     pw.writebackCollidingEntities(world, CollidingEntities as unknown as Component);
+    pw.finalizeDerivedFixedStep();
   },
 });