@north-light/api 0.3.580 → 0.3.587

package/dist/core/subscription-state.js

@@ -0,0 +1,438 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { brokerConfigSnapshot } from './config.js';
+import { openDb, withCanvasWrite } from './canvas/db.js';
+import { personIdAsync } from './canvas/person.js';
+import { loadSecretsKey, open, seal } from './secrets/index.js';
+import { modelCooldownFamily } from './rate-limit-scope.js';
+import { REFRESH_BUSY_PHRASE, REFRESH_TIMEOUT_PHRASE } from './provider-error-recognition.js';
+import { registerRotationReader } from './model-routes.js';
+import { coolingUntilFor, getProviderLabel, isInvalidRefreshTokenError, DuplicateSubscriptionError, ANTHROPIC_PROVIDER_ID, MAX_RATE_LIMIT_COOLDOWN_MS, INVALID_REFRESH_TOKEN_BACKOFF_MS } from './managed-providers.js';
+export * from './managed-providers.js';
+const DEFAULT_FALLBACK_STRENGTH = 'strong';
+function normalizeStrength(value) { return value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light' ? value : undefined; }
+function key(label) { return label.toLowerCase(); }
+function optionalString(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function credential(input) { const label = typeof input.label === 'string' ? input.label.trim() : ''; const refresh = typeof input.refresh === 'string' ? input.refresh.trim() : ''; const access = typeof input.access === 'string' ? input.access.trim() : ''; const expires = Number(input.expires); if (!label || !refresh || !access || !Number.isFinite(expires))
+    return undefined; const accountId = optionalString(input.accountId); const clientId = optionalString(input.clientId); return { label, refresh, access, expires, rateLimitedUntil: Number.isFinite(Number(input.rateLimitedUntil)) ? Number(input.rateLimitedUntil) : 0, lastAttemptAt: Number.isFinite(Number(input.lastAttemptAt)) ? Number(input.lastAttemptAt) : 0, lastRateLimitedAt: Number.isFinite(Number(input.lastRateLimitedAt)) ? Number(input.lastRateLimitedAt) : 0, ...(input.authFailure === 'invalid_grant' ? { authFailure: 'invalid_grant' } : {}), ...(accountId ? { accountId } : {}), ...(clientId ? { clientId } : {}), ...(modelCooldowns(input.modelCooldowns) ? { modelCooldowns: modelCooldowns(input.modelCooldowns) } : {}) }; }
+function modelCooldowns(value) { if (!value || typeof value !== 'object' || Array.isArray(value))
+    return undefined; const entries = Object.entries(value).filter(([family, until]) => family.trim() !== '' && Number.isFinite(Number(until))).map(([family, until]) => [family, Number(until)]); return entries.length ? Object.fromEntries(entries) : undefined; }
+function assertCredential(provider, entry) { if (!entry.label?.trim())
+    throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`); const result = credential(entry); if (!result)
+    throw new Error(`Refusing to persist incomplete ${getProviderLabel(provider)} subscription "${entry.label.trim()}"; pool rows require both OAuth tokens.`); return result; }
+/** A slot re-signed into a provably different account (both account ids known and unequal): its model-family cooldowns were the old account's server quota windows, not this one's. Unknown or matching ids keep them. */
+function differentAccount(previous, next) { const a = previous.accountId?.trim(); const b = next.accountId?.trim(); return Boolean(a && b && a !== b); }
+function identity(entry) { return entry.accountId?.trim() || (entry.refresh.trim() ? `refresh:${createHash('sha256').update(entry.refresh.trim()).digest('hex')}` : undefined); }
+function withClientId(tokens, clientId) { const id = optionalString(clientId); return id ? { ...tokens, clientId: id } : tokens; }
+function assertTokens(provider, label, value) { const refresh = value.refresh?.trim() ?? ''; const access = value.access?.trim() ?? ''; const expires = Number(value.expires); if (!refresh || !access || !Number.isFinite(expires))
+    throw new Error(`${getProviderLabel(provider)} subscription "${label}" returned an incomplete credential; the stored credential was left unchanged.`); return { refresh, access, expires }; }
+/** Longest a refresh exchange may hold the account's row lock. */
+export const REFRESH_EXCHANGE_TIMEOUT_MS = 10_000;
+/** Longest a statement waits for another process's row or provider lock before the call gives up. */
+const LOCK_TIMEOUT = '15s';
+const LOCK_NOT_AVAILABLE = '55P03';
+/** Another process held this account's row lock for the whole lock timeout (a slow refresh exchange): the account is cooling for this call, not failed. */
+export class RefreshBusyError extends Error {
+    constructor(provider, label) { super(`${getProviderLabel(provider)} subscription "${label}" ${REFRESH_BUSY_PHRASE}; treating it as cooling for this call`); this.name = 'RefreshBusyError'; }
+}
+/** The vendor did not answer a refresh exchange within `REFRESH_EXCHANGE_TIMEOUT_MS`. */
+export class RefreshTimeoutError extends Error {
+    constructor(provider) { super(`${getProviderLabel(provider)} ${REFRESH_TIMEOUT_PHRASE} ${REFRESH_EXCHANGE_TIMEOUT_MS} ms`); this.name = 'RefreshTimeoutError'; }
+}
+const COLUMNS = 'id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure,refresh_sealed,access_sealed,expires,vendor_account_id,client_id,key_id';
+export const aadOf = (person, provider, id, part) => `model_accounts|${person}|${provider}|${id}|${part}`;
+function stored(entry) { return { refresh: entry.refresh, access: entry.access, expires: entry.expires, ...(entry.accountId ? { accountId: entry.accountId } : {}), ...(entry.clientId ? { clientId: entry.clientId } : {}) }; }
+function rowOf(provider, r) { return { providerId: provider, id: r.id, label: r.label, labelKey: r.label_key, position: r.position, lastAttemptAt: r.last_attempt_at, lastRateLimitedAt: r.last_rate_limited_at, rateLimitedUntil: r.rate_limited_until, ...(r.auth_failure ? { authFailure: r.auth_failure } : {}) }; }
+function toPublic(person, provider, r, cooldowns = []) {
+    if (!r.refresh_sealed || !r.access_sealed || r.expires === null || !r.key_id)
+        throw new Error(`managed ${provider} account ${r.id} has no credential record`);
+    const secrets = loadSecretsKey();
+    const refresh = open(r.refresh_sealed, r.key_id, secrets, aadOf(person, provider, r.id, 'refresh'));
+    const access = open(r.access_sealed, r.key_id, secrets, aadOf(person, provider, r.id, 'access'));
+    const row = rowOf(provider, r);
+    const entry = { label: row.label, refresh, access, expires: r.expires, rateLimitedUntil: row.authFailure || !row.lastRateLimitedAt ? row.rateLimitedUntil : Math.min(row.rateLimitedUntil, row.lastRateLimitedAt + MAX_RATE_LIMIT_COOLDOWN_MS), lastAttemptAt: row.lastAttemptAt, lastRateLimitedAt: row.lastRateLimitedAt, ...(row.authFailure ? { authFailure: row.authFailure } : {}), ...(r.vendor_account_id ? { accountId: r.vendor_account_id } : {}), ...(r.client_id ? { clientId: r.client_id } : {}), ...(cooldowns.length ? { modelCooldowns: Object.fromEntries(cooldowns.map((cooldown) => [cooldown.family, cooldown.lastRateLimitedAt ? Math.min(cooldown.rateLimitedUntil, cooldown.lastRateLimitedAt + MAX_RATE_LIMIT_COOLDOWN_MS) : cooldown.rateLimitedUntil])) } : {}) };
+    return { row, entry };
+}
+async function loadCooldowns(db, person, provider) {
+    const out = new Map();
+    const rows = await db.prepare('SELECT account_id,family,rate_limited_until,last_rate_limited_at FROM model_account_cooldowns WHERE person=? AND provider_id=? ORDER BY family').all(person, provider);
+    for (const r of rows) {
+        const list = out.get(r.account_id) ?? [];
+        list.push({ family: r.family, rateLimitedUntil: r.rate_limited_until, lastRateLimitedAt: r.last_rate_limited_at });
+        out.set(r.account_id, list);
+    }
+    return out;
+}
+/** The person's accounts at one provider in pool order, tokens opened. `forUpdate` row-locks them. */
+async function loadPool(db, person, provider, forUpdate = false) {
+    const rows = await db.prepare(`SELECT ${COLUMNS} FROM model_accounts WHERE person=? AND provider_id=? ORDER BY position${forUpdate ? ' FOR UPDATE' : ''}`).all(person, provider);
+    const cooldowns = await loadCooldowns(db, person, provider);
+    return rows.map((r) => toPublic(person, provider, r, cooldowns.get(r.id)));
+}
+/** One account by 1-based position or label, row-locked. */
+async function lockedAccount(db, person, provider, ref) {
+    const needle = ref.trim().toLowerCase();
+    const position = Number.parseInt(needle, 10);
+    const byPosition = Number.isFinite(position) && String(position) === needle && position >= 1;
+    const r = await db.prepare(`SELECT ${COLUMNS} FROM model_accounts WHERE person=? AND provider_id=? AND ${byPosition ? 'position=?' : 'label_key=?'} FOR UPDATE`).get(person, provider, byPosition ? position - 1 : needle);
+    if (!r)
+        return undefined;
+    return toPublic(person, provider, r, (await loadCooldowns(db, person, provider)).get(r.id));
+}
+async function setLockTimeout(db) { await db.exec(`SET LOCAL lock_timeout = '${LOCK_TIMEOUT}'`); }
+/** Run one pool mutation in a transaction holding the provider's advisory lock and a row lock on every account, so no two processes mutate one pool at once. */
+async function locked(provider, run) {
+    const person = await personIdAsync();
+    return withCanvasWrite(async (db) => {
+        await setLockTimeout(db);
+        await db.prepare('SELECT pg_advisory_xact_lock(hashtext(?))').get(`model_accounts|${person}|${provider}`);
+        return run({ db, person, rows: await loadPool(db, person, provider, true) });
+    });
+}
+export async function insertAccount(db, person, provider, row, entry) {
+    const secrets = loadSecretsKey();
+    const refresh = seal(entry.refresh, secrets, aadOf(person, provider, row.id, 'refresh'));
+    const access = seal(entry.access, secrets, aadOf(person, provider, row.id, 'access'));
+    await db.prepare('INSERT INTO model_accounts(person,provider_id,id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure,refresh_sealed,access_sealed,expires,vendor_account_id,client_id,key_id) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)')
+        .run(person, provider, row.id, row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null, refresh.sealed, access.sealed, entry.expires, entry.accountId ?? null, entry.clientId ?? null, refresh.keyId);
+}
+/** Replace the account's whole token record (account id and client id included). */
+async function setCredential(db, person, provider, id, entry) {
+    const secrets = loadSecretsKey();
+    const refresh = seal(entry.refresh, secrets, aadOf(person, provider, id, 'refresh'));
+    const access = seal(entry.access, secrets, aadOf(person, provider, id, 'access'));
+    await db.prepare('UPDATE model_accounts SET refresh_sealed=?,access_sealed=?,expires=?,vendor_account_id=?,client_id=?,key_id=? WHERE person=? AND provider_id=? AND id=?').run(refresh.sealed, access.sealed, entry.expires, entry.accountId ?? null, entry.clientId ?? null, refresh.keyId, person, provider, id);
+}
+async function updateHealth(db, person, row) { await db.prepare('UPDATE model_accounts SET label=?,label_key=?,position=?,last_attempt_at=?,last_rate_limited_at=?,rate_limited_until=?,auth_failure=? WHERE person=? AND provider_id=? AND id=?').run(row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null, person, row.providerId, row.id); }
+export async function upsertModelCooldown(db, person, provider, accountId, family, until, rateLimitedAt) { await db.prepare('INSERT INTO model_account_cooldowns(person,provider_id,account_id,family,rate_limited_until,last_rate_limited_at) VALUES(?,?,?,?,?,?) ON CONFLICT(person,provider_id,account_id,family) DO UPDATE SET rate_limited_until=excluded.rate_limited_until,last_rate_limited_at=excluded.last_rate_limited_at').run(person, provider, accountId, family, until, rateLimitedAt); }
+async function deleteModelCooldowns(db, person, provider, accountId) { if (accountId === undefined)
+    await db.prepare('DELETE FROM model_account_cooldowns WHERE person=? AND provider_id=?').run(person, provider);
+else
+    await db.prepare('DELETE FROM model_account_cooldowns WHERE person=? AND provider_id=? AND account_id=?').run(person, provider, accountId); }
+const publicPool = async ({ db, person }, provider) => (await loadPool(db, person, provider)).map(({ entry }) => entry);
+const lockWaitExpired = (error) => error?.code === LOCK_NOT_AVAILABLE;
+/** Stop waiting on a network exchange made while holding a row lock. */
+function withExchangeTimeout(provider, run) { let timer; return Promise.race([run, new Promise((_, reject) => { timer = setTimeout(() => reject(new RefreshTimeoutError(provider)), REFRESH_EXCHANGE_TIMEOUT_MS); })]).finally(() => clearTimeout(timer)); }
+export async function readSubscriptionPool(provider) { return (await readSubscriptionPoolRows(provider)).map(({ entry }) => entry); }
+/** The pool with each account's row id: the stable handle a caller outside the process removes an account by. */
+export async function readSubscriptionPoolRows(provider) { const person = await personIdAsync(); return (await loadPool(await openDb(), person, provider)).map(({ row, entry }) => ({ id: row.id, entry })); }
+export async function writeSubscriptionPool(provider, next) {
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const normalized = next.map((entry) => assertCredential(provider, entry));
+        const ids = normalized.map((entry, index) => ({ entry, id: rows[index]?.row.id ?? randomUUID() }));
+        const priorFamilies = await loadCooldowns(db, person, provider);
+        await db.prepare('DELETE FROM model_accounts WHERE person=? AND provider_id=?').run(person, provider);
+        await deleteModelCooldowns(db, person, provider);
+        for (const [position, { entry, id }] of ids.entries()) {
+            await insertAccount(db, person, provider, { providerId: provider, id, label: entry.label, labelKey: key(entry.label), position, lastAttemptAt: entry.lastAttemptAt, lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil, ...(entry.authFailure ? { authFailure: entry.authFailure } : {}) }, stored(entry));
+            for (const [family, until] of Object.entries(entry.modelCooldowns ?? {}))
+                await upsertModelCooldown(db, person, provider, id, family, until, priorFamilies.get(id)?.find((prior) => prior.family === family)?.lastRateLimitedAt ?? entry.lastRateLimitedAt);
+        }
+        return normalized;
+    });
+}
+function resolve(rows, ref) { const needle = ref.trim().toLowerCase(); const number = Number.parseInt(needle, 10); if (Number.isFinite(number) && String(number) === needle && number >= 1 && number <= rows.length)
+    return number - 1; return rows.findIndex(({ entry }) => key(entry.label) === needle); }
+const duplicateAccount = (provider, label) => new DuplicateSubscriptionError(`This ${getProviderLabel(provider)} account is already added as “${label}” — it shares the same quota, so a second slot adds no redundancy.`);
+export async function addSubscription(provider, entry) {
+    const checked = assertCredential(provider, entry);
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        if (rows.some(({ entry: existing }) => key(existing.label) === key(checked.label)))
+            throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${checked.label}`);
+        const same = identity(checked);
+        const collision = rows.find(({ entry: existing }) => identity(existing) === same);
+        if (same && collision)
+            throw duplicateAccount(provider, collision.entry.label);
+        await insertAccount(db, person, provider, { providerId: provider, id: randomUUID(), label: checked.label, labelKey: key(checked.label), position: rows.length, lastAttemptAt: checked.lastAttemptAt, lastRateLimitedAt: checked.lastRateLimitedAt, rateLimitedUntil: checked.rateLimitedUntil, ...(checked.authFailure ? { authFailure: checked.authFailure } : {}) }, stored(checked));
+        return publicPool(pool, provider);
+    });
+}
+export async function upsertSubscription(provider, entry) { const checked = assertCredential(provider, entry); const existing = (await readSubscriptionPool(provider)).find((x) => key(x.label) === key(checked.label)); return existing ? upsertSubscriptionWithUniqueAccount(provider, checked) : addSubscription(provider, checked); }
+export async function upsertSubscriptionWithUniqueAccount(provider, entry) {
+    const checked = assertCredential(provider, entry);
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const index = rows.findIndex(({ entry: existing }) => key(existing.label) === key(checked.label));
+        const existing = rows[index];
+        const duplicate = rows.find(({ entry: other }, i) => i !== index && identity(other) === identity(checked));
+        if (identity(checked) && duplicate)
+            throw duplicateAccount(provider, duplicate.entry.label);
+        if (!existing) {
+            await insertAccount(db, person, provider, { providerId: provider, id: randomUUID(), label: checked.label, labelKey: key(checked.label), position: rows.length, lastAttemptAt: checked.lastAttemptAt, lastRateLimitedAt: checked.lastRateLimitedAt, rateLimitedUntil: checked.rateLimitedUntil }, stored(checked));
+            return publicPool(pool, provider);
+        }
+        const row = existing.row;
+        const cooldownIncoming = checked.lastRateLimitedAt >= row.lastRateLimitedAt;
+        await setCredential(db, person, provider, row.id, stored(checked));
+        await updateHealth(db, person, { ...row, authFailure: undefined, label: checked.label, labelKey: key(checked.label), lastAttemptAt: Math.max(row.lastAttemptAt, checked.lastAttemptAt), lastRateLimitedAt: cooldownIncoming ? checked.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: cooldownIncoming ? checked.rateLimitedUntil : row.rateLimitedUntil });
+        if (differentAccount(existing.entry, checked))
+            await deleteModelCooldowns(db, person, provider, row.id);
+        return publicPool(pool, provider);
+    });
+}
+export async function renameSubscription(provider, ref, nextLabel) {
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const index = resolve(rows, ref);
+        if (index < 0)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`);
+        const label = nextLabel.trim();
+        if (!label)
+            throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`);
+        if (rows.some((value, i) => i !== index && key(value.entry.label) === key(label)))
+            throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${label}`);
+        await updateHealth(db, person, { ...rows[index].row, label, labelKey: key(label) });
+        return publicPool(pool, provider);
+    });
+}
+async function remove(provider, find, missing) {
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const index = find(rows);
+        if (index < 0)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${missing}`);
+        const removed = rows[index].row;
+        await db.prepare('DELETE FROM model_accounts WHERE person=? AND provider_id=? AND id=?').run(person, provider, removed.id);
+        await deleteModelCooldowns(db, person, provider, removed.id);
+        return publicPool(pool, provider);
+    });
+}
+export async function removeManagedAccount(provider, ref) { return remove(provider, (rows) => resolve(rows, ref), ref); }
+/** Remove the account whose row id is `id` (see `readSubscriptionPoolRows`); throws when no account has it. */
+export async function removeManagedAccountById(provider, id) { return remove(provider, (rows) => rows.findIndex(({ row }) => row.id === id), id); }
+export async function removeSubscription(provider, ref) { return remove(provider, (rows) => resolve(rows, ref), ref); }
+export async function removeAllManagedAccounts(provider) {
+    return locked(provider, async ({ db, person, rows }) => {
+        await db.prepare('DELETE FROM model_accounts WHERE person=? AND provider_id=?').run(person, provider);
+        await deleteModelCooldowns(db, person, provider);
+        return rows.length;
+    });
+}
+export async function removeManagedProvider(provider, label) { if (label === undefined) {
+    await removeAllManagedAccounts(provider);
+    return [];
+} return removeManagedAccount(provider, label); }
+export async function promoteSubscription(provider, ref) {
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const index = resolve(rows, ref);
+        if (index < 0)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`);
+        const reordered = [rows[index], ...rows.filter((_, i) => i !== index)];
+        for (const [position, item] of reordered.entries())
+            await updateHealth(db, person, { ...item.row, position });
+        return publicPool(pool, provider);
+    });
+}
+/** Health writes lock only the one account's row: a 429 on one account never waits for a mutation of another. */
+async function healthWrite(provider, ref, write) {
+    const person = await personIdAsync();
+    await withCanvasWrite(async (db) => {
+        await setLockTimeout(db);
+        const account = await lockedAccount(db, person, provider, ref);
+        if (!account)
+            throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`);
+        await write(db, person, account.row);
+    });
+    return readSubscriptionPool(provider);
+}
+export async function markSubscriptionAttempt(provider, ref, attemptAt = Date.now()) { return healthWrite(provider, ref, (db, person, row) => updateHealth(db, person, { ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt) })); }
+/** Record a 429 on an account. `scope` defaults to the whole account; a model scope cools only that family on this account, and a 429 older than the newest one already recorded for the same scope is ignored. */
+export async function markSubscriptionRateLimited(provider, ref, retryAfterMs, attemptAt = Date.now(), rateLimitedAt = Date.now(), scope = { kind: 'account' }) {
+    retryAfterMs = Math.min(Math.max(0, retryAfterMs), MAX_RATE_LIMIT_COOLDOWN_MS);
+    return healthWrite(provider, ref, async (db, person, row) => {
+        if (scope.kind === 'account') {
+            if (rateLimitedAt < row.lastRateLimitedAt)
+                return;
+            await updateHealth(db, person, { ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt), lastRateLimitedAt: rateLimitedAt, rateLimitedUntil: rateLimitedAt + retryAfterMs });
+            return;
+        }
+        await updateHealth(db, person, { ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt) });
+        const current = (await loadCooldowns(db, person, provider)).get(row.id)?.find((cooldown) => cooldown.family === scope.family);
+        if (current && rateLimitedAt < current.lastRateLimitedAt)
+            return;
+        await upsertModelCooldown(db, person, provider, row.id, scope.family, rateLimitedAt + retryAfterMs, rateLimitedAt);
+    });
+}
+/** A call on `modelId` succeeded: clear the account-wide cooldown and auth failure, and that model family's cooldown, unless a newer 429 for the same scope landed after `attemptAt` began. */
+export async function markSubscriptionSuccess(provider, ref, attemptAt = Date.now(), modelId) {
+    const family = modelCooldownFamily(modelId);
+    return healthWrite(provider, ref, async (db, person, row) => {
+        if (attemptAt >= row.lastRateLimitedAt)
+            await updateHealth(db, person, { ...row, authFailure: undefined, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt), rateLimitedUntil: 0 });
+        if (family === undefined)
+            return;
+        const current = (await loadCooldowns(db, person, provider)).get(row.id)?.find((cooldown) => cooldown.family === family);
+        if (current && attemptAt >= current.lastRateLimitedAt)
+            await db.prepare('DELETE FROM model_account_cooldowns WHERE person=? AND provider_id=? AND account_id=? AND family=?').run(person, provider, row.id, family);
+    });
+}
+/** The vendor refused this account's refresh token: flag the row so every pool reader skips it until a sign-in replaces it. Both refresh paths (pi's `modify` and the daemon's /v1/llm) record it here, in the transaction that holds the row lock, so a process waiting on the lock finds the flag and does not spend the token again. */
+async function recordInvalidGrant(db, person, row) { const at = Date.now(); await updateHealth(db, person, { ...row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(row.lastAttemptAt, at), rateLimitedUntil: Math.max(row.rateLimitedUntil, at + INVALID_REFRESH_TOKEN_BACKOFF_MS) }); }
+/** Refresh one account's tokens under its row lock. A process that waited on the lock finds the tokens already fresh (or the account already flagged) and does not call the vendor again. */
+export async function refreshSubscriptionCredential(provider, label, exchange) {
+    const person = await personIdAsync();
+    let outcome;
+    try {
+        outcome = await withCanvasWrite(async (db) => {
+            await setLockTimeout(db);
+            const current = await lockedAccount(db, person, provider, label);
+            if (!current)
+                throw new Error(`${getProviderLabel(provider)} subscription "${label}" no longer exists`);
+            if (current.entry.expires > Date.now())
+                return { entry: current.entry };
+            if (current.row.authFailure)
+                throw new Error(`${getProviderLabel(provider)} subscription "${current.entry.label}" refresh refused with status=400 invalid_grant; it needs a new sign-in`);
+            let next;
+            try {
+                next = await withExchangeTimeout(provider, exchange(current.entry.refresh, current.entry.clientId));
+            }
+            catch (error) {
+                if (!isInvalidRefreshTokenError(error))
+                    throw error;
+                await recordInvalidGrant(db, person, current.row);
+                return { refused: error };
+            }
+            const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId);
+            await setCredential(db, person, provider, current.row.id, stored({ ...current.entry, ...tokens }));
+            return { entry: { ...current.entry, ...tokens } };
+        });
+    }
+    catch (error) {
+        if (lockWaitExpired(error))
+            throw new RefreshBusyError(provider, label);
+        throw error;
+    }
+    if ('refused' in outcome)
+        throw outcome.refused;
+    return outcome.entry;
+}
+export async function modifyElectedSubscription(provider, elect, apply) {
+    const person = await personIdAsync();
+    let outcome;
+    try {
+        outcome = await withCanvasWrite(async (db) => {
+            await setLockTimeout(db);
+            const rows = await loadPool(db, person, provider, true);
+            const attempted = new Set();
+            let lastError;
+            while (attempted.size < rows.length) {
+                const chosen = elect(rows.filter(({ entry }) => !attempted.has(entry.label)).map(({ entry }) => entry));
+                if (!chosen)
+                    break;
+                const current = rows.find(({ entry }) => entry.label === chosen.label);
+                attempted.add(current.entry.label);
+                try {
+                    const next = await withExchangeTimeout(provider, apply(current.entry));
+                    if (!next)
+                        return { entry: current.entry };
+                    const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId);
+                    await setCredential(db, person, provider, current.row.id, stored({ ...current.entry, ...tokens }));
+                    return { entry: { ...current.entry, ...tokens } };
+                }
+                catch (error) {
+                    if (!isInvalidRefreshTokenError(error))
+                        throw error;
+                    lastError = error;
+                    await recordInvalidGrant(db, person, current.row);
+                }
+            }
+            return lastError ? { refused: lastError } : {};
+        });
+    }
+    catch (error) {
+        if (lockWaitExpired(error))
+            throw new RefreshBusyError(provider, elect([])?.label ?? provider);
+        throw error;
+    }
+    if ('refused' in outcome)
+        throw outcome.refused;
+    return outcome.entry;
+}
+export async function enrichManagedLoginIdentity(provider, value) { const supplied = value.accountId?.trim(); const suppliedEmail = value.email?.trim(); if (provider !== ANTHROPIC_PROVIDER_ID)
+    return { ...(supplied ? { accountId: supplied } : {}), ...(suppliedEmail ? { email: suppliedEmail } : {}) }; try {
+    const response = await fetch('https://api.anthropic.com/api/oauth/profile', { headers: { Authorization: `Bearer ${value.access}`, Accept: 'application/json' }, signal: AbortSignal.timeout(3_000) });
+    if (!response.ok)
+        return supplied ? { accountId: supplied } : {};
+    const body = await response.json();
+    const accountId = typeof body.account?.uuid === 'string' && body.account.uuid.trim() ? body.account.uuid.trim() : undefined;
+    const email = typeof body.account?.email === 'string' && body.account.email.trim() ? body.account.email.trim() : undefined;
+    return { ...(accountId ? { accountId } : {}), ...(email ? { email } : {}) };
+}
+catch {
+    return supplied ? { accountId: supplied } : {};
+} }
+export async function commitManagedLogin(provider, label, value) {
+    const identityInfo = await enrichManagedLoginIdentity(provider, value);
+    return locked(provider, async (pool) => {
+        const { db, person, rows } = pool;
+        const selected = value.autoLabel ? undefined : label?.trim();
+        const incomingIdentity = identity({ refresh: value.refresh, accountId: identityInfo.accountId });
+        const matching = (selected ? rows.find(({ entry }) => key(entry.label) === key(selected)) : undefined) ?? rows.find(({ entry }) => identity(entry) === incomingIdentity);
+        let resolved = matching?.entry.label ?? selected;
+        if (!resolved && value.autoLabel) {
+            const base = identityInfo.email || label?.trim() || `Account ${rows.length + 1}`;
+            resolved = base;
+            for (let n = 2; rows.some(({ entry }) => key(entry.label) === key(resolved)); n++)
+                resolved = `${base} (${n})`;
+        }
+        if (!resolved)
+            throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`);
+        const entry = assertCredential(provider, { label: resolved, refresh: value.refresh, access: value.access, expires: value.expires, ...(identityInfo.accountId ? { accountId: identityInfo.accountId } : {}), ...(value.clientId ? { clientId: value.clientId } : {}), rateLimitedUntil: 0, lastAttemptAt: Date.now(), lastRateLimitedAt: value.lastRateLimitedAt });
+        if (!matching) {
+            if (rows.some(({ entry: existing }) => key(existing.label) === key(entry.label)))
+                throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${entry.label}`);
+            const duplicate = rows.find(({ entry: existing }) => identity(existing) === identity(entry));
+            if (identity(entry) && duplicate)
+                throw duplicateAccount(provider, duplicate.entry.label);
+            await insertAccount(db, person, provider, { providerId: provider, id: randomUUID(), label: entry.label, labelKey: key(entry.label), position: rows.length, lastAttemptAt: entry.lastAttemptAt, lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil }, stored(entry));
+            return publicPool(pool, provider);
+        }
+        const row = matching.row;
+        const duplicate = rows.find(({ entry: other }) => other.label !== matching.entry.label && identity(other) === identity(entry));
+        if (identity(entry) && duplicate)
+            throw duplicateAccount(provider, duplicate.entry.label);
+        const clear = entry.lastRateLimitedAt >= row.lastRateLimitedAt;
+        await setCredential(db, person, provider, row.id, stored(entry));
+        await updateHealth(db, person, { ...row, authFailure: undefined, lastAttemptAt: Math.max(row.lastAttemptAt, entry.lastAttemptAt), lastRateLimitedAt: clear ? entry.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: clear ? 0 : row.rateLimitedUntil });
+        if (differentAccount(matching.entry, entry))
+            await deleteModelCooldowns(db, person, provider, row.id);
+        return publicPool(pool, provider);
+    });
+}
+const rotationCache = new Map();
+function rotationFromRow(row) { return { defaultFallbackStrength: normalizeStrength(row?.default_fallback_strength) ?? DEFAULT_FALLBACK_STRENGTH, revertWhenAvailable: row?.revert_when_available === undefined || row.revert_when_available === null ? true : Boolean(row.revert_when_available) }; }
+/** The person's rotation settings from their `model_settings` row (defaults when there is no row), also stored for `readRotationConfig`. */
+export async function loadRotationConfig() {
+    const person = await personIdAsync();
+    const loaded = rotationFromRow(await (await openDb()).prepare('SELECT default_fallback_strength,revert_when_available FROM model_settings WHERE person=?').get(person));
+    rotationCache.set(person, loaded);
+    return loaded;
+}
+registerRotationReader(() => readRotationConfig());
+/** Rotation settings for route expansion: a broker's launch snapshot (a broker never reads rows), else the person's `model_settings` row. */
+export async function readRotationConfig() {
+    const snapshot = brokerConfigSnapshot();
+    return snapshot ? snapshot.rotation : loadRotationConfig();
+}
+export async function writeRotationConfig(next) {
+    const person = await personIdAsync();
+    const merged = await withCanvasWrite(async (db) => {
+        await setLockTimeout(db);
+        await db.prepare('INSERT INTO model_settings(person) VALUES(?) ON CONFLICT(person) DO NOTHING').run(person);
+        const current = rotationFromRow(await db.prepare('SELECT default_fallback_strength,revert_when_available FROM model_settings WHERE person=? FOR UPDATE').get(person));
+        const result = { defaultFallbackStrength: normalizeStrength(next.defaultFallbackStrength) ?? current.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH, revertWhenAvailable: next.revertWhenAvailable ?? current.revertWhenAvailable ?? true };
+        await db.prepare('UPDATE model_settings SET default_fallback_strength=?,revert_when_available=?,revision=revision+1 WHERE person=?').run(result.defaultFallbackStrength, result.revertWhenAvailable ? 1 : 0, person);
+        return result;
+    });
+    rotationCache.set(person, merged);
+    return merged;
+}
+/** Stable per-install UUID sent to OpenAI as `ext_agent_host_id=urn:uuid:<id>` during ChatGPT sign-in: the person's get-or-create secret in `model_settings`. */
+export async function openAIDeviceId() {
+    const person = await personIdAsync();
+    const row = await (await openDb()).prepare('INSERT INTO model_settings(person,openai_device_id) VALUES(?,?) ON CONFLICT(person) DO UPDATE SET openai_device_id=COALESCE(model_settings.openai_device_id,EXCLUDED.openai_device_id) RETURNING openai_device_id').get(person, randomUUID());
+    return row.openai_device_id;
+}
+export async function formatStatusLine(provider, now = Date.now(), modelId) { const pool = await readSubscriptionPool(provider); const ready = pool.filter((entry) => entry.authFailure === undefined && coolingUntilFor(entry, modelId) <= now); const label = getProviderLabel(provider); return ready.length === 0 ? `${label} pool exhausted` : `${label} ${ready[0]?.label ?? provider} (${ready.length}/${pool.length} ready)`; }

