@protoyard/database 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @protoyard/database
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+IndexedDB persistence for Protoyard prototypes, built on [Dexie 4](https://dexie.org).
+Each prototype owns exactly two databases, named from its manifest namespace:
+
+| Database | Contents |
+| --- | --- |
+| `protoyard.<namespace>.data` | the prototype's domain tables + reserved `py_organizations`, `py_personas`, `py_memberships`, `py_events` |
+| `protoyard.<namespace>.control` | active scenario, overrides, clock, actor/org, timeline checkpoint, per-persona preferences, snapshots |
+
+Keeping them apart means session, theme or snapshot bookkeeping can never touch domain
+rows, and loading a scenario never deletes saved snapshots.
+
+## API
+
+```ts
+import {
+  openPrototypeStorage, // both DBs + StorageStatus, with honest in-memory fallback
+  openPrototypeDatabase, // data DB only (runs migrations)
+  openControlStore,
+  dumpTables, restoreTables, clearWorld, countTables,
+  deleteProtoyardDatabases,
+  probeStorage, requestPersistence,
+  StorageError, mapStorageError,
+  liveQuery,
+} from '@protoyard/database';
+```
+
+### Data database and migrations
+
+```ts
+const db = await openPrototypeDatabase(definition); // { manifest.storage, database.versions }
+const deals = db.rows<Deal>('deals'); // typed Dexie table; unknown names throw
+db.domainTables; // ['companies', 'deals']
+db.allTables; // domain + reserved
+```
+
+- Every `database.versions` entry is declared in order; the reserved tables are merged into
+  every version. An `upgrade(tx)` runs through Dexie's `.upgrade()` with a Dexie `Transaction`.
+- Tables starting with `py_` are reserved and rejected.
+- Opening an **older** database migrates it. Opening a database written by **newer** code
+  throws `StorageError('version-newer')` and deletes nothing (Dexie 4 would otherwise open
+  it silently, so the native version is compared explicitly).
+
+### Control store
+
+```ts
+const control = await openControlStore('crm-demo');
+await control.writeState({ actorId: 'user_0002', overrides: null }); // one transaction; null deletes
+await control.setPreference('user_0002', { themeId: 'ocean', mode: 'dark' });
+await control.putSnapshot(snapshot); // summary and table payload stored separately
+await control.listSnapshots(); // newest first, never loads rows
+```
+
+### Snapshot I/O
+
+- `dumpTables(db)` reads every domain + reserved table in one read transaction.
+- `restoreTables(db, tables, { knownTables })` clears and refills **all** known tables in ONE
+  read-write transaction. Unknown tables are skipped and reported. Any failure aborts the
+  transaction, so current data stays untouched.
+- `clearWorld(db)` empties domain + reserved tables in one transaction.
+
+### Storage status, errors and degraded mode
+
+`StorageError.code` is one of `unavailable | quota-exceeded | version-newer | blocked | unknown`,
+with a friendly `message`. `mapStorageError(err)` recognises DOM and Dexie errors, including
+errors wrapped in Dexie's `inner` (for example `OpenFailedError` → `InvalidStateError` in
+Firefox private mode).
+
+`openPrototypeStorage()` falls back to an in-memory IndexedDB (`fake-indexeddb`, loaded lazily
+with a dynamic `import()` so it never ships in the normal path) **only** when IndexedDB is
+unavailable. It then reports `{ backend: 'memory', persistent: false, warning }`. Quota,
+version and blocked errors are thrown rather than hidden behind memory storage.
+
+`probeStorage()` reports availability, `navigator.storage.estimate()` and `persisted()`.
+`requestPersistence()` asks for persistent storage and returns `false` when refused.
+
+`deleteProtoyardDatabases(namespace)` deletes only that prototype's two databases.
+
+**Sandboxes:** `sandboxNamespace(namespace, name)` returns `<namespace>~<name>`; the `~`
+never appears in a manifest namespace. `listProtoyardDatabases(namespace)` returns
+`{ supported, databases, sandboxes }` using `indexedDB.databases()`, and reports
+`supported: false` where the browser can't enumerate. `parseDatabaseName(name)` reads any
+`protoyard.<namespace>[~<sandbox>].<data|control>` name.
+
+## Tests
+
+`pnpm vitest run packages/database` covers migrations, version-newer, atomic restore, the
+control store, error mapping, memory fallback and namespace-scoped deletion.
+
+## Package output
+
+The manifest keeps TypeScript source exports for workspace development. `pnpm build:packages --filter engine` creates the ESM and declaration files under `dist/` that the packed manifest exposes.

package/dist/backend.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which IndexedDB implementation to use. Omitted fields mean "the browser's".
+ * Tests and the degraded in-memory mode inject `fake-indexeddb` here.
+ */
+export interface StorageBackend {
+    indexedDB?: IDBFactory;
+    IDBKeyRange?: typeof IDBKeyRange;
+}
+export declare function resolveFactory(backend?: StorageBackend): IDBFactory;
+/** Dexie constructor options for an explicit backend (empty = browser default). */
+export declare function dexieBackendOptions(backend?: StorageBackend): StorageBackend;
+/**
+ * In-memory IndexedDB for when the real one cannot open (private mode,
+ * disabled storage). Loaded lazily so `fake-indexeddb` never ships in the
+ * normal path; data lives only as long as the page.
+ */
+export declare function loadMemoryBackend(): Promise<Required<StorageBackend>>;

