core_versionedSave.js

/**
 * @file versionedSave.js
 * SAVE-01: Versioned save engine, sequential schema migrations,
 * reference validation, future version detection, and corrupt JSON recovery.
 */

/**
 * In-memory fallback storage adhering to Storage interface.
 */
export class MapStorage {
    /**
     * @param {Array<Array<string>>} [initialEntries]
     */
    constructor(initialEntries) {
        this._map = new Map(initialEntries || []);
    }

    /**
     * @param {string} key
     * @returns {string|null}
     */
    getItem(key) {
        const k = String(key);
        return this._map.has(k) ? this._map.get(k) : null;
    }

    /**
     * @param {string} key
     * @param {string} value
     */
    setItem(key, value) {
        this._map.set(String(key), String(value));
    }

    /**
     * @param {string} key
     */
    removeItem(key) {
        this._map.delete(String(key));
    }

    clear() {
        this._map.clear();
    }

    /**
     * @param {number} index
     * @returns {string|null}
     */
    key(index) {
        return Array.from(this._map.keys())[index] || null;
    }

    /**
     * @returns {string[]}
     */
    keys() {
        return Array.from(this._map.keys());
    }

    /**
     * @returns {number}
     */
    get length() {
        return this._map.size;
    }
}

/**
 * Error thrown when a save file schema version exceeds the supported version.
 */
export class FutureVersionError extends Error {
    /**
     * @param {number} saveVersion
     * @param {number} supportedVersion
     * @param {string} [customMessage]
     */
    constructor(saveVersion, supportedVersion, customMessage) {
        const msg = customMessage ||
            `Save schema version (${saveVersion}) is newer than supported version (${supportedVersion}). Please update the application to load this save.`;
        super(msg);
        this.name = "FutureVersionError";
        this.code = "ERR_FUTURE_SCHEMA_VERSION";
        this.saveVersion = saveVersion;
        this.supportedVersion = supportedVersion;
        this.isFutureVersion = true;
    }
}

/**
 * Error thrown when entity or component references are invalid.
 */
export class ReferenceValidationError extends Error {
    /**
     * @param {Object|string} resultOrMessage
     * @param {Object} [details]
     */
    constructor(resultOrMessage, details) {
        const message = typeof resultOrMessage === "string"
            ? resultOrMessage
            : ReferenceValidationError.formatMessage(resultOrMessage);
        super(message);
        this.name = "ReferenceValidationError";
        this.code = "ERR_REFERENCE_VALIDATION";

        if (resultOrMessage && typeof resultOrMessage === "object") {
            this.validationResult = resultOrMessage;
            this.errors = resultOrMessage.errors || [];
            this.duplicates = resultOrMessage.duplicates || { entities: [], components: [] };
            this.dangling = resultOrMessage.dangling || [];
        } else {
            const extra = details || {};
            this.errors = extra.errors || [message];
            this.duplicates = extra.duplicates || { entities: [], components: [] };
            this.dangling = extra.dangling || [];
        }
    }

    /**
     * Format a readable message from validation results.
     * @param {Object} result
     * @returns {string}
     */
    static formatMessage(result) {
        const parts = ["Reference validation failed:"];
        if (result && Array.isArray(result.errors) && result.errors.length > 0) {
            for (let i = 0; i < result.errors.length; i++) {
                parts.push(`  - ${result.errors[i]}`);
            }
        }
        return parts.join("\n");
    }
}

/**
 * Error thrown when a schema migration fails or fails step verification.
 */
export class MigrationError extends Error {
    /**
     * @param {string} message
     * @param {Object} [details]
     */
    constructor(message, details) {
        super(message);
        this.name = "MigrationError";
        this.code = "ERR_SCHEMA_MIGRATION";
        const info = details || {};
        this.fromVersion = info.fromVersion;
        this.toVersion = info.toVersion;
        this.step = info.step;
        this.cause = info.cause || null;
        this.aborted = true;
        this.originalStatePreserved = true;
    }
}

/**
 * Error thrown when JSON save data is corrupt and cannot be parsed or recovered.
 */
export class CorruptSaveError extends Error {
    /**
     * @param {string} message
     * @param {Object} [details]
     */
    constructor(message, details) {
        super(message);
        this.name = "CorruptSaveError";
        this.code = "ERR_CORRUPT_SAVE_JSON";
        const info = details || {};
        this.line = info.line || 1;
        this.column = info.column || 1;
        this.position = info.position || 0;
        this.snippet = info.snippet || "";
        this.rawText = info.rawText || "";
        this.diagnostic = info.diagnostic || null;
    }
}

