@north-light/api 0.3.579 → 0.3.587

package/dist/core/ledger/check.d.ts

@@ -0,0 +1,48 @@
+import { RunError } from '../runs/operations.js';
+import type { Funding, Limit } from './types.js';
+/** A model or tool call, checked before it is sent: everything about it is known. A limit matches when its `payer` equals
+ *  the candidate's and each of its non-null filters equals the candidate's value. */
+export interface CallCandidate {
+    scope: 'call';
+    payer: string;
+    /** The principal Northlight invoices for `payer`; absent means the function finds the payer's holder. */
+    account?: string | null;
+    funding: Funding;
+    sub: string | null;
+    grantee: string;
+    provider: string | null;
+}
+/** A node birth, `run.start`, cron fire, job start or dormant revive. `payer` is whoever pays the node's model calls. A limit
+ *  matches only when its `funding` and `provider` are both null and its other filters match: only a limit that would refuse
+ *  every charge of that payer (a $0 stop, or app Y's cap on the person) can stop a start. */
+export interface StartCandidate {
+    scope: 'start';
+    payer: string;
+    account?: string | null;
+    sub: string | null;
+    grantee: string;
+}
+export type Candidate = CallCandidate | StartCandidate;
+/** The limit that refused and what had been spent against it. */
+export interface Refusal {
+    limit: Limit;
+    usd: number;
+    month: string;
+    reset_at: string;
+}
+/** The first limit (by id) that refuses `candidate` this month, or null. One call to the SQL function `ledger_check`
+ *  (schema delta 007), which holds the rule. */
+export declare function findRefusal(candidate: Candidate, at?: Date): Promise<Refusal | null>;
+/** The `user_action` a person can take for a limit of this source; absent for an operator limit. */
+export declare function userActionOf(source: Limit['source']): 'raise_cap' | 'clear_limit' | undefined;
+/** `402 cap_exhausted` for a refusal. Details: `limit` (id, payer, filters, usd_per_month, source), `usd`, `reset_at`, and
+ *  `user_action` when the person can act; plus the deprecated `spend_cap` (= `limit.usd_per_month`) and `usd_equivalent` (= `usd`)
+ *  that the refusal carried before the ledger, kept so a caller that reads them still gets the numbers. */
+export declare function refusalError(refusal: Refusal): RunError;
+/** Throw `refusalError` when a limit refuses `candidate`. */
+export declare function check(candidate: Candidate, at?: Date): Promise<void>;
+/** The mark stored on the refused row a site writes before it moves to the next candidate. */
+export declare const refusedMark: (refusal: Refusal) => {
+    limit: string;
+    reason: string;
+};

package/dist/core/ledger/check.js

@@ -0,0 +1,38 @@
+// The check (design-ledger, "The check"): one SQL statement selects the limits that match the candidate and sums, for each,
+// the current month's `charge_totals` rows that match that limit's non-null fields. A limit refuses when its sum is greater
+// than or equal to it. No reservation: one call may go over a limit and the next is refused.
+import { openDb } from '../canvas/db.js';
+import { RunError } from '../runs/operations.js';
+import { usageMonth } from './months.js';
+/** The first limit (by id) that refuses `candidate` this month, or null. One call to the SQL function `ledger_check`
+ *  (schema delta 007), which holds the rule. */
+export async function findRefusal(candidate, at = new Date()) {
+    const input = { ...candidate, month: usageMonth(at) };
+    const row = await (await openDb()).prepare('SELECT ledger_check(?::jsonb) AS refusal').get(JSON.stringify(input));
+    const found = typeof row?.refusal === 'string' ? JSON.parse(row.refusal) : row?.refusal ?? null;
+    return found;
+}
+/** The `user_action` a person can take for a limit of this source; absent for an operator limit. */
+export function userActionOf(source) {
+    return source === 'grant_sync' ? 'raise_cap' : source === 'person' ? 'clear_limit' : undefined;
+}
+/** `402 cap_exhausted` for a refusal. Details: `limit` (id, payer, filters, usd_per_month, source), `usd`, `reset_at`, and
+ *  `user_action` when the person can act; plus the deprecated `spend_cap` (= `limit.usd_per_month`) and `usd_equivalent` (= `usd`)
+ *  that the refusal carried before the ledger, kept so a caller that reads them still gets the numbers. */
+export function refusalError(refusal) {
+    const { limit } = refusal;
+    const userAction = userActionOf(limit.source);
+    return new RunError(402, 'cap_exhausted', `${limit.payer ?? limit.account} reached its monthly limit (${limit.id})`, undefined, {
+        limit: { id: limit.id, payer: limit.payer, account: limit.account, filters: { account: limit.account, funding: limit.funding, grantee: limit.grantee, provider: limit.provider, sub: limit.sub },
+            usd_per_month: limit.usd_per_month, source: limit.source },
+        usd: refusal.usd, reset_at: refusal.reset_at, spend_cap: limit.usd_per_month, usd_equivalent: refusal.usd, ...(userAction === undefined ? {} : { user_action: userAction }),
+    });
+}
+/** Throw `refusalError` when a limit refuses `candidate`. */
+export async function check(candidate, at) {
+    const refusal = await findRefusal(candidate, at);
+    if (refusal !== null)
+        throw refusalError(refusal);
+}
+/** The mark stored on the refused row a site writes before it moves to the next candidate. */
+export const refusedMark = (refusal) => ({ limit: refusal.limit.id, reason: `${refusal.limit.payer ?? refusal.limit.account} reached ${refusal.limit.usd_per_month} USD this month (spent ${refusal.usd})` });