package/dist/backend.js

@@ -0,0 +1,31 @@
+import { StorageError } from "./errors.js";
+export function resolveFactory(backend = {}) {
+    const factory = backend.indexedDB ?? globalThis.indexedDB;
+    if (!factory) {
+        throw new StorageError('unavailable', {
+            message: 'IndexedDB is not available in this environment. Changes will not persist after you close the tab.',
+        });
+    }
+    return factory;
+}
+/** Dexie constructor options for an explicit backend (empty = browser default). */
+export function dexieBackendOptions(backend = {}) {
+    const options = {};
+    if (backend.indexedDB)
+        options.indexedDB = backend.indexedDB;
+    if (backend.IDBKeyRange)
+        options.IDBKeyRange = backend.IDBKeyRange;
+    return options;
+}
+/**
+ * In-memory IndexedDB for when the real one cannot open (private mode,
+ * disabled storage). Loaded lazily so `fake-indexeddb` never ships in the
+ * normal path; data lives only as long as the page.
+ */
+export async function loadMemoryBackend() {
+    const mod = await import('fake-indexeddb');
+    return {
+        indexedDB: new mod.IDBFactory(),
+        IDBKeyRange: mod.IDBKeyRange,
+    };
+}

package/dist/control-store.d.ts

@@ -0,0 +1,59 @@
+import type { ActiveScenarioInfo, ClockState, ColorMode, Overrides, Snapshot, SnapshotSummary, Theme } from '@protoyard/core';
+import { type StorageBackend } from './backend.ts';
+/**
+ * The control database holds everything ABOUT the world (active scenario,
+ * overrides, clock, session, preferences, snapshots) and never domain rows.
+ * Keeping it separate means appearance or session changes can never corrupt
+ * prototype data, and a scenario load never wipes saved snapshots.
+ */
+export interface TimelineCheckpoint {
+    /** Committed clock offset the timeline has been applied up to. */
+    committedOffsetMs: number;
+    /** ISO instant matching that offset (for humans and DevTools). */
+    at: string;
+}
+export interface ControlState {
+    activeScenario: ActiveScenarioInfo;
+    overrides: Overrides;
+    clock: ClockState;
+    actorId: string;
+    organizationId: string;
+    /** Simulated sign-out (stored only while signed out). */
+    signedOut: boolean;
+    timelineCheckpoint: TimelineCheckpoint;
+    /** Theme Studio themes; re-validated with `ThemeSchema` on every boot. */
+    customThemes: Theme[];
+}
+export type ControlStateKey = keyof ControlState;
+export interface PersonaPreference {
+    personaId: string;
+    themeId?: string;
+    mode?: ColorMode;
+    reducedMotion?: boolean;
+}
+export type ControlStatePatch = {
+    [K in ControlStateKey]?: ControlState[K] | null;
+};
+export interface ControlStore {
+    readonly namespace: string;
+    readonly name: string;
+    getState<K extends ControlStateKey>(key: K): Promise<ControlState[K] | undefined>;
+    setState<K extends ControlStateKey>(key: K, value: ControlState[K]): Promise<void>;
+    deleteState(...keys: ControlStateKey[]): Promise<void>;
+    readState(): Promise<Partial<ControlState>>;
+    /** Writes several keys in one transaction; `null` deletes a key. */
+    writeState(patch: ControlStatePatch): Promise<void>;
+    getPreference(personaId: string): Promise<PersonaPreference | undefined>;
+    /** Merges into the stored preference; `undefined` fields are removed. */
+    setPreference(personaId: string, patch: Omit<PersonaPreference, 'personaId'>): Promise<PersonaPreference>;
+    listPreferences(): Promise<PersonaPreference[]>;
+    /** Newest first, without table payloads. */
+    listSnapshots(): Promise<SnapshotSummary[]>;
+    getSnapshot(id: string): Promise<Snapshot | undefined>;
+    putSnapshot(snapshot: Snapshot): Promise<void>;
+    deleteSnapshot(id: string): Promise<void>;
+    /** Clears state, preferences and snapshots. */
+    clearAll(): Promise<void>;
+    close(): void;
+}
+export declare function openControlStore(namespace: string, backend?: StorageBackend): Promise<ControlStore>;

package/dist/control-store.js

