@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/system-lifecycle.js

@@ -0,0 +1,281 @@
+import { cloneCanonical, defaultChecksum } from './canonical.js';
+export function createDeterministicLifecycleRunner(descriptors, hooks) {
+    validateLifecycleDescriptors(descriptors, hooks);
+    const ordered = [...descriptors].sort(compareLifecycleDescriptors);
+    const descriptorById = new Map(ordered.map((descriptor) => [descriptor.id, descriptor]));
+    let frame = 0;
+    let initialized = new Set();
+    let enabled = new Set(ordered.filter((descriptor) => descriptor.startEnabled !== false).map((descriptor) => descriptor.id));
+    let pendingSignals = [];
+    let counters = new Map();
+    let log = [];
+    function context(systemId) {
+        return {
+            frame,
+            systemId,
+            emit(event) {
+                log.push(`${frame}:${systemId}:${event}`);
+            },
+            increment(key, amount = 1) {
+                counters.set(key, (counters.get(key) ?? 0) + amount);
+            },
+            signal(signal) {
+                pendingSignals.push(cloneCanonical(signal));
+            },
+        };
+    }
+    function isEffectivelyEnabled(systemId) {
+        const descriptor = descriptorById.get(systemId);
+        if (descriptor === undefined || !enabled.has(systemId)) {
+            return false;
+        }
+        return descriptor.parentId === undefined || isEffectivelyEnabled(descriptor.parentId);
+    }
+    return {
+        get frame() {
+            return frame;
+        },
+        enable(systemId) {
+            assertLifecycleSystem(descriptorById, systemId);
+            if (!enabled.has(systemId)) {
+                enabled.add(systemId);
+                hooks[systemId]?.onEnabled?.(context(systemId));
+            }
+        },
+        disable(systemId) {
+            assertLifecycleSystem(descriptorById, systemId);
+            if (enabled.has(systemId)) {
+                enabled.delete(systemId);
+                hooks[systemId]?.onDisabled?.(context(systemId));
+            }
+        },
+        signal(signal) {
+            pendingSignals.push(cloneCanonical(signal));
+        },
+        step() {
+            for (const descriptor of ordered) {
+                if (!initialized.has(descriptor.id)) {
+                    initialized.add(descriptor.id);
+                    hooks[descriptor.id]?.onInit?.(context(descriptor.id));
+                }
+            }
+            const signals = pendingSignals.sort(compareLifecycleSignals);
+            pendingSignals = [];
+            for (const descriptor of ordered) {
+                if (!isEffectivelyEnabled(descriptor.id)) {
+                    continue;
+                }
+                const systemHooks = hooks[descriptor.id];
+                for (const signal of signals) {
+                    systemHooks?.signal?.(context(descriptor.id), signal);
+                }
+                if (descriptor.signalsOnly !== true) {
+                    systemHooks?.update?.(context(descriptor.id));
+                }
+            }
+            frame += 1;
+        },
+        snapshot() {
+            return lifecycleSnapshot(frame, initialized, enabled, counters, pendingSignals, log);
+        },
+        restore(snapshot) {
+            validateLifecycleSnapshot(snapshot, descriptorById);
+            frame = snapshot.frame;
+            initialized = new Set(snapshot.initialized);
+            enabled = new Set(snapshot.enabled);
+            counters = new Map(stableRecordKeys(snapshot.counters).map((key) => [key, snapshot.counters[key]]));
+            pendingSignals = snapshot.pendingSignals.map((signal) => cloneCanonical(signal));
+            log = [...snapshot.log];
+        },
+    };
+}
+export function runDeterministicLifecycleFixture(frames = 128) {
+    const descriptors = [
+        { id: 'root', order: 0 },
+        { id: 'child', order: 1, parentId: 'root' },
+        { id: 'late', order: 2, startEnabled: false },
+        { id: 'signals', order: 3, signalsOnly: true },
+    ];
+    const hooks = Object.fromEntries(descriptors.map((descriptor) => [descriptor.id, lifecycleCountingHooks(descriptor.id)]));
+    const runner = createDeterministicLifecycleRunner(descriptors, hooks);
+    let snapshot;
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (frame === 4)
+            runner.enable('late');
+        if (frame === 8)
+            runner.disable('root');
+        if (frame === 12)
+            runner.enable('root');
+        if (frame % 5 === 0)
+            runner.signal({ id: 'tick', payload: { frame } });
+        if (frame === Math.floor(frames / 2))
+            snapshot = runner.snapshot();
+        runner.step();
+    }
+    const checksum = runner.snapshot().checksum;
+    if (snapshot === undefined) {
+        throw new Error('Lifecycle fixture did not capture snapshot');
+    }
+    const restored = createDeterministicLifecycleRunner(descriptors, hooks);
+    restored.restore(snapshot);
+    for (let frame = snapshot.frame; frame < frames; frame += 1) {
+        if (frame === 4)
+            restored.enable('late');
+        if (frame === 8)
+            restored.disable('root');
+        if (frame === 12)
+            restored.enable('root');
+        if (frame % 5 === 0)
+            restored.signal({ id: 'tick', payload: { frame } });
+        restored.step();
+    }
+    const restoredSnapshot = restored.snapshot();
+    return {
+        checksum,
+        restoredChecksum: restoredSnapshot.checksum,
+        rollbackEquivalent: checksum === restoredSnapshot.checksum,
+        ...summarizeDeterministicLifecycleCounters(restoredSnapshot.counters, restoredSnapshot.log),
+    };
+}
+export function summarizeDeterministicLifecycleCounters(counters, log) {
+    return {
+        initCalls: counters.init ?? 0,
+        updateCalls: counters.update ?? 0,
+        enabledCalls: counters.enabled ?? 0,
+        disabledCalls: counters.disabled ?? 0,
+        signalCalls: counters.signal ?? 0,
+        hierarchySkippedUpdates: countMissingChildUpdates(log, 8, 12),
+        startDisabledCovered: log.some((entry) => entry.endsWith('late:enabled')),
+        signalOnlySkippedUpdate: log.length > 0 && log.every((entry) => !entry.includes(':signals:update')),
+        orderStable: firstFrameOrder(log).join(',') === 'root,child',
+    };
+}
+function lifecycleCountingHooks(systemId) {
+    return {
+        onInit(ctx) {
+            ctx.increment('init');
+            ctx.emit('init');
+        },
+        onEnabled(ctx) {
+            ctx.increment('enabled');
+            ctx.emit('enabled');
+        },
+        onDisabled(ctx) {
+            ctx.increment('disabled');
+            ctx.emit('disabled');
+        },
+        update(ctx) {
+            ctx.increment('update');
+            ctx.emit('update');
+        },
+        signal(ctx, signal) {
+            ctx.increment('signal');
+            ctx.emit(`signal:${signal.id}:${systemId}`);
+        },
+    };
+}
+function lifecycleSnapshot(frame, initialized, enabled, counters, pendingSignals, log) {
+    const body = {
+        frame,
+        initialized: [...initialized].sort(compareStrings),
+        enabled: [...enabled].sort(compareStrings),
+        counters: Object.fromEntries([...counters.entries()].sort((left, right) => compareStrings(left[0], right[0]))),
+        pendingSignals: [...pendingSignals].sort(compareLifecycleSignals).map((signal) => cloneCanonical(signal)),
+        log: [...log],
+    };
+    return { ...body, checksum: defaultChecksum(body) };
+}
+function validateLifecycleDescriptors(descriptors, hooks) {
+    const ids = new Set();
+    for (const descriptor of descriptors) {
+        if (typeof descriptor.id !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(descriptor.id)) {
+            throw new Error(`Invalid lifecycle system id ${descriptor.id}`);
+        }
+        if (ids.has(descriptor.id)) {
+            throw new Error(`Duplicate lifecycle system id ${descriptor.id}`);
+        }
+        ids.add(descriptor.id);
+        if (!Number.isInteger(descriptor.order)) {
+            throw new Error(`Lifecycle system ${descriptor.id} order must be an integer`);
+        }
+    }
+    for (const descriptor of descriptors) {
+        if (descriptor.parentId !== undefined && typeof descriptor.parentId !== 'string') {
+            throw new Error(`Lifecycle system ${descriptor.id} references invalid parent ${descriptor.parentId}`);
+        }
+        if (descriptor.parentId !== undefined && !ids.has(descriptor.parentId)) {
+            throw new Error(`Lifecycle system ${descriptor.id} references missing parent ${descriptor.parentId}`);
+        }
+        if (hooks[descriptor.id] === undefined) {
+            throw new Error(`Lifecycle system ${descriptor.id} missing hooks`);
+        }
+    }
+    for (const descriptor of descriptors) {
+        validateParentChain(descriptor.id, new Set(), descriptors);
+    }
+}
+function validateParentChain(systemId, seen, descriptors) {
+    if (seen.has(systemId)) {
+        throw new Error(`Lifecycle system ${systemId} parent chain contains a cycle`);
+    }
+    seen.add(systemId);
+    const descriptor = descriptors.find((candidate) => candidate.id === systemId);
+    if (descriptor?.parentId !== undefined) {
+        validateParentChain(descriptor.parentId, seen, descriptors);
+    }
+    seen.delete(systemId);
+}
+function validateLifecycleSnapshot(snapshot, descriptors) {
+    if (!Number.isInteger(snapshot.frame) || snapshot.frame < 0) {
+        throw new Error('Lifecycle snapshot frame must be a non-negative integer');
+    }
+    for (const systemId of [...snapshot.initialized, ...snapshot.enabled]) {
+        if (!descriptors.has(systemId)) {
+            throw new Error(`Lifecycle snapshot references unknown system ${systemId}`);
+        }
+    }
+    for (const key of stableRecordKeys(snapshot.counters)) {
+        const value = snapshot.counters[key];
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new Error(`Lifecycle snapshot counter ${key} must be finite`);
+        }
+    }
+    const expected = lifecycleSnapshot(snapshot.frame, new Set(snapshot.initialized), new Set(snapshot.enabled), new Map(stableRecordKeys(snapshot.counters).map((key) => [key, snapshot.counters[key]])), snapshot.pendingSignals, snapshot.log).checksum;
+    if (snapshot.checksum !== expected) {
+        throw new Error('Lifecycle snapshot checksum mismatch');
+    }
+}
+function assertLifecycleSystem(descriptors, systemId) {
+    if (!descriptors.has(systemId)) {
+        throw new Error(`Unknown lifecycle system ${systemId}`);
+    }
+}
+function countMissingChildUpdates(log, startFrame, endFrame) {
+    let missing = 0;
+    const observedFrames = new Set(log.map((entry) => Number(entry.split(':')[0])).filter((frame) => Number.isInteger(frame)));
+    for (let frame = startFrame; frame < endFrame; frame += 1) {
+        if (observedFrames.has(frame) && !log.includes(`${frame}:child:update`)) {
+            missing += 1;
+        }
+    }
+    return missing;
+}
+function firstFrameOrder(log) {
+    return log
+        .filter((entry) => entry.startsWith('0:') && entry.endsWith(':update'))
+        .map((entry) => entry.split(':')[1]);
+}
+function compareLifecycleDescriptors(left, right) {
+    return left.order - right.order || compareStrings(left.id, right.id);
+}
+function compareLifecycleSignals(left, right) {
+    return compareStrings(left.id, right.id) || compareStrings(defaultChecksum(left.payload), defaultChecksum(right.payload));
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function stableRecordKeys(record) {
+    return Reflect.ownKeys(record)
+        .filter((key) => typeof key === 'string')
+        .sort(compareStrings);
+}

package/dist/timers.d.ts

@@ -0,0 +1,17 @@
+export interface DeterministicCooldown {
+    readonly remainingFrames: number;
+    readonly ready: boolean;
+}
+export interface ScheduledFrameEvent<Event> {
+    readonly frame: number;
+    readonly event: Event;
+}
+export declare function framesToMilliseconds(frames: number, tickRate: number): number;
+export declare function millisecondsToFrames(milliseconds: number, tickRate: number): number;
+export declare function createCooldown(durationFrames: number): DeterministicCooldown;
+export declare function tickCooldown(cooldown: DeterministicCooldown, frames?: number): DeterministicCooldown;
+export declare function scheduleFrameEvent<Event>(currentFrame: number, delayFrames: number, event: Event): ScheduledFrameEvent<Event>;
+export declare function popDueFrameEvents<Event>(currentFrame: number, events: readonly ScheduledFrameEvent<Event>[]): {
+    readonly due: readonly ScheduledFrameEvent<Event>[];
+    readonly pending: readonly ScheduledFrameEvent<Event>[];
+};

package/dist/timers.js

@@ -0,0 +1,53 @@
+export function framesToMilliseconds(frames, tickRate) {
+    assertNonNegativeInteger('frames', frames);
+    assertPositiveInteger('tickRate', tickRate);
+    return Math.trunc((frames * 1000) / tickRate);
+}
+export function millisecondsToFrames(milliseconds, tickRate) {
+    if (!Number.isFinite(milliseconds) || milliseconds < 0) {
+        throw new Error('milliseconds must be a finite non-negative number');
+    }
+    assertPositiveInteger('tickRate', tickRate);
+    return Math.ceil((milliseconds * tickRate) / 1000);
+}
+export function createCooldown(durationFrames) {
+    assertNonNegativeInteger('durationFrames', durationFrames);
+    return {
+        remainingFrames: durationFrames,
+        ready: durationFrames === 0,
+    };
+}
+export function tickCooldown(cooldown, frames = 1) {
+    assertNonNegativeInteger('frames', frames);
+    const remainingFrames = Math.max(0, cooldown.remainingFrames - frames);
+    return {
+        remainingFrames,
+        ready: remainingFrames === 0,
+    };
+}
+export function scheduleFrameEvent(currentFrame, delayFrames, event) {
+    assertNonNegativeInteger('currentFrame', currentFrame);
+    assertNonNegativeInteger('delayFrames', delayFrames);
+    return {
+        frame: currentFrame + delayFrames,
+        event,
+    };
+}
+export function popDueFrameEvents(currentFrame, events) {
+    assertNonNegativeInteger('currentFrame', currentFrame);
+    const sorted = [...events].sort((left, right) => left.frame - right.frame);
+    return {
+        due: sorted.filter((entry) => entry.frame <= currentFrame),
+        pending: sorted.filter((entry) => entry.frame > currentFrame),
+    };
+}
+function assertNonNegativeInteger(label, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer`);
+    }
+}
+function assertPositiveInteger(label, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { checkDeterminism, checkSourceText, collectDeterminismSuppressions, type DeterminismCheckMode, type DeterminismCheckOptions, type DeterminismDiagnostic, type DeterminismParserKind, type DeterminismSeverity, type DeterminismSuppression, } from './static-checker.js';
+export { createSyncplayViteConfig, createProjectCertificationCommand, createProjectCheckCommand, formatDiagnostics, runProjectCheck, runProjectCertification, rundotSyncplayPlugin, withSyncplayViteConfig, type DeterministicProjectCertificationPluginOptions, type DeterministicProjectCheckPluginOptions, type SyncplayPluginOptions, type MinimalViteConfig, type MinimalVitePlugin, type MinimalVitePluginApply, type MinimalVitePluginEnforce, type MinimalVitePluginEnvironment, } from './vite-plugin.js';
+export { createDefaultCertificationManifest, runCertificationSuite, stableCertificationJson, } from '../certification.js';
+export { runSyncplaySynctest, type SyncplaySynctestConfig, type SyncplaySynctestDivergence, type SyncplaySynctestInputFuzz, type SyncplaySynctestPhase, type SyncplaySynctestResult, } from '../synctest.js';

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { checkDeterminism, checkSourceText, collectDeterminismSuppressions, } from './static-checker.js';
+export { createSyncplayViteConfig, createProjectCertificationCommand, createProjectCheckCommand, formatDiagnostics, runProjectCheck, runProjectCertification, rundotSyncplayPlugin, withSyncplayViteConfig, } from './vite-plugin.js';
+export { createDefaultCertificationManifest, runCertificationSuite, stableCertificationJson, } from '../certification.js';
+export { runSyncplaySynctest, } from '../synctest.js';

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

@@ -0,0 +1,31 @@
+export type DeterminismSeverity = 'warn' | 'error';
+export type DeterminismCheckMode = 'warn' | 'strict';
+export interface DeterminismDiagnostic {
+    readonly ruleId: string;
+    readonly severity: DeterminismSeverity;
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly message: string;
+    readonly suggestion: string;
+}
+export interface DeterminismSuppression {
+    readonly ruleId: string;
+    readonly path: string;
+    readonly line: number;
+    readonly reason: string;
+}
+export interface DeterminismCheckOptions {
+    readonly paths: readonly string[];
+    readonly mode?: DeterminismCheckMode;
+    readonly followImports?: boolean;
+    readonly parserKind?: DeterminismParserKind;
+    readonly project?: string;
+    readonly schemaStateFields?: readonly string[];
+    readonly stateObjectName?: string;
+}
+export type DeterminismParserKind = 'typescript-ast' | 'regex-scanner';
+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[];
+export declare function getDeterminismParserKind(): DeterminismParserKind;