rn-gamekit 0.1.0 → 0.2.0

package/src/storage/store.ts

@@ -0,0 +1,380 @@
+import { GameStorageError, storageError } from './errors';
+import type { CreateGameSaveStoreOptions, GameSaveLoadResult, GameSaveStore } from './types';
+import { STORAGE_LIMITS } from './types';
+import { storageKey, legacyStorageKey, validateNamespace, validateSlot } from './validation';
+import { createDefaultData, migratePayload, validateCurrentData } from './schema';
+import { cloneAndValidatePlainData, parseEnvelope, serializeEnvelope, utf8ByteLength, STORAGE_ENVELOPE_FORMAT } from './serialization';
+import type { StoredGameEnvelope } from './types';
+
+export function createGameSaveStore<TData>(options: CreateGameSaveStoreOptions<TData>): GameSaveStore<TData> {
+  const schema = options.schema;
+  const adapter = options.adapter;
+  const namespace = options.namespace;
+
+  validateNamespace(namespace);
+
+  // Per-slot serialized queue: slot -> tail promise. Retained until every accepted operation settles.
+  const slotQueues = new Map<string, Promise<void>>();
+  // Active operation promises for flush() snapshotting. Each flush gets its own immutable snapshot.
+  const active = new Set<Promise<void>>();
+
+  let disposed = false;
+
+  function track<T>(p: Promise<T>): Promise<T> {
+    const wrapped = p.finally(() => {
+      active.delete(wrapped as unknown as Promise<void>);
+    });
+    active.add(wrapped as unknown as Promise<void>);
+    return wrapped;
+  }
+
+  function enqueue<T>(slot: string, op: () => Promise<T>): Promise<T> {
+    // Acceptance boundary is the successful public method call; already-accepted ops are never cancelled by later dispose.
+    const tail = slotQueues.get(slot) ?? Promise.resolve();
+    let resolveTail: () => void = () => {};
+    const nextTail = new Promise<void>((res) => {
+      resolveTail = res;
+    });
+    slotQueues.set(slot, nextTail);
+
+    const run = tail
+      .catch(() => {
+        // Previous failure does not block next; continue
+      })
+      .then(() => op())
+      .finally(() => {
+        // Clean only when this tail is still the current tail; otherwise a newer operation has already replaced it.
+        if (slotQueues.get(slot) === nextTail) {
+          slotQueues.delete(slot);
+        }
+        resolveTail();
+      });
+
+    // Ensure nextTail mirrors run settlement without creating an unhandled rejection.
+    run.then(() => {}, () => {});
+
+    return track(run);
+  }
+
+  async function loadInternal(slot: string): Promise<GameSaveLoadResult<TData>> {
+    validateSlot(slot);
+    const key = storageKey(namespace, slot);
+    let raw: string | undefined;
+    try {
+      raw = await adapter.read(key);
+    } catch (cause) {
+      throw storageError(`backend read failed for slot "${slot}"`, 'BACKEND_READ_FAILED', {
+        operation: 'load',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+    // GS-STORAGE-01: read-only legacy fallback — pre-upgrade records load
+    // without any rewrite. A v2 miss costs one extra read for heritage.
+    if (raw === undefined) {
+      try {
+        raw = await adapter.read(legacyStorageKey(namespace, slot));
+      } catch (cause) {
+        throw storageError(`backend read failed for slot "${slot}"`, 'BACKEND_READ_FAILED', {
+          operation: 'load',
+          namespace,
+          slot,
+          cause,
+        });
+      }
+    }
+    if (raw === undefined) {
+      const data = createDefaultData(schema);
+      return { status: 'default', data };
+    }
+
+    // F3: measure raw UTF-8 byte length before JSON.parse and reject oversized records.
+    const rawBytes = utf8ByteLength(raw);
+    if (rawBytes > STORAGE_LIMITS.MAX_SERIALIZED_BYTES) {
+      throw storageError(`stored record for slot "${slot}" exceeds ${STORAGE_LIMITS.MAX_SERIALIZED_BYTES} bytes (got ${rawBytes})`, 'SIZE_EXCEEDED', {
+        operation: 'load',
+        namespace,
+        slot,
+        schemaId: schema.id,
+        schemaVersion: schema.version,
+        path: 'envelope',
+      });
+    }
+
+    // Validate loaded bytes as untrusted before migration
+    let envelope: StoredGameEnvelope;
+    try {
+      envelope = parseEnvelope(raw);
+    } catch (cause) {
+      if (cause instanceof GameStorageError) {
+        throw new GameStorageError((cause as GameStorageError).message, {
+          code: (cause as GameStorageError).code,
+          operation: 'load',
+          namespace,
+          slot,
+          schemaId: schema.id,
+          schemaVersion: schema.version,
+          path: (cause as GameStorageError).path,
+          cause: (cause as GameStorageError).cause ?? cause,
+        });
+      }
+      throw storageError(`corrupt envelope for slot "${slot}"`, 'CORRUPT_ENVELOPE', {
+        operation: 'load',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+
+    if (envelope.schemaId !== schema.id) {
+      throw storageError(`schema id mismatch: expected "${schema.id}" got "${envelope.schemaId}"`, 'SCHEMA_ID_MISMATCH', {
+        operation: 'load',
+        namespace,
+        slot,
+        schemaId: schema.id,
+        schemaVersion: schema.version,
+      });
+    }
+    if (!Number.isSafeInteger(envelope.schemaVersion) || envelope.schemaVersion < 1) {
+      throw storageError(`corrupt envelope: invalid schemaVersion`, 'CORRUPT_ENVELOPE', {
+        operation: 'load',
+        namespace,
+        slot,
+        schemaId: schema.id,
+      });
+    }
+    if (envelope.schemaVersion > schema.version) {
+      throw storageError(`stored version ${envelope.schemaVersion} is newer than current ${schema.version}`, 'FUTURE_VERSION', {
+        operation: 'load',
+        namespace,
+        slot,
+        schemaId: schema.id,
+        schemaVersion: schema.version,
+      });
+    }
+
+    // F3: bounded plain-data validation of the loaded payload BEFORE any migration sees it.
+    try {
+      cloneAndValidatePlainData(envelope.payload, 'payload');
+    } catch (cause) {
+      if (cause instanceof GameStorageError) {
+        throw new GameStorageError((cause as GameStorageError).message, {
+          code: (cause as GameStorageError).code,
+          operation: 'load',
+          namespace,
+          slot,
+          schemaId: schema.id,
+          schemaVersion: schema.version,
+          path: (cause as GameStorageError).path,
+          cause: (cause as GameStorageError).cause ?? cause,
+        });
+      }
+      throw storageError(`payload validation failed`, 'VALIDATION_FAILED', {
+        operation: 'load',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+
+    // Migrate if needed — each migration receives a deeply frozen engine-owned input and its output is bounded-cloned/frozen.
+    let payload: unknown = envelope.payload;
+    let fromVersion = envelope.schemaVersion;
+    let toVersion = schema.version;
+    let migrated = false;
+    if (fromVersion !== toVersion) {
+      try {
+        const result = migratePayload(schema, fromVersion, payload);
+        payload = result.data;
+        fromVersion = result.fromVersion;
+        toVersion = result.toVersion;
+        migrated = true;
+      } catch (cause) {
+        if (cause instanceof GameStorageError) {
+          throw new GameStorageError((cause as GameStorageError).message, {
+            code: (cause as GameStorageError).code,
+            operation: 'load',
+            namespace,
+            slot,
+            schemaId: schema.id,
+            schemaVersion: schema.version,
+            path: (cause as GameStorageError).path,
+            cause: (cause as GameStorageError).cause ?? cause,
+          });
+        }
+        throw storageError(`migration failed`, 'MIGRATION_FAILED', {
+          operation: 'load',
+          namespace,
+          slot,
+          cause,
+        });
+      }
+    }
+
+    // Final validation — never overwrites stored record on failure
+    let data: TData;
+    try {
+      data = validateCurrentData(schema, payload, 'payload');
+    } catch (cause) {
+      if (cause instanceof GameStorageError) {
+        throw new GameStorageError(cause.message, {
+          code: 'VALIDATION_FAILED',
+          operation: 'load',
+          namespace,
+          slot,
+          schemaId: schema.id,
+          schemaVersion: schema.version,
+          path: cause.path,
+          cause: cause.cause ?? cause,
+        });
+      }
+      throw storageError(`final validation failed`, 'VALIDATION_FAILED', {
+        operation: 'load',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+
+    if (migrated) {
+      return { status: 'migrated', data, fromVersion: envelope.schemaVersion, toVersion };
+    }
+    return { status: 'stored', data };
+  }
+
+  async function saveInternal(slot: string, data: TData): Promise<void> {
+    validateSlot(slot);
+    // GS-STORAGE-02: save() already validated, normalized, cloned, and
+    // froze this snapshot at acceptance — re-running domain validation
+    // here would double-apply normalizing validators. Serialization still
+    // bounds-checks the bytes at its own boundary.
+    const envelope: StoredGameEnvelope = {
+      format: STORAGE_ENVELOPE_FORMAT,
+      schemaId: schema.id,
+      schemaVersion: schema.version,
+      savedAtMs: Date.now(),
+      payload: data,
+    };
+    let serialized: string;
+    try {
+      serialized = serializeEnvelope(envelope);
+    } catch (cause) {
+      if (cause instanceof GameStorageError) {
+        throw new GameStorageError(cause.message, {
+          code: cause.code === 'SIZE_EXCEEDED' || cause.code === 'DEPTH_EXCEEDED' ? cause.code : 'SERIALIZATION_FAILED',
+          operation: 'save',
+          namespace,
+          slot,
+          schemaId: schema.id,
+          schemaVersion: schema.version,
+          path: cause.path,
+          cause: cause.cause ?? cause,
+        });
+      }
+      throw storageError(`serialization failed for slot "${slot}"`, 'SERIALIZATION_FAILED', {
+        operation: 'save',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+    const key = storageKey(namespace, slot);
+    try {
+      await adapter.write(key, serialized);
+    } catch (cause) {
+      throw storageError(`backend write failed for slot "${slot}"`, 'BACKEND_WRITE_FAILED', {
+        operation: 'save',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+  }
+
+  async function removeInternal(slot: string): Promise<void> {
+    validateSlot(slot);
+    // GS-STORAGE-01: delete the versioned record and its legacy heritage.
+    // Heritage deletion matches v1 shared-fate semantics for colliding
+    // pairs and converges to independence as pairs save under v2.
+    const key = storageKey(namespace, slot);
+    const legacyKey = legacyStorageKey(namespace, slot);
+    try {
+      await adapter.remove(key);
+      if (legacyKey !== key) {
+        await adapter.remove(legacyKey);
+      }
+    } catch (cause) {
+      throw storageError(`backend remove failed for slot "${slot}"`, 'BACKEND_REMOVE_FAILED', {
+        operation: 'remove',
+        namespace,
+        slot,
+        cause,
+      });
+    }
+  }
+
+  const store: GameSaveStore<TData> = {
+    get disposed() {
+      return disposed;
+    },
+    load(slot: string): Promise<GameSaveLoadResult<TData>> {
+      if (disposed) {
+        return Promise.reject(storageError(`store is disposed`, 'DISPOSED', { operation: 'load', namespace, slot }));
+      }
+      try {
+        validateSlot(slot);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+      return enqueue(slot, () => loadInternal(slot));
+    },
+    save(slot: string, data: TData): Promise<void> {
+      if (disposed) {
+        return Promise.reject(storageError(`store is disposed`, 'DISPOSED', { operation: 'save', namespace, slot }));
+      }
+      try {
+        validateSlot(slot);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+      // Snapshot synchronously so caller mutation after save() does not affect stored bytes
+      let snapshot: TData;
+      try {
+        snapshot = validateCurrentData(schema, data, 'data');
+      } catch (e) {
+        return Promise.reject(e);
+      }
+      return enqueue(slot, () => saveInternal(slot, snapshot));
+    },
+    remove(slot: string): Promise<void> {
+      if (disposed) {
+        return Promise.reject(storageError(`store is disposed`, 'DISPOSED', { operation: 'remove', namespace, slot }));
+      }
+      try {
+        validateSlot(slot);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+      return enqueue(slot, () => removeInternal(slot));
+    },
+    delete(slot: string): Promise<void> {
+      return (store as GameSaveStore<TData>).remove(slot);
+    },
+    async flush(): Promise<void> {
+      // Snapshot the currently tracked operation promises; do not let operations accepted after the call delay this flush.
+      const snapshot = Array.from(active);
+      if (snapshot.length === 0) return;
+      await Promise.allSettled(snapshot);
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      // Do not use generation to suppress already-accepted Promise results.
+      // Retain queue/tail ownership until every accepted operation settles; tails clean themselves when still current.
+      // New work is rejected at the public boundary above.
+    },
+  };
+
+  return store;
+}

package/src/storage/types.ts

@@ -0,0 +1,76 @@
+/**
+ * V1 storage contracts — game-owned projections, engine envelope, adapter.
+ */
+
+export interface GameSaveSchema<TData> {
+  readonly id: string;
+  readonly version: number;
+  readonly createDefault: () => TData;
+  readonly validate: (value: unknown) => TData;
+  readonly migrations: Readonly<Record<number, (value: unknown) => unknown>>;
+}
+
+export interface GameStorageAdapter {
+  read(key: string): Promise<string | undefined>;
+  write(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+export interface StoredGameEnvelope {
+  readonly format: 'rn-gamekit.save';
+  readonly schemaId: string;
+  readonly schemaVersion: number;
+  readonly savedAtMs: number;
+  readonly payload: unknown;
+}
+
+export type GameSaveLoadStatus = 'default' | 'stored' | 'migrated';
+
+export interface GameSaveLoadResult<TData> {
+  readonly status: GameSaveLoadStatus;
+  readonly data: TData;
+  /** Present only when status === 'migrated' */
+  readonly fromVersion?: number;
+  /** Present only when status === 'migrated' */
+  readonly toVersion?: number;
+}
+
+export interface CreateGameSaveStoreOptions<TData> {
+  readonly schema: GameSaveSchema<TData>;
+  readonly adapter: GameStorageAdapter;
+  readonly namespace: string;
+}
+
+export interface GameSaveStore<TData> {
+  load(slot: string): Promise<GameSaveLoadResult<TData>>;
+  save(slot: string, data: TData): Promise<void>;
+  /**
+   * Delete a slot's record (GS-STORAGE-04): `remove` is the canonical
+   * verb; `delete` is a same-behavior alias kept for preview
+   * compatibility. Removes the versioned record and its legacy heritage.
+   */
+  remove(slot: string): Promise<void>;
+  /** Alias for remove — both names are accepted. */
+  delete(slot: string): Promise<void>;
+  /**
+   * Drain operations accepted before the call (GS-STORAGE-04): snapshots
+   * the in-flight set, waits for every snapshot member to settle —
+   * including failures — and never waits for later work. Always resolves
+   * (never rejects): each operation's own returned promise carries its
+   * success or failure. Per-slot ordering is per store instance, not a
+   * global cross-store lock; disposal rejects new work while accepted
+   * work still settles normally.
+   */
+  flush(): Promise<void>;
+  dispose(): void;
+  readonly disposed: boolean;
+}
+
+export const STORAGE_LIMITS = {
+  MAX_SERIALIZED_BYTES: 262_144, // 256 KiB per slot
+  MAX_DEPTH: 16,
+  MAX_NODES: 4096,
+  MAX_ARRAY_LENGTH: 1024,
+  MAX_OBJECT_FIELDS: 1024,
+  MAX_STRING_LENGTH: 16_384,
+} as const;

package/src/storage/validation.ts

@@ -0,0 +1,102 @@
+import { GameStorageError, storageError } from './errors';
+
+const SCHEMA_ID_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i;
+const NAMESPACE_RE = /^[a-zA-Z0-9._-]+$/;
+const SLOT_RE = /^[a-zA-Z0-9._-]+$/;
+
+export function validateSchemaId(id: string): void {
+  if (typeof id !== 'string' || id.length === 0 || id.length > 128 || id.includes('\0')) {
+    throw storageError(`schema id must be a non-empty string 1..128 without null bytes`, 'INVALID_SCHEMA_ID', {
+      schemaId: String(id),
+    });
+  }
+  if (!SCHEMA_ID_RE.test(id)) {
+    throw storageError(`schema id "${id}" must be namespaced (e.g. com.example.game.save)`, 'INVALID_SCHEMA_ID', {
+      schemaId: id,
+    });
+  }
+  if (id.startsWith('.') || id.endsWith('.') || id.includes('..')) {
+    throw storageError(`schema id "${id}" has invalid dot placement`, 'INVALID_SCHEMA_ID', { schemaId: id });
+  }
+}
+
+export function validateVersion(version: number): void {
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw storageError(`schema version must be a positive safe integer`, 'INVALID_SCHEMA_VERSION', {
+      schemaVersion: version,
+    });
+  }
+}
+
+export function validateNamespace(namespace: string): void {
+  if (typeof namespace !== 'string' || namespace.length === 0 || namespace.length > 64 || namespace.includes('\0')) {
+    throw storageError(`namespace must be a non-empty string 1..64`, 'INVALID_NAMESPACE', { namespace });
+  }
+  if (!NAMESPACE_RE.test(namespace)) {
+    throw storageError(`namespace "${namespace}" contains invalid characters`, 'INVALID_NAMESPACE', { namespace });
+  }
+}
+
+export function validateSlot(slot: string): void {
+  if (typeof slot !== 'string' || slot.length === 0 || slot.length > 64 || slot.includes('\0')) {
+    throw storageError(`slot must be a non-empty string 1..64`, 'INVALID_SLOT', { slot });
+  }
+  if (!SLOT_RE.test(slot)) {
+    throw storageError(`slot "${slot}" contains invalid characters`, 'INVALID_SLOT', { slot });
+  }
+}
+
+export function validateMigrations(
+  migrations: Readonly<Record<number, (value: unknown) => unknown>>,
+  currentVersion: number,
+): void {
+  if (migrations === null || typeof migrations !== 'object' || Array.isArray(migrations)) {
+    throw new GameStorageError('migrations must be a plain record', { code: 'INVALID_MIGRATION' });
+  }
+  const proto = Object.getPrototypeOf(migrations);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new GameStorageError('migrations must be a plain record', { code: 'INVALID_MIGRATION' });
+  }
+  for (const [rawKey, fn] of Object.entries(migrations)) {
+    const n = Number(rawKey);
+    // GS-STORAGE-03: keys must be canonical — '01' and '1e0' normalize to
+    // 1 but would never be found by the numeric lookup, and two spellings
+    // of one version must not both be accepted (the canonicality check
+    // rejects every non-canonical spelling, so each version appears once).
+    if (!Number.isSafeInteger(n) || n < 1 || n >= currentVersion || String(n) !== rawKey) {
+      throw storageError(`migration key "${rawKey}" must be a canonical integer 1..${currentVersion - 1}`, 'INVALID_MIGRATION', {
+        path: `migrations.${rawKey}`,
+      });
+    }
+    if (typeof fn !== 'function') {
+      throw storageError(`migration ${n} must be a function`, 'INVALID_MIGRATION', { path: `migrations.${n}` });
+    }
+  }
+}
+
+export function storageKey(namespace: string, slot: string): string {
+  // GS-STORAGE-01: length-prefixed tuple — dots, slashes, and colons
+  // inside names can never collide across pairs. Format-versioned so
+  // future schemes route without guessing.
+  return `rn-gamekit.storage/v2/${namespace.length}:${namespace}/${slot.length}:${slot}`;
+}
+
+/**
+ * Recovery/compatibility policy (GS-STORAGE-01, preview release):
+ *
+ * - Writes go to v2 keys only. Reads try v2, then fall back to the legacy
+ *   dotted key, so pre-upgrade records load without any rewrite.
+ * - The first v2 save for a slot lazily migrates it; no blanket rewrite
+ *   ever runs, and legacy records are never deleted after an ambiguous
+ *   read (a legacy key cannot identify which pair wrote it).
+ * - `remove` deletes both the v2 and legacy keys. Under v1, colliding
+ *   pairs already shared one record (shared fate on delete); v2 converges
+ *   to independence as each pair saves. A pair that never saves under v2
+ *   keeps reading its legacy record until it does.
+ * - A legacy collision (`('game.a','b')` vs `('game','a.b')`) cannot be
+ *   disambiguated from the key alone: both pairs read the same heritage
+ *   record, exactly as v1 behaved. New writes never collide.
+ */
+export function legacyStorageKey(namespace: string, slot: string): string {
+  return `rn-gamekit.storage.${namespace}.${slot}`;
+}

package/src/storage.ts

@@ -0,0 +1 @@
+export * from './storage/index';

package/src/testing.ts

@@ -59,3 +59,7 @@ export class ManualFrameDriver implements FrameDriver {
     callback(timestampMs);
   }
 }
+
+// Test-only tilemap chunk-read instrumentation (T16-RF4): intentionally NOT
+// re-exported from rn-gamekit/tilemap.
+export { __resetChunkReadStats, __chunkReadCount } from './tilemap/chunkStats';

package/src/tilemap/chunkStats.ts

@@ -0,0 +1,24 @@
+/**
+ * Test-only chunk-read instrumentation (T16-F6/T16-RF4).
+ *
+ * Lives OUTSIDE the public `rn-gamekit/tilemap` entry: the counters are
+ * re-exported only through the `rn-gamekit/testing` subpath so published
+ * diagnostics never leak double-underscore seams into app code.
+ */
+
+let chunkReads = 0;
+
+/** Internal: record one chunk-region lookup. */
+export function recordChunkRead(): void {
+  chunkReads += 1;
+}
+
+/** Test-only: reset the chunk-visit counter. */
+export function __resetChunkReadStats(): void {
+  chunkReads = 0;
+}
+
+/** Test-only: number of chunk lookups since the last reset. */
+export function __chunkReadCount(): number {
+  return chunkReads;
+}