@zhin.js/plugin-runtime 1.1.14 → 1.1.16

package/README.md

@@ -27,8 +27,20 @@ prepare shadow state -> validate -> handoff -> atomic commit
 局部 HMR 只缩小 prepare/setup/dispose 范围；每次 commit 始终发布完整一致的 snapshot。
 长期 socket、worker 或 admission loop 必须参加 generation handoff，不能成为模块级副作用。
 
+`SnapshotReader.acquire()` 返回的 `SnapshotLease.retirementSignal` 在该运行代被新一代替换、
+或 Root 关闭时同步触发，即使仍有 lease 持有旧资源。它供交互等待等需要随代结束的操作主动取消；
+不会代替 `lease.release()`、强制中断普通旧操作或提前销毁资源。被拒绝的候选不会触发当前代的信号。
+
 本包没有生产依赖。YAML、AJV、watcher、IM 与 AI 都属于上层 adapter 或 Runtime。
 
+## 可选管理员任务端口
+
+`PluginTaskProvider` 与 `pluginTaskProviderToken` 定义插件自己的管理员任务服务：插件通过 `provide()` 发布，Host 从当前运行代的所属 Scope 读取，不额外建立调度器。聊天发送者的个人任务不进入这个端口。
+
+任务快照包含真实任务、`revision` 与有界持久 `receipts`。创建或修改提交客户端操作 UUID 和原 `expectedRevision`；同一操作必须按相同内容幂等核对，不同内容复用 ID 或过期版本均应拒绝。回执确认的是持久命令，不是外部消息投递。未拿到响应时先只读核对，不能自动重发。服务必须携带 `generationAdmissionSource` 并参与实例退役。
+
+`PluginTaskError.message` 是可以向管理员展示的业务说明，不应含凭据或原始异常。Host 自己的输入、权限与运行代校验使用固定说明，普通异常不直接暴露。任务使用已有 `DeliveryTarget` 保留完整账号、会话、父容器与话题；`actions` 只列实际支持的操作，`unknown` 状态不能被包装成可安全重试。
+
 验证：`pnpm --filter @zhin.js/plugin-runtime test && pnpm --filter @zhin.js/plugin-runtime build`。
 
 详细契约见 [Kernel 与 Generation](../../../docs/architecture/target-implementation/kernel-and-generation.md)。

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,6 +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,6 +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-configuration.d.ts

@@ -1,4 +1,4 @@
-/** Canonical `zhin.config.*#plugins` shape keyed by Plugin instanceKey. */
+/** Plugin business configuration keyed by the aliases in a v2 application declaration. */
 export type PluginConfigurationMap = Readonly<Record<string, unknown>>;
 /** Raised when a Root config still uses a non-canonical Plugin configuration shape. */
 export declare class PluginConfigurationShapeError extends TypeError {
@@ -6,10 +6,6 @@ export declare class PluginConfigurationShapeError extends TypeError {
     constructor(source?: string);
 }
 /**
- * Reads the canonical Plugin instance configuration map.
- *
- * An omitted `plugins` key means that the Root has no configured child instances.
- * Every present value must be an object map; legacy package-name arrays belong only
- * to the explicit migration pipeline.
+ * Projects top-level business blocks for the declared application instances.
  */
 export declare function readPluginConfigurationMap(document: Readonly<Record<string, unknown>>, source?: string): PluginConfigurationMap;

package/lib/plugin-configuration.js

@@ -9,18 +9,20 @@ export class PluginConfigurationShapeError extends TypeError {
     }
 }
 /**
- * Reads the canonical Plugin instance configuration map.
- *
- * An omitted `plugins` key means that the Root has no configured child instances.
- * Every present value must be an object map; legacy package-name arrays belong only
- * to the explicit migration pipeline.
+ * Projects top-level business blocks for the declared application instances.
  */
 export function readPluginConfigurationMap(document, source = 'Root config') {
+    if (document.configVersion !== 2) {
+        throw new TypeError(`${source}.configVersion must be 2; see docs/migrations/plugin-instance-declarations.md`);
+    }
     const value = document.plugins;
     if (value === undefined)
         return EMPTY_PLUGIN_CONFIGURATION;
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new PluginConfigurationShapeError(source);
     }
-    return value;
+    if (Object.values(value).some(reference => typeof reference !== 'string' || reference.length === 0)) {
+        throw new TypeError(`${source}.plugins must map instance aliases to package strings`);
+    }
+    return Object.freeze(Object.fromEntries(Object.keys(value).map(key => [key, document[key] === undefined ? {} : document[key]])));
 }

package/lib/plugin-tasks.d.ts

