@joystyk/storage 0.0.0-stage → 0.2.0

package/dist/memory.d.ts

@@ -0,0 +1,23 @@
+import { type StorageBackend, type StoreName } from './backend.js';
+export type MemoryBackendOptions = {
+    /**
+     * Simulates a storage quota: a write fails with `QuotaExceeded` when the stored keys and
+     * JSON text would exceed this many UTF-16 code units. Unlimited when absent.
+     */
+    readonly quota?: number;
+};
+/** A `StorageBackend` with read access to its raw contents, for tests. */
+export interface MemoryBackend extends StorageBackend {
+    /** Writes a raw value with no checks, as a corrupted or older database would hold it. */
+    poke(store: StoreName, key: string, value: unknown): void;
+    /** The raw value, or `undefined`. */
+    peek(store: StoreName, key: string): unknown;
+    /** The space in use, in the units `quota` counts. */
+    used(): number;
+}
+/**
+ * An in-memory backend for unit tests and server rendering, where there is no IndexedDB.
+ * It copies values on the way in and out, as IndexedDB's structured clone does, so a caller
+ * that mutates a value it read can't change what is stored.
+ */
+export declare const createMemoryBackend: (options?: MemoryBackendOptions) => MemoryBackend;

package/dist/memory.js

@@ -0,0 +1,65 @@
+import { MESSAGES, STORE_NAMES, storageError } from "./backend.js";
+import { err, ok } from "@joystyk/contracts";
+//#region src/memory.ts
+var { structuredClone } = globalThis;
+var copy = (value) => structuredClone(value);
+var sizeOf = (key, value) => key.length + (JSON.stringify(value)?.length ?? 0);
+/**
+* An in-memory backend for unit tests and server rendering, where there is no IndexedDB.
+* It copies values on the way in and out, as IndexedDB's structured clone does, so a caller
+* that mutates a value it read can't change what is stored.
+*/
+var createMemoryBackend = (options = {}) => {
+	const stores = new Map(STORE_NAMES.map((name) => [name, /* @__PURE__ */ new Map()]));
+	const store = (name) => {
+		const found = stores.get(name);
+		if (found === void 0) throw new Error(`Unknown store "${name}"`);
+		return found;
+	};
+	const used = () => {
+		let total = 0;
+		for (const entries of stores.values()) for (const [key, value] of entries) total += sizeOf(key, value);
+		return total;
+	};
+	const put = (name, key, value) => {
+		const entries = store(name);
+		if (options.quota !== void 0) {
+			const previous = entries.has(key) ? sizeOf(key, entries.get(key)) : 0;
+			if (used() - previous + sizeOf(key, value) > options.quota) return err(storageError("QuotaExceeded", MESSAGES.QuotaExceeded));
+		}
+		entries.set(key, copy(value));
+		return ok(void 0);
+	};
+	return {
+		get: async (name, key) => ok(copy(store(name).get(key))),
+		put: async (name, key, value) => put(name, key, value),
+		putIfAbsent: async (name, key, value) => {
+			const existing = store(name).get(key);
+			if (existing !== void 0) return ok({
+				written: false,
+				value: copy(existing)
+			});
+			const written = put(name, key, value);
+			return written.ok ? ok({ written: true }) : written;
+		},
+		delete: async (name, key) => {
+			store(name).delete(key);
+			return ok(void 0);
+		},
+		keys: async (name, prefix) => ok([...store(name).keys()].filter((key) => key.startsWith(prefix)).sort((a, b) => a < b ? -1 : a > b ? 1 : 0)),
+		clear: async (name) => {
+			store(name).clear();
+			return ok(void 0);
+		},
+		close: () => {},
+		poke: (name, key, value) => {
+			store(name).set(key, value);
+		},
+		peek: (name, key) => store(name).get(key),
+		used
+	};
+};
+//#endregion
+export { createMemoryBackend };
+
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","names":[],"sources":["../src/memory.ts"],"sourcesContent":["import { err, ok, type Json, type Result } from '@joystyk/contracts';\nimport {\n  MESSAGES,\n  STORE_NAMES,\n  storageError,\n  type StorageBackend,\n  type StorageError,\n  type StoreName,\n} from './backend.ts';\n\nexport type MemoryBackendOptions = {\n  /**\n   * Simulates a storage quota: a write fails with `QuotaExceeded` when the stored keys and\n   * JSON text would exceed this many UTF-16 code units. Unlimited when absent.\n   */\n  readonly quota?: number;\n};\n\n/** A `StorageBackend` with read access to its raw contents, for tests. */\nexport interface MemoryBackend extends StorageBackend {\n  /** Writes a raw value with no checks, as a corrupted or older database would hold it. */\n  poke(store: StoreName, key: string, value: unknown): void;\n  /** The raw value, or `undefined`. */\n  peek(store: StoreName, key: string): unknown;\n  /** The space in use, in the units `quota` counts. */\n  used(): number;\n}\n\n// Node, browsers and workers all have structuredClone; the core's ES-only lib doesn't name it.\nconst { structuredClone } = globalThis as unknown as { structuredClone: <T>(value: T) => T };\nconst copy = <T>(value: T): T => structuredClone(value);\n\nconst sizeOf = (key: string, value: unknown): number => key.length + (JSON.stringify(value)?.length ?? 0);\n\n/**\n * An in-memory backend for unit tests and server rendering, where there is no IndexedDB.\n * It copies values on the way in and out, as IndexedDB's structured clone does, so a caller\n * that mutates a value it read can't change what is stored.\n */\nexport const createMemoryBackend = (options: MemoryBackendOptions = {}): MemoryBackend => {\n  const stores = new Map<StoreName, Map<string, unknown>>(STORE_NAMES.map((name) => [name, new Map()]));\n  const store = (name: StoreName): Map<string, unknown> => {\n    const found = stores.get(name);\n    if (found === undefined) throw new Error(`Unknown store \"${name}\"`);\n    return found;\n  };\n  const used = (): number => {\n    let total = 0;\n    for (const entries of stores.values()) for (const [key, value] of entries) total += sizeOf(key, value);\n    return total;\n  };\n\n  const put = (name: StoreName, key: string, value: Json): Result<void, StorageError> => {\n    const entries = store(name);\n    if (options.quota !== undefined) {\n      const previous = entries.has(key) ? sizeOf(key, entries.get(key)) : 0;\n      if (used() - previous + sizeOf(key, value) > options.quota) {\n        return err(storageError('QuotaExceeded', MESSAGES.QuotaExceeded));\n      }\n    }\n    entries.set(key, copy(value));\n    return ok(undefined);\n  };\n\n  return {\n    get: async (name, key) => ok(copy(store(name).get(key))),\n    put: async (name, key, value: Json) => put(name, key, value),\n    // Check and write in one synchronous step, so no other call can come between them.\n    putIfAbsent: async (name, key, value: Json) => {\n      const existing = store(name).get(key);\n      if (existing !== undefined) return ok({ written: false, value: copy(existing) });\n      const written = put(name, key, value);\n      return written.ok ? ok({ written: true }) : written;\n    },\n    delete: async (name, key) => {\n      store(name).delete(key);\n      return ok(undefined);\n    },\n    keys: async (name, prefix) =>\n      ok([...store(name).keys()].filter((key) => key.startsWith(prefix)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))),\n    clear: async (name) => {\n      store(name).clear();\n      return ok(undefined);\n    },\n    close: () => {},\n    poke: (name, key, value) => {\n      store(name).set(key, value);\n    },\n    peek: (name, key) => store(name).get(key),\n    used,\n  };\n};\n"],"mappings":";;;AA6BA,IAAM,EAAE,oBAAoB;AAC5B,IAAM,QAAW,UAAgB,gBAAgB,KAAK;AAEtD,IAAM,UAAU,KAAa,UAA2B,IAAI,UAAU,KAAK,UAAU,KAAK,CAAC,EAAE,UAAU;;;;;;AAOvG,IAAa,uBAAuB,UAAgC,CAAC,MAAqB;CACxF,MAAM,SAAS,IAAI,IAAqC,YAAY,KAAK,SAAS,CAAC,sBAAM,IAAI,IAAI,CAAC,CAAC,CAAC;CACpG,MAAM,SAAS,SAA0C;EACvD,MAAM,QAAQ,OAAO,IAAI,IAAI;EAC7B,IAAI,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,kBAAkB,KAAK,EAAE;EAClE,OAAO;CACT;CACA,MAAM,aAAqB;EACzB,IAAI,QAAQ;EACZ,KAAK,MAAM,WAAW,OAAO,OAAO,GAAG,KAAK,MAAM,CAAC,KAAK,UAAU,SAAS,SAAS,OAAO,KAAK,KAAK;EACrG,OAAO;CACT;CAEA,MAAM,OAAO,MAAiB,KAAa,UAA4C;EACrF,MAAM,UAAU,MAAM,IAAI;EAC1B,IAAI,QAAQ,UAAU,KAAA,GAAW;GAC/B,MAAM,WAAW,QAAQ,IAAI,GAAG,IAAI,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI;GACpE,IAAI,KAAK,IAAI,WAAW,OAAO,KAAK,KAAK,IAAI,QAAQ,OACnD,OAAO,IAAI,aAAa,iBAAiB,SAAS,aAAa,CAAC;EAEpE;EACA,QAAQ,IAAI,KAAK,KAAK,KAAK,CAAC;EAC5B,OAAO,GAAG,KAAA,CAAS;CACrB;CAEA,OAAO;EACL,KAAK,OAAO,MAAM,QAAQ,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;EACvD,KAAK,OAAO,MAAM,KAAK,UAAgB,IAAI,MAAM,KAAK,KAAK;EAE3D,aAAa,OAAO,MAAM,KAAK,UAAgB;GAC7C,MAAM,WAAW,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG;GACpC,IAAI,aAAa,KAAA,GAAW,OAAO,GAAG;IAAE,SAAS;IAAO,OAAO,KAAK,QAAQ;GAAE,CAAC;GAC/E,MAAM,UAAU,IAAI,MAAM,KAAK,KAAK;GACpC,OAAO,QAAQ,KAAK,GAAG,EAAE,SAAS,KAAK,CAAC,IAAI;EAC9C;EACA,QAAQ,OAAO,MAAM,QAAQ;GAC3B,MAAM,IAAI,CAAC,CAAC,OAAO,GAAG;GACtB,OAAO,GAAG,KAAA,CAAS;EACrB;EACA,MAAM,OAAO,MAAM,WACjB,GAAG,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,QAAQ,IAAI,WAAW,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,MAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAE,CAAC;EACjH,OAAO,OAAO,SAAS;GACrB,MAAM,IAAI,CAAC,CAAC,MAAM;GAClB,OAAO,GAAG,KAAA,CAAS;EACrB;EACA,aAAa,CAAC;EACd,OAAO,MAAM,KAAK,UAAU;GAC1B,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;EAC5B;EACA,OAAO,MAAM,QAAQ,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG;EACxC;CACF;AACF"}

