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

package/dist/engine-runtime.d.ts

@@ -0,0 +1,351 @@
+import { type CanonicalValue } from './canonical.js';
+import type { DeterministicCommandChannelDescriptor, DeterministicCommandTimeline, DeterministicCommandTimelineSnapshot, DeterministicPlayerCommand, DeterministicRejectedCommand } from './commands.js';
+import { DeterministicRandom } from './random.js';
+import { type DeterministicDslSchema } from './schema-dsl-binary.js';
+export type DeterministicComponentScalarFieldKind = 'int' | 'fixed' | 'bool' | 'string' | 'asset-ref' | 'entity-ref';
+export type DeterministicComponentFixedArrayFieldKind = `${DeterministicComponentScalarFieldKind}[${number}]`;
+export type DeterministicComponentFrameHeapFieldKind = 'frame-list' | 'frame-dictionary' | 'frame-hash-set';
+export type DeterministicComponentFieldKind = DeterministicComponentScalarFieldKind | `${DeterministicComponentScalarFieldKind}[]` | DeterministicComponentFixedArrayFieldKind | DeterministicComponentFrameHeapFieldKind;
+export interface DeterministicComponentFieldDescriptor {
+    readonly name: string;
+    readonly kind: DeterministicComponentFieldKind;
+    readonly defaultValue?: CanonicalValue;
+    readonly assetType?: string;
+}
+export interface DeterministicComponentDescriptor {
+    readonly id: string;
+    readonly fields: readonly DeterministicComponentFieldDescriptor[];
+    readonly singleton?: boolean;
+}
+export interface DeterministicFrameRuntimeDescriptor {
+    readonly id: string;
+    readonly tickRate: number;
+    readonly components: readonly DeterministicComponentDescriptor[];
+    readonly systems: readonly DeterministicSystemDescriptor[];
+    readonly commandChannels?: readonly DeterministicCommandChannelDescriptor[];
+    readonly eventChannels?: readonly DeterministicRuntimePayloadDescriptor[];
+    readonly signalChannels?: readonly DeterministicRuntimePayloadDescriptor[];
+}
+export interface DeterministicSystemDescriptor {
+    readonly id: string;
+    readonly group: 'input' | 'simulation' | 'physics' | 'post-physics' | 'presentation';
+    readonly order: number;
+    readonly before?: readonly string[];
+    readonly after?: readonly string[];
+}
+export interface DeterministicRuntimePayloadDescriptor {
+    readonly id: string;
+    readonly fields: readonly DeterministicComponentFieldDescriptor[];
+}
+export interface DeterministicEntityRef {
+    readonly id: number;
+    readonly generation: number;
+}
+export type DeterministicComponentData = Readonly<Record<string, CanonicalValue>>;
+export interface DeterministicQueryRow {
+    readonly entity: DeterministicEntityRef;
+    readonly components: Readonly<Record<string, DeterministicComponentData>>;
+}
+export interface DeterministicFrameQueryFilter {
+    readonly all?: readonly string[];
+    readonly any?: readonly string[];
+    readonly without?: readonly string[];
+}
+export type DeterministicFrameHeapCollectionKind = 'list' | 'dictionary' | 'hash-set';
+export interface DeterministicFrameHeapHandle {
+    readonly id: number;
+    readonly generation: number;
+    readonly kind: DeterministicFrameHeapCollectionKind;
+}
+export interface DeterministicFrameHeapSnapshot {
+    readonly nextHandleId: number;
+    readonly freeHandleIds: readonly number[];
+    readonly generations: Readonly<Record<string, number>>;
+    readonly collections: Readonly<Record<string, DeterministicFrameHeapCollectionSnapshot>>;
+}
+export type DeterministicFrameHeapCollectionSnapshot = {
+    readonly kind: 'list';
+    readonly generation: number;
+    readonly values: readonly CanonicalValue[];
+} | {
+    readonly kind: 'dictionary';
+    readonly generation: number;
+    readonly entries: readonly {
+        readonly key: string;
+        readonly value: CanonicalValue;
+    }[];
+} | {
+    readonly kind: 'hash-set';
+    readonly generation: number;
+    readonly values: readonly CanonicalValue[];
+};
+export interface DeterministicFrameSnapshot {
+    readonly frame: number;
+    readonly nextEntityId: number;
+    readonly freeEntityIds: readonly number[];
+    readonly generations: Readonly<Record<string, number>>;
+    readonly components: Readonly<Record<string, Readonly<Record<string, DeterministicComponentData>>>>;
+    readonly singletonComponents: Readonly<Record<string, DeterministicComponentData>>;
+    readonly frameHeap: DeterministicFrameHeapSnapshot;
+    readonly debugEvents: readonly {
+        readonly frame: number;
+        readonly type: string;
+        readonly payload: CanonicalValue;
+    }[];
+    readonly runtimeEvents: readonly DeterministicRuntimeMessage[];
+    readonly runtimeSignals: readonly DeterministicRuntimeMessage[];
+    readonly dispatchedSignals: readonly DeterministicRuntimeMessage[];
+    readonly nextRuntimeMessageSequence: number;
+    readonly commandTimeline?: DeterministicCommandTimelineSnapshot;
+    readonly randomState: number;
+    readonly bytes: string;
+    readonly checksum: string;
+}
+export interface DeterministicFrameRuntimeOptions {
+    readonly commandTimeline?: DeterministicCommandTimeline;
+    readonly assetRefs?: readonly string[];
+    readonly typedAssetRefs?: Readonly<Record<string, readonly string[]>>;
+    readonly statelessSystemSourceGuards?: boolean;
+}
+export type DeterministicStatelessSystemDiagnosticReason = 'missing-system' | 'mutable-own-fields' | 'external-mutation';
+export interface DeterministicStatelessSystemDiagnostic {
+    readonly systemId: string;
+    readonly reason: DeterministicStatelessSystemDiagnosticReason;
+    readonly externalMutation?: string;
+    readonly ownFields?: readonly string[];
+}
+export interface DeterministicStatelessSystemValidationResult {
+    readonly pass: boolean;
+    readonly diagnostics: readonly DeterministicStatelessSystemDiagnostic[];
+}
+export interface DeterministicSystemContext {
+    readonly frame: number;
+    readonly deltaTicks: 1;
+    readonly random: DeterministicRandom;
+    createEntity(): DeterministicEntityRef;
+    destroyEntity(entity: DeterministicEntityRef): void;
+    hasComponent(entity: DeterministicEntityRef, componentId: string): boolean;
+    getComponent(entity: DeterministicEntityRef, componentId: string): DeterministicComponentData | undefined;
+    setComponent(entity: DeterministicEntityRef, componentId: string, data: DeterministicComponentData): void;
+    removeComponent(entity: DeterministicEntityRef, componentId: string): void;
+    getSingleton(componentId: string): DeterministicComponentData | undefined;
+    setSingleton(componentId: string, data: DeterministicComponentData): void;
+    query(componentIds: readonly string[]): readonly DeterministicQueryRow[];
+    queryFilter(filter: DeterministicFrameQueryFilter): readonly DeterministicQueryRow[];
+    componentCount(componentId: string): number;
+    allocateFrameList(values?: readonly CanonicalValue[]): DeterministicFrameHeapHandle;
+    resolveFrameList(handle: DeterministicFrameHeapHandle): readonly CanonicalValue[];
+    setFrameList(handle: DeterministicFrameHeapHandle, values: readonly CanonicalValue[]): void;
+    allocateFrameDictionary(entries?: Readonly<Record<string, CanonicalValue>>): DeterministicFrameHeapHandle;
+    resolveFrameDictionary(handle: DeterministicFrameHeapHandle): Readonly<Record<string, CanonicalValue>>;
+    setFrameDictionaryValue(handle: DeterministicFrameHeapHandle, key: string, value: CanonicalValue): void;
+    deleteFrameDictionaryValue(handle: DeterministicFrameHeapHandle, key: string): void;
+    allocateFrameHashSet(values?: readonly CanonicalValue[]): DeterministicFrameHeapHandle;
+    resolveFrameHashSet(handle: DeterministicFrameHeapHandle): readonly CanonicalValue[];
+    addFrameHashSetValue(handle: DeterministicFrameHeapHandle, value: CanonicalValue): void;
+    deleteFrameHashSetValue(handle: DeterministicFrameHeapHandle, value: CanonicalValue): void;
+    freeFrameHeapCollection(handle: DeterministicFrameHeapHandle): void;
+    recordPlayerCommand(command: DeterministicPlayerCommand): DeterministicRejectedCommand | undefined;
+    recordPlayerCommandFromSlot(senderSlot: number, command: DeterministicPlayerCommand): DeterministicRejectedCommand | undefined;
+    pollPlayerCommands(frame?: number, slot?: number, channelId?: string): readonly DeterministicPlayerCommand[];
+    emitEvent(type: string, payload: DeterministicComponentData): void;
+    pollEvents(frame?: number, type?: string): readonly DeterministicRuntimeMessage[];
+    emitSignal(type: string, payload: DeterministicComponentData): void;
+    pollSignals(frame?: number, type?: string): readonly DeterministicRuntimeMessage[];
+    dispatchSignals<TState>(state: Readonly<TState>, handlers: readonly DeterministicRuntimeSignalHandler<TState>[], frame?: number, type?: string): TState;
+    emitDebug(type: string, payload: CanonicalValue): void;
+}
+export type DeterministicSystem = (ctx: DeterministicSystemContext) => void;
+export interface DeterministicFrameRuntime {
+    readonly descriptor: DeterministicFrameRuntimeDescriptor;
+    readonly frame: number;
+    readonly debugEvents: readonly {
+        readonly frame: number;
+        readonly type: string;
+        readonly payload: CanonicalValue;
+    }[];
+    createEntity(): DeterministicEntityRef;
+    destroyEntity(entity: DeterministicEntityRef): void;
+    setComponent(entity: DeterministicEntityRef, componentId: string, data: DeterministicComponentData): void;
+    removeComponent(entity: DeterministicEntityRef, componentId: string): void;
+    setSingleton(componentId: string, data: DeterministicComponentData): void;
+    query(componentIds: readonly string[]): readonly DeterministicQueryRow[];
+    queryFilter(filter: DeterministicFrameQueryFilter): readonly DeterministicQueryRow[];
+    componentCount(componentId: string): number;
+    step(systems: Readonly<Record<string, DeterministicSystem>>): void;
+    snapshot(): DeterministicFrameSnapshot;
+    restore(snapshot: DeterministicFrameSnapshot): void;
+}
+export interface DeterministicComponentAccessor {
+    readonly id: string;
+    has(ctx: Pick<DeterministicSystemContext, 'hasComponent'>, entity: DeterministicEntityRef): boolean;
+    get(ctx: Pick<DeterministicSystemContext, 'getComponent'>, entity: DeterministicEntityRef): DeterministicComponentData | undefined;
+    getOrDefault(ctx: Pick<DeterministicSystemContext, 'getComponent'>, entity: DeterministicEntityRef): DeterministicComponentData;
+    set(ctx: Pick<DeterministicSystemContext, 'setComponent'>, entity: DeterministicEntityRef, data: DeterministicComponentData): void;
+    patch(ctx: Pick<DeterministicSystemContext, 'getComponent' | 'setComponent'>, entity: DeterministicEntityRef, data: DeterministicComponentData): void;
+    setField(ctx: Pick<DeterministicSystemContext, 'getComponent' | 'setComponent'>, entity: DeterministicEntityRef, fieldName: string, value: CanonicalValue): void;
+    remove(ctx: Pick<DeterministicSystemContext, 'removeComponent'>, entity: DeterministicEntityRef): void;
+    query(ctx: Pick<DeterministicSystemContext, 'query'>, extraComponentIds?: readonly string[]): readonly DeterministicQueryRow[];
+    queryFilter(ctx: Pick<DeterministicSystemContext, 'queryFilter'>, filter?: DeterministicFrameQueryFilter): readonly DeterministicQueryRow[];
+    count(ctx: Pick<DeterministicSystemContext, 'componentCount'>): number;
+}
+export interface DeterministicSingletonAccessor {
+    readonly id: string;
+    get(ctx: Pick<DeterministicSystemContext, 'getSingleton'>): DeterministicComponentData | undefined;
+    getOrDefault(ctx: Pick<DeterministicSystemContext, 'getSingleton'>): DeterministicComponentData;
+    set(ctx: Pick<DeterministicSystemContext, 'setSingleton'>, data: DeterministicComponentData): void;
+    patch(ctx: Pick<DeterministicSystemContext, 'getSingleton' | 'setSingleton'>, data: DeterministicComponentData): void;
+    setField(ctx: Pick<DeterministicSystemContext, 'getSingleton' | 'setSingleton'>, fieldName: string, value: CanonicalValue): void;
+}
+export interface DeterministicCommandAccessor {
+    readonly id: string;
+    record(ctx: Pick<DeterministicSystemContext, 'recordPlayerCommand'>, command: DeterministicPlayerCommand): DeterministicRejectedCommand | undefined;
+    recordFromSlot(ctx: Pick<DeterministicSystemContext, 'recordPlayerCommandFromSlot'>, senderSlot: number, command: DeterministicPlayerCommand): DeterministicRejectedCommand | undefined;
+    poll(ctx: Pick<DeterministicSystemContext, 'pollPlayerCommands' | 'frame'>, frame?: number, slot?: number): readonly DeterministicPlayerCommand[];
+}
+export interface DeterministicRuntimeMessage {
+    readonly frame: number;
+    readonly type: string;
+    readonly sequence: number;
+    readonly payload: DeterministicComponentData;
+}
+export interface DeterministicRuntimeSignalHandler<TState> {
+    readonly id: string;
+    readonly type: string;
+    readonly order: number;
+    handle(state: Readonly<TState>, signal: DeterministicRuntimeMessage): TState;
+}
+export interface DeterministicEventAccessor {
+    readonly id: string;
+    emit(ctx: Pick<DeterministicSystemContext, 'emitEvent'>, payload: DeterministicComponentData): void;
+    poll(ctx: Pick<DeterministicSystemContext, 'pollEvents' | 'frame'>, frame?: number): readonly DeterministicRuntimeMessage[];
+}
+export interface DeterministicSignalAccessor {
+    readonly id: string;
+    emit(ctx: Pick<DeterministicSystemContext, 'emitSignal'>, payload: DeterministicComponentData): void;
+    poll(ctx: Pick<DeterministicSystemContext, 'pollSignals' | 'frame'>, frame?: number): readonly DeterministicRuntimeMessage[];
+    dispatch<TState>(ctx: Pick<DeterministicSystemContext, 'dispatchSignals' | 'frame'>, state: Readonly<TState>, handlers: readonly DeterministicRuntimeSignalHandler<TState>[], frame?: number): TState;
+}
+export interface DeterministicFrameRuntimeAccessors {
+    readonly descriptorHash: string;
+    readonly components: Readonly<Record<string, DeterministicComponentAccessor>>;
+    readonly singletons: Readonly<Record<string, DeterministicSingletonAccessor>>;
+    readonly commands: Readonly<Record<string, DeterministicCommandAccessor>>;
+    readonly events: Readonly<Record<string, DeterministicEventAccessor>>;
+    readonly signals: Readonly<Record<string, DeterministicSignalAccessor>>;
+    readonly source: string;
+    readonly sourceHash: string;
+}
+export interface DeterministicDslRuntimeCompileOptions {
+    readonly id?: string;
+    readonly tickRate?: number;
+    readonly systems?: readonly DeterministicSystemDescriptor[];
+}
+export interface DeterministicDslRuntimeFixtureResult {
+    readonly schemaHash: string;
+    readonly descriptorHash: string;
+    readonly permutedDescriptorHash: string;
+    readonly generatedSourceHash: string;
+    readonly generatedSourceBytes: number;
+    readonly mapRuntimeChecksum: string;
+    readonly sparseRuntimeChecksum: string;
+    readonly restoredChecksum: string;
+    readonly componentCount: number;
+    readonly singletonCount: number;
+    readonly commandChannelCount: number;
+    readonly eventChannelCount: number;
+    readonly signalChannelCount: number;
+    readonly arrayFieldCount: number;
+    readonly fixedArrayFieldCount: number;
+    readonly assetRefFieldCount: number;
+    readonly entityRefFieldCount: number;
+    readonly dynamicCollectionHandleFieldCount: number;
+    readonly generatedAccessorsExecuted: number;
+    readonly generatedFrameApiHelpersExecuted: number;
+    readonly generatedEventSignalAccessorsExecuted: number;
+    readonly generatedTypedInterfacesCovered: boolean;
+    readonly runtimeAssetRefsValidated: boolean;
+    readonly descriptorPermutationStable: boolean;
+    readonly sparseRuntimeEquivalent: boolean;
+    readonly rollbackEquivalent: boolean;
+    readonly checksum: string;
+}
+export interface DeterministicFrameRuntimeFrameApiFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly filterAnyWithoutStable: boolean;
+    readonly componentCountStable: boolean;
+    readonly frameHeapRollbackEquivalent: boolean;
+    readonly frameHeapHandlesAllocated: number;
+    readonly frameHeapFreedRejected: boolean;
+    readonly frameHeapReusedGenerationSafe: boolean;
+    readonly frameHeapSnapshotBytes: number;
+}
+export interface DeterministicSystemSchedulerFixtureResult {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly sparseChecksum: string;
+    readonly rollbackEquivalent: boolean;
+    readonly sparseEquivalent: boolean;
+    readonly order: string;
+    readonly beforeEdges: number;
+    readonly afterEdges: number;
+    readonly cycleRejected: boolean;
+    readonly unknownDependencyRejected: boolean;
+    readonly crossGroupDependencyRejected: boolean;
+}
+export declare function createDeterministicFrameRuntime(descriptor: DeterministicFrameRuntimeDescriptor, seed?: number, options?: DeterministicFrameRuntimeOptions): DeterministicFrameRuntime;
+export declare function createDeterministicSparseSetFrameRuntime(descriptor: DeterministicFrameRuntimeDescriptor, seed?: number, capacity?: number, options?: DeterministicFrameRuntimeOptions): DeterministicFrameRuntime;
+export declare function createDeterministicFrameRuntimeAccessors(descriptor: DeterministicFrameRuntimeDescriptor): DeterministicFrameRuntimeAccessors;
+export declare function generateDeterministicFrameRuntimeSource(descriptor: DeterministicFrameRuntimeDescriptor): string;
+export declare function compileDeterministicDslRuntimeDescriptor(schema: DeterministicDslSchema, options?: DeterministicDslRuntimeCompileOptions): DeterministicFrameRuntimeDescriptor;
+export declare function runDeterministicDslRuntimeFixture(iterations?: number, seed?: number): DeterministicDslRuntimeFixtureResult;
+export declare function createDeterministicSlotMap<T extends CanonicalValue>(): {
+    readonly size: number;
+    insert(value: T): number;
+    get(slot: number): T | undefined;
+    remove(slot: number): void;
+    entries(): readonly {
+        readonly slot: number;
+        readonly value: T;
+    }[];
+    checksum(): string;
+};
+export declare function createDeterministicBitset(size: number): {
+    set(index: number, value: boolean): void;
+    has(index: number): boolean;
+    indices(): readonly number[];
+    checksum(): string;
+};
+export declare function runDeterministicFrameRuntimeMutationCorpus(iterations: number, seed: number): {
+    readonly checksum: string;
+    readonly restoredChecksum: string;
+    readonly queryOrderStable: boolean;
+    readonly entityCreates: number;
+    readonly entityDestroys: number;
+    readonly componentWrites: number;
+    readonly snapshotBytes: number;
+    readonly p95FrameTimeMs: number;
+    readonly p99FrameTimeMs: number;
+};
+export declare function runDeterministicFrameRuntimeFrameApiFixture(iterations?: number, seed?: number): DeterministicFrameRuntimeFrameApiFixtureResult;
+export declare function isDeterministicFrameHeapStaleHandleError(error: unknown): boolean;
+export declare function assertDeterministicFrameHeapStaleHandleError(error: unknown): void;
+export declare function runDeterministicSystemSchedulerFixture(seed?: number): DeterministicSystemSchedulerFixtureResult;
+export declare function runDeterministicGeneratedRuntimeFixture(iterations: number, seed: number): {
+    readonly descriptorHash: string;
+    readonly generatedSourceHash: string;
+    readonly generatedSourceBytes: number;
+    readonly mapRuntimeChecksum: string;
+    readonly sparseRuntimeChecksum: string;
+    readonly sparseSnapshotBytes: number;
+    readonly generatedAccessorsExecuted: number;
+    readonly sparseSetBackedRuntimeEquivalent: boolean;
+    readonly accessorQueryOrderStable: boolean;
+    readonly rollbackEquivalent: boolean;
+    readonly entityRefGenerationSafe: boolean;
+    readonly runtimeHostApiGuarded: boolean;
+    readonly checksum: string;
+};
+export declare function validateDeterministicFrameSystemsStateless(descriptor: DeterministicFrameRuntimeDescriptor, systems: Readonly<Record<string, DeterministicSystem>>): DeterministicStatelessSystemValidationResult;
+export declare function assertDeterministicFrameSystemsStateless(descriptor: DeterministicFrameRuntimeDescriptor, systems: Readonly<Record<string, DeterministicSystem>>): void;