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

package/dist/schema-artifacts.d.ts

@@ -0,0 +1,49 @@
+import { type CanonicalValue } from './canonical.js';
+import type { DeterministicGameDescriptor, ValidatedDeterministicGameDescriptor } from './schema.js';
+import type { RecordedInputFrame } from './types.js';
+export interface SchemaFrameDump {
+    readonly frame: number;
+    readonly artifactId: string;
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly checksum: string;
+    readonly state: CanonicalValue;
+    readonly inputFrame?: RecordedInputFrame;
+}
+export interface DeterministicSchemaArtifacts {
+    readonly descriptor: ValidatedDeterministicGameDescriptor;
+    canonicalizeInput(input: unknown): CanonicalValue;
+    canonicalizeCommand(channelId: string, command: unknown): CanonicalValue;
+    /** Checksum projection: ONLY checksummed fields — feeds checksumState. */
+    canonicalizeState(state: unknown): CanonicalValue;
+    /** Every declared state field — the shape snapshots/restores must carry. */
+    canonicalizeFullState(state: unknown): CanonicalValue;
+    canonicalizeReplayMetadata(metadata: unknown): CanonicalValue;
+    canonicalizeAssetManifest(manifest: unknown): CanonicalValue;
+    serializeInput(input: unknown): Uint8Array;
+    deserializeInput(bytes: Uint8Array): CanonicalValue;
+    serializeCommand(channelId: string, command: unknown): Uint8Array;
+    deserializeCommand(channelId: string, bytes: Uint8Array): CanonicalValue;
+    serializeState(state: unknown): Uint8Array;
+    deserializeState(bytes: Uint8Array): CanonicalValue;
+    /**
+     * Snapshot serialization over the FULL declared state. Rollback/late-join
+     * restore replaces the live state with the deserialized snapshot — the
+     * checksum projection would silently wipe every checksummed:false field to
+     * undefined on restore (divergence the checksum can't see, because those
+     * fields aren't in it).
+     */
+    serializeFullState(state: unknown): Uint8Array;
+    deserializeFullState(bytes: Uint8Array): CanonicalValue;
+    serializeReplayMetadata(metadata: unknown): Uint8Array;
+    deserializeReplayMetadata(bytes: Uint8Array): CanonicalValue;
+    serializeAssetManifest(manifest: unknown): Uint8Array;
+    deserializeAssetManifest(bytes: Uint8Array): CanonicalValue;
+    checksumState(state: unknown): string;
+    dumpFrame(config: {
+        readonly frame: number;
+        readonly state: unknown;
+        readonly inputFrame?: RecordedInputFrame;
+    }): SchemaFrameDump;
+}
+export declare function createSchemaArtifacts(descriptor: DeterministicGameDescriptor): DeterministicSchemaArtifacts;

package/dist/schema-artifacts.js