package/dist/preferences.d.ts

@@ -0,0 +1,61 @@
+import { type Preferences, type Result } from '@joystyk/contracts';
+import type { StorageError } from './backend.js';
+import { type ChangeFeed } from './changes.js';
+import { type RecordContext } from './record.js';
+/**
+ * What a player chose. `system` follows the operating system's setting; the frame resolves
+ * the choices into the contracts' `Preferences` with `resolvePreferences`.
+ */
+export type StoredPreferences = {
+    readonly reducedMotion: 'system' | 'reduce' | 'no-preference';
+    readonly sound: boolean;
+    /** 0 … 1. */
+    readonly volume: number;
+    /**
+     * Whether shortcuts made of a single printable key are on. WCAG 2.1.4 requires a way to
+     * turn them off, for speech-input and switch users.
+     */
+    readonly singleKeyShortcuts: boolean;
+    readonly theme: 'system' | 'light' | 'dark';
+    /** A BCP 47 tag, or null to follow the browser. */
+    readonly locale: string | null;
+    /**
+     * True once the player accepted the AI-content notice (D-44); games with AI-made content
+     * stay locked until then. Missing means not yet, so older records need no migration.
+     */
+    readonly aiContentAccepted?: boolean;
+};
+export declare const DEFAULT_PREFERENCES: StoredPreferences;
+/** Version 1 of the preferences record. */
+export declare const PREFERENCES_RECORD: import("./record.js").RecordKind<StoredPreferences>;
+/** What the browser reports, read by the frame (`systemEnvironment` in the browser entry). */
+export type SystemEnvironment = {
+    readonly prefersReducedMotion: boolean;
+    readonly prefersDark: boolean;
+    readonly locale: string;
+};
+/** The contracts' `Preferences` plus the shortcut setting, which games with keyboard controls honor too. */
+export type ResolvedPreferences = Preferences & {
+    readonly singleKeyShortcuts: boolean;
+};
+/** Resolves a player's choices against the system's settings. Pure. */
+export declare const resolvePreferences: (stored: StoredPreferences, system: SystemEnvironment) => ResolvedPreferences;
+/** Where a change came from: an `update` in this tab, or one in another tab of the site. */
+export type PreferencesSource = 'this-tab' | 'other-tab';
+/** One player's preferences. */
+export interface PreferencesStore {
+    /** The stored choices, or `DEFAULT_PREFERENCES`. */
+    get(): Promise<Result<StoredPreferences, StorageError>>;
+    /**
+     * Merges `changes` into the stored choices, writes them, notifies this tab's subscribers,
+     * tells the other tabs, and returns them.
+     */
+    update(changes: Partial<StoredPreferences>): Promise<Result<StoredPreferences, StorageError>>;
+    /**
+     * Called after each successful `update` in this tab, and, when storage has a change feed,
+     * after each one in another tab, with the choices read back from storage (gp-d4v).
+     * Returns an idempotent unsubscribe.
+     */
+    subscribe(listener: (preferences: StoredPreferences, source: PreferencesSource) => void): () => void;
+}
+export declare const createPreferencesStore: (context: RecordContext, playerId: string, changes?: ChangeFeed) => PreferencesStore;