/**
 * Registry and planner for sequential schema migrations.
 */
export class SchemaMigrationRegistry {
    constructor() {
        /** @type {Map<number, Object>} */
        this._migrations = new Map();
    }

    /**
     * Register a migration step.
     * Can be called as register(fromVersion, toVersion, migrateFn, options)
     * or register(fromVersion, migrateFn, options) where toVersion = fromVersion + 1.
     *
     * @param {number} fromVersion
     * @param {number|Function} toVersionOrFn
     * @param {Function} [maybeFn]
     * @param {Object} [options]
     * @returns {SchemaMigrationRegistry}
     */
    register(fromVersion, toVersionOrFn, maybeFn, options) {
        if (!Number.isInteger(fromVersion)) {
            throw new TypeError("fromVersion must be an integer.");
        }

        let toVersion;
        let migrateFn;
        let stepOptions = options || {};

        if (typeof toVersionOrFn === "function") {
            toVersion = fromVersion + 1;
            migrateFn = toVersionOrFn;
            if (typeof maybeFn === "object" && maybeFn !== null) {
                stepOptions = maybeFn;
            }
        } else if (Number.isInteger(toVersionOrFn) && typeof maybeFn === "function") {
            toVersion = toVersionOrFn;
            migrateFn = maybeFn;
        } else {
            throw new TypeError("Invalid migration arguments: expected (fromVersion, toVersion, migrateFn) or (fromVersion, migrateFn).");
        }

        if (toVersion <= fromVersion) {
            throw new RangeError(`Migration target version (${toVersion}) must be greater than source version (${fromVersion}).`);
        }

        this._migrations.set(fromVersion, {
            fromVersion,
            toVersion,
            migrate: migrateFn,
            verify: stepOptions.verify || null,
            description: stepOptions.description || `Migration from v${fromVersion} to v${toVersion}`
        });

        return this;
    }

    /**
     * Check if a migration is registered from fromVersion.
     * @param {number} fromVersion
     * @returns {boolean}
     */
    has(fromVersion) {
        return this._migrations.has(fromVersion);
    }

    /**
     * Get migration step starting from fromVersion.
     * @param {number} fromVersion
     * @returns {Object|null}
     */
    get(fromVersion) {
        return this._migrations.get(fromVersion) || null;
    }

    /**
     * Plan sequential migration steps from sourceVersion to targetVersion.
     * @param {number} fromVersion
     * @param {number} targetVersion
     * @returns {Array<Object>}
     */
    getPlan(fromVersion, targetVersion) {
        if (!Number.isInteger(fromVersion) || !Number.isInteger(targetVersion)) {
            throw new TypeError("Schema versions must be integers.");
        }
        if (fromVersion > targetVersion) {
            throw new RangeError(`Cannot migrate backward from v${fromVersion} to v${targetVersion}.`);
        }
        if (fromVersion === targetVersion) {
            return [];
        }

        const plan = [];
        let current = fromVersion;
        while (current < targetVersion) {
            const step = this._migrations.get(current);
            if (!step) {
                throw new Error(`No migration registered from schema version ${current} to reach supported version ${targetVersion}.`);
            }
            if (step.toVersion > targetVersion) {
                throw new Error(`Migration step from v${current} targets v${step.toVersion}, which exceeds target version ${targetVersion}.`);
            }
            plan.push(step);
            current = step.toVersion;
        }
        return plan;
    }

    /**
     * Clear all registered migrations.
     */
    clear() {
        this._migrations.clear();
    }
}

/**
 * Validates entity and component references for duplicate IDs and dangling pointers.
 */
export class ReferenceValidator {
    /**
     * @param {Object} [options]
     */
    constructor(options) {
        const opts = options || {};
        this.referenceFields = opts.referenceFields || [
            "parentId",
            "parent",
            "targetId",
            "targetEntityId",
            "entityId",
            "followTargetId",
            "ownerId"
        ];
        this.throwOnError = opts.throwOnError || false;
    }

    /**
     * Static shortcut to validate references on data.
     * @param {Object} data
     * @param {Object} [options]
     * @returns {Object}
     */
    static validate(data, options) {
        const validator = new ReferenceValidator(options);
        return validator.validate(data, options);
    }

