@columenlabs/lumen-person 0.1.162 → 0.1.164

package/README.md

@@ -53,6 +53,19 @@ 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).
 
+## Row budgets: no loop can spend the account's day
+
+Cloudflare's free plan allows an account 5M Durable Objects rows read and 100k rows written a day, across every object. Past either, every SQL call in every object throws until 00:00 UTC. Every store is bounded (`budget` in its deps, `RowBudget` in `./budget` for any other object):
+
+| Bound | Default | Past it |
+|---|---|---|
+| One call | 100k rows read, 20k written | its next statement throws; the call answers 503 |
+| One wake | 200k read, 20k written | the same, for that wake |
+| The store's UTC day | 600k read, 12k written | calls answer 503 until 00:00 UTC |
+| `background` share of the day | 0.6 | wakes wait for the next day (spread over its first half hour); calls keep working |
+
+Counts are the cursors' own `rowsRead` and `rowsWritten`, what Cloudflare bills. `onLimit` hears each level once a day (alert someone there). `_object.budget` reads today's totals and `_object.brake {level: 'background' | 'stop' | 'ok', until?}` sets a brake from outside, for when the whole account nears its cap; both answer on a spent day. A request that needs more than one call's budget (an import, a rebuild) is a background job in small wakes, never one request.
+
 ## 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.

package/dist/budget.d.ts

@@ -0,0 +1,88 @@
+export interface RowLimits {
+    /** Rows one call may read (default 100k). */
+    callRead?: number;
+    /** Rows one call may write (default 20k). */
+    callWrite?: number;
+    /** Rows one wake may read (default 200k). */
+    wakeRead?: number;
+    /** Rows one wake may write (default 20k). */
+    wakeWrite?: number;
+    /** Rows this object may read in one UTC day (default 600k). */
+    dayRead?: number;
+    /** Rows this object may write in one UTC day (default 12k). */
+    dayWrite?: number;
+    /** Share of the day after which wakes wait for the next day (default 0.6). */
+    background?: number;
+}
+export type BudgetLevel = 'ok' | 'background' | 'stop';
+/** What `onLimit` hears, once per level per day, and what `_object.budget` returns. */
+export interface BudgetState {
+    day: string;
+    read: number;
+    written: number;
+    level: BudgetLevel;
+    brake: BudgetLevel;
+    limits: Required<RowLimits>;
+}
+export interface BudgetHooks {
+    /** A level crossed today (`background`, `stop`) or one call or wake stopped (`call`, `wake`). */
+    onLimit?(e: {
+        kind: 'background' | 'stop' | 'call' | 'wake';
+        state: BudgetState;
+    }): void;
+}
+export declare const DEFAULT_LIMITS: Required<RowLimits>;
+/** A spent budget: the person sees a 503 that says when it comes back. */
+export declare class BudgetError extends Error {
+    readonly status: 503;
+}
+/** The UTC day of `now` (`2026-10-29`). */
+export declare const utcDay: (now?: number) => string;
+/** The next 00:00 UTC after `now`. */
+export declare function nextUtcDay(now?: number): number;
+interface BudgetStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+}
+/** One object's row budget. Wrap its SQL with `sql()`, run each call or wake in `scope()`. */
+export declare class RowBudget {
+    private readonly storage;
+    private readonly hooks;
+    readonly limits: Required<RowLimits>;
+    private day;
+    private read;
+    private written;
+    private brake;
+    private told;
+    private loaded?;
+    private savedAt;
+    private loose;
+    constructor(storage: BudgetStorage, limits?: RowLimits, hooks?: BudgetHooks);
+    /** Reads the day's saved totals once (one row). */
+    load(): Promise<void>;
+    /** The SQLite with every statement counted against the current call or wake, and the object. */
+    sql<S extends {
+        exec(query: string, ...b: unknown[]): unknown;
+    }>(raw: S): S;
+    private roll;
+    /** Moves finished counts onto the day's totals. */
+    private settle;
+    private settleLoose;
+    /** The level today's totals and the brake give. */
+    level(): BudgetLevel;
+    state(): BudgetState;
+    private tell;
+    /** Throws before a statement that would run past the call's, wake's or day's budget. */
+    private check;
+    /** Whether a call may start now (false: the day is spent or the brake is on). */
+    callAllowed(): boolean;
+    /** Whether background work may start now. */
+    wakeAllowed(): boolean;
+    /** Runs `fn` as one call or wake, counted on its own and then on the day. */
+    scope<T>(kind: 'call' | 'wake', fn: () => Promise<T>): Promise<T>;
+    /** A brake from outside (`ok` lifts it); it ends by itself at `until` (default next 00:00 UTC). */
+    setBrake(level: BudgetLevel, until?: number): Promise<BudgetState>;
+    /** Saves the day's totals (at most once a minute unless forced). */
+    save(force?: boolean): Promise<void>;
+}
+export {};