package/dist/core/ledger/chunks.d.ts

@@ -0,0 +1,8 @@
+import type { Charge } from './types.js';
+/** The moved rows of a month (or of every month), read once per instance. A chunk row whose blob is missing throws: the rows are nowhere else. */
+export declare class ChunkRows {
+    private readonly byMonth;
+    private all;
+    rows(month?: string): Promise<Charge[]>;
+    private load;
+}

package/dist/core/ledger/chunks.js

@@ -0,0 +1,43 @@
+// Charge rows the `ledger-r2` lane moved out of `charges`: one `charge_chunks` row per (month, payer) names a zstd-compressed
+// JSON-lines blob of `to_jsonb(charges)` rows. The read side (read.ts) merges these with the live rows, so a moved month reads
+// exactly as it did before the move.
+import { zstdDecompressSync } from 'node:zlib';
+import { blobStore } from '../blobs/index.js';
+import { openDb } from '../canvas/db.js';
+import { chargeOf } from './charges.js';
+const FIELDS = ['id', 'request', 'at', 'month', 'kind', 'what', 'units', 'usd', 'payer', 'funding', 'sub', 'grantee', 'node', 'run', 'provider', 'caused_by', 'vendor_ref', 'refused', 'account', 'billed_usd'];
+/** The moved rows of a month (or of every month), read once per instance. A chunk row whose blob is missing throws: the rows are nowhere else. */
+export class ChunkRows {
+    byMonth = new Map();
+    all;
+    rows(month) {
+        if (month === undefined)
+            return this.all ??= this.load(undefined);
+        let found = this.byMonth.get(month);
+        if (found === undefined) {
+            found = this.load(month);
+            this.byMonth.set(month, found);
+        }
+        return found;
+    }
+    async load(month) {
+        const chunks = await (await openDb()).prepareUncached(`SELECT blob_key FROM charge_chunks${month === undefined ? '' : ' WHERE month = ?'} ORDER BY month, payer`)
+            .all(...(month === undefined ? [] : [month]));
+        if (chunks.length === 0)
+            return [];
+        const store = await blobStore();
+        const out = [];
+        for (const { blob_key } of chunks) {
+            const blob = await store.get(blob_key);
+            if (blob === null)
+                throw new Error(`charge chunk ${blob_key} is recorded in charge_chunks but its blob is missing`);
+            for (const line of zstdDecompressSync(blob).toString('utf8').split('\n')) {
+                if (line === '')
+                    continue;
+                const stored = JSON.parse(line);
+                out.push(chargeOf(Object.fromEntries(FIELDS.map((field) => [field, stored[field] ?? null]))));
+            }
+        }
+        return out;
+    }
+}

package/dist/core/ledger/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './months.js';
+export { payerOf, type Payer, type PayerCall } from './payer.js';
+export { writeCharge, receiptChargeId, chargeOf, type WriteResult } from './charges.js';
+export { check, findRefusal, refusalError, refusedMark, userActionOf, type Candidate, type CallCandidate, type StartCandidate, type Refusal } from './check.js';
+export { upsertLimit, deleteLimit, listLimits } from './limits.js';
+export { usageFor, listCharges, monthTotals, assertReference, type Reader, type ChargePage, type ListFilter, type MonthTotals } from './read.js';
+export { REBUILD_ALL_TOTALS, rebuildTotalsFor } from './totals.js';
+export { appsHeldBy } from './account.js';

package/dist/core/ledger/index.js

@@ -0,0 +1,10 @@
+// The ledger core (design-ledger, cycle 4). Every site calls these.
+export * from './types.js';
+export * from './months.js';
+export { payerOf } from './payer.js';
+export { writeCharge, receiptChargeId, chargeOf } from './charges.js';
+export { check, findRefusal, refusalError, refusedMark, userActionOf } from './check.js';
+export { upsertLimit, deleteLimit, listLimits } from './limits.js';
+export { usageFor, listCharges, monthTotals, assertReference } from './read.js';
+export { REBUILD_ALL_TOTALS, rebuildTotalsFor } from './totals.js';
+export { appsHeldBy } from './account.js';

package/dist/core/ledger/infra-allowance.d.ts

