@zhin.js/plugin-runtime 1.1.17 → 1.1.18

package/lib/admission.d.ts

@@ -1,13 +1,15 @@
 export declare class GenerationAdmissionGate {
     #private;
     get active(): boolean;
+    /** Root closure fact, bound at first publication and retained after generation retirement. */
+    get stopSignal(): AbortSignal | undefined;
     acquire(): (() => void) | undefined;
     /** Observe the first commit which publishes this generation. */
     onActivate(listener: () => void): () => void;
     /**
      * Observe retirement of the generation that owns this gate. The callback is
-     * synchronous and must not fail; it is intended for closing process-owned
-     * ingress transports such as WebSocket connections.
+     * synchronous and must not fail. It closes new admission; it does not decide
+     * whether already-owned transports or work should end. Use stopSignal for Root shutdown.
      */
     onDeactivate(listener: () => void): () => void;
     enter<T>(operation: () => T): T | undefined;
@@ -26,4 +28,14 @@ export interface GenerationAdmissionSource {
 }
 export declare function bindGenerationAdmission<T>(value: T, gate: GenerationAdmissionGate): T;
 export declare function collectGenerationAdmissions(values: Iterable<unknown>): ReadonlySet<GenerationAdmissionGate>;
-export declare function replaceGenerationAdmissions(previous: ReadonlySet<GenerationAdmissionGate>, next: ReadonlySet<GenerationAdmissionGate>, owner: object, publishNext: () => void, acquireNext?: () => () => void): void;
+/** One SnapshotStore-owned publication; all gates share that Root's explicit close fact. */
+interface GenerationAdmissionTransition {
+    readonly previous: ReadonlySet<GenerationAdmissionGate>;
+    readonly next: ReadonlySet<GenerationAdmissionGate>;
+    readonly owner: object;
+    readonly publishNext: () => void;
+    readonly acquireNext?: () => () => void;
+    readonly stopSignal: AbortSignal;
+}
+export declare function replaceGenerationAdmissions({ previous, next, owner, publishNext, acquireNext, stopSignal }: GenerationAdmissionTransition): void;
+export {};

package/lib/admission.js

@@ -5,13 +5,14 @@ let admissionLifecycle;
 export class GenerationAdmissionGate {
     #state = { active: false };
     #owner;
+    #stopSignal;
     #activationListeners = new Set();
     #deactivationListeners = new Set();
     static {
         admissionLifecycle = {
             assertClaimable: (gate, owner) => gate.#assertClaimable(owner),
             assertOwner: (gate, owner) => gate.#assertOwner(owner),
-            claim: (gate, owner) => { gate.#owner = owner; },
+            claim: (gate, owner, stopSignal) => { gate.#owner = owner; gate.#stopSignal = stopSignal; },
             activate: (gate, acquire) => gate.#activate(acquire),
             deactivate: (gate) => gate.#deactivate(),
             notifyActivation: (gate) => gate.#notifyActivation(),
@@ -21,6 +22,10 @@ export class GenerationAdmissionGate {
     get active() {
         return this.#state.active;
     }
+    /** Root closure fact, bound at first publication and retained after generation retirement. */
+    get stopSignal() {
+        return this.#stopSignal;
+    }
     acquire() {
         return this.#state.active ? this.#state.acquire?.() : undefined;
     }
@@ -35,8 +40,8 @@ export class GenerationAdmissionGate {
     }
     /**
      * Observe retirement of the generation that owns this gate. The callback is
-     * synchronous and must not fail; it is intended for closing process-owned
-     * ingress transports such as WebSocket connections.
+     * synchronous and must not fail. It closes new admission; it does not decide
+     * whether already-owned transports or work should end. Use stopSignal for Root shutdown.
      */
     onDeactivate(listener) {
         if (!this.active) {
@@ -136,7 +141,7 @@ export function collectGenerationAdmissions(values) {
     }
     return result;
 }
-export function replaceGenerationAdmissions(previous, next, owner, publishNext, acquireNext) {
+export function replaceGenerationAdmissions({ previous, next, owner, publishNext, acquireNext, stopSignal }) {
     // Validate the complete switch before changing ownership or visibility. A
     // rejected cross-Root gate must leave both generations exactly untouched.
     for (const gate of next)
@@ -148,7 +153,7 @@ export function replaceGenerationAdmissions(previous, next, owner, publishNext,
     // potentially rejecting ownership check has completed before publication.
     publishNext();
     for (const gate of next)
-        admissionLifecycle.claim(gate, owner);
+        admissionLifecycle.claim(gate, owner, stopSignal);
     for (const gate of previous) {
         if (next.has(gate))
             continue;

package/lib/data-migration.d.ts

@@ -0,0 +1,105 @@
+import type { DeliveryTarget } from './delivery-target.js';
+import type { GenerationAdmissionSource } from './admission.js';
+import type { JsonValue } from './persistent-state.js';
+/** Read-only, owner-namespaced historical data; candidate IDs are opaque to the Host. */
+export interface DataMigrationCandidate {
+    readonly id: string;
+    readonly domain: string;
+    readonly title: string;
+    readonly sourceVersion: string;
+    readonly recordCount: number;
+    readonly beforeDigest: string;
+    readonly status: 'unresolved' | 'canonical' | 'corrupt';
+    /** Display facts only; never a preselected account or recovered authorization. */
+    readonly summary: Readonly<Record<string, JsonValue>>;
+    /** False when the configured persistence cannot supply the required atomic unit. */
+    readonly executable: boolean;
+}
+export interface DataMigrationInventory {
+    readonly revision: string;
+    readonly candidates: readonly DataMigrationCandidate[];
+}
+export interface DataMigrationRequest {
+    readonly signal?: AbortSignal;
+}
+export interface PrepareDataMigrationRequest extends DataMigrationRequest {
+    /** Host-generated operation UUID; reused to reconcile a lost response. */
+    readonly planId: string;
+    readonly candidateId: string;
+    readonly expectedDigest: string;
+    /** Explicit administrator selection, validated by the Host against the account directory. */
+    readonly target: DeliveryTarget;
+}
+/** Domain-prepared exact unit; the Host persists the complete plan before admitting any mutation. */
+export interface DataMigrationPlan {
+    readonly id: string;
+    readonly candidateId: string;
+    readonly domain: string;
+    readonly sourceVersion: string;
+    readonly beforeDigest: string;
+    readonly target: DeliveryTarget;
+    readonly recordCount: number;
+    /** Full lossless before-images and exact domain writes, not a 64 KiB state-store value. */
+    readonly data: JsonValue;
+    readonly description: readonly string[];
+    /** These facts require fresh authorization and must never be activated by a data migration. */
+    readonly authorizationCandidates: readonly JsonValue[];
+}
+export interface ApplyDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+/** Confirmed by the same atomic domain unit as the writes; unknown commits are never blindly retried. */
+export interface DataMigrationReceipt {
+    /** Distinguishes an original commit from its explicit reversal during reconciliation. */
+    readonly operation: 'apply' | 'restore';
+    readonly planId: string;
+    readonly candidateId: string;
+    readonly beforeDigest: string;
+    readonly afterDigest: string;
+    readonly recordCount: number;
+    readonly status: 'applied' | 'already_applied';
+    readonly maintenance: 'paused';
+}
+export interface ResumeDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+export interface RestoreDataMigrationRequest extends ResumeDataMigrationRequest {
+    readonly receipt: DataMigrationReceipt;
+}
+export interface InspectDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+/** Verified current rows plus the durable maintenance journal, never inferred from a missing receipt. */
+export interface DataMigrationInspection {
+    readonly data: 'not_applied' | 'applied' | 'restored' | 'conflict' | 'unknown';
+    readonly maintenance: 'paused' | 'resumed' | 'unknown';
+    /** True only for paused, drained scopes with a verified current recovery baseline; never authorizes data writes. */
+    readonly resumable: boolean;
+    /** A committed write receipt is not evidence that maintenance has resumed. */
+    readonly receipt?: DataMigrationReceipt;
+}
+/** Plugin owns record semantics, maintenance admission/drain and the existing transactional store. */
+export interface PluginDataMigrationProvider extends GenerationAdmissionSource {
+    readonly title: string;
+    preview(request?: DataMigrationRequest): Promise<DataMigrationInventory>;
+    prepare(request: PrepareDataMigrationRequest): Promise<DataMigrationPlan>;
+    /** Enter the selected scope's maintenance, drain work, recheck and commit; leave it paused. */
+    apply(request: ApplyDataMigrationRequest): Promise<DataMigrationReceipt>;
+    /** Pure authoritative inspection; an in-flight mutation or unprovable state remains unknown. */
+    inspect(request: InspectDataMigrationRequest): Promise<DataMigrationInspection>;
+    /** Explicit resumption never starts an account, replays delivery or extends a game deadline. */
+    resume(request: ResumeDataMigrationRequest): Promise<void>;
+    /** Restore only when the actual rows still match the confirmed after-image; remain paused. */
+    restore(request: RestoreDataMigrationRequest): Promise<DataMigrationReceipt>;
+}
+/**
+ * commit_unknown means the data commit result is unconfirmed. invalid_input/conflict/unsupported/
+ * not_found guarantee no data commit by this invocation, but do not imply maintenance was released.
+ * unavailable does not establish either outcome. Inspect before recovery; never blindly replay.
+ */
+export declare class DataMigrationError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'unsupported' | 'unavailable' | 'not_found' | 'commit_unknown';
+    constructor(code: 'invalid_input' | 'conflict' | 'unsupported' | 'unavailable' | 'not_found' | 'commit_unknown', message: string);
+}
+/** Existing owner Resource discovery, not a process-global migration registry. */
+export declare const pluginDataMigrationProviderToken: import("./token.js").Token<PluginDataMigrationProvider>;

package/lib/data-migration.js

@@ -0,0 +1,16 @@
+import { createToken } from './token.js';
+/**
+ * commit_unknown means the data commit result is unconfirmed. invalid_input/conflict/unsupported/
+ * not_found guarantee no data commit by this invocation, but do not imply maintenance was released.
+ * unavailable does not establish either outcome. Inspect before recovery; never blindly replay.
+ */
+export class DataMigrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DataMigrationError';
+    }
+}
+/** Existing owner Resource discovery, not a process-global migration registry. */
+export const pluginDataMigrationProviderToken = createToken('zhin.plugin-data-migration', 'Plugin-owned historical data migration, controlled by authenticated Host operations');

package/lib/index.d.ts

@@ -5,6 +5,10 @@
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
+/** @internal Shared accepted-owner frame; no additional admission or task registry. */
+export { OwnerOperation } from './owner-operation.js';
+/** @internal Runtime-owned delivery authority; author contexts expose subscriptions only. */
+export { createPluginEventChannel, type PluginEventChannel } from './plugin-events.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionBindable, type GenerationAdmissionSource, } from './admission.js';
 export * from './handoff.js';
@@ -41,3 +45,5 @@ export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
 export * from './task-storage.js';
 export * from './plugin-console-rpc.js';
+export * from './data-migration.js';
+export * from './relational-target-migration.js';

package/lib/index.js

@@ -5,6 +5,10 @@
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
+/** @internal Shared accepted-owner frame; no additional admission or task registry. */
+export { OwnerOperation } from './owner-operation.js';
+/** @internal Runtime-owned delivery authority; author contexts expose subscriptions only. */
+export { createPluginEventChannel } from './plugin-events.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, } from './admission.js';
 export * from './handoff.js';
@@ -41,3 +45,5 @@ export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
 export * from './task-storage.js';
 export * from './plugin-console-rpc.js';
+export * from './data-migration.js';
+export * from './relational-target-migration.js';

package/lib/outbound-host.d.ts

@@ -30,22 +30,16 @@ export interface OutboundSendInput {
     readonly content: string;
 }
 export interface OutboundReactionInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
     readonly emoji: string;
     readonly sceneType?: string;
     readonly channelId?: string;
 }
 export interface OutboundRemoveReactionInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
     readonly reactionId: string;
 }
 export interface OutboundRecallInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
 }
 export type OutboundEndpointOperation = 'recall' | 'edit' | 'reaction' | 'typing';
@@ -56,11 +50,11 @@ export interface OutboundEndpointInput {
 export interface OutboundEndpointCapabilities {
     readonly operations: readonly OutboundEndpointOperation[];
 }
-export interface OutboundEditInput extends OutboundEndpointInput {
+export interface OutboundEditInput {
     readonly message: OutboundMessage;
     readonly content: unknown;
 }
-export interface OutboundTypingInput extends OutboundEndpointInput {
+export interface OutboundTypingInput {
     readonly conversation: OutboundMessage['conversation'];
     readonly active?: boolean;
 }
@@ -74,7 +68,34 @@ export interface OutboundMessage {
     }>;
     readonly id: string;
 }
+/** Retain a real source Client while its inbound operation is active. Never serialize this input. */
+export interface OutboundCaptureInput {
+    readonly target: DeliveryTarget;
+    readonly client: unknown;
+    readonly signal?: AbortSignal;
+}
+/** Messaging effects bound to one source incarnation, independent of reusable account names. */
+export interface CapturedOutboundOperation {
+    readonly target: DeliveryTarget;
+    readonly signal: AbortSignal;
+    send(content: unknown, options?: Readonly<{
+        locale?: Locale;
+        signal?: AbortSignal;
+    }>): Promise<string | null>;
+    recall?(message: OutboundMessage): Promise<void>;
+    edit?(message: OutboundMessage, content: unknown): Promise<string | null>;
+    addReaction?(message: OutboundMessage, emoji: string, hint?: Readonly<{
+        sceneType?: string;
+        channelId?: string;
+    }>): Promise<string | null>;
+    removeReaction?(message: OutboundMessage, reactionId: string): Promise<void>;
+    typing?(conversation: OutboundMessage['conversation'], active?: boolean): Promise<void>;
+    /** Release the captured source and Root leases on every completion path. */
+    release(): void;
+}
 export interface OutboundHost {
+    /** Creates source-bound effects; ordinary persisted sends continue using sendTarget. */
+    captureOperation?(input: OutboundCaptureInput): CapturedOutboundOperation;
     /** Sends to persisted exact identities, rejecting stale addresses instead of aliasing another bot. */
     sendTarget?(target: DeliveryTarget, content: unknown, options?: Readonly<{
         locale?: Locale;
@@ -99,7 +120,8 @@ export interface OutboundHost {
     typing?(input: OutboundTypingInput): Promise<void>;
 }
 /** Root-only process port: requester is supplied by the owner-bound facade. */
-export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget'> {
+export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget' | 'captureOperation'> {
+    captureOperation?(input: OutboundCaptureInput, requester: PluginId): CapturedOutboundOperation;
     sendTarget?(target: DeliveryTarget, content: unknown, requester: PluginId, options?: Readonly<{
         locale?: Locale;
     }>): Promise<string | null>;
@@ -107,6 +129,7 @@ export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget'> {
 /** Preserve the sending plugin as requester, independent of the destination endpoint owner. */
 export declare class PluginOutboundHost implements OutboundHost {
     #private;
+    readonly captureOperation?: OutboundHost['captureOperation'];
     readonly sendTarget?: OutboundHost['sendTarget'];
     readonly runWithView?: OutboundHost['runWithView'];
     readonly capabilities?: OutboundHost['capabilities'];

package/lib/outbound-host.js

@@ -3,6 +3,7 @@ import { generationAdmissionBinder, generationAdmissionSource } from './admissio
 import { OwnerOperation } from './owner-operation.js';
 /** Preserve the sending plugin as requester, independent of the destination endpoint owner. */
 export class PluginOutboundHost {
+    captureOperation;
     sendTarget;
     runWithView;
     capabilities;
@@ -20,6 +21,8 @@ export class PluginOutboundHost {
         this.#host = host;
         this.#admission = admission;
         this.#operation = new OwnerOperation(admission, 'Outbound');
+        const captureOperation = host.captureOperation?.bind(host);
+        this.captureOperation = captureOperation ? input => this.#run(() => captureOperation(input, this.#owner)) : undefined;
         const sendTarget = host.sendTarget?.bind(host);
         const runWithView = host.runWithView?.bind(host);
         const capabilities = host.capabilities?.bind(host);

package/lib/plugin-console-rpc.d.ts

@@ -1,4 +1,5 @@
 import { type GenerationAdmissionSource } from './admission.js';
+import type { PluginId, FeatureId } from './identity.js';
 import type { JsonValue } from './persistent-state.js';
 /**
  * Plugin-registered Console RPC (zhinjs/zhin#970).
@@ -22,6 +23,15 @@ export type PluginConsoleRpcInput = Readonly<Record<string, JsonValue>>;
 export interface PluginConsoleRpcCall {
     /** Aborted when the Host request times out. Long work must observe it. */
     readonly signal: AbortSignal;
+    /** Authenticated operation view; no snapshot, configuration, resource or private resolver access. */
+    readonly runtime?: Readonly<{
+        owner: PluginId;
+        generation: number;
+        operator: boolean;
+        project(feature: FeatureId): unknown;
+    }>;
+    /** Framework-only request-local notification before a validated durable mutation begins. */
+    commitStarted?(): void;
 }
 export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput> {
     /** Local name of a Page owned by the same plugin (`pages/<page>/index.tsx`). Its access rules apply. */
@@ -77,7 +87,7 @@ export interface PluginConsoleRpc extends GenerationAdmissionSource {
 }
 /** Safe, user-facing failure. `message` is shown in the Console; never put raw errors in it. */
 export declare class PluginConsoleRpcError extends Error {
-    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable';
+    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable' | 'forbidden' | 'commit_unknown';
     constructor(code: PluginConsoleRpcError['code'], message: string);
 }
 export declare const pluginConsoleRpcToken: import("./token.js").Token<PluginConsoleRpc>;

package/lib/plugin-events.d.ts

@@ -0,0 +1,47 @@
+import type { Dispose } from './dispose.js';
+import type { CapabilityId, PluginId } from './identity.js';
+/** Planned invalidation is distinct from the instances actually replaced at commit. */
+export interface HmrReloadScope {
+    readonly fullRoot: boolean;
+    readonly plugins: readonly PluginId[];
+    readonly capabilities: readonly CapabilityId[];
+}
+export interface HmrEventDetails {
+    readonly trigger: 'manual' | 'source';
+    readonly changed: readonly string[];
+    readonly planned: HmrReloadScope;
+    readonly previousGeneration: number;
+    readonly activeGeneration: number;
+    readonly receiver: Readonly<{
+        owner: PluginId;
+        creationGeneration: number;
+        state: 'current' | 'replaced';
+    }>;
+}
+export type HmrOutcome = 'committed' | 'unchanged' | 'rejected' | 'cancelled' | 'restart-required';
+export interface HmrResumeDetails extends HmrEventDetails {
+    readonly outcome: HmrOutcome;
+    readonly reason?: 'root-stopping';
+    readonly replaced: readonly PluginId[];
+}
+/** A control-phase signal, not a command to cancel the plugin's accepted business work. */
+export interface PluginLifecycleEvent<TDetails> {
+    readonly signal: AbortSignal;
+    readonly details: Readonly<TDetails>;
+}
+export interface PluginLifecycleEventMap {
+    readonly 'hmr.pause': PluginLifecycleEvent<HmrEventDetails>;
+    readonly 'hmr.resume': PluginLifecycleEvent<HmrResumeDetails>;
+}
+export interface PluginEventSubscriptions {
+    /** Subscription belongs to this concrete plugin instance, including when its Scope is reused. */
+    on<TName extends keyof PluginLifecycleEventMap>(name: TName, handler: (event: PluginLifecycleEventMap[TName]) => void | Promise<void>): Dispose;
+}
+/** @internal Runtime delivery authority; never exposed through a setup context or resource snapshot. */
+export interface PluginEventChannel {
+    readonly events: PluginEventSubscriptions;
+    dispatch<TName extends keyof PluginLifecycleEventMap>(name: TName, event: PluginLifecycleEventMap[TName]): Promise<void>;
+    dispose(): void;
+}
+/** @internal One instance-owned subscription record; no inherited or process-wide listener registry. */
+export declare function createPluginEventChannel(): PluginEventChannel;

package/lib/plugin-events.js

@@ -0,0 +1,30 @@
+/** @internal One instance-owned subscription record; no inherited or process-wide listener registry. */
+export function createPluginEventChannel() {
+    const handlers = {
+        'hmr.pause': new Set(), 'hmr.resume': new Set(),
+    };
+    let disposed = false;
+    return Object.freeze({
+        events: Object.freeze({
+            on(name, handler) {
+                if (disposed)
+                    throw new Error('Plugin event subscriptions are disposed');
+                handlers[name].add(handler);
+                return () => { handlers[name].delete(handler); };
+            },
+        }),
+        async dispatch(name, event) {
+            if (disposed)
+                throw new Error('Plugin event subscriptions are disposed');
+            const results = await Promise.allSettled([...handlers[name]].map(handler => Promise.resolve().then(() => handler(event))));
+            const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+            if (errors.length)
+                throw new AggregateError(errors, `Plugin ${name} handlers failed`);
+        },
+        dispose() {
+            disposed = true;
+            handlers['hmr.pause'].clear();
+            handlers['hmr.resume'].clear();
+        },
+    });
+}

package/lib/plugin.d.ts

@@ -6,6 +6,7 @@ import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
+import type { PluginEventSubscriptions } from './plugin-events.js';
 export interface PluginMetadata {
     readonly displayName?: string;
     readonly icon?: string;
@@ -27,6 +28,7 @@ export interface PluginInstanceView {
     readonly role: 'root' | 'child';
 }
 export interface PluginSetupContext<TConfig = unknown> {
+    readonly events: PluginEventSubscriptions;
     readonly signal: AbortSignal;
     readonly plugin: PluginInstanceView;
     readonly config: ConfigView<TConfig>;
@@ -40,6 +42,7 @@ export interface PluginSetupContext<TConfig = unknown> {
      */
     addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
+export { type PluginEventSubscriptions, type PluginLifecycleEvent, type PluginLifecycleEventMap, type HmrEventDetails, type HmrResumeDetails, type HmrReloadScope, type HmrOutcome, } from './plugin-events.js';
 export interface PluginDefinition<TConfig = unknown> {
     readonly name: string;
     readonly config?: PluginConfigSchema<TConfig>;
@@ -69,5 +72,7 @@ export declare function definePlugin<TConfig = unknown>(definition: PluginDefini
 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 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 { outboundHostToken, type OutboundConversation, type OutboundEditInput, type OutboundEndpointCapabilities, type OutboundEndpointInput, type OutboundEndpointOperation, type OutboundHost, type OutboundCaptureInput, type CapturedOutboundOperation, 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';
+export { DataMigrationError, pluginDataMigrationProviderToken, type DataMigrationCandidate, type DataMigrationInventory, type DataMigrationRequest, type PrepareDataMigrationRequest, type DataMigrationPlan, type ApplyDataMigrationRequest, type DataMigrationReceipt, type ResumeDataMigrationRequest, type RestoreDataMigrationRequest, type InspectDataMigrationRequest, type DataMigrationInspection, type PluginDataMigrationProvider, } from './data-migration.js';
+export { TargetMigrationScopes, targetMigrationDigest, orderedMigrationRows, createRelationalTargetMigration, type TargetMigrationRows, type TargetMigrationWrite, type RelationalTargetMigrationUnit, type RelationalTargetMigrationOptions, } from './relational-target-migration.js';

package/lib/plugin.js

@@ -36,3 +36,5 @@ export { PluginStateStore } from './persistent-state.js';
 export { databaseHostToken, PluginDatabaseHost, } from './database-host.js';
 export { outboundHostToken, } from './outbound-host.js';
 export { scheduleHostToken, PluginScheduleHost, } from './schedule-host.js';
+export { DataMigrationError, pluginDataMigrationProviderToken, } from './data-migration.js';
+export { TargetMigrationScopes, targetMigrationDigest, orderedMigrationRows, createRelationalTargetMigration, } from './relational-target-migration.js';

package/lib/relational-target-migration.d.ts

@@ -0,0 +1,68 @@
+import type { DatabaseHostTransaction, PluginDatabaseHost } from './database-host.js';
+import { type DeliveryTarget } from './delivery-target.js';
+import { type DataMigrationCandidate, type PluginDataMigrationProvider } from './data-migration.js';
+import type { JsonValue } from './persistent-state.js';
+type Row = Record<string, unknown>;
+/** One business-key row set; identical keyless rows remain an indivisible group. */
+export interface TargetMigrationRows {
+    readonly table: string;
+    readonly query: Readonly<Row>;
+    readonly rows: readonly Row[];
+}
+export interface TargetMigrationWrite {
+    readonly before: TargetMigrationRows;
+    readonly after: TargetMigrationRows;
+    readonly patch: Readonly<Row>;
+}
+export interface RelationalTargetMigrationUnit {
+    readonly id: string;
+    readonly title: string;
+    readonly scope: string;
+    readonly status: DataMigrationCandidate['status'];
+    readonly records: readonly TargetMigrationRows[];
+    readonly summary: Readonly<Record<string, JsonValue>>;
+    readonly authorizationCandidates?: readonly JsonValue[];
+}
+export interface RelationalTargetMigrationOptions {
+    /** Owner-qualified Host facade; raw process tables never enter the provider. */
+    readonly database: PluginDatabaseHost;
+    readonly domain: string;
+    readonly title: string;
+    readonly sourceVersion: string;
+    /** All tables that this domain is allowed to read or change. */
+    readonly tables: readonly string[];
+    readonly scopes: TargetMigrationScopes;
+    readUnits(reader: DatabaseHostTransaction): Promise<readonly RelationalTargetMigrationUnit[]>;
+    /** Rewrites routing only. Domain state, deadlines, IDs and revision fields are retained. */
+    rewrite(unit: RelationalTargetMigrationUnit, target: DeliveryTarget): {
+        readonly writes: readonly TargetMigrationWrite[];
+        readonly destinationScope: string;
+    };
+}
+/** Stable, lossless digest; this does not impose the small-object StateStore size limit. */
+export declare function targetMigrationDigest(value: unknown): string;
+export declare function orderedMigrationRows(rows: readonly Row[]): readonly Row[];
+/** Per-instance scope admission. Existing work drains; unrelated scopes continue. */
+export declare class TargetMigrationScopes {
+    #private;
+    constructor(input: Readonly<{
+        pending: (scope: string) => boolean;
+    }>);
+    bindInitialization(initialize: () => Promise<void>): void;
+    run<T>(input: Readonly<{
+        scope: string;
+        run: () => Promise<T>;
+    }>): Promise<T>;
+    pause(input: Readonly<{
+        planId: string;
+        scopes: readonly string[];
+        persist: () => Promise<void>;
+    }>): Promise<void>;
+    drained(scopes: readonly string[]): boolean;
+    maintenance(planId: string, scopes: readonly string[]): 'paused' | 'resumed' | 'unknown';
+    restorePause(planId: string, scopes: readonly string[]): void;
+    resume(planId: string, scopes: readonly string[]): void;
+}
+/** Shared only by the concrete game and subscription target migrations. No raw-SQL or generic schema discovery. */
+export declare function createRelationalTargetMigration(options: RelationalTargetMigrationOptions): PluginDataMigrationProvider;
+export {};