@north-light/api 0.3.579 → 0.3.587

package/dist/core/scoped-state/migrate.js

@@ -0,0 +1,332 @@
+import { prepared as cachedStatement } from '../sqlite-statements.js';
+import { randomUUID } from 'node:crypto';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import lockfile from 'proper-lockfile';
+import { CONFIG_FILE, PROFILE_DIR, STATE_FILE } from '../../types.js';
+import { LockedJsonFile } from '../locked-file.js';
+import { assertScopedStoreReady, createScopedStore, openScopedStore, discardIncompleteScopedStore, legacyScopedStorePaths, PROFILE_ID_SHAPE, scopedStoreExists, withProjectStateLock, writeOwnerRoot } from './db.js';
+import { canonicalRoot, providerStore, projectStore, userStore } from './paths.js';
+import { profileSpace, appSpace } from '../layout.js';
+import { createScopedSchema } from './schema.js';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { loadSecretsKey, seal } from '../secrets/index.js';
+import { putEnvRowIfAbsent } from '../secrets/env-rows.js';
+import { DEPLOYMENT_ID } from '../secrets/environment-secrets.js';
+import { isReservedEnvName, validateEnvVarName } from '../env-name.js';
+import { insertAccount, upsertModelCooldown } from '../subscription-state.js';
+import { userScopeRoot } from '../scope.js';
+import { secretsDir } from '../layout.js';
+import { readLegacyUserSnapshot } from './legacy-profiles.js';
+import { revisionOf } from './person-store.js';
+import { loadPersonSettings, applyOpsToRows, readSnapshotFromRows } from './person-rows.js';
+function json(path) { return JSON.parse(readFileSync(path, 'utf8')); }
+function existsLegacy(paths) { return paths.some(existsSync); }
+function preserve(root, paths) { const target = join(root, '.legacy-scoped-state'); try {
+    mkdirSync(target, { mode: 0o700 });
+}
+catch (error) {
+    if (error.code !== 'EEXIST' || !statSync(target).isDirectory())
+        throw error;
+} chmodSync(target, 0o700); for (const path of paths)
+    if (existsSync(path) && statSync(path).isFile()) {
+        const fromRoot = relative(root, path);
+        if (fromRoot === '' || fromRoot.startsWith('..'))
+            throw new Error(`legacy state is outside its owning root: ${path}`);
+        const destination = join(target, fromRoot);
+        if (dirname(destination) !== target)
+            mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+        copyFileSync(path, destination);
+        chmodSync(destination, 0o600);
+    } }
+/** Conversion is intentionally explicit. Deployment coordination must prove all legacy writers at these shared roots are stopped before calling it. */
+export function convertLegacyScopedStore(input) {
+    const store = input.kind === 'user' ? userStore(input.root) : input.kind === 'project' ? projectStore(input.root) : providerStore(input.root);
+    if (input.kind !== 'project' && scopedStoreExists(store))
+        return;
+    if (input.kind === 'provider')
+        throw new Error('provider conversion requires convertLegacyProviderStore() under coordinated shared-agent-dir activation');
+    const paths = legacyScopedStorePaths(store);
+    const convert = () => {
+        if (input.kind === 'project')
+            discardIncompleteScopedStore(store);
+        if (scopedStoreExists(store))
+            return;
+        if (input.kind === 'project' && existsLegacy(paths))
+            preserve(store.root, paths);
+        createScopedStore(store, (db) => {
+            createScopedSchema(db, input.kind);
+            const owner = input.kind === 'user' ? 'user' : 'project';
+            writeOwnerRoot(db, owner, store.root);
+            if (input.kind === 'user')
+                importUser(db, store.root);
+            else
+                importState(db, owner, join(store.root, STATE_FILE));
+        });
+        if (input.kind === 'user' && existsLegacy(paths))
+            preserve(store.root, paths);
+    };
+    if (input.kind === 'project')
+        withProjectStateLock(store.root, () => { convert(); assertScopedStoreReady(store); });
+    else
+        convert();
+}
+function parseLegacyProviderPool(path) {
+    if (!existsSync(path))
+        return [];
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!Array.isArray(raw))
+        throw new Error(`legacy subscription pool is malformed: ${path}`);
+    const labels = new Set();
+    return raw.map((item, position) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            throw new Error(`legacy subscription pool entry ${position + 1} is malformed: ${path}`);
+        const value = item;
+        const label = typeof value.label === 'string' ? value.label.trim() : '';
+        const refresh = typeof value.refresh === 'string' ? value.refresh.trim() : '';
+        const access = typeof value.access === 'string' ? value.access.trim() : '';
+        const expires = Number(value.expires);
+        if (!label || !refresh || !access || !Number.isFinite(expires))
+            throw new Error(`legacy subscription pool entry ${position + 1} is incomplete: ${path}`);
+        const labelKey = label.toLowerCase();
+        if (labels.has(labelKey))
+            throw new Error(`legacy subscription pool has duplicate label "${label}": ${path}`);
+        labels.add(labelKey);
+        const timing = (field) => Number.isFinite(Number(value[field])) ? Number(value[field]) : 0;
+        const accountId = typeof value.accountId === 'string' && value.accountId.trim() !== '' ? value.accountId.trim() : undefined;
+        return { label, refresh, access, expires, rateLimitedUntil: timing('rateLimitedUntil'), lastAttemptAt: timing('lastAttemptAt'), lastRateLimitedAt: timing('lastRateLimitedAt'), ...(value.authFailure === 'invalid_grant' ? { authFailure: 'invalid_grant' } : {}), ...(accountId ? { accountId } : {}) };
+    });
+}
+function parseLegacyRotation(path) {
+    if (!existsSync(path))
+        return {};
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error(`legacy provider rotation settings are malformed: ${path}`);
+    const value = raw;
+    return { ...(value.defaultFallbackStrength === 'ultra' || value.defaultFallbackStrength === 'strong' || value.defaultFallbackStrength === 'medium' || value.defaultFallbackStrength === 'light' ? { defaultFallbackStrength: value.defaultFallbackStrength } : {}), ...(typeof value.revertWhenAvailable === 'boolean' ? { revertWhenAvailable: value.revertWhenAvailable } : {}) };
+}
+async function withLegacyProviderLocks(paths, run) {
+    const releases = [];
+    try {
+        for (const path of paths)
+            if (existsSync(path))
+                releases.push(await lockfile.lock(path, { realpath: false, retries: 0, stale: 30_000, update: 10_000 }));
+        return await run();
+    }
+    finally {
+        await Promise.allSettled(releases.reverse().map((release) => release()));
+    }
+}
+/** Converts legacy provider pools only after the activation owner has stopped every writer sharing this agent directory. */
+export async function convertLegacyProviderStore(agentDir) {
+    const store = providerStore(agentDir);
+    if (scopedStoreExists(store))
+        return;
+    const paths = legacyScopedStorePaths(store);
+    await withLegacyProviderLocks(paths, async () => {
+        if (scopedStoreExists(store))
+            return;
+        const pools = new Map(paths.slice(0, 2).map((path, index) => [index === 0 ? 'anthropic' : 'openai-codex', parseLegacyProviderPool(path)]));
+        const rotation = parseLegacyRotation(paths[2]);
+        mkdirSync(store.root, { recursive: true, mode: 0o700 });
+        preserve(store.root, paths);
+        for (const [provider, pool] of pools) {
+            const accounts = Object.fromEntries(pool.map((entry) => { const id = randomUUID(); return [id, { refresh: entry.refresh, access: entry.access, expires: entry.expires, ...(entry.accountId ? { accountId: entry.accountId } : {}) }]; }));
+            const file = new LockedJsonFile(join(store.root, `${provider}-credentials.json`), true, '{"version":1,"accounts":{}}\n');
+            await file.withLockAsync(async (_current, _held, publish) => { publish(`${JSON.stringify({ version: 1, accounts })}\n`); return { result: undefined }; });
+        }
+        createScopedStore(store, (db) => {
+            createScopedSchema(db, 'provider');
+            for (const [provider, pool] of pools) {
+                const accounts = JSON.parse(readFileSync(join(store.root, `${provider}-credentials.json`), 'utf8'));
+                const ids = Object.keys(accounts.accounts);
+                const insert = cachedStatement(db, 'INSERT INTO managed_accounts(provider_id,id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure) VALUES(?,?,?,?,?,?,?,?,?)');
+                pool.forEach((entry, position) => insert.run(provider, ids[position], entry.label, entry.label.toLowerCase(), position, entry.lastAttemptAt, entry.lastRateLimitedAt, entry.rateLimitedUntil, entry.authFailure ?? null));
+            }
+            if (rotation.defaultFallbackStrength !== undefined || rotation.revertWhenAvailable !== undefined)
+                cachedStatement(db, 'INSERT INTO rotation_settings(singleton,default_fallback_strength,revert_when_available) VALUES(1,?,?)').run(rotation.defaultFallbackStrength ?? null, rotation.revertWhenAvailable === undefined ? null : rotation.revertWhenAvailable ? 1 : 0);
+        });
+    });
+}
+function importSettings(db, owner, path) { if (!existsSync(path))
+    return; const raw = json(path); if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+    throw new Error(`legacy config is malformed: ${path}`); cachedStatement(db, 'INSERT INTO scope_settings(owner_key,raw_json) VALUES(?,?)').run(owner, JSON.stringify(raw)); }
+function importState(db, owner, path) { if (!existsSync(path))
+    return; const raw = json(path); if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+    throw new Error(`legacy state is malformed: ${path}`); const state = raw; cachedStatement(db, 'INSERT INTO scope_bookkeeping(owner_key,last_self_check,active_canvas) VALUES(?,?,?)').run(owner, state.last_self_check ?? null, state.activeCanvas ?? null); const market = cachedStatement(db, 'INSERT INTO scope_marketplaces(owner_key,name,last_updated) VALUES(?,?,?)'); for (const [name, value] of Object.entries(state.marketplaces ?? {}))
+    market.run(owner, name, value.last_updated ?? null); const plugins = cachedStatement(db, 'INSERT INTO scope_plugins(owner_key,name,last_updated,etag,checked_at) VALUES(?,?,?,?,?)'); for (const [name, value] of Object.entries(state.plugins ?? {}))
+    plugins.run(owner, name, value.last_updated ?? null, value.etag ?? null, value.checked_at ?? null); }
+function importUser(db, root) {
+    importSettings(db, 'user', join(root, CONFIG_FILE));
+    importState(db, 'user', join(root, STATE_FILE));
+    const profiles = join(root, PROFILE_DIR);
+    if (existsSync(profiles))
+        for (const entry of readdirSync(profiles, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !PROFILE_ID_SHAPE.test(entry.name))
+                continue;
+            const id = entry.name;
+            const profileRoot = join(profiles, id);
+            const path = join(profileRoot, 'profile.json');
+            if (!existsSync(path))
+                throw new Error(`legacy profile manifest is missing: ${path}`);
+            const manifest = json(path);
+            if (!manifest || typeof manifest !== 'object' || !Array.isArray(manifest.projects) || typeof manifest.name !== 'string' || typeof manifest.created_at !== 'string')
+                throw new Error(`legacy profile manifest is malformed: ${path}`);
+            cachedStatement(db, 'INSERT INTO profiles(id,name,created_at,last_used_at,paused_at,default_kind,grantee,metadata_json) VALUES(?,?,?,?,?,?,?,?)').run(id, manifest.name, manifest.created_at, manifest.last_used_at ?? null, manifest.paused_at ?? null, manifest.default_kind ?? null, manifest.grantee ?? null, JSON.stringify(manifest.metadata ?? {}));
+            cachedStatement(db, 'INSERT INTO scope_owners(owner_key,kind,root,profile_id) VALUES(?,?,?,?)').run(`profile:${id}`, 'profile', canonicalRoot(profileSpace(manifest.grantee ?? 'app:terminal', id).dir), id);
+            const project = cachedStatement(db, 'INSERT INTO profile_projects(profile_id,path,position) VALUES(?,?,?)');
+            const cap = cachedStatement(db, 'INSERT INTO legacy_project_caps(profile_id,path,memory) VALUES(?,?,?)');
+            manifest.projects.forEach((p, position) => { project.run(id, p.path, position); if (p.memory !== undefined && p.memory !== 'content')
+                cap.run(id, p.path, p.memory); });
+            importSettings(db, `profile:${id}`, join(profileRoot, CONFIG_FILE));
+            importState(db, `profile:${id}`, join(profileRoot, STATE_FILE));
+        }
+    const defaults = join(root, 'profile-defaults.json');
+    if (existsSync(defaults)) {
+        const raw = json(defaults);
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error(`legacy profile defaults are malformed: ${defaults}`);
+        const insert = cachedStatement(db, 'INSERT INTO profile_defaults(directory,profile_id) VALUES(?,?)');
+        for (const [directory, id] of Object.entries(raw)) {
+            if (typeof id !== 'string')
+                throw new Error(`legacy profile default is malformed: ${defaults}`);
+            insert.run(directory, id);
+        }
+    }
+}
+// ------------------------------------------------------------------ the one-time boot copy into the person's rows
+const COPIED_KEY = 'person_stores_copied';
+const CREDENTIAL_FILES = { anthropic: 'anthropic-credentials.json', 'openai-codex': 'openai-codex-credentials.json', openai: 'openai-credentials.json' };
+export async function personStoresCopied() {
+    const row = await (await openDb()).prepare('SELECT value FROM canvas_meta WHERE key = ?').get(COPIED_KEY);
+    return row !== undefined;
+}
+function readLegacyAccounts(agentDir) {
+    const store = providerStore(agentDir);
+    if (!scopedStoreExists(store))
+        return [];
+    const db = openScopedStore(store);
+    const out = [];
+    for (const provider of Object.keys(CREDENTIAL_FILES)) {
+        const path = join(agentDir, CREDENTIAL_FILES[provider]);
+        if (!existsSync(path))
+            continue;
+        const file = json(path);
+        const cooldowns = cachedStatement(db, 'SELECT account_id,family,rate_limited_until,last_rate_limited_at FROM managed_account_model_cooldowns WHERE provider_id=?').all(provider);
+        for (const r of cachedStatement(db, 'SELECT id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure FROM managed_accounts WHERE provider_id=? ORDER BY position').all(provider)) {
+            const tokens = file.accounts?.[r.id];
+            if (tokens === undefined)
+                continue;
+            out.push({
+                provider, id: r.id,
+                row: { 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 } : {}) },
+                tokens: { refresh: tokens.refresh, access: tokens.access, expires: tokens.expires, ...(tokens.accountId ? { accountId: tokens.accountId } : {}), ...(tokens.clientId ? { clientId: tokens.clientId } : {}) },
+                cooldowns: cooldowns.filter((c) => c.account_id === r.id).map((c) => ({ family: c.family, until: c.rate_limited_until, at: c.last_rate_limited_at })),
+            });
+        }
+    }
+    return out;
+}
+/** The old `{vars}` env file at `path`, with the filters its reader applied: a valid name, a string value without NUL, and the names `admits` allows. */
+function readLegacyEnvFile(path, admits) {
+    if (!existsSync(path) || !statSync(path).isFile())
+        return {};
+    let raw;
+    try {
+        raw = json(path);
+    }
+    catch {
+        return {};
+    } // the old reader gave a corrupt file no values; the file stays for the person
+    const out = {};
+    if (raw === null || typeof raw !== 'object' || raw.vars === null || typeof raw.vars !== 'object' || Array.isArray(raw.vars))
+        return out;
+    for (const [name, value] of Object.entries(raw.vars))
+        if (validateEnvVarName(name).isValid && admits(name) && typeof value === 'string' && !value.includes('\0'))
+            out[name] = value;
+    return out;
+}
+const LEGACY_DEPLOYMENT_NAMES = new Set(['CRTR_FEEDBACK_ENDPOINT', 'CRTR_FEEDBACK_TOKEN']);
+/** Seal every legacy env file into `env_vars` rows: each profile's file, each app's `_app` file and the deployment-wide `_deployment` file under `<secrets>/env`. */
+async function copyLegacyEnvFiles(db, person, profiles) {
+    const envRoot = join(secretsDir(), 'env');
+    if (!existsSync(envRoot))
+        return;
+    const put = async (owner, vars) => { for (const [name, value] of Object.entries(vars))
+        await putEnvRowIfAbsent(db, owner, name, value); };
+    for (const profile of profiles)
+        await put({ person, kind: 'profile', id: profile.profileId }, readLegacyEnvFile(profileSpace(profile.manifest.grantee ?? 'app:terminal', profile.profileId).env, (name) => !isReservedEnvName(name)));
+    for (const entry of readdirSync(envRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const app = `app:${entry.name}`;
+        if (basename(appSpace(app).root) !== entry.name)
+            continue;
+        await put({ person, kind: 'app', id: app }, readLegacyEnvFile(join(envRoot, entry.name, '_app'), (name) => !isReservedEnvName(name)));
+    }
+    await put({ person: null, kind: 'deployment', id: DEPLOYMENT_ID }, readLegacyEnvFile(join(envRoot, '_deployment'), (name) => LEGACY_DEPLOYMENT_NAMES.has(name)));
+}
+/** Copy this install's files into the person's rows, once: profiles, scope settings and bookkeeping, the plugin and marketplace
+ *  lists, managed model accounts with their cooldowns, rotation settings, the OpenAI device id, `auth.json` API keys and the profile, app and deployment env files (sealed into `env_vars`). One
+ *  transaction, skipping any key a row already holds, ending with `canvas_meta.person_stores_copied`. The files stay, unread. */
+export async function copyPersonStoresToRows(person, legacyUserSnapshot, agentDir) {
+    const accounts = readLegacyAccounts(agentDir);
+    const rotation = (() => { const store = providerStore(agentDir); if (!scopedStoreExists(store))
+        return undefined; return cachedStatement(openScopedStore(store), 'SELECT default_fallback_strength,revert_when_available FROM rotation_settings WHERE singleton=1').get(); })();
+    const deviceIdPath = join(agentDir, 'openai-device-id');
+    const deviceId = existsSync(deviceIdPath) ? readFileSync(deviceIdPath, 'utf8').trim() : '';
+    const authPath = join(agentDir, 'auth.json');
+    const apiKeys = existsSync(authPath) ? Object.entries(json(authPath)).filter(([id]) => !(id in CREDENTIAL_FILES)) : [];
+    await withCanvasWrite(async (db) => {
+        if (await db.prepare('SELECT 1 FROM canvas_meta WHERE key = ?').get(COPIED_KEY) !== undefined)
+            return;
+        if (legacyUserSnapshot !== null) {
+            const have = await readSnapshotFromRows(db, person);
+            const ops = [];
+            const known = new Set(have.profiles.map((p) => p.profileId));
+            for (const profile of legacyUserSnapshot.profiles)
+                if (!known.has(profile.profileId))
+                    ops.push({ op: 'profile.insert', profile });
+            for (const owner of Object.keys(legacyUserSnapshot.settings))
+                if (have.settings[owner] === undefined)
+                    ops.push({ op: 'settings.replace', owner, raw: legacyUserSnapshot.settings[owner], ifRevision: revisionOf(undefined) });
+            for (const owner of Object.keys(legacyUserSnapshot.state)) {
+                const st = legacyUserSnapshot.state[owner];
+                if (have.state[owner] === undefined && (owner === 'user' || known.has(owner.replace(/^profile:/, '')) || legacyUserSnapshot.profiles.some((p) => `profile:${p.profileId}` === owner)))
+                    ops.push({ op: 'state.write', owner, state: st });
+            }
+            if (Object.keys(have.defaults).length === 0 && Object.keys(legacyUserSnapshot.defaults).length > 0)
+                ops.push({ op: 'defaults.replace', defaults: legacyUserSnapshot.defaults });
+            if (ops.length > 0)
+                await applyOpsToRows(db, person, ops);
+        }
+        for (const a of accounts) {
+            const present = await db.prepare('SELECT 1 FROM model_accounts WHERE person=? AND provider_id=? AND (id=? OR label_key=?)').get(person, a.provider, a.id, a.row.labelKey);
+            if (present !== undefined)
+                continue;
+            await insertAccount(db, person, a.provider, a.row, a.tokens);
+            for (const c of a.cooldowns)
+                await upsertModelCooldown(db, person, a.provider, a.id, c.family, c.until, c.at);
+        }
+        if (rotation !== undefined)
+            await db.prepare('INSERT INTO model_settings(person,default_fallback_strength,revert_when_available) VALUES(?,?,?) ON CONFLICT(person) DO NOTHING').run(person, rotation.default_fallback_strength, rotation.revert_when_available);
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deviceId))
+            await db.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)').run(person, deviceId.toLowerCase());
+        for (const [providerId, credential] of apiKeys) {
+            const { sealed, keyId } = seal(JSON.stringify(credential), loadSecretsKey(), `model_api_keys|${person}|${providerId}`);
+            await db.prepare('INSERT INTO model_api_keys(person,provider_id,credential_sealed,key_id,updated_at) VALUES(?,?,?,?,?) ON CONFLICT(person,provider_id) DO NOTHING').run(person, providerId, sealed, keyId, new Date().toISOString());
+        }
+        await copyLegacyEnvFiles(db, person, legacyUserSnapshot?.profiles ?? []);
+        await db.prepare('INSERT INTO canvas_meta(key,value) VALUES(?,?)').run(COPIED_KEY, new Date().toISOString());
+    });
+}
+/** The install's person just became known: copy the old local files into their rows once, then load their snapshot. */
+export async function adoptInstallPerson(person) {
+    if (!(await personStoresCopied())) {
+        const root = userScopeRoot();
+        convertLegacyScopedStore({ kind: 'user', root });
+        await copyPersonStoresToRows(person, readLegacyUserSnapshot(root), secretsDir());
+    }
+    await loadPersonSettings(person);
+}

