openworkgraph 0.2.12

package/dist/operations/update.js

@@ -0,0 +1,216 @@
+import { spawn } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import { join, relative, isAbsolute, sep } from 'node:path';
+import { SERVICE_VERSION } from "../vendor/protocol/index.js";
+import { readInstance, requestInstance, startBackground, waitUntilStopped } from './lifecycle.js';
+const PACKAGE_NAME = 'openworkgraph';
+/** Compare the running package against npm's actual global package location. */
+export async function isGlobalNpmInstallation(cliPath, spawnProcess = spawn) {
+    const invocation = process.platform === 'win32'
+        ? { command: process.env.ComSpec ?? process.env.COMSPEC ?? 'cmd.exe', args: ['/d', '/s', '/c', 'npm root -g'] }
+        : { command: 'npm', args: ['root', '-g'] };
+    try {
+        const root = await new Promise((resolve, reject) => {
+            const child = spawnProcess(invocation.command, invocation.args, { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+            let output = '';
+            child.stdout?.on('data', chunk => { if (output.length < 8192)
+                output += chunk.toString('utf8'); });
+            child.once('error', reject);
+            child.once('close', code => code === 0 ? resolve(output.trim()) : reject(new Error('npm root failed')));
+        });
+        if (!root)
+            return false;
+        const installedPath = join(root, PACKAGE_NAME);
+        if ((await lstat(installedPath)).isSymbolicLink())
+            return false;
+        const packagePath = await realpath(installedPath);
+        const runningPath = await realpath(cliPath);
+        const inside = relative(packagePath, runningPath);
+        return inside !== '' && inside !== '..' && !inside.startsWith('..' + sep) && !isAbsolute(inside);
+    }
+    catch {
+        return false;
+    }
+}
+/** The updater must outlive the Runtime that it stops. */
+export async function startWebUpdate(cliPath, spawnProcess = spawn, onExit) {
+    const child = spawnProcess(process.execPath, [cliPath, 'update', '--output-json'], {
+        detached: true, windowsHide: true, stdio: 'ignore',
+    });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('spawn', resolve);
+    });
+    if (onExit)
+        child.once('close', onExit);
+    child.unref();
+}
+function parseSemVer(value) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+    const prerelease = match?.[4]?.split('.');
+    if (!match || prerelease?.some(identifier => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))) {
+        throw new Error(`Invalid semantic version: ${value}`);
+    }
+    return { core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])], prerelease };
+}
+export function compareSemVer(left, right) {
+    const a = parseSemVer(left), b = parseSemVer(right);
+    for (let index = 0; index < a.core.length; index++) {
+        if (a.core[index] < b.core[index])
+            return -1;
+        if (a.core[index] > b.core[index])
+            return 1;
+    }
+    if (!a.prerelease && !b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+        const leftPart = a.prerelease[index], rightPart = b.prerelease[index];
+        if (leftPart === undefined)
+            return -1;
+        if (rightPart === undefined)
+            return 1;
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/.test(leftPart), rightNumeric = /^\d+$/.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return BigInt(leftPart) < BigInt(rightPart) ? -1 : 1;
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+export function npmInstallInvocation(platform = process.platform, environment = process.env) {
+    if (platform === 'win32') {
+        // Recent Node versions reject direct .cmd execution with spawn EINVAL.
+        // Invoke npm through the Windows command interpreter explicitly instead.
+        return {
+            command: environment.ComSpec ?? environment.COMSPEC ?? 'cmd.exe',
+            args: ['/d', '/s', '/c', `npm install -g ${PACKAGE_NAME}`],
+        };
+    }
+    return { command: 'npm', args: ['install', '-g', PACKAGE_NAME] };
+}
+export function npmVersionInvocation(platform = process.platform, environment = process.env) {
+    if (platform === 'win32') {
+        return {
+            command: environment.ComSpec ?? environment.COMSPEC ?? 'cmd.exe',
+            args: ['/d', '/s', '/c', `npm view ${PACKAGE_NAME} version --json`],
+        };
+    }
+    return { command: 'npm', args: ['view', PACKAGE_NAME, 'version', '--json'] };
+}
+export async function latestAgentServiceVersion(spawnProcess = spawn) {
+    const invocation = npmVersionInvocation();
+    const child = spawnProcess(invocation.command, invocation.args, {
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '', stderr = '';
+    child.stdout?.on('data', chunk => {
+        if (stdout.length < 64 * 1024)
+            stdout += chunk.toString('utf8');
+    });
+    child.stderr?.on('data', chunk => {
+        if (stderr.length < 64 * 1024)
+            stderr += chunk.toString('utf8');
+    });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(stderr.trim() || `npm version check failed (${signal ?? code ?? 'unknown'})`));
+        });
+    });
+    let response;
+    try {
+        response = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error('npm returned an invalid package version response.');
+    }
+    // npm 12 wraps even a single scalar field in an array; older npm returns the string directly.
+    const version = Array.isArray(response) && response.length === 1 ? response[0] : response;
+    if (typeof version !== 'string')
+        throw new Error('npm returned an invalid package version response.');
+    parseSemVer(version);
+    return version;
+}
+export async function installGlobalAgentService(outputJson = false, spawnProcess = spawn) {
+    const invocation = npmInstallInvocation();
+    const child = spawnProcess(invocation.command, invocation.args, {
+        windowsHide: true,
+        stdio: outputJson ? ['ignore', 'ignore', 'pipe'] : 'inherit',
+    });
+    let stderr = '';
+    child.stderr?.on('data', chunk => {
+        if (stderr.length < 64 * 1024)
+            stderr += chunk.toString('utf8');
+    });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(stderr.trim() || `npm install failed (${signal ?? code ?? 'unknown'})`));
+        });
+    });
+}
+const defaultDependencies = {
+    latestAgentServiceVersion, readInstance, requestInstance, waitUntilStopped, installGlobalAgentService, startBackground,
+};
+export async function updateAgentService(dataDir, cliPath, interruptAndStop, outputJson, dependencies = defaultDependencies) {
+    const latestVersion = await dependencies.latestAgentServiceVersion();
+    const updateAvailable = compareSemVer(latestVersion, SERVICE_VERSION) > 0;
+    if (!updateAvailable) {
+        return {
+            packageName: PACKAGE_NAME, currentVersion: SERVICE_VERSION, latestVersion,
+            updateAvailable: false, updated: false, restarted: false,
+        };
+    }
+    let record;
+    let status;
+    if (dataDir) {
+        try {
+            record = await dependencies.readInstance(dataDir);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (record)
+            try {
+                status = await dependencies.requestInstance(record, 'status');
+            }
+            catch (error) {
+                if (error.code !== 'ECONNREFUSED')
+                    throw error;
+            }
+    }
+    let restartArgs;
+    if (record && status) {
+        if (!status.listenHost)
+            throw new Error('The older runtime did not report its listen address. Update it manually with npm install -g openworkgraph, then restart it with an explicit --host value. The runtime has not been stopped.');
+        const port = new URL(status.localEndpoint).port || '80';
+        if (!/^\d+$/.test(port) || Number(port) > 65535)
+            throw new Error('The running runtime reported an invalid listen port. The runtime has not been stopped.');
+        restartArgs = ['--data-dir', dataDir, '--host', status.listenHost, '--port', port];
+        await dependencies.requestInstance(record, interruptAndStop ? 'interrupt-and-stop' : 'stop');
+        await dependencies.waitUntilStopped(record);
+    }
+    await dependencies.installGlobalAgentService(outputJson);
+    const restarted = restartArgs ? await dependencies.startBackground(cliPath, restartArgs) : undefined;
+    return {
+        packageName: PACKAGE_NAME, currentVersion: SERVICE_VERSION, latestVersion,
+        updateAvailable: true, updated: true, restarted: Boolean(restartArgs),
+        ...(restarted && typeof restarted === 'object' ? restarted : {}),
+    };
+}
+//# sourceMappingURL=update.js.map

package/dist/persistence/asset-business-schema.d.ts

@@ -0,0 +1,2 @@
+/** Additive schema 6 fragment. No legacy resource conversion or file migration. */
+export declare const ASSET_BUSINESS_SCHEMA = "\nCREATE TABLE resource_uploads (\n id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id),\n name TEXT NOT NULL, mime TEXT NOT NULL, bytes INTEGER NOT NULL CHECK(bytes >= 0),\n expected_sha256 TEXT, received INTEGER NOT NULL DEFAULT 0 CHECK(received >= 0 AND received <= bytes),\n state TEXT NOT NULL DEFAULT 'uploading' CHECK(state IN ('uploading','finished')),\n sha256 TEXT REFERENCES blobs(sha256), created_at INTEGER NOT NULL,\n CHECK((state='finished' AND sha256 IS NOT NULL) OR (state='uploading' AND sha256 IS NULL))\n) STRICT;\nCREATE TABLE resource_upload_chunks (\n upload_id TEXT NOT NULL REFERENCES resource_uploads(id), offset INTEGER NOT NULL CHECK(offset >= 0),\n bytes INTEGER NOT NULL CHECK(bytes > 0), sha256 TEXT NOT NULL, path TEXT NOT NULL UNIQUE,\n PRIMARY KEY(upload_id,offset)\n) STRICT;\nCREATE TABLE resource_blob_files (sha256 TEXT PRIMARY KEY REFERENCES blobs(sha256), path TEXT NOT NULL UNIQUE) STRICT;\nCREATE TABLE resource_file_deletions (path TEXT PRIMARY KEY, created_at INTEGER NOT NULL, completed INTEGER NOT NULL DEFAULT 0 CHECK(completed IN (0,1))) STRICT;\nCREATE TABLE resource_read_leases (id TEXT PRIMARY KEY, sha256 TEXT NOT NULL REFERENCES blobs(sha256)) STRICT;\nCREATE TABLE resource_maintenance_leases (id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK(kind IN ('backup','drain')), created_at INTEGER NOT NULL) STRICT;\nCREATE TABLE resource_representations (\n sha256 TEXT NOT NULL REFERENCES blobs(sha256), processor TEXT NOT NULL, version INTEGER NOT NULL CHECK(version > 0),\n state TEXT NOT NULL CHECK(state IN ('ready','unsupported','failed')), mime TEXT NOT NULL, text TEXT, reason TEXT,\n PRIMARY KEY(sha256,processor,version)\n) STRICT;\nCREATE TRIGGER resource_blob_file_immutable BEFORE UPDATE ON resource_blob_files BEGIN SELECT RAISE(ABORT,'immutable blob file'); END;\nCREATE TRIGGER resource_asset_ref_reset AFTER UPDATE OF asset_id ON asset_references BEGIN\n UPDATE assets SET unreferenced_since=NULL WHERE id IN (OLD.asset_id,NEW.asset_id);\nEND;\nCREATE TRIGGER resource_no_rebind_deleted_asset BEFORE UPDATE OF asset_id,asset_version ON asset_references\n WHEN (NEW.asset_id!=OLD.asset_id OR NEW.asset_version!=OLD.asset_version) AND (SELECT deleted_at FROM assets WHERE id=NEW.asset_id) IS NOT NULL\n BEGIN SELECT RAISE(ABORT,'deleted assets reject new references'); END;\nCREATE TRIGGER resource_output_added AFTER INSERT ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=NEW.asset_id; END;\nCREATE TRIGGER resource_output_removed AFTER DELETE ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=OLD.asset_id; END;\nCREATE TRIGGER resource_output_changed AFTER UPDATE OF asset_id ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id IN (OLD.asset_id,NEW.asset_id); END;\n";

package/dist/persistence/asset-business-schema.js

@@ -0,0 +1,36 @@
+/** Additive schema 6 fragment. No legacy resource conversion or file migration. */
+export const ASSET_BUSINESS_SCHEMA = `
+CREATE TABLE resource_uploads (
+ id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id),
+ name TEXT NOT NULL, mime TEXT NOT NULL, bytes INTEGER NOT NULL CHECK(bytes >= 0),
+ expected_sha256 TEXT, received INTEGER NOT NULL DEFAULT 0 CHECK(received >= 0 AND received <= bytes),
+ state TEXT NOT NULL DEFAULT 'uploading' CHECK(state IN ('uploading','finished')),
+ sha256 TEXT REFERENCES blobs(sha256), created_at INTEGER NOT NULL,
+ CHECK((state='finished' AND sha256 IS NOT NULL) OR (state='uploading' AND sha256 IS NULL))
+) STRICT;
+CREATE TABLE resource_upload_chunks (
+ upload_id TEXT NOT NULL REFERENCES resource_uploads(id), offset INTEGER NOT NULL CHECK(offset >= 0),
+ bytes INTEGER NOT NULL CHECK(bytes > 0), sha256 TEXT NOT NULL, path TEXT NOT NULL UNIQUE,
+ PRIMARY KEY(upload_id,offset)
+) STRICT;
+CREATE TABLE resource_blob_files (sha256 TEXT PRIMARY KEY REFERENCES blobs(sha256), path TEXT NOT NULL UNIQUE) STRICT;
+CREATE TABLE resource_file_deletions (path TEXT PRIMARY KEY, created_at INTEGER NOT NULL, completed INTEGER NOT NULL DEFAULT 0 CHECK(completed IN (0,1))) STRICT;
+CREATE TABLE resource_read_leases (id TEXT PRIMARY KEY, sha256 TEXT NOT NULL REFERENCES blobs(sha256)) STRICT;
+CREATE TABLE resource_maintenance_leases (id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK(kind IN ('backup','drain')), created_at INTEGER NOT NULL) STRICT;
+CREATE TABLE resource_representations (
+ sha256 TEXT NOT NULL REFERENCES blobs(sha256), processor TEXT NOT NULL, version INTEGER NOT NULL CHECK(version > 0),
+ state TEXT NOT NULL CHECK(state IN ('ready','unsupported','failed')), mime TEXT NOT NULL, text TEXT, reason TEXT,
+ PRIMARY KEY(sha256,processor,version)
+) STRICT;
+CREATE TRIGGER resource_blob_file_immutable BEFORE UPDATE ON resource_blob_files BEGIN SELECT RAISE(ABORT,'immutable blob file'); END;
+CREATE TRIGGER resource_asset_ref_reset AFTER UPDATE OF asset_id ON asset_references BEGIN
+ UPDATE assets SET unreferenced_since=NULL WHERE id IN (OLD.asset_id,NEW.asset_id);
+END;
+CREATE TRIGGER resource_no_rebind_deleted_asset BEFORE UPDATE OF asset_id,asset_version ON asset_references
+ WHEN (NEW.asset_id!=OLD.asset_id OR NEW.asset_version!=OLD.asset_version) AND (SELECT deleted_at FROM assets WHERE id=NEW.asset_id) IS NOT NULL
+ BEGIN SELECT RAISE(ABORT,'deleted assets reject new references'); END;
+CREATE TRIGGER resource_output_added AFTER INSERT ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=NEW.asset_id; END;
+CREATE TRIGGER resource_output_removed AFTER DELETE ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=OLD.asset_id; END;
+CREATE TRIGGER resource_output_changed AFTER UPDATE OF asset_id ON outputs BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id IN (OLD.asset_id,NEW.asset_id); END;
+`;
+//# sourceMappingURL=asset-business-schema.js.map

package/dist/persistence/database.d.ts

@@ -0,0 +1,7 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { Migration } from './schema.js';
+/** Nest safely in auth/business transactions without committing the caller's work. */
+export declare function atomic<T>(db: DatabaseSync, work: () => T): T;
+export declare function transaction<T>(db: DatabaseSync, work: () => T): T;
+export declare function migrate(db: DatabaseSync, migrations?: readonly Migration[]): void;
+export declare function openDatabase(path: string, migrations?: readonly Migration[]): DatabaseSync;

package/dist/persistence/database.js

@@ -0,0 +1,91 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ServiceError } from '../errors.js';
+import { MIGRATIONS, SCHEMA_VERSION } from './schema.js';
+import { randomUUID } from 'node:crypto';
+/** Nest safely in auth/business transactions without committing the caller's work. */
+export function atomic(db, work) {
+    if (!db.isTransaction)
+        return transaction(db, work);
+    const name = 'op_' + randomUUID().replaceAll('-', '');
+    db.exec(`SAVEPOINT ${name}`);
+    try {
+        const result = work();
+        if (result && typeof result.then === 'function')
+            throw new Error('Transactions must be synchronous');
+        db.exec(`RELEASE ${name}`);
+        return result;
+    }
+    catch (error) {
+        db.exec(`ROLLBACK TO ${name}; RELEASE ${name}`);
+        throw error;
+    }
+}
+export function transaction(db, work) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = work();
+        if (result && typeof result.then === 'function')
+            throw new Error('Transactions must be synchronous');
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+export function migrate(db, migrations = MIGRATIONS) {
+    transaction(db, () => {
+        const version = Number(db.prepare('PRAGMA user_version').get()['user_version']);
+        if (version > SCHEMA_VERSION || version < 0)
+            throw new ServiceError('SCHEMA_UNSUPPORTED', `Unsupported database schema ${version}; expected 0..${SCHEMA_VERSION}`);
+        if (version === 0 && db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").get())
+            throw new ServiceError('SCHEMA_UNSUPPORTED', 'Unversioned nonempty database; refusing to overwrite');
+        if (version > 0) {
+            for (const table of ['identity', 'settings', 'sessions', 'pairing_codes']) {
+                if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                    throw new ServiceError('SCHEMA_UNSUPPORTED', `Missing schema table ${table}`);
+            }
+        }
+        for (let next = version + 1; next <= SCHEMA_VERSION; next++) {
+            const migration = migrations.find(item => item.version === next);
+            if (!migration)
+                throw new ServiceError('SCHEMA_UNSUPPORTED', `Missing migration ${next}`);
+            try {
+                db.exec(migration.sql);
+                db.exec(`PRAGMA user_version = ${next}`);
+            }
+            catch (cause) {
+                throw new ServiceError('MIGRATION_FAILED', `Migration ${next} failed; database unchanged`, { cause });
+            }
+        }
+        for (const table of ['identity', 'settings', 'sessions', 'pairing_codes', 'projects', 'graphs', 'nodes', 'node_versions', 'edges', 'blobs', 'assets', 'asset_versions', 'runs', 'snapshots', 'outputs', 'asset_references', 'events', 'interactions', 'occupancy', 'idempotency', 'plugin_contracts', 'backups', 'trusted_origins', 'canvas_resources', 'canvas_resource_versions', 'canvas_resource_references', 'canvas_outputs']) {
+            if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                throw new ServiceError('SCHEMA_UNSUPPORTED', `Missing schema table ${table}`);
+        }
+        for (const table of ['execution_input_snapshots', 'execution_outputs', 'project_file_bindings', 'project_file_observations', 'project_file_outputs', 'node_resource_history', 'graph_groups', 'group_members', 'run_runtime', 'run_process_records', 'run_notifications', 'generation_candidates', 'publication_manifests', 'resource_uploads', 'resource_upload_chunks', 'resource_blob_files', 'resource_file_deletions', 'resource_read_leases', 'resource_maintenance_leases']) {
+            if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                throw new ServiceError('SCHEMA_UNSUPPORTED', `Missing schema table ${table}`);
+        }
+        if (db.prepare('PRAGMA foreign_key_check').get())
+            throw new ServiceError('SCHEMA_UNSUPPORTED', 'Database has foreign key violations');
+        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='node_version_schemas'").get())
+            throw new ServiceError('SCHEMA_UNSUPPORTED', 'Missing node version schema history');
+        for (const table of ['image_providers', 'image_provider_models', 'image_provider_config_versions', 'image_provider_revoked_credentials'])
+            if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table))
+                throw new ServiceError('SCHEMA_UNSUPPORTED', 'Missing image provider directory');
+    });
+}
+export function openDatabase(path, migrations = MIGRATIONS) {
+    const db = new DatabaseSync(path, { enableForeignKeyConstraints: true, timeout: 5000, allowExtension: false });
+    try {
+        migrate(db, migrations);
+        db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/persistence/plugin-schema.d.ts

@@ -0,0 +1,9 @@
+/** Additive schema7, wired by the main migration owner.
+ * Backfill is valid for the pre-plugin-management lineage: no node schema
+ * migration API could run before this table existed (it fails closed). Existing
+ * imported nodes may use schema >1, but all their retained versions use that
+ * same schema. A database with out-of-band historical schema mutations needs
+ * explicit recovery metadata; this migration cannot infer those mutations.
+ * Ambiguous preexisting read_only rows stay original, never auto-unlocked.
+ */
+export declare const PLUGIN_SCHEMA = "\nALTER TABLE nodes ADD COLUMN read_only_reason TEXT NOT NULL DEFAULT 'none'\n  CHECK(read_only_reason IN ('none','missing_plugin','original'));\nUPDATE nodes SET read_only_reason='original' WHERE read_only=1;\nCREATE TABLE node_version_schemas (\n  node_id TEXT NOT NULL,\n  version INTEGER NOT NULL CHECK(version > 0),\n  schema_version INTEGER NOT NULL CHECK(schema_version > 0),\n  PRIMARY KEY(node_id,version),\n  FOREIGN KEY(node_id,version) REFERENCES node_versions(node_id,version) ON DELETE CASCADE\n) STRICT;\nINSERT INTO node_version_schemas(node_id,version,schema_version)\n  SELECT v.node_id,v.version,n.schema_version FROM node_versions v JOIN nodes n ON n.id=v.node_id;\nCREATE TRIGGER node_version_schema_capture AFTER INSERT ON node_versions BEGIN\n  INSERT INTO node_version_schemas(node_id,version,schema_version)\n    SELECT NEW.node_id,NEW.version,schema_version FROM nodes WHERE id=NEW.node_id;\nEND;\nCREATE TRIGGER node_version_schema_immutable BEFORE UPDATE ON node_version_schemas BEGIN\n  SELECT RAISE(ABORT,'immutable node version schema');\nEND;\nCREATE TRIGGER node_version_schema_delete_guard BEFORE DELETE ON node_version_schemas\nWHEN EXISTS(SELECT 1 FROM node_versions WHERE node_id=OLD.node_id AND version=OLD.version) BEGIN\n  SELECT RAISE(ABORT,'retained node version requires schema history');\nEND;\nCREATE TRIGGER node_current_schema_guard BEFORE UPDATE OF schema_version,current_version ON nodes\nWHEN EXISTS(SELECT 1 FROM node_version_schemas s WHERE s.node_id=NEW.id AND s.version=NEW.current_version AND s.schema_version!=NEW.schema_version) BEGIN\n  SELECT RAISE(ABORT,'current node schema does not match version history');\nEND;\n";

package/dist/persistence/plugin-schema.js

@@ -0,0 +1,38 @@
+/** Additive schema7, wired by the main migration owner.
+ * Backfill is valid for the pre-plugin-management lineage: no node schema
+ * migration API could run before this table existed (it fails closed). Existing
+ * imported nodes may use schema >1, but all their retained versions use that
+ * same schema. A database with out-of-band historical schema mutations needs
+ * explicit recovery metadata; this migration cannot infer those mutations.
+ * Ambiguous preexisting read_only rows stay original, never auto-unlocked.
+ */
+export const PLUGIN_SCHEMA = `
+ALTER TABLE nodes ADD COLUMN read_only_reason TEXT NOT NULL DEFAULT 'none'
+  CHECK(read_only_reason IN ('none','missing_plugin','original'));
+UPDATE nodes SET read_only_reason='original' WHERE read_only=1;
+CREATE TABLE node_version_schemas (
+  node_id TEXT NOT NULL,
+  version INTEGER NOT NULL CHECK(version > 0),
+  schema_version INTEGER NOT NULL CHECK(schema_version > 0),
+  PRIMARY KEY(node_id,version),
+  FOREIGN KEY(node_id,version) REFERENCES node_versions(node_id,version) ON DELETE CASCADE
+) STRICT;
+INSERT INTO node_version_schemas(node_id,version,schema_version)
+  SELECT v.node_id,v.version,n.schema_version FROM node_versions v JOIN nodes n ON n.id=v.node_id;
+CREATE TRIGGER node_version_schema_capture AFTER INSERT ON node_versions BEGIN
+  INSERT INTO node_version_schemas(node_id,version,schema_version)
+    SELECT NEW.node_id,NEW.version,schema_version FROM nodes WHERE id=NEW.node_id;
+END;
+CREATE TRIGGER node_version_schema_immutable BEFORE UPDATE ON node_version_schemas BEGIN
+  SELECT RAISE(ABORT,'immutable node version schema');
+END;
+CREATE TRIGGER node_version_schema_delete_guard BEFORE DELETE ON node_version_schemas
+WHEN EXISTS(SELECT 1 FROM node_versions WHERE node_id=OLD.node_id AND version=OLD.version) BEGIN
+  SELECT RAISE(ABORT,'retained node version requires schema history');
+END;
+CREATE TRIGGER node_current_schema_guard BEFORE UPDATE OF schema_version,current_version ON nodes
+WHEN EXISTS(SELECT 1 FROM node_version_schemas s WHERE s.node_id=NEW.id AND s.version=NEW.current_version AND s.schema_version!=NEW.schema_version) BEGIN
+  SELECT RAISE(ABORT,'current node schema does not match version history');
+END;
+`;
+//# sourceMappingURL=plugin-schema.js.map

package/dist/persistence/repositories.d.ts

@@ -0,0 +1,20 @@
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
+import type { Json, ServiceEvent } from "../vendor/protocol/index.js";
+export declare function canonicalJson(value: Json): string;
+/** Same digest as canonicalJson, without joining an entire resource bundle. */
+export declare function canonicalJsonHash(value: Json): string;
+export declare class Repositories {
+    readonly db: DatabaseSync;
+    constructor(db: DatabaseSync);
+    identity(): string;
+    /** All business effects and the replay response commit in one short transaction. */
+    replay(scope: string, key: string, body: Json): Json | undefined;
+    idempotent(scope: string, key: string, body: Json, work: () => Json): Json;
+    setting(key: string): Json | undefined;
+    /** Internal persistence only; never expose this generic interface as an HTTP route. */
+    insert(table: StorageTable, values: Record<string, SQLInputValue>): void;
+    list(table: StorageTable, limit?: number): Record<string, unknown>[];
+    appendEvent(event: Omit<ServiceEvent, 'cursor' | 'serviceId'>): string;
+}
+export declare const STORAGE_TABLES: readonly ['sessions', 'pairing_codes', 'projects', 'graphs', 'nodes', 'node_versions', 'edges', 'blobs', 'assets', 'asset_versions', 'runs', 'run_notifications', 'snapshots', 'outputs', 'asset_references', 'events', 'interactions', 'occupancy', 'idempotency', 'plugin_contracts', 'backups', 'canvas_resources', 'canvas_resource_versions', 'canvas_resource_references', 'canvas_outputs', 'project_file_bindings', 'project_file_observations', 'project_file_outputs'];
+export type StorageTable = typeof STORAGE_TABLES[number];

package/dist/persistence/repositories.js

@@ -0,0 +1,106 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { ServiceError } from '../errors.js';
+import { atomic, transaction } from './database.js';
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        if (typeof value === 'number' && !Number.isFinite(value))
+            throw new ServiceError('INVALID_REQUEST', 'Non-finite JSON number');
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new ServiceError('INVALID_REQUEST', 'Invalid JSON value');
+        return encoded;
+    }
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonicalJson(value[key])).join(',') + '}';
+}
+/** Same digest as canonicalJson, without joining an entire resource bundle. */
+export function canonicalJsonHash(value) {
+    const hash = createHash('sha256');
+    function visit(item) {
+        if (item === null || typeof item !== 'object') {
+            hash.update(canonicalJson(item));
+            return;
+        }
+        const array = Array.isArray(item);
+        hash.update(array ? '[' : '{');
+        const keys = array ? item.map((_, index) => String(index)) : Object.keys(item).sort();
+        keys.forEach((key, index) => {
+            if (index)
+                hash.update(',');
+            if (!array)
+                hash.update(JSON.stringify(key) + ':');
+            visit(item[key]);
+        });
+        hash.update(array ? ']' : '}');
+    }
+    visit(value);
+    return hash.digest('hex');
+}
+export class Repositories {
+    db;
+    constructor(db) { this.db = db; }
+    identity() {
+        return transaction(this.db, () => {
+            this.db.prepare('INSERT OR IGNORE INTO identity(singleton,service_id,created_at) VALUES(1,?,?)').run(randomUUID(), new Date().toISOString());
+            return String(this.db.prepare('SELECT service_id FROM identity WHERE singleton=1').get()['service_id']);
+        });
+    }
+    /** All business effects and the replay response commit in one short transaction. */
+    replay(scope, key, body) {
+        if (!scope || !key || key.length > 256)
+            throw new ServiceError('INVALID_REQUEST', 'Invalid idempotency scope or key');
+        const prior = this.db.prepare('SELECT request_hash,response,invalidated FROM idempotency WHERE scope=? AND key=?').get(scope, key);
+        if (!prior)
+            return undefined;
+        if (prior['request_hash'] !== createHash('sha256').update(canonicalJson(body)).digest('hex'))
+            throw new ServiceError('IDEMPOTENCY_CONFLICT', 'Idempotency key already used with a different request body');
+        if (prior['invalidated'])
+            throw new ServiceError('NOT_FOUND', 'The graph associated with this request was permanently deleted');
+        return JSON.parse(String(prior['response']));
+    }
+    idempotent(scope, key, body, work) {
+        if (!scope || !key || key.length > 256)
+            throw new ServiceError('INVALID_REQUEST', 'Invalid idempotency scope or key');
+        const hash = createHash('sha256').update(canonicalJson(body)).digest('hex');
+        return atomic(this.db, () => {
+            const prior = this.db.prepare('SELECT request_hash,response,invalidated FROM idempotency WHERE scope=? AND key=?').get(scope, key);
+            if (prior) {
+                if (prior['request_hash'] !== hash)
+                    throw new ServiceError('IDEMPOTENCY_CONFLICT', 'Idempotency key already used with a different request body');
+                if (prior['invalidated'])
+                    throw new ServiceError('NOT_FOUND', 'The graph associated with this request was permanently deleted');
+                return JSON.parse(String(prior['response']));
+            }
+            const result = work();
+            if (result && typeof result.then === 'function')
+                throw new Error('Idempotent work must be synchronous');
+            this.db.prepare('INSERT INTO idempotency(scope,key,request_hash,response) VALUES(?,?,?,?)').run(scope, key, hash, canonicalJson(result));
+            return result;
+        });
+    }
+    setting(key) {
+        const row = this.db.prepare('SELECT value FROM settings WHERE key=?').get(key);
+        return row ? JSON.parse(String(row['value'])) : undefined;
+    }
+    /** Internal persistence only; never expose this generic interface as an HTTP route. */
+    insert(table, values) {
+        const columns = Object.keys(values);
+        if (!STORAGE_TABLES.includes(table) || !columns.length || columns.some(key => !/^[a-z_][a-z0-9_]*$/.test(key)))
+            throw new Error('Invalid storage identifier');
+        this.db.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')})`).run(...columns.map(key => values[key]));
+    }
+    list(table, limit = 100) {
+        if (!STORAGE_TABLES.includes(table) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error('Invalid storage query');
+        return this.db.prepare(`SELECT * FROM ${table} LIMIT ?`).all(limit);
+    }
+    appendEvent(event) {
+        if (!this.db.isTransaction)
+            throw new Error('Events must be persisted inside the business transaction');
+        const result = this.db.prepare('INSERT INTO events(id,type,project_id,graph_id,entity_id,revision,occurred_at,payload) VALUES(?,?,?,?,?,?,?,?)').run(event.eventId, event.type, event.projectId, event.graphId, event.entityId, event.revision, event.occurredAt, canonicalJson(event.payload));
+        return String(result.lastInsertRowid);
+    }
+}
+export const STORAGE_TABLES = ['sessions', 'pairing_codes', 'projects', 'graphs', 'nodes', 'node_versions', 'edges', 'blobs', 'assets', 'asset_versions', 'runs', 'run_notifications', 'snapshots', 'outputs', 'asset_references', 'events', 'interactions', 'occupancy', 'idempotency', 'plugin_contracts', 'backups', 'canvas_resources', 'canvas_resource_versions', 'canvas_resource_references', 'canvas_outputs', 'project_file_bindings', 'project_file_observations', 'project_file_outputs'];
+//# sourceMappingURL=repositories.js.map

package/dist/persistence/resource-schema.d.ts

@@ -0,0 +1,2 @@
+/** Additive only: legacy asset references, outputs and snapshot JSON are preserved. */
+export declare const RESOURCE_SCHEMA = "\nALTER TABLE assets ADD COLUMN name TEXT NOT NULL DEFAULT '';\nALTER TABLE assets ADD COLUMN current_version INTEGER NOT NULL DEFAULT 0 CHECK(current_version >= 0);\nUPDATE assets SET current_version=COALESCE((SELECT MAX(version) FROM asset_versions WHERE asset_id=assets.id),0);\nCREATE INDEX assets_project_name ON assets(project_id,name);\nCREATE UNIQUE INDEX runs_id_graph ON runs(id,graph_id);\nCREATE TABLE canvas_resources (\n  id TEXT PRIMARY KEY, project_id TEXT NOT NULL, graph_id TEXT NOT NULL, name TEXT NOT NULL,\n  current_version INTEGER NOT NULL CHECK(current_version > 0), UNIQUE(id,graph_id),\n  FOREIGN KEY(graph_id,project_id) REFERENCES graphs(id,project_id),\n  FOREIGN KEY(id,current_version) REFERENCES canvas_resource_versions(resource_id,version) DEFERRABLE INITIALLY DEFERRED\n) STRICT;\nCREATE TABLE canvas_resource_versions (\n  resource_id TEXT NOT NULL REFERENCES canvas_resources(id) DEFERRABLE INITIALLY DEFERRED,\n  version INTEGER NOT NULL CHECK(version > 0), sha256 TEXT NOT NULL REFERENCES blobs(sha256), mime TEXT NOT NULL,\n  representation_version INTEGER, PRIMARY KEY(resource_id,version)\n) STRICT;\nCREATE TRIGGER canvas_version_immutable BEFORE UPDATE ON canvas_resource_versions BEGIN SELECT RAISE(ABORT,'immutable canvas resource version'); END;\nCREATE TRIGGER canvas_binding_immutable BEFORE UPDATE OF project_id,graph_id ON canvas_resources WHEN NEW.project_id != OLD.project_id OR NEW.graph_id != OLD.graph_id BEGIN SELECT RAISE(ABORT,'canvas resource binding immutable'); END;\nCREATE TABLE canvas_resource_references (\n  id TEXT PRIMARY KEY, resource_id TEXT NOT NULL, resource_version INTEGER NOT NULL, graph_id TEXT NOT NULL,\n  owner_kind TEXT NOT NULL CHECK(owner_kind IN ('graph','node','snapshot','history')),\n  node_id TEXT, run_id TEXT,\n  CHECK((owner_kind='graph' AND node_id IS NULL AND run_id IS NULL) OR (owner_kind='node' AND node_id IS NOT NULL AND run_id IS NULL) OR (owner_kind IN ('snapshot','history') AND node_id IS NULL AND run_id IS NOT NULL)),\n  FOREIGN KEY(resource_id,resource_version) REFERENCES canvas_resource_versions(resource_id,version),\n  FOREIGN KEY(resource_id,graph_id) REFERENCES canvas_resources(id,graph_id),\n  FOREIGN KEY(node_id,graph_id) REFERENCES nodes(id,graph_id),\n  FOREIGN KEY(run_id,graph_id) REFERENCES runs(id,graph_id)\n) STRICT;\nCREATE INDEX canvas_refs_resource ON canvas_resource_references(resource_id,resource_version);\nCREATE TRIGGER frozen_resource_reference_immutable BEFORE UPDATE ON canvas_resource_references WHEN OLD.owner_kind IN ('snapshot','history') BEGIN SELECT RAISE(ABORT,'frozen resource reference'); END;\nCREATE TABLE canvas_outputs (\n  run_id TEXT NOT NULL, graph_id TEXT NOT NULL, output_key TEXT NOT NULL, resource_id TEXT NOT NULL, resource_version INTEGER NOT NULL,\n  PRIMARY KEY(run_id,output_key), FOREIGN KEY(resource_id,resource_version) REFERENCES canvas_resource_versions(resource_id,version),\n  FOREIGN KEY(resource_id,graph_id) REFERENCES canvas_resources(id,graph_id), FOREIGN KEY(run_id,graph_id) REFERENCES runs(id,graph_id)\n) STRICT;\nCREATE TRIGGER no_new_canvas_asset_link BEFORE INSERT ON asset_references WHEN NEW.node_id IS NOT NULL BEGIN SELECT RAISE(ABORT,'canvas nodes must use independent canvas resources'); END;\nCREATE TRIGGER no_rebind_canvas_asset_link BEFORE UPDATE OF asset_id,asset_version,node_id ON asset_references WHEN NEW.node_id IS NOT NULL BEGIN SELECT RAISE(ABORT,'legacy canvas asset references cannot be rebound'); END;\nCREATE TRIGGER no_new_deleted_asset_reference BEFORE INSERT ON asset_references WHEN (SELECT deleted_at FROM assets WHERE id=NEW.asset_id) IS NOT NULL BEGIN SELECT RAISE(ABORT,'deleted assets reject new references'); END;\nCREATE TRIGGER asset_reference_added AFTER INSERT ON asset_references BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=NEW.asset_id; END;\nCREATE TRIGGER asset_reference_removed AFTER DELETE ON asset_references BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=OLD.asset_id; END;\n";

package/dist/persistence/resource-schema.js

@@ -0,0 +1,44 @@
+/** Additive only: legacy asset references, outputs and snapshot JSON are preserved. */
+export const RESOURCE_SCHEMA = `
+ALTER TABLE assets ADD COLUMN name TEXT NOT NULL DEFAULT '';
+ALTER TABLE assets ADD COLUMN current_version INTEGER NOT NULL DEFAULT 0 CHECK(current_version >= 0);
+UPDATE assets SET current_version=COALESCE((SELECT MAX(version) FROM asset_versions WHERE asset_id=assets.id),0);
+CREATE INDEX assets_project_name ON assets(project_id,name);
+CREATE UNIQUE INDEX runs_id_graph ON runs(id,graph_id);
+CREATE TABLE canvas_resources (
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL, graph_id TEXT NOT NULL, name TEXT NOT NULL,
+  current_version INTEGER NOT NULL CHECK(current_version > 0), UNIQUE(id,graph_id),
+  FOREIGN KEY(graph_id,project_id) REFERENCES graphs(id,project_id),
+  FOREIGN KEY(id,current_version) REFERENCES canvas_resource_versions(resource_id,version) DEFERRABLE INITIALLY DEFERRED
+) STRICT;
+CREATE TABLE canvas_resource_versions (
+  resource_id TEXT NOT NULL REFERENCES canvas_resources(id) DEFERRABLE INITIALLY DEFERRED,
+  version INTEGER NOT NULL CHECK(version > 0), sha256 TEXT NOT NULL REFERENCES blobs(sha256), mime TEXT NOT NULL,
+  representation_version INTEGER, PRIMARY KEY(resource_id,version)
+) STRICT;
+CREATE TRIGGER canvas_version_immutable BEFORE UPDATE ON canvas_resource_versions BEGIN SELECT RAISE(ABORT,'immutable canvas resource version'); END;
+CREATE TRIGGER canvas_binding_immutable BEFORE UPDATE OF project_id,graph_id ON canvas_resources WHEN NEW.project_id != OLD.project_id OR NEW.graph_id != OLD.graph_id BEGIN SELECT RAISE(ABORT,'canvas resource binding immutable'); END;
+CREATE TABLE canvas_resource_references (
+  id TEXT PRIMARY KEY, resource_id TEXT NOT NULL, resource_version INTEGER NOT NULL, graph_id TEXT NOT NULL,
+  owner_kind TEXT NOT NULL CHECK(owner_kind IN ('graph','node','snapshot','history')),
+  node_id TEXT, run_id TEXT,
+  CHECK((owner_kind='graph' AND node_id IS NULL AND run_id IS NULL) OR (owner_kind='node' AND node_id IS NOT NULL AND run_id IS NULL) OR (owner_kind IN ('snapshot','history') AND node_id IS NULL AND run_id IS NOT NULL)),
+  FOREIGN KEY(resource_id,resource_version) REFERENCES canvas_resource_versions(resource_id,version),
+  FOREIGN KEY(resource_id,graph_id) REFERENCES canvas_resources(id,graph_id),
+  FOREIGN KEY(node_id,graph_id) REFERENCES nodes(id,graph_id),
+  FOREIGN KEY(run_id,graph_id) REFERENCES runs(id,graph_id)
+) STRICT;
+CREATE INDEX canvas_refs_resource ON canvas_resource_references(resource_id,resource_version);
+CREATE TRIGGER frozen_resource_reference_immutable BEFORE UPDATE ON canvas_resource_references WHEN OLD.owner_kind IN ('snapshot','history') BEGIN SELECT RAISE(ABORT,'frozen resource reference'); END;
+CREATE TABLE canvas_outputs (
+  run_id TEXT NOT NULL, graph_id TEXT NOT NULL, output_key TEXT NOT NULL, resource_id TEXT NOT NULL, resource_version INTEGER NOT NULL,
+  PRIMARY KEY(run_id,output_key), FOREIGN KEY(resource_id,resource_version) REFERENCES canvas_resource_versions(resource_id,version),
+  FOREIGN KEY(resource_id,graph_id) REFERENCES canvas_resources(id,graph_id), FOREIGN KEY(run_id,graph_id) REFERENCES runs(id,graph_id)
+) STRICT;
+CREATE TRIGGER no_new_canvas_asset_link BEFORE INSERT ON asset_references WHEN NEW.node_id IS NOT NULL BEGIN SELECT RAISE(ABORT,'canvas nodes must use independent canvas resources'); END;
+CREATE TRIGGER no_rebind_canvas_asset_link BEFORE UPDATE OF asset_id,asset_version,node_id ON asset_references WHEN NEW.node_id IS NOT NULL BEGIN SELECT RAISE(ABORT,'legacy canvas asset references cannot be rebound'); END;
+CREATE TRIGGER no_new_deleted_asset_reference BEFORE INSERT ON asset_references WHEN (SELECT deleted_at FROM assets WHERE id=NEW.asset_id) IS NOT NULL BEGIN SELECT RAISE(ABORT,'deleted assets reject new references'); END;
+CREATE TRIGGER asset_reference_added AFTER INSERT ON asset_references BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=NEW.asset_id; END;
+CREATE TRIGGER asset_reference_removed AFTER DELETE ON asset_references BEGIN UPDATE assets SET unreferenced_since=NULL WHERE id=OLD.asset_id; END;
+`;
+//# sourceMappingURL=resource-schema.js.map

package/dist/persistence/schema.d.ts

@@ -0,0 +1,6 @@
+export interface Migration {
+    version: number;
+    sql: string;
+}
+export declare const MIGRATIONS: readonly Migration[];
+export declare const SCHEMA_VERSION = 24;