@@ -0,0 +1,116 @@
+import { Dexie } from 'dexie';
+import { dexieBackendOptions, resolveFactory } from "./backend.js";
+import { mapStorageError } from "./errors.js";
+import { controlDatabaseName } from "./names.js";
+class ControlDatabase extends Dexie {
+    state;
+    preferences;
+    // Summaries and payloads are split so listing snapshots never loads rows.
+    snapshots;
+    snapshotTables;
+    constructor(namespace, backend) {
+        super(controlDatabaseName(namespace), dexieBackendOptions(backend));
+        this.version(1).stores({
+            state: 'key',
+            preferences: 'personaId',
+            snapshots: 'id, createdAt',
+            snapshotTables: 'id',
+        });
+    }
+}
+function wrap(promise) {
+    return promise.catch((error) => {
+        throw mapStorageError(error);
+    });
+}
+export async function openControlStore(namespace, backend = {}) {
+    resolveFactory(backend);
+    const db = new ControlDatabase(namespace, backend);
+    try {
+        await db.open();
+    }
+    catch (error) {
+        db.close();
+        throw mapStorageError(error);
+    }
+    const store = {
+        namespace,
+        name: db.name,
+        async getState(key) {
+            const row = await wrap(db.state.get(key));
+            return row?.value;
+        },
+        async setState(key, value) {
+            await wrap(db.state.put({ key, value }));
+        },
+        async deleteState(...keys) {
+            await wrap(db.state.bulkDelete(keys));
+        },
+        async readState() {
+            const rows = await wrap(db.state.toArray());
+            return Object.fromEntries(rows.map((row) => [row.key, row.value]));
+        },
+        async writeState(patch) {
+            const puts = [];
+            const deletes = [];
+            for (const [key, value] of Object.entries(patch)) {
+                if (value === undefined)
+                    continue;
+                if (value === null)
+                    deletes.push(key);
+                else
+                    puts.push({ key, value });
+            }
+            await wrap(db.transaction('rw', db.state, async () => {
+                if (deletes.length)
+                    await db.state.bulkDelete(deletes);
+                if (puts.length)
+                    await db.state.bulkPut(puts);
+            }));
+        },
+        getPreference: (personaId) => wrap(db.preferences.get(personaId)),
+        async setPreference(personaId, patch) {
+            return wrap(db.transaction('rw', db.preferences, async () => {
+                const current = (await db.preferences.get(personaId)) ?? { personaId };
+                const next = { ...current, ...patch, personaId };
+                for (const key of Object.keys(next)) {
+                    if (next[key] === undefined)
+                        delete next[key];
+                }
+                await db.preferences.put(next);
+                return next;
+            }));
+        },
+        listPreferences: () => wrap(db.preferences.toArray()),
+        async listSnapshots() {
+            return wrap(db.snapshots.orderBy('createdAt').reverse().toArray());
+        },
+        async getSnapshot(id) {
+            const [summary, payload] = await wrap(db.transaction('r', db.snapshots, db.snapshotTables, () => Promise.all([db.snapshots.get(id), db.snapshotTables.get(id)])));
+            if (!summary)
+                return undefined;
+            return { ...summary, tables: payload?.tables ?? [] };
+        },
+        async putSnapshot(snapshot) {
+            const { tables, ...summary } = snapshot;
+            await wrap(db.transaction('rw', db.snapshots, db.snapshotTables, async () => {
+                await db.snapshots.put(summary);
+                await db.snapshotTables.put({ id: snapshot.id, tables });
+            }));
+        },
+        async deleteSnapshot(id) {
+            await wrap(db.transaction('rw', db.snapshots, db.snapshotTables, async () => {
+                await db.snapshots.delete(id);
+                await db.snapshotTables.delete(id);
+            }));
+        },
+        async clearAll() {
+            await wrap(db.transaction('rw', db.tables, async () => {
+                for (const table of db.tables)
+                    await table.clear();
+            }));
+        },
+        close: () => db.close(),
+    };
+    return store;
+}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Storage failures surfaced to people, not stack traces. Every IndexedDB/Dexie
+ * failure the runtime can hit is mapped to one of these codes so the renderer
+ * can show a friendly, actionable message.
+ */
+export type StorageErrorCode = 'unavailable' | 'quota-exceeded' | 'version-newer' | 'blocked' | 'unknown';
+export declare const STORAGE_ERROR_MESSAGES: Record<StorageErrorCode, string>;
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    /** The original error, kept for DevTools diagnostics. */
+    readonly cause: unknown;
+    constructor(code: StorageErrorCode, options?: {
+        message?: string;
+        cause?: unknown;
+    });
+}
+export declare function isStorageError(error: unknown): error is StorageError;
+/**
+ * Maps any thrown value to a {@link StorageError}. Dexie wraps the native
+ * failure in `inner` (e.g. `OpenFailedError` → `InvalidStateError`), so the
+ * chain is walked until a recognised name appears.
+ */
+export declare function mapStorageError(error: unknown): StorageError;

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Storage failures surfaced to people, not stack traces. Every IndexedDB/Dexie
+ * failure the runtime can hit is mapped to one of these codes so the renderer
+ * can show a friendly, actionable message.
+ */
+export const STORAGE_ERROR_MESSAGES = {
+    unavailable: 'Browser storage (IndexedDB) is not available here — private browsing or a strict privacy setting may be blocking it. Changes will not persist after you close the tab.',
+    'quota-exceeded': 'Browser storage is full. Delete old snapshots or reset a prototype to free space.',
+    'version-newer': 'This browser holds data from a newer version of this prototype. Update the prototype, or reset its data from DevTools. Nothing was deleted.',
+    blocked: 'The prototype database is open in another tab with an older version. Close the other tabs of this prototype and reload.',
+    unknown: 'The prototype database could not be used because of an unexpected storage error.',
+};
+export class StorageError extends Error {
+    code;
+    /** The original error, kept for DevTools diagnostics. */
+    cause;
+    constructor(code, options = {}) {
+        super(options.message ?? STORAGE_ERROR_MESSAGES[code]);
+        this.name = 'StorageError';
+        this.code = code;
+        this.cause = options.cause;
+    }
+}
+export function isStorageError(error) {
+    return error instanceof StorageError;
+}
+/** Names of DOM exceptions and Dexie errors (Dexie names end with `Error`). */
+const CODE_BY_NAME = {
+    QuotaExceededError: 'quota-exceeded',
+    VersionError: 'version-newer',
+    MissingAPIError: 'unavailable',
+    // Firefox private mode and Safari with storage disabled throw these on open.
+    // (Chrome's UnknownError — a transient/corrupt backing store on a profile that
+    // may hold real data — is deliberately NOT here: it must be shown, never
+    // silently replaced by an empty in-memory world.)
+    InvalidStateError: 'unavailable',
+    SecurityError: 'unavailable',
+    NotAllowedError: 'unavailable',
+    BlockedError: 'blocked',
+    VersionChangeError: 'blocked',
+};
+function errorName(error) {
+    if (error && typeof error === 'object' && 'name' in error) {
+        const name = error.name;
+        return typeof name === 'string' ? name : undefined;
+    }
+    return undefined;
+}
+/**
+ * Maps any thrown value to a {@link StorageError}. Dexie wraps the native
+ * failure in `inner` (e.g. `OpenFailedError` → `InvalidStateError`), so the
+ * chain is walked until a recognised name appears.
+ */
+export function mapStorageError(error) {
+    if (error instanceof StorageError)
+        return error;
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth++) {
+        const name = errorName(current);
+        const code = name ? CODE_BY_NAME[name] : undefined;
+        if (code)
+            return new StorageError(code, { cause: error });
+        if (name && /quota/i.test(name))
+            return new StorageError('quota-exceeded', { cause: error });
+        current =
+            current.inner ??
+                current.cause;
+    }
+    return new StorageError('unknown', { cause: error });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { Table, Transaction } from 'dexie';
+export { Dexie, liveQuery } from 'dexie';
+export { loadMemoryBackend, type StorageBackend } from './backend.ts';
+export { type ControlState, type ControlStateKey, type ControlStatePatch, type ControlStore, openControlStore, type PersonaPreference, type TimelineCheckpoint, } from './control-store.ts';
+export { isStorageError, mapStorageError, STORAGE_ERROR_MESSAGES, StorageError, type StorageErrorCode, } from './errors.ts';
+export { allTableNames, controlDatabaseName, DATABASE_PREFIX, dataDatabaseName, domainTableNames, latestVersion, type ParsedDatabaseName, parseDatabaseName, RESERVED_PREFIX, RESERVED_TABLE_NAMES, reviewDatabaseName, SANDBOX_SEPARATOR, sandboxNamespace, } from './names.ts';
+export { createPrototypeDatabase, type DatabaseSource, openPrototypeDatabase, PrototypeDatabase, } from './prototype-database.ts';
+export { type DatabaseListing, deleteProtoyardDatabases, listProtoyardDatabases, MEMORY_STORAGE_WARNING, openPrototypeStorage, type PrototypeStorage, probeStorage, requestPersistence, } from './storage.ts';
+export { clearWorld, countTables, dumpTables, type RestoreResult, restoreTables, type SnapshotTable, } from './world-io.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { Dexie, liveQuery } from 'dexie';
+export { loadMemoryBackend } from "./backend.js";
+export { openControlStore, } from "./control-store.js";
+export { isStorageError, mapStorageError, STORAGE_ERROR_MESSAGES, StorageError, } from "./errors.js";
+export { allTableNames, controlDatabaseName, DATABASE_PREFIX, dataDatabaseName, domainTableNames, latestVersion, parseDatabaseName, RESERVED_PREFIX, RESERVED_TABLE_NAMES, reviewDatabaseName, SANDBOX_SEPARATOR, sandboxNamespace, } from "./names.js";
+export { createPrototypeDatabase, openPrototypeDatabase, PrototypeDatabase, } from "./prototype-database.js";
+export { deleteProtoyardDatabases, listProtoyardDatabases, MEMORY_STORAGE_WARNING, openPrototypeStorage, probeStorage, requestPersistence, } from "./storage.js";
+export { clearWorld, countTables, dumpTables, restoreTables, } from "./world-io.js";

