@columenlabs/lumen-person 0.0.0-stage → 0.1.144

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Columen Labs
+
+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/NOTICE

@@ -0,0 +1,12 @@
+Lumen
+Copyright (c) 2026 Columen Labs. Licensed under the MIT License (see LICENSE).
+
+Lumen draws price and market charts with TradingView Lightweight Charts™
+(https://github.com/tradingview/lightweight-charts), Copyright (c) 2025
+TradingView, Inc., licensed under the Apache License 2.0. Lumen turns off the
+chart's own logo, so per that library's NOTICE, an app that shows these charts
+should link to https://www.tradingview.com/ somewhere a user can find it (an
+About page or footer is enough).
+
+The components under packages/ui/src/ui are based on shadcn/ui
+(https://ui.shadcn.com), MIT License, Copyright (c) 2023 shadcn.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @columenlabs/lumen-person
 
-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.
+Lumen's one store per person: a Durable Object whose SQLite holds every app's tables for that person. Each app is a module that owns its tables (`<module>_*`), its migrations and its wake time, so app code stays apart while one person's data joins in one SQL query, one backup and one delete. No dependencies: it runs in a Worker with `nodejs_compat` (for `AsyncLocalStorage`) and any Durable Object with SQLite storage.
+
+- Source: https://github.com/columenlabs/lumen (`packages/person`). MIT.
+
+## Install
+
+```bash
+bun add @columenlabs/lumen-person
+```
+
+Pin it to the same exact version as the other Lumen packages.
+
+## A store and its modules
+
+```ts
+import { DurableObject } from 'cloudflare:workers';
+import { PersonObject, type PersonModule, personModule } from '@columenlabs/lumen-person';
+
+const notes: PersonModule<Env> = {
+  name: 'notes',
+  migrations: [
+    'CREATE TABLE notes_items (id INTEGER PRIMARY KEY, title TEXT NOT NULL, at INTEGER NOT NULL)',
+  ],
+  async call(ctx, method, args) {
+    if (method === 'add') {
+      ctx.sql.exec('INSERT INTO notes_items (title, at) VALUES (?, ?)', (args as { title: string }).title, Date.now());
+      await ctx.wakeAt(Date.now() + 60_000);
+      return { ok: true };
+    }
+    throw new Error(`no ${method}`);
+  },
+  async wake(ctx) {
+    // small steps: stop by ctx.deadline and ask for the next time
+  },
+};
+
+export class PersonStore extends DurableObject<Env> {
+  private readonly person = new PersonObject(this.ctx, { modules: [notes], extra: this.env });
+  call(owner: string, module: string, method: string, args?: unknown) {
+    return this.person.call(owner, module, method, args);
+  }
+  alarm() {
+    return this.person.alarm();
+  }
+}
+
+// In the Worker
+const mine = personModule(env.PERSON, email, 'notes');
+await mine.call('add', { title: 'Buy saw blades' });
+```
+
+The first call names the person and claims the store; a later call for anyone else is refused (403).
+
+## Rules it keeps
+
+- **Migrations fail per module.** Each module migrates on its first call or wake, each step in one transaction. A step that throws leaves only that module answering 503 for a minute before it tries again; every other module keeps working. Never edit or reorder a released step: add one.
+- **One alarm for every module.** `_wakes` keeps each module's next time and the store's alarm is the earliest. Each wake gets `ctx.deadline` (30 s by default, `wakeMs`) to stop by and set its next time. A wake that throws is tried again in 1 minute, doubling to an hour.
+- **Waiting is shared, work is not.** While one call awaits the network (a fetch, a model) other calls run. Only synchronous work holds the store, so keep heavy parsing out of it.
+- **Calls stay in place.** Code running in a person's store that calls the same person through `personCall` runs in place instead of a new request.
+
+## Backup, restore, delete
+
+The store's own module `_object` (or `personModule(...).own(method)` for one module):
+
+| Method | Does |
+| --- | --- |
+| `dump` | Every module's tables as stored (sealed values stay sealed), with each module's migration level |
+| `dumpModule {module}` | One module's tables |
+| `loadModule {module, dump, prefix?}` | Replaces one module's tables from a dump. With `prefix`, tables named without it (`items`) load into `<module>_items`, so rows move in from an older store |
+| `load` | Replaces every module's tables from a whole dump |
+| `wipeModule {module}` | Empties one module's tables and its wake |
+| `wipe` | Deletes the whole store (every table, key and the alarm) |
+| `counts` | Rows per table, migration levels and any module whose migration is failing |
+
+## Moving rows in from an older store
+
+An app that kept its own Durable Object moves into the person's store a page at a time, so no step holds either store for long:
+
+- The old store answers `exportRows(sql, table, after)`: rows after a rowid bookmark, at most 500 rows and about 4 MB a page (at least one row, so a big blob still moves), bytes as `{b64}`.
+- The module's wake writes each page with `importRows(sql, table, page)` inside `ctx.transaction`, keeps the bookmark and asks to wake again. Rows keep their rowids, so a page sent twice changes nothing.
+- When every table is across, `rowStats` on both sides (rows and highest rowid per table) must match before the app reads from the new store. Stop the old store's alarm and writes while it moves; a table whose stats differ goes again.
+
+Point-in-time recovery (`ctx.storage.getBookmarkForTime`) restores the whole store, every module at once. Restore one module from its dump instead, and keep PITR for the whole store.
+
+Virtual tables (an FTS5 word index from `@columenlabs/lumen-ai`'s `findSql`) are not copied: their triggers fill them as rows load, and a rebuild runs after.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @columenlabs/lumen-person: one store per person, every app's tables in it. `PersonObject` runs
+ * inside a Durable Object class; `personCall` reaches it from the Worker (or in place, from code
+ * already running in that person's store).
+ */
+import { type PersonReply } from './object.js';
+export * from './move.js';
+export * from './object.js';
+/** What the Worker holds of the Durable Object namespace: the class's RPC `call` passes to `PersonObject.call`. */
+export interface PersonNamespace {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        call(owner: string, module: string, method: string, args?: unknown): Promise<PersonReply>;
+    };
+}
+/** Calls `module.method(args)` in the person's store and returns its value, or throws its `PersonError`. */
+export declare function personCall<T>(ns: PersonNamespace, owner: string, module: string, method: string, args?: unknown): Promise<T>;
+/** One module of one person's store, so app code reads `career.call('stories')`. */
+export declare function personModule(ns: PersonNamespace, owner: string, module: string): {
+    call: <T>(method: string, args?: unknown) => Promise<T>;
+    /** The store's own methods for this module: dumpModule, loadModule, wipeModule. */
+    own: <T>(method: string, args?: Record<string, unknown>) => Promise<T>;
+};

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * @columenlabs/lumen-person: one store per person, every app's tables in it. `PersonObject` runs
+ * inside a Durable Object class; `personCall` reaches it from the Worker (or in place, from code
+ * already running in that person's store).
+ */
+import { OBJECT_MODULE, PersonError, insideStore } from './object.js';
+export * from './move.js';
+export * from './object.js';
+/** Calls `module.method(args)` in the person's store and returns its value, or throws its `PersonError`. */
+export async function personCall(ns, owner, module, method, args) {
+    const here = insideStore();
+    if (here?.owner === owner) {
+        // In place, copied as a stub call copies (structured clone, bytes included), so callers see the same values.
+        try {
+            const out = await here.call(module, method, structuredClone(args ?? null));
+            return (out === undefined ? null : structuredClone(out));
+        }
+        catch (err) {
+            if (err instanceof PersonError)
+                throw err;
+            throw new PersonError(502, `${module} failed`);
+        }
+    }
+    const r = await ns.get(ns.idFromName(owner)).call(owner, module, method, args ?? null);
+    if (!r.ok)
+        throw new PersonError(r.status, r.error);
+    return r.value;
+}
+/** One module of one person's store, so app code reads `career.call('stories')`. */
+export function personModule(ns, owner, module) {
+    return {
+        call: (method, args) => personCall(ns, owner, module, method, args),
+        /** The store's own methods for this module: dumpModule, loadModule, wipeModule. */
+        own: (method, args) => personCall(ns, owner, OBJECT_MODULE, method, { ...args, module }),
+    };
+}

package/dist/json.d.ts

@@ -0,0 +1,3 @@
+/** A SQLite value as JSON carries it: bytes become `{b64}` (no Buffer, so it runs anywhere). */
+export declare function toJson(v: unknown): unknown;
+export declare function fromJson(v: unknown): unknown;

package/dist/json.js

@@ -0,0 +1,23 @@
+/** A SQLite value as JSON carries it: bytes become `{b64}` (no Buffer, so it runs anywhere). */
+export function toJson(v) {
+    if (v instanceof ArrayBuffer || ArrayBuffer.isView(v)) {
+        const bytes = v instanceof ArrayBuffer
+            ? new Uint8Array(v)
+            : new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+        let s = '';
+        for (let i = 0; i < bytes.length; i += 0x8000)
+            s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+        return { b64: btoa(s) };
+    }
+    return v;
+}
+export function fromJson(v) {
+    if (v && typeof v === 'object' && 'b64' in v) {
+        const s = atob(String(v.b64));
+        const bytes = new Uint8Array(s.length);
+        for (let i = 0; i < s.length; i++)
+            bytes[i] = s.charCodeAt(i);
+        return bytes.buffer;
+    }
+    return v;
+}

package/dist/move.d.ts

@@ -0,0 +1,29 @@
+import type { DumpTable, SqlLike } from './object.js';
+/** One page of a table: its columns, rows and their rowids, and the bookmark to ask for next (null: done). */
+export interface RowsPage extends DumpTable {
+    ids: number[];
+    next: number | null;
+}
+/** A table's row count and highest rowid, to check a move is whole. */
+export type RowStats = Record<string, {
+    n: number;
+    max: number;
+}>;
+/**
+ * Rows of `table` after rowid `after`, in rowid order: at most `limit` rows and about `maxBytes`
+ * (at least one row a page, so a big blob still moves). Bytes come as `{b64}`, as in a dump.
+ */
+export declare function exportRows(sql: SqlLike, table: string, after: number, opts?: {
+    limit?: number;
+    maxBytes?: number;
+}): RowsPage;
+/**
+ * Writes a page into `table`, naming only the columns the table has (the rest keep their
+ * defaults) and keeping each row's rowid, so the two stores' `rowStats` match and a page sent
+ * twice changes nothing. Run it inside the module's transaction.
+ */
+export declare function importRows(sql: SqlLike, table: string, page: DumpTable & {
+    ids?: number[];
+}): number;
+/** Row counts and highest rowids of `tables` (a missing table counts as empty). */
+export declare function rowStats(sql: SqlLike, tables: string[]): RowStats;

package/dist/move.js

@@ -0,0 +1,77 @@
+/**
+ * Moving an app's rows in from the Durable Object that held them before, a page at a time, so no
+ * step holds either store for long. The old store answers `exportRows` pages (by rowid, from a
+ * bookmark); the module's wake writes each page with `importRows` and keeps the bookmark, and when
+ * every table is across `rowStats` on both sides says the move is whole. Keep the old store from
+ * writing while it moves (stop its alarm and its writes), or rows it changes behind the bookmark
+ * are missed: `rowStats` then tells, and that table goes again.
+ */
+import { fromJson, toJson } from './json.js';
+const quote = (name) => `"${name.replace(/"/g, '""')}"`;
+/**
+ * Rows of `table` after rowid `after`, in rowid order: at most `limit` rows and about `maxBytes`
+ * (at least one row a page, so a big blob still moves). Bytes come as `{b64}`, as in a dump.
+ */
+export function exportRows(sql, table, after, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 500, 1), 5000);
+    const maxBytes = opts.maxBytes ?? 4_000_000;
+    const cols = sql
+        .exec(`SELECT name FROM pragma_table_info('${table.replace(/'/g, "''")}')`)
+        .toArray()
+        .map((r) => r.name);
+    if (!cols.length)
+        return { cols, rows: [], ids: [], next: null };
+    const found = sql
+        .exec(`SELECT rowid AS _rowid_, * FROM ${quote(table)} WHERE rowid > ? ORDER BY rowid LIMIT ?`, after, limit)
+        .toArray();
+    const rows = [];
+    const ids = [];
+    let bytes = 0;
+    let last = after;
+    for (const r of found) {
+        if (rows.length && bytes > maxBytes)
+            break;
+        const row = cols.map((c) => toJson(r[c]));
+        bytes += JSON.stringify(row).length;
+        rows.push(row);
+        last = Number(r._rowid_);
+        ids.push(last);
+    }
+    const more = rows.length === found.length ? found.length === limit : true;
+    return { cols, rows, ids, next: more ? last : null };
+}
+/**
+ * Writes a page into `table`, naming only the columns the table has (the rest keep their
+ * defaults) and keeping each row's rowid, so the two stores' `rowStats` match and a page sent
+ * twice changes nothing. Run it inside the module's transaction.
+ */
+export function importRows(sql, table, page) {
+    const have = new Set(sql
+        .exec(`SELECT name FROM pragma_table_info('${table.replace(/'/g, "''")}')`)
+        .toArray()
+        .map((r) => r.name));
+    const pick = page.cols.map((c, i) => [c, i]).filter(([c]) => have.has(c));
+    if (!pick.length)
+        return 0;
+    const ids = page.ids?.length === page.rows.length ? page.ids : null;
+    const names = [...(ids ? ['rowid'] : []), ...pick.map(([c]) => quote(c))];
+    const insert = `INSERT OR REPLACE INTO ${quote(table)} (${names.join(', ')}) VALUES (${names.map(() => '?').join(', ')})`;
+    page.rows.forEach((row, k) => sql.exec(insert, ...(ids ? [ids[k]] : []), ...pick.map(([, i]) => fromJson(row[i]))));
+    return page.rows.length;
+}
+/** Row counts and highest rowids of `tables` (a missing table counts as empty). */
+export function rowStats(sql, tables) {
+    const out = {};
+    for (const t of tables) {
+        try {
+            const r = sql
+                .exec(`SELECT COUNT(*) AS n, MAX(rowid) AS max FROM ${quote(t)}`)
+                .toArray()[0];
+            out[t] = { n: Number(r?.n ?? 0), max: Number(r?.max ?? 0) };
+        }
+        catch {
+            out[t] = { n: 0, max: 0 };
+        }
+    }
+    return out;
+}

package/dist/object.d.ts

@@ -0,0 +1,135 @@
+/** The SQLite of a Durable Object (`ctx.storage.sql`): typed loosely, so `SqlStorage` passes as it is. */
+export interface SqlLike {
+    exec<T extends Record<string, any> = Record<string, unknown>>(query: string, ...bindings: any[]): {
+        toArray(): T[];
+    };
+}
+/** What the store needs of `DurableObjectState`. */
+export interface PersonState {
+    storage: {
+        sql: SqlLike;
+        get<T>(key: string): Promise<T | undefined>;
+        put(key: string, value: unknown): Promise<void>;
+        setAlarm(ms: number): Promise<void>;
+        deleteAlarm(): Promise<void>;
+        /** Deletes every key and table of the object, SQLite included. */
+        deleteAll(): Promise<void>;
+        /** Runs `fn` as one SQLite transaction: a throw rolls back every statement in it. */
+        transactionSync<T>(fn: () => T): T;
+    };
+    blockConcurrencyWhile<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** One migration step: SQL (statements separated by `;`) or a function over the SQLite, never async. */
+export type PersonMigration = string | ((sql: SqlLike) => void);
+/** What a module gets on each call and wake. `X` is the app's own (its env, a vault). */
+export interface PersonCtx<X = unknown> {
+    owner: string;
+    module: string;
+    sql: SqlLike;
+    extra: X;
+    /** `fn` as one SQLite transaction (a throw rolls it all back). */
+    transaction<T>(fn: () => T): T;
+    /** Runs `fn` with no other call or wake let in until it ends. Use rarely: it stops the store. */
+    exclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /** When this module wants its `wake` next; null: never. */
+    wakeAt(at: number | null): Promise<void>;
+    /** The time (ms) a wake should stop by and set its next time. A call gets none (Infinity). */
+    deadline: number;
+}
+/** An app's part of the store: its tables, what the Worker may ask of it and its alarm. */
+export interface PersonModule<X = unknown> {
+    /** Lower-case letters and digits; every table of the module is `<name>_*`. */
+    name: string;
+    /** In order; each runs once, inside the object. Never edit or reorder a released step: add one. */
+    migrations: PersonMigration[];
+    call(ctx: PersonCtx<X>, method: string, args: unknown): Promise<unknown>;
+    /** Runs at the time it last asked for (`wakeAt`). Do small steps and ask again for more. */
+    wake?(ctx: PersonCtx<X>): Promise<void>;
+}
+export interface PersonDeps<X = unknown> {
+    modules: PersonModule<X>[];
+    extra: X;
+    /** Names a person may have (the first call claims the store). Default: 1 to 200 non-space characters. */
+    owner?: RegExp;
+    /** Runs once, when the first call claims the store (to list it somewhere). */
+    onClaim?(owner: string): Promise<void>;
+    /** How long one module's wake may run (default 30 s). */
+    wakeMs?: number;
+}
+/** A refusal with a status and a message the person can act on. */
+export declare class PersonError extends Error {
+    readonly status: 400 | 403 | 404 | 409 | 502 | 503;
+    constructor(status: 400 | 403 | 404 | 409 | 502 | 503, message: string);
+}
+/** How a call answers: across RPC an error loses its class, so the status travels in the value. */
+export type PersonReply = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    status: PersonError['status'];
+    error: string;
+};
+/** The store's own module: backup, restore, delete and counts. */
+export declare const OBJECT_MODULE = "_object";
+/** One table of a dump: its columns and rows in that order. Bytes are `{b64}`. */
+export interface DumpTable {
+    cols: string[];
+    rows: unknown[][];
+}
+/** What `dump` (whole store) or `dumpModule` (one module) returns, and `load`/`loadModule` take. */
+export interface PersonDump {
+    owner: string;
+    /** The module dumped; absent for the whole store. */
+    module?: string;
+    at: string;
+    /** Each module's migration level when dumped. */
+    schema: Record<string, number>;
+    tables: Record<string, DumpTable>;
+}
+/** Calls made from inside a store to its own person run in place (a stub call back in is a new request). */
+type Inside = {
+    owner: string;
+    call(module: string, method: string, args: unknown): Promise<unknown>;
+};
+export declare const insideStore: () => Inside | undefined;
+/** One person's store. A Durable Object class holds one and passes its calls and alarm through. */
+export declare class PersonObject<X = unknown> {
+    private readonly state;
+    private readonly load;
+    private deps?;
+    private owner?;
+    private ownerRead;
+    private readonly ready;
+    private readonly broken;
+    constructor(state: PersonState, load: PersonDeps<X> | (() => Promise<PersonDeps<X>>));
+    private get sql();
+    private setup;
+    /** The module's pending migrations, each in its own transaction. False: it is broken for now. */
+    private migrate;
+    private currentOwner;
+    /** The first call names the person; every later one must match. */
+    private claim;
+    private ctx;
+    private arm;
+    private module;
+    /** A call from the Worker (an RPC method on the Durable Object passes it through). */
+    call(owner: string, module: string, method: string, args?: unknown): Promise<PersonReply>;
+    /** The same as `call`, for a store reached by `fetch` with `{owner, module, method, args}`. */
+    fetch(req: Request): Promise<Response>;
+    private run;
+    /** Runs `fn` as code inside this store: its calls to this person stay in place. */
+    private within;
+    private tables;
+    /** Data tables a dump carries: virtual tables (FTS5) and their shadow tables are rebuilt, not copied. */
+    private dataTables;
+    private columns;
+    private schema;
+    private dumpTables;
+    /** Replaces `names` with the dump's rows; only columns this version has, the rest keep defaults. */
+    private loadTables;
+    private own;
+    /** The Durable Object's alarm: each due module's wake in turn, then the next earliest time. */
+    alarm(): Promise<void>;
+}
+export {};

package/dist/object.js

@@ -0,0 +1,387 @@
+/**
+ * One store per person: a Durable Object (named by the person) whose SQLite holds every app's
+ * tables for that person. Each app is a module that owns the tables named `<module>_*`, its own
+ * migrations and its own wake time, so app code stays apart while one person's data can be joined
+ * in one SQL query.
+ *
+ * - Migrations run per module, on that module's first call or wake, each step in one transaction.
+ *   A step that throws leaves the module refusing its own calls (503) for a minute, then it tries
+ *   again; every other module keeps answering.
+ * - One alarm serves every module: `_wakes` keeps each module's next time and the alarm is set to
+ *   the earliest. A wake gets a deadline to stop by and set its next time. A wake that throws is
+ *   tried again later, sooner first (1 minute, doubling to an hour).
+ * - `_object` methods back up, restore and delete one module's tables or the whole store.
+ *
+ * The object is the only writer of its person's data: a sync, a webhook and an edit run in turn,
+ * so a read-modify-write needs no retry loop. Network waits still let other calls in (input gates).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { fromJson, toJson } from './json.js';
+/** A refusal with a status and a message the person can act on. */
+export class PersonError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The store's own module: backup, restore, delete and counts. */
+export const OBJECT_MODULE = '_object';
+const NAME = /^[a-z][a-z0-9]*$/;
+const OWNER = /^[^\s]{1,200}$/;
+const RETRY_MS = 60_000;
+const BACKOFF_MAX_MS = 3_600_000;
+/** An alarm may run 15 minutes; stop starting wakes well before. */
+const ALARM_MS = 10 * 60_000;
+const inside = new AsyncLocalStorage();
+export const insideStore = () => inside.getStore();
+/** One person's store. A Durable Object class holds one and passes its calls and alarm through. */
+export class PersonObject {
+    state;
+    load;
+    deps;
+    owner;
+    ownerRead = false;
+    ready = new Set();
+    broken = new Map();
+    constructor(state, load) {
+        this.state = state;
+        this.load = load;
+    }
+    get sql() {
+        return this.state.storage.sql;
+    }
+    async setup() {
+        this.deps ??= (async () => {
+            const deps = typeof this.load === 'function' ? await this.load() : this.load;
+            for (const m of deps.modules)
+                if (!NAME.test(m.name))
+                    throw new Error(`person module name ${m.name}`);
+            this.sql.exec('CREATE TABLE IF NOT EXISTS _schema (module TEXT PRIMARY KEY, version INTEGER NOT NULL)');
+            this.sql.exec('CREATE TABLE IF NOT EXISTS _wakes (module TEXT PRIMARY KEY, at INTEGER NOT NULL, fails INTEGER NOT NULL DEFAULT 0)');
+            return deps;
+        })();
+        this.deps.catch(() => {
+            this.deps = undefined;
+        });
+        return this.deps;
+    }
+    /** The module's pending migrations, each in its own transaction. False: it is broken for now. */
+    migrate(m) {
+        if (this.ready.has(m.name))
+            return true;
+        const broke = this.broken.get(m.name);
+        if (broke && Date.now() - broke.at < RETRY_MS)
+            return false;
+        try {
+            const row = this.sql
+                .exec('SELECT version FROM _schema WHERE module = ?', m.name)
+                .toArray()[0];
+            for (let v = row?.version ?? 0; v < m.migrations.length; v++) {
+                const step = m.migrations[v];
+                this.state.storage.transactionSync(() => {
+                    if (typeof step === 'string')
+                        this.sql.exec(step);
+                    else
+                        step(this.sql);
+                    this.sql.exec('INSERT INTO _schema (module, version) VALUES (?, ?) ON CONFLICT (module) DO UPDATE SET version = excluded.version', m.name, v + 1);
+                });
+            }
+            this.broken.delete(m.name);
+            this.ready.add(m.name);
+            return true;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            this.broken.set(m.name, { at: Date.now(), error });
+            console.error(JSON.stringify({ event: 'person_migration_failed', module: m.name, error }));
+            return false;
+        }
+    }
+    async currentOwner() {
+        if (!this.ownerRead) {
+            this.owner = await this.state.storage.get('owner');
+            this.ownerRead = true;
+        }
+        return this.owner;
+    }
+    /** The first call names the person; every later one must match. */
+    async claim(deps, owner) {
+        if (!(deps.owner ?? OWNER).test(owner))
+            throw new PersonError(400, 'not a person this store can hold');
+        const now = await this.currentOwner();
+        if (now === owner)
+            return;
+        if (now)
+            throw new PersonError(403, 'not this person’s store');
+        await this.state.storage.put('owner', owner);
+        this.owner = owner;
+        await deps.onClaim?.(owner);
+    }
+    ctx(deps, owner, module, deadline) {
+        return {
+            owner,
+            module,
+            sql: this.sql,
+            extra: deps.extra,
+            deadline,
+            transaction: (fn) => this.state.storage.transactionSync(fn),
+            exclusive: (fn) => this.state.blockConcurrencyWhile(fn),
+            wakeAt: async (at) => {
+                if (at === null)
+                    this.sql.exec('DELETE FROM _wakes WHERE module = ?', module);
+                else
+                    this.sql.exec('INSERT INTO _wakes (module, at, fails) VALUES (?, ?, 0) ON CONFLICT (module) DO UPDATE SET at = excluded.at, fails = 0', module, Math.round(at));
+                await this.arm();
+            },
+        };
+    }
+    async arm() {
+        const next = this.sql
+            .exec('SELECT MIN(at) AS at FROM _wakes')
+            .toArray()[0]?.at;
+        if (next)
+            await this.state.storage.setAlarm(Math.max(next, Date.now()));
+        else
+            await this.state.storage.deleteAlarm();
+    }
+    module(deps, name) {
+        const m = deps.modules.find((x) => x.name === name);
+        if (!m)
+            throw new PersonError(404, `no module ${name}`);
+        if (!this.migrate(m))
+            throw new PersonError(503, `${name} is updating; try again in a minute`);
+        return m;
+    }
+    /** A call from the Worker (an RPC method on the Durable Object passes it through). */
+    async call(owner, module, method, args) {
+        try {
+            const deps = await this.setup();
+            await this.claim(deps, owner);
+            const value = await this.within(deps, owner, () => this.run(deps, owner, module, method, args ?? null));
+            return { ok: true, value: value ?? null };
+        }
+        catch (err) {
+            if (err instanceof PersonError)
+                return { ok: false, status: err.status, error: err.message };
+            console.error(JSON.stringify({ event: 'person_call_failed', module, method, error: String(err) }));
+            return { ok: false, status: 502, error: `${module} failed` };
+        }
+    }
+    /** The same as `call`, for a store reached by `fetch` with `{owner, module, method, args}`. */
+    async fetch(req) {
+        const body = (await req.json().catch(() => null));
+        if (!body?.owner || !body.module || !body.method)
+            return Response.json({ error: 'bad request' }, { status: 400 });
+        const r = await this.call(body.owner, body.module, body.method, body.args);
+        return r.ok ? Response.json(r) : Response.json({ error: r.error }, { status: r.status });
+    }
+    run(deps, owner, module, method, args) {
+        if (module === OBJECT_MODULE)
+            return this.own(deps, method, args);
+        const m = this.module(deps, module);
+        return m.call(this.ctx(deps, owner, m.name, Number.POSITIVE_INFINITY), method, args);
+    }
+    /** Runs `fn` as code inside this store: its calls to this person stay in place. */
+    within(deps, owner, fn) {
+        return inside.run({ owner, call: (module, method, args) => this.run(deps, owner, module, method, args) }, fn);
+    }
+    tables() {
+        return this.sql
+            .exec(
+        // Not SQLite's, the platform's (`_cf_*`) or a local runtime's (`__*`) own tables.
+        "SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\' AND name NOT LIKE '\\_cf\\_%' ESCAPE '\\' AND name NOT LIKE '\\_\\_%' ESCAPE '\\' ORDER BY name")
+            .toArray()
+            .map((r) => ({ name: r.name, virtual: /^\s*CREATE\s+VIRTUAL/i.test(r.sql ?? '') }));
+    }
+    /** Data tables a dump carries: virtual tables (FTS5) and their shadow tables are rebuilt, not copied. */
+    dataTables(prefix) {
+        const all = this.tables();
+        const virtual = all.filter((t) => t.virtual).map((t) => t.name);
+        const shadow = (n) => virtual.some((v) => n.startsWith(`${v}_`));
+        return all
+            .filter((t) => !t.virtual && !shadow(t.name))
+            .map((t) => t.name)
+            .filter((n) => (prefix ? n.startsWith(prefix) : true));
+    }
+    columns(table) {
+        return this.sql
+            .exec(`SELECT name FROM pragma_table_info('${table.replace(/'/g, "''")}')`)
+            .toArray()
+            .map((r) => r.name);
+    }
+    schema() {
+        return Object.fromEntries(this.sql
+            .exec('SELECT module, version FROM _schema')
+            .toArray()
+            .map((r) => [r.module, r.version]));
+    }
+    dumpTables(names) {
+        const tables = {};
+        for (const t of names) {
+            const cols = this.columns(t);
+            const rows = this.sql
+                .exec(`SELECT * FROM "${t}"`)
+                .toArray()
+                .map((r) => cols.map((c) => toJson(r[c])));
+            tables[t] = { cols, rows };
+        }
+        return tables;
+    }
+    /** Replaces `names` with the dump's rows; only columns this version has, the rest keep defaults. */
+    loadTables(names, dump, rename) {
+        const loaded = {};
+        const skipped = [];
+        this.state.storage.transactionSync(() => {
+            this.sql.exec('PRAGMA defer_foreign_keys = ON');
+            for (const t of names)
+                this.sql.exec(`DELETE FROM "${t}"`);
+            for (const [from, data] of Object.entries(dump)) {
+                const t = rename(from);
+                if (!names.includes(t)) {
+                    skipped.push(from);
+                    continue;
+                }
+                const cols = this.columns(t);
+                const pick = data.cols.map((c, i) => [c, i]).filter(([c]) => cols.includes(c));
+                const insert = `INSERT INTO "${t}" (${pick.map(([c]) => `"${c}"`).join(', ')}) VALUES (${pick.map(() => '?').join(', ')})`;
+                for (const row of data.rows)
+                    this.sql.exec(insert, ...pick.map(([, i]) => fromJson(row[i])));
+                loaded[t] = data.rows.length;
+            }
+        });
+        // Word indexes kept by triggers are already in step; a rebuild covers any that are not.
+        for (const v of this.tables().filter((x) => x.virtual)) {
+            try {
+                this.sql.exec(`INSERT INTO "${v.name}"("${v.name}") VALUES ('rebuild')`);
+            }
+            catch {
+                // Not an FTS5 table with its own content: nothing to rebuild.
+            }
+        }
+        return { loaded, skipped };
+    }
+    async own(deps, method, args) {
+        const owner = this.owner;
+        const a = (args ?? {});
+        const named = () => {
+            if (!a.module)
+                throw new PersonError(400, 'name the module');
+            return this.module(deps, a.module);
+        };
+        switch (method) {
+            case 'dump':
+                for (const m of deps.modules)
+                    this.migrate(m);
+                return {
+                    owner,
+                    at: new Date().toISOString(),
+                    schema: this.schema(),
+                    tables: this.dumpTables(this.dataTables().filter((t) => !t.startsWith('_'))),
+                };
+            case 'dumpModule': {
+                const m = named();
+                return {
+                    owner,
+                    module: m.name,
+                    at: new Date().toISOString(),
+                    schema: { [m.name]: this.schema()[m.name] ?? 0 },
+                    tables: this.dumpTables(this.dataTables(`${m.name}_`)),
+                };
+            }
+            case 'loadModule': {
+                // Restores one module (from its own dump), or moves rows in from an older store: table
+                // names without the prefix get it (`stories` → `career_stories`) when `prefix` is set.
+                const m = named();
+                const dump = a.dump;
+                if (!dump?.tables)
+                    throw new PersonError(400, 'loadModule takes a dump');
+                if (dump.owner && dump.owner !== owner)
+                    throw new PersonError(400, 'that dump is another person’s');
+                const p = `${m.name}_`;
+                return this.state.blockConcurrencyWhile(async () => this.loadTables(this.dataTables(p), dump.tables, (t) => a.prefix && !t.startsWith(p) ? p + t : t));
+            }
+            case 'load': {
+                const dump = args;
+                if (!dump?.tables || dump.owner !== owner)
+                    throw new PersonError(400, 'load takes this person’s dump');
+                for (const m of deps.modules)
+                    this.migrate(m);
+                return this.state.blockConcurrencyWhile(async () => {
+                    const out = this.loadTables(this.dataTables().filter((t) => !t.startsWith('_')), dump.tables, (t) => t);
+                    await this.arm();
+                    return out;
+                });
+            }
+            case 'counts': {
+                const counts = {};
+                for (const t of this.dataTables())
+                    counts[t] = Number(this.sql.exec(`SELECT COUNT(*) AS n FROM "${t}"`).toArray()[0]?.n ?? 0);
+                return { schema: this.schema(), counts, broken: Object.fromEntries(this.broken) };
+            }
+            case 'wipeModule': {
+                const m = named();
+                this.state.storage.transactionSync(() => {
+                    for (const t of this.dataTables(`${m.name}_`))
+                        this.sql.exec(`DELETE FROM "${t}"`);
+                    this.sql.exec('DELETE FROM _wakes WHERE module = ?', m.name);
+                });
+                await this.arm();
+                return { wiped: m.name };
+            }
+            case 'wipe':
+                await this.state.storage.deleteAlarm();
+                await this.state.storage.deleteAll();
+                // The next call starts over: migrations again, then the first call claims it.
+                this.deps = undefined;
+                this.ready.clear();
+                this.broken.clear();
+                this.owner = undefined;
+                this.ownerRead = false;
+                return { wiped: true };
+            default:
+                throw new PersonError(404, `no ${OBJECT_MODULE} method ${method}`);
+        }
+    }
+    /** The Durable Object's alarm: each due module's wake in turn, then the next earliest time. */
+    async alarm() {
+        const deps = await this.setup();
+        const owner = await this.currentOwner();
+        if (!owner)
+            return;
+        const start = Date.now();
+        const due = this.sql
+            .exec('SELECT module, fails FROM _wakes WHERE at <= ? ORDER BY at', start + 1000)
+            .toArray();
+        for (const { module, fails } of due) {
+            if (Date.now() - start > ALARM_MS)
+                break; // the rest stay due; the alarm comes straight back
+            const m = deps.modules.find((x) => x.name === module);
+            if (!m?.wake) {
+                this.sql.exec('DELETE FROM _wakes WHERE module = ?', module);
+                continue;
+            }
+            if (!this.migrate(m)) {
+                this.sql.exec('UPDATE _wakes SET at = ? WHERE module = ?', Date.now() + RETRY_MS, module);
+                continue;
+            }
+            // A module that sets no new time is not woken again.
+            this.sql.exec('DELETE FROM _wakes WHERE module = ?', module);
+            const wake = m.wake.bind(m);
+            try {
+                await this.within(deps, owner, () => wake(this.ctx(deps, owner, module, Date.now() + (deps.wakeMs ?? 30_000))));
+            }
+            catch (err) {
+                const wait = Math.min(RETRY_MS * 2 ** fails, BACKOFF_MAX_MS);
+                this.sql.exec('INSERT INTO _wakes (module, at, fails) VALUES (?, ?, ?) ON CONFLICT (module) DO UPDATE SET at = MIN(_wakes.at, excluded.at), fails = excluded.fails', module, Date.now() + wait, fails + 1);
+                console.error(JSON.stringify({
+                    event: 'person_wake_failed',
+                    module,
+                    fails: fails + 1,
+                    error: String(err),
+                }));
+            }
+        }
+        await this.arm();
+    }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@columenlabs/lumen-person",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.144",
+  "description": "Lumen's one store per person: a Durable Object whose SQLite holds every app's tables for that person, with migrations that fail per app, one alarm shared by every app, and backup, restore and delete per app or whole.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "homepage": "https://github.com/columenlabs/lumen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/columenlabs/lumen.git",
+    "directory": "packages/person"
+  },
+  "bugs": "https://github.com/columenlabs/lumen/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {}
+}