@aura3d/core 1.0.6

package/dist/VersionedSerialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VersionedSerialization.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/VersionedSerialization.ts"],"names":[],"mappings":"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"}

package/dist/VersionedSerialization.js

@@ -0,0 +1,278 @@
+import { ValidationError } from "./Errors.js";
+export class VersionedSchema {
+    name;
+    version;
+    fields = new Map();
+    constructor(name, version) {
+        this.name = name;
+        this.version = version;
+        if (!name.trim())
+            throw new ValidationError("SCHEMA_NAME", "VersionedSchema requires a non-empty name.");
+        if (!Number.isSafeInteger(version) || version < 0)
+            throw new ValidationError("SCHEMA_VERSION", "VersionedSchema version must be a non-negative integer.");
+    }
+    addField(field) {
+        if (!field.name.trim())
+            throw new ValidationError("SCHEMA_FIELD", "Schema field requires a non-empty name.");
+        if (this.fields.has(field.name))
+            throw new ValidationError("SCHEMA_FIELD_DUPLICATE", `Duplicate schema field: ${field.name}`);
+        if (field.kind === "array" && !field.elementKind)
+            throw new ValidationError("SCHEMA_ARRAY_ELEMENT", `Array field ${field.name} requires elementKind.`);
+        this.fields.set(field.name, field);
+        return this;
+    }
+    getField(name) {
+        return this.fields.get(name);
+    }
+    getFields() {
+        return [...this.fields.values()];
+    }
+    validate(data) {
+        const issues = [];
+        if (!isRecord(data)) {
+            return { ok: false, issues: [`${this.name} must be an object.`] };
+        }
+        for (const field of this.fields.values()) {
+            const value = data[field.name];
+            if (value === undefined) {
+                if (field.required && field.defaultValue === undefined)
+                    issues.push(`${field.name} is required.`);
+                continue;
+            }
+            collectTypeIssues(value, field, field.name, issues);
+        }
+        return { ok: issues.length === 0, issues };
+    }
+    serialize(data) {
+        const validation = this.validate(data);
+        if (!validation.ok)
+            throw new ValidationError("SCHEMA_VALIDATE", validation.issues.join(" "));
+        const record = data;
+        const result = {};
+        for (const field of this.fields.values()) {
+            const value = record[field.name];
+            if (value !== undefined) {
+                result[field.name] = value;
+            }
+            else if (field.defaultValue !== undefined) {
+                result[field.name] = cloneValue(field.defaultValue);
+            }
+        }
+        return result;
+    }
+    deserialize(data) {
+        return this.serialize(data);
+    }
+    static builder(name, version) {
+        return new VersionedSchemaBuilder(name, version);
+    }
+}
+export class VersionedSchemaBuilder {
+    schema;
+    constructor(name, version) {
+        this.schema = new VersionedSchema(name, version);
+    }
+    boolean(name, options = {}) {
+        return this.field({ name, kind: "boolean", ...options });
+    }
+    int32(name, options = {}) {
+        return this.field({ name, kind: "int32", ...options });
+    }
+    uint32(name, options = {}) {
+        return this.field({ name, kind: "uint32", ...options });
+    }
+    float32(name, options = {}) {
+        return this.field({ name, kind: "float32", ...options });
+    }
+    string(name, options = {}) {
+        return this.field({ name, kind: "string", ...options });
+    }
+    array(name, elementKind, options = {}) {
+        return this.field({ name, kind: "array", elementKind, ...options });
+    }
+    object(name, schema, options = {}) {
+        return this.field({ name, kind: "object", schema, ...options });
+    }
+    field(field) {
+        this.schema.addField(field);
+        return this;
+    }
+    build() {
+        return this.schema;
+    }
+}
+export class MigrationRegistry {
+    migrations = new Map();
+    register(migration) {
+        if (!Number.isSafeInteger(migration.from) || !Number.isSafeInteger(migration.to) || migration.to <= migration.from) {
+            throw new ValidationError("MIGRATION_VERSION", "Migration must move from a lower integer version to a higher integer version.");
+        }
+        const list = this.migrations.get(migration.from) ?? [];
+        if (list.some((entry) => entry.to === migration.to)) {
+            throw new ValidationError("MIGRATION_DUPLICATE", `Duplicate migration path: ${migration.from} -> ${migration.to}`);
+        }
+        list.push(migration);
+        list.sort((left, right) => left.to - right.to);
+        this.migrations.set(migration.from, list);
+        return this;
+    }
+    canMigrate(from, to) {
+        try {
+            this.plan(from, to);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    migrate(data, from, to) {
+        let current = data;
+        for (const migration of this.plan(from, to)) {
+            current = migration.migrate(current);
+        }
+        return current;
+    }
+    list() {
+        return [...this.migrations.values()].flat().sort((left, right) => left.from - right.from || left.to - right.to);
+    }
+    plan(from, to) {
+        if (from === to)
+            return [];
+        if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from > to) {
+            throw new ValidationError("MIGRATION_TARGET", "Migration target must be an integer version greater than or equal to the source.");
+        }
+        const plan = [];
+        let current = from;
+        while (current < to) {
+            const next = (this.migrations.get(current) ?? []).find((migration) => migration.to <= to);
+            if (!next)
+                throw new ValidationError("MIGRATION_PATH", `No migration path from version ${current} to ${to}.`);
+            plan.push(next);
+            current = next.to;
+        }
+        return plan;
+    }
+}
+export class SaveSlot {
+    id;
+    data = null;
+    format = "json";
+    timestamp;
+    metadata = {};
+    compressed = false;
+    constructor(id, timestamp = Date.now()) {
+        this.id = id;
+        if (!id.trim())
+            throw new ValidationError("SAVE_SLOT_ID", "SaveSlot requires a non-empty id.");
+        this.timestamp = timestamp;
+    }
+    setData(data, format, options = {}) {
+        this.data = typeof data === "string" ? data : new Uint8Array(data);
+        this.format = format;
+        this.compressed = options.compressed ?? false;
+        this.timestamp = Date.now();
+    }
+    getData() {
+        return typeof this.data === "string" || this.data === null ? this.data : new Uint8Array(this.data);
+    }
+    getFormat() {
+        return this.format;
+    }
+    getTimestamp() {
+        return this.timestamp;
+    }
+    getMetadata() {
+        return { ...this.metadata };
+    }
+    setMetadata(metadata) {
+        this.metadata = { ...this.metadata, ...metadata };
+    }
+    isCompressed() {
+        return this.compressed;
+    }
+    getSize() {
+        if (this.data === null)
+            return 0;
+        return typeof this.data === "string" ? new TextEncoder().encode(this.data).byteLength : this.data.byteLength;
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            format: this.format,
+            timestamp: this.timestamp,
+            metadata: { ...this.metadata },
+            compressed: this.compressed,
+            data: this.data instanceof Uint8Array ? bytesToBase64(this.data) : this.data ?? ""
+        };
+    }
+    static fromJSON(serialized) {
+        const slot = new SaveSlot(serialized.id, serialized.timestamp);
+        slot.format = serialized.format;
+        slot.metadata = { ...serialized.metadata };
+        slot.compressed = serialized.compressed;
+        slot.data = serialized.format === "binary" ? base64ToBytes(serialized.data) : serialized.data;
+        return slot;
+    }
+}
+function collectTypeIssues(value, field, path, issues) {
+    if (!matchesKind(value, field.kind)) {
+        issues.push(`${path} expected ${field.kind}.`);
+        return;
+    }
+    if (field.kind === "array" && field.elementKind && Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            if (!matchesKind(entry, field.elementKind))
+                issues.push(`${path}[${index}] expected ${field.elementKind}.`);
+        });
+    }
+    if (field.kind === "object" && field.schema) {
+        const nested = field.schema.validate(value);
+        for (const issue of nested.issues)
+            issues.push(`${path}.${issue}`);
+    }
+}
+function matchesKind(value, kind) {
+    switch (kind) {
+        case "boolean":
+            return typeof value === "boolean";
+        case "int32":
+            return Number.isInteger(value) && Number(value) >= -2147483648 && Number(value) <= 2147483647;
+        case "uint32":
+            return Number.isInteger(value) && Number(value) >= 0 && Number(value) <= 4294967295;
+        case "float32":
+        case "float64":
+            return typeof value === "number" && Number.isFinite(value);
+        case "string":
+            return typeof value === "string";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+    }
+}
+function cloneValue(value) {
+    if (typeof structuredClone === "function")
+        return structuredClone(value);
+    return JSON.parse(JSON.stringify(value));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(bytes).toString("base64");
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function base64ToBytes(base64) {
+    if (typeof Buffer !== "undefined")
+        return new Uint8Array(Buffer.from(base64, "base64"));
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+//# sourceMappingURL=VersionedSerialization.js.map

package/dist/VersionedSerialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VersionedSerialization.js","sourceRoot":"","sources":["../../../../packages/core/src/VersionedSerialization.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./Engine.js";
+export * from "./EngineConfig.js";
+export * from "./EngineLoop.js";
+export * from "./Time.js";
+export * from "./FixedStepAccumulator.js";
+export * from "./EventBus.js";
+export * from "./Scheduler.js";
+export * from "./TaskQueue.js";
+export * from "./Logger.js";
+export * from "./Diagnostics.js";
+export * from "./Errors.js";
+export * from "./Disposable.js";
+export * from "./ResourceScope.js";
+export * from "./VersionedSerialization.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/core/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from "./Engine.js";
+export * from "./EngineConfig.js";
+export * from "./EngineLoop.js";
+export * from "./Time.js";
+export * from "./FixedStepAccumulator.js";
+export * from "./EventBus.js";
+export * from "./Scheduler.js";
+export * from "./TaskQueue.js";
+export * from "./Logger.js";
+export * from "./Diagnostics.js";
+export * from "./Errors.js";
+export * from "./Disposable.js";
+export * from "./ResourceScope.js";
+export * from "./VersionedSerialization.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/core/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC"}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@aura3d/core",
+  "version": "1.0.6",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aura3d/math": "1.0.6"
+  }
+}