package/dist/core/scoped-state/person-rows.d.ts

@@ -0,0 +1,10 @@
+import { type CanvasDb } from '../canvas/db.js';
+import { type PersonSnapshot, type SettingsOp, type SettingsTransport } from './person-store.js';
+export declare function readSnapshotFromRows(db: CanvasDb, person: string): Promise<PersonSnapshot>;
+/** Load (or reload) one person's snapshot from the rows into this process. */
+export declare function loadPersonSettings(person: string): Promise<PersonSnapshot>;
+/** Apply ops to the rows inside the caller's transaction. Bumps `person_settings.plugins_revision` when a plugin or marketplace
+ *  block changed, and signals `settings:<person>` in the same transaction so other processes holding the person reload. */
+export declare function applyOpsToRows(db: CanvasDb, person: string, ops: readonly SettingsOp[]): Promise<void>;
+/** The process holds the database: write the rows in one transaction, then reload the person from the committed rows. */
+export declare const rowsTransport: SettingsTransport;

package/dist/core/scoped-state/person-rows.js

@@ -0,0 +1,173 @@
+// person-rows.ts — the database half of the person store: read a person's snapshot from the rows and apply settings ops to them
+// inside one transaction. Only a process that holds the database imports this (crtrd, tests); a CLI or viewer process reaches the
+// same ops over `PUT /v1/settings`. Importing this module makes the rows the process's settings transport and reloader.
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { isCloudRole } from '../canvas/person-state.js';
+import { grantedProviderIds, isProviderBundleRow } from '../grants/mirror.js';
+import { materializePlugins } from './materialized-plugins.js';
+import { revisionOf, setPersonSnapshot, setSettingsReloader, setSettingsTransport, SettingsRevisionConflictError } from './person-store.js';
+const s = (v) => (typeof v === 'string' ? v : undefined);
+export async function readSnapshotFromRows(db, person) {
+    const profileRows = await db.prepare('SELECT * FROM profiles WHERE person = ? AND deleting_since IS NULL ORDER BY created_at, id').all(person);
+    const projectRows = await db.prepare('SELECT p.profile_id, p.path FROM profile_projects p JOIN profiles f ON f.id = p.profile_id WHERE f.person = ? ORDER BY p.profile_id, p.position').all(person);
+    const projects = new Map();
+    for (const r of projectRows)
+        (projects.get(r.profile_id) ?? projects.set(r.profile_id, []).get(r.profile_id)).push({ path: r.path });
+    const profiles = profileRows.map((r) => {
+        const metadata = JSON.parse(String(r['metadata_json']));
+        const limits = JSON.parse(String(r['delivery_limits_json']));
+        return {
+            profileId: String(r['id']),
+            manifest: {
+                schema_version: 1, name: String(r['name']), projects: projects.get(String(r['id'])) ?? [], paused_at: s(r['paused_at']) ?? null,
+                ...(s(r['default_kind']) === undefined ? {} : { default_kind: s(r['default_kind']) }),
+                ...(s(r['grantee']) === undefined ? {} : { grantee: s(r['grantee']) }),
+                ...(s(r['environment_id']) === undefined ? {} : { environment_id: s(r['environment_id']) }),
+                ...(Object.keys(limits).length === 0 ? {} : { delivery_limits: limits }),
+                ...(Object.keys(metadata).length === 0 ? {} : { metadata }),
+                created_at: String(r['created_at']), last_used_at: s(r['last_used_at']) ?? null,
+            },
+        };
+    });
+    const defaults = Object.fromEntries((await db.prepare('SELECT directory, profile_id FROM profile_defaults WHERE person = ?').all(person)).map((r) => [r.directory, r.profile_id]));
+    const settings = {};
+    for (const r of await db.prepare('SELECT owner_key, raw_json FROM scope_settings WHERE person = ?').all(person))
+        settings[r.owner_key] = JSON.parse(r.raw_json);
+    const state = {};
+    const stateOf = (owner) => (state[owner] ??= { marketplaces: {}, plugins: {}, activeCanvas: null });
+    for (const r of await db.prepare('SELECT owner_key, last_self_check, active_canvas FROM scope_bookkeeping WHERE person = ?').all(person)) {
+        const st = stateOf(r.owner_key);
+        if (r.last_self_check !== null)
+            st.last_self_check = r.last_self_check;
+        st.activeCanvas = r.active_canvas;
+    }
+    for (const r of await db.prepare('SELECT * FROM scope_marketplaces WHERE person = ? ORDER BY owner_key, name').all(person)) {
+        const owner = String(r['owner_key']);
+        const name = String(r['name']);
+        stateOf(owner).marketplaces[name] = s(r['last_updated']) === undefined ? {} : { last_updated: s(r['last_updated']) };
+        if (s(r['url']) !== undefined) {
+            const raw = (settings[owner] ??= {});
+            const block = (raw['marketplaces'] ??= {});
+            block[name] = { url: s(r['url']), ref: s(r['ref']) ?? '', installed_at: s(r['installed_at']) ?? '' };
+        }
+    }
+    for (const r of await db.prepare('SELECT * FROM scope_plugins WHERE person = ? ORDER BY owner_key, name').all(person)) {
+        const owner = String(r['owner_key']);
+        const name = String(r['name']);
+        stateOf(owner).plugins[name] = { ...(s(r['last_updated']) === undefined ? {} : { last_updated: s(r['last_updated']) }), ...(s(r['etag']) === undefined ? {} : { etag: s(r['etag']) }), ...(s(r['checked_at']) === undefined ? {} : { checked_at: s(r['checked_at']) }) };
+        const raw = (settings[owner] ??= {});
+        const block = (raw['plugins'] ??= {});
+        block[name] = { enabled: Number(r['enabled']) === 1, ...(s(r['source_marketplace']) === undefined ? {} : { source_marketplace: s(r['source_marketplace']) }), ...(s(r['version']) === undefined ? {} : { version: s(r['version']) }) };
+    }
+    return { profiles, defaults, settings, state };
+}
+/** Load (or reload) one person's snapshot from the rows into this process. */
+export async function loadPersonSettings(person) {
+    const db = await openDb();
+    const snapshot = await readSnapshotFromRows(db, person);
+    // A cloud-role process has no plugin directories: it installs the person's enabled plugins (D84) before the snapshot is usable, so
+    // a request that cannot have its plugins fails here instead of reading an empty list.
+    if (isCloudRole())
+        await materializePersonPlugins(db, person);
+    setPersonSnapshot(person, snapshot);
+    return snapshot;
+}
+/** Install the person's enabled user-scope plugins from their marketplaces, for the current `plugins_revision`. */
+async function materializePersonPlugins(db, person) {
+    const plugins = await db.prepare(`SELECT p.name, p.version, p.source_path, p.source_marketplace, m.url, m.ref FROM scope_plugins p
+    LEFT JOIN scope_marketplaces m ON m.person = p.person AND m.owner_key = p.owner_key AND m.name = p.source_marketplace
+    WHERE p.person = ? AND p.owner_key = 'user' AND p.enabled = 1 ORDER BY p.name`).all(person);
+    const revisionRow = await db.prepare('SELECT plugins_revision FROM person_settings WHERE person = ?').get(person);
+    const granted = await grantedProviderIds(person);
+    const installs = plugins.map((r) => ({
+        name: String(r['name']), version: s(r['version']) ?? null, sourcePath: s(r['source_path']) ?? null,
+        marketplace: s(r['source_marketplace']) === undefined ? null : { name: s(r['source_marketplace']), url: s(r['url']) ?? null, ref: s(r['ref']) ?? null },
+        providerBundle: isProviderBundleRow({ name: String(r['name']), source_marketplace: s(r['source_marketplace']) ?? null, source_path: s(r['source_path']) ?? null }, granted),
+    }));
+    await materializePlugins(person, revisionRow === undefined ? 0 : Number(revisionRow.plugins_revision), installs);
+}
+// ------------------------------------------------------------------ writing rows
+async function currentRaw(db, person, owner) {
+    return (await readSnapshotFromRows(db, person)).settings[owner];
+}
+/** Apply ops to the rows inside the caller's transaction. Bumps `person_settings.plugins_revision` when a plugin or marketplace
+ *  block changed, and signals `settings:<person>` in the same transaction so other processes holding the person reload. */
+export async function applyOpsToRows(db, person, ops) {
+    let pluginsChanged = false;
+    for (const op of ops) {
+        if (op.op === 'settings.replace') {
+            const before = await currentRaw(db, person, op.owner);
+            if (op.ifRevision !== revisionOf(before))
+                throw new SettingsRevisionConflictError();
+            const { plugins, marketplaces, ...rest } = op.raw;
+            const rawJson = JSON.stringify(rest);
+            await db.prepare('INSERT INTO scope_settings (person, owner_key, raw_json) VALUES (?, ?, ?) ON CONFLICT (person, owner_key) DO UPDATE SET raw_json = EXCLUDED.raw_json').run(person, op.owner, rawJson);
+            const pluginBlock = (plugins ?? {});
+            const marketBlock = (marketplaces ?? {});
+            const had = JSON.stringify([before?.['plugins'], before?.['marketplaces']]);
+            if (had !== JSON.stringify([plugins, marketplaces]) && !(had === '[null,null]' && plugins === undefined && marketplaces === undefined))
+                pluginsChanged = true;
+            await db.prepare('DELETE FROM scope_plugins WHERE person = ? AND owner_key = ? AND NOT (name IN (SELECT jsonb_array_elements_text(?::jsonb)))').run(person, op.owner, JSON.stringify(Object.keys(pluginBlock)));
+            for (const [name, e] of Object.entries(pluginBlock)) {
+                await db.prepare(`INSERT INTO scope_plugins (person, owner_key, name, enabled, source_marketplace, version) VALUES (?, ?, ?, ?, ?, ?)
+          ON CONFLICT (person, owner_key, name) DO UPDATE SET enabled = EXCLUDED.enabled, source_marketplace = EXCLUDED.source_marketplace, version = EXCLUDED.version`).run(person, op.owner, name, e.enabled === false ? 0 : 1, e.source_marketplace ?? null, e.version ?? null);
+            }
+            await db.prepare('DELETE FROM scope_marketplaces WHERE person = ? AND owner_key = ? AND NOT (name IN (SELECT jsonb_array_elements_text(?::jsonb)))').run(person, op.owner, JSON.stringify(Object.keys(marketBlock)));
+            for (const [name, e] of Object.entries(marketBlock)) {
+                await db.prepare(`INSERT INTO scope_marketplaces (person, owner_key, name, url, ref, installed_at) VALUES (?, ?, ?, ?, ?, ?)
+          ON CONFLICT (person, owner_key, name) DO UPDATE SET url = EXCLUDED.url, ref = EXCLUDED.ref, installed_at = EXCLUDED.installed_at`).run(person, op.owner, name, e.url ?? null, e.ref ?? null, e.installed_at ?? null);
+            }
+        }
+        else if (op.op === 'state.write') {
+            await db.prepare(`INSERT INTO scope_bookkeeping (person, owner_key, last_self_check, active_canvas) VALUES (?, ?, ?, ?)
+        ON CONFLICT (person, owner_key) DO UPDATE SET last_self_check = EXCLUDED.last_self_check, active_canvas = EXCLUDED.active_canvas`).run(person, op.owner, op.state.last_self_check ?? null, op.state.activeCanvas ?? null);
+            // Bookkeeping updates only rows the settings already created: a row is an install (url / enabled belong to settings), and
+            // bookkeeping for a marketplace or plugin that is not installed is dropped.
+            for (const [name, v] of Object.entries(op.state.marketplaces))
+                await db.prepare('UPDATE scope_marketplaces SET last_updated = ? WHERE person = ? AND owner_key = ? AND name = ?').run(v.last_updated ?? null, person, op.owner, name);
+            for (const [name, v] of Object.entries(op.state.plugins))
+                await db.prepare('UPDATE scope_plugins SET last_updated = ?, etag = ?, checked_at = ? WHERE person = ? AND owner_key = ? AND name = ?').run(v.last_updated ?? null, v.etag ?? null, v.checked_at ?? null, person, op.owner, name);
+        }
+        else if (op.op === 'profile.insert') {
+            const m = op.profile.manifest;
+            await db.prepare('INSERT INTO profiles (id, person, name, created_at, last_used_at, paused_at, default_kind, grantee, metadata_json, delivery_limits_json, environment_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+                .run(op.profile.profileId, person, m.name, m.created_at, m.last_used_at, m.paused_at, m.default_kind ?? null, m.grantee ?? null, JSON.stringify(m.metadata ?? {}), JSON.stringify(m.delivery_limits ?? {}), m.environment_id ?? null);
+            await replaceProjects(db, op.profile);
+        }
+        else if (op.op === 'profile.update') {
+            const m = op.profile.manifest;
+            const r = await db.prepare('UPDATE profiles SET name = ?, last_used_at = ?, paused_at = ?, default_kind = ?, grantee = ?, metadata_json = ?, delivery_limits_json = ?, environment_id = ? WHERE id = ? AND person = ?')
+                .run(m.name, m.last_used_at, m.paused_at, m.default_kind ?? null, m.grantee ?? null, JSON.stringify(m.metadata ?? {}), JSON.stringify(m.delivery_limits ?? {}), m.environment_id ?? null, op.profile.profileId, person);
+            if (r.changes !== 1)
+                throw new Error(`no stored profile ${op.profile.profileId}`);
+            await replaceProjects(db, op.profile);
+        }
+        else if (op.op === 'profile.delete') {
+            const owner = `profile:${op.profileId}`;
+            for (const table of ['scope_settings', 'scope_bookkeeping', 'scope_marketplaces', 'scope_plugins'])
+                await db.prepare(`DELETE FROM ${table} WHERE person = ? AND owner_key = ?`).run(person, owner);
+            await db.prepare('DELETE FROM profiles WHERE id = ? AND person = ?').run(op.profileId, person);
+        }
+        else {
+            await db.prepare('DELETE FROM profile_defaults WHERE person = ?').run(person);
+            for (const [directory, profileId] of Object.entries(op.defaults))
+                await db.prepare('INSERT INTO profile_defaults (person, directory, profile_id) VALUES (?, ?, ?)').run(person, directory, profileId);
+        }
+    }
+    if (pluginsChanged)
+        await db.prepare('INSERT INTO person_settings (person, plugins_revision) VALUES (?, 1) ON CONFLICT (person) DO UPDATE SET plugins_revision = person_settings.plugins_revision + 1').run(person);
+    await db.prepare("SELECT pg_notify('crtr_signal', ?)").get(`settings:${person}`);
+}
+async function replaceProjects(db, profile) {
+    await db.prepare('DELETE FROM profile_projects WHERE profile_id = ?').run(profile.profileId);
+    let position = 0;
+    for (const project of profile.manifest.projects)
+        await db.prepare('INSERT INTO profile_projects (profile_id, path, position) VALUES (?, ?, ?)').run(profile.profileId, project.path, position++);
+}
+/** The process holds the database: write the rows in one transaction, then reload the person from the committed rows. */
+export const rowsTransport = async (person, ops) => {
+    await withCanvasWrite((db) => applyOpsToRows(db, person, ops));
+    return await loadPersonSettings(person);
+};
+setSettingsTransport(rowsTransport);
+setSettingsReloader(loadPersonSettings);

package/dist/core/scoped-state/schema.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const SCOPED_SCHEMA_VERSION = 5;
+export declare const PROVIDER_SCHEMA_VERSION = 1;
+/** `profiles.environment_id` (null = the machine environment) is additive to version 5: a store written before it gains the
+ *  column on open (`upgradeScopedStore`), and an older generation sharing the store names its columns and never reads it, so
+ *  the version stays 5 and a runtime rollback keeps opening the store. */
+export declare const PROFILE_ENVIRONMENT_COLUMN = "environment_id";
+/** Adds the model-cooldown table to a provider store that predates it; a no-op (no write) once present. */
+export declare function ensureProviderModelCooldowns(db: DatabaseSync): void;
+export declare function createScopedSchema(db: DatabaseSync, kind: 'user' | 'project' | 'provider'): void;

package/dist/core/scoped-state/schema.js

@@ -0,0 +1,47 @@
+import { prepared as cachedStatement } from '../sqlite-statements.js';
+export const SCOPED_SCHEMA_VERSION = 5;
+export const PROVIDER_SCHEMA_VERSION = 1;
+/** `profiles.environment_id` (null = the machine environment) is additive to version 5: a store written before it gains the
+ *  column on open (`upgradeScopedStore`), and an older generation sharing the store names its columns and never reads it, so
+ *  the version stays 5 and a runtime rollback keeps opening the store. */
+export const PROFILE_ENVIRONMENT_COLUMN = 'environment_id';
+const SCOPE_SCHEMA = `
+CREATE TABLE scope_owners (owner_key TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK(kind IN ('user','profile','project')), root TEXT NOT NULL UNIQUE, profile_id TEXT UNIQUE);
+CREATE TABLE profiles (id TEXT PRIMARY KEY, name TEXT NOT NULL, created_at TEXT NOT NULL, last_used_at TEXT, paused_at TEXT, default_kind TEXT, grantee TEXT, metadata_json TEXT NOT NULL CHECK(json_valid(metadata_json)), delivery_limits_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(delivery_limits_json)), environment_id TEXT);
+CREATE TABLE profile_projects (profile_id TEXT NOT NULL REFERENCES profiles(id) ON DELETE CASCADE, path TEXT NOT NULL, position INTEGER NOT NULL, PRIMARY KEY(profile_id,path), UNIQUE(profile_id,position));
+-- Pre-canvas per-project memory caps awaiting the canvas import, which turns them into delivery_limits and deletes the rows.
+CREATE TABLE legacy_project_caps (profile_id TEXT NOT NULL, path TEXT NOT NULL, memory TEXT NOT NULL CHECK(memory IN ('none','name','preview')), PRIMARY KEY(profile_id,path));
+CREATE TABLE profile_defaults (directory TEXT PRIMARY KEY, profile_id TEXT NOT NULL REFERENCES profiles(id) ON DELETE CASCADE);
+CREATE TABLE scope_settings (owner_key TEXT PRIMARY KEY REFERENCES scope_owners(owner_key), raw_json TEXT NOT NULL CHECK(json_valid(raw_json)));
+CREATE TABLE scope_bookkeeping (owner_key TEXT PRIMARY KEY REFERENCES scope_owners(owner_key), last_self_check TEXT, active_canvas TEXT);
+CREATE TABLE scope_marketplaces (owner_key TEXT NOT NULL REFERENCES scope_owners(owner_key), name TEXT NOT NULL, last_updated TEXT, PRIMARY KEY(owner_key,name));
+CREATE TABLE scope_plugins (owner_key TEXT NOT NULL REFERENCES scope_owners(owner_key), name TEXT NOT NULL, last_updated TEXT, etag TEXT, checked_at TEXT, PRIMARY KEY(owner_key,name));`;
+// A subscription 429 on one model family's window (Anthropic `seven_day_opus` /
+// `seven_day_sonnet`) cools only that family on that account. Additive to v1: a
+// store written before this table existed gains it on open (ensureProviderModelCooldowns),
+// and older crtr generations sharing the store simply never read it, so the provider
+// schema version stays 1 and a runtime rollback keeps opening the store.
+const MODEL_COOLDOWNS_TABLE = 'CREATE TABLE IF NOT EXISTS managed_account_model_cooldowns (provider_id TEXT NOT NULL, account_id TEXT NOT NULL, family TEXT NOT NULL, rate_limited_until INTEGER NOT NULL, last_rate_limited_at INTEGER NOT NULL, PRIMARY KEY(provider_id,account_id,family));';
+/** Adds the model-cooldown table to a provider store that predates it; a no-op (no write) once present. */
+export function ensureProviderModelCooldowns(db) {
+    const present = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='managed_account_model_cooldowns'").get();
+    if (present === undefined)
+        db.exec(MODEL_COOLDOWNS_TABLE);
+}
+const PROVIDER_SCHEMA = `
+CREATE TABLE managed_accounts (provider_id TEXT NOT NULL, id TEXT NOT NULL, label TEXT NOT NULL, label_key TEXT NOT NULL, position INTEGER NOT NULL, last_attempt_at INTEGER NOT NULL, last_rate_limited_at INTEGER NOT NULL, rate_limited_until INTEGER NOT NULL, auth_failure TEXT CHECK(auth_failure IS NULL OR auth_failure='invalid_grant'), PRIMARY KEY(provider_id,id), UNIQUE(provider_id,label_key));
+CREATE INDEX managed_accounts_order ON managed_accounts(provider_id,position);
+CREATE TABLE rotation_settings (singleton INTEGER PRIMARY KEY CHECK(singleton=1), default_fallback_strength TEXT, revert_when_available INTEGER CHECK(revert_when_available IN (0,1)));
+CREATE TABLE provider_revision (singleton INTEGER PRIMARY KEY CHECK(singleton=1), revision INTEGER NOT NULL);
+${MODEL_COOLDOWNS_TABLE}`;
+export function createScopedSchema(db, kind) {
+    db.exec(kind === 'provider' ? PROVIDER_SCHEMA : SCOPE_SCHEMA);
+    if (kind !== 'provider') {
+        const ownerKey = kind === 'user' ? 'user' : 'project';
+        cachedStatement(db, 'INSERT INTO scope_owners(owner_key, kind, root, profile_id) VALUES (?, ?, ?, NULL)').run(ownerKey, kind, '');
+    }
+    else {
+        cachedStatement(db, 'INSERT INTO provider_revision(singleton, revision) VALUES (1, 0)').run();
+    }
+    db.exec(`PRAGMA user_version = ${kind === 'provider' ? PROVIDER_SCHEMA_VERSION : SCOPED_SCHEMA_VERSION}`);
+}

package/dist/core/scopes.d.ts

@@ -0,0 +1,20 @@
+import { scopeAllowed } from '../shared/env.js';
+export { scopeAllowed };
+/** The scopes an unrestricted local terminal run presents to the document substrate. */
+export declare const SCOPE_VOCABULARY: readonly ["crtr:llm", "crtr:act", "crtr:schedule", "crtr:memory:rw:user", "crtr:memory:manage:user", "crtr:files:rw:user:."];
+/** A memory string naming the app itself (`crtr:memory:read|rw:app:<A>`, or its profile form). No grant holds one: it exists only to
+ *  narrow a run within its own space. */
+export declare function isOwnMemoryScope(scope: string, grantee: string): boolean;
+/** Reject unknown scope strings before they can silently change an allow-list. */
+export declare function validateScopes(value: unknown): string[];
+export declare function assertScope(meta: {
+    node_id: string;
+    scopes?: readonly string[] | null;
+}, scope: string): void;
+/** `holder` names who lacks the scope in prose — `node <id>` for a node's own
+ *  allow-list, `the bearer token` for a scoped API token's ceiling. */
+export declare class ScopeDeniedError extends Error {
+    readonly holder: string;
+    readonly scope: string;
+    constructor(holder: string, scope: string);
+}