@@ -0,0 +1,7 @@
+import { type WriteResult } from './charges.js';
+import type { ChargeInput } from './types.js';
+/** Write a `sandbox` or `storage` row whose `billed_usd` is the part of its usd above the account's monthly allowance. A row with no
+ *  billable account (house-paid, or no holder) bills 0 and takes no lock. */
+export declare function writeInfraCharge(input: ChargeInput & {
+    usd: number;
+}, billable: boolean): Promise<WriteResult>;

package/dist/core/ledger/infra-allowance.js

@@ -0,0 +1,31 @@
+// The monthly free allowance on infrastructure (design-fleet D56): the first `CRTR_LEDGER_INFRA_FREE_USD_PER_MONTH` (default $50) of a billing
+// account's sandbox and storage usd in a UTC month is free; `billed_usd` is the part of each row above it. Until the allowance is spent
+// every row bills 0, which keeps the directory's card stop (D68) off a person with no card.
+//
+// A row's billed part depends on the rows written before it, so the write transaction takes a lock per (account, month) and sums the
+// existing rows after taking it: two lane processes writing for one account queue, and the billed total comes out as
+// max(0, usd total - allowance) whichever order the rows land in.
+import { withCanvasWrite } from '../canvas/db.js';
+import { writeCharge } from './charges.js';
+import { usageMonth } from './months.js';
+import { infraFreeUsdPerMonth } from './rates.js';
+/** The usd precision of a stored charge (`numeric(14,6)`): amounts are rounded to it before the split so the parts add up exactly. */
+const round6 = (value) => Math.round(value * 1e6) / 1e6;
+/** Write a `sandbox` or `storage` row whose `billed_usd` is the part of its usd above the account's monthly allowance. A row with no
+ *  billable account (house-paid, or no holder) bills 0 and takes no lock. */
+export async function writeInfraCharge(input, billable) {
+    const usd = round6(input.usd);
+    const account = input.account ?? null;
+    if (!billable || account === null)
+        return await writeCharge({ ...input, usd, billedUsd: 0 });
+    const free = infraFreeUsdPerMonth();
+    const month = usageMonth(input.at ?? new Date());
+    return await withCanvasWrite(async (tx) => {
+        await tx.prepare('SELECT pg_advisory_xact_lock(hashtextextended(?, 0))').get(`infra:${account}:${month}`);
+        const prior = await tx.prepare(`SELECT COALESCE(sum(usd), 0) AS usd FROM charges WHERE account = ? AND month = ? AND kind IN ('sandbox', 'storage') AND id <> ?`)
+            .get(account, month, input.id ?? '');
+        const before = Number(prior.usd);
+        const billed = round6(Math.min(usd, Math.max(0, before + usd - free)));
+        return await writeCharge({ ...input, usd, billedUsd: billed });
+    });
+}

package/dist/core/ledger/limits.d.ts

@@ -0,0 +1,10 @@
+import type { Limit, LimitInput, LimitSource } from './types.js';
+/** Insert or replace one limit row by id. */
+export declare function upsertLimit(input: LimitInput): Promise<Limit>;
+/** Delete one limit row; true when it existed. */
+export declare function deleteLimit(id: string): Promise<boolean>;
+/** Limit rows, optionally of one source or one payer, in id order. */
+export declare function listLimits(filter?: {
+    source?: LimitSource;
+    payer?: string;
+}): Promise<Limit[]>;

package/dist/core/ledger/limits.js

@@ -0,0 +1,35 @@
+// The `limits` table: one row shape, three writers (`grant_sync` rows come from the `grants` trigger `crtr_grant_limit` of
+// schema delta 002; `person` and `operator` rows from here).
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+const COLUMNS = 'id, payer, account, funding, grantee, provider, sub, usd_per_month, source, updated_at';
+/** Insert or replace one limit row by id. */
+export async function upsertLimit(input) {
+    if (!Number.isFinite(input.usd_per_month) || input.usd_per_month < 0)
+        throw new RangeError('usd_per_month must be a number of at least 0');
+    const row = { account: null, funding: null, grantee: null, provider: null, sub: null, ...input, updated_at: new Date().toISOString() };
+    await withCanvasWrite(async (db) => {
+        await db.prepare(`INSERT INTO limits (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (id) DO UPDATE SET payer = excluded.payer, account = excluded.account, funding = excluded.funding, grantee = excluded.grantee,
+        provider = excluded.provider, sub = excluded.sub, usd_per_month = excluded.usd_per_month, source = excluded.source, updated_at = excluded.updated_at`)
+            .run(row.id, row.payer, row.account, row.funding, row.grantee, row.provider, row.sub, row.usd_per_month, row.source, row.updated_at);
+    });
+    return row;
+}
+/** Delete one limit row; true when it existed. */
+export async function deleteLimit(id) {
+    return await withCanvasWrite(async (db) => (await db.prepare('DELETE FROM limits WHERE id = ?').run(id)).changes > 0);
+}
+/** Limit rows, optionally of one source or one payer, in id order. */
+export async function listLimits(filter = {}) {
+    const where = [];
+    const params = [];
+    if (filter.source !== undefined) {
+        where.push('source = ?');
+        params.push(filter.source);
+    }
+    if (filter.payer !== undefined) {
+        where.push('payer = ?');
+        params.push(filter.payer);
+    }
+    return await (await openDb()).prepareUncached(`SELECT ${COLUMNS} FROM limits${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY id`).all(...params);
+}