package/src/Diagnostics.ts

@@ -0,0 +1,80 @@
+export type MetricKind = "counter" | "gauge" | "timing";
+
+export interface MetricSnapshot {
+  readonly kind: MetricKind;
+  readonly name: string;
+  readonly value: number;
+  readonly samples: readonly number[];
+}
+
+export interface DiagnosticsSnapshot {
+  readonly metrics: readonly MetricSnapshot[];
+  readonly timestamp: number;
+}
+
+interface MutableMetric {
+  kind: MetricKind;
+  value: number;
+  samples: number[];
+}
+
+export class Diagnostics {
+  private readonly metrics = new Map<string, MutableMetric>();
+  private readonly activeTimers = new Map<string, number>();
+
+  constructor(private readonly maxHistory = 120) {}
+
+  increment(name: string, amount = 1): void {
+    const metric = this.ensure(name, "counter");
+    metric.value += amount;
+    this.recordSample(metric, metric.value);
+  }
+
+  gauge(name: string, value: number): void {
+    const metric = this.ensure(name, "gauge");
+    metric.value = value;
+    this.recordSample(metric, value);
+  }
+
+  begin(name: string): void {
+    if (this.activeTimers.has(name)) throw new Error(`Timer ${name} already started.`);
+    this.activeTimers.set(name, performance.now());
+  }
+
+  end(name: string): number {
+    const start = this.activeTimers.get(name);
+    if (start === undefined) throw new Error(`Timer ${name} was not started.`);
+    this.activeTimers.delete(name);
+    const duration = performance.now() - start;
+    const metric = this.ensure(name, "timing");
+    metric.value = duration;
+    this.recordSample(metric, duration);
+    return duration;
+  }
+
+  snapshot(): DiagnosticsSnapshot {
+    const metrics = [...this.metrics.entries()].map(([name, metric]) => Object.freeze({
+      kind: metric.kind,
+      name,
+      value: metric.value,
+      samples: Object.freeze([...metric.samples])
+    }));
+    return Object.freeze({ metrics: Object.freeze(metrics), timestamp: Date.now() });
+  }
+
+  private ensure(name: string, kind: MetricKind): MutableMetric {
+    const existing = this.metrics.get(name);
+    if (existing) {
+      if (existing.kind !== kind) throw new Error(`Metric ${name} already exists as ${existing.kind}.`);
+      return existing;
+    }
+    const metric: MutableMetric = { kind, value: 0, samples: [] };
+    this.metrics.set(name, metric);
+    return metric;
+  }
+
+  private recordSample(metric: MutableMetric, value: number): void {
+    metric.samples.push(value);
+    if (metric.samples.length > this.maxHistory) metric.samples.shift();
+  }
+}

