@series-inc/rundot-syncplay 5.23.0 → 5.24.0-beta.1

package/dist/secret-protocol.js

@@ -0,0 +1,230 @@
+import { canonicalStringify, canonicalize, encodeUtf8 } from './canonical.js';
+export const syncplaySecretProtocol = 'rdm-secret/v1';
+export const syncplaySecretRequestMaxBytes = 65_536;
+export const syncplaySecretPrivateMessageMaxBytes = 262_144;
+export function isSyncplaySecretCommand(value) {
+    if (!isRecord(value) || !isSecretCommandBase(value))
+        return false;
+    const base = ['kind', 'systemId', 'requestId', 'authorityId', 'receipt'];
+    if (value.kind === 'syncplay.choice.committed' || value.kind === 'syncplay.choice.revealed') {
+        return isExactRecord(value, [...base, 'roundId', 'slot'])
+            && isIdentifier(value.roundId, 128) && isNonNegativeInteger(value.slot);
+    }
+    if (value.kind === 'syncplay.choice.resolved') {
+        return isExactRecord(value, [...base, 'roundId', 'reveals', 'missingSlots', 'missingReveal'])
+            && isIdentifier(value.roundId, 128) && isRecord(value.reveals) && isCanonical(value.reveals)
+            && Array.isArray(value.missingSlots) && value.missingSlots.every(isNonNegativeInteger)
+            && isOneOf(value.missingReveal, ['omit', 'forfeit']);
+    }
+    if (value.kind === 'syncplay.random.committed') {
+        return isExactRecord(value, [...base, 'link', 'draws', 'min', 'max'])
+            && isHex(value.link, 64) && isNonNegativeInteger(value.draws)
+            && Number.isSafeInteger(value.min) && Number.isSafeInteger(value.max);
+    }
+    if (value.kind === 'syncplay.random.drawn') {
+        return isExactRecord(value, [...base, 'drawIndex', 'previousLink', 'preimage', 'value'])
+            && isNonNegativeInteger(value.drawIndex) && isHex(value.previousLink, 64) && isHex(value.preimage, 64)
+            && Number.isSafeInteger(value.value);
+    }
+    if (value.kind === 'syncplay.collection.committed') {
+        return isExactRecord(value, [...base, 'collectionKind', 'root', 'count'])
+            && isOneOf(value.collectionKind, ['deck', 'bag']) && isHex(value.root, 64)
+            && isNonNegativeInteger(value.count);
+    }
+    if (value.kind === 'syncplay.collection.drawn') {
+        return isExactRecord(value, [...base, 'collectionKind', 'ownerSlot', 'tokenIds', 'count', 'remaining'])
+            && isOneOf(value.collectionKind, ['deck', 'bag']) && isNonNegativeInteger(value.ownerSlot)
+            && Array.isArray(value.tokenIds) && value.tokenIds.every((tokenId) => isIdentifier(tokenId, 128))
+            && isNonNegativeInteger(value.count) && isNonNegativeInteger(value.remaining);
+    }
+    if (value.kind === 'syncplay.collection.revealed') {
+        return isExactRecord(value, [...base, 'collectionKind', 'action', 'ownerSlot', 'tokenId', 'value', 'leafNonce', 'leafIndex', 'proof', 'root'])
+            && isOneOf(value.collectionKind, ['deck', 'bag']) && isOneOf(value.action, ['reveal', 'play'])
+            && isNonNegativeInteger(value.ownerSlot) && isIdentifier(value.tokenId, 128) && isCanonical(value.value)
+            && isHex(value.leafNonce, 64) && isNonNegativeInteger(value.leafIndex)
+            && Array.isArray(value.proof) && value.proof.every((entry) => typeof entry === 'string' && /^[lr]:[0-9a-f]{64}$/.test(entry))
+            && isHex(value.root, 64);
+    }
+    if (value.kind === 'syncplay.role.assigned') {
+        return isExactRecord(value, [...base, 'slot', 'tokenId'])
+            && isNonNegativeInteger(value.slot) && isIdentifier(value.tokenId, 128);
+    }
+    if (value.kind === 'syncplay.role.revealed') {
+        return isExactRecord(value, [...base, 'slot', 'tokenId', 'value'])
+            && isNonNegativeInteger(value.slot) && isIdentifier(value.tokenId, 128) && isCanonical(value.value);
+    }
+    return false;
+}
+function isSecretCommandBase(value) {
+    if (!isIdentifier(value.systemId, 64) || !isIdentifier(value.requestId, 128)
+        || !isIdentifier(value.authorityId, 256) || !isSignedReceipt(value.receipt))
+        return false;
+    const receipt = value.receipt;
+    return receipt.body.systemId === value.systemId
+        && receipt.body.requestId === value.requestId
+        && receipt.body.authorityId === value.authorityId;
+}
+export function encodeSyncplaySecretRequest(input) {
+    const request = { protocol: syncplaySecretProtocol, ...input, payload: canonicalize(input.payload) };
+    if (!isSecretRequest(request))
+        throw new Error('Syncplay secret request is malformed');
+    return encodeWithinBudget(request, syncplaySecretRequestMaxBytes, 'request');
+}
+export function decodeSyncplaySecretRequest(encoded) {
+    return decodeWithinBudget(encoded, syncplaySecretRequestMaxBytes, isSecretRequest);
+}
+export function encodeSyncplaySecretPrivateMessage(input) {
+    const message = { protocol: syncplaySecretProtocol, ...input };
+    if (!isSecretPrivateMessage(message))
+        throw new Error('Syncplay secret private message is malformed');
+    return encodeWithinBudget(message, syncplaySecretPrivateMessageMaxBytes, 'private response');
+}
+export function decodeSyncplaySecretPrivateMessage(encoded) {
+    return decodeWithinBudget(encoded, syncplaySecretPrivateMessageMaxBytes, isSecretPrivateMessage);
+}
+function encodeWithinBudget(value, maxBytes, label) {
+    const encoded = canonicalStringify(value);
+    if (encodeUtf8(encoded).byteLength > maxBytes) {
+        throw new Error(`Syncplay secret ${label} exceeds byte budget`);
+    }
+    return encoded;
+}
+function decodeWithinBudget(encoded, maxBytes, validate) {
+    if (typeof encoded !== 'string')
+        return { ok: false, error: 'malformed-envelope' };
+    if (encodeUtf8(encoded).byteLength > maxBytes)
+        return { ok: false, error: 'oversized-payload' };
+    try {
+        const parsed = JSON.parse(encoded);
+        if (!validate(parsed))
+            return { ok: false, error: 'malformed-envelope' };
+        return { ok: true, value: parsed };
+    }
+    catch {
+        return { ok: false, error: 'malformed-envelope' };
+    }
+}
+function isSecretRequest(value) {
+    if (!isExactRecord(value, ['protocol', 'kind', 'requestId', 'requestSequence', 'systemId', 'payload']))
+        return false;
+    return value.protocol === syncplaySecretProtocol
+        && isOneOf(value.kind, ['choice-commit', 'choice-reveal', 'random-draw', 'collection-draw', 'collection-reveal', 'collection-play', 'role-reveal'])
+        && isIdentifier(value.requestId, 128)
+        && Number.isSafeInteger(value.requestSequence)
+        && value.requestSequence >= 0
+        && isIdentifier(value.systemId, 64)
+        && isCanonical(value.payload);
+}
+function isSecretPrivateMessage(value) {
+    if (!isRecord(value) || value.protocol !== syncplaySecretProtocol || typeof value.kind !== 'string')
+        return false;
+    if (value.kind === 'secret-error') {
+        return isExactRecord(value, ['protocol', 'kind', 'requestId', 'error'])
+            && isIdentifier(value.requestId, 128)
+            && isOneOf(value.error, secretErrorCodes);
+    }
+    if (value.kind === 'secret-receipt') {
+        if (!hasOnlyKeys(value, ['protocol', 'kind', 'requestId', 'receipt', 'result']))
+            return false;
+        return isIdentifier(value.requestId, 128) && isSignedReceipt(value.receipt)
+            && (!('result' in value) || isCanonical(value.result));
+    }
+    if (value.kind === 'secret-token') {
+        return isExactRecord(value, ['protocol', 'kind', 'requestId', 'token'])
+            && isIdentifier(value.requestId, 128) && isOwnedToken(value.token);
+    }
+    if (value.kind === 'secret-start') {
+        if (!hasOnlyKeys(value, ['protocol', 'kind', 'authorityId', 'configHash', 'playerId', 'slot', 'role', 'kid', 'publicKeySpki', 'systems', 'nextRequestSequence']))
+            return false;
+        const seatedFieldsValid = value.role === 'spectator'
+            ? value.playerId === undefined && value.slot === undefined
+            : value.role === 'player' && isIdentifier(value.playerId, 256) && isNonNegativeInteger(value.slot);
+        return seatedFieldsValid && isIdentifier(value.authorityId, 256) && isHex(value.configHash, 64)
+            && isIdentifier(value.kid, 128) && typeof value.publicKeySpki === 'string' && value.publicKeySpki.length > 0
+            && (value.nextRequestSequence === undefined || isNonNegativeInteger(value.nextRequestSequence))
+            && Array.isArray(value.systems) && value.systems.every(isManifestSystem);
+    }
+    return false;
+}
+const secretErrorCodes = [
+    'secret-transport-unavailable', 'spectator-read-only', 'unknown-system', 'wrong-system-kind',
+    'malformed-envelope', 'oversized-payload', 'request-conflict', 'request-history-expired', 'invalid-phase',
+    'deadline-elapsed', 'missing-local-commitment', 'commitment-mismatch', 'random-exhausted', 'collection-empty',
+    'hand-full', 'token-unknown', 'token-owner-mismatch', 'token-already-consumed', 'proof-invalid',
+    'signing-unavailable', 'signature-invalid', 'restore-config-mismatch',
+];
+function isManifestSystem(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ['systemId', 'kind', 'min', 'max', 'count', 'proof']))
+        return false;
+    return isIdentifier(value.systemId, 64) && isOneOf(value.kind, ['choice', 'random', 'deck', 'bag', 'roles'])
+        && (value.min === undefined || Number.isSafeInteger(value.min))
+        && (value.max === undefined || Number.isSafeInteger(value.max))
+        && (value.count === undefined || isNonNegativeInteger(value.count))
+        && (value.proof === undefined || isManifestProof(value.proof));
+}
+function isManifestProof(value) {
+    if (!isRecord(value) || typeof value.kind !== 'string')
+        return false;
+    if (value.kind === 'random-context') {
+        return isExactRecord(value, ['kind', 'link', 'nextDrawIndex', 'receipt'])
+            && isHex(value.link, 64) && isNonNegativeInteger(value.nextDrawIndex) && isSignedReceipt(value.receipt);
+    }
+    const collectionKeys = value.assignedTokenId === undefined
+        ? ['kind', 'root', 'receipt']
+        : ['kind', 'root', 'assignedTokenId', 'receipt'];
+    return value.kind === 'collection-context'
+        && isExactRecord(value, collectionKeys)
+        && isHex(value.root, 64)
+        && (value.assignedTokenId === undefined || isIdentifier(value.assignedTokenId, 128))
+        && isSignedReceipt(value.receipt);
+}
+function isSignedReceipt(value) {
+    if (!isExactRecord(value, ['body', 'signature']) || typeof value.signature !== 'string')
+        return false;
+    const body = value.body;
+    return isExactRecord(body, ['protocol', 'domain', 'authorityId', 'systemId', 'requestId', 'playerId', 'slot', 'acceptedTick', 'commandHash', 'kid'])
+        && body.protocol === syncplaySecretProtocol && body.domain === 'run.syncplay.receipt/v1'
+        && isIdentifier(body.authorityId, 256) && isIdentifier(body.systemId, 64) && isIdentifier(body.requestId, 128)
+        && isIdentifier(body.playerId, 256) && isNonNegativeInteger(body.slot) && isNonNegativeInteger(body.acceptedTick)
+        && isHex(body.commandHash, 64) && isIdentifier(body.kid, 128);
+}
+function isOwnedToken(value) {
+    return isExactRecord(value, ['tokenId', 'systemId', 'ownerSlot', 'value', 'leafNonce', 'leafIndex', 'proof', 'root', 'receipt'])
+        && isIdentifier(value.tokenId, 128) && isIdentifier(value.systemId, 64) && isNonNegativeInteger(value.ownerSlot)
+        && isCanonical(value.value) && isHex(value.leafNonce, 64) && isNonNegativeInteger(value.leafIndex)
+        && Array.isArray(value.proof) && value.proof.every((entry) => typeof entry === 'string' && /^[lr]:[0-9a-f]{64}$/.test(entry))
+        && isHex(value.root, 64) && isSignedReceipt(value.receipt);
+}
+function isCanonical(value) {
+    try {
+        return canonicalStringify(value) === JSON.stringify(value);
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isExactRecord(value, keys) {
+    return isRecord(value) && Object.keys(value).length === keys.length && hasOnlyKeys(value, keys);
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key)) && keys.every((key) => key in value || optionalKey(key));
+}
+function optionalKey(key) {
+    return key === 'result' || key === 'playerId' || key === 'slot' || key === 'min' || key === 'max' || key === 'count'
+        || key === 'proof' || key === 'nextRequestSequence';
+}
+function isIdentifier(value, maxLength) {
+    return typeof value === 'string' && value.length >= 1 && value.length <= maxLength;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isHex(value, length) {
+    return typeof value === 'string' && value.length === length && /^[0-9a-f]+$/.test(value);
+}
+function isOneOf(value, values) {
+    return typeof value === 'string' && values.includes(value);
+}

package/dist/session-build.d.ts

@@ -12,6 +12,22 @@ export interface BuildDeterministicSessionConfig<State, Input> {
     readonly maxCatchUpFrames?: number;
     readonly replayRecordingMode?: ReplayRecordingMode;
     readonly runtimeGuards?: boolean;
+    /**
+     * State-codec overrides (same signatures as DeterministicSessionConfig).
+     * Each field independently replaces its schema-artifact default; unlike the
+     * raw low-level config there is NO fallback chain — a lone canonicalizeState
+     * shapes replay initial state and canonical egress but never byte
+     * serialization. Override these when your state is not fully expressible as
+     * declared descriptor fields (large typed-array worlds, custom binary
+     * codecs, incremental hashes). serializeState/deserializeState must be
+     * provided together. If your custom serializer covers fields the descriptor
+     * does not declare, also provide canonicalizeState — the schema default
+     * drops undeclared fields from replay initial state and snapshot egress.
+     */
+    readonly checksum?: (state: State) => string | number;
+    readonly canonicalizeState?: (state: State) => unknown;
+    readonly serializeState?: (state: State) => Uint8Array;
+    readonly deserializeState?: (bytes: Uint8Array) => State;
 }
 /**
  * Construct an OfflineSession from a validated descriptor, wiring the

package/dist/session-build.js

@@ -10,6 +10,9 @@ export function buildDeterministicSession(config) {
     if (config.playerCount > config.descriptor.maxPlayers) {
         throw new Error(`Session playerCount ${config.playerCount} exceeds descriptor maxPlayers ${config.descriptor.maxPlayers}`);
     }
+    if ((config.serializeState === undefined) !== (config.deserializeState === undefined)) {
+        throw new Error('serializeState and deserializeState must be provided together — a custom encoding one side cannot decode corrupts snapshot restore');
+    }
     return createOfflineSession({
         tickRate: config.descriptor.tickRate,
         playerCount: config.playerCount,
@@ -25,10 +28,10 @@ export function buildDeterministicSession(config) {
         // FULL declared state for replay initial-state and snapshots (rollback,
         // late-join hydration restore from these): they must carry every declared
         // field, not just the checksummed projection.
-        canonicalizeState: (state) => artifacts.canonicalizeFullState(state),
-        serializeState: (state) => artifacts.serializeFullState(state),
-        deserializeState: (bytes) => artifacts.deserializeFullState(bytes),
-        checksum: (state) => artifacts.checksumState(state),
+        canonicalizeState: config.canonicalizeState ?? ((state) => artifacts.canonicalizeFullState(state)),
+        serializeState: config.serializeState ?? ((state) => artifacts.serializeFullState(state)),
+        deserializeState: config.deserializeState ?? ((bytes) => artifacts.deserializeFullState(bytes)),
+        checksum: config.checksum ?? ((state) => artifacts.checksumState(state)),
         randomSeed: config.randomSeed,
         snapshotBufferSize: config.snapshotBufferSize,
         checksumIntervalFrames: config.checksumIntervalFrames,

package/dist/session-promotion.js

@@ -1,4 +1,5 @@
 import { canonicalize } from './canonical.js';
+import { computeWireStateChecksum } from './checksum-basis.js';
 import { SyncplayError, invariant } from './errors.js';
 import { createOfflineSession } from './offline-session.js';
 import { base64ToBytes, bytesToBase64, encodeDeterministicStateSnapshot, decodeDeterministicStateSnapshot, } from './session-snapshot.js';
@@ -28,7 +29,7 @@ import { base64ToBytes, bytesToBase64, encodeDeterministicStateSnapshot, decodeD
 export function exportPromotionSnapshot(session, frame) {
     const targetFrame = frame ?? session.currentFrame;
     invariant(Number.isInteger(targetFrame) && targetFrame >= 1, 'Promotion export requires a stepped frame (>= 1): the v1 snapshot envelope encodes tick = frame - 1', 'promotion.invalid-frame');
-    const snapshot = session.getSnapshot(targetFrame);
+    const snapshot = session.peekSnapshot(targetFrame);
     if (snapshot === undefined) {
         throw new SyncplayError(`No snapshot buffered for frame ${targetFrame} — it may have been evicted from the rolling buffer`, { code: 'promotion.missing-snapshot', frame: targetFrame });
     }
@@ -36,9 +37,9 @@ export function exportPromotionSnapshot(session, frame) {
         v: 1,
         tick: targetFrame - 1,
         sessionFrame: targetFrame,
-        stateBytes: bytesToBase64(snapshot.stateBytes),
+        stateBytes: bytesToBase64(session.getSnapshotBytes(snapshot.frame)),
         randomState: snapshot.randomState,
-        stateChecksum: snapshot.checksum,
+        stateChecksum: session.getWireStateChecksum(snapshot.frame),
         // Session inputs are canonical by construction (cloneCanonical on setInput).
         confirmedInputs: snapshot.inputs.map((input) => canonicalize(input)),
     });
@@ -62,8 +63,7 @@ export function createSessionFromPromotionSnapshot(config, blob) {
         // over the raw recorded value (adversarial-review LOW).
         (recorded) => (config.hydrateInput !== undefined ? config.hydrateInput(recorded) : recorded)),
     });
-    const restored = session.getSnapshot(session.currentFrame);
-    if (restored === undefined || restored.checksum !== snapshot.stateChecksum) {
+    if (computeWireStateChecksum(config, session.getState()) !== snapshot.stateChecksum) {
         throw new SyncplayError('Promotion snapshot checksum mismatch after hydration — the game build or state bytes do not match the exporter', { code: 'promotion.checksum-mismatch', frame: snapshot.sessionFrame });
     }
     return session;

package/dist/synctest.d.ts

@@ -1,6 +1,6 @@
 import { DeterministicRandom } from './random.js';
 import type { DeterministicSessionConfig } from './types.js';
-export type SyncplaySynctestPhase = 'straight' | 'rollback' | 'replay';
+export type SyncplaySynctestPhase = 'straight' | 'rollback' | 'replay' | 'aliasing' | 'hydration' | 'codec';
 export type SyncplaySynctestInputFuzz<Input> = (random: DeterministicRandom, slot: number, frame: number) => Input;
 export interface SyncplaySynctestConfig<State, Input> extends DeterministicSessionConfig<State, Input> {
     readonly frames?: number;

package/dist/synctest.js

@@ -1,3 +1,5 @@
+import { defaultChecksum } from './canonical.js';
+import { deserializeStateWith, serializeStateWith } from './checksum-basis.js';
 import { stableSortedKeys } from './collections.js';
 import { SyncplayError, invariant } from './errors.js';
 import { createOfflineSession } from './offline-session.js';
@@ -37,9 +39,56 @@ export function runSyncplaySynctest(config) {
         const schedule = buildInputSchedule(config.playerCount, frames, seed, inputFuzz);
         const straightChecksums = [];
         for (let frame = 0; frame < frames; frame += 1) {
+            const beforeSnapshot = straight.peekSnapshot(straight.currentFrame);
+            const beforeFingerprint = beforeSnapshot === undefined
+                ? undefined
+                : defaultChecksum(beforeSnapshot.state);
+            const external = straight.exportExternalSnapshot(straight.currentFrame);
+            const hydrated = createOfflineSession(sessionConfig);
+            hydrated.restoreSnapshot(external);
             applyScheduledInputs(straight, schedule[frame]);
             straight.stepFrames(1);
             straightChecksums.push(takeChecksum(lastChecksum, straight.currentFrame));
+            if (beforeSnapshot !== undefined && beforeFingerprint !== undefined) {
+                const afterFingerprint = defaultChecksum(beforeSnapshot.state);
+                if (afterFingerprint !== beforeFingerprint) {
+                    return diverged(seedsRun, framesChecked, {
+                        seed,
+                        frame: beforeSnapshot.frame,
+                        phase: 'aliasing',
+                        straightChecksum: beforeFingerprint,
+                        rollbackChecksum: afterFingerprint,
+                    });
+                }
+            }
+            applyScheduledInputs(hydrated, schedule[frame]);
+            hydrated.stepFrames(1);
+            const straightAfter = defaultChecksum(straight.getState());
+            const hydratedAfter = defaultChecksum(hydrated.getState());
+            if (straightAfter !== hydratedAfter) {
+                return diverged(seedsRun, framesChecked, {
+                    seed,
+                    frame: external.frame,
+                    phase: 'hydration',
+                    straightChecksum: straightAfter,
+                    rollbackChecksum: hydratedAfter,
+                });
+            }
+            if (sessionConfig.serializeState !== undefined) {
+                const live = straight.getState();
+                const roundTripped = deserializeStateWith(sessionConfig, serializeStateWith(sessionConfig, live));
+                const liveChecksum = defaultChecksum(live);
+                const roundTripChecksum = defaultChecksum(roundTripped);
+                if (liveChecksum !== roundTripChecksum) {
+                    return diverged(seedsRun, framesChecked, {
+                        seed,
+                        frame: straight.currentFrame,
+                        phase: 'codec',
+                        straightChecksum: liveChecksum,
+                        rollbackChecksum: roundTripChecksum,
+                    });
+                }
+            }
         }
         const replay = straight.exportReplay();
         const rollback = createOfflineSession(sessionConfig);

package/dist/testing.d.ts

@@ -38,6 +38,8 @@ export { runDeterministicNavmeshImportTraversalFixture, runDeterministicNavmeshL
 export type { DeterministicNavmeshImportTraversalFixtureResult, DeterministicNavmeshLayered3DFixtureResult, DeterministicNavmeshVelocityObstacleFixtureResult } from './navmesh.js';
 export { runDeterministicPhysics3DCallbackMaskFixture, runDeterministicPhysics3DDetailFixture, runDeterministicPhysics3DMaterialFixture, runDeterministicPhysics3DQueryOptionsFixture, runDeterministicPhysics3DStackFixture } from './physics3d.js';
 export type { DeterministicPhysics3DCallbackMaskFixtureResult, DeterministicPhysics3DDetailFixtureResult, DeterministicPhysics3DMaterialFixtureResult, DeterministicPhysics3DQueryOptionsFixtureResult, DeterministicPhysics3DStackFixtureResult } from './physics3d.js';
+export { runDeterministicRagdoll3DFixture, runDeterministicRigidWheelVehicle3DFixture } from './physics3d-recipes.js';
+export type { DeterministicRagdoll3DFixtureResult, DeterministicRigidWheelVehicle3DFixtureResult } from './physics3d-recipes.js';
 export { runDeterministicVehicle3DFixture } from './physics3d-vehicle.js';
 export type { DeterministicVehicle3DFixtureResult } from './physics3d-vehicle.js';
 export { runDeterministicRollbackHistoryFixture } from './rollback-history.js';

package/dist/testing.js

@@ -37,6 +37,7 @@ export { runDeterministicLocalAuthorityWireFixture } from './local-authority-wir
 export { runDeterministicKcc3DAdversarialFixture, runDeterministicKcc3DCallbackFilterFixture, runDeterministicKcc3DCrowdFixture, runDeterministicKcc3DFilterForceFixture, runDeterministicKcc3DGeometryFixture } from './movement3d.js';
 export { runDeterministicNavmeshImportTraversalFixture, runDeterministicNavmeshLayered3DFixture, runDeterministicNavmeshVelocityObstacleFixture } from './navmesh.js';
 export { runDeterministicPhysics3DCallbackMaskFixture, runDeterministicPhysics3DDetailFixture, runDeterministicPhysics3DMaterialFixture, runDeterministicPhysics3DQueryOptionsFixture, runDeterministicPhysics3DStackFixture } from './physics3d.js';
+export { runDeterministicRagdoll3DFixture, runDeterministicRigidWheelVehicle3DFixture } from './physics3d-recipes.js';
 export { runDeterministicVehicle3DFixture } from './physics3d-vehicle.js';
 export { runDeterministicRollbackHistoryFixture } from './rollback-history.js';
 export { runDeterministicDslBinaryFixture } from './schema-dsl-binary.js';

package/dist/tools/static-checker.d.ts

@@ -25,6 +25,17 @@ export interface DeterminismCheckOptions {
     readonly stateObjectName?: string;
 }
 export type DeterminismParserKind = 'typescript-ast' | 'regex-scanner';
+export interface DeterminismUnresolvedImport {
+    readonly importer: string;
+    readonly specifier: string;
+    readonly line: number;
+}
+export interface DeterminismCheckRun {
+    readonly diagnostics: readonly DeterminismDiagnostic[];
+    readonly checkedFiles: readonly string[];
+    readonly unresolvedImports: readonly DeterminismUnresolvedImport[];
+}
+export declare function runDeterminismCheck(options: DeterminismCheckOptions): Promise<DeterminismCheckRun>;
 export declare function checkDeterminism(options: DeterminismCheckOptions): Promise<readonly DeterminismDiagnostic[]>;
 export declare function collectDeterminismSuppressions(paths: readonly string[]): Promise<readonly DeterminismSuppression[]>;
 export declare function checkSourceText(path: string, content: string, mode?: DeterminismCheckMode, options?: Pick<DeterminismCheckOptions, 'parserKind' | 'schemaStateFields' | 'stateObjectName'>): readonly DeterminismDiagnostic[];

package/dist/tools/static-checker.js

@@ -277,19 +277,33 @@ const nodeBuiltinSpecifiers = new Set([
     'worker_threads',
     'zlib',
 ]);
-export async function checkDeterminism(options) {
+export async function runDeterminismCheck(options) {
     const mode = options.mode ?? 'warn';
-    const files = await collectFiles(options.paths, options.followImports ?? true, options.project);
+    const collected = await collectFiles(options.paths, options.followImports ?? true, options.project);
     const diagnostics = [];
     const schemaOptions = createSchemaOptions(options.schemaStateFields, options.stateObjectName);
-    for (const file of files) {
+    for (const file of collected.files) {
         const content = await readFile(file, 'utf8');
         diagnostics.push(...checkFile(file, content, mode, schemaOptions, options.parserKind));
     }
-    return diagnostics;
+    for (const unresolved of collected.unresolvedImports) {
+        diagnostics.push({
+            ruleId: 'determinism/unresolved-import',
+            severity: 'warn',
+            path: unresolved.importer,
+            line: unresolved.line,
+            column: 1,
+            message: `Import "${unresolved.specifier}" resolves to no file, so that part of the simulation graph was NOT determinism-checked.`,
+            suggestion: 'Fix the import path so the checker can traverse it, or remove the dead import.',
+        });
+    }
+    return { diagnostics, checkedFiles: collected.files, unresolvedImports: collected.unresolvedImports };
+}
+export async function checkDeterminism(options) {
+    return (await runDeterminismCheck(options)).diagnostics;
 }
 export async function collectDeterminismSuppressions(paths) {
-    const files = await collectFiles(paths, true);
+    const files = (await collectFiles(paths, true)).files;
     const suppressions = [];
     for (const file of files) {
         const lines = (await readFile(file, 'utf8')).split(/\r?\n/);
@@ -1252,23 +1266,34 @@ function checkDeclaredStateFields(path, lineText, previousLine, sourceLine, mode
 }
 async function collectFiles(paths, followImports, project) {
     const files = [];
+    const unresolvedImports = [];
     const visited = new Set();
     const resolver = await createImportResolver(project);
     for (const path of paths) {
         const entry = await stat(path);
         if (entry.isFile() && isCheckableFile(path)) {
             if (followImports) {
-                files.push(...(await collectFileWithImports(path, visited, resolver)));
+                files.push(...(await collectFileWithImports(path, visited, resolver, unresolvedImports)));
             }
             else {
                 files.push(path);
             }
         }
         if (entry.isDirectory()) {
-            files.push(...(await collectDirectory(path)));
+            // With followImports, a directory's files also traverse their imports —
+            // a dir whose files import shared code OUTSIDE the dir must not skip it.
+            const directoryFiles = await collectDirectory(path);
+            if (followImports) {
+                for (const directoryFile of directoryFiles) {
+                    files.push(...(await collectFileWithImports(directoryFile, visited, resolver, unresolvedImports)));
+                }
+            }
+            else {
+                files.push(...directoryFiles);
+            }
         }
     }
-    return Array.from(new Set(files)).sort();
+    return { files: Array.from(new Set(files)).sort(), unresolvedImports };
 }
 async function collectDirectory(path) {
     const files = [];
@@ -1291,7 +1316,7 @@ async function collectDirectory(path) {
 function isCheckableFile(path) {
     return /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(path);
 }
-async function collectFileWithImports(path, visited, resolver) {
+async function collectFileWithImports(path, visited, resolver, unresolvedImports) {
     const absolutePath = resolve(path);
     if (visited.has(absolutePath)) {
         return [];
@@ -1299,20 +1324,42 @@ async function collectFileWithImports(path, visited, resolver) {
     visited.add(absolutePath);
     const files = [path];
     const content = await readFile(path, 'utf8');
-    for (const specifier of findStaticImportSpecifiers(content)) {
-        const resolvedPath = await resolver.resolve(path, specifier);
+    for (const found of findStaticImportSpecifiers(content)) {
+        // Resolve with any ?query/#hash suffix stripped: './helper.ts?worker' is
+        // real executed source and must be traversed; the bundler resolves the
+        // bare path.
+        const bare = found.specifier.replace(/[?#].*$/, '');
+        const resolvedPath = await resolver.resolve(path, bare);
         if (resolvedPath !== undefined) {
-            files.push(...(await collectFileWithImports(resolvedPath, visited, resolver)));
+            files.push(...(await collectFileWithImports(resolvedPath, visited, resolver, unresolvedImports)));
+        }
+        else if (isRelativeSpecifier(bare) && !(await specifierTargetsExistingFile(path, bare))) {
+            unresolvedImports.push({ importer: path, specifier: found.specifier, line: found.line });
         }
     }
     return files;
 }
+function isRelativeSpecifier(specifier) {
+    return specifier.startsWith('.') || specifier.startsWith('/');
+}
+// Vite-style asset imports ('./sprite.png', './style.css?inline') point at
+// real files that just aren't checkable source — only a specifier reaching NO
+// file is a hole in the checked graph.
+async function specifierTargetsExistingFile(importer, bareSpecifier) {
+    try {
+        return (await stat(resolve(dirname(importer), bareSpecifier))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function findStaticImportSpecifiers(content) {
     const specifiers = [];
     const importPattern = /^\s*(?:import|export)\s+(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/gm;
     let match = importPattern.exec(content);
     while (match !== null) {
-        specifiers.push(match[1]);
+        const line = content.slice(0, match.index).split('\n').length;
+        specifiers.push({ specifier: match[1], line });
         match = importPattern.exec(content);
     }
     return specifiers;

package/dist/types.d.ts

@@ -10,6 +10,18 @@ export interface DeterministicStepContext {
     readonly math: DeterministicMath;
     readonly commands: readonly CanonicalValue[];
 }
+/**
+ * The simulation step.
+ *
+ * OWNERSHIP CONTRACT (enforced by synctest's `aliasing` phase):
+ * - `step` MUST NOT mutate `state`, nor anything reachable from it. Copy any
+ *   array, Map, Set or object before modifying it.
+ * - Sharing unmodified substructure with the prior state is expected and makes
+ *   a persistent map an O(1) snapshot. Returning `state` unchanged is legal.
+ * - The engine retains the returned object in its snapshot ring by reference
+ *   and hands it back on rollback without copying. Mutating a prior state can
+ *   therefore corrupt retained snapshots and desync only peers that roll back.
+ */
 export type DeterministicStep<State, Input> = (state: Readonly<State>, inputs: readonly Readonly<Input>[], frame: number, ctx: DeterministicStepContext) => State;
 export interface DeterministicSessionConfig<State, Input> {
     readonly tickRate: TickRate;
@@ -98,9 +110,9 @@ export interface ExternalSessionSnapshot<Input> {
 export interface FrameSnapshot<State, Input> {
     readonly frame: number;
     readonly inputs: readonly Input[];
-    readonly checksum: string;
+    /** Present only when `frame % checksumIntervalFrames === 0`. */
+    readonly checksum: string | undefined;
     readonly state: State;
-    readonly stateBytes: Uint8Array;
     readonly randomState: number;
 }
 export interface SessionSchemaIdentity {
@@ -120,7 +132,14 @@ export interface OfflineSession<State, Input> {
     stepFrames(count: number): void;
     getState(): State;
     exportReplay(): ReplayFile;
+    /** Zero-copy access to the retained ring entry. Do not mutate it. */
+    peekSnapshot(frame: number): FrameSnapshot<State, Input> | undefined;
     getSnapshot(frame: number): FrameSnapshot<State, Input> | undefined;
+    getSnapshotBytes(frame: number): Uint8Array;
+    exportExternalSnapshot(frame: number): ExternalSessionSnapshot<Input>;
+    getRecordedChecksum(frame: number): string | undefined;
+    computeRecordedChecksum(frame: number): string;
+    getWireStateChecksum(frame: number): string;
     restoreToFrame(frame: number): void;
     /**
      * Hydrate from a snapshot exported by ANOTHER session (snapshot late-join):