package/dist/preferences.js

@@ -0,0 +1,93 @@
+import { createRecordStore, defineRecordKind } from "./record.js";
+import { parseStorageChange } from "./changes.js";
+import { ok } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/preferences.ts
+var DEFAULT_PREFERENCES = {
+	reducedMotion: "system",
+	sound: true,
+	volume: .8,
+	singleKeyShortcuts: true,
+	theme: "system",
+	locale: null
+};
+/** Version 1 of the preferences record. */
+var PREFERENCES_RECORD = defineRecordKind({
+	store: "preferences",
+	version: 1,
+	schema: z.object({
+		reducedMotion: z.enum([
+			"system",
+			"reduce",
+			"no-preference"
+		]),
+		sound: z.boolean(),
+		volume: z.number().check(z.gte(0), z.lte(1)),
+		singleKeyShortcuts: z.boolean(),
+		theme: z.enum([
+			"system",
+			"light",
+			"dark"
+		]),
+		locale: z.nullable(z.string().check(z.regex(/^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/))),
+		aiContentAccepted: z.optional(z.boolean())
+	}),
+	label: "set of preferences"
+});
+/** Resolves a player's choices against the system's settings. Pure. */
+var resolvePreferences = (stored, system) => ({
+	reducedMotion: stored.reducedMotion === "system" ? system.prefersReducedMotion : stored.reducedMotion === "reduce",
+	sound: stored.sound,
+	volume: stored.volume,
+	colorScheme: stored.theme === "system" ? system.prefersDark ? "dark" : "light" : stored.theme,
+	locale: stored.locale ?? system.locale,
+	singleKeyShortcuts: stored.singleKeyShortcuts
+});
+var createPreferencesStore = (context, playerId, changes) => {
+	const records = createRecordStore(context, PREFERENCES_RECORD);
+	const listeners = /* @__PURE__ */ new Set();
+	const get = async () => {
+		const stored = await records.get(playerId);
+		return stored.ok ? ok(stored.value ?? DEFAULT_PREFERENCES) : stored;
+	};
+	const tell = (preferences, source) => {
+		for (const listener of [...listeners]) listener(preferences, source);
+	};
+	changes?.subscribe((message) => {
+		parseStorageChange(message).then(async (change) => {
+			if (change?.kind !== "preferences" || change.playerId !== playerId || listeners.size === 0) return;
+			const current = await get();
+			if (current.ok) tell(current.value, "other-tab");
+		});
+	});
+	return {
+		get,
+		update: async (partial) => {
+			const current = await get();
+			if (!current.ok) return current;
+			const next = {
+				...current.value,
+				...partial
+			};
+			const written = await records.set(playerId, next);
+			if (!written.ok) return written;
+			tell(next, "this-tab");
+			changes?.publish({
+				kind: "preferences",
+				playerId
+			});
+			return ok(next);
+		},
+		subscribe: (listener) => {
+			const entry = (preferences, source) => listener(preferences, source);
+			listeners.add(entry);
+			return () => {
+				listeners.delete(entry);
+			};
+		}
+	};
+};
+//#endregion
+export { DEFAULT_PREFERENCES, PREFERENCES_RECORD, createPreferencesStore, resolvePreferences };
+
+//# sourceMappingURL=preferences.js.map

