@zhin.js/plugin-runtime 1.1.5 → 1.1.7

package/lib/admission.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
+ * External callbacks may enter while the owning Resource is present in the
+ * committed snapshot; candidate and retired Resources fail closed.
+ */
+export declare class GenerationAdmissionGate {
+    constructor();
+    get active(): boolean;
+    acquire(): (() => void) | undefined;
+    /**
+     * 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.
+     */
+    onDeactivate(listener: () => void): () => void;
+    enter<T>(operation: () => T): T | undefined;
+}
+export declare function createGenerationAdmissionGate(): GenerationAdmissionGate;
+/** Resource hook used by CapabilityContext to bind an ingress dependency. */
+export declare const generationAdmissionBinder: unique symbol;
+export interface GenerationAdmissionBindable<T> {
+    [generationAdmissionBinder](gate: GenerationAdmissionGate): T;
+}
+/** Snapshot value hook used to declare lifecycle-owned ingress gates. */
+export declare const generationAdmissionSource: unique symbol;
+export interface GenerationAdmissionSource {
+    readonly [generationAdmissionSource]: readonly GenerationAdmissionGate[];
+}
+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, acquireNext?: () => () => void): void;

package/lib/admission.js

@@ -0,0 +1,133 @@
+/**
+ * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
+ * External callbacks may enter while the owning Resource is present in the
+ * committed snapshot; candidate and retired Resources fail closed.
+ */
+export class GenerationAdmissionGate {
+    constructor() {
+        admissionState.set(this, { active: false });
+        admissionDeactivationListeners.set(this, new Set());
+    }
+    get active() {
+        return admissionState.get(this)?.active === true;
+    }
+    acquire() {
+        const state = admissionState.get(this);
+        return state?.active ? state.acquire?.() : undefined;
+    }
+    /**
+     * 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.
+     */
+    onDeactivate(listener) {
+        const listeners = admissionDeactivationListeners.get(this);
+        if (!listeners)
+            throw new Error('Unknown generation admission gate');
+        if (!this.active) {
+            listener();
+            return () => undefined;
+        }
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    }
+    enter(operation) {
+        const release = this.acquire();
+        if (!release)
+            return undefined;
+        try {
+            const result = operation();
+            if (isPromiseLike(result))
+                return Promise.resolve(result).finally(release);
+            release();
+            return result;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+}
+const admissionState = new WeakMap();
+const admissionOwners = new WeakMap();
+const admissionDeactivationListeners = new WeakMap();
+export function createGenerationAdmissionGate() {
+    return new GenerationAdmissionGate();
+}
+/** Resource hook used by CapabilityContext to bind an ingress dependency. */
+export const generationAdmissionBinder = Symbol('GenerationAdmissionBinder');
+/** Snapshot value hook used to declare lifecycle-owned ingress gates. */
+export const generationAdmissionSource = Symbol('GenerationAdmissionSource');
+export function bindGenerationAdmission(value, gate) {
+    if (!isObject(value))
+        return value;
+    const binder = value[generationAdmissionBinder];
+    return typeof binder === 'function' ? binder.call(value, gate) : value;
+}
+export function collectGenerationAdmissions(values) {
+    const result = new Set();
+    for (const value of values) {
+        if (value instanceof GenerationAdmissionGate) {
+            result.add(value);
+            continue;
+        }
+        if (!isObject(value))
+            continue;
+        const gates = value[generationAdmissionSource];
+        if (!Array.isArray(gates))
+            continue;
+        for (const gate of gates) {
+            if (!(gate instanceof GenerationAdmissionGate)) {
+                throw new TypeError('Generation admission source returned an invalid gate');
+            }
+            result.add(gate);
+        }
+    }
+    return result;
+}
+export function replaceGenerationAdmissions(previous, next, owner, acquireNext) {
+    // 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)
+        assertClaimableAdmission(gate, owner);
+    for (const gate of previous) {
+        assertAdmissionOwner(gate, owner);
+    }
+    for (const gate of next)
+        admissionOwners.set(gate, owner);
+    for (const gate of previous) {
+        if (next.has(gate))
+            continue;
+        admissionState.set(gate, { active: false });
+        for (const listener of admissionDeactivationListeners.get(gate) ?? []) {
+            try {
+                listener();
+            }
+            catch {
+                // Admission publication is an infallible pointer switch. Transport
+                // cleanup reports through its own lifecycle and cannot veto commit.
+            }
+        }
+    }
+    for (const gate of next) {
+        admissionState.set(gate, { active: true, acquire: acquireNext });
+    }
+}
+function assertClaimableAdmission(gate, owner) {
+    const current = admissionOwners.get(gate);
+    if (current && current !== owner) {
+        throw new Error('Generation admission gate belongs to another SnapshotStore');
+    }
+}
+function assertAdmissionOwner(gate, owner) {
+    if (admissionOwners.get(gate) !== owner) {
+        throw new Error('SnapshotStore does not own generation admission gate');
+    }
+}
+function isObject(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}
+function isPromiseLike(value) {
+    return isObject(value)
+        && typeof value.then === 'function';
+}

package/lib/handoff.d.ts

@@ -1,30 +1,24 @@
-import type { RuntimeSnapshot } from './snapshot.js';
 export interface GenerationHandoff {
-    quiescePrevious(previous: RuntimeSnapshot): void | Promise<void>;
-    activateNext(): void | Promise<void>;
+    activateNext(signal: AbortSignal): void | Promise<void>;
     deactivateNext(): void | Promise<void>;
-    resumePrevious(): void | Promise<void>;
-    openNext(): void;
 }
 export interface GenerationHandoffParticipant {
-    quiescePrevious?(previous: RuntimeSnapshot): void | Promise<void>;
-    activateNext?(): void | Promise<void>;
+    activateNext?(signal: AbortSignal): void | Promise<void>;
     deactivateNext?(): void | Promise<void>;
-    resumePrevious?(): void | Promise<void>;
-    openNext?(): void;
 }
 export interface GenerationHandoffRegistry {
     add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
 }
+/** A transaction failed and its internal compensation also failed. */
+export declare class GenerationCompensationError extends AggregateError {
+    constructor(errors: readonly unknown[], message: string, options?: ErrorOptions);
+}
 /** Composes owner-ordered Resource handoffs and compensates partial progress. */
 export declare class GenerationHandoffStack implements GenerationHandoffRegistry, GenerationHandoff {
     #private;
     get size(): number;
     add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
     seal(): GenerationHandoff | undefined;
-    quiescePrevious(previous: RuntimeSnapshot): Promise<void>;
-    activateNext(): Promise<void>;
+    activateNext(signal: AbortSignal): Promise<void>;
     deactivateNext(): Promise<void>;
-    resumePrevious(): Promise<void>;
-    openNext(): void;
 }

package/lib/handoff.js

@@ -1,8 +1,14 @@
 import { DisposeStack } from './dispose.js';
+/** A transaction failed and its internal compensation also failed. */
+export class GenerationCompensationError extends AggregateError {
+    constructor(errors, message, options) {
+        super(errors, message, options);
+        this.name = 'GenerationCompensationError';
+    }
+}
 /** Composes owner-ordered Resource handoffs and compensates partial progress. */
 export class GenerationHandoffStack {
     #participants = [];
-    #quiesced = [];
     #activated = [];
     #sealed = false;
     get size() {
@@ -18,27 +24,13 @@ export class GenerationHandoffStack {
         this.#sealed = true;
         return this.size > 0 ? this : undefined;
     }
-    async quiescePrevious(previous) {
-        this.#assertSealed();
-        try {
-            for (const participant of [...this.#participants].reverse()) {
-                if (!participant.quiescePrevious)
-                    continue;
-                await participant.quiescePrevious(previous);
-                this.#quiesced.push(participant);
-            }
-        }
-        catch (error) {
-            await compensate(error, () => this.resumePrevious(), 'Quiesce and resume both failed');
-        }
-    }
-    async activateNext() {
+    async activateNext(signal) {
         this.#assertSealed();
         try {
             for (const participant of this.#participants) {
                 if (!participant.activateNext)
                     continue;
-                await participant.activateNext();
+                await participant.activateNext(signal);
                 this.#activated.push(participant);
             }
         }
@@ -49,22 +41,6 @@ export class GenerationHandoffStack {
     async deactivateNext() {
         await unwind(this.#activated, (participant) => participant.deactivateNext?.(), 'One or more next-generation Resources failed to deactivate');
     }
-    async resumePrevious() {
-        await unwind(this.#quiesced, (participant) => participant.resumePrevious?.(), 'One or more previous-generation Resources failed to resume');
-    }
-    openNext() {
-        const errors = [];
-        for (const participant of this.#participants) {
-            try {
-                participant.openNext?.();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, 'One or more Resources failed to open');
-    }
     #assertSealed() {
         if (!this.#sealed)
             throw new Error('GenerationHandoffStack is not sealed');
@@ -75,7 +51,7 @@ async function compensate(primary, rollback, message) {
         await rollback();
     }
     catch (rollbackError) {
-        throw new AggregateError([primary, rollbackError], message, { cause: rollbackError });
+        throw new GenerationCompensationError([primary, rollbackError], message, { cause: rollbackError });
     }
     throw primary;
 }

package/lib/index.d.ts

@@ -2,6 +2,7 @@
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionBindable, type GenerationAdmissionSource, } from './admission.js';
 export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */

package/lib/index.js

@@ -2,6 +2,7 @@
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, } from './admission.js';
 export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */

package/lib/outbound-host.d.ts

@@ -26,7 +26,7 @@ export interface OutboundSendInput {
 export interface OutboundReactionInput {
     readonly adapter: string;
     readonly endpointKey: string;
-    readonly messageId: string;
+    readonly message: OutboundMessage;
     readonly emoji: string;
     readonly sceneType?: string;
     readonly channelId?: string;
@@ -34,13 +34,23 @@ export interface OutboundReactionInput {
 export interface OutboundRemoveReactionInput {
     readonly adapter: string;
     readonly endpointKey: string;
-    readonly messageId: string;
+    readonly message: OutboundMessage;
     readonly reactionId: string;
 }
 export interface OutboundRecallInput {
     readonly adapter: string;
     readonly endpointKey: string;
-    readonly messageId: string;
+    readonly message: OutboundMessage;
+}
+/** Structured message identity; structurally compatible with IM MessageRef. */
+export interface OutboundMessage {
+    readonly conversation: OutboundConversation & Readonly<{
+        readonly endpoint: Readonly<{
+            readonly id: string;
+            readonly adapter: string;
+        }>;
+    }>;
+    readonly id: string;
 }
 export interface OutboundHost {
     /** Returns platform message id when available (activity-feedback needs it). */

package/lib/plugin.d.ts

@@ -18,6 +18,7 @@ export interface PluginInstanceView {
     readonly role: 'root' | 'child';
 }
 export interface PluginSetupContext<TConfig = unknown> {
+    readonly signal: AbortSignal;
     readonly plugin: PluginInstanceView;
     readonly config: ConfigView<TConfig>;
     readonly resources: Scope;

package/lib/root-controller.d.ts

@@ -1,25 +1,30 @@
 import type { PluginId } from './identity.js';
-import { SnapshotStore, type PreparedGeneration, type RuntimeSnapshot, type SnapshotState } from './snapshot.js';
+import { type CommittedGeneration, type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
 export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
-export type PrepareGeneration = (current: RuntimeSnapshot) => PreparedGeneration | Promise<PreparedGeneration>;
-export type PrepareTransaction = (current: RuntimeSnapshot) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
+export type PrepareGeneration<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | Promise<PreparedGeneration<TState>>;
+export type PrepareTransaction<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | undefined | Promise<PreparedGeneration<TState> | undefined>;
 export type ControlErrorHandler = (error: unknown) => void;
-export interface GenerationCommitEvent {
-    readonly previous: RuntimeSnapshot;
-    readonly current: RuntimeSnapshot;
+export interface GenerationCommitEvent<TState = undefined> {
+    readonly previous: CommittedGeneration<TState>;
+    readonly current: CommittedGeneration<TState>;
 }
-export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
-export declare class RootController {
+export type GenerationCommitListener<TState = undefined> = (event: GenerationCommitEvent<TState>) => void | Promise<void>;
+export declare class RootIntegrityError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class RootController<TState = undefined> {
     #private;
     private readonly onControlError;
-    readonly snapshots: SnapshotStore;
-    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
+    readonly snapshots: SnapshotReader;
+    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get state(): RootState;
     get generation(): number;
+    get snapshot(): RuntimeSnapshot;
+    get committed(): CommittedGeneration<TState>;
     /** Observe successful generation commits, including the initial start. */
-    onGenerationCommit(listener: GenerationCommitListener): () => void;
-    start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
-    transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
-    reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
+    onGenerationCommit(listener: GenerationCommitListener<TState>): () => void;
+    start(prepare: PrepareGeneration<TState>): Promise<RuntimeSnapshot>;
+    transact(prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
+    reload(_target: PluginId | string, prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
     stop(): Promise<void>;
 }

package/lib/root-controller.js

@@ -1,19 +1,46 @@
+import { GenerationCompensationError } from './handoff.js';
 import { SnapshotStore, } from './snapshot.js';
+export class RootIntegrityError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'RootIntegrityError';
+    }
+}
 export class RootController {
     onControlError;
     snapshots;
+    #snapshotStore;
     #state = 'idle';
     #tail = Promise.resolve();
+    #stopResult;
+    #stopRequested = false;
+    #activeTransaction;
     #generationCommitListeners = new Set();
-    constructor(initial, onControlError = () => undefined) {
+    constructor(initial, onControlError = () => undefined, ...state) {
         this.onControlError = onControlError;
-        this.snapshots = new SnapshotStore(initial);
+        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error), ...state);
+        const store = this.#snapshotStore;
+        this.snapshots = Object.freeze({
+            acquire: () => {
+                if (this.#state !== 'running' || this.#stopRequested) {
+                    throw new RootIntegrityError(`Root is not accepting generation operations (${this.#state})`);
+                }
+                return store.acquire();
+            },
+            owns: (lease) => store.owns(lease),
+        });
     }
     get state() {
         return this.#state;
     }
     get generation() {
-        return this.snapshots.current.generation;
+        return this.#snapshotStore.current.generation;
+    }
+    get snapshot() {
+        return this.#snapshotStore.current;
+    }
+    get committed() {
+        return this.#snapshotStore.committed;
     }
     /** Observe successful generation commits, including the initial start. */
     onGenerationCommit(listener) {
@@ -29,12 +56,15 @@ export class RootController {
             }
             let prepared;
             let activated = false;
+            const transaction = new AbortController();
+            this.#activeTransaction = transaction;
             try {
-                prepared = await prepare(this.snapshots.current);
+                prepared = await prepare(this.#snapshotStore.current, transaction.signal);
                 if (prepared.handoff) {
                     activated = true;
-                    await prepared.handoff.activateNext();
+                    await prepared.handoff.activateNext(transaction.signal);
                 }
+                this.#assertPublishable('idle');
                 this.#state = 'running';
                 const snapshot = this.#commitGeneration(0, prepared);
                 prepared = undefined;
@@ -44,6 +74,10 @@ export class RootController {
                 this.#state = 'failed';
                 return this.#rollback(prepared, { activated }, error);
             }
+            finally {
+                if (this.#activeTransaction === transaction)
+                    this.#activeTransaction = undefined;
+            }
         });
     }
     transact(prepare) {
@@ -53,26 +87,28 @@ export class RootController {
             }
             const previous = this.snapshots.acquire();
             let prepared;
-            let quiesced = false;
             let activated = false;
+            const transaction = new AbortController();
+            this.#activeTransaction = transaction;
             try {
-                prepared = await prepare(previous.value);
+                prepared = await prepare(previous.value, transaction.signal);
                 if (!prepared)
                     return previous.value;
                 if (prepared.handoff) {
-                    quiesced = true;
-                    await prepared.handoff.quiescePrevious(previous.value);
                     activated = true;
-                    await prepared.handoff.activateNext();
+                    await prepared.handoff.activateNext(transaction.signal);
                 }
+                this.#assertPublishable('running');
                 const snapshot = this.#commitGeneration(previous.value.generation, prepared);
                 prepared = undefined;
                 return snapshot;
             }
             catch (error) {
-                return this.#rollback(prepared, { quiesced, activated }, error);
+                return this.#rollback(prepared, { activated }, error);
             }
             finally {
+                if (this.#activeTransaction === transaction)
+                    this.#activeTransaction = undefined;
                 previous.release();
             }
         });
@@ -81,16 +117,26 @@ export class RootController {
         return this.transact(prepare);
     }
     stop() {
-        return this.#enqueue(async () => {
+        if (this.#stopResult)
+            return this.#stopResult;
+        this.#stopRequested = true;
+        this.#activeTransaction?.abort(new Error('Root lifecycle is stopping'));
+        const result = this.#enqueue(async () => {
             if (this.#state === 'stopped')
                 return;
             if (this.#state !== 'running' && this.#state !== 'failed') {
                 throw new Error(`Cannot stop RootController from ${this.#state}`);
             }
             this.#state = 'stopping';
-            await this.snapshots.close();
-            this.#state = 'stopped';
+            try {
+                await this.#snapshotStore.close();
+            }
+            finally {
+                this.#state = 'stopped';
+            }
         });
+        this.#stopResult = result;
+        return result;
     }
     #enqueue(operation) {
         const result = this.#tail.then(operation, operation);
@@ -98,30 +144,23 @@ export class RootController {
         return result;
     }
     #commitGeneration(expectedGeneration, prepared) {
-        const previous = this.snapshots.current;
-        const snapshot = this.snapshots.commit(expectedGeneration, prepared);
-        this.#openNext(prepared.handoff);
-        const event = Object.freeze({ previous, current: snapshot });
+        const previous = this.#snapshotStore.committed;
+        const current = this.#snapshotStore.commit(expectedGeneration, prepared);
+        const event = Object.freeze({ previous, current });
         const listeners = [...this.#generationCommitListeners];
         queueMicrotask(() => {
             for (const listener of listeners) {
                 try {
-                    listener(event);
+                    void Promise.resolve(listener(event)).catch((error) => {
+                        this.#reportControlError(error);
+                    });
                 }
                 catch (error) {
                     this.#reportControlError(error);
                 }
             }
         });
-        return snapshot;
-    }
-    #openNext(handoff) {
-        try {
-            handoff?.openNext();
-        }
-        catch (error) {
-            this.#reportControlError(error);
-        }
+        return current.snapshot;
     }
     #reportControlError(error) {
         try {
@@ -141,14 +180,6 @@ export class RootController {
                 errors.push(error);
             }
         }
-        if (prepared && state.quiesced) {
-            try {
-                await prepared.handoff?.resumePrevious();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
         if (prepared) {
             try {
                 await prepared.dispose();
@@ -157,9 +188,22 @@ export class RootController {
                 errors.push(error);
             }
         }
-        if (errors.length > 1) {
-            throw new AggregateError(errors, 'Generation transaction and rollback both failed');
+        if (errors.length > 1 || transactionError instanceof GenerationCompensationError) {
+            const aggregate = new AggregateError(errors, 'Generation transaction and rollback both failed');
+            this.#failIntegrity(aggregate);
+            throw new RootIntegrityError('Root integrity failed while rolling back a generation transaction', { cause: aggregate });
         }
         throw transactionError;
     }
+    #failIntegrity(error) {
+        if (this.#state === 'stopped' || this.#state === 'stopping')
+            return;
+        this.#state = 'failed';
+        this.#reportControlError(error);
+    }
+    #assertPublishable(expected) {
+        if (this.#state !== expected || this.#stopRequested) {
+            throw new RootIntegrityError(`Root cannot publish a generation after admission entered ${this.#stopRequested ? 'stopping' : this.#state}`);
+        }
+    }
 }

package/lib/snapshot.d.ts

@@ -22,11 +22,20 @@ export interface RuntimeSnapshot {
     readonly projections: ReadonlyMap<FeatureId, unknown>;
 }
 export type SnapshotState = Omit<RuntimeSnapshot, 'generation'>;
-export interface PreparedGeneration {
+interface PreparedGenerationBase {
     readonly snapshot: SnapshotState;
     readonly dispose: Dispose;
     readonly handoff?: GenerationHandoff;
 }
+export type PreparedGeneration<TState = undefined> = PreparedGenerationBase & ([TState] extends [undefined] ? {
+    readonly state?: undefined;
+} : {
+    readonly state: TState;
+});
+export interface CommittedGeneration<TState = undefined> {
+    readonly snapshot: RuntimeSnapshot;
+    readonly state: TState;
+}
 export declare class GenerationConflictError extends Error {
     readonly expected: number;
     readonly actual: number;
@@ -41,13 +50,21 @@ export declare class SnapshotLease {
     get active(): boolean;
     release(): void;
 }
-export declare class SnapshotStore {
+/** Read-only operation seam exposed by a Root lifecycle. */
+export interface SnapshotReader {
+    acquire(): SnapshotLease;
+    owns(lease: SnapshotLease): boolean;
+}
+export declare class SnapshotStore<TState = undefined> implements SnapshotReader {
     #private;
-    constructor(initial: SnapshotState);
+    private readonly onDisposalError;
+    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get current(): RuntimeSnapshot;
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed(): CommittedGeneration<TState>;
     acquire(): SnapshotLease;
     owns(lease: SnapshotLease): boolean;
-    commit(expectedGeneration: number, prepared: PreparedGeneration): RuntimeSnapshot;
+    commit(expectedGeneration: number, prepared: PreparedGeneration<TState>): CommittedGeneration<TState>;
     close(): Promise<void>;
 }
 export declare function createSnapshotView(generation: number, state: SnapshotState): RuntimeSnapshot;

package/lib/snapshot.js

@@ -1,3 +1,4 @@
+import { collectGenerationAdmissions, replaceGenerationAdmissions, } from './admission.js';
 export class GenerationConflictError extends Error {
     expected;
     actual;
@@ -30,30 +31,41 @@ export class SnapshotLease {
     }
 }
 export class SnapshotStore {
+    onDisposalError;
     #current;
     #retired = new Set();
     #leases = new WeakSet();
     #closed = false;
-    constructor(initial) {
-        this.#current = {
-            snapshot: createSnapshotView(0, initial),
+    constructor(initial, onDisposalError = () => undefined, ...state) {
+        this.onDisposalError = onDisposalError;
+        const initialState = state[0];
+        const snapshot = createSnapshotView(0, initial);
+        const committed = Object.freeze({ snapshot, state: initialState });
+        const admissions = collectSnapshotAdmissions(snapshot);
+        const record = {
+            snapshot,
+            state: initialState,
+            committed,
             dispose: () => undefined,
+            admissions,
             leases: 0,
             retired: false,
         };
+        replaceGenerationAdmissions(new Set(), admissions, this, () => this.#retain(record));
+        this.#current = record;
     }
     get current() {
         return this.#current.snapshot;
     }
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed() {
+        return this.#current.committed;
+    }
     acquire() {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
         const record = this.#current;
-        record.leases += 1;
-        const lease = new SnapshotLease(record.snapshot, () => {
-            record.leases -= 1;
-            this.#disposeIfReady(record);
-        }, snapshotLeaseAuthority);
+        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority);
         this.#leases.add(lease);
         return lease;
     }
@@ -70,23 +82,33 @@ export class SnapshotStore {
             throw new GenerationConflictError(expectedGeneration, this.#current.snapshot.generation);
         }
         const previous = this.#current;
-        // Commit only swaps the active pointer. The previous record may still be
-        // serving in-flight work, so disposal is deferred to its final lease.
-        this.#current = {
-            snapshot: createSnapshotView(expectedGeneration + 1, prepared.snapshot),
+        const snapshot = createSnapshotView(expectedGeneration + 1, prepared.snapshot);
+        const state = prepared.state;
+        const committed = Object.freeze({ snapshot, state });
+        const admissions = collectSnapshotAdmissions(snapshot);
+        const next = {
+            snapshot,
+            state,
+            committed,
             dispose: prepared.dispose,
+            admissions,
             leases: 0,
             retired: false,
         };
+        replaceGenerationAdmissions(previous.admissions, admissions, this, () => this.#retain(next));
+        // Commit only swaps the active pointer. The previous record may still be
+        // serving in-flight work, so disposal is deferred to its final lease.
+        this.#current = next;
         previous.retired = true;
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
-        return this.#current.snapshot;
+        return this.#current.committed;
     }
     async close() {
         if (this.#closed)
             return;
         this.#closed = true;
+        replaceGenerationAdmissions(this.#current.admissions, new Set(), this);
         this.#current.retired = true;
         this.#retired.add(this.#current);
         this.#disposeIfReady(this.#current);
@@ -100,9 +122,25 @@ export class SnapshotStore {
             return;
         if (!record.disposing) {
             record.disposing = Promise.resolve().then(record.dispose);
-            void record.disposing.then(() => record.drain?.resolve(), (error) => record.drain?.reject(error));
+            void record.disposing.then(() => record.drain?.resolve(), (error) => {
+                record.drain?.reject(error);
+                this.onDisposalError(error);
+            });
         }
     }
+    #retain(record) {
+        record.leases += 1;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            record.leases -= 1;
+            if (record.leases < 0)
+                throw new Error('Snapshot lease underflow');
+            this.#disposeIfReady(record);
+        };
+    }
     #waitForDisposal(record) {
         if (record.disposing)
             return record.disposing;
@@ -118,6 +156,12 @@ export class SnapshotStore {
         return record.drain.promise;
     }
 }
+function collectSnapshotAdmissions(snapshot) {
+    return collectGenerationAdmissions([
+        ...snapshot.projections.values(),
+        ...[...snapshot.resources.values()].flatMap((resources) => [...resources.values()]),
+    ]);
+}
 export function createSnapshotView(generation, state) {
     // Object.freeze(Map) does not disable Map#set. ReadonlyMapView removes the
     // mutator interface at runtime, including from provider projection hooks.

package/lib/token.d.ts

@@ -6,6 +6,7 @@ export interface Token<T> {
     readonly _type?: () => T;
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
+export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
 export declare class Scope {
     #private;
     readonly owner: PluginId;

package/lib/token.js

@@ -1,8 +1,14 @@
 import { DisposeStack } from './dispose.js';
 import { tokenId } from './identity.js';
+const rootPrivateTokens = new WeakSet();
 export function createToken(id, description) {
     return Object.freeze({ id: tokenId(id), description });
 }
+export function createRootPrivateToken(id, description) {
+    const token = { id: tokenId(id), description };
+    rootPrivateTokens.add(token);
+    return Object.freeze(token);
+}
 export class Scope {
     owner;
     parent;
@@ -20,20 +26,36 @@ export class Scope {
         if (this.#bindings.has(token.id)) {
             throw new Error(`Duplicate resource ${token.id} in ${this.owner}`);
         }
-        this.#bindings.set(token.id, Object.freeze({ owner: this.owner, value }));
+        this.#bindings.set(token.id, Object.freeze({
+            owner: this.owner,
+            value,
+            rootPrivate: rootPrivateTokens.has(token),
+            token,
+        }));
         if (dispose)
             this.disposers.add(dispose);
     }
     use(token) {
         const binding = this.#bindings.get(token.id);
-        if (binding)
-            return binding.value;
-        if (this.parent)
-            return this.parent.use(token);
+        if (binding) {
+            if (!binding.rootPrivate || binding.token === token)
+                return binding.value;
+            throw new Error(`Missing resource ${token.id} for ${this.owner}`);
+        }
+        const inherited = this.parent
+            ? this.parent.#resolveForDescendant(token.id)
+            : undefined;
+        if (inherited?.status === 'found')
+            return inherited.binding.value;
         throw new Error(`Missing resource ${token.id} for ${this.owner}`);
     }
     has(token) {
-        return this.#bindings.has(token.id) || Boolean(this.parent?.has(token));
+        const binding = this.#bindings.get(token.id);
+        if (binding)
+            return !binding.rootPrivate || binding.token === token;
+        return this.parent
+            ? this.parent.#resolveForDescendant(token.id)?.status === 'found'
+            : false;
     }
     seal() {
         this.#sealed = true;
@@ -45,8 +67,19 @@ export class Scope {
         const result = this.parent
             ? new Map(this.parent.snapshot())
             : new Map();
-        for (const [id, binding] of this.#bindings)
-            result.set(id, binding.value);
+        for (const [id, binding] of this.#bindings) {
+            if (!binding.rootPrivate)
+                result.set(id, binding.value);
+        }
         return result;
     }
+    #resolveForDescendant(id) {
+        const binding = this.#bindings.get(id);
+        if (binding) {
+            return binding.rootPrivate
+                ? Object.freeze({ status: 'blocked' })
+                : Object.freeze({ status: 'found', binding });
+        }
+        return this.parent ? this.parent.#resolveForDescendant(id) : undefined;
+    }
 }

package/package.json

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