@zhin.js/plugin-runtime 1.1.15 → 1.1.16

package/lib/database-host.d.ts

@@ -35,6 +35,10 @@ export interface DatabaseHostModel {
      */
     count?(where?: Record<string, unknown>): Promise<number>;
 }
+/** Callback-scoped transaction models; no raw SQL or administration access. */
+export interface DatabaseHostTransaction {
+    model(name: string): DatabaseHostModel;
+}
 export type DatabaseHostType = 'related' | 'document' | 'keyvalue';
 export interface DatabaseHostTable {
     readonly name: string;
@@ -85,6 +89,8 @@ export interface DatabaseHost {
     models: {
         get(name: string): DatabaseHostModel | undefined;
     };
+    /** Atomic SQL operations. The callback must await all operations before returning. */
+    transaction?<T>(callback: (transaction: DatabaseHostTransaction) => Promise<T>): Promise<T>;
     /** Root-only management port; absent on lightweight test/memory hosts. */
     readonly console?: DatabaseHostConsole;
     /**
@@ -125,7 +131,10 @@ export declare class PluginDatabaseHost extends OwnerScopedResourceHost {
     get started(): boolean;
     define(name: string, definition: Record<string, unknown>): void;
     tables(): readonly string[];
+    transaction<T>(callback: (transaction: DatabaseHostTransaction) => Promise<T>): Promise<T>;
 }
+/** A saved query/model cannot escape the callback and reuse the transaction. */
+export declare function guardTransactionModel(model: DatabaseHostModel, check: () => void): DatabaseHostModel;
 /**
  * Plugin-facing scoped persistence token. Runtime replaces this binding for
  * every Plugin Scope; plugin code must never receive the process-wide host.

package/lib/database-host.js

@@ -63,6 +63,27 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
             return logical === undefined ? [] : [logical];
         })));
     }
+    async transaction(callback) {
+        if (!this.#host.transaction)
+            throw new Error('Database Host does not support transactions');
+        return this.#execute(() => this.#host.transaction(async (transaction) => {
+            let active = true;
+            const requireActive = () => { if (!active)
+                throw new Error('Database transaction is already closed'); };
+            try {
+                return await callback(Object.freeze({ model: (name) => {
+                        requireActive();
+                        // Reuse the ordinary facade so qualification and generation checks stay identical.
+                        const model = transaction.model(this.qualify(name));
+                        const guarded = guardTransactionModel(model, requireActive);
+                        return this.#bindModel(guarded);
+                    } }));
+            }
+            finally {
+                active = false;
+            }
+        }));
+    }
     #bindSelection(selection) {
         const modify = (operation) => this.#operation.setup(() => {
             const next = operation();
@@ -94,6 +115,21 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
         return this.#operation.run(operation);
     }
 }
+/** A saved query/model cannot escape the callback and reuse the transaction. */
+export function guardTransactionModel(model, check) {
+    const selection = (source) => ({
+        where(query) { check(); return selection(source.where(query)); },
+        orderBy(field, direction) { check(); return selection(source.orderBy(field, direction)); },
+        limit(count) { check(); return selection(source.limit(count)); },
+        then(resolve, reject) { return Promise.resolve().then(() => { check(); return source; }).then(resolve, reject); },
+    });
+    return {
+        select: (...fields) => { check(); return selection(model.select(...fields)); },
+        insert: async (row) => { check(); return model.insert(row); },
+        update: patch => { check(); return { where: async (query) => { check(); return model.update(patch).where(query); } }; },
+        delete: () => { check(); return { where: async (query) => { check(); return model.delete().where(query); } }; },
+    };
+}
 /**
  * Plugin-facing scoped persistence token. Runtime replaces this binding for
  * every Plugin Scope; plugin code must never receive the process-wide host.

package/lib/inbox.d.ts

@@ -10,6 +10,28 @@ import type { DatabaseHost } from './database-host.js';
 export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
 export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";
 export declare const INBOX_TABLE_NOTICE = "unified_inbox_notice";
+export declare const INBOX_MESSAGE_QUERY_COLUMNS: {
+    readonly direction: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_capability_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_adapter_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly thread_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly query_version: {
+        readonly type: "integer";
+        readonly nullable: true;
+    };
+};
 export declare const INBOX_MESSAGE_DEFINITION: Record<string, unknown>;
 export declare const INBOX_REQUEST_DEFINITION: Record<string, unknown>;
 export declare const INBOX_NOTICE_DEFINITION: Record<string, unknown>;

package/lib/inbox.js

@@ -10,7 +10,15 @@ import { createToken } from './token.js';
 export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
 export const INBOX_TABLE_REQUEST = 'unified_inbox_request';
 export const INBOX_TABLE_NOTICE = 'unified_inbox_notice';
+export const INBOX_MESSAGE_QUERY_COLUMNS = {
+    direction: { type: 'text', nullable: true },
+    endpoint_capability_id: { type: 'text', nullable: true },
+    endpoint_adapter_id: { type: 'text', nullable: true },
+    thread_id: { type: 'text', nullable: true },
+    query_version: { type: 'integer', nullable: true },
+};
 export const INBOX_MESSAGE_DEFINITION = {
+    ...INBOX_MESSAGE_QUERY_COLUMNS,
     id: { type: 'integer', primary: true, autoIncrement: true },
     adapter: { type: 'text', nullable: false },
     endpoint_id: { type: 'text', nullable: false },

package/lib/index.d.ts

@@ -33,7 +33,9 @@ export * from './outbound-host.js';
 export * from './outbound-sender.js';
 export * from './delivery-target.js';
 export * from './persistent-state.js';
+export * from './relational-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
+export * from './task-storage.js';

package/lib/index.js

@@ -33,7 +33,9 @@ export * from './outbound-host.js';
 export * from './outbound-sender.js';
 export * from './delivery-target.js';
 export * from './persistent-state.js';
+export * from './relational-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
+export * from './task-storage.js';

package/lib/plugin.d.ts

@@ -68,6 +68,6 @@ export interface PluginDefinition<TConfig = unknown> {
 export declare function definePlugin<TConfig = unknown>(definition: PluginDefinition<TConfig>): Readonly<PluginDefinition<TConfig>>;
 export { createDeliveryTarget, type DeliveryTarget } from './delivery-target.js';
 export { PluginStateStore, type JsonValue, type StateScope, type StateRecord, type PersistentStatePort, type StateWriteOptions } from './persistent-state.js';
-export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, PluginDatabaseHost, } from './database-host.js';
+export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostTransaction, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, PluginDatabaseHost, } from './database-host.js';
 export { outboundHostToken, type OutboundConversation, type OutboundEditInput, type OutboundEndpointCapabilities, type OutboundEndpointInput, type OutboundEndpointOperation, type OutboundHost, type OutboundMessage, type OutboundReactionInput, type OutboundRecallInput, type OutboundRemoveReactionInput, type OutboundSendInput, type OutboundTypingInput, } from './outbound-host.js';
 export { scheduleHostToken, PluginScheduleHost, type ScheduleJobRegistration, } from './schedule-host.js';

package/lib/relational-state.d.ts

@@ -0,0 +1,24 @@
+import { PluginStateStore, type JsonValue } from './persistent-state.js';
+import type { PluginDatabaseHost } from './database-host.js';
+export interface RelationalStateCodec {
+    /** Existing plugin-scoped key to migrate once. */
+    readonly key: string;
+    readonly header: {
+        readonly table: string;
+        readonly definition: Record<string, unknown>;
+    };
+    readonly tables: Readonly<Record<string, Record<string, unknown>>>;
+    encode(value: JsonValue): {
+        header: Record<string, unknown>;
+        rows: Record<string, readonly Record<string, unknown>[]>;
+    };
+    decode(header: Record<string, unknown>, rows: Record<string, readonly Record<string, unknown>[]>): JsonValue;
+}
+/**
+ * Reuses PluginStateStore's CAS and admission contract with relational records.
+ * Only registered plugin keys are accepted; ordinary state uses database.state.
+ * Register in setup. Tables, revision and receipts commit or roll back together.
+ */
+export declare function createRelationalStateStore(database: PluginDatabaseHost, codecs: readonly RelationalStateCodec[]): PluginStateStore;
+/** Only for pure database mutations; never wrap external sends or arbitrary side effects. */
+export declare function retryRelationalOperation<T>(operation: () => Promise<T>): Promise<T>;

package/lib/relational-state.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { setImmediate } from 'node:timers/promises';
+import { PluginStateStore } from './persistent-state.js';
+/**
+ * Reuses PluginStateStore's CAS and admission contract with relational records.
+ * Only registered plugin keys are accepted; ordinary state uses database.state.
+ * Register in setup. Tables, revision and receipts commit or roll back together.
+ */
+export function createRelationalStateStore(database, codecs) {
+    if (!['sqlite', 'mysql', 'pg'].includes(database.dialect)) {
+        throw new Error(`结构化任务持久化仅支持 SQLite、MySQL、PostgreSQL，当前为 ${database.dialect}；不会自动更换数据库`);
+    }
+    const legacy = database.state;
+    const byKey = new Map(codecs.map(codec => [codec.key, codec]));
+    if (byKey.size !== codecs.length)
+        throw new Error('Duplicate relational state key');
+    for (const codec of codecs) {
+        database.define(codec.header.table, {
+            ...codec.header.definition,
+            storage_id: { type: 'integer', primary: true },
+            storage_revision: { type: 'text', length: 36, nullable: false },
+            storage_present: { type: 'boolean', nullable: false },
+            storage_expires_at: { type: 'bigint', nullable: true },
+        });
+        for (const [name, definition] of Object.entries(codec.tables))
+            database.define(name, definition);
+    }
+    const migrated = new Set();
+    const writeRows = async (transaction, codec, rows) => {
+        for (const name of Object.keys(codec.tables)) {
+            const model = transaction.model(name);
+            await model.delete().where({});
+            for (const row of rows[name] ?? [])
+                await model.insert(row);
+        }
+    };
+    const migrate = async (codec) => {
+        if (migrated.has(codec.key))
+            return;
+        // Read outside the transaction: the old port may use another connection.
+        const old = await legacy.get(codec.key);
+        await retryRelationalOperation(() => database.transaction(async (transaction) => {
+            const model = transaction.model(codec.header.table);
+            if ((await model.select().where({ storage_id: 1 }))[0])
+                return;
+            const encoded = old === undefined ? { header: {}, rows: {} } : codec.encode(old);
+            await model.insert({ ...encoded.header, storage_id: 1, storage_revision: randomUUID(),
+                storage_present: old !== undefined, storage_expires_at: null });
+            await writeRows(transaction, codec, encoded.rows);
+        }));
+        // A durable header is the cutover marker, including an empty/deleted book.
+        // Cleanup failure is safe to retry; never reimport an old deleted task.
+        await retryRelationalOperation(() => legacy.delete(codec.key));
+        migrated.add(codec.key);
+    };
+    return new PluginStateStore(database.owner, {
+        async read(_owner, scope, key) {
+            const codec = byKey.get(key);
+            if (!codec || scope.kind !== 'plugin')
+                throw new Error(`Unregistered relational state key: ${key}`);
+            await migrate(codec);
+            return retryRelationalOperation(() => database.transaction(async (transaction) => {
+                const header = (await transaction.model(codec.header.table).select().where({ storage_id: 1 }))[0];
+                if (!header)
+                    throw new Error('Relational state header is missing');
+                const rows = {};
+                for (const name of Object.keys(codec.tables))
+                    rows[name] = await transaction.model(name).select().orderBy('position');
+                return { revision: String(header.storage_revision),
+                    value: header.storage_present ? codec.decode(header, rows) : null,
+                    // Tombstones must remain visible to CAS, but appear absent to the updater.
+                    expiresAt: header.storage_present ? (header.storage_expires_at == null ? null : Number(header.storage_expires_at)) : 0 };
+            }));
+        },
+        async compareExchange(_owner, scope, key, revision, value, expiresAt) {
+            const codec = byKey.get(key);
+            if (!codec || scope.kind !== 'plugin')
+                throw new Error(`Unregistered relational state key: ${key}`);
+            if (revision === undefined)
+                throw new Error('Relational state must be read before CAS');
+            try {
+                return await database.transaction(async (transaction) => {
+                    const encoded = value === undefined ? { header: {}, rows: {} } : codec.encode(value);
+                    const changed = await transaction.model(codec.header.table).update({ ...encoded.header,
+                        storage_revision: randomUUID(), storage_present: value !== undefined, storage_expires_at: expiresAt,
+                    }).where({ storage_id: 1, storage_revision: revision });
+                    if (changed !== 1)
+                        return false;
+                    await writeRows(transaction, codec, encoded.rows);
+                    return true;
+                });
+            }
+            catch (error) {
+                if (!isRelationalContention(error))
+                    throw error;
+                await setImmediate();
+                return false;
+            }
+        },
+    });
+}
+/** Only for pure database mutations; never wrap external sends or arbitrary side effects. */
+export async function retryRelationalOperation(operation) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= 63 || !isRelationalContention(error))
+                throw error;
+            await setImmediate();
+        }
+    }
+}
+/** Constraint races and serialization conflicts may replay the pure updater. */
+function isRelationalContention(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const value = error;
+    return ['40001', '40P01', '23505', 'SQLITE_BUSY', 'SQLITE_BUSY_SNAPSHOT', 'SQLITE_CONSTRAINT_PRIMARYKEY', 'SQLITE_CONSTRAINT_UNIQUE', 'ER_DUP_ENTRY', 'ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT'].includes(value.code ?? '')
+        || [1062, 1213, 1205].includes(value.errno ?? 0)
+        || [5, 517, 1555, 2067].includes(value.errcode ?? 0)
+        || (value.cause !== undefined && isRelationalContention(value.cause));
+}