package/dist/core/substrate/delivery/corpus.d.ts

@@ -0,0 +1,26 @@
+import type { ObjectRow, Reader, RuleOn } from '../../graph/types.js';
+import type { ProfileManifest } from '../../../types.js';
+import { type NodeConfigSubject } from '../subject.js';
+import type { Rung } from '../schema.js';
+import type { DeliveryDoc } from './types.js';
+import type { CanvasDb } from '../../canvas/db.js';
+export declare function ownerHandle(owner: ObjectRow): string;
+/** The key that names one owner exactly in `delivery_limits`: `<type>:<handle>`,
+ *  the typed form `resolveName` accepts (`repo:crouter`, `person:user`, `app:terminal`). */
+export declare function typedLimitKey(owner: ObjectRow): string;
+/** The profile's cap for one owner. A typed key (`<type>:<handle>`) beats a bare
+ *  handle key, which matches an owner of any type holding that handle. The
+ *  reader's own profile is never capped, even when a bare key shares its handle
+ *  with another owner; an owner the profile does not name is uncapped. */
+export declare function deliveryLimitFor(manifest: ProfileManifest | null, owner: ObjectRow, reader?: Reader): Rung;
+/** Fetch the bodies of every document in `docs` that has not read its own, in one query, so each `body()` call after it answers from memory. */
+export declare function primeBodies(db: CanvasDb, docs: readonly DeliveryDoc[]): Promise<void>;
+/** Documents with a rule on one of `on` that the reader may read, in view order. At `boot` a node's own documents come in even without a
+ *  boot rule. */
+export declare function loadCorpus(db: CanvasDb, reader: Reader, on: RuleOn[]): Promise<DeliveryDoc[]>;
+/** One document as a delivery document for `reader`, with all its rules (an explicit read). */
+export declare function deliveryDocOf(db: CanvasDb, reader: Reader, doc: ObjectRow): Promise<DeliveryDoc>;
+/** Every listed document of one owner the reader can read, for prefix listings. */
+export declare function listingCorpus(db: CanvasDb, reader: Reader, owner: ObjectRow): Promise<DeliveryDoc[]>;
+/** The node reader's gate subject, with `repo` from the reader's eligible repos (cwd's, then its profile projects'). */
+export declare function nodeSubject(_db: CanvasDb, reader: Reader): Promise<NodeConfigSubject>;