package/dist/core/ledger/months.d.ts

@@ -0,0 +1,6 @@
+/** The UTC calendar month `YYYY-MM` of `at`. */
+export declare function usageMonth(at?: Date): string;
+/** 00:00Z on the first day of the UTC month after `month`. */
+export declare function resetAt(month: string): string;
+/** A `month` query value: `YYYY-MM` with a real month, years 1000-9999; absent means the current month. */
+export declare function parseUsageMonth(value: string | null): string;

package/dist/core/ledger/months.js

@@ -0,0 +1,19 @@
+// UTC month helpers for the ledger.
+import { RunError } from '../runs/operations.js';
+/** The UTC calendar month `YYYY-MM` of `at`. */
+export function usageMonth(at = new Date()) {
+    return at.toISOString().slice(0, 7);
+}
+/** 00:00Z on the first day of the UTC month after `month`. */
+export function resetAt(month) {
+    const [year, mon] = month.split('-').map(Number);
+    return new Date(Date.UTC(year, mon, 1)).toISOString();
+}
+/** A `month` query value: `YYYY-MM` with a real month, years 1000-9999; absent means the current month. */
+export function parseUsageMonth(value) {
+    if (value === null)
+        return usageMonth();
+    if (!/^[1-9]\d{3}-(0[1-9]|1[0-2])$/.test(value))
+        throw new RunError(400, 'invalid_request', 'month must be YYYY-MM', 'month');
+    return value;
+}

package/dist/core/ledger/payer.d.ts

@@ -0,0 +1,34 @@
+import type { Funding } from './types.js';
+export interface Payer {
+    payer: string;
+    funding: Funding;
+}
+export type PayerCall = 
+/** A model call on an app-paid grant: the app's inference endpoint pays. `grantee` is the app principal (`app:<id>`). */
+{
+    call: 'model';
+    route: 'endpoint';
+    grantee: string;
+}
+/** A model call on a managed subscription account from the pool, or on an API key (incl. a managed provider reached
+ *  through a key, which is `key`, never `subscription`). `sub` is the person the work is for. */
+ | {
+    call: 'model';
+    route: 'subscription' | 'key';
+    sub: string;
+}
+/** A tool call over HTTP: the outbound token's `payer` claim (`app:<id>` when the app pays, else the person). Both are `bill`: the app's holder is invoiced for an app-paid call. */
+ | {
+    call: 'tool';
+    tokenPayer: string;
+    sub: string;
+}
+/** The payer of a node's model calls, for the start check: `app:<grantee>` when the grant is app-paid, else the person. */
+ | {
+    call: 'start';
+    grantPayer: 'user' | 'app' | null | undefined;
+    sub: string;
+    grantee: string;
+};
+/** Who pays, and with what funding. A device call is not priced and never asks. */
+export declare function payerOf(call: PayerCall): Payer;

package/dist/core/ledger/payer.js

@@ -0,0 +1,14 @@
+// Payer resolution (design-ledger, "Payer resolution"): one function. It reads the grant's payer and the credential route,
+// never a request header, so a caller cannot name its payer.
+/** Who pays, and with what funding. A device call is not priced and never asks. */
+export function payerOf(call) {
+    switch (call.call) {
+        case 'model':
+            return call.route === 'endpoint' ? { payer: call.grantee, funding: 'endpoint' } : { payer: call.sub, funding: call.route };
+        case 'tool':
+            return call.tokenPayer.startsWith('app:') ? { payer: call.tokenPayer, funding: 'bill' } : { payer: call.sub, funding: 'bill' };
+        case 'start':
+            // Funding is chosen per candidate later; a start check ignores it.
+            return call.grantPayer === 'app' ? { payer: call.grantee, funding: 'endpoint' } : { payer: call.sub, funding: 'bill' };
+    }
+}

package/dist/core/ledger/read.d.ts