package/dist/names.d.ts

@@ -0,0 +1,38 @@
+import { type DatabaseDefinition, RESERVED_TABLES } from '@protoyard/core';
+/**
+ * Every prototype owns separate data, control, and review IndexedDB databases. Names are derived
+ * from the manifest namespace so prototypes on the same origin (the gallery
+ * serves them all from one host) never see each other's data.
+ */
+export declare const DATABASE_PREFIX = "protoyard";
+export declare function dataDatabaseName(namespace: string): string;
+export declare function controlDatabaseName(namespace: string): string;
+/** The prototype's local review comments live outside snapshots and scenario data. */
+export declare function reviewDatabaseName(namespace: string): string;
+/**
+ * Sandboxes are disposable copies of a prototype's world (`?sandbox=a`). Their
+ * namespace is `<namespace>~<sandbox>`: `~` never appears in a manifest
+ * namespace, so a sandbox can't collide with another prototype.
+ */
+export declare const SANDBOX_SEPARATOR = "~";
+export declare function sandboxNamespace(namespace: string, sandbox: string): string;
+export interface ParsedDatabaseName {
+    name: string;
+    /** Base namespace (without the sandbox suffix). */
+    namespace: string;
+    sandbox: string | null;
+    kind: 'data' | 'control';
+}
+/** Reads `protoyard.<namespace>[~<sandbox>].<data|control>`; null for anything else. */
+export declare function parseDatabaseName(name: string): ParsedDatabaseName | null;
+export declare const RESERVED_TABLE_NAMES: readonly (keyof typeof RESERVED_TABLES)[];
+/** `py_` belongs to the platform; prototypes cannot declare such tables. */
+export declare const RESERVED_PREFIX = "py_";
+/**
+ * Domain tables that exist after applying every version in order. A store
+ * set to `null` deletes the table from that version on (Dexie semantics).
+ */
+export declare function domainTableNames(definition: DatabaseDefinition): string[];
+/** Domain tables followed by the reserved platform tables. */
+export declare function allTableNames(definition: DatabaseDefinition): string[];
+export declare function latestVersion(definition: DatabaseDefinition): number;