    /**
     * Validate data for duplicate entity/component IDs and dangling references.
     * @param {Object} data
     * @param {Object} [options]
     * @returns {Object}
     */
    validate(data, options) {
        const opts = options || {};
        const shouldThrow = opts.throwOnError !== undefined ? opts.throwOnError : this.throwOnError;

        const allEntities = [];
        const allComponents = [];
        const entityMap = new Map();
        const componentMap = new Map();
        const duplicateEntityIds = new Set();
        const duplicateComponentIds = new Set();
        const dangling = [];
        const visited = new Set();

        function visitEntity(ent) {
            if (!ent || typeof ent !== "object" || visited.has(ent)) return;
            visited.add(ent);
            allEntities.push(ent);

            if (ent.id !== undefined && ent.id !== null) {
                const idStr = String(ent.id);
                if (entityMap.has(idStr)) {
                    duplicateEntityIds.add(idStr);
                } else {
                    entityMap.set(idStr, ent);
                }
            }

            // Inspect components
            if (Array.isArray(ent.components)) {
                for (let i = 0; i < ent.components.length; i++) {
                    const comp = ent.components[i];
                    if (comp && typeof comp === "object") {
                        allComponents.push({ component: comp, entity: ent });
                        if (comp.id !== undefined && comp.id !== null) {
                            const cidStr = String(comp.id);
                            if (componentMap.has(cidStr)) {
                                duplicateComponentIds.add(cidStr);
                            } else {
                                componentMap.set(cidStr, { component: comp, entity: ent });
                            }
                        }
                    }
                }
            } else if (ent.components && typeof ent.components === "object") {
                // Dictionary of components
                for (const key of Object.keys(ent.components)) {
                    const comp = ent.components[key];
                    if (comp && typeof comp === "object") {
                        allComponents.push({ component: comp, entity: ent });
                        if (comp.id !== undefined && comp.id !== null) {
                            const cidStr = String(comp.id);
                            if (componentMap.has(cidStr)) {
                                duplicateComponentIds.add(cidStr);
                            } else {
                                componentMap.set(cidStr, { component: comp, entity: ent });
                            }
                        }
                    }
                }
            }

            // Inspect child entities
            if (Array.isArray(ent.children)) {
                for (let i = 0; i < ent.children.length; i++) {
                    const child = ent.children[i];
                    if (child && typeof child === "object") {
                        visitEntity(child);
                    }
                }
            }
        }

        function scan(obj) {
            if (!obj || typeof obj !== "object" || visited.has(obj)) return;

            if (Array.isArray(obj)) {
                for (let i = 0; i < obj.length; i++) {
                    const item = obj[i];
                    if (item && typeof item === "object") {
                        if (item.id !== undefined && (
                            item.components !== undefined ||
                            item.children !== undefined ||
                            item.parentId !== undefined ||
                            item.parent !== undefined ||
                            item.type === "Entity" ||
                            item.name !== undefined
                        )) {
                            visitEntity(item);
                        } else {
                            scan(item);
                        }
                    }
                }
                return;
            }

            if (Array.isArray(obj.entities)) {
                for (let i = 0; i < obj.entities.length; i++) {
                    visitEntity(obj.entities[i]);
                }
            }

            if (Array.isArray(obj.children)) {
                for (let i = 0; i < obj.children.length; i++) {
                    if (obj.children[i] && typeof obj.children[i] === "object") {
                        visitEntity(obj.children[i]);
                    }
                }
            }

            if (obj.state && typeof obj.state === "object") scan(obj.state);
            if (obj.scene && typeof obj.scene === "object") scan(obj.scene);
            if (obj.data && typeof obj.data === "object") scan(obj.data);

            if (obj.id !== undefined && (
                obj.components !== undefined ||
                obj.children !== undefined ||
                obj.parentId !== undefined ||
                obj.parent !== undefined
            )) {
                visitEntity(obj);
            }
        }

        scan(data);

        // Check dangling entity references
        for (let i = 0; i < allEntities.length; i++) {
            const ent = allEntities[i];
            const entId = ent.id !== undefined ? String(ent.id) : `[anonymous entity #${i}]`;

            // Parent reference check
            const parentRef = ent.parentId !== undefined && ent.parentId !== null && ent.parentId !== ""
                ? ent.parentId
                : (typeof ent.parent === "string" && ent.parent !== "" ? ent.parent : null);

            if (parentRef !== null && parentRef !== undefined) {
                const targetId = String(parentRef);
                if (ent.id !== undefined && String(ent.id) === targetId) {
                    dangling.push({
                        sourceId: entId,
                        sourceType: "entity",
                        field: "parentId",
                        targetId,
                        message: `Entity '${entId}' has cyclic self-referencing parentId '${targetId}'.`
                    });
                } else if (!entityMap.has(targetId)) {
                    dangling.push({
                        sourceId: entId,
                        sourceType: "entity",
                        field: "parentId",
                        targetId,
                        message: `Entity '${entId}' references non-existent parentId '${targetId}'.`
                    });
                }
            }

            // Check other reference fields on entity
            for (let f = 0; f < this.referenceFields.length; f++) {
                const field = this.referenceFields[f];
                if (field === "parentId" || field === "parent") continue;
                if (ent[field] !== undefined && ent[field] !== null && ent[field] !== "") {
                    const targetId = String(ent[field]);
                    if (!entityMap.has(targetId) && !componentMap.has(targetId)) {
                        dangling.push({
                            sourceId: entId,
                            sourceType: "entity",
                            field,
                            targetId,
                            message: `Entity '${entId}' has dangling reference in '${field}' pointing to non-existent '${targetId}'.`
                        });
                    }
                }
            }
        }

        // Check dangling component references
        for (let i = 0; i < allComponents.length; i++) {
            const { component, entity } = allComponents[i];
            const sourceId = component.id !== undefined ? String(component.id) : (entity?.id ? String(entity.id) : `[component #${i}]`);
            const compLabel = component.id ? `Component '${component.id}'` : `Component on entity '${entity?.id}'`;

            for (let f = 0; f < this.referenceFields.length; f++) {
                const field = this.referenceFields[f];
                if (component[field] !== undefined && component[field] !== null && component[field] !== "") {
                    const targetId = String(component[field]);
                    if (!entityMap.has(targetId) && !componentMap.has(targetId)) {
                        dangling.push({
                            sourceId,
                            sourceType: "component",
                            field,
                            targetId,
                            message: `${compLabel} has dangling reference in '${field}' pointing to non-existent '${targetId}'.`
                        });
                    }
                }
            }
        }

        const errors = [];
        for (const id of duplicateEntityIds) {
            errors.push(`Duplicate entity ID detected: '${id}'.`);
        }
        for (const id of duplicateComponentIds) {
            errors.push(`Duplicate component ID detected: '${id}'.`);
        }
        for (let i = 0; i < dangling.length; i++) {
            errors.push(dangling[i].message);
        }

        const result = {
            valid: errors.length === 0,
            errors,
            duplicates: {
                entities: Array.from(duplicateEntityIds),
                components: Array.from(duplicateComponentIds)
            },
            dangling,
            entityCount: allEntities.length,
            componentCount: allComponents.length
        };

        if (!result.valid && shouldThrow) {
            throw new ReferenceValidationError(result);
        }

        return result;
    }
}