@@ -0,0 +1,62 @@
+import type { DeliveryTarget } from './delivery-target.js';
+import type { JsonValue } from './persistent-state.js';
+import type { GenerationAdmissionSource } from './admission.js';
+export type PluginTaskState = 'scheduled' | 'paused' | 'running' | 'unknown' | 'succeeded' | 'failed' | 'cancelled';
+export type PluginTaskAction = 'pause' | 'resume' | 'cancel' | 'update';
+/** Business task facts. Chat-user tasks are deliberately outside this administrator port. */
+export interface PluginTask {
+    readonly id: string;
+    readonly ownership: 'administrator';
+    readonly title: string;
+    readonly target: DeliveryTarget;
+    readonly state: PluginTaskState;
+    readonly createdAt: number;
+    readonly nextRunAt?: number;
+    readonly lastRunAt?: number;
+    readonly timezone?: string;
+    readonly detail?: string;
+    readonly parameters: Readonly<Record<string, JsonValue>>;
+    readonly actions: readonly PluginTaskAction[];
+}
+export interface PluginTaskSnapshot {
+    /** Changes whenever facts change. A stale mutation must fail instead of overwriting. */
+    readonly revision: string;
+    readonly tasks: readonly PluginTask[];
+    /** Bounded durable mutation acknowledgements, distinct from external delivery receipts. */
+    readonly receipts: readonly PluginTaskMutationReceipt[];
+}
+export interface PluginTaskMutationReceipt {
+    readonly requestId: string;
+    readonly taskId: string;
+    readonly operation: 'create' | PluginTaskAction;
+}
+export interface PluginTaskMutation {
+    /** Client-created operation UUID, retained for reconciliation after a lost response. */
+    readonly requestId: string;
+    readonly expectedRevision: string;
+}
+/** Optional plugin-owned task service, resolved from the current generation's owner scope. */
+export interface PluginTaskProvider extends GenerationAdmissionSource {
+    readonly title: string;
+    readonly description: string;
+    /** JSON Schema for this provider's creation/update parameters, never a Console-specific form. */
+    readonly schema: Readonly<Record<string, JsonValue>>;
+    /** Discloses future external effects before the operator creates a task. */
+    readonly effects: readonly string[];
+    read(): Promise<PluginTaskSnapshot>;
+    create(input: PluginTaskMutation & Readonly<{
+        target: DeliveryTarget;
+        parameters: Readonly<Record<string, JsonValue>>;
+    }>): Promise<PluginTaskSnapshot>;
+    change(input: PluginTaskMutation & Readonly<{
+        id: string;
+        action: PluginTaskAction;
+        parameters?: Readonly<Record<string, JsonValue>>;
+    }>): Promise<PluginTaskSnapshot>;
+}
+/** message is safe business guidance for administrators; never include secrets or raw exceptions. */
+export declare class PluginTaskError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable';
+    constructor(code: PluginTaskError['code'], message: string);
+}
+export declare const pluginTaskProviderToken: import("./token.js").Token<PluginTaskProvider>;

package/lib/plugin-tasks.js

@@ -0,0 +1,11 @@
+import { createToken } from './token.js';
+/** message is safe business guidance for administrators; never include secrets or raw exceptions. */
+export class PluginTaskError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PluginTaskError';
+        this.code = code;
+    }
+}
+export const pluginTaskProviderToken = createToken('zhin.plugin-task-provider', 'Plugin-owned persistent administrator tasks, controlled only through authenticated Host operations');

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/root-config-document.d.ts

@@ -10,10 +10,13 @@ export type ConfigPatch = {
 export interface ConfigDocumentSnapshot {
     readonly document: RuntimeConfigDocument;
     readonly revision: string;
+    /** v2 declaration aliases in source order, including integer-like keys. */
+    readonly pluginOrder?: readonly string[];
 }
 /** A prepared write is inert until the generation handoff activates it. */
 export interface PreparedConfigDocument {
     readonly document: RuntimeConfigDocument;
+    readonly pluginOrder?: readonly string[];
     commit(): Promise<ConfigDocumentSnapshot>;
     rollback(): Promise<void>;
 }

package/lib/snapshot.d.ts

@@ -50,7 +50,11 @@ export declare class SnapshotLease {
     #private;
     readonly value: RuntimeSnapshot;
     private readonly releaseRecord;
-    constructor(value: RuntimeSnapshot, releaseRecord: () => void, authority: typeof snapshotLeaseAuthority);
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    readonly retirementSignal: AbortSignal;
+    constructor(value: RuntimeSnapshot, releaseRecord: () => void, authority: typeof snapshotLeaseAuthority, 
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    retirementSignal: AbortSignal);
     get active(): boolean;
     release(): void;
 }

package/lib/snapshot.js

@@ -13,10 +13,14 @@ const snapshotLeaseAuthority = Symbol('SnapshotLeaseAuthority');
 export class SnapshotLease {
     value;
     releaseRecord;
+    retirementSignal;
     #released = false;
-    constructor(value, releaseRecord, authority) {
+    constructor(value, releaseRecord, authority, 
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    retirementSignal) {
         this.value = value;
         this.releaseRecord = releaseRecord;
+        this.retirementSignal = retirementSignal;
         if (authority !== snapshotLeaseAuthority)
             throw new TypeError('SnapshotLease is owned by SnapshotStore');
     }
@@ -43,6 +47,7 @@ export class SnapshotStore {
         const committed = Object.freeze({ snapshot, state: initialState });
         const admissions = collectSnapshotAdmissions(snapshot);
         const record = {
+            retirement: new AbortController(),
             snapshot,
             state: initialState,
             committed,
@@ -65,7 +70,7 @@ export class SnapshotStore {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
         const record = this.#current;
-        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority);
+        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority, record.retirement.signal);
         this.#leases.add(lease);
         return lease;
     }
@@ -87,6 +92,7 @@ export class SnapshotStore {
         const committed = Object.freeze({ snapshot, state });
         const admissions = collectSnapshotAdmissions(snapshot);
         const next = {
+            retirement: new AbortController(),
             snapshot,
             state,
             committed,
@@ -99,6 +105,7 @@ export class SnapshotStore {
         // Commit only swaps the active pointer. The previous record may still be
         // serving in-flight work, so disposal is deferred to its final lease.
         previous.retired = true;
+        previous.retirement.abort();
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
         return this.#current.committed;
@@ -109,6 +116,7 @@ export class SnapshotStore {
         this.#closed = true;
         replaceGenerationAdmissions(this.#current.admissions, new Set(), this, () => undefined);
         this.#current.retired = true;
+        this.#current.retirement.abort();
         this.#retired.add(this.#current);
         this.#disposeIfReady(this.#current);
         // A Root is not stopped while any historical generation still owns live

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.14",
+  "version": "1.1.16",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",