openworkgraph 0.2.12

package/dist/operations/daemon.js

@@ -0,0 +1,159 @@
+import { createService } from '../service.js';
+import { listenerInfo } from '../network.js';
+import { localControl } from '../local-control.js';
+import { acquireOperationsLock } from './lifecycle.js';
+import { OperationsLog } from './logs.js';
+import { waitForBackups, clearStaleResourceLeases } from './backups.js';
+import { localCapacity } from './capacity.js';
+import { registerLocalPlugin } from './plugins.js';
+import { fileURLToPath } from 'node:url';
+import { isGlobalNpmInstallation, startWebUpdate } from './update.js';
+export function activeRunCount(db) {
+    return Number(db.prepare("SELECT count(*) AS n FROM runs WHERE status NOT IN ('accepted','queued','paused_restore','succeeded','failed','cancelled','interrupted')").get().n);
+}
+/** Public host wrapper: the lock is acquired BEFORE opening SQLite or listeners. */
+export async function serveManaged(dataDir, host, port, onStopped) {
+    const lock = await acquireOperationsLock(dataDir), log = new OperationsLog(lock.root);
+    let service;
+    const cliPath = fileURLToPath(new URL('../cli.js', import.meta.url));
+    const npmInstallation = isGlobalNpmInstallation(cliPath);
+    try {
+        service = createService(lock.root, {
+            npmInstallation: () => npmInstallation,
+            updateRuntime: async (onExit) => {
+                if (state !== 'running')
+                    throw new Error('Runtime is stopping.');
+                await startWebUpdate(cliPath, undefined, onExit);
+            },
+        });
+    }
+    catch (error) {
+        try {
+            await log.append('startup_failed');
+        }
+        finally {
+            await lock.release();
+        }
+        throw error;
+    }
+    let state = 'running';
+    let stopping = false;
+    const drains = new Set();
+    let closing;
+    let recoveryAttempted = false;
+    const onSignal = () => { void stop(false).catch(() => log.append('shutdown_failed')); };
+    const removeSignals = () => { process.removeListener('SIGINT', onSignal); process.removeListener('SIGTERM', onSignal); };
+    const status = () => ({ state, activeRuns: activeRunCount(service.db), listenHost: service.server.address().address, ...listenerInfo(service.server.address(), service.info.serviceId, service.instanceId) });
+    async function stop(interrupt) {
+        // Escalation remains available while an earlier drain waits indefinitely.
+        if (stopping && (!interrupt || state === 'interrupting'))
+            return;
+        state = interrupt ? 'interrupting' : 'draining';
+        stopping = true;
+        service.runtime.stopRuns();
+        await log.append(interrupt ? 'interrupting' : 'draining');
+        const drain = (async () => {
+            // Flush the command acknowledgment before any transport is closed.
+            await new Promise(resolve => setTimeout(resolve, 30));
+            await Promise.all([waitForBackups(service.db), service.runtime.drain({ interrupt: true })]);
+        })();
+        drains.add(drain);
+        void drain.then(async () => {
+            drains.delete(drain);
+            if (drains.size || closing || state === 'failed')
+                return;
+            closing = (async () => {
+                await service.close();
+                removeSignals();
+                try {
+                    await log.append('stopped');
+                }
+                finally {
+                    await lock.release();
+                    await onStopped?.();
+                }
+            })();
+            try {
+                await closing;
+            }
+            catch {
+                state = 'failed';
+                await log.append('shutdown_failed');
+            }
+        }, async () => {
+            drains.delete(drain);
+            state = 'failed';
+            await log.append('shutdown_failed');
+            // Keep ownership while backend termination is uncertain.
+        }).catch(() => { });
+    }
+    try {
+        clearStaleResourceLeases(service.db, lock);
+        await service.api.backups.recoverCreating(lock);
+        await new Promise((done, reject) => { service.server.once('error', reject); service.server.listen(port, host, done); });
+        // Own the kernel lock before transferring scheduler epochs. Runtime.start
+        // resets acceptingRuns after a normal shutdown and starts its dispatch timer.
+        recoveryAttempted = true;
+        await service.runtime.recover();
+        await lock.publish(service.info.serviceId, async (command, argument) => {
+            if (command === 'status')
+                return status();
+            if (command === 'capacity')
+                return localCapacity(service.db, argument);
+            if (command === 'plugin-register')
+                return registerLocalPlugin(service.db, service.info.serviceId, argument ?? '');
+            if (command === 'sessions')
+                return service.auth.list();
+            if (command === 'resolve-client')
+                return service.auth.resolveClientPairing(argument ?? '');
+            if (command === 'pair-short') {
+                const request = JSON.parse(argument ?? '{}');
+                return service.auth.approveClientPairing(request.code, request.clientCode);
+            }
+            if (command === 'revoke-session') {
+                service.auth.revokeLocal(argument ?? '');
+                return { revoked: argument, acceptedTasksUnaffected: true };
+            }
+            if (command === 'pair-code' || command === 'pair-client') {
+                const control = localControl(lock.root);
+                try {
+                    return await control.pairingCode(command === 'pair-code' ? argument ?? '' : '', command === 'pair-client' ? argument ?? '' : undefined);
+                }
+                finally {
+                    control.close();
+                }
+            }
+            if (command === 'backup-create') {
+                if (state !== 'running')
+                    throw new Error('Service is draining; new backups are unavailable');
+                const result = await service.api.backups.create(argument);
+                await log.append('backup_ready');
+                return result;
+            }
+            await stop(command === 'interrupt-and-stop');
+            return { state, serviceId: service.info.serviceId, instanceId: service.instanceId };
+        }, service.instanceId);
+        await log.append('started');
+    }
+    catch (error) {
+        removeSignals();
+        // Before epoch transfer there is no backend owned by this startup. Draining
+        // old active rows here would wait forever and could mutate the previous Run.
+        // Once recovery was attempted, retain the normal conservative drain path.
+        if (!recoveryAttempted)
+            await service.abortStartup();
+        else
+            await service.close();
+        try {
+            await log.append('startup_failed');
+        }
+        finally {
+            await lock.release();
+        }
+        throw error;
+    }
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    return { service, lock, status, stop };
+}
+//# sourceMappingURL=daemon.js.map