package/lib/task-storage.d.ts

@@ -0,0 +1,74 @@
+import { type DeliveryTarget } from './delivery-target.js';
+/** Reversible SQL text encoding, including endpoint ids containing NUL. */
+export declare function encodeStorageIdentity(value: string): string;
+export declare function decodeStorageIdentity(value: unknown): string;
+export declare const TASK_TARGET_COLUMNS: {
+    readonly endpoint_adapter: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly endpoint_id: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly conversation_kind: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly conversation_id: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly parent_kind: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly parent_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly thread_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+};
+export declare function encodeTaskTarget(target: DeliveryTarget): Record<string, unknown>;
+export declare function decodeTaskTarget(row: Record<string, unknown>): DeliveryTarget;
+export declare const TASK_RECEIPT_COLUMNS: {
+    readonly id: {
+        readonly type: "text";
+        readonly length: 128;
+        readonly primary: true;
+    };
+    readonly position: {
+        readonly type: "integer";
+        readonly nullable: false;
+    };
+    readonly fingerprint: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly nullable: false;
+    };
+    readonly task_id: {
+        readonly type: "text";
+        readonly length: 128;
+        readonly nullable: false;
+    };
+    readonly operation: {
+        readonly type: "text";
+        readonly length: 32;
+        readonly nullable: false;
+    };
+};
+export declare function encodeTaskReceipts(receipts: readonly {
+    id: string;
+    fingerprint: string;
+    taskId: string;
+    operation: string;
+}[]): Record<string, unknown>[];
+export declare function decodeTaskReceipts(rows: readonly Record<string, unknown>[]): {
+    id: string;
+    fingerprint: string;
+    taskId: string;
+    operation: string;
+}[];