@@ -0,0 +1,57 @@
+import type { SpendUsageDTO } from '../../api/dto/usage.js';
+import type { Charge, Limit } from './types.js';
+/** `usage.get` for one grantee and month, computed from `charges`. `by_model` and `app_paid.by_model` group the `model` rows
+ *  of a `user:` / `app:` payer by `what`, with token sums from `units` and `usd_equivalent` null when every row's `usd` is null.
+ *  `usd_equivalent` is what the grant's limit reads: every `user:` payer charge for this grantee, model and tool, refused and
+ *  take rows excluded. `spend_cap` is the grant limit's `usd_per_month` for this grantee, null when none exists. With `sub` (a cloud
+ *  role, where one app serves many people) only that person's rows and that person's cap count; without it, every row of the grantee. */
+export declare function usageFor(grantee: string, month?: string, sub?: string): Promise<SpendUsageDTO>;
+/** Who is reading: a person sees the rows where they are `sub`, `payer` or `account`; an app the rows where it is `grantee`
+ *  or `payer`. Absent means the install's person, who sees every row. */
+/** `sub` on an app reader (a cloud role, where one app serves many people) keeps only that person's rows. */
+export type Reader = {
+    person: string;
+} | {
+    app: string;
+    sub?: string;
+};
+export interface ListFilter {
+    /** Only rows of this month. */
+    month?: string;
+    /** The reader; absent reads every row. */
+    reader?: Reader;
+    /** A reference: `message:<id>`, `request:<id>`, `cron_run:<id>`, `run:<id>`, or a charge id. */
+    under?: string;
+    /** Page size, 1 to 10,000; default 1,000. */
+    limit?: number;
+    /** The `next` of the previous page: continue after that page's last row. */
+    after?: string;
+}
+/** One page of rows in `(at, id)` order. `next` continues after the last row; null when this page is the last. */
+export interface ChargePage {
+    charges: Charge[];
+    next: string | null;
+}
+/** A page of rows in `(at, id)` order, newest last: the rows under a reference when `under` is set (every month unless `month`
+ *  is given), otherwise the month's rows (default the current month). */
+export declare function listCharges(filter?: ListFilter): Promise<ChargePage>;
+export interface MonthTotals {
+    month: string;
+    by_payer: Array<{
+        payer: string;
+        usd: number;
+    }>;
+    by_funding: Array<{
+        payer: string;
+        funding: string;
+        usd: number;
+    }>;
+    limits: Limit[];
+}
+/** The payers a `user:<id>` answers for: itself, and every app held (`ledger_holder`) by it or by a team it belongs to. */
+export declare function payersOf(owner: string): Promise<string[]>;
+/** One month's dollars per payer and per payer and funding, from the rollup, with the limit rows. For one person: the rows of the
+ *  person's `payersOf` (itself and the apps it or its teams hold now), and the limits on those payers or on the person's account. */
+export declare function monthTotals(month?: string, person?: string): Promise<MonthTotals>;
+/** A reference's shape, or a 400. */
+export declare function assertReference(value: string): string;

package/dist/core/ledger/read.js