package/dist/names.js

@@ -0,0 +1,70 @@
+import { RESERVED_TABLES, SANDBOX_PATTERN } from '@protoyard/core';
+/**
+ * Every prototype owns separate data, control, and review IndexedDB databases. Names are derived
+ * from the manifest namespace so prototypes on the same origin (the gallery
+ * serves them all from one host) never see each other's data.
+ */
+export const DATABASE_PREFIX = 'protoyard';
+export function dataDatabaseName(namespace) {
+    return `${DATABASE_PREFIX}.${namespace}.data`;
+}
+export function controlDatabaseName(namespace) {
+    return `${DATABASE_PREFIX}.${namespace}.control`;
+}
+/** The prototype's local review comments live outside snapshots and scenario data. */
+export function reviewDatabaseName(namespace) {
+    return `${DATABASE_PREFIX}.${namespace}.review`;
+}
+/**
+ * Sandboxes are disposable copies of a prototype's world (`?sandbox=a`). Their
+ * namespace is `<namespace>~<sandbox>`: `~` never appears in a manifest
+ * namespace, so a sandbox can't collide with another prototype.
+ */
+export const SANDBOX_SEPARATOR = '~';
+export function sandboxNamespace(namespace, sandbox) {
+    if (!SANDBOX_PATTERN.test(sandbox)) {
+        throw new Error(`Invalid sandbox name "${sandbox}" (lowercase letters, digits and dashes).`);
+    }
+    return `${namespace}${SANDBOX_SEPARATOR}${sandbox}`;
+}
+/** Reads `protoyard.<namespace>[~<sandbox>].<data|control>`; null for anything else. */
+export function parseDatabaseName(name) {
+    const match = /^protoyard\.([a-z][a-z0-9-]*)(?:~([a-z0-9][a-z0-9-]*))?\.(data|control)$/.exec(name);
+    if (!match)
+        return null;
+    return {
+        name,
+        namespace: match[1],
+        sandbox: match[2] ?? null,
+        kind: match[3],
+    };
+}
+export const RESERVED_TABLE_NAMES = Object.keys(RESERVED_TABLES);
+/** `py_` belongs to the platform; prototypes cannot declare such tables. */
+export const RESERVED_PREFIX = 'py_';
+/**
+ * Domain tables that exist after applying every version in order. A store
+ * set to `null` deletes the table from that version on (Dexie semantics).
+ */
+export function domainTableNames(definition) {
+    const tables = new Set();
+    for (const version of definition.versions) {
+        for (const [name, schema] of Object.entries(version.stores)) {
+            if (schema === null)
+                tables.delete(name);
+            else
+                tables.add(name);
+        }
+    }
+    return [...tables];
+}
+/** Domain tables followed by the reserved platform tables. */
+export function allTableNames(definition) {
+    return [...domainTableNames(definition), ...RESERVED_TABLE_NAMES];
+}
+export function latestVersion(definition) {
+    const last = definition.versions[definition.versions.length - 1];
+    if (!last)
+        throw new Error('database.versions must declare at least one version');
+    return last.version;
+}

package/dist/prototype-database.d.ts

@@ -0,0 +1,34 @@
+import { type DatabaseDefinition, type PrototypeManifest, type Row } from '@protoyard/core';
+import { Dexie, type Table } from 'dexie';
+import { type StorageBackend } from './backend.ts';
+/** The parts of a prototype definition the database layer needs. */
+export interface DatabaseSource {
+    manifest: Pick<PrototypeManifest, 'storage'>;
+    database: DatabaseDefinition;
+}
+/**
+ * A prototype's data database: its own versioned domain tables plus the
+ * reserved `py_*` platform tables, merged into every version so identities and
+ * events survive any domain migration.
+ */
+export declare class PrototypeDatabase extends Dexie {
+    readonly namespace: string;
+    /** Latest schema version declared by the code. */
+    readonly schemaVersion: number;
+    readonly domainTables: readonly string[];
+    readonly reservedTables: readonly string[];
+    constructor(source: DatabaseSource, backend?: StorageBackend);
+    /** Domain tables first, then reserved tables. */
+    get allTables(): readonly string[];
+    hasTable(name: string): boolean;
+    /** Typed table accessor that refuses unknown names with a clear message. */
+    rows<T extends Row = Row>(name: string): Table<T, string>;
+}
+/** Builds the Dexie instance without opening it (Dexie opens lazily). */
+export declare function createPrototypeDatabase(source: DatabaseSource, backend?: StorageBackend): PrototypeDatabase;
+/**
+ * Opens (and migrates) the prototype database. Older databases are upgraded
+ * through each version's `upgrade`; a database written by NEWER code is never
+ * deleted — it is closed and reported as `version-newer`.
+ */
+export declare function openPrototypeDatabase(source: DatabaseSource, backend?: StorageBackend): Promise<PrototypeDatabase>;

