@north-light/api 0.3.580 → 0.3.587

package/dist/core/layout-migrate/stores.js

@@ -0,0 +1,543 @@
+import { DatabaseSync } from 'node:sqlite';
+import { closeSync, copyFileSync, existsSync, realpathSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { LEGACY_LOCAL_PERSON } from '../canvas/legacy-person.js';
+import { profileSpace } from '../layout.js';
+import { isJunkFile, movePath, sameFile, setAside, setAsidePath } from './index.js';
+import { rewriteBodyPaths } from './stored-paths.js';
+function gitInRepo(repo, args) {
+    execFileSync('git', ['-c', `safe.directory=${repo}`, '-C', repo, ...args], { stdio: 'pipe' });
+}
+function physical(path, migration) {
+    const { root, targetRoot } = migration.map.old;
+    return resolve(root, relative(targetRoot, path));
+}
+/** Writable only for a real run's resolutions (closing a worktree row, clearing a lost transcript path). */
+function canvasDb(migration, writable = false) {
+    const { old } = migration.map;
+    const original = join(old.canvas, 'canvas.db');
+    const moved = join(old.root, 'runtime', 'canvas.db');
+    const path = existsSync(original) ? original : moved;
+    return existsSync(path) && lstatSync(path).size > 0 ? new DatabaseSync(path, { readOnly: !writable || migration.dryRun }) : null;
+}
+function nodeApps(db) {
+    return new Map(db.prepare('SELECT node_id, grantee FROM nodes').all().map(({ node_id, grantee }) => {
+        const app = grantee === LEGACY_LOCAL_PERSON ? 'terminal' : grantee.startsWith('app:') ? grantee.slice(4) : '';
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(app))
+            throw new Error(`node ${node_id} has no valid app`);
+        return [node_id, app];
+    }));
+}
+/** The profile-owned files folder in its app: where a profile's leftovers the layout has no slot for are kept. */
+function profileFiles(app, id, migration) {
+    return join(migration.map.old.targetRoot, 'apps', app, 'files', 'profiles', id);
+}
+/**
+ * Merge an old profile home into the app home. A file both hold with different
+ * bytes keeps the app home's copy; the profile's copy moves to `divert` at the
+ * same relative path.
+ */
+function mergeHome(from, to, divert, migration) {
+    if (!existsSync(from))
+        return;
+    if (!existsSync(to)) {
+        movePath(from, to, migration);
+        return;
+    }
+    const a = lstatSync(from);
+    const b = lstatSync(to);
+    if (a.isDirectory() && b.isDirectory()) {
+        for (const name of readdirSync(from))
+            mergeHome(join(from, name), join(to, name), join(divert, name), migration);
+        rmdirSync(from);
+        return;
+    }
+    if (a.isFile() && b.isFile() && sameFile(from, to)) {
+        unlinkSync(from);
+        return;
+    }
+    const target = physical(divert, migration);
+    if (!migration.dryRun)
+        movePath(from, target, migration);
+    migration.resolutions.push(`profile-home: ${to} differs from the profile's ${from}; kept the app home's copy, moved the profile's to ${target}`);
+}
+function previewHome(from, to, divert, migration) {
+    if (!existsSync(from) || !existsSync(to))
+        return;
+    const a = lstatSync(from);
+    const b = lstatSync(to);
+    if (a.isDirectory() && b.isDirectory()) {
+        for (const name of readdirSync(from))
+            previewHome(join(from, name), join(to, name), join(divert, name), migration);
+        return;
+    }
+    if (a.isFile() && b.isFile() && sameFile(from, to))
+        return;
+    migration.resolutions.push(`profile-home: ${to} differs from the profile's ${from}; kept the app home's copy, moved the profile's to ${physical(divert, migration)}`);
+}
+function bodyPath(migration, from, to) {
+    if (!migration.bodyPaths.some(([old]) => old === from))
+        migration.bodyPaths.push([from, to]);
+}
+/**
+ * A profile is its scoped-state row; the row is authoritative even when an
+ * interrupted run already removed the old profile folder. There is no profile
+ * folder in the new layout: the old folder's own path (the profile's
+ * scope_owners.root) becomes its memory folder. What else the folder holds is
+ * the profile's own files and moves to `apps/<app>/files/profiles/<id>/`; a
+ * folder with no row moves there whole, under the terminal app.
+ */
+export function profileFolders(migration) {
+    const { map } = migration;
+    const scoped = [join(map.old.scope, 'operations.db'), join(map.old.root, 'runtime', 'scope', 'operations.db')].find(existsSync);
+    const profileDb = scoped ? new DatabaseSync(scoped, { readOnly: true }) : null;
+    const profileApps = new Map();
+    try {
+        if (profileDb && profileDb.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='profiles'").get()) {
+            for (const row of profileDb.prepare('SELECT id, grantee FROM profiles').all())
+                profileApps.set(row.id, row.grantee);
+        }
+    }
+    finally {
+        profileDb?.close();
+    }
+    const targets = new Map();
+    for (const [id, grantee] of profileApps) {
+        const app = grantee == null || grantee === LEGACY_LOCAL_PERSON ? 'terminal' : grantee.startsWith('app:') ? grantee.slice(4) : '';
+        const target = profileSpace(app, id);
+        const old = join(map.old.storedScope, 'profiles', id);
+        map.retire(old, target.dir);
+        map.add(join(old, 'memory'), target.dir);
+        map.add(join(old, 'env.json'), target.env);
+        map.add(join(old, 'home'), target.home);
+        targets.set(id, { target, app });
+    }
+    const profiles = join(map.old.scope, 'profiles');
+    const result = { folders: [], junk: [], aside: [] };
+    if (!existsSync(profiles))
+        return result;
+    for (const id of readdirSync(profiles)) {
+        const source = join(profiles, id);
+        if (!lstatSync(source).isDirectory()) {
+            (isJunkFile(id) ? result.junk : result.aside).push(source);
+            continue;
+        }
+        if (id === '.locks') {
+            for (const name of readdirSync(source)) {
+                const path = join(source, name);
+                if (!(name.endsWith('.lock') && lstatSync(path).isFile()) && !isJunkFile(name))
+                    result.aside.push(path);
+            }
+            continue;
+        }
+        const stored = join(map.old.storedScope, 'profiles', id);
+        const owned = targets.get(id);
+        if (!owned) {
+            const files = profileFiles('terminal', id, migration);
+            map.add(stored, files);
+            bodyPath(migration, stored, files);
+            result.folders.push({ id, source, target: null, files, extras: [] });
+            continue;
+        }
+        const files = profileFiles(owned.app, id, migration);
+        const extras = [];
+        for (const name of readdirSync(source)) {
+            const stat = lstatSync(join(source, name));
+            const slot = name === 'memory' || name === 'home' ? stat.isDirectory()
+                : name === 'env.json' || name === 'profile.json' || name.endsWith('.lock') ? stat.isFile()
+                    : isJunkFile(name);
+            if (slot)
+                continue;
+            extras.push(name);
+            map.add(join(stored, name), join(files, name));
+            bodyPath(migration, join(stored, name), join(files, name));
+        }
+        result.folders.push({ id, source, target: owned.target, files, extras });
+    }
+    return result;
+}
+function profileLines(plan, migration) {
+    for (const folder of plan.folders) {
+        if (!folder.target)
+            migration.resolutions.push(`profile-folder: ${folder.source} has no profile row; moved whole to ${physical(folder.files, migration)}`);
+        for (const name of folder.extras)
+            migration.resolutions.push(`profile-extra: ${join(folder.source, name)} moved to ${physical(join(folder.files, name), migration)}`);
+    }
+    for (const path of plan.junk)
+        migration.resolutions.push(`profile-leftover: deleted ${path} (not profile data)`);
+    for (const path of plan.aside)
+        migration.resolutions.push(`profile-leftover: ${path} is not a profile; moved to ${setAsidePath(migration, 'profiles', basename(path))}`);
+}
+export function memoryAndProfiles(migration) {
+    const { map } = migration;
+    movePath(join(map.old.scope, 'memory'), join(map.old.root, 'user', 'memory'), migration);
+    const db = canvasDb(migration);
+    if (db) {
+        try {
+            for (const [id, app] of nodeApps(db)) {
+                const target = join(map.old.root, 'apps', app, 'memory', 'nodes', id);
+                movePath(join(map.old.root, 'apps', app, 'nodes', id, 'context', 'memory'), target, migration);
+                // A partial R23a run may have left this node at its original location.
+                movePath(join(map.old.canvas, 'nodes', id, 'context', 'memory'), target, migration);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    const plan = profileFolders(migration);
+    profileLines(plan, migration);
+    for (const { source, target, files, extras } of plan.folders) {
+        if (!target) {
+            movePath(source, physical(files, migration), migration, true);
+            continue;
+        }
+        for (const name of extras)
+            movePath(join(source, name), physical(join(files, name), migration), migration);
+        movePath(join(source, 'memory'), physical(target.dir, migration), migration);
+        movePath(join(source, 'env.json'), physical(target.env, migration), migration);
+        mergeHome(join(source, 'home'), physical(target.home, migration), join(files, 'home'), migration);
+        // Only the legacy manifest, lock files and junk remain; the scoped row replaces them.
+        for (const name of readdirSync(source))
+            unlinkSync(join(source, name));
+        rmdirSync(source);
+        migration.moved++;
+        migration.changes.push(`${source} (removed)`);
+    }
+    for (const path of plan.junk)
+        unlinkSync(path);
+    for (const path of plan.aside)
+        setAside(path, 'profiles', migration);
+    const profiles = join(map.old.scope, 'profiles');
+    if (existsSync(profiles)) {
+        const locks = join(profiles, '.locks');
+        if (existsSync(locks)) {
+            for (const name of readdirSync(locks))
+                unlinkSync(join(locks, name));
+            rmdirSync(locks);
+        }
+        rmdirSync(profiles);
+    }
+}
+/** Retain the old credential volume's session files as the rollback copy. */
+function moveSession(from, to, migration, retainSource) {
+    if (!existsSync(from))
+        return;
+    if (!lstatSync(from).isFile())
+        throw new Error(`session path is not a file: ${from}`);
+    mkdirSync(dirname(to), { recursive: true });
+    if (existsSync(to)) {
+        if (lstatSync(to).isFile() && sameFile(from, to))
+            return;
+        const aside = setAside(to, 'replaced', migration, relative(migration.map.old.root, to));
+        migration.resolutions.push(`stray-destination: ${to} predates the migration; moved it to ${aside} and put ${from} in its place`);
+    }
+    if (retainSource) {
+        const temp = join(dirname(to), `.${basename(to)}.migrating`);
+        if (existsSync(temp))
+            unlinkSync(temp);
+        copyFileSync(from, temp);
+        const fd = openSync(temp, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (!sameFile(from, temp))
+            throw new Error(`session copy verification failed: ${from}`);
+        renameSync(temp, to);
+        migration.moved++;
+        migration.changes.push(`${from} -> ${to} (source retained)`);
+        return;
+    }
+    renameSync(from, to);
+    migration.moved++;
+    migration.changes.push(`${from} -> ${to}`);
+}
+/** A transcript missing from both paths is gone: its binding keeps no path, unless it is a live node's current session. */
+function lostTranscripts(migration, db, rows) {
+    const live = new Set(db.prepare("SELECT s.transcript_path AS path FROM sessions s JOIN nodes n ON n.node_id = s.node_id WHERE s.unbound_at IS NULL AND n.status IN ('active', 'idle') AND s.transcript_path IS NOT NULL").all().map(row => row.path));
+    const clear = migration.dryRun ? null : db.prepare('UPDATE sessions SET transcript_path = NULL WHERE transcript_path = ?');
+    for (const row of rows) {
+        if (existsSync(row.source) || existsSync(physical(row.destination, migration)))
+            continue;
+        if (live.has(row.transcript_path)) {
+            migration.resolutions.push(`lost-transcript: ${row.transcript_path} is missing but is a live node's current session; kept its path`);
+            continue;
+        }
+        clear?.run(row.transcript_path);
+        migration.resolutions.push(`lost-transcript: ${row.transcript_path} is missing from both paths; cleared the session's transcript path`);
+    }
+}
+export function conversations(migration) {
+    const db = canvasDb(migration, true);
+    if (!db)
+        return;
+    try {
+        const apps = nodeApps(db);
+        // Match conversationOwner/pathFor: a transferred session's active or
+        // latest-created binding owns the file, not the last binding modified.
+        const rows = db.prepare('SELECT session_id, node_id, transcript_path FROM sessions WHERE transcript_path IS NOT NULL ORDER BY session_id, (unbound_at IS NULL) DESC, created_at DESC, rowid DESC').all();
+        const owners = new Map();
+        const paths = new Map();
+        const pathBindings = new Map();
+        for (const row of rows) {
+            if (!owners.has(row.session_id))
+                owners.set(row.session_id, row.node_id);
+            pathBindings.set(row.transcript_path, (pathBindings.get(row.transcript_path) ?? 0) + 1);
+            const ids = paths.get(row.transcript_path) ?? new Set();
+            ids.add(row.session_id);
+            paths.set(row.transcript_path, ids);
+        }
+        const seen = new Set();
+        const planned = [];
+        for (const { session_id, node_id, transcript_path } of rows) {
+            if (seen.has(transcript_path))
+                continue;
+            seen.add(transcript_path);
+            if (paths.get(transcript_path).size !== 1)
+                throw new Error(`two conversations share a transcript: ${transcript_path}`);
+            const owner = pathBindings.get(transcript_path) > 1 ? owners.get(session_id) : node_id;
+            const app = apps.get(owner);
+            if (!app)
+                throw new Error(`session belongs to unknown node: ${owner}`);
+            if (!isAbsolute(transcript_path))
+                throw new Error(`session path is not absolute: ${transcript_path}`);
+            const destination = join(migration.map.old.targetRoot, 'apps', app, 'conversations', owner, basename(transcript_path));
+            if (transcript_path === destination)
+                continue;
+            const agent = transcript_path === migration.map.old.storedAgent || transcript_path.startsWith(migration.map.old.storedAgent + sep);
+            const source = agent ? join(migration.map.old.agent, relative(migration.map.old.storedAgent, transcript_path)) : transcript_path;
+            planned.push({ transcript_path, destination, source, retain: process.platform === 'linux' && agent });
+        }
+        lostTranscripts(migration, db, planned);
+        for (const { transcript_path, destination } of planned)
+            migration.map.add(transcript_path, destination);
+        if (migration.dryRun)
+            return;
+        for (const { destination, source, retain } of planned)
+            moveSession(source, physical(destination, migration), migration, retain);
+    }
+    finally {
+        db.close();
+    }
+}
+export function repairMovedRepositories(migration) {
+    if (process.platform !== 'linux')
+        return;
+    const db = canvasDb(migration);
+    if (!db)
+        return;
+    try {
+        const rows = db.prepare('SELECT node_id, path, repo_root FROM worktrees').all();
+        const apps = nodeApps(db);
+        for (const row of rows) {
+            const repository = migration.map.mapPath(row.repo_root);
+            if (repository === row.repo_root)
+                continue;
+            const app = apps.get(row.node_id);
+            if (!app)
+                throw new Error(`worktree belongs to unknown node: ${row.node_id}`);
+            const checkout = physical(join(migration.map.old.targetRoot, 'apps', app, 'nodes', row.node_id, 'worktree'), migration);
+            if (!existsSync(checkout))
+                continue;
+            gitInRepo(physical(repository, migration), ['worktree', 'repair', checkout]);
+            const oldCheckout = row.path.startsWith(migration.map.old.storedCanvas + sep)
+                ? join(migration.map.old.canvas, relative(migration.map.old.storedCanvas, row.path)) : row.path;
+            repairSubmoduleLinks(oldCheckout, checkout, migration);
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function repairSubmoduleLinks(oldCheckout, checkout, migration) {
+    const visit = (dir) => {
+        for (const name of readdirSync(dir)) {
+            const path = join(dir, name);
+            if (name === '.git' && path !== join(checkout, '.git') && lstatSync(path).isFile()) {
+                const text = readFileSync(path, 'utf8');
+                if (!text.startsWith('gitdir: '))
+                    throw new Error(`invalid submodule git link: ${path}`);
+                const link = text.slice('gitdir: '.length).trim();
+                const current = resolve(dirname(path), link);
+                const oldLocation = join(oldCheckout, relative(checkout, path));
+                const previous = resolve(dirname(oldLocation), link);
+                const gitDir = existsSync(current) ? current : previous;
+                if (!existsSync(gitDir))
+                    throw new Error(`submodule git directory missing: ${oldLocation}`);
+                const mapped = migration?.map.mapPath(gitDir) ?? gitDir;
+                const target = migration && mapped !== gitDir ? physical(mapped, migration) : gitDir;
+                if (!existsSync(target))
+                    throw new Error(`moved submodule git directory missing: ${target}`);
+                if (current !== target)
+                    writeFileSync(path, `gitdir: ${relative(dirname(path), target)}\n`);
+                const config = join(target, 'config');
+                const textConfig = readFileSync(config, 'utf8');
+                if (!/^\s*worktree\s*=.*$/m.test(textConfig))
+                    throw new Error(`submodule has no worktree setting: ${config}`);
+                const value = JSON.stringify(relative(target, dirname(path)));
+                const updated = textConfig.replace(/^(\s*worktree\s*=).*$/m, `$1 ${value}`);
+                if (updated !== textConfig)
+                    writeFileSync(config, updated);
+            }
+            else if (name !== '.git' && lstatSync(path).isDirectory())
+                visit(path);
+        }
+    };
+    visit(checkout);
+}
+function gitOut(repo, args) {
+    return execFileSync('git', ['-c', `safe.directory=${repo}`, '-C', repo, ...args], { stdio: 'pipe', encoding: 'utf8' });
+}
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** Whether the repository still records this checkout as one of its worktrees. */
+function registered(repo, checkout) {
+    try {
+        const want = real(checkout);
+        return gitOut(repo, ['worktree', 'list', '--porcelain']).split('\n')
+            .some(line => line.startsWith('worktree ') && real(line.slice('worktree '.length)) === want);
+    }
+    catch {
+        return false;
+    }
+}
+/** `git worktree repair` can relink a checkout only while the repository still holds its admin folder. */
+function repairable(repo, checkout) {
+    if (!existsSync(repo))
+        return false;
+    try {
+        const link = readFileSync(join(checkout, '.git'), 'utf8');
+        if (!link.startsWith('gitdir: '))
+            return false;
+        return existsSync(resolve(checkout, link.slice('gitdir: '.length).trim()));
+    }
+    catch {
+        return false;
+    }
+}
+function closeRow(db, row, migration) {
+    if (migration.dryRun || (row.state !== 'open' && row.cleanup_state === 'complete'))
+        return;
+    db.prepare("UPDATE worktrees SET state = CASE WHEN state = 'open' THEN 'closed' ELSE state END, cleanup_state = 'complete', closed_at = COALESCE(closed_at, ?) WHERE node_id = ?")
+        .run(new Date().toISOString(), row.node_id);
+}
+export function worktrees(migration) {
+    const db = canvasDb(migration, true);
+    if (!db)
+        return;
+    try {
+        const apps = nodeApps(db);
+        const rows = db.prepare('SELECT node_id, state, cleanup_state, path, repo_root FROM worktrees').all();
+        for (const row of rows) {
+            const app = apps.get(row.node_id);
+            if (!app)
+                throw new Error(`worktree belongs to unknown node: ${row.node_id}`);
+            if (!isAbsolute(row.path))
+                throw new Error(`worktree path is not absolute: ${row.path}`);
+            const destination = join(migration.map.old.targetRoot, 'apps', app, 'nodes', row.node_id, 'worktree');
+            if (row.path === destination)
+                continue;
+            const from = row.path === migration.map.old.storedCanvas || row.path.startsWith(migration.map.old.storedCanvas + sep)
+                ? join(migration.map.old.canvas, relative(migration.map.old.storedCanvas, row.path)) : row.path;
+            const to = physical(destination, migration);
+            if (!existsSync(from)) {
+                migration.map.add(row.path, destination);
+                if (!existsSync(to)) {
+                    if (!(row.state !== 'open' && row.cleanup_state === 'complete')) {
+                        closeRow(db, row, migration);
+                        migration.resolutions.push(`missing-worktree: ${row.path} (node ${row.node_id}) is gone; closed its row`);
+                    }
+                }
+                else if (!migration.dryRun && existsSync(row.repo_root)) {
+                    gitInRepo(row.repo_root, ['worktree', 'repair', to]);
+                    repairSubmoduleLinks(from, to);
+                }
+                continue;
+            }
+            if (!registered(row.repo_root, from)) {
+                // Only an open row is still in use; a closed row's leftover folder is set aside.
+                if (row.state === 'open' && repairable(row.repo_root, from)) {
+                    migration.resolutions.push(`unregistered-worktree: ${row.path} (node ${row.node_id}) is not registered in ${row.repo_root}; relinked it with git worktree repair`);
+                    if (!migration.dryRun)
+                        gitInRepo(row.repo_root, ['worktree', 'repair', from]);
+                }
+                else {
+                    const aside = setAsidePath(migration, 'worktrees', basename(from));
+                    migration.resolutions.push(`unregistered-worktree: ${row.path} (node ${row.node_id}${row.state === 'open' ? '' : `, ${row.state}`}) is not a worktree of ${existsSync(row.repo_root) ? row.repo_root : `the missing repository ${row.repo_root}`}; ${row.state === 'open' ? 'closed its row and ' : ''}moved the folder to ${aside}`);
+                    // `records` mapped this path into the node's folder; it goes aside instead.
+                    migration.map.redirect(row.path, join(migration.map.old.targetRoot, relative(migration.map.old.root, aside)));
+                    if (!migration.dryRun) {
+                        setAside(from, 'worktrees', migration);
+                        closeRow(db, row, migration);
+                    }
+                    continue;
+                }
+            }
+            migration.map.add(row.path, destination);
+            if (existsSync(to)) {
+                const aside = setAsidePath(migration, 'replaced', relative(migration.map.old.root, to));
+                migration.resolutions.push(`stray-destination: ${to} predates the migration; moved it to ${aside} and put the worktree ${from} in its place`);
+                if (!migration.dryRun)
+                    setAside(to, 'replaced', migration, relative(migration.map.old.root, to));
+            }
+            if (migration.dryRun)
+                continue;
+            mkdirSync(dirname(to), { recursive: true });
+            // Run before the hosted work directory is moved so git can still find its
+            // common directory. `git worktree move` repairs the repository's records.
+            try {
+                gitInRepo(row.repo_root, ['worktree', 'move', from, to]);
+            }
+            catch (error) {
+                const stderr = String(error.stderr ?? '');
+                if (!stderr.includes('submodule'))
+                    throw error;
+                renameSync(from, to);
+                gitInRepo(row.repo_root, ['worktree', 'repair', to]);
+            }
+            repairSubmoduleLinks(from, to);
+            migration.moved++;
+            migration.changes.push(`${from} -> ${to} (git worktree move)`);
+        }
+    }
+    finally {
+        db.close();
+    }
+    if (!migration.dryRun)
+        pruneOldNodeFolders(migration);
+}
+/** `records` keeps a node folder while its worktree is still inside; once the worktree moved, the folder is empty. */
+function pruneOldNodeFolders(migration) {
+    const nodes = join(migration.map.old.canvas, 'nodes');
+    if (!existsSync(nodes))
+        return;
+    for (const id of readdirSync(nodes)) {
+        const path = join(nodes, id);
+        if (lstatSync(path).isDirectory() && readdirSync(path).length === 0)
+            rmdirSync(path);
+    }
+    if (readdirSync(nodes).length === 0)
+        rmdirSync(nodes);
+}
+/** Every resolution the real run would make, computed without changing anything. */
+export function previewStores(migration) {
+    worktrees(migration);
+    const plan = profileFolders(migration);
+    profileLines(plan, migration);
+    for (const { source, target, files } of plan.folders) {
+        if (target)
+            previewHome(join(source, 'home'), physical(target.home, migration), join(files, 'home'), migration);
+    }
+    conversations(migration);
+    rewriteBodyPaths(migration);
+}

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

@@ -0,0 +1,12 @@
+import type { CanvasDb } from '../canvas/db.js';
+/** The Northlight team's principal in the directory's `relations` rows. A payer it holds is house-paid: its rows carry no account and bill $0. */
+export declare const NORTHLIGHT_TEAM = "team:apofkzuloox7";
+export interface BillingAccount {
+    /** The principal to invoice, or null when the payer is house-paid or has no holder. */
+    account: string | null;
+    /** Whether a row for this payer can be billed: false for a house-paid payer and for one with no holder. */
+    billable: boolean;
+}
+export declare function billingAccountOf(db: CanvasDb, payer: string): Promise<BillingAccount>;
+/** The `app:<id>` payers whose holder (`ledger_holder`) is one of `holders` (a `user:<id>` or a `team:<id>`): the apps whose spend is that holder's. */
+export declare function appsHeldBy(db: CanvasDb, holders: readonly string[]): Promise<string[]>;

package/dist/core/ledger/account.js

@@ -0,0 +1,13 @@
+// Who Northlight invoices for a payer: the holder `ledger_holder` finds (schema delta 007), or nobody when the Northlight team holds it.
+/** The Northlight team's principal in the directory's `relations` rows. A payer it holds is house-paid: its rows carry no account and bill $0. */
+export const NORTHLIGHT_TEAM = 'team:apofkzuloox7';
+export async function billingAccountOf(db, payer) {
+    const holder = (await db.prepare('SELECT ledger_holder(?) AS holder').get(payer)).holder;
+    return holder === null || holder === NORTHLIGHT_TEAM ? { account: null, billable: false } : { account: holder, billable: true };
+}
+/** The `app:<id>` payers whose holder (`ledger_holder`) is one of `holders` (a `user:<id>` or a `team:<id>`): the apps whose spend is that holder's. */
+export async function appsHeldBy(db, holders) {
+    const rows = await db.prepare(`SELECT 'app:' || r.resource_id AS app FROM (SELECT DISTINCT resource_id FROM relations WHERE resource_type = 'app' AND relation = 'admin') r
+    WHERE ledger_holder('app:' || r.resource_id) = ANY(?::text[]) ORDER BY 1`).all(holders);
+    return rows.map((row) => row.app);
+}

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

@@ -0,0 +1,16 @@
+import type { Charge, ChargeInput } from './types.js';
+/** The id of a tool charge: the receipt-level idempotency key, so two providers' receipt ids never collide. */
+export declare const receiptChargeId: (provider: string, receiptId: string) => string;
+export interface WriteResult {
+    /** False when `id` already existed: a repeat delivery adds nothing, to the row or the rollup. */
+    written: boolean;
+    id: string;
+    /** The id of the take row written beside it, when `CRTR_LEDGER_TAKE_PCT` is above 0. */
+    takeId: string | null;
+}
+/** Write one charge row; the `charges` trigger (schema delta 007) adds it to `charge_totals`. A refused row is stored with
+ *  usd 0 and never rolled up; a take row (written only while `CRTR_LEDGER_TAKE_PCT` > 0) is stored and never rolled up. Inside a
+ *  caller's `withCanvasWrite` it joins that transaction. */
+export declare function writeCharge(input: ChargeInput): Promise<WriteResult>;
+/** A stored row as the `Charge` shape (jsonb arrives as text from `charges`, as an object from a moved chunk). */
+export declare function chargeOf(row: Record<string, unknown>): Charge;

package/dist/core/ledger/charges.js

@@ -0,0 +1,43 @@
+// Writing a charge and its rollup row in one transaction (design-ledger, "Data model").
+import { randomUUID } from 'node:crypto';
+import { withCanvasWrite } from '../canvas/db.js';
+import { takePercent } from './rates.js';
+import { usageMonth } from './months.js';
+/** The id of a tool charge: the receipt-level idempotency key, so two providers' receipt ids never collide. */
+export const receiptChargeId = (provider, receiptId) => `receipt:${provider}:${receiptId}`;
+const COLUMNS = 'id, request, at, month, kind, what, units, usd, payer, funding, sub, grantee, node, run, provider, caused_by, vendor_ref, refused, account, billed_usd, usd_rolled_by_trigger';
+const PLACEHOLDERS = '?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?, ?, true';
+/** Write one charge row; the `charges` trigger (schema delta 007) adds it to `charge_totals`. A refused row is stored with
+ *  usd 0 and never rolled up; a take row (written only while `CRTR_LEDGER_TAKE_PCT` > 0) is stored and never rolled up. Inside a
+ *  caller's `withCanvasWrite` it joins that transaction. */
+export async function writeCharge(input) {
+    const at = input.at ?? new Date();
+    const refused = input.refused ?? null;
+    const id = input.id ?? randomUUID();
+    const month = usageMonth(at);
+    const usd = refused ? 0 : input.usd;
+    const pct = takePercent();
+    return await withCanvasWrite(async (db) => {
+        const row = (rowId, kind, what, rowUsd, funding) => [
+            rowId, input.request ?? null, at.toISOString(), month, kind, what, input.units == null ? null : JSON.stringify(input.units), rowUsd,
+            input.payer, funding, input.sub ?? null, input.grantee, input.node ?? null, input.run ?? null, input.provider ?? null,
+            input.causedBy ?? null, input.vendorRef ?? null, refused === null ? null : JSON.stringify(refused), input.account ?? null, input.billedUsd ?? null
+        ];
+        const inserted = await db.prepare(`INSERT INTO charges (${COLUMNS}) VALUES (${PLACEHOLDERS}) ON CONFLICT (id) DO NOTHING`)
+            .run(...row(id, input.kind, input.what, usd, input.funding));
+        if (inserted.changes === 0)
+            return { written: false, id, takeId: null };
+        let takeId = null;
+        if (pct > 0 && refused === null && (input.kind === 'model' || input.kind === 'tool') && usd !== null && usd > 0) {
+            takeId = `take:${id}`;
+            await db.prepare(`INSERT INTO charges (${COLUMNS}) VALUES (${PLACEHOLDERS}) ON CONFLICT (id) DO NOTHING`)
+                .run(...row(takeId, 'take', input.what, usd * pct / 100, 'take'));
+        }
+        return { written: true, id, takeId };
+    });
+}
+/** A stored row as the `Charge` shape (jsonb arrives as text from `charges`, as an object from a moved chunk). */
+export function chargeOf(row) {
+    const json = (value) => typeof value === 'string' ? JSON.parse(value) : typeof value === 'object' ? value : null;
+    return { ...row, units: json(row['units']), refused: json(row['refused']) };
+}