@@ -0,0 +1,356 @@
+import { canonicalize, cloneCanonical, decodeUtf8, defaultChecksum, encodeUtf8 } from './canonical.js';
+import { SyncplayError } from './errors.js';
+import { defineSyncplayGame } from './schema.js';
+export function createSchemaArtifacts(descriptor) {
+    const validated = defineSyncplayGame(descriptor);
+    const canonicalizeInput = (input) => {
+        return canonicalizeDeclaredFields('input', input, validated.input.fields, validated.maxPlayers);
+    };
+    const canonicalizeState = (state) => {
+        return canonicalizeDeclaredFields('state', state, validated.state.fields, validated.maxPlayers, (field) => 'checksummed' in field && field.checksummed);
+    };
+    const canonicalizeFullState = (state) => {
+        return canonicalizeDeclaredFields('state', state, validated.state.fields, validated.maxPlayers);
+    };
+    const commandChannels = new Map((validated.commandChannels ?? []).map((channel) => [channel.id, channel]));
+    const canonicalizeCommand = (channelId, command) => {
+        const channel = commandChannels.get(channelId);
+        if (channel === undefined) {
+            throw new SyncplayError(`Command channel ${channelId} is not declared in schema`, {
+                code: 'schema-artifacts.command-channel',
+            });
+        }
+        return canonicalizeDeclaredFields(`command.${channelId}`, command, channel.fields, validated.maxPlayers);
+    };
+    const canonicalizeReplayMetadata = (metadata) => {
+        return canonicalizeLabeledRecord('replayMetadata', metadata);
+    };
+    const canonicalizeAssetManifest = (manifest) => {
+        return canonicalizeLabeledRecord('assetManifest', manifest);
+    };
+    return {
+        descriptor: validated,
+        canonicalizeInput,
+        canonicalizeCommand,
+        canonicalizeState,
+        canonicalizeFullState,
+        canonicalizeReplayMetadata,
+        canonicalizeAssetManifest,
+        serializeInput(input) {
+            return serializeCanonicalValue(canonicalizeInput(input));
+        },
+        deserializeInput(bytes) {
+            return canonicalizeInput(deserializeCanonicalValue('input', bytes));
+        },
+        serializeCommand(channelId, command) {
+            return serializeCanonicalValue(canonicalizeCommand(channelId, command));
+        },
+        deserializeCommand(channelId, bytes) {
+            return canonicalizeCommand(channelId, deserializeCanonicalValue(`command.${channelId}`, bytes));
+        },
+        serializeState(state) {
+            return serializeCanonicalValue(canonicalizeState(state));
+        },
+        deserializeState(bytes) {
+            return canonicalizeState(deserializeCanonicalValue('state', bytes));
+        },
+        serializeFullState(state) {
+            return serializeCanonicalValue(canonicalizeFullState(state));
+        },
+        deserializeFullState(bytes) {
+            return canonicalizeFullState(deserializeCanonicalValue('state', bytes));
+        },
+        serializeReplayMetadata(metadata) {
+            return serializeCanonicalValue(canonicalizeReplayMetadata(metadata));
+        },
+        deserializeReplayMetadata(bytes) {
+            return canonicalizeReplayMetadata(deserializeCanonicalValue('replayMetadata', bytes));
+        },
+        serializeAssetManifest(manifest) {
+            return serializeCanonicalValue(canonicalizeAssetManifest(manifest));
+        },
+        deserializeAssetManifest(bytes) {
+            return canonicalizeAssetManifest(deserializeCanonicalValue('assetManifest', bytes));
+        },
+        checksumState(state) {
+            return defaultChecksum(canonicalizeState(state));
+        },
+        dumpFrame(config) {
+            if (!Number.isInteger(config.frame) || config.frame < 0) {
+                throw new SyncplayError('Frame dump requires a non-negative integer frame', {
+                    code: 'schema-artifacts.frame',
+                    frame: config.frame,
+                });
+            }
+            const state = canonicalizeState(config.state);
+            const inputFrame = config.inputFrame === undefined
+                ? undefined
+                : canonicalizeRecordedInputFrame(config.inputFrame, canonicalizeInput, validated.maxPlayers);
+            return {
+                frame: config.frame,
+                artifactId: validated.artifactId,
+                inputSchemaId: validated.input.id,
+                stateSchemaId: validated.state.id,
+                checksum: defaultChecksum(state),
+                state,
+                ...(inputFrame === undefined ? {} : { inputFrame }),
+            };
+        },
+    };
+}
+const serializeCanonicalValue = (value) => encodeUtf8(JSON.stringify(value));
+function deserializeCanonicalValue(label, bytes) {
+    try {
+        const source = decodeUtf8(bytes);
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new SyncplayError(`${label} bytes are not valid schema JSON`, {
+            code: 'schema-artifacts.deserialize',
+        });
+    }
+}
+function canonicalizeDeclaredFields(label, value, fields, maxPlayers, includeField = () => true) {
+    const record = requireRecord(label, value);
+    const output = {};
+    const declaredFields = new Map(fields.map((field) => [field.name, field]));
+    for (const field of fields) {
+        if (!Object.prototype.hasOwnProperty.call(record, field.name)) {
+            if ('defaultValue' in field) {
+                if (includeField(field)) {
+                    output[field.name] = canonicalize(validateFieldValue(`${label}.${field.name}`, field, field.defaultValue, maxPlayers));
+                }
+                continue;
+            }
+            if (includeField(field)) {
+                throw new SyncplayError(`${label}.${field.name} is missing`, {
+                    code: 'schema-artifacts.missing-field',
+                });
+            }
+            continue;
+        }
+        const canonicalValue = canonicalize(validateFieldValue(`${label}.${field.name}`, field, record[field.name], maxPlayers));
+        if (includeField(field)) {
+            output[field.name] = canonicalValue;
+        }
+    }
+    for (const key of Object.keys(record).sort(compareStrings)) {
+        if (!declaredFields.has(key)) {
+            throw new SyncplayError(`${label}.${key} is not declared in schema`, {
+                code: 'schema-artifacts.undeclared-field',
+            });
+        }
+    }
+    return output;
+}
+function compareStrings(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    /* istanbul ignore else -- record-key sorts in this module cannot compare duplicate keys. */
+    if (left > right) {
+        return 1;
+    }
+    /* istanbul ignore next -- record-key sorts in this module cannot compare duplicate keys. */
+    return 0;
+}
+function canonicalizeLabeledRecord(label, value) {
+    return canonicalize(requireRecord(label, value));
+}
+function validateFieldValue(label, field, value, maxPlayers) {
+    if (Array.isArray(value)) {
+        if (field.collectionOrdering === undefined) {
+            throw new SyncplayError(`${label} is an array but does not declare collectionOrdering`, {
+                code: 'schema-artifacts.collection-ordering',
+            });
+        }
+        const items = value.map((item, index) => validateScalarValue(`${label}[${index}]`, field, item, maxPlayers));
+        // ENFORCE the declared ordering, don't just validate the enum: two peers
+        // holding the same logical collection in different array order must
+        // canonicalize identically, or the engine reports a desync that isn't one.
+        // 'indexed' means array order IS the meaning — preserved as-is.
+        if (field.collectionOrdering === 'sorted-key') {
+            return [...items].sort((left, right) => compareCanonicalScalars(label, left, right));
+        }
+        return items;
+    }
+    return validateScalarValue(label, field, value, maxPlayers);
+}
+function compareCanonicalScalars(label, left, right) {
+    if (typeof left === 'number' && typeof right === 'number') {
+        return left - right;
+    }
+    if (typeof left === 'string' && typeof right === 'string') {
+        return compareStrings(left, right);
+    }
+    if (typeof left === 'boolean' && typeof right === 'boolean') {
+        return Number(left) - Number(right);
+    }
+    throw new SyncplayError(`${label} sorted-key collection requires uniformly comparable scalar items`, {
+        code: 'schema-artifacts.collection-ordering',
+    });
+}
+function validateScalarValue(label, field, value, maxPlayers) {
+    switch (field.kind) {
+        case 'boolean':
+        case 'button':
+            if (typeof value !== 'boolean') {
+                throwTypeError(label, 'boolean');
+            }
+            return value;
+        case 'string':
+        case 'asset-ref':
+            if (typeof value !== 'string') {
+                throwTypeError(label, 'string');
+            }
+            return value;
+        case 'integer':
+        case 'fixed-q16':
+        case 'bitfield':
+        case 'player-slot':
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                throwTypeError(label, 'integer');
+            }
+            assertRange(label, field, value);
+            if (field.kind === 'player-slot' && (value < 0 || value >= maxPlayers)) {
+                throw new SyncplayError(`${label} must be a player slot between 0 and ${maxPlayers - 1}`, {
+                    code: 'schema-artifacts.player-slot',
+                });
+            }
+            return value;
+        /* istanbul ignore next -- defineSyncplayGame rejects unsupported field kinds before artifact creation. */
+        default:
+            throw new SyncplayError(`${label} uses unsupported field kind`, {
+                code: 'schema-artifacts.unsupported-kind',
+            });
+    }
+}
+function canonicalizeRecordedInputFrame(inputFrame, canonicalizeInput, maxPlayers) {
+    const record = requireRecord('inputFrame', inputFrame);
+    const allowedKeys = new Set(['frame', 'inputs', 'inputFlags']);
+    for (const key of Object.keys(record).sort(compareStrings)) {
+        if (!allowedKeys.has(key)) {
+            throw new SyncplayError(`inputFrame.${key} is not declared`, {
+                code: 'schema-artifacts.input-frame',
+            });
+        }
+    }
+    const frame = requireOwnProperty(record, 'inputFrame', 'frame');
+    if (typeof frame !== 'number' || !Number.isInteger(frame) || frame < 0) {
+        throw new SyncplayError('inputFrame.frame must be a non-negative integer', {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    const inputs = requireOwnProperty(record, 'inputFrame', 'inputs');
+    if (!Array.isArray(inputs)) {
+        throw new SyncplayError('inputFrame.inputs must be an array', {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    if (inputs.length > maxPlayers) {
+        throw new SyncplayError(`inputFrame.inputs cannot exceed maxPlayers ${maxPlayers}`, {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    const output = {
+        frame,
+        inputs: inputs.map((input) => canonicalizeInput(input)),
+    };
+    const hasInputFlags = Object.prototype.hasOwnProperty.call(record, 'inputFlags');
+    if (!hasInputFlags && record.inputFlags !== undefined) {
+        throw new SyncplayError('inputFrame.inputFlags must be an own property when present', {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    if (!hasInputFlags) {
+        return cloneCanonical(output);
+    }
+    const inputFlags = record.inputFlags;
+    if (!Array.isArray(inputFlags)) {
+        throw new SyncplayError('inputFrame.inputFlags must be an array when present', {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    return cloneCanonical({
+        ...output,
+        inputFlags: canonicalizeRecordedInputFlags(inputFlags, inputs.length, maxPlayers),
+    });
+}
+function canonicalizeRecordedInputFlags(inputFlags, expectedLength, maxPlayers) {
+    if (inputFlags.length !== expectedLength) {
+        throw new SyncplayError(`inputFrame.inputFlags length ${inputFlags.length} must match inputs length ${expectedLength}`, {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    return inputFlags.map((flag, index) => {
+        const record = requireRecord(`inputFrame.inputFlags[${index}]`, flag);
+        const allowedKeys = new Set(['slot', 'playerPresent', 'repeatedPrevious', 'replacedByServer', 'commandInput']);
+        for (const key of Object.keys(record).sort(compareStrings)) {
+            if (!allowedKeys.has(key)) {
+                throw new SyncplayError(`inputFrame.inputFlags[${index}].${key} is not declared`, {
+                    code: 'schema-artifacts.input-frame',
+                });
+            }
+        }
+        const slot = requireOwnProperty(record, `inputFrame.inputFlags[${index}]`, 'slot');
+        if (typeof slot !== 'number' || !Number.isInteger(slot) || slot < 0 || slot >= maxPlayers) {
+            throw new SyncplayError(`inputFrame.inputFlags[${index}].slot must be a valid player slot`, {
+                code: 'schema-artifacts.input-frame',
+            });
+        }
+        if (slot !== index) {
+            throw new SyncplayError(`inputFrame.inputFlags[${index}].slot must match its index`, {
+                code: 'schema-artifacts.input-frame',
+            });
+        }
+        return {
+            slot,
+            playerPresent: requireBooleanFlag(record, index, 'playerPresent'),
+            repeatedPrevious: requireBooleanFlag(record, index, 'repeatedPrevious'),
+            replacedByServer: requireBooleanFlag(record, index, 'replacedByServer'),
+            commandInput: requireBooleanFlag(record, index, 'commandInput'),
+        };
+    });
+}
+function requireBooleanFlag(record, index, key) {
+    const value = requireOwnProperty(record, `inputFrame.inputFlags[${index}]`, key);
+    if (typeof value !== 'boolean') {
+        throw new SyncplayError(`inputFrame.inputFlags[${index}].${key} must be boolean`, {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    return value;
+}
+function requireOwnProperty(record, label, key) {
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+        throw new SyncplayError(`${label}.${key} must be an own property`, {
+            code: 'schema-artifacts.input-frame',
+        });
+    }
+    return record[key];
+}
+function assertRange(label, field, value) {
+    if (field.min !== undefined && value < field.min) {
+        throw new SyncplayError(`${label} is below minimum ${field.min}`, {
+            code: 'schema-artifacts.range',
+        });
+    }
+    if (field.max !== undefined && value > field.max) {
+        throw new SyncplayError(`${label} is above maximum ${field.max}`, {
+            code: 'schema-artifacts.range',
+        });
+    }
+}
+function requireRecord(label, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new SyncplayError(`${label} must be an object`, {
+            code: 'schema-artifacts.record',
+        });
+    }
+    return value;
+}
+function throwTypeError(label, expected) {
+    throw new SyncplayError(`${label} must be ${expected}`, {
+        code: 'schema-artifacts.type',
+    });
+}

package/dist/schema-codegen.d.ts

@@ -0,0 +1,21 @@
+import { type DeterministicGameDescriptor } from './schema.js';
+import { type DeterministicDslSchema } from './schema-dsl-binary.js';
+export interface SchemaTypesOptions {
+    readonly rootName?: string;
+}
+export declare function generateSchemaTypes(descriptor: DeterministicGameDescriptor, options?: SchemaTypesOptions): string;
+export interface SchemaBinarySourceOptions {
+    readonly rootName?: string;
+    readonly importFrom?: string;
+}
+export interface SchemaBinaryProof {
+    readonly result: 'pass';
+    readonly schemaHash: string;
+    readonly declarationCount: number;
+    readonly fieldCount: number;
+    readonly encodedBytes: number;
+    readonly roundTripChecksum: string;
+}
+export declare function createDeterministicDescriptorBinarySchema(descriptor: DeterministicGameDescriptor, options?: SchemaBinarySourceOptions): DeterministicDslSchema;
+export declare function generateSchemaBinarySource(descriptor: DeterministicGameDescriptor, options?: SchemaBinarySourceOptions): string;
+export declare function proveSchemaBinaryRoundTrip(descriptor: DeterministicGameDescriptor, options?: SchemaBinarySourceOptions): SchemaBinaryProof;