package/dist/budget.js

@@ -0,0 +1,231 @@
+/**
+ * Row budgets for a Durable Object's SQLite. Cloudflare's free plan allows an account 5M rows
+ * read and 100k rows written a day across every object; past either, every SQL call in every
+ * object throws until 00:00 UTC. One looping page or a full-table scan per request can spend that
+ * in minutes, so every call, wake and object here is bounded:
+ *
+ *   per call   one request may read and write so many rows; past it, its next statement throws
+ *   per wake   the same for one alarm wake (background work)
+ *   per day    the object's share of the account for one UTC day; past `background` of it, wakes
+ *              wait for the next day; past all of it, calls are refused until 00:00 UTC
+ *   brake      a level set from outside (the whole account is near its cap): `background` stops
+ *              wakes, `stop` refuses calls too
+ *
+ * Counts come from the cursors themselves (`rowsRead`, `rowsWritten`), so they are what Cloudflare
+ * bills. The day's totals live in memory and are saved to storage at most once a minute.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const DEFAULT_LIMITS = {
+    callRead: 100_000,
+    callWrite: 20_000,
+    wakeRead: 200_000,
+    wakeWrite: 20_000,
+    dayRead: 600_000,
+    dayWrite: 12_000,
+    background: 0.6,
+};
+/** A spent budget: the person sees a 503 that says when it comes back. */
+export class BudgetError extends Error {
+    status = 503;
+}
+const scopes = new AsyncLocalStorage();
+/** The UTC day of `now` (`2026-10-29`). */
+export const utcDay = (now = Date.now()) => new Date(now).toISOString().slice(0, 10);
+/** The next 00:00 UTC after `now`. */
+export function nextUtcDay(now = Date.now()) {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+const sum = (cs, k) => cs.reduce((n, c) => n + (Number(c[k]) || 0), 0);
+const KEY = '_row_budget';
+const FLUSH_MS = 60_000;
+/** One object's row budget. Wrap its SQL with `sql()`, run each call or wake in `scope()`. */
+export class RowBudget {
+    storage;
+    hooks;
+    limits;
+    day = utcDay();
+    read = 0;
+    written = 0;
+    brake = { level: 'ok', until: 0 };
+    told = new Set();
+    loaded;
+    savedAt = 0;
+    loose = [];
+    constructor(storage, limits = {}, hooks = {}) {
+        this.storage = storage;
+        this.hooks = hooks;
+        this.limits = { ...DEFAULT_LIMITS, ...limits };
+    }
+    /** Reads the day's saved totals once (one row). */
+    load() {
+        this.loaded ??= (async () => {
+            const s = await this.storage
+                .get(KEY)
+                .catch(() => undefined);
+            if (s?.day === this.day) {
+                this.read = Math.max(this.read, s.read);
+                this.written = Math.max(this.written, s.written);
+            }
+            if (s?.brake && s.brake.until > Date.now())
+                this.brake = s.brake;
+        })();
+        return this.loaded;
+    }
+    /** The SQLite with every statement counted against the current call or wake, and the object. */
+    sql(raw) {
+        const self = this;
+        return new Proxy(raw, {
+            get(t, p) {
+                if (p !== 'exec')
+                    return Reflect.get(t, p, t);
+                return (query, ...b) => {
+                    self.check();
+                    const cur = t.exec(query, ...b);
+                    const s = scopes.getStore();
+                    if (s)
+                        s.cursors.push(cur);
+                    else
+                        self.loose.push(cur);
+                    return cur;
+                };
+            },
+        });
+    }
+    roll() {
+        const today = utcDay();
+        if (today === this.day)
+            return;
+        this.day = today;
+        this.read = 0;
+        this.written = 0;
+        this.told.clear();
+    }
+    /** Moves finished counts onto the day's totals. */
+    settle(cursors) {
+        this.roll();
+        this.read += sum(cursors, 'rowsRead');
+        this.written += sum(cursors, 'rowsWritten');
+    }
+    settleLoose() {
+        if (!this.loose.length)
+            return;
+        const l = this.loose;
+        this.loose = [];
+        this.settle(l);
+    }
+    /** The level today's totals and the brake give. */
+    level() {
+        this.settleLoose();
+        this.roll();
+        const l = this.limits;
+        const brake = this.brake.until > Date.now() ? this.brake.level : 'ok';
+        if (brake === 'stop' || this.read >= l.dayRead || this.written >= l.dayWrite)
+            return 'stop';
+        if (brake === 'background' ||
+            this.read >= l.dayRead * l.background ||
+            this.written >= l.dayWrite * l.background)
+            return 'background';
+        return 'ok';
+    }
+    state() {
+        const level = this.level();
+        return {
+            day: this.day,
+            read: this.read,
+            written: this.written,
+            level,
+            brake: this.brake.until > Date.now() ? this.brake.level : 'ok',
+            limits: this.limits,
+        };
+    }
+    tell(kind) {
+        const key = kind === 'call' || kind === 'wake' ? `${kind}:${Math.floor(Date.now() / 3_600_000)}` : kind;
+        if (this.told.has(key))
+            return;
+        this.told.add(key);
+        try {
+            this.hooks.onLimit?.({ kind, state: this.state() });
+        }
+        catch { }
+        console.error(JSON.stringify({ event: 'row_budget', kind, ...this.state(), limits: undefined }));
+    }
+    /** Throws before a statement that would run past the call's, wake's or day's budget. */
+    check() {
+        const s = scopes.getStore();
+        if (s) {
+            const read = s.read + sum(s.cursors, 'rowsRead');
+            const written = s.written + sum(s.cursors, 'rowsWritten');
+            const l = this.limits;
+            const [r, w] = s.kind === 'call' ? [l.callRead, l.callWrite] : [l.wakeRead, l.wakeWrite];
+            if (read >= r || written >= w) {
+                this.tell(s.kind);
+                throw new BudgetError(`this ${s.kind === 'call' ? 'request' : 'background step'} reads or writes too much at once (${read} rows read, ${written} written)`);
+            }
+            // Only a step past the whole day's budget is stopped mid-way; background waits at its start.
+            if (this.read + read >= l.dayRead || this.written + written >= l.dayWrite) {
+                this.tell('stop');
+                throw new BudgetError(stopMessage());
+            }
+        }
+        else if (this.level() === 'stop') {
+            this.tell('stop');
+            throw new BudgetError(stopMessage());
+        }
+    }
+    /** Whether a call may start now (false: the day is spent or the brake is on). */
+    callAllowed() {
+        const ok = this.level() !== 'stop';
+        if (!ok)
+            this.tell('stop');
+        return ok;
+    }
+    /** Whether background work may start now. */
+    wakeAllowed() {
+        const level = this.level();
+        if (level !== 'ok')
+            this.tell(level);
+        return level === 'ok';
+    }
+    /** Runs `fn` as one call or wake, counted on its own and then on the day. */
+    async scope(kind, fn) {
+        const s = { kind, cursors: [], read: 0, written: 0 };
+        try {
+            return await scopes.run(s, fn);
+        }
+        finally {
+            this.settle(s.cursors);
+            const level = this.level();
+            if (level !== 'ok')
+                this.tell(level);
+            void this.save();
+        }
+    }
+    /** A brake from outside (`ok` lifts it); it ends by itself at `until` (default next 00:00 UTC). */
+    async setBrake(level, until = nextUtcDay()) {
+        this.brake = { level, until: level === 'ok' ? 0 : until };
+        await this.save(true);
+        return this.state();
+    }
+    /** Saves the day's totals (at most once a minute unless forced). */
+    async save(force = false) {
+        if (!force && Date.now() - this.savedAt < FLUSH_MS)
+            return;
+        this.savedAt = Date.now();
+        this.settleLoose();
+        try {
+            await this.storage.put(KEY, {
+                day: this.day,
+                read: this.read,
+                written: this.written,
+                brake: this.brake,
+            });
+        }
+        catch {
+            // The storage itself may be refusing (the account's limit): the totals stay in memory.
+        }
+    }
+}
+function stopMessage(now = Date.now()) {
+    return `today's storage budget is used; it comes back at ${new Date(nextUtcDay(now)).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * already running in that person's store).
  */
 import { type PersonReply } from './object.js';
+export * from './budget.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`. */

package/dist/index.js

@@ -4,6 +4,7 @@
  * already running in that person's store).
  */
 import { OBJECT_MODULE, PersonError, insideStore } from './object.js';
+export * from './budget.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`. */

package/dist/object.d.ts

@@ -1,7 +1,10 @@
+import { type BudgetHooks, type RowLimits } from './budget.js';
 /** 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[];
+        rowsRead?: number;
+        rowsWritten?: number;
     };
 }
 /** What the store needs of `DurableObjectState`. */
@@ -55,6 +58,11 @@ export interface PersonDeps<X = unknown> {
     onClaim?(owner: string): Promise<void>;
     /** How long one module's wake may run (default 30 s). */
     wakeMs?: number;
+    /**
+     * Row budgets for this store (`./budget`): per call, per wake and per UTC day, so no loop can
+     * spend the account's daily Durable Objects limit. Left out, the defaults apply.
+     */
+    budget?: RowLimits & BudgetHooks;
 }
 /** A refusal with a status and a message the person can act on. */
 export declare class PersonError extends Error {
@@ -102,8 +110,13 @@ export declare class PersonObject<X = unknown> {
     private ownerRead;
     private readonly ready;
     private readonly broken;
+    private rows?;
+    private metered?;
     constructor(state: PersonState, load: PersonDeps<X> | (() => Promise<PersonDeps<X>>));
+    /** The SQLite, every statement counted against the row budget once it is set up. */
     private get sql();
+    /** The store's row budget (set up with the first call or wake). */
+    private budget;
     private setup;
     /** The module's pending migrations, each in its own transaction. False: it is broken for now. */
     private migrate;

package/dist/object.js

@@ -16,6 +16,7 @@
  * 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 { BudgetError, RowBudget, nextUtcDay, } from './budget.js';
 import { fromJson, toJson } from './json.js';
 /** A refusal with a status and a message the person can act on. */
 export class PersonError extends Error {
@@ -44,21 +45,35 @@ export class PersonObject {
     ownerRead = false;
     ready = new Set();
     broken = new Map();
+    rows;
+    metered;
     constructor(state, load) {
         this.state = state;
         this.load = load;
     }
+    /** The SQLite, every statement counted against the row budget once it is set up. */
     get sql() {
-        return this.state.storage.sql;
+        if (!this.rows)
+            return this.state.storage.sql;
+        this.metered ??= this.rows.sql(this.state.storage.sql);
+        return this.metered;
+    }
+    /** The store's row budget (set up with the first call or wake). */
+    budget(deps) {
+        this.rows ??= new RowBudget(this.state.storage, deps.budget, deps.budget);
+        return this.rows;
     }
     async setup() {
         this.deps ??= (async () => {
             const deps = typeof this.load === 'function' ? await this.load() : this.load;
+            await this.budget(deps).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)');
+            // The store's own two tables, unmetered so the budget can answer even on a spent day.
+            const raw = this.state.storage.sql;
+            raw.exec('CREATE TABLE IF NOT EXISTS _schema (module TEXT PRIMARY KEY, version INTEGER NOT NULL)');
+            raw.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(() => {
@@ -157,13 +172,23 @@ export class PersonObject {
     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));
+            const rows = this.budget(deps);
+            // The budget itself answers even when the day is spent: it reads no rows.
+            if (module === OBJECT_MODULE && (method === 'budget' || method === 'brake'))
+                return { ok: true, value: await this.own(deps, method, args ?? null) };
+            if (!rows.callAllowed())
+                throw new BudgetError(spentMessage());
+            const value = await rows.scope('call', async () => {
+                await this.claim(deps, owner);
+                return 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 };
+            if (err instanceof BudgetError)
+                return { ok: false, status: 503, error: err.message };
             console.error(JSON.stringify({ event: 'person_call_failed', module, method, error: String(err) }));
             return { ok: false, status: 502, error: `${module} failed` };
         }
@@ -270,6 +295,15 @@ export class PersonObject {
             return this.module(deps, a.module);
         };
         switch (method) {
+            case 'budget':
+                return this.budget(deps).state();
+            case 'brake': {
+                // From the Worker when the whole account nears its cap: `background` stops wakes, `stop` calls too.
+                const b = (args ?? {});
+                if (b.level !== 'ok' && b.level !== 'background' && b.level !== 'stop')
+                    throw new PersonError(400, 'brake takes level ok, background or stop');
+                return this.budget(deps).setBrake(b.level, b.until);
+            }
             case 'dump':
                 for (const m of deps.modules)
                     this.migrate(m);
@@ -349,6 +383,21 @@ export class PersonObject {
         const owner = await this.currentOwner();
         if (!owner)
             return;
+        const rows = this.budget(deps);
+        if (!rows.wakeAllowed()) {
+            // Background work waits for the next UTC day (spread over its first half hour), so the
+            // budget left today serves the person's own requests. Unmetered: two small statements.
+            const raw = this.state.storage.sql;
+            const at = nextUtcDay() + Math.floor(Math.random() * 30 * 60_000);
+            try {
+                raw.exec('UPDATE _wakes SET at = ? WHERE at < ?', at, at);
+                await this.state.storage.setAlarm(at);
+            }
+            catch {
+                // Storage refusing too: the alarm is not set again, the next call or wake sets it.
+            }
+            return;
+        }
         const start = Date.now();
         const due = this.sql
             .exec('SELECT module, fails FROM _wakes WHERE at <= ? ORDER BY at', start + 1000)
@@ -369,7 +418,7 @@ export class PersonObject {
             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))));
+                await rows.scope('wake', () => 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);
@@ -385,3 +434,6 @@ export class PersonObject {
         await this.arm();
     }
 }
+function spentMessage() {
+    return `today's storage budget is used; it comes back at ${new Date(nextUtcDay()).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-person",
-  "version": "0.1.162",
+  "version": "0.1.164",
   "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",