@@ -0,0 +1,194 @@
+// Read side of the ledger: `usage.get`'s computation, charge pages (a month, or the rows under a reference), month listings and totals.
+// Everything here reads this runtime only.
+import { openDb } from '../canvas/db.js';
+import { subjectSet } from '../permissions/evaluator.js';
+import { RunError } from '../runs/operations.js';
+import { appsHeldBy } from './account.js';
+import { chargeOf } from './charges.js';
+import { ChunkRows } from './chunks.js';
+import { listLimits } from './limits.js';
+import { resetAt, usageMonth } from './months.js';
+const CHARGE_COLUMNS = 'id, request, at, month, kind, what, units, usd, payer, funding, sub, grantee, node, run, provider, caused_by, vendor_ref, refused, account, billed_usd';
+/** `usage.get` for one grantee and month, computed from `charges`. `by_model` and `app_paid.by_model` group the `model` rows
+ *  of a `user:` / `app:` payer by `what`, with token sums from `units` and `usd_equivalent` null when every row's `usd` is null.
+ *  `usd_equivalent` is what the grant's limit reads: every `user:` payer charge for this grantee, model and tool, refused and
+ *  take rows excluded. `spend_cap` is the grant limit's `usd_per_month` for this grantee, null when none exists. With `sub` (a cloud
+ *  role, where one app serves many people) only that person's rows and that person's cap count; without it, every row of the grantee. */
+export async function usageFor(grantee, month = usageMonth(), sub) {
+    const db = await openDb();
+    const rows = await db.prepare(`SELECT payer, what, kind, units, usd FROM charges
+    WHERE grantee = ? AND month = ? AND refused IS NULL AND kind <> 'take'${sub === undefined ? '' : ' AND sub = ?'}`).all(...(sub === undefined ? [grantee, month] : [grantee, month, sub]));
+    // The month's rows `ledger-r2` moved into a blob count the same.
+    for (const row of await new ChunkRows().rows(month))
+        if (row.grantee === grantee && (sub === undefined || row.sub === sub) && row.refused === null && row.kind !== 'take')
+            rows.push(row);
+    const byModel = (prefix) => {
+        const grouped = new Map();
+        for (const row of rows) {
+            if (row.kind !== 'model' || !row.payer.startsWith(prefix))
+                continue;
+            const units = (row.units === null ? {} : typeof row.units === 'string' ? JSON.parse(row.units) : row.units);
+            const entry = grouped.get(row.what) ?? { served_model: row.what, input_tokens: 0, output_tokens: 0, usd_equivalent: null };
+            entry.input_tokens += units.input ?? 0;
+            entry.output_tokens += units.output ?? 0;
+            if (row.usd !== null)
+                entry.usd_equivalent = (entry.usd_equivalent ?? 0) + Number(row.usd);
+            grouped.set(row.what, entry);
+        }
+        return [...grouped.values()].sort((a, b) => a.served_model < b.served_model ? -1 : 1);
+    };
+    const sum = (prefix) => rows.filter((row) => row.payer.startsWith(prefix)).reduce((total, row) => total + Number(row.usd ?? 0), 0);
+    const cap = await db.prepare(`SELECT usd_per_month FROM limits WHERE source = 'grant_sync' AND grantee = ? AND payer LIKE 'user:%' AND funding IS NULL AND provider IS NULL${sub === undefined ? '' : ' AND payer = ?'} ORDER BY id LIMIT 1`)
+        .get(...(sub === undefined ? [grantee] : [grantee, sub]));
+    return {
+        grantee, month, usd_equivalent: sum('user:'), by_model: byModel('user:'),
+        app_paid: { usd_equivalent: sum('app:'), by_model: byModel('app:') },
+        spend_cap: cap === undefined ? null : Number(cap.usd_per_month), reset_at: resetAt(month),
+    };
+}
+const REFERENCE = /^(message|request|cron_run|run):(.+)$/;
+async function referenceMatch(reference, chunks) {
+    const match = REFERENCE.exec(reference);
+    if (match === null)
+        return { sql: 'id = ?', params: [reference], test: (row) => row.id === reference };
+    if (match[1] === 'message' || match[1] === 'cron_run')
+        return { sql: 'caused_by = ?', params: [reference], test: (row) => row.caused_by === reference };
+    if (match[1] === 'request')
+        return { sql: '(request = ? OR caused_by = ?)', params: [match[2], reference], test: (row) => row.request === match[2] || row.caused_by === reference };
+    const run = match[2];
+    const db = await openDb();
+    const requests = new Set((await db.prepare('SELECT DISTINCT request FROM charges WHERE run = ? AND request IS NOT NULL').all(run)).map((row) => row.request));
+    for (const row of await chunks.rows())
+        if (row.run === run && row.request !== null)
+            requests.add(row.request);
+    const runs = new Set([run]);
+    if (requests.size > 0) {
+        const roots = await db.prepare('SELECT n.run_id FROM nodes n WHERE n.run_id IS NOT NULL AND n.node_id = n.run_id AND n.caused_by = ANY(?::text[])')
+            .all([...requests].map((request) => `request:${request}`));
+        for (const root of roots)
+            runs.add(root.run_id);
+    }
+    return { sql: 'run = ANY(?::text[])', params: [[...runs]], test: (row) => row.run !== null && runs.has(row.run) };
+}
+function readerCondition(reader) {
+    return 'person' in reader
+        ? { sql: '(sub = ? OR payer = ? OR account = ?)', params: [reader.person, reader.person, reader.person] }
+        : reader.sub === undefined ? { sql: '(grantee = ? OR payer = ?)', params: [reader.app, reader.app] }
+            : { sql: '((grantee = ? OR payer = ?) AND sub = ?)', params: [reader.app, reader.app, reader.sub] };
+}
+const mayRead = (row, reader) => 'person' in reader
+    ? row.sub === reader.person || row.payer === reader.person || row.account === reader.person
+    : (row.grantee === reader.app || row.payer === reader.app) && (reader.sub === undefined || row.sub === reader.sub);
+/** The rows the reader may see in a chain. A row the reader may not see is replaced by its parent's row: the rows whose
+ *  `request` is the id in its `caused_by` (the tool call that made this one), then that row's parent if the reader cannot
+ *  see it either. A hop with no visible ancestor is dropped. Order and uniqueness are kept. */
+async function visibleChain(rows, reader, chunks) {
+    const db = await openDb();
+    const out = new Map();
+    const parentOf = async (row) => {
+        const cause = row.caused_by;
+        if (cause === null || !cause.startsWith('request:'))
+            return undefined;
+        const request = cause.slice('request:'.length);
+        const parents = [...(await db.prepare(`SELECT ${CHARGE_COLUMNS} FROM charges WHERE request = ? AND id <> ?`).all(request, row.id)).map(chargeOf),
+            ...(await chunks.rows()).filter((moved) => moved.request === request && moved.id !== row.id)].sort(byAtId);
+        return parents.find((parent) => mayRead(parent, reader)) ?? parents[0];
+    };
+    for (const row of rows) {
+        let shown = row;
+        for (let hops = 0; shown !== undefined && !mayRead(shown, reader) && hops < 64; hops += 1)
+            shown = await parentOf(shown);
+        if (shown !== undefined && mayRead(shown, reader))
+            out.set(shown.id, shown);
+    }
+    return [...out.values()];
+}
+const byAtId = (a, b) => a.at < b.at ? -1 : a.at > b.at ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+const encodeCursor = (row) => Buffer.from(JSON.stringify([row.at, row.id]), 'utf8').toString('base64url');
+function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (Array.isArray(value) && value.length === 2 && typeof value[0] === 'string' && typeof value[1] === 'string')
+            return [value[0], value[1]];
+    }
+    catch { /* fall through to the 400 */ }
+    throw new RunError(400, 'invalid_request', 'cursor must be a `next` value from a previous page', 'after');
+}
+/** A page of rows in `(at, id)` order, newest last: the rows under a reference when `under` is set (every month unless `month`
+ *  is given), otherwise the month's rows (default the current month). */
+export async function listCharges(filter = {}) {
+    const limit = Math.min(Math.max(Math.trunc(filter.limit ?? 1000), 1), 10_000);
+    const chunks = new ChunkRows();
+    const conditions = [];
+    const params = [];
+    const tests = [];
+    let chunkMonth;
+    if (filter.under !== undefined) {
+        const reference = await referenceMatch(filter.under, chunks);
+        conditions.push(reference.sql);
+        params.push(...reference.params);
+        tests.push(reference.test);
+        if (filter.month !== undefined) {
+            conditions.push('month = ?');
+            params.push(filter.month);
+            tests.push((row) => row.month === filter.month);
+            chunkMonth = filter.month;
+        }
+    }
+    else {
+        const month = filter.month ?? usageMonth();
+        conditions.push('month = ?');
+        params.push(month);
+        chunkMonth = month;
+    }
+    // Under a reference the whole tree is read and each hidden row replaced below; a month list is filtered in the query.
+    if (filter.under === undefined && filter.reader !== undefined) {
+        const visible = readerCondition(filter.reader);
+        conditions.push(visible.sql);
+        params.push(...visible.params);
+        const reader = filter.reader;
+        tests.push((row) => mayRead(row, reader));
+    }
+    if (filter.after !== undefined) {
+        const [at, id] = decodeCursor(filter.after);
+        conditions.push('(at, id) > (?, ?)');
+        params.push(at, id);
+        tests.push((row) => row.at > at || (row.at === at && row.id > id));
+    }
+    const live = (await (await openDb()).prepare(`SELECT ${CHARGE_COLUMNS} FROM charges WHERE ${conditions.join(' AND ')} ORDER BY at, id LIMIT ${limit + 1}`)
+        .all(...params)).map(chargeOf);
+    // The rows `ledger-r2` moved into blobs join the live rows, filtered by the same tests.
+    const moved = (await chunks.rows(chunkMonth)).filter((row) => tests.every((test) => test(row)));
+    const rows = [...live, ...moved].sort(byAtId).slice(0, limit + 1);
+    const page = rows.slice(0, limit);
+    const charges = filter.under !== undefined && filter.reader !== undefined ? await visibleChain(page, filter.reader, chunks) : page;
+    return { charges, next: rows.length > limit ? encodeCursor(page[limit - 1]) : null };
+}
+/** The payers a `user:<id>` answers for: itself, and every app held (`ledger_holder`) by it or by a team it belongs to. */
+export async function payersOf(owner) {
+    const db = await openDb();
+    const { groupIds } = await subjectSet(db, owner.slice('user:'.length));
+    return [owner, ...await appsHeldBy(db, [owner, ...groupIds])];
+}
+/** One month's dollars per payer and per payer and funding, from the rollup, with the limit rows. For one person: the rows of the
+ *  person's `payersOf` (itself and the apps it or its teams hold now), and the limits on those payers or on the person's account. */
+export async function monthTotals(month = usageMonth(), person) {
+    const db = await openDb();
+    const payers = person === undefined ? undefined : await payersOf(person);
+    const where = payers === undefined ? '' : ' AND payer = ANY(?::text[])';
+    const params = payers === undefined ? [month] : [month, payers];
+    const byPayer = await db.prepare(`SELECT payer, SUM(usd) AS usd FROM charge_totals WHERE month = ?${where} GROUP BY payer ORDER BY payer`).all(...params);
+    const byFunding = await db.prepare(`SELECT payer, funding, SUM(usd) AS usd FROM charge_totals WHERE month = ?${where} GROUP BY payer, funding ORDER BY payer, funding`).all(...params);
+    const limits = payers === undefined ? await listLimits() : (await listLimits()).filter((limit) => (limit.payer !== null && payers.includes(limit.payer)) || limit.account === person);
+    return {
+        month, by_payer: byPayer.map((row) => ({ payer: row.payer, usd: Number(row.usd) })),
+        by_funding: byFunding.map((row) => ({ payer: row.payer, funding: row.funding, usd: Number(row.usd) })),
+        limits,
+    };
+}
+/** A reference's shape, or a 400. */
+export function assertReference(value) {
+    if (value.length === 0 || value.length > 512)
+        throw new RunError(400, 'invalid_request', 'under must be a reference or a charge id', 'under');
+    return value;
+}