package/dist/preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.js","names":[],"sources":["../src/preferences.ts"],"sourcesContent":["import { ok, type Preferences, type Result } from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport type { StorageError } from './backend.ts';\nimport { parseStorageChange, type ChangeFeed } from './changes.ts';\nimport { createRecordStore, defineRecordKind, type RecordContext } from './record.ts';\n\n/**\n * What a player chose. `system` follows the operating system's setting; the frame resolves\n * the choices into the contracts' `Preferences` with `resolvePreferences`.\n */\nexport type StoredPreferences = {\n  readonly reducedMotion: 'system' | 'reduce' | 'no-preference';\n  readonly sound: boolean;\n  /** 0 … 1. */\n  readonly volume: number;\n  /**\n   * Whether shortcuts made of a single printable key are on. WCAG 2.1.4 requires a way to\n   * turn them off, for speech-input and switch users.\n   */\n  readonly singleKeyShortcuts: boolean;\n  readonly theme: 'system' | 'light' | 'dark';\n  /** A BCP 47 tag, or null to follow the browser. */\n  readonly locale: string | null;\n  /**\n   * True once the player accepted the AI-content notice (D-44); games with AI-made content\n   * stay locked until then. Missing means not yet, so older records need no migration.\n   */\n  readonly aiContentAccepted?: boolean;\n};\n\nexport const DEFAULT_PREFERENCES: StoredPreferences = {\n  reducedMotion: 'system',\n  sound: true,\n  volume: 0.8,\n  singleKeyShortcuts: true,\n  theme: 'system',\n  locale: null,\n};\n\n/** Version 1 of the preferences record. */\nexport const PREFERENCES_RECORD = defineRecordKind<StoredPreferences>({\n  store: 'preferences',\n  version: 1,\n  schema: z.object({\n    reducedMotion: z.enum(['system', 'reduce', 'no-preference']),\n    sound: z.boolean(),\n    volume: z.number().check(z.gte(0), z.lte(1)),\n    singleKeyShortcuts: z.boolean(),\n    theme: z.enum(['system', 'light', 'dark']),\n    locale: z.nullable(z.string().check(z.regex(/^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/))),\n    aiContentAccepted: z.optional(z.boolean()),\n  }),\n  label: 'set of preferences',\n});\n\n/** What the browser reports, read by the frame (`systemEnvironment` in the browser entry). */\nexport type SystemEnvironment = {\n  readonly prefersReducedMotion: boolean;\n  readonly prefersDark: boolean;\n  readonly locale: string;\n};\n\n/** The contracts' `Preferences` plus the shortcut setting, which games with keyboard controls honor too. */\nexport type ResolvedPreferences = Preferences & { readonly singleKeyShortcuts: boolean };\n\n/** Resolves a player's choices against the system's settings. Pure. */\nexport const resolvePreferences = (stored: StoredPreferences, system: SystemEnvironment): ResolvedPreferences => ({\n  reducedMotion: stored.reducedMotion === 'system' ? system.prefersReducedMotion : stored.reducedMotion === 'reduce',\n  sound: stored.sound,\n  volume: stored.volume,\n  colorScheme: stored.theme === 'system' ? (system.prefersDark ? 'dark' : 'light') : stored.theme,\n  locale: stored.locale ?? system.locale,\n  singleKeyShortcuts: stored.singleKeyShortcuts,\n});\n\n/** Where a change came from: an `update` in this tab, or one in another tab of the site. */\nexport type PreferencesSource = 'this-tab' | 'other-tab';\n\n/** One player's preferences. */\nexport interface PreferencesStore {\n  /** The stored choices, or `DEFAULT_PREFERENCES`. */\n  get(): Promise<Result<StoredPreferences, StorageError>>;\n  /**\n   * Merges `changes` into the stored choices, writes them, notifies this tab's subscribers,\n   * tells the other tabs, and returns them.\n   */\n  update(changes: Partial<StoredPreferences>): Promise<Result<StoredPreferences, StorageError>>;\n  /**\n   * Called after each successful `update` in this tab, and, when storage has a change feed,\n   * after each one in another tab, with the choices read back from storage (gp-d4v).\n   * Returns an idempotent unsubscribe.\n   */\n  subscribe(listener: (preferences: StoredPreferences, source: PreferencesSource) => void): () => void;\n}\n\nexport const createPreferencesStore = (\n  context: RecordContext,\n  playerId: string,\n  changes?: ChangeFeed,\n): PreferencesStore => {\n  const records = createRecordStore(context, PREFERENCES_RECORD);\n  const listeners = new Set<(preferences: StoredPreferences, source: PreferencesSource) => void>();\n  const get = async (): Promise<Result<StoredPreferences, StorageError>> => {\n    const stored = await records.get(playerId);\n    return stored.ok ? ok(stored.value ?? DEFAULT_PREFERENCES) : stored;\n  };\n  const tell = (preferences: StoredPreferences, source: PreferencesSource): void => {\n    for (const listener of [...listeners]) listener(preferences, source);\n  };\n  // Another tab changed this player's choices: read them back, through the schema.\n  changes?.subscribe((message) => {\n    void parseStorageChange(message).then(async (change) => {\n      if (change?.kind !== 'preferences' || change.playerId !== playerId || listeners.size === 0) return;\n      const current = await get();\n      if (current.ok) tell(current.value, 'other-tab');\n    });\n  });\n  return {\n    get,\n    update: async (partial) => {\n      const current = await get();\n      if (!current.ok) return current;\n      const next = { ...current.value, ...partial };\n      const written = await records.set(playerId, next);\n      if (!written.ok) return written;\n      tell(next, 'this-tab');\n      changes?.publish({ kind: 'preferences', playerId });\n      return ok(next);\n    },\n    subscribe: (listener) => {\n      // A wrapper, so subscribing the same function twice gives two independent subscriptions.\n      const entry = (preferences: StoredPreferences, source: PreferencesSource): void => listener(preferences, source);\n      listeners.add(entry);\n      return () => {\n        listeners.delete(entry);\n      };\n    },\n  };\n};\n"],"mappings":";;;;;AA8BA,IAAa,sBAAyC;CACpD,eAAe;CACf,OAAO;CACP,QAAQ;CACR,oBAAoB;CACpB,OAAO;CACP,QAAQ;AACV;;AAGA,IAAa,qBAAqB,iBAAoC;CACpE,OAAO;CACP,SAAS;CACT,QAAQ,EAAE,OAAO;EACf,eAAe,EAAE,KAAK;GAAC;GAAU;GAAU;EAAe,CAAC;EAC3D,OAAO,EAAE,QAAQ;EACjB,QAAQ,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;EAC3C,oBAAoB,EAAE,QAAQ;EAC9B,OAAO,EAAE,KAAK;GAAC;GAAU;GAAS;EAAM,CAAC;EACzC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,qCAAqC,CAAC,CAAC;EACnF,mBAAmB,EAAE,SAAS,EAAE,QAAQ,CAAC;CAC3C,CAAC;CACD,OAAO;AACT,CAAC;;AAaD,IAAa,sBAAsB,QAA2B,YAAoD;CAChH,eAAe,OAAO,kBAAkB,WAAW,OAAO,uBAAuB,OAAO,kBAAkB;CAC1G,OAAO,OAAO;CACd,QAAQ,OAAO;CACf,aAAa,OAAO,UAAU,WAAY,OAAO,cAAc,SAAS,UAAW,OAAO;CAC1F,QAAQ,OAAO,UAAU,OAAO;CAChC,oBAAoB,OAAO;AAC7B;AAsBA,IAAa,0BACX,SACA,UACA,YACqB;CACrB,MAAM,UAAU,kBAAkB,SAAS,kBAAkB;CAC7D,MAAM,4BAAY,IAAI,IAAyE;CAC/F,MAAM,MAAM,YAA8D;EACxE,MAAM,SAAS,MAAM,QAAQ,IAAI,QAAQ;EACzC,OAAO,OAAO,KAAK,GAAG,OAAO,SAAS,mBAAmB,IAAI;CAC/D;CACA,MAAM,QAAQ,aAAgC,WAAoC;EAChF,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAAG,SAAS,aAAa,MAAM;CACrE;CAEA,SAAS,WAAW,YAAY;EAC9B,mBAAwB,OAAO,CAAC,CAAC,KAAK,OAAO,WAAW;GACtD,IAAI,QAAQ,SAAS,iBAAiB,OAAO,aAAa,YAAY,UAAU,SAAS,GAAG;GAC5F,MAAM,UAAU,MAAM,IAAI;GAC1B,IAAI,QAAQ,IAAI,KAAK,QAAQ,OAAO,WAAW;EACjD,CAAC;CACH,CAAC;CACD,OAAO;EACL;EACA,QAAQ,OAAO,YAAY;GACzB,MAAM,UAAU,MAAM,IAAI;GAC1B,IAAI,CAAC,QAAQ,IAAI,OAAO;GACxB,MAAM,OAAO;IAAE,GAAG,QAAQ;IAAO,GAAG;GAAQ;GAC5C,MAAM,UAAU,MAAM,QAAQ,IAAI,UAAU,IAAI;GAChD,IAAI,CAAC,QAAQ,IAAI,OAAO;GACxB,KAAK,MAAM,UAAU;GACrB,SAAS,QAAQ;IAAE,MAAM;IAAe;GAAS,CAAC;GAClD,OAAO,GAAG,IAAI;EAChB;EACA,YAAY,aAAa;GAEvB,MAAM,SAAS,aAAgC,WAAoC,SAAS,aAAa,MAAM;GAC/G,UAAU,IAAI,KAAK;GACnB,aAAa;IACX,UAAU,OAAO,KAAK;GACxB;EACF;CACF;AACF"}

package/dist/record.d.ts

@@ -0,0 +1,117 @@
+import { type Json, type Migration, type Result, type Validator } from '@joystyk/contracts';
+import { type StorageBackend, type StorageError, type StoreName } from './backend.js';
+import { type Issue } from './validate.js';
+/**
+ * One kind of record: where it lives, the current version of its shape, the schema that
+ * decodes it and the migrations that bring older versions up to date. Every record a
+ * `RecordStore` reads passes through all three before anyone sees it.
+ */
+export type RecordKind<T extends Json> = {
+    readonly store: StoreName;
+    /** The current shape's version, from 1. Bump it, and add a migration, when the shape changes. */
+    readonly version: number;
+    readonly schema: Validator<T>;
+    /** Pure steps from each older version to the next (the contracts' `Migration`). */
+    readonly migrations: readonly Migration[];
+    /**
+     * What happens to a record that fails to decode: `discard` deletes it; `archive` moves its
+     * raw value to the `archive` store first, where nothing reads it as trusted data, so a bug
+     * report or a later build can still recover it. Saves are archived (offline-and-updates.md,
+     * Rule 3).
+     */
+    readonly onInvalid: 'discard' | 'archive';
+    /** How notices name this record to a player, e.g. "saved game". */
+    readonly label: string;
+};
+/** Fills in a record kind's defaults: no migrations, and invalid records discarded. */
+export declare const defineRecordKind: <T extends Json>(kind: Omit<RecordKind<T>, "migrations" | "onInvalid"> & Partial<Pick<RecordKind<T>, "migrations" | "onInvalid">>) => RecordKind<T>;
+/** Why the store is telling the player something. */
+export type StorageNoticeCode = 
+/** A record failed to decode and was deleted. */
+'RecordDiscarded'
+/** A record failed to decode and was moved to the archive. */
+ | 'RecordArchived'
+/** A record was written by a newer build. It is kept, but this build can't read it. */
+ | 'RecordFromFuture'
+/** A write failed because storage is full, even after clearing the archive. */
+ | 'QuotaExceeded'
+/** Storage can't be opened at all. */
+ | 'Unavailable';
+/**
+ * Something the frame should show the player, shaped like the contracts' `Notice` plus where
+ * it happened. `issues` is developer detail for logs; never show it to players.
+ */
+export type StorageNotice = {
+    readonly code: StorageNoticeCode;
+    readonly message: string;
+    /** Where it happened; null for a notice about storage as a whole. */
+    readonly store: StoreName | null;
+    readonly key: string | null;
+    readonly issues: readonly Issue[];
+};
+/** What every record store shares: the backend, the notice sink and the clock. */
+export type RecordContext = {
+    readonly backend: StorageBackend;
+    readonly notify: (notice: StorageNotice) => void;
+    /** Epoch milliseconds, recorded with each write for v2 sync ("newest wins"). */
+    readonly now: () => number;
+};
+/** Typed, validated access to one kind of record. */
+export interface RecordStore<T extends Json> {
+    /** The decoded value, or null when it is absent or failed to decode (with a notice). */
+    get(key: string): Promise<Result<T | null, StorageError>>;
+    /** Validates `value` against the kind's schema, then writes it at the current version. */
+    set(key: string, value: T): Promise<Result<void, StorageError>>;
+    /**
+     * Validates `value`, then writes it only when the key holds no readable record, atomically
+     * (see `StorageBackend.putIfAbsent`). Resolves to the record the key holds afterwards: this
+     * value, or the one another caller, perhaps in another tab, wrote first. A record that fails
+     * to decode is discarded or archived first, as `get` does. When the key holds a record from
+     * a newer build, the value is returned unwritten.
+     */
+    setIfAbsent(key: string, value: T): Promise<Result<T, StorageError>>;
+    delete(key: string): Promise<Result<void, StorageError>>;
+    /** Keys that start with `prefix`, ascending. */
+    keys(prefix?: string): Promise<Result<readonly string[], StorageError>>;
+    /**
+     * Discards or archives a record (by the kind's `onInvalid`) that decoded but failed a later
+     * check, such as a game's own save schema, and tells the player.
+     */
+    reject(key: string, issues: readonly Issue[]): Promise<void>;
+}
+/** What the archive store holds for a record that failed to decode. */
+export type ArchivedRecord = {
+    readonly store: StoreName;
+    readonly key: string;
+    readonly archivedAt: number;
+    readonly issues: readonly string[];
+    /** The raw record, or null when it wasn't even JSON. */
+    readonly raw: Json | null;
+};
+type Decoded<T> = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'valid';
+    readonly value: T;
+    readonly migrated: boolean;
+} | {
+    readonly kind: 'future';
+    readonly issues: readonly Issue[];
+} | {
+    readonly kind: 'invalid';
+    readonly issues: readonly Issue[];
+};
+/**
+ * Decodes a raw backend value as a record of `kind`: checks the record's own shape, runs the
+ * migrations from its version to the current one, then validates the value with the kind's
+ * schema. Pure apart from the schema, which may be async.
+ */
+export declare const decodeRecord: <T extends Json>(kind: RecordKind<T>, raw: unknown) => Promise<Decoded<T>>;
+/**
+ * Writes a value, and when storage is full, clears the archive (the least valuable data the
+ * site keeps) and tries once more.
+ */
+export declare const putWithQuotaRetry: (context: RecordContext, store: StoreName, key: string, value: Json) => Promise<Result<void, StorageError>>;
+/** Creates the typed store for one kind of record. */
+export declare const createRecordStore: <T extends Json>(context: RecordContext, kind: RecordKind<T>) => RecordStore<T>;
+export {};