package/dist/prototype-database.js

@@ -0,0 +1,82 @@
+import { RESERVED_TABLES, } from '@protoyard/core';
+import { Dexie } from 'dexie';
+import { dexieBackendOptions, resolveFactory } from "./backend.js";
+import { mapStorageError, StorageError } from "./errors.js";
+import { dataDatabaseName, domainTableNames, latestVersion, RESERVED_PREFIX, RESERVED_TABLE_NAMES, } from "./names.js";
+/**
+ * A prototype's data database: its own versioned domain tables plus the
+ * reserved `py_*` platform tables, merged into every version so identities and
+ * events survive any domain migration.
+ */
+export class PrototypeDatabase extends Dexie {
+    namespace;
+    /** Latest schema version declared by the code. */
+    schemaVersion;
+    domainTables;
+    reservedTables = RESERVED_TABLE_NAMES;
+    constructor(source, backend = {}) {
+        const namespace = source.manifest.storage.namespace;
+        super(dataDatabaseName(namespace), dexieBackendOptions(backend));
+        this.namespace = namespace;
+        this.schemaVersion = latestVersion(source.database);
+        this.domainTables = domainTableNames(source.database);
+        for (const version of source.database.versions) {
+            for (const name of Object.keys(version.stores)) {
+                if (name.startsWith(RESERVED_PREFIX)) {
+                    throw new Error(`Table "${name}" uses the reserved "${RESERVED_PREFIX}" prefix. Rename it in database/schema.ts.`);
+                }
+            }
+            const declared = this.version(version.version).stores({
+                ...version.stores,
+                ...RESERVED_TABLES,
+            });
+            const upgrade = version.upgrade;
+            if (upgrade)
+                declared.upgrade((tx) => upgrade(tx));
+        }
+    }
+    /** Domain tables first, then reserved tables. */
+    get allTables() {
+        return [...this.domainTables, ...this.reservedTables];
+    }
+    hasTable(name) {
+        return this.domainTables.includes(name) || this.reservedTables.includes(name);
+    }
+    /** Typed table accessor that refuses unknown names with a clear message. */
+    rows(name) {
+        if (!this.hasTable(name)) {
+            throw new Error(`Unknown table "${name}". Declared tables: ${this.allTables.join(', ')}.`);
+        }
+        return this.table(name);
+    }
+}
+/** Builds the Dexie instance without opening it (Dexie opens lazily). */
+export function createPrototypeDatabase(source, backend = {}) {
+    return new PrototypeDatabase(source, backend);
+}
+/**
+ * Opens (and migrates) the prototype database. Older databases are upgraded
+ * through each version's `upgrade`; a database written by NEWER code is never
+ * deleted — it is closed and reported as `version-newer`.
+ */
+export async function openPrototypeDatabase(source, backend = {}) {
+    resolveFactory(backend);
+    const db = new PrototypeDatabase(source, backend);
+    try {
+        await db.open();
+    }
+    catch (error) {
+        db.close();
+        throw mapStorageError(error);
+    }
+    // Dexie 4 opens newer databases silently (and stores version × 10, plus one
+    // per implicit schema bump), so compare the native version ourselves.
+    const installed = Math.floor(db.backendDB().version / 10);
+    if (installed > db.schemaVersion) {
+        db.close();
+        throw new StorageError('version-newer', {
+            message: `This browser holds data for schema v${installed} of this prototype, but the code only knows v${db.schemaVersion}. Update the prototype or reset its data from DevTools. Nothing was deleted.`,
+        });
+    }
+    return db;
+}

package/dist/storage.d.ts

@@ -0,0 +1,48 @@
+import type { StorageStatus } from '@protoyard/core';
+import { type StorageBackend } from './backend.ts';
+import { type ControlStore } from './control-store.ts';
+import { type ParsedDatabaseName } from './names.ts';
+import { type DatabaseSource, type PrototypeDatabase } from './prototype-database.ts';
+export declare const MEMORY_STORAGE_WARNING = "IndexedDB is unavailable (private browsing or blocked storage). This prototype is running from memory: changes are lost when you close or reload the tab.";
+/**
+ * Reports what storage this browser offers. Never throws: missing APIs simply
+ * leave fields undefined.
+ */
+export declare function probeStorage(backend?: StorageBackend): Promise<StorageStatus>;
+/**
+ * Asks the browser to keep this origin's data under storage pressure. Returns
+ * `false` when refused or unsupported — persistence is never assumed.
+ */
+export declare function requestPersistence(): Promise<boolean>;
+/** Deletes ONLY this prototype's data + control databases. */
+export declare function deleteProtoyardDatabases(namespace: string, backend?: StorageBackend): Promise<void>;
+export interface DatabaseListing {
+    /** False when the browser can't enumerate databases (no `indexedDB.databases()`). */
+    supported: boolean;
+    /** This prototype's databases: the default world and every sandbox. */
+    databases: ParsedDatabaseName[];
+    /** Sandbox names with at least one database, sorted. */
+    sandboxes: string[];
+}
+/**
+ * Lists a prototype's databases, including sandboxes, so DevTools can offer
+ * "Clear N sandboxes". Never throws: an unsupported or failing enumeration
+ * reports `supported: false` with empty lists.
+ */
+export declare function listProtoyardDatabases(namespace: string, backend?: StorageBackend): Promise<DatabaseListing>;
+export interface PrototypeStorage {
+    db: PrototypeDatabase;
+    control: ControlStore;
+    status: StorageStatus;
+    /** The backend actually used (memory backend in degraded mode). */
+    backend: StorageBackend;
+}
+/**
+ * Opens both databases. When IndexedDB cannot be used at all, falls back to an
+ * in-memory backend and says so in `status` — persistence is never faked.
+ * Other failures (quota, newer version, blocked) are thrown: silently switching
+ * to memory there would hide the user's real data.
+ */
+export declare function openPrototypeStorage(source: DatabaseSource, options?: StorageBackend & {
+    allowMemoryFallback?: boolean;
+}): Promise<PrototypeStorage>;