package/dist/core/ledger/totals.d.ts

@@ -0,0 +1,10 @@
+import type { CanvasDb } from '../canvas/db.js';
+/** Rebuild the whole rollup from `charges`, `billed_usd` with `usd`: a rebuild that dropped it would zero the billed totals
+ *  002's trigger keeps, and an older build that may still open the database must not do that either. Plain SQL, so the SQLite
+ *  import runs it on its own client. */
+export declare const REBUILD_ALL_TOTALS: readonly ["DELETE FROM charge_totals", "INSERT INTO charge_totals (month, payer, funding, sub, grantee, provider, usd, billed_usd) SELECT month, payer, funding, COALESCE(sub, ''), grantee, COALESCE(provider, ''), COALESCE(SUM(usd), 0), COALESCE(SUM(billed_usd), 0)\n  FROM charges WHERE refused IS NULL AND kind <> 'take' GROUP BY month, payer, funding, COALESCE(sub, ''), grantee, COALESCE(provider, '')"];
+/** Rename person `from` to `to` in the rollup rows that name it as payer, sub or grantee, summing rows that now share a key.
+ *  For person substitution, in the same transaction as the rename of `charges`. The rollup already holds every charge, so renaming
+ *  keeps the months `ledger-r2` moved out of `charges` (a rebuild from `charges` would drop them), and the sums stay exactly what a
+ *  rebuild of the rows still in `charges` plus the moved months would give. Returns the rollup rows renamed. */
+export declare function rebuildTotalsFor(db: CanvasDb, from: string, to: string): Promise<number>;