package/dist/core/substrate/delivery/corpus.js

@@ -0,0 +1,138 @@
+/** The documents delivery may consider for one reader: every document carrying a rule for the activity (or, at boot, owned by the node) that
+ *  the reader's `permits(read)` admits inside the query. The reader's view only ranks names and caps owners. */
+import { permits, resolveReader } from '../../permissions/evaluator.js';
+import { get as getBody, getMany as getBodies } from '../../graph/bodies.js';
+import { resolveName, viewOf, viewResolutions } from '../../graph/names.js';
+import { rulesOn, rulesOf } from '../../graph/rules.js';
+import { loadExactProfileManifest } from '../../profiles/manifest.js';
+import { assembleNodeSubject } from '../subject.js';
+import { mapAsync } from '../../async-array.js';
+export function ownerHandle(owner) {
+    return owner.type === 'node' ? owner.id : owner.name;
+}
+/** The key that names one owner exactly in `delivery_limits`: `<type>:<handle>`,
+ *  the typed form `resolveName` accepts (`repo:crouter`, `person:user`, `app:terminal`). */
+export function typedLimitKey(owner) {
+    return `${owner.type}:${ownerHandle(owner)}`;
+}
+/** The profile's cap for one owner. A typed key (`<type>:<handle>`) beats a bare
+ *  handle key, which matches an owner of any type holding that handle. The
+ *  reader's own profile is never capped, even when a bare key shares its handle
+ *  with another owner; an owner the profile does not name is uncapped. */
+export function deliveryLimitFor(manifest, owner, reader) {
+    if (reader?.class === 'node' && reader.profile !== null && reader.profile.id === owner.id)
+        return 'content';
+    const limits = manifest?.delivery_limits;
+    if (!limits)
+        return 'content';
+    return limits[typedLimitKey(owner)] ?? limits[ownerHandle(owner)] ?? 'content';
+}
+async function readerManifest(db, reader) {
+    if (reader.class !== 'node' || reader.profile === null)
+        return null;
+    const row = await db.prepare("SELECT external_id FROM identities WHERE object = ? AND scheme = 'profile'").get(reader.profile.id);
+    if (!row)
+        throw new Error(`profile object ${reader.profile.id} has no profile identity`);
+    return loadExactProfileManifest(row.external_id).manifest;
+}
+/** The live documents satisfying `where` that the reader may read. */
+async function documentRows(db, ev, where, args) {
+    const read = await permits(db, ev, 'read', 'o');
+    return await db.prepareUncached(`SELECT o.*, d.heads_key, d.unlisted, d.source_path FROM objects o JOIN documents d ON d.object = o.id
+    WHERE o.type = 'document' AND o.deleted_at IS NULL AND ${where} AND ${read.sql} ORDER BY o.seq`).all(...args, ...read.params);
+}
+async function headBodyHash(db, doc) {
+    const heads = doc.heads_key.split(',');
+    const row = await db.prepareUncached(`SELECT body_hash FROM revisions WHERE document = ? AND rev_id IN (${heads.map(() => '?').join(',')})
+    ORDER BY number DESC LIMIT 1`).get(doc.id, ...heads);
+    if (!row)
+        throw new Error(`document ${doc.id} has no head revision ${doc.heads_key}`);
+    return row.body_hash;
+}
+/** One reader's view and resolved evaluator reader, shared by every document of one corpus: each document's display name resolves its bare
+ *  name against the view. */
+async function resolveContext(db, reader, view) {
+    return { view, ev: await resolveReader(db, reader) };
+}
+/** `resolvedNames` holds what each corpus name resolves to (`viewResolutions`); a name without an entry is resolved here. */
+async function toDeliveryDoc(db, reader, context, manifest, doc, rules, resolvedNames) {
+    const { view } = context;
+    const viewRank = view.findIndex((o) => o.id === doc.owner);
+    const owner = viewRank >= 0 ? view[viewRank] : await db.prepare('SELECT * FROM objects WHERE id = ?').get(doc.owner);
+    const handle = ownerHandle(owner);
+    const known = resolvedNames?.get(doc.name);
+    const resolved = known === undefined ? await resolveName(db, reader, doc.name, context) : known === null ? { missing: true } : { object: { id: known } };
+    const bodyHash = await headBodyHash(db, doc);
+    const { heads_key, unlisted, source_path, ...object } = doc;
+    const delivery = {
+        object, owner, ownerHandle: handle, viewRank: viewRank >= 0 ? viewRank : view.length,
+        ownNode: reader.class === 'node' && doc.owner === reader.node.id,
+        shipped: source_path !== null,
+        kind: doc.kind === 'preference' ? 'preference' : 'knowledge',
+        name: doc.name,
+        displayName: 'object' in resolved && resolved.object.id === doc.id ? doc.name : `${handle}/${doc.name}`,
+        preview: doc.preview, unlisted: unlisted !== 0, headsKey: heads_key, bodyHash,
+        body: async () => texts.get(delivery) ?? remember(delivery, await getBody(db, bodyHash)),
+        rules, limit: deliveryLimitFor(manifest, owner, reader),
+    };
+    return delivery;
+}
+const texts = new WeakMap();
+function remember(doc, text) {
+    texts.set(doc, text);
+    return text;
+}
+/** Fetch the bodies of every document in `docs` that has not read its own, in one query, so each `body()` call after it answers from memory. */
+export async function primeBodies(db, docs) {
+    const unread = docs.filter((d) => !texts.has(d));
+    const fetched = await getBodies(db, unread.map((d) => d.bodyHash));
+    for (const d of unread)
+        texts.set(d, fetched.get(d.bodyHash));
+}
+/** Documents with a rule on one of `on` that the reader may read, in view order. At `boot` a node's own documents come in even without a
+ *  boot rule. */
+export async function loadCorpus(db, reader, on) {
+    const view = await viewOf(db, reader);
+    const context = await resolveContext(db, reader, view);
+    const manifest = await readerManifest(db, reader);
+    const rulesByDoc = new Map();
+    // A document owned by another node is readable but never delivered: a node's rules reach that node's own sessions only.
+    const read = await permits(db, context.ev, 'read', 'o');
+    const deliverable = { sql: `${read.sql} AND (NOT EXISTS (SELECT 1 FROM objects own WHERE own.id = o.owner AND own.type = 'node') OR o.owner = ?)`,
+        params: [...read.params, reader.class === 'node' ? reader.node.id : ''] };
+    for (const rule of await rulesOn(db, on, deliverable)) {
+        rulesByDoc.set(rule.object, [...rulesByDoc.get(rule.object) ?? [], rule]);
+    }
+    const own = reader.class === 'node' && on.includes('boot') ? await documentRows(db, context.ev, 'o.owner = ?', [reader.node.id]) : [];
+    const ids = [...new Set([...rulesByDoc.keys(), ...own.map((d) => d.id)])];
+    const rows = ids.length === 0 ? [] : await documentRows(db, context.ev, `o.id IN (${ids.map(() => '?').join(',')})`, ids);
+    const rank = new Map(view.map((o, i) => [o.id, i]));
+    const rankOf = (o) => rank.get(o.owner) ?? view.length;
+    const resolvedNames = await viewResolutions(db, context, rows.map((r) => r.name));
+    return (await mapAsync(rows.sort((a, b) => rankOf(a) - rankOf(b) || a.seq - b.seq), async (row) => await toDeliveryDoc(db, reader, context, manifest, row, rulesByDoc.get(row.id) ?? [], resolvedNames)));
+}
+/** One document as a delivery document for `reader`, with all its rules (an explicit read). */
+export async function deliveryDocOf(db, reader, doc) {
+    const context = await resolveContext(db, reader, await viewOf(db, reader));
+    const row = (await documentRows(db, context.ev, 'o.id = ?', [doc.id]))[0];
+    if (!row)
+        throw new Error(`document ${doc.id} has no documents row or is not readable`);
+    return await toDeliveryDoc(db, reader, context, await readerManifest(db, reader), row, await rulesOf(db, row));
+}
+/** Every listed document of one owner the reader can read, for prefix listings. */
+export async function listingCorpus(db, reader, owner) {
+    const context = await resolveContext(db, reader, await viewOf(db, reader));
+    const manifest = await readerManifest(db, reader);
+    const rows = await documentRows(db, context.ev, 'o.owner = ? AND d.unlisted = 0', [owner.id]);
+    const resolvedNames = await viewResolutions(db, context, rows.map((r) => r.name));
+    return (await mapAsync(rows, async (row) => await toDeliveryDoc(db, reader, context, manifest, row, await rulesOf(db, row), resolvedNames)));
+}
+/** The node reader's gate subject, with `repo` from the reader's eligible repos (cwd's, then its profile projects'). */
+export async function nodeSubject(_db, reader) {
+    if (reader.class !== 'node')
+        throw new Error(`nodeSubject needs a node reader, got ${reader.class}`);
+    const subject = await assembleNodeSubject(reader.node.id, [...reader.repos, ...reader.projectRepos]);
+    if (subject === null)
+        throw new Error(`no node ${reader.node.id}`);
+    return subject;
+}