package/src/Disposable.ts

@@ -0,0 +1,41 @@
+export interface Disposable {
+  dispose(): void | Promise<void>;
+}
+
+export function isDisposable(value: unknown): value is Disposable {
+  return typeof value === "object" && value !== null && "dispose" in value && typeof (value as Disposable).dispose === "function";
+}
+
+export class DisposableStack implements Disposable {
+  private readonly entries: Disposable[] = [];
+  private disposed = false;
+
+  use<T extends Disposable>(resource: T): T {
+    if (this.disposed) {
+      throw new Error("Cannot add a disposable to an already disposed stack.");
+    }
+    this.entries.push(resource);
+    return resource;
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    const errors: unknown[] = [];
+    while (this.entries.length > 0) {
+      const entry = this.entries.pop();
+      if (!entry) continue;
+      try {
+        await entry.dispose();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, "One or more disposables failed.");
+  }
+}

package/src/Engine.ts

@@ -0,0 +1,140 @@
+import { DisposableStack } from "./Disposable.js";
+import { EngineLoop, type FrameContext } from "./EngineLoop.js";
+import { resolveEngineConfig, type EngineConfig, type ResolvedEngineConfig } from "./EngineConfig.js";
+import { LifecycleError } from "./Errors.js";
+import { EventBus } from "./EventBus.js";
+import { Diagnostics } from "./Diagnostics.js";
+import { Logger } from "./Logger.js";
+import { ResourceScope } from "./ResourceScope.js";
+import { Scheduler, SystemPhase } from "./Scheduler.js";
+import { TaskQueue } from "./TaskQueue.js";
+
+export type EngineState = "created" | "initializing" | "initialized" | "running" | "stopped" | "disposed" | "failed";
+
+export interface EngineEvents {
+  stateChanged: { readonly previous: EngineState; readonly current: EngineState };
+  frame: FrameContext;
+  error: unknown;
+}
+
+export interface EnginePlugin {
+  readonly id: string;
+  init?(engine: Engine): void | Promise<void>;
+  dispose?(): void | Promise<void>;
+}
+
+export class Engine {
+  readonly config: ResolvedEngineConfig;
+  readonly events = new EventBus<EngineEvents>((error) => this.events.emit("error", error));
+  readonly diagnostics = new Diagnostics();
+  readonly logger = new Logger();
+  readonly scheduler = new Scheduler();
+  readonly tasks = new TaskQueue();
+  readonly resources = new ResourceScope("engine");
+
+  private readonly plugins: EnginePlugin[] = [];
+  private readonly pluginDisposables = new DisposableStack();
+  private readonly loop: EngineLoop;
+  private stateValue: EngineState = "created";
+
+  constructor(config: EngineConfig = {}) {
+    this.config = resolveEngineConfig(config);
+    this.loop = new EngineLoop({
+      mode: "manual",
+      fixedDelta: this.config.fixedDelta,
+      maxDelta: this.config.maxDelta,
+      maxFixedSteps: this.config.maxFixedSteps,
+      timeScale: this.config.timeScale
+    }, (context) => this.runFrame(context));
+  }
+
+  get state(): EngineState {
+    return this.stateValue;
+  }
+
+  use(plugin: EnginePlugin): this {
+    if (this.stateValue !== "created") throw new LifecycleError("PLUGIN_AFTER_INIT", "Plugins must be registered before init.");
+    if (this.plugins.some((existing) => existing.id === plugin.id)) throw new LifecycleError("DUPLICATE_PLUGIN", `Plugin ${plugin.id} already registered.`);
+    this.plugins.push(plugin);
+    return this;
+  }
+
+  async init(): Promise<void> {
+    if (this.stateValue === "initialized" || this.stateValue === "running" || this.stateValue === "stopped") return;
+    if (this.stateValue !== "created") throw new LifecycleError("INVALID_INIT", `Cannot init engine from ${this.stateValue}.`);
+    this.setState("initializing");
+    try {
+      for (const plugin of this.plugins) {
+        await plugin.init?.(this);
+        if (plugin.dispose) this.pluginDisposables.use({ dispose: () => plugin.dispose?.() });
+      }
+      this.setState("initialized");
+      if (this.config.autoStart) this.start();
+    } catch (error) {
+      this.setState("failed");
+      await this.pluginDisposables.dispose();
+      throw error;
+    }
+  }
+
+  start(): void {
+    if (this.stateValue !== "initialized" && this.stateValue !== "stopped") throw new LifecycleError("START_BEFORE_INIT", "Engine must be initialized before start.");
+    this.loop.start();
+    this.setState("running");
+  }
+
+  stop(): void {
+    if (this.stateValue !== "running") return;
+    this.loop.stop();
+    this.setState("stopped");
+  }
+
+  async step(delta: number): Promise<FrameContext> {
+    if (this.stateValue === "created") await this.init();
+    if (this.stateValue !== "initialized" && this.stateValue !== "running" && this.stateValue !== "stopped") {
+      throw new LifecycleError("STEP_INVALID_STATE", `Cannot step engine from ${this.stateValue}.`);
+    }
+    return this.loop.step(delta);
+  }
+
+  async dispose(): Promise<void> {
+    if (this.stateValue === "disposed") return;
+    if (this.stateValue === "running") this.stop();
+    const errors: unknown[] = [];
+    try {
+      await this.pluginDisposables.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+    try {
+      await this.resources.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+    this.events.clear();
+    this.setState("disposed");
+    if (errors.length > 0) throw new AggregateError(errors, "Engine disposal failed.");
+  }
+
+  private async runFrame(context: FrameContext): Promise<void> {
+    this.diagnostics.increment("frames");
+    await this.scheduler.runPhase(SystemPhase.Platform);
+    await this.scheduler.runPhase(SystemPhase.Tasks);
+    await this.tasks.flush();
+    for (let step = 0; step < context.fixedSteps; step++) {
+      await this.scheduler.runPhase(SystemPhase.Fixed, step);
+    }
+    await this.scheduler.runPhase(SystemPhase.Update);
+    await this.scheduler.runPhase(SystemPhase.Scene);
+    await this.scheduler.runPhase(SystemPhase.Render);
+    await this.scheduler.runPhase(SystemPhase.Present);
+    await this.scheduler.runPhase(SystemPhase.Cleanup);
+    this.events.emit("frame", context);
+  }
+
+  private setState(next: EngineState): void {
+    const previous = this.stateValue;
+    this.stateValue = next;
+    this.events.emit("stateChanged", Object.freeze({ previous, current: next }));
+  }
+}

package/src/EngineConfig.ts

@@ -0,0 +1,38 @@
+import { ValidationError } from "./Errors.js";
+
+export interface EngineConfig {
+  targetFPS?: number;
+  fixedDelta?: number;
+  maxDelta?: number;
+  maxFixedSteps?: number;
+  timeScale?: number;
+  autoStart?: boolean;
+}
+
+export interface ResolvedEngineConfig {
+  readonly targetFPS: number;
+  readonly fixedDelta: number;
+  readonly maxDelta: number;
+  readonly maxFixedSteps: number;
+  readonly timeScale: number;
+  readonly autoStart: boolean;
+}
+
+export function resolveEngineConfig(config: EngineConfig = {}): ResolvedEngineConfig {
+  const resolved = {
+    targetFPS: config.targetFPS ?? 60,
+    fixedDelta: config.fixedDelta ?? 1 / 60,
+    maxDelta: config.maxDelta ?? 0.25,
+    maxFixedSteps: config.maxFixedSteps ?? 5,
+    timeScale: config.timeScale ?? 1,
+    autoStart: config.autoStart ?? false
+  };
+
+  if (!Number.isFinite(resolved.targetFPS) || resolved.targetFPS <= 0) throw new ValidationError("INVALID_TARGET_FPS", "targetFPS must be positive.");
+  if (!Number.isFinite(resolved.fixedDelta) || resolved.fixedDelta <= 0) throw new ValidationError("INVALID_FIXED_DELTA", "fixedDelta must be positive.");
+  if (!Number.isFinite(resolved.maxDelta) || resolved.maxDelta <= 0) throw new ValidationError("INVALID_MAX_DELTA", "maxDelta must be positive.");
+  if (!Number.isInteger(resolved.maxFixedSteps) || resolved.maxFixedSteps <= 0) throw new ValidationError("INVALID_MAX_FIXED_STEPS", "maxFixedSteps must be a positive integer.");
+  if (!Number.isFinite(resolved.timeScale) || resolved.timeScale < 0) throw new ValidationError("INVALID_TIME_SCALE", "timeScale must be finite and non-negative.");
+
+  return Object.freeze(resolved);
+}