package/dist/operations/files.d.ts

@@ -0,0 +1,12 @@
+export declare const digest: (data: Uint8Array | string) => string;
+export declare const identifier: (value: string) => string;
+/** macOS exposes OS-owned /var and /tmp aliases. Normalize only these fixed
+ * aliases; arbitrary user-created symlink parents are still forbidden. */
+export declare function normalizeSystemPath(path: string): string;
+/** Check EVERY existing component; never follow a user supplied parent symlink. */
+export declare function safePath(path: string, missing?: boolean): Promise<string>;
+export declare function privateDir(path: string): Promise<string>;
+export declare function readSafe(path: string, max?: number): Promise<Buffer>;
+export declare function syncDir(path: string): Promise<void>;
+export declare function writeNew(path: string, data: Uint8Array | string, mode?: number): Promise<void>;
+export declare function atomicJson(path: string, data: unknown): Promise<void>;

package/dist/operations/files.js

@@ -0,0 +1,84 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, rename } from 'node:fs/promises';
+import { dirname, parse, resolve, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+export const digest = (data) => createHash('sha256').update(data).digest('hex');
+export const identifier = (value) => {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(value))
+        throw new Error('Invalid operations identifier');
+    return value;
+};
+/** macOS exposes OS-owned /var and /tmp aliases. Normalize only these fixed
+ * aliases; arbitrary user-created symlink parents are still forbidden. */
+export function normalizeSystemPath(path) {
+    const absolute = resolve(path);
+    return process.platform === 'darwin' && /^[/](var|tmp)([/]|$)/.test(absolute) ? '/private' + absolute : absolute;
+}
+/** Check EVERY existing component; never follow a user supplied parent symlink. */
+export async function safePath(path, missing = false) {
+    const absolute = normalizeSystemPath(path);
+    let current = parse(absolute).root;
+    for (const part of absolute.slice(current.length).split(/[\\/]/).filter(Boolean)) {
+        current = join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error('Operations paths cannot contain symlinks');
+        }
+        catch (error) {
+            if (!missing || error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return absolute;
+}
+export async function privateDir(path) {
+    path = await safePath(path, true);
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    return realpath(path);
+}
+export async function readSafe(path, max = 512 * 1024 * 1024) {
+    path = await safePath(path);
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > max)
+            throw new Error('Invalid or oversized operations file');
+        return await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function syncDir(path) {
+    // Windows does not support opening directories through fs.open. File flushes
+    // still apply; crash durability of rename must be verified on that platform.
+    if (process.platform === 'win32')
+        return;
+    const file = await open(path, constants.O_RDONLY);
+    try {
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function writeNew(path, data, mode = 0o400) {
+    path = await safePath(path, true);
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(data);
+        await file.sync();
+        await file.chmod(mode);
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function atomicJson(path, data) {
+    path = await safePath(path, true);
+    const temporary = path + '.' + randomUUID() + '.tmp';
+    await writeNew(temporary, JSON.stringify(data), 0o600);
+    await rename(temporary, path);
+    await syncDir(dirname(path));
+}
+//# sourceMappingURL=files.js.map

package/dist/operations/lifecycle.d.ts

@@ -0,0 +1,28 @@
+export interface InstanceRecord {
+    instanceId: string;
+    serviceId: string;
+    token: string;
+    port: number;
+    pid: number;
+    startedAt: string;
+}
+export type ManagementCommand = 'status' | 'stop' | 'interrupt-and-stop' | 'pair-code' | 'pair-client' | 'resolve-client' | 'pair-short' | 'sessions' | 'revoke-session' | 'backup-create' | 'capacity' | 'plugin-register';
+export type ManagementHandler = (command: ManagementCommand, argument?: string) => Promise<unknown>;
+export declare function rootPath(dataDir?: string): string;
+export declare function managementPort(root: string): number;
+/** The kernel-held listener is the lifetime/maintenance lock. No PID killing,
+ * stale-file deletion, expiry heuristics, or check-then-create races. Hash port
+ * collisions fail closed. Only the loopback address is ever used. */
+export declare function acquireOperationsLock(dataDir?: string): Promise<{
+    root: string;
+    record: InstanceRecord;
+    readonly held: boolean;
+    publish(serviceId: string, next: ManagementHandler, instanceId?: string): Promise<void>;
+    release(): Promise<void>;
+}>;
+export type OperationsLock = Awaited<ReturnType<typeof acquireOperationsLock>>;
+export declare function readInstance(dataDir?: string): Promise<InstanceRecord>;
+export declare function requestInstance(record: InstanceRecord, command: ManagementCommand, argument?: string): Promise<unknown>;
+export declare function manage(dataDir: string | undefined, command: ManagementCommand, argument?: string): Promise<unknown>;
+export declare function startBackground(cliPath: string, args: string[]): Promise<unknown>;
+export declare function waitUntilStopped(record: InstanceRecord, timeoutMs?: number): Promise<void>;

package/dist/operations/lifecycle.js

@@ -0,0 +1,155 @@
+import { createServer, createConnection } from 'node:net';
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { atomicJson, digest, privateDir, readSafe, safePath, normalizeSystemPath } from './files.js';
+export function rootPath(dataDir) { return normalizeSystemPath(dataDir ?? join(homedir(), '.openworkgraph')); }
+export function managementPort(root) { return 20000 + Number.parseInt(digest(root).slice(0, 8), 16) % 40000; }
+const equal = (a, b) => typeof a === 'string' && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/** The kernel-held listener is the lifetime/maintenance lock. No PID killing,
+ * stale-file deletion, expiry heuristics, or check-then-create races. Hash port
+ * collisions fail closed. Only the loopback address is ever used. */
+export async function acquireOperationsLock(dataDir) {
+    const root = await privateDir(rootPath(dataDir));
+    const port = managementPort(root);
+    const record = { instanceId: randomUUID(), serviceId: '', token: randomBytes(32).toString('hex'), port, pid: process.pid, startedAt: new Date().toISOString() };
+    let handler;
+    let released = false;
+    const sockets = new Set();
+    const server = createServer(socket => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+        socket.on('error', () => { });
+        socket.setTimeout(2000, () => socket.destroy());
+        let input = '';
+        let handled = false;
+        socket.on('data', chunk => {
+            if (handled)
+                return;
+            input += chunk.toString('utf8');
+            if (Buffer.byteLength(input) > 2 * 1024 * 1024) {
+                socket.destroy();
+                return;
+            }
+            if (!input.includes('\n'))
+                return;
+            handled = true;
+            void (async () => {
+                const request = JSON.parse(input.slice(0, input.indexOf('\n')));
+                if (!handler || !equal(request.token, record.token) || request.instanceId !== record.instanceId || request.serviceId !== record.serviceId)
+                    throw new Error('Unauthenticated instance');
+                if (!['status', 'stop', 'interrupt-and-stop', 'pair-code', 'pair-client', 'resolve-client', 'pair-short', 'sessions', 'revoke-session', 'backup-create', 'capacity', 'plugin-register'].includes(String(request.command)))
+                    throw new Error('Unsupported local command');
+                if (request.argument !== undefined && typeof request.argument !== 'string')
+                    throw new Error('Invalid argument');
+                socket.setTimeout(0);
+                const result = await handler(request.command, request.argument);
+                socket.end(JSON.stringify({ ok: true, instanceId: record.instanceId, serviceId: record.serviceId, result }) + '\n');
+            })().catch(() => socket.end(JSON.stringify({ ok: false, error: 'Management request refused' }) + '\n'));
+        });
+    });
+    await new Promise((done, reject) => {
+        server.once('error', reject);
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => { server.removeListener('error', reject); done(); });
+    }).catch(error => { throw new Error('Data directory is running or in maintenance, or its management port is occupied', { cause: error }); });
+    return {
+        root, record, get held() { return !released && server.listening; },
+        async publish(serviceId, next, instanceId = record.instanceId) {
+            record.serviceId = serviceId;
+            record.instanceId = instanceId;
+            handler = next;
+            await atomicJson(join(root, 'operations-instance.json'), record);
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            handler = undefined;
+            for (const socket of sockets)
+                socket.destroy();
+            await new Promise((done, reject) => server.close(error => error ? reject(error) : done()));
+            // Stale metadata is harmless. Retaining it avoids deleting a successor's record.
+        },
+    };
+}
+export async function readInstance(dataDir) {
+    const root = await realpath(await safePath(rootPath(dataDir)));
+    const record = JSON.parse((await readSafe(join(root, 'operations-instance.json'), 8192)).toString());
+    if (record.port !== managementPort(root) || !/^[a-f0-9]{64}$/.test(record.token))
+        throw new Error('Invalid instance metadata');
+    return record;
+}
+export async function requestInstance(record, command, argument) {
+    return new Promise((done, reject) => {
+        const socket = createConnection({ host: '127.0.0.1', port: record.port });
+        let input = '';
+        let complete = false;
+        socket.setTimeout(command === 'backup-create' ? 300000 : 3000, () => socket.destroy(new Error('Local management timed out')));
+        socket.once('error', reject);
+        socket.once('connect', () => socket.write(JSON.stringify({ ...record, command, argument }) + '\n'));
+        socket.on('data', chunk => {
+            input += chunk.toString();
+            if (input.length > 65536) {
+                socket.destroy(new Error('Oversized management response'));
+                return;
+            }
+            if (!input.includes('\n') || complete)
+                return;
+            complete = true;
+            try {
+                const response = JSON.parse(input.slice(0, input.indexOf('\n')));
+                if (!response.ok || response.serviceId !== record.serviceId || response.instanceId !== record.instanceId)
+                    throw new Error('Management identity/token mismatch');
+                done(response.result);
+            }
+            catch (error) {
+                reject(error);
+            }
+            finally {
+                socket.destroy();
+            }
+        });
+        socket.once('close', () => { if (!complete)
+            reject(new Error('Service not running or management unavailable')); });
+    });
+}
+export async function manage(dataDir, command, argument) { return requestInstance(await readInstance(dataDir), command, argument); }
+export async function startBackground(cliPath, args) {
+    // IPC carries the startup acknowledgment; stdio never inherits a terminal or
+    // writes unbounded backend output. The daemon emits allowlisted lifecycle logs.
+    const child = spawn(process.execPath, [cliPath, 'serve', ...args], { detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'], env: { ...process.env, OPENWORKGRAPH_BACKGROUND: '1' } });
+    return new Promise((done, reject) => {
+        const timeout = setTimeout(() => { child.disconnect(); child.unref(); reject(new Error('Startup acknowledgment timed out; inspect status before retrying')); }, 15000);
+        child.once('error', error => { clearTimeout(timeout); reject(error); });
+        child.once('exit', code => { clearTimeout(timeout); reject(new Error('Background startup failed (' + code + ')')); });
+        child.once('message', message => {
+            clearTimeout(timeout);
+            child.disconnect();
+            child.unref();
+            const result = message;
+            if (!result.ok)
+                reject(new Error('Background startup refused: ' + (result.error ?? 'inspect status and logs')));
+            else
+                done(result.status);
+        });
+    });
+}
+export async function waitUntilStopped(record, timeoutMs = 10000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            await requestInstance(record, 'status');
+        }
+        catch (error) {
+            // An auth failure or closing DB is NOT proof of kernel-lock release.
+            if (error.code === 'ECONNREFUSED')
+                return;
+        }
+        await delay(50);
+    }
+    throw new Error('Service is still draining; interactions/cancel remain available');
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/operations/local-admin.d.ts

@@ -0,0 +1,6 @@
+import { Backups } from './backups.js';
+/** Opens only an EXISTING data directory. No migration or initialization of DB
+ * precedes restore verification. The entire local operation excludes serve. */
+export declare function withOfflineBackups<T>(dataDir: string | undefined, work: (backups: Backups) => Promise<T>): Promise<T>;
+/** Read-only catalogue/downloads are allowed while the owning service runs. */
+export declare function withReadBackups<T>(dataDir: string | undefined, work: (backups: Backups) => Promise<T>): Promise<T>;

package/dist/operations/local-admin.js

@@ -0,0 +1,38 @@
+import { DatabaseSync } from 'node:sqlite';
+import { join } from 'node:path';
+import { initializeDirectories } from '../directories.js';
+import { Backups } from './backups.js';
+import { acquireOperationsLock, rootPath } from './lifecycle.js';
+import { safePath } from './files.js';
+/** Opens only an EXISTING data directory. No migration or initialization of DB
+ * precedes restore verification. The entire local operation excludes serve. */
+export async function withOfflineBackups(dataDir, work) {
+    const lock = await acquireOperationsLock(dataDir);
+    try {
+        await safePath(join(lock.root, 'service.sqlite'));
+        const directories = initializeDirectories(lock.root);
+        const db = new DatabaseSync(directories.database, { allowExtension: false, timeout: 5000 });
+        try {
+            return await work(new Backups(db, directories, { maintenance: lock }));
+        }
+        finally {
+            db.close();
+        }
+    }
+    finally {
+        await lock.release();
+    }
+}
+/** Read-only catalogue/downloads are allowed while the owning service runs. */
+export async function withReadBackups(dataDir, work) {
+    const root = await safePath(rootPath(dataDir)), database = await safePath(join(root, 'service.sqlite'));
+    const directories = { root, database, config: join(root, 'config'), blobs: join(root, 'blobs'), staging: join(root, 'staging'), runs: join(root, 'runs'), backups: join(root, 'backups') };
+    const db = new DatabaseSync(database, { readOnly: true, allowExtension: false, timeout: 5000 });
+    try {
+        return await work(new Backups(db, directories));
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=local-admin.js.map

package/dist/operations/logs.d.ts

@@ -0,0 +1,16 @@
+declare const events: readonly ['started', 'draining', 'interrupting', 'stopped', 'startup_failed', 'shutdown_failed', 'backup_ready', 'backup_failed', 'restored'];
+type LogEvent = typeof events[number];
+interface Entry {
+    time: string;
+    event: LogEvent;
+}
+/** Allowlist, not regex redaction: never persist prompts, paths, tokens, backend
+ * stdout or arbitrary errors. Both entry count and read size are bounded. */
+export declare class OperationsLog {
+    readonly root: string;
+    private pending;
+    constructor(root: string);
+    read(): Promise<Entry[]>;
+    append(event: LogEvent): Promise<void>;
+}
+export {};

package/dist/operations/logs.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { atomicJson, readSafe } from './files.js';
+const events = ['started', 'draining', 'interrupting', 'stopped', 'startup_failed', 'shutdown_failed', 'backup_ready', 'backup_failed', 'restored'];
+/** Allowlist, not regex redaction: never persist prompts, paths, tokens, backend
+ * stdout or arbitrary errors. Both entry count and read size are bounded. */
+export class OperationsLog {
+    root;
+    pending = Promise.resolve();
+    constructor(root) {
+        this.root = root;
+    }
+    async read() {
+        try {
+            const data = JSON.parse((await readSafe(join(this.root, 'operations-log.json'), 65536)).toString());
+            if (!Array.isArray(data))
+                return [];
+            return data.filter((v) => !!v && typeof v === 'object' && events.includes(v.event) && typeof v.time === 'string' && /^\d{4}-\d{2}-\d{2}T[0-9:.]+Z$/.test(v.time)).slice(-256).map(v => ({ time: v.time, event: v.event }));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    append(event) {
+        if (!events.includes(event))
+            return Promise.reject(new Error('Unknown lifecycle event'));
+        const task = this.pending.then(async () => {
+            const entries = await this.read();
+            entries.push({ time: new Date().toISOString(), event });
+            await atomicJson(join(this.root, 'operations-log.json'), entries.slice(-256));
+        });
+        this.pending = task.catch(() => { });
+        return task;
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/operations/plugins.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Trusted local declarative registration only: no import(), executable files,
+ * dependency installation, or node migrations are implied by registration. */
+export declare function registerLocalPlugin(db: DatabaseSync, serviceId: string, serialized: string): {
+    registered: boolean;
+    typeId: string;
+    pluginId: string;
+    version: string;
+    schemaVersion: number;
+};

package/dist/operations/plugins.js

@@ -0,0 +1,11 @@
+import { Graphs } from '../graphs.js';
+import { PluginManagement } from '../plugin-management.js';
+/** Trusted local declarative registration only: no import(), executable files,
+ * dependency installation, or node migrations are implied by registration. */
+export function registerLocalPlugin(db, serviceId, serialized) {
+    if (Buffer.byteLength(serialized) > 1024 * 1024)
+        throw new Error('Plugin manifest exceeds 1 MiB');
+    const contract = new PluginManagement(new Graphs(db, serviceId)).registerTrustedLocal(JSON.parse(serialized));
+    return { registered: true, typeId: contract.typeId, pluginId: contract.pluginId, version: contract.version, schemaVersion: contract.schemaVersion };
+}
+//# sourceMappingURL=plugins.js.map

package/dist/operations/snapshot-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/operations/snapshot-worker.js

@@ -0,0 +1,18 @@
+import { DatabaseSync } from 'node:sqlite';
+import { parentPort, workerData } from 'node:worker_threads';
+// Dedicated worker: a large VACUUM must not block HTTP interactions/cancellation.
+const { source, destination } = workerData;
+try {
+    const db = new DatabaseSync(source, { readOnly: true, allowExtension: false, timeout: 5000 });
+    try {
+        db.prepare('VACUUM INTO ?').run(destination);
+    }
+    finally {
+        db.close();
+    }
+    parentPort.postMessage({ ok: true });
+}
+catch {
+    parentPort.postMessage({ ok: false });
+}
+//# sourceMappingURL=snapshot-worker.js.map

package/dist/operations/snapshot.d.ts

@@ -0,0 +1 @@
+export declare function createDatabaseSnapshot(source: string, destination: string): Promise<void>;

package/dist/operations/snapshot.js

@@ -0,0 +1,14 @@
+import { Worker } from 'node:worker_threads';
+import { safePath } from './files.js';
+export async function createDatabaseSnapshot(source, destination) {
+    await safePath(source);
+    await safePath(destination, true);
+    const worker = new Worker(new URL('./snapshot-worker.js', import.meta.url), { workerData: { source, destination } });
+    await new Promise((done, reject) => {
+        let ok = false;
+        worker.on('message', result => { ok = result?.ok === true; });
+        worker.once('error', reject);
+        worker.once('exit', code => code === 0 && ok ? done() : reject(new Error('SQLite snapshot worker failed')));
+    });
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/operations/update.d.ts

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+import { readInstance, requestInstance, startBackground, waitUntilStopped } from './lifecycle.js';
+/** Compare the running package against npm's actual global package location. */
+export declare function isGlobalNpmInstallation(cliPath: string, spawnProcess?: SpawnProcess): Promise<boolean>;
+/** The updater must outlive the Runtime that it stops. */
+export declare function startWebUpdate(cliPath: string, spawnProcess?: SpawnProcess, onExit?: () => void): Promise<void>;
+type SpawnProcess = typeof spawn;
+type NpmInvocation = {
+    command: string;
+    args: string[];
+};
+export declare function compareSemVer(left: string, right: string): number;
+export declare function npmInstallInvocation(platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv): NpmInvocation;
+export declare function npmVersionInvocation(platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv): NpmInvocation;
+export declare function latestAgentServiceVersion(spawnProcess?: SpawnProcess): Promise<string>;
+export declare function installGlobalAgentService(outputJson?: boolean, spawnProcess?: SpawnProcess): Promise<void>;
+export interface UpdateDependencies {
+    latestAgentServiceVersion: typeof latestAgentServiceVersion;
+    readInstance: typeof readInstance;
+    requestInstance: typeof requestInstance;
+    waitUntilStopped: typeof waitUntilStopped;
+    installGlobalAgentService: typeof installGlobalAgentService;
+    startBackground: typeof startBackground;
+}
+export declare function updateAgentService(dataDir: string | undefined, cliPath: string, interruptAndStop: boolean, outputJson: boolean, dependencies?: UpdateDependencies): Promise<Record<string, unknown>>;
+export {};