package/dist/storage.js

@@ -0,0 +1,147 @@
+import { loadMemoryBackend, resolveFactory } from "./backend.js";
+import { openControlStore } from "./control-store.js";
+import { isStorageError, StorageError } from "./errors.js";
+import { controlDatabaseName, dataDatabaseName, parseDatabaseName, } from "./names.js";
+import { openPrototypeDatabase, } from "./prototype-database.js";
+function storageManager() {
+    const nav = globalThis.navigator;
+    return nav?.storage && typeof nav.storage.estimate === 'function' ? nav.storage : undefined;
+}
+export const MEMORY_STORAGE_WARNING = 'IndexedDB is unavailable (private browsing or blocked storage). This prototype is running from memory: changes are lost when you close or reload the tab.';
+/**
+ * Reports what storage this browser offers. Never throws: missing APIs simply
+ * leave fields undefined.
+ */
+export async function probeStorage(backend = {}) {
+    let available = true;
+    try {
+        resolveFactory(backend);
+    }
+    catch {
+        available = false;
+    }
+    const status = available
+        ? { backend: 'indexeddb', persistent: true }
+        : { backend: 'memory', persistent: false, warning: MEMORY_STORAGE_WARNING };
+    const manager = storageManager();
+    if (manager) {
+        try {
+            const estimate = await manager.estimate();
+            if (estimate.usage !== undefined)
+                status.usageBytes = estimate.usage;
+            if (estimate.quota !== undefined)
+                status.quotaBytes = estimate.quota;
+        }
+        catch {
+            // Some browsers reject estimate() in private contexts; it is optional.
+        }
+        try {
+            if (typeof manager.persisted === 'function')
+                status.persisted = await manager.persisted();
+        }
+        catch {
+            // Optional API.
+        }
+    }
+    return status;
+}
+/**
+ * Asks the browser to keep this origin's data under storage pressure. Returns
+ * `false` when refused or unsupported — persistence is never assumed.
+ */
+export async function requestPersistence() {
+    const manager = storageManager();
+    if (!manager || typeof manager.persist !== 'function')
+        return false;
+    try {
+        return await manager.persist();
+    }
+    catch {
+        return false;
+    }
+}
+function deleteDatabase(factory, name) {
+    return new Promise((resolve, reject) => {
+        const request = factory.deleteDatabase(name);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+        // Another tab still has it open; the delete completes once it closes.
+        request.onblocked = () => reject(new StorageError('blocked'));
+    });
+}
+/** Deletes ONLY this prototype's data + control databases. */
+export async function deleteProtoyardDatabases(namespace, backend = {}) {
+    const factory = resolveFactory(backend);
+    await deleteDatabase(factory, dataDatabaseName(namespace));
+    await deleteDatabase(factory, controlDatabaseName(namespace));
+}
+/**
+ * Lists a prototype's databases, including sandboxes, so DevTools can offer
+ * "Clear N sandboxes". Never throws: an unsupported or failing enumeration
+ * reports `supported: false` with empty lists.
+ */
+export async function listProtoyardDatabases(namespace, backend = {}) {
+    let factory;
+    try {
+        factory = resolveFactory(backend);
+    }
+    catch {
+        return { supported: false, databases: [], sandboxes: [] };
+    }
+    if (typeof factory.databases !== 'function') {
+        return { supported: false, databases: [], sandboxes: [] };
+    }
+    try {
+        const infos = await factory.databases();
+        const databases = infos
+            .map((info) => (info.name ? parseDatabaseName(info.name) : null))
+            .filter((db) => db !== null && db.namespace === namespace)
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const sandboxes = [
+            ...new Set(databases.flatMap((db) => (db.sandbox ? [db.sandbox] : []))),
+        ].sort();
+        return { supported: true, databases, sandboxes };
+    }
+    catch {
+        return { supported: false, databases: [], sandboxes: [] };
+    }
+}
+/**
+ * Opens both databases. When IndexedDB cannot be used at all, falls back to an
+ * in-memory backend and says so in `status` — persistence is never faked.
+ * Other failures (quota, newer version, blocked) are thrown: silently switching
+ * to memory there would hide the user's real data.
+ */
+export async function openPrototypeStorage(source, options = {}) {
+    const backend = {};
+    if (options.indexedDB)
+        backend.indexedDB = options.indexedDB;
+    if (options.IDBKeyRange)
+        backend.IDBKeyRange = options.IDBKeyRange;
+    const namespace = source.manifest.storage.namespace;
+    try {
+        const db = await openPrototypeDatabase(source, backend);
+        try {
+            const control = await openControlStore(namespace, backend);
+            return { db, control, status: await probeStorage(backend), backend };
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    catch (error) {
+        const unavailable = isStorageError(error) && error.code === 'unavailable';
+        if (!unavailable || options.allowMemoryFallback === false)
+            throw error;
+        const memory = await loadMemoryBackend();
+        const db = await openPrototypeDatabase(source, memory);
+        const control = await openControlStore(namespace, memory);
+        return {
+            db,
+            control,
+            status: { backend: 'memory', persistent: false, warning: MEMORY_STORAGE_WARNING },
+            backend: memory,
+        };
+    }
+}

package/dist/world-io.d.ts

@@ -0,0 +1,21 @@
+import type { Snapshot } from '@protoyard/core';
+import type { PrototypeDatabase } from './prototype-database.ts';
+export type SnapshotTable = Snapshot['tables'][number];
+/** Reads every domain + reserved table in one read transaction (consistent view). */
+export declare function dumpTables(db: PrototypeDatabase): Promise<SnapshotTable[]>;
+export interface RestoreResult {
+    restored: string[];
+    /** Tables present in the input but unknown to this schema. */
+    skipped: string[];
+}
+/**
+ * Replaces the whole world in ONE read-write transaction: every known table is
+ * cleared and refilled. If anything fails (bad row, quota) IndexedDB aborts the
+ * transaction and the current data stays exactly as it was.
+ */
+export declare function restoreTables(db: PrototypeDatabase, tables: readonly SnapshotTable[], options?: {
+    knownTables?: readonly string[];
+}): Promise<RestoreResult>;
+/** Clears domain + reserved tables in one transaction (used before seeding). */
+export declare function clearWorld(db: PrototypeDatabase): Promise<void>;
+export declare function countTables(db: PrototypeDatabase): Promise<Record<string, number>>;

package/dist/world-io.js

@@ -0,0 +1,84 @@
+import { mapStorageError } from "./errors.js";
+/** Rows per bulkAdd inside the single restore transaction. */
+const RESTORE_CHUNK = 1000;
+/** Reads every domain + reserved table in one read transaction (consistent view). */
+export async function dumpTables(db) {
+    const names = db.allTables;
+    try {
+        return await db.transaction('r', [...names], async () => {
+            const out = [];
+            for (const name of names) {
+                out.push({ name, rows: (await db.table(name).toArray()) });
+            }
+            return out;
+        });
+    }
+    catch (error) {
+        throw mapStorageError(error);
+    }
+}
+/**
+ * Replaces the whole world in ONE read-write transaction: every known table is
+ * cleared and refilled. If anything fails (bad row, quota) IndexedDB aborts the
+ * transaction and the current data stays exactly as it was.
+ */
+export async function restoreTables(db, tables, options = {}) {
+    const known = new Set(options.knownTables ?? db.allTables);
+    const restored = [];
+    const skipped = [];
+    const byName = new Map();
+    for (const table of tables) {
+        if (known.has(table.name) && db.hasTable(table.name)) {
+            byName.set(table.name, [...(byName.get(table.name) ?? []), ...table.rows]);
+        }
+        else
+            skipped.push(table.name);
+    }
+    const targets = db.allTables.filter((name) => known.has(name));
+    try {
+        await db.transaction('rw', targets, async () => {
+            for (const name of targets) {
+                const table = db.table(name);
+                await table.clear();
+                const rows = byName.get(name);
+                if (rows?.length) {
+                    // Chunked so big restores keep the page responsive (same as scenario loads).
+                    for (let i = 0; i < rows.length; i += RESTORE_CHUNK) {
+                        await table.bulkAdd(rows.slice(i, i + RESTORE_CHUNK));
+                    }
+                    restored.push(name);
+                }
+            }
+        });
+    }
+    catch (error) {
+        throw mapStorageError(error);
+    }
+    return { restored, skipped };
+}
+/** Clears domain + reserved tables in one transaction (used before seeding). */
+export async function clearWorld(db) {
+    try {
+        await db.transaction('rw', [...db.allTables], async () => {
+            for (const name of db.allTables)
+                await db.table(name).clear();
+        });
+    }
+    catch (error) {
+        throw mapStorageError(error);
+    }
+}
+export async function countTables(db) {
+    const names = db.allTables;
+    try {
+        return await db.transaction('r', [...names], async () => {
+            const counts = {};
+            for (const name of names)
+                counts[name] = await db.table(name).count();
+            return counts;
+        });
+    }
+    catch (error) {
+        throw mapStorageError(error);
+    }
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@protoyard/database",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "IndexedDB persistence for Protoyard prototypes (Dexie): namespaced databases, migrations, control store, snapshot I/O and storage diagnostics.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@protoyard/core": "1.1.0",
+    "dexie": "^4.4.7",
+    "fake-indexeddb": "~6.2.6"
+  },
+  "protoyard": {
+    "build": {
+      "group": "engine",
+      "assets": []
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DailybotHQ/protoyard",
+    "directory": "packages/database"
+  },
+  "homepage": "https://protoyard.app",
+  "bugs": {
+    "url": "https://github.com/DailybotHQ/protoyard/issues"
+  },
+  "keywords": [
+    "protoyard",
+    "indexeddb",
+    "dexie",
+    "prototype"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "types": "./dist/index.d.ts"
 }