package/lib/task-storage.js

@@ -0,0 +1,41 @@
+import { normalizeDeliveryTarget } from './delivery-target.js';
+/** Reversible SQL text encoding, including endpoint ids containing NUL. */
+export function encodeStorageIdentity(value) {
+    return `k1:${value.replaceAll('%', '%25').replaceAll('\0', '%00')}`;
+}
+export function decodeStorageIdentity(value) {
+    if (typeof value !== 'string' || !value.startsWith('k1:'))
+        throw new Error('Invalid stored identity');
+    return value.slice(3).replaceAll('%00', '\0').replaceAll('%25', '%');
+}
+export const TASK_TARGET_COLUMNS = {
+    endpoint_adapter: { type: 'text', nullable: false }, endpoint_id: { type: 'text', nullable: false },
+    conversation_kind: { type: 'text', nullable: false }, conversation_id: { type: 'text', nullable: false },
+    parent_kind: { type: 'text', nullable: true }, parent_id: { type: 'text', nullable: true },
+    thread_id: { type: 'text', nullable: true },
+};
+export function encodeTaskTarget(target) {
+    const value = normalizeDeliveryTarget(target);
+    return { endpoint_adapter: encodeStorageIdentity(value.endpoint.adapter), endpoint_id: encodeStorageIdentity(value.endpoint.id),
+        conversation_kind: value.kind, conversation_id: encodeStorageIdentity(value.id),
+        parent_kind: value.parent?.kind ?? null, parent_id: value.parent ? encodeStorageIdentity(value.parent.id) : null,
+        thread_id: value.threadId === undefined ? null : encodeStorageIdentity(value.threadId) };
+}
+export function decodeTaskTarget(row) {
+    return normalizeDeliveryTarget({ endpoint: { adapter: decodeStorageIdentity(row.endpoint_adapter), id: decodeStorageIdentity(row.endpoint_id) },
+        kind: row.conversation_kind, id: decodeStorageIdentity(row.conversation_id),
+        ...(row.parent_kind == null ? {} : { parent: { kind: row.parent_kind, id: decodeStorageIdentity(row.parent_id) } }),
+        ...(row.thread_id == null ? {} : { threadId: decodeStorageIdentity(row.thread_id) }) });
+}
+export const TASK_RECEIPT_COLUMNS = {
+    id: { type: 'text', length: 128, primary: true }, position: { type: 'integer', nullable: false },
+    fingerprint: { type: 'text', length: 64, nullable: false }, task_id: { type: 'text', length: 128, nullable: false },
+    operation: { type: 'text', length: 32, nullable: false },
+};
+export function encodeTaskReceipts(receipts) {
+    return receipts.map((receipt, position) => ({ id: receipt.id, fingerprint: receipt.fingerprint,
+        task_id: receipt.taskId, operation: receipt.operation, position }));
+}
+export function decodeTaskReceipts(rows) {
+    return rows.map(row => ({ id: String(row.id), fingerprint: String(row.fingerprint), taskId: String(row.task_id), operation: String(row.operation) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",