package/dist/core/ledger/totals.js

@@ -0,0 +1,34 @@
+// The `charge_totals` rollup: how a charge adds to it, and how it is rebuilt from `charges`.
+// Refused rows and take rows are never in it.
+import { CrtrError } from '../errors.js';
+const REBUILD_SELECT = `SELECT month, payer, funding, COALESCE(sub, ''), grantee, COALESCE(provider, ''), COALESCE(SUM(usd), 0), COALESCE(SUM(billed_usd), 0)
+  FROM charges WHERE refused IS NULL AND kind <> 'take'`;
+const REBUILD_GROUP = 'GROUP BY month, payer, funding, COALESCE(sub, \'\'), grantee, COALESCE(provider, \'\')';
+/** Rebuild the whole rollup from `charges`, `billed_usd` with `usd`: a rebuild that dropped it would zero the billed totals
+ *  002's trigger keeps, and an older build that may still open the database must not do that either. Plain SQL, so the SQLite
+ *  import runs it on its own client. */
+export const REBUILD_ALL_TOTALS = ['DELETE FROM charge_totals',
+    `INSERT INTO charge_totals (month, payer, funding, sub, grantee, provider, usd, billed_usd) ${REBUILD_SELECT} ${REBUILD_GROUP}`];
+/** Rename person `from` to `to` in the rollup rows that name it as payer, sub or grantee, summing rows that now share a key.
+ *  For person substitution, in the same transaction as the rename of `charges`. The rollup already holds every charge, so renaming
+ *  keeps the months `ledger-r2` moved out of `charges` (a rebuild from `charges` would drop them), and the sums stay exactly what a
+ *  rebuild of the rows still in `charges` plus the moved months would give. Returns the rollup rows renamed. */
+export async function rebuildTotalsFor(db, from, to) {
+    // A `charge_chunks` row holds one blob key per (month, payer), so two people with a moved month in common cannot be merged without
+    // rewriting a blob; refuse before anything changes.
+    const clash = await db.prepare('SELECT a.month FROM charge_chunks a JOIN charge_chunks b ON b.month = a.month AND b.payer = ? WHERE a.payer = ? ORDER BY a.month LIMIT 1').get(to, from);
+    if (clash !== undefined) {
+        throw new CrtrError('person_conflict', `${from} and ${to} both have the moved month ${clash.month} (charge_chunks holds one blob per month and payer), so they cannot be merged`, undefined, { from, to, month: clash.month });
+    }
+    const rows = await db.prepare(`DELETE FROM charge_totals WHERE payer = ? OR sub = ? OR grantee = ?
+    RETURNING month, payer, funding, sub, grantee, provider, usd, billed_usd`).all(from, from, from);
+    const rename = (value) => value === from ? to : value;
+    for (const row of rows) {
+        await db.prepare(`INSERT INTO charge_totals (month, payer, funding, sub, grantee, provider, usd, billed_usd) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (month, payer, funding, sub, grantee, provider) DO UPDATE SET usd = charge_totals.usd + EXCLUDED.usd, billed_usd = charge_totals.billed_usd + EXCLUDED.billed_usd`)
+            .run(row.month, rename(row.payer), row.funding, rename(row.sub), rename(row.grantee), row.provider, row.usd, row.billed_usd);
+    }
+    // A moved month's chunk row names its payer too. Its blob key stays as written: readers follow the stored key.
+    const chunks = await db.prepare('UPDATE charge_chunks SET payer = ? WHERE payer = ?').run(to, from);
+    return rows.length + chunks.changes;
+}