/**
 * Versioned Save Engine providing sequential migrations, step verification,
 * atomic rollback on failure, future version detection, reference validation,
 * and corrupt JSON diagnostics/recovery.
 */
export class VersionedSaveEngine {
    /**
     * @param {Object} [options]
     */
    constructor(options) {
        const opts = options || {};
        this.currentVersion = Number.isInteger(opts.currentVersion) ? opts.currentVersion : 1;
        this.storage = opts.storage !== undefined
            ? opts.storage
            : (typeof globalThis.localStorage !== "undefined" ? globalThis.localStorage : new MapStorage());
        this.prefix = opts.prefix || "neptune.save";
        this.validateReferences = opts.validateReferences !== undefined ? Boolean(opts.validateReferences) : true;
        this.autoRecoverCorrupt = opts.autoRecoverCorrupt !== undefined ? Boolean(opts.autoRecoverCorrupt) : true;

        this.migrationRegistry = opts.migrations instanceof SchemaMigrationRegistry
            ? opts.migrations
            : new SchemaMigrationRegistry();

        if (opts.migrations && !(opts.migrations instanceof SchemaMigrationRegistry)) {
            if (Array.isArray(opts.migrations)) {
                for (let i = 0; i < opts.migrations.length; i++) {
                    const m = opts.migrations[i];
                    this.migrationRegistry.register(m.from, m.to, m.migrate, m);
                }
            } else if (typeof opts.migrations === "object") {
                for (const key of Object.keys(opts.migrations)) {
                    const fromV = Number.parseInt(key, 10);
                    if (Number.isInteger(fromV)) {
                        const val = opts.migrations[key];
                        if (typeof val === "function") {
                            this.migrationRegistry.register(fromV, val);
                        } else if (val && typeof val === "object" && typeof val.migrate === "function") {
                            this.migrationRegistry.register(fromV, val.to || (fromV + 1), val.migrate, val);
                        }
                    }
                }
            }
        }

        this.validator = opts.validator instanceof ReferenceValidator
            ? opts.validator
            : new ReferenceValidator(opts.validator);
    }