package/dist/record.js

@@ -0,0 +1,177 @@
+import { MESSAGES, storageError } from "./backend.js";
+import { json, validate } from "./validate.js";
+import { err, isJson, ok, runMigrations } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/record.ts
+/** Fills in a record kind's defaults: no migrations, and invalid records discarded. */
+var defineRecordKind = (kind) => ({
+	migrations: [],
+	onInvalid: "discard",
+	...kind
+});
+/** How every record sits in a backend: its shape's version, when it was written, and the value. */
+var storedRecord = z.object({
+	version: z.int().check(z.positive()),
+	writtenAt: z.number().check(z.nonnegative()),
+	value: json
+});
+/**
+* Decodes a raw backend value as a record of `kind`: checks the record's own shape, runs the
+* migrations from its version to the current one, then validates the value with the kind's
+* schema. Pure apart from the schema, which may be async.
+*/
+var decodeRecord = async (kind, raw) => {
+	if (raw === void 0) return { kind: "absent" };
+	const record = await validate(storedRecord, raw);
+	if (!record.ok) return {
+		kind: "invalid",
+		issues: record.error
+	};
+	const { version, value } = record.value;
+	const migrated = runMigrations(kind.migrations, value, version, kind.version);
+	if (!migrated.ok) {
+		const issues = [`${migrated.error.code}: ${migrated.error.message}`];
+		return migrated.error.code === "SaveFromFuture" ? {
+			kind: "future",
+			issues
+		} : {
+			kind: "invalid",
+			issues
+		};
+	}
+	const decoded = await validate(kind.schema, migrated.value);
+	if (!decoded.ok) return {
+		kind: "invalid",
+		issues: decoded.error
+	};
+	return {
+		kind: "valid",
+		value: decoded.value,
+		migrated: version !== kind.version
+	};
+};
+/**
+* Writes a value, and when storage is full, clears the archive (the least valuable data the
+* site keeps) and tries once more.
+*/
+var putWithQuotaRetry = async (context, store, key, value) => {
+	const first = await context.backend.put(store, key, value);
+	if (first.ok || first.error.code !== "QuotaExceeded" || store === "archive") return first;
+	if (!(await context.backend.clear("archive")).ok) return first;
+	return context.backend.put(store, key, value);
+};
+var failureNotice = (store, key, error) => error.code === "QuotaExceeded" || error.code === "Unavailable" ? {
+	code: error.code,
+	message: error.message,
+	store,
+	key,
+	issues: []
+} : null;
+/** Creates the typed store for one kind of record. */
+var createRecordStore = (context, kind) => {
+	const { backend, notify } = context;
+	const reportFailure = (key, result) => {
+		if (!result.ok) {
+			const notice = failureNotice(kind.store, key, result.error);
+			if (notice !== null) notify(notice);
+		}
+		return result;
+	};
+	const write = async (key, value) => reportFailure(key, await putWithQuotaRetry(context, kind.store, key, {
+		version: kind.version,
+		writtenAt: context.now(),
+		value
+	}));
+	const reject = async (key, raw, issues) => {
+		if (kind.onInvalid === "archive") {
+			const archivedAt = context.now();
+			const entry = {
+				store: kind.store,
+				key,
+				archivedAt,
+				issues,
+				raw: isJson(raw) ? raw : null
+			};
+			await backend.put("archive", `${kind.store}/${key}@${archivedAt}`, entry);
+		}
+		await backend.delete(kind.store, key);
+		const message = kind.onInvalid === "archive" ? `A ${kind.label} couldn't be opened, so it was set aside.` : `A ${kind.label} couldn't be read, so it was removed.`;
+		notify({
+			code: kind.onInvalid === "archive" ? "RecordArchived" : "RecordDiscarded",
+			message,
+			store: kind.store,
+			key,
+			issues
+		});
+	};
+	const get = async (key) => {
+		const raw = await backend.get(kind.store, key);
+		if (!raw.ok) return reportFailure(key, raw);
+		const decoded = await decodeRecord(kind, raw.value);
+		switch (decoded.kind) {
+			case "absent": return ok(null);
+			case "future":
+				notify({
+					code: "RecordFromFuture",
+					message: `This ${kind.label} was saved by a newer version of the site. Reload the page to open it.`,
+					store: kind.store,
+					key,
+					issues: decoded.issues
+				});
+				return ok(null);
+			case "invalid":
+				await reject(key, raw.value, decoded.issues);
+				return ok(null);
+			case "valid":
+				if (decoded.migrated) await write(key, decoded.value);
+				return ok(decoded.value);
+		}
+	};
+	const check = async (value) => {
+		if (!isJson(value)) return err(storageError("InvalidValue", MESSAGES.InvalidValue));
+		const checked = await validate(kind.schema, value);
+		return checked.ok ? ok(checked.value) : err(storageError("InvalidValue", MESSAGES.InvalidValue, [...checked.error]));
+	};
+	/** One atomic attempt, with the same quota retry as `write`. */
+	const putIfAbsent = async (key, value) => {
+		const record = {
+			version: kind.version,
+			writtenAt: context.now(),
+			value
+		};
+		const first = await backend.putIfAbsent(kind.store, key, record);
+		if (first.ok || first.error.code !== "QuotaExceeded") return reportFailure(key, first);
+		const cleared = await backend.clear("archive");
+		return reportFailure(key, cleared.ok ? await backend.putIfAbsent(kind.store, key, record) : first);
+	};
+	return {
+		get,
+		set: async (key, value) => {
+			const checked = await check(value);
+			return checked.ok ? write(key, checked.value) : checked;
+		},
+		setIfAbsent: async (key, value) => {
+			const checked = await check(value);
+			if (!checked.ok) return checked;
+			for (let attempt = 0; attempt < 2; attempt += 1) {
+				const put = await putIfAbsent(key, checked.value);
+				if (!put.ok) return put;
+				if (put.value.written) return ok(checked.value);
+				const existing = await get(key);
+				if (!existing.ok) return existing;
+				if (existing.value !== null) return ok(existing.value);
+			}
+			return ok(checked.value);
+		},
+		delete: async (key) => reportFailure(key, await backend.delete(kind.store, key)),
+		keys: async (prefix = "") => reportFailure(prefix, await backend.keys(kind.store, prefix)),
+		reject: async (key, issues) => {
+			const raw = await backend.get(kind.store, key);
+			await reject(key, raw.ok ? raw.value : void 0, issues);
+		}
+	};
+};
+//#endregion
+export { createRecordStore, decodeRecord, defineRecordKind, putWithQuotaRetry };
+
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","names":[],"sources":["../src/record.ts"],"sourcesContent":["import {\n  err,\n  isJson,\n  ok,\n  runMigrations,\n  type Json,\n  type Migration,\n  type Result,\n  type Validator,\n} from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport { MESSAGES, storageError, type StorageBackend, type StorageError, type StoreName } from './backend.ts';\nimport { json, validate, type Issue } from './validate.ts';\n\n/**\n * One kind of record: where it lives, the current version of its shape, the schema that\n * decodes it and the migrations that bring older versions up to date. Every record a\n * `RecordStore` reads passes through all three before anyone sees it.\n */\nexport type RecordKind<T extends Json> = {\n  readonly store: StoreName;\n  /** The current shape's version, from 1. Bump it, and add a migration, when the shape changes. */\n  readonly version: number;\n  readonly schema: Validator<T>;\n  /** Pure steps from each older version to the next (the contracts' `Migration`). */\n  readonly migrations: readonly Migration[];\n  /**\n   * What happens to a record that fails to decode: `discard` deletes it; `archive` moves its\n   * raw value to the `archive` store first, where nothing reads it as trusted data, so a bug\n   * report or a later build can still recover it. Saves are archived (offline-and-updates.md,\n   * Rule 3).\n   */\n  readonly onInvalid: 'discard' | 'archive';\n  /** How notices name this record to a player, e.g. \"saved game\". */\n  readonly label: string;\n};\n\n/** Fills in a record kind's defaults: no migrations, and invalid records discarded. */\nexport const defineRecordKind = <T extends Json>(\n  kind: Omit<RecordKind<T>, 'migrations' | 'onInvalid'> & Partial<Pick<RecordKind<T>, 'migrations' | 'onInvalid'>>,\n): RecordKind<T> => ({ migrations: [], onInvalid: 'discard', ...kind });\n\n/** Why the store is telling the player something. */\nexport type StorageNoticeCode =\n  /** A record failed to decode and was deleted. */\n  | 'RecordDiscarded'\n  /** A record failed to decode and was moved to the archive. */\n  | 'RecordArchived'\n  /** A record was written by a newer build. It is kept, but this build can't read it. */\n  | 'RecordFromFuture'\n  /** A write failed because storage is full, even after clearing the archive. */\n  | 'QuotaExceeded'\n  /** Storage can't be opened at all. */\n  | 'Unavailable';\n\n/**\n * Something the frame should show the player, shaped like the contracts' `Notice` plus where\n * it happened. `issues` is developer detail for logs; never show it to players.\n */\nexport type StorageNotice = {\n  readonly code: StorageNoticeCode;\n  readonly message: string;\n  /** Where it happened; null for a notice about storage as a whole. */\n  readonly store: StoreName | null;\n  readonly key: string | null;\n  readonly issues: readonly Issue[];\n};\n\n/** What every record store shares: the backend, the notice sink and the clock. */\nexport type RecordContext = {\n  readonly backend: StorageBackend;\n  readonly notify: (notice: StorageNotice) => void;\n  /** Epoch milliseconds, recorded with each write for v2 sync (\"newest wins\"). */\n  readonly now: () => number;\n};\n\n/** Typed, validated access to one kind of record. */\nexport interface RecordStore<T extends Json> {\n  /** The decoded value, or null when it is absent or failed to decode (with a notice). */\n  get(key: string): Promise<Result<T | null, StorageError>>;\n  /** Validates `value` against the kind's schema, then writes it at the current version. */\n  set(key: string, value: T): Promise<Result<void, StorageError>>;\n  /**\n   * Validates `value`, then writes it only when the key holds no readable record, atomically\n   * (see `StorageBackend.putIfAbsent`). Resolves to the record the key holds afterwards: this\n   * value, or the one another caller, perhaps in another tab, wrote first. A record that fails\n   * to decode is discarded or archived first, as `get` does. When the key holds a record from\n   * a newer build, the value is returned unwritten.\n   */\n  setIfAbsent(key: string, value: T): Promise<Result<T, StorageError>>;\n  delete(key: string): Promise<Result<void, StorageError>>;\n  /** Keys that start with `prefix`, ascending. */\n  keys(prefix?: string): Promise<Result<readonly string[], StorageError>>;\n  /**\n   * Discards or archives a record (by the kind's `onInvalid`) that decoded but failed a later\n   * check, such as a game's own save schema, and tells the player.\n   */\n  reject(key: string, issues: readonly Issue[]): Promise<void>;\n}\n\n/** How every record sits in a backend: its shape's version, when it was written, and the value. */\nconst storedRecord = z.object({\n  version: z.int().check(z.positive()),\n  writtenAt: z.number().check(z.nonnegative()),\n  value: json,\n});\n\n/** What the archive store holds for a record that failed to decode. */\nexport type ArchivedRecord = {\n  readonly store: StoreName;\n  readonly key: string;\n  readonly archivedAt: number;\n  readonly issues: readonly string[];\n  /** The raw record, or null when it wasn't even JSON. */\n  readonly raw: Json | null;\n};\n\ntype Decoded<T> =\n  | { readonly kind: 'absent' }\n  | { readonly kind: 'valid'; readonly value: T; readonly migrated: boolean }\n  | { readonly kind: 'future'; readonly issues: readonly Issue[] }\n  | { readonly kind: 'invalid'; readonly issues: readonly Issue[] };\n\n/**\n * Decodes a raw backend value as a record of `kind`: checks the record's own shape, runs the\n * migrations from its version to the current one, then validates the value with the kind's\n * schema. Pure apart from the schema, which may be async.\n */\nexport const decodeRecord = async <T extends Json>(kind: RecordKind<T>, raw: unknown): Promise<Decoded<T>> => {\n  if (raw === undefined) return { kind: 'absent' };\n  const record = await validate(storedRecord, raw);\n  if (!record.ok) return { kind: 'invalid', issues: record.error };\n  const { version, value } = record.value;\n  const migrated = runMigrations(kind.migrations, value, version, kind.version);\n  if (!migrated.ok) {\n    const issues = [`${migrated.error.code}: ${migrated.error.message}`];\n    return migrated.error.code === 'SaveFromFuture' ? { kind: 'future', issues } : { kind: 'invalid', issues };\n  }\n  const decoded = await validate(kind.schema, migrated.value);\n  if (!decoded.ok) return { kind: 'invalid', issues: decoded.error };\n  return { kind: 'valid', value: decoded.value, migrated: version !== kind.version };\n};\n\n/**\n * Writes a value, and when storage is full, clears the archive (the least valuable data the\n * site keeps) and tries once more.\n */\nexport const putWithQuotaRetry = async (\n  context: RecordContext,\n  store: StoreName,\n  key: string,\n  value: Json,\n): Promise<Result<void, StorageError>> => {\n  const first = await context.backend.put(store, key, value);\n  if (first.ok || first.error.code !== 'QuotaExceeded' || store === 'archive') return first;\n  const cleared = await context.backend.clear('archive');\n  if (!cleared.ok) return first;\n  return context.backend.put(store, key, value);\n};\n\nconst failureNotice = (store: StoreName, key: string, error: StorageError): StorageNotice | null =>\n  error.code === 'QuotaExceeded' || error.code === 'Unavailable'\n    ? { code: error.code, message: error.message, store, key, issues: [] }\n    : null;\n\n/** Creates the typed store for one kind of record. */\nexport const createRecordStore = <T extends Json>(context: RecordContext, kind: RecordKind<T>): RecordStore<T> => {\n  const { backend, notify } = context;\n\n  const reportFailure = <V>(key: string, result: Result<V, StorageError>): Result<V, StorageError> => {\n    if (!result.ok) {\n      const notice = failureNotice(kind.store, key, result.error);\n      if (notice !== null) notify(notice);\n    }\n    return result;\n  };\n\n  const write = async (key: string, value: Json): Promise<Result<void, StorageError>> =>\n    reportFailure(\n      key,\n      await putWithQuotaRetry(context, kind.store, key, { version: kind.version, writtenAt: context.now(), value }),\n    );\n\n  const reject = async (key: string, raw: unknown, issues: readonly Issue[]): Promise<void> => {\n    if (kind.onInvalid === 'archive') {\n      const archivedAt = context.now();\n      const entry: ArchivedRecord = { store: kind.store, key, archivedAt, issues, raw: isJson(raw) ? raw : null };\n      // Best effort: a full archive must not keep a broken record in the live store.\n      await backend.put('archive', `${kind.store}/${key}@${archivedAt}`, entry);\n    }\n    await backend.delete(kind.store, key);\n    const message =\n      kind.onInvalid === 'archive'\n        ? `A ${kind.label} couldn't be opened, so it was set aside.`\n        : `A ${kind.label} couldn't be read, so it was removed.`;\n    notify({\n      code: kind.onInvalid === 'archive' ? 'RecordArchived' : 'RecordDiscarded',\n      message,\n      store: kind.store,\n      key,\n      issues,\n    });\n  };\n\n  const get = async (key: string): Promise<Result<T | null, StorageError>> => {\n    const raw = await backend.get(kind.store, key);\n    if (!raw.ok) return reportFailure(key, raw);\n    const decoded = await decodeRecord(kind, raw.value);\n    switch (decoded.kind) {\n      case 'absent':\n        return ok(null);\n      case 'future':\n        notify({\n          code: 'RecordFromFuture',\n          message: `This ${kind.label} was saved by a newer version of the site. Reload the page to open it.`,\n          store: kind.store,\n          key,\n          issues: decoded.issues,\n        });\n        return ok(null);\n      case 'invalid':\n        await reject(key, raw.value, decoded.issues);\n        return ok(null);\n      case 'valid':\n        // Store the upgraded shape, so the migration runs once. Failing to is harmless.\n        if (decoded.migrated) await write(key, decoded.value);\n        return ok(decoded.value);\n    }\n  };\n\n  const check = async (value: T): Promise<Result<T, StorageError>> => {\n    if (!isJson(value)) return err(storageError('InvalidValue', MESSAGES.InvalidValue));\n    const checked = await validate(kind.schema, value);\n    return checked.ok\n      ? ok(checked.value)\n      : err(storageError('InvalidValue', MESSAGES.InvalidValue, [...checked.error]));\n  };\n\n  /** One atomic attempt, with the same quota retry as `write`. */\n  const putIfAbsent = async (key: string, value: T) => {\n    const record = { version: kind.version, writtenAt: context.now(), value };\n    const first = await backend.putIfAbsent(kind.store, key, record);\n    if (first.ok || first.error.code !== 'QuotaExceeded') return reportFailure(key, first);\n    const cleared = await backend.clear('archive');\n    return reportFailure(key, cleared.ok ? await backend.putIfAbsent(kind.store, key, record) : first);\n  };\n\n  return {\n    get,\n    set: async (key, value) => {\n      const checked = await check(value);\n      return checked.ok ? write(key, checked.value) : checked;\n    },\n    setIfAbsent: async (key, value) => {\n      const checked = await check(value);\n      if (!checked.ok) return checked;\n      // A second attempt follows a record that failed to decode and was removed.\n      for (let attempt = 0; attempt < 2; attempt += 1) {\n        const put = await putIfAbsent(key, checked.value);\n        if (!put.ok) return put;\n        if (put.value.written) return ok(checked.value);\n        const existing = await get(key);\n        if (!existing.ok) return existing;\n        if (existing.value !== null) return ok(existing.value);\n      }\n      return ok(checked.value);\n    },\n    delete: async (key) => reportFailure(key, await backend.delete(kind.store, key)),\n    keys: async (prefix = '') => reportFailure(prefix, await backend.keys(kind.store, prefix)),\n    reject: async (key, issues) => {\n      const raw = await backend.get(kind.store, key);\n      await reject(key, raw.ok ? raw.value : undefined, issues);\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/saves.d.ts

@@ -0,0 +1,46 @@
+import { type Json, type Migration, type Result, type SaveEnvelope, type Validator } from '@joystyk/contracts';
+import { type StorageError } from './backend.js';
+import { type RecordContext } from './record.js';
+/** One saved game in a slot. */
+export type SavedGame = {
+    readonly slot: string;
+    /** Epoch milliseconds of the write. */
+    readonly savedAt: number;
+    readonly envelope: SaveEnvelope;
+};
+/** What a game supplies to bring its saved state up to date: the game module's chain and schema. */
+export type SaveDecoder = {
+    /** The game's current save version (`manifest.versions.save`). */
+    readonly saveVersion: number;
+    readonly migrations: readonly Migration[];
+    /** The engine's `schemas.state` (or the simulation's). */
+    readonly state: Validator<Json>;
+};
+type SaveRecord = {
+    readonly savedAt: number;
+    readonly envelope: SaveEnvelope;
+};
+/** Version 1 of the save record: the contracts' envelope plus the time it was written. */
+export declare const SAVE_RECORD: import("./record.js").RecordKind<SaveRecord>;
+/** One player's save slots, by game id and slot name. */
+export interface SaveStore {
+    /** Every readable save of one game, by slot name. Unreadable ones are archived with a notice. */
+    list(gameId: string): Promise<Result<readonly SavedGame[], StorageError>>;
+    /**
+     * The save in a slot with its envelope decoded, or null. The game's own state is not
+     * migrated or checked; use `load` to resume play.
+     */
+    read(gameId: string, slot: string): Promise<Result<SavedGame | null, StorageError>>;
+    /**
+     * The save in a slot, ready to resume: its state migrated from the saved version to the
+     * game's current one and validated with the game's schema. A save that can't be brought up
+     * to date is archived with a notice and comes back as null. The caller still compares
+     * `rulesVersion` with the game's (offline-and-updates.md, Rule 3).
+     */
+    load(gameId: string, slot: string, decoder: SaveDecoder): Promise<Result<SavedGame | null, StorageError>>;
+    /** Writes an envelope to a slot. The envelope's `gameId` must be `gameId`. */
+    write(gameId: string, slot: string, envelope: SaveEnvelope): Promise<Result<void, StorageError>>;
+    delete(gameId: string, slot: string): Promise<Result<void, StorageError>>;
+}
+export declare const createSaveStore: (context: RecordContext, playerId: string) => SaveStore;
+export {};