    /**
     * Build storage key for a save slot.
     * @param {string} slot
     * @returns {string}
     */
    key(slot) {
        if (typeof slot !== "string" || !slot.trim()) {
            throw new TypeError("Save slot must be a non-empty string.");
        }
        return `${this.prefix}.${encodeURIComponent(slot)}`;
    }

    /**
     * Register a schema migration.
     * @param {number} fromVersion
     * @param {number|Function} toVersionOrFn
     * @param {Function} [maybeFn]
     * @param {Object} [options]
     * @returns {VersionedSaveEngine}
     */
    registerMigration(fromVersion, toVersionOrFn, maybeFn, options) {
        this.migrationRegistry.register(fromVersion, toVersionOrFn, maybeFn, options);
        return this;
    }

    /**
     * Diagnose a corrupt JSON string and produce line, column, snippet, and reason.
     * @param {string} rawText
     * @param {Error} [syntaxError]
     * @returns {Object}
     */
    diagnoseCorruptJson(rawText, syntaxError) {
        if (typeof rawText !== "string") {
            return {
                position: 0,
                line: 1,
                column: 1,
                snippet: "",
                reason: "Input is not a string",
                message: "Corrupt JSON: input is not a string."
            };
        }

        const errMessage = syntaxError ? syntaxError.message : "";
        let position = null;

        const posMatch = errMessage.match(/position\s+(\d+)/i);
        if (posMatch) {
            position = Number.parseInt(posMatch[1], 10);
        } else {
            const lineColMatch = errMessage.match(/(\d+):(\d+)/);
            if (lineColMatch) {
                const targetLine = Number.parseInt(lineColMatch[1], 10);
                const targetCol = Number.parseInt(lineColMatch[2], 10);
                const lines = rawText.split("\n");
                let charCount = 0;
                for (let i = 0; i < targetLine - 1 && i < lines.length; i++) {
                    charCount += lines[i].length + 1;
                }
                position = charCount + targetCol - 1;
            }
        }

        if (position === null || position >= rawText.length) {
            if (/unexpected end/i.test(errMessage)) {
                position = Math.max(0, rawText.length);
            } else {
                position = 0;
            }
        }

        const lines = rawText.split("\n");
        let currentPos = 0;
        let line = 1;
        let column = 1;

        for (let i = 0; i < lines.length; i++) {
            const lineLen = lines[i].length + 1;
            if (currentPos + lineLen > position || i === lines.length - 1) {
                line = i + 1;
                column = Math.max(1, position - currentPos + 1);
                break;
            }
            currentPos += lineLen;
        }

        const lineContent = lines[line - 1] || "";
        const prefix = `Line ${line}: `;
        const pointerIndent = " ".repeat(prefix.length + Math.max(0, Math.min(column - 1, lineContent.length)));
        const snippet = `${prefix}${lineContent}\n${pointerIndent}^`;

        let reason = "Syntax error in JSON string.";
        if (/unexpected end/i.test(errMessage)) {
            reason = "Unexpected end of JSON input. The file was likely truncated during an interrupted save or crash.";
        } else if (/,(\s*[}\]])/.test(rawText)) {
            reason = "Illegal trailing comma before closing brace or bracket.";
        } else if (/'[^']*'/.test(rawText)) {
            reason = "Single quotes used instead of double quotes.";
        } else if (/expected property name/i.test(errMessage) || /expected double-quoted/i.test(errMessage)) {
            reason = "Unquoted or improperly quoted object property key.";
        }

        const message = `Corrupt JSON at line ${line}, column ${column}: ${reason}\n${snippet}`;

        return {
            position,
            line,
            column,
            snippet,
            reason,
            message,
            rawText,
            cause: syntaxError || null
        };
    }

    /**
     * Repair truncated JSON strings by closing open quotes and brackets.
     * @param {string} text
     * @returns {string|null}
     * @private
     */
    #repairTruncatedJson(text) {
        if (!text || typeof text !== "string") return null;
        const s = text.trim();
        if (!s) return null;

        let inString = false;
        let escaped = false;
        const stack = [];

        for (let i = 0; i < s.length; i++) {
            const char = s[i];
            if (inString) {
                if (escaped) {
                    escaped = false;
                } else if (char === "\\") {
                    escaped = true;
                } else if (char === '"') {
                    inString = false;
                }
            } else {
                if (char === '"') {
                    inString = true;
                } else if (char === "{" || char === "[") {
                    stack.push(char);
                } else if (char === "}") {
                    if (stack.length > 0 && stack[stack.length - 1] === "{") stack.pop();
                } else if (char === "]") {
                    if (stack.length > 0 && stack[stack.length - 1] === "[") stack.pop();
                }
            }
        }

        let repaired = s;
        if (inString) {
            repaired += '"';
        }

        repaired = repaired.replace(/,\s*$/, "");
        repaired = repaired.replace(/,(\s*[}\]])/g, "$1");

        while (stack.length > 0) {
            const open = stack.pop();
            repaired = repaired.replace(/,\s*$/, "");
            if (open === "{") repaired += "}";
            else if (open === "[") repaired += "]";
        }

        return repaired;
    }

    /**
     * Attempt recovery of corrupt JSON through heuristics and fallback backups.
     * @param {string} rawText
     * @param {Object} [options]
     * @returns {Object}
     */
    recoverCorruptJson(rawText, options) {
        if (typeof rawText !== "string") {
            throw new TypeError("rawText must be a string.");
        }

        const opts = options || {};

        // 1. Valid JSON check
        try {
            const parsed = JSON.parse(rawText);
            return {
                recovered: false,
                data: parsed,
                strategy: "none",
                message: "JSON is already valid."
            };
        } catch (parseError) {
            const diagnostic = this.diagnoseCorruptJson(rawText, parseError);

            // 2. Check backup if provided
            if (opts.backupText && typeof opts.backupText === "string") {
                try {
                    const backupData = JSON.parse(opts.backupText);
                    return {
                        recovered: true,
                        data: backupData,
                        strategy: "backup_slot",
                        diagnostic,
                        message: "Recovered from backup slot."
                    };
                } catch (_) {}
            }

            // 3. Strategy: Trailing comma removal
            const trailingCleaned = rawText.replace(/,(\s*[}\]])/g, "$1");
            if (trailingCleaned !== rawText) {
                try {
                    const data = JSON.parse(trailingCleaned);
                    return {
                        recovered: true,
                        data,
                        strategy: "trailing_comma_cleanup",
                        diagnostic,
                        message: "Recovered by removing trailing commas."
                    };
                } catch (_) {}
            }

            // 4. Strategy: Single quotes conversion
            const quoteNormalized = rawText
                .replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, '"$1"')
                .replace(/,(\s*[}\]])/g, "$1");
            if (quoteNormalized !== rawText) {
                try {
                    const data = JSON.parse(quoteNormalized);
                    return {
                        recovered: true,
                        data,
                        strategy: "quote_normalization",
                        diagnostic,
                        message: "Recovered by converting single quotes to double quotes."
                    };
                } catch (_) {}
            }

            // 5. Strategy: Truncated JSON repair
            const repaired = this.#repairTruncatedJson(rawText);
            if (repaired !== null) {
                try {
                    const data = JSON.parse(repaired);
                    return {
                        recovered: true,
                        data,
                        strategy: "truncated_json_repair",
                        diagnostic,
                        message: "Recovered truncated JSON by safely closing open structures."
                    };
                } catch (_) {}
            }

            // Unrecoverable
            if (opts.throwOnError !== false) {
                throw new CorruptSaveError(diagnostic.message, diagnostic);
            }

            return {
                recovered: false,
                data: null,
                strategy: "failed",
                diagnostic,
                message: "Could not recover corrupt JSON."
            };
        }
    }

    /**
     * Migrate a save record through sequential registered schema migrations.
     * Enforces step verification and atomic abort on errors.
     *
     * @param {Object} record
     * @param {number} [targetVersion]
     * @returns {Object}
     */
    migrate(record, targetVersion) {
        if (!record || typeof record !== "object") {
            throw new TypeError("Save record must be an object.");
        }

        const destVersion = Number.isInteger(targetVersion) ? targetVersion : this.currentVersion;
        const sourceVersion = record.schemaVersion !== undefined
            ? record.schemaVersion
            : (record.version !== undefined ? record.version : null);

        if (sourceVersion === null || sourceVersion === undefined) {
            throw new Error("Save record is missing schemaVersion.");
        }
        if (!Number.isInteger(sourceVersion)) {
            throw new TypeError(`Invalid schemaVersion: expected integer, got ${sourceVersion}.`);
        }

        // Future version detection
        if (sourceVersion > destVersion) {
            throw new FutureVersionError(sourceVersion, destVersion);
        }

        // Already at target version
        if (sourceVersion === destVersion) {
            return structuredClone(record);
        }

        const plan = this.migrationRegistry.getPlan(sourceVersion, destVersion);

        // Atomic: clone input so original record is never mutated if migration fails
        let currentRecord = structuredClone(record);

        for (let i = 0; i < plan.length; i++) {
            const step = plan[i];
            const snapshotBeforeStep = structuredClone(currentRecord);

            let migrated;
            try {
                migrated = step.migrate(snapshotBeforeStep, {
                    fromVersion: step.fromVersion,
                    toVersion: step.toVersion
                });
            } catch (err) {
                throw new MigrationError(
                    `Migration failed at step v${step.fromVersion} -> v${step.toVersion}: ${err.message}`,
                    {
                        fromVersion: step.fromVersion,
                        toVersion: step.toVersion,
                        step: i + 1,
                        cause: err
                    }
                );
            }

            // Step verification
            if (!migrated || typeof migrated !== "object") {
                throw new MigrationError(
                    `Step verification failed at step v${step.fromVersion} -> v${step.toVersion}: migration returned non-object.`,
                    { fromVersion: step.fromVersion, toVersion: step.toVersion, step: i + 1 }
                );
            }

            const stepResultVersion = migrated.schemaVersion !== undefined
                ? migrated.schemaVersion
                : (migrated.version !== undefined ? migrated.version : null);

            if (stepResultVersion !== step.toVersion) {
                throw new MigrationError(
                    `Step verification failed at step v${step.fromVersion} -> v${step.toVersion}: expected schemaVersion ${step.toVersion}, got ${stepResultVersion}.`,
                    { fromVersion: step.fromVersion, toVersion: step.toVersion, step: i + 1 }
                );
            }

            if (typeof step.verify === "function") {
                let verified = false;
                try {
                    verified = step.verify(migrated);
                } catch (verifyErr) {
                    throw new MigrationError(
                        `Step verification threw an error at step v${step.fromVersion} -> v${step.toVersion}: ${verifyErr.message}`,
                        { fromVersion: step.fromVersion, toVersion: step.toVersion, step: i + 1, cause: verifyErr }
                    );
                }
                if (verified === false) {
                    throw new MigrationError(
                        `Step verification failed custom check at step v${step.fromVersion} -> v${step.toVersion}.`,
                        { fromVersion: step.fromVersion, toVersion: step.toVersion, step: i + 1 }
                    );
                }
            }

            currentRecord = migrated;
        }

        return currentRecord;
    }

    /**
     * Validate references on entities and components.
     * @param {Object} data
     * @param {Object} [options]
     * @returns {Object}
     */
    validate(data, options) {
        return this.validator.validate(data, options);
    }

    /**
     * Save data into a named storage slot with backup and reference validation.
     * @param {string} slot
     * @param {Object} data
     * @param {Object} [options]
     * @returns {Object}
     */
    save(slot, data, options) {
        const opts = options || {};
        if (typeof slot !== "string" || !slot.trim()) {
            throw new TypeError("Save slot must be a non-empty string.");
        }
        if (!data || typeof data !== "object") {
            throw new TypeError("Game state to save must be an object.");
        }

        const shouldValidate = opts.validateReferences !== undefined
            ? opts.validateReferences
            : this.validateReferences;

        if (shouldValidate) {
            this.validator.validate(data, { throwOnError: true });
        }

        const clonedData = structuredClone(data);
        const record = Array.isArray(clonedData)
            ? {
                schemaVersion: this.currentVersion,
                savedAt: Date.now(),
                entities: clonedData
            }
            : {
                schemaVersion: this.currentVersion,
                savedAt: Date.now(),
                ...clonedData
            };

        let text;
        try {
            text = JSON.stringify(record, null, opts.pretty ? 2 : 0);
        } catch (err) {
            throw new Error(`Failed to serialize save data: ${err.message}`);
        }

        const key = this.key(slot);
        if (this.storage) {
            const existing = this.storage.getItem(key);
            if (existing !== null) {
                this.storage.setItem(`${key}.bak`, existing);
            }
            this.storage.setItem(key, text);
        }

        return record;
    }

    /**
     * Load, migrate, and validate save data from a slot or raw JSON text.
     * @param {string|Object} slotOrRaw
     * @param {Object} [options]
     * @returns {Object|null}
     */
    load(slotOrRaw, options) {
        const opts = options || {};
        const shouldValidate = opts.validateReferences !== undefined
            ? opts.validateReferences
            : this.validateReferences;
        const autoRecover = opts.autoRecoverCorrupt !== undefined
            ? opts.autoRecoverCorrupt
            : this.autoRecoverCorrupt;

        let rawText = null;
        let slotKey = null;
        let parsedRecord = null;

        if (typeof slotOrRaw === "string") {
            const trimmed = slotOrRaw.trim();
            if (opts.raw === true || trimmed.startsWith("{") || trimmed.startsWith("[")) {
                rawText = slotOrRaw;
            } else {
                slotKey = this.key(slotOrRaw);
                const stored = this.storage ? this.storage.getItem(slotKey) : null;
                if (stored !== null) {
                    rawText = stored;
                } else if (/[\s{}[\]"':]/.test(trimmed)) {
                    // Not in storage and contains spaces or syntax chars: treat as raw text
                    rawText = slotOrRaw;
                } else {
                    if (opts.required) {
                        throw new Error(`Save slot '${slotOrRaw}' does not exist.`);
                    }
                    return null;
                }
            }
        } else if (slotOrRaw && typeof slotOrRaw === "object") {
            parsedRecord = slotOrRaw;
        } else {
            throw new TypeError("load() expects a slot name string, raw JSON string, or object.");
        }

        if (rawText !== null) {
            let backupText = null;
            if (slotKey && this.storage) {
                backupText = this.storage.getItem(`${slotKey}.bak`);
            }

            if (autoRecover) {
                const recovery = this.recoverCorruptJson(rawText, {
                    backupText,
                    throwOnError: true
                });
                parsedRecord = recovery.data;
            } else {
                try {
                    parsedRecord = JSON.parse(rawText);
                } catch (err) {
                    const diag = this.diagnoseCorruptJson(rawText, err);
                    throw new CorruptSaveError(diag.message, diag);
                }
            }
        }

        if (!parsedRecord || typeof parsedRecord !== "object") {
            throw new CorruptSaveError("Save data is empty or not a valid object.");
        }

        const targetVersion = Number.isInteger(opts.targetVersion)
            ? opts.targetVersion
            : this.currentVersion;

        // Run sequential migrations with step verification and atomic abort
        const migratedRecord = this.migrate(parsedRecord, targetVersion);

        // Validate references on migrated state
        if (shouldValidate) {
            this.validator.validate(migratedRecord, { throwOnError: true });
        }

        if (opts.returnRecord || opts.returnEnvelope) {
            return migratedRecord;
        }

        return migratedRecord;
    }

    /**
     * List all save slots currently present in storage.
     * @returns {string[]}
     */
    slots() {
        if (!this.storage) return [];
        const keys = typeof this.storage.keys === "function"
            ? this.storage.keys()
            : Array.from({ length: this.storage.length || 0 }, (_, i) => this.storage.key(i));
        const prefixDot = `${this.prefix}.`;
        return keys
            .filter(k => k && k.startsWith(prefixDot) && !k.endsWith(".bak"))
            .map(k => decodeURIComponent(k.slice(prefixDot.length)));
    }

    /**
     * Remove a save slot and its backup from storage.
     * @param {string} slot
     */
    remove(slot) {
        if (!this.storage) return;
        const key = this.key(slot);
        this.storage.removeItem(key);
        this.storage.removeItem(`${key}.bak`);
    }

    /**
     * Check if a save slot exists in storage.
     * @param {string} slot
     * @returns {boolean}
     */
    has(slot) {
        if (!this.storage) return false;
        return this.storage.getItem(this.key(slot)) !== null;
    }
}