@spine-event-engine/auth 2.0.0-snapshot.25 → 2.0.0-snapshot.26

package/dist/subscriptions/index.js

@@ -13,6 +13,7 @@
  */
 import { clone, create, fromBinary, toBinary } from "@bufbuild/protobuf";
 import { SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS } from "@spine-event-engine/core/spi/subscription-lifecycle";
+import { ReaderIdentities, snapshotTrustedReader, } from "@spine-event-engine/core/spi/trusted-reader";
 import { ActorContextSchema, TenantIdSchema } from "@spine-event-engine/proto";
 import { SubscriptionSchema, SubscriptionUpdateSchema, TopicSchema, } from "@spine-event-engine/proto/client";
 import { IncomingRequests } from "../request/index.js";
@@ -34,6 +35,7 @@ export class InMemorySubscriptionBindings {
     #limits;
     /**
      * Creates the in-memory binding store.
+     *
      * @param options Supplies identifiers, process limits, and disposal behavior.
      */
     constructor(options) {
@@ -43,6 +45,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Returns the number of retained private bindings for lifecycle observability.
+     *
      * @returns Returns the retained binding count.
      */
     get size() {
@@ -50,6 +53,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Removes already-expired logical bindings without a background timer.
+     *
      * @param nowMs Supplies the current time in milliseconds.
      * @returns Completes after expired envelopes are removed.
      */
@@ -61,14 +65,13 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Closes the store by aborting work and waiting for bounded cleanup.
-     *
      * Cooperative callbacks allow cleanup to complete before this method resolves.
      * Non-cooperative raw callbacks cause an `AggregateError` after
      * `shutdownTimeoutMs`; their exactly-once disposal remains queued until they
      * settle.
+     * `AggregateError` when cleanup exceeds its shutdown limit.
      *
      * @returns Completes after bounded cooperative cleanup, or rejects with an
-     * `AggregateError` when cleanup exceeds its shutdown limit.
      */
     async close() {
         this.#closed = true;
@@ -84,6 +87,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Creates an inactive binding from a trusted rewritten topic.
+     *
      * @param input Supplies the topic and expiry.
      * @returns Returns the retained public subscription wire.
      */
@@ -103,6 +107,7 @@ export class InMemorySubscriptionBindings {
             this.#bindings.set(id, {
                 definition: wire.wire.bytes.slice(),
                 context: clone(ActorContextSchema, topic.context),
+                reader: input.reader,
                 expiresAtMs: input.whenExpires,
                 state: "inactive",
                 controller: new AbortController(),
@@ -120,6 +125,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Activates only an owned inactive binding and restores retry state after callback failure.
+     *
      * @param input Supplies ownership facts and the backend callback.
      * @returns Returns the ownership transition outcome.
      */
@@ -134,6 +140,9 @@ export class InMemorySubscriptionBindings {
                 return { kind: "denied" };
             binding.state = "active";
             binding.controller = new AbortController();
+            /**
+             * Cancels this activation when the caller aborts.
+             */
             const abort = () => {
                 binding.controller.abort();
             };
@@ -155,6 +164,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Cancels an owned binding and retains retry state after failed cleanup.
+     *
      * @param input Supplies ownership facts and the backend callback.
      * @returns Returns the ownership transition outcome.
      */
@@ -182,7 +192,12 @@ export class InMemorySubscriptionBindings {
             return { kind: "closed" };
         });
     }
-    #owned(input) {
+    /**
+     * Checks whether the retained binding still matches its current ID slot.
+     *
+     * @param input Retained binding and current lifecycle state.
+     * @returns Whether this binding is still current.
+     */ #owned(input) {
         const binding = this.#bindings.get(input.id);
         if (binding === undefined)
             return Promise.resolve(undefined);
@@ -190,15 +205,22 @@ export class InMemorySubscriptionBindings {
             this.#expire(input.id, binding);
             return Promise.resolve(undefined);
         }
-        return SubscriptionGatewayValues.contextsEqual(binding.context, input.context)
+        return SubscriptionGatewayValues.contextsEqual(binding.context, input.context) &&
+            ReaderIdentities.matches(binding.reader, input.reader)
             ? Promise.resolve(binding)
             : Promise.resolve(undefined);
     }
-    #precheck(input) {
+    /**
+     * Checks retained binding state before an asynchronous effect.
+     *
+     * @param input Retained binding and current lifecycle state.
+     * @returns Whether the effect may proceed.
+     */ #precheck(input) {
         const binding = this.#bindings.get(input.id);
         if (binding === undefined)
             return "absent";
-        if (!SubscriptionGatewayValues.contextsEqual(binding.context, input.context))
+        if (!SubscriptionGatewayValues.contextsEqual(binding.context, input.context) ||
+            !ReaderIdentities.matches(binding.reader, input.reader))
             return "denied";
         if (binding.expiring ||
             (binding.expiresAtMs !== undefined && binding.expiresAtMs <= input.nowMs)) {
@@ -207,7 +229,12 @@ export class InMemorySubscriptionBindings {
         }
         return "owned";
     }
-    #expire(id, binding) {
+    /**
+     * Expires one retained binding only if it is still current.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     */ #expire(id, binding) {
         if (binding.expiring || this.#bindings.get(id) !== binding)
             return;
         binding.expiring = true;
@@ -215,16 +242,33 @@ export class InMemorySubscriptionBindings {
         // spine-log-boundary: auth.subscription_expiry_cleanup
         void this.#disposeAfterWork(id, binding).catch(() => undefined);
     }
-    #dispose(id, binding) {
+    /**
+     * Clears retained definition bytes and releases binding state.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     */ #dispose(id, binding) {
         binding.definition.fill(0);
         binding.state = "closed";
         this.#bindings.delete(id);
     }
-    async #runEffect(binding, callback) {
+    /**
+     * Starts one retained definition effect and tracks its completion.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ async #runEffect(binding, callback) {
         const effect = this.#startEffect(binding, callback);
         await SubscriptionGatewayValues.withTimeout(effect, this.#limits.operationTimeoutMs, binding.controller);
     }
-    async #runActiveEffect(binding, callback) {
+    /**
+     * Runs a retained binding effect while observing cancellation.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ async #runActiveEffect(binding, callback) {
         let observeAbort = () => undefined;
         const aborted = new Promise((resolve) => {
             observeAbort = () => {
@@ -245,7 +289,13 @@ export class InMemorySubscriptionBindings {
         }
         throw new Error("subscription operation aborted");
     }
-    #startEffect(binding, callback) {
+    /**
+     * Builds the public definition callback effect for a retained binding.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ #startEffect(binding, callback) {
         const definition = SubscriptionGatewayValues.copyPublic({
             kind: "public-subscription",
             bytes: binding.definition,
@@ -265,7 +315,13 @@ export class InMemorySubscriptionBindings {
         void settled.then(() => definition.bytes.fill(0));
         return effect;
     }
-    #disposeAfterWork(id, binding) {
+    /**
+     * Waits for active callback work before clearing a binding.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     * @returns Completion after the operation settles.
+     */ #disposeAfterWork(id, binding) {
         const cleanup = binding.tail
             .then(() => binding.effectTail)
             .then(() => this.#disposeWithCallback(id, binding));
@@ -275,10 +331,21 @@ export class InMemorySubscriptionBindings {
         void cleanup.catch(() => undefined);
         return cleanup;
     }
-    #waitForShutdown(cleanup) {
+    /**
+     * Waits for accepted binding effects before disposal.
+     *
+     * @param cleanup Resource cleanup operation.
+     * @returns Completion after the operation settles.
+     */ #waitForShutdown(cleanup) {
         return SubscriptionGatewayValues.withTimeout(cleanup, this.#limits.shutdownTimeoutMs, new AbortController());
     }
-    async #disposeWithCallback(id, binding) {
+    /**
+     * Detaches a retained binding and invokes its cleanup callback.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     * @returns Completion after the operation settles.
+     */ async #disposeWithCallback(id, binding) {
         if (this.#bindings.get(id) !== binding)
             return;
         const definition = SubscriptionGatewayValues.copyPublic({
@@ -339,6 +406,7 @@ export class SubscriptionGateway {
     #closed = false;
     /**
      * Creates the subscription gateway.
+     *
      * @param options Supplies admission, authorization, binding, and backend collaborators.
      */
     constructor(options) {
@@ -349,6 +417,7 @@ export class SubscriptionGateway {
     }
     /**
      * Handles one admitted subscription RPC request.
+     *
      * @param request Supplies the copied request admission facts.
      * @returns Returns the opaque operation result.
      */
@@ -367,6 +436,7 @@ export class SubscriptionGateway {
     }
     /**
      * Closes admission and closes retained bindings.
+     *
      * @returns Completes after retained bindings close.
      */
     async close() {
@@ -381,6 +451,7 @@ export class SubscriptionGateway {
     }
     /**
      * Schedules finite local expiry cleanup for a recovered durable definition.
+     *
      * @param whenExpires Supplies the retained expiry in epoch milliseconds.
      */
     scheduleExpiry(whenExpires) {
@@ -394,7 +465,12 @@ export class SubscriptionGateway {
         }, Math.max(0, whenExpires - nowMs));
         this.#expiryTimers.add(timer);
     }
-    async #handleOperation(request) {
+    /**
+     * Rejects stale or malformed gateway operations before binding mutations.
+     *
+     * @param request The request being processed.
+     * @returns Authorized result or a structured rejection.
+     */ async #handleOperation(request) {
         const kind = SubscriptionGatewayValues.operationFor(request);
         if (kind === undefined)
             return SubscriptionGatewayValues.rejected("unknown-operation");
@@ -414,7 +490,13 @@ export class SubscriptionGateway {
             return prepared;
         return this.#perform(prepared, request.updates, request.signal);
     }
-    async #prepareSecurity(kind, request) {
+    /**
+     * Resolves the session and policy decision for one subscription operation.
+     *
+     * @param kind Requested subscription operation.
+     * @param request The request being processed.
+     * @returns Prepared operation or an authentication/policy rejection.
+     */ async #prepareSecurity(kind, request) {
         const source = SubscriptionGatewayValues.decode(kind, request.wire.bytes, request.transport);
         if (source === undefined)
             return SubscriptionGatewayValues.rejected("malformed-request");
@@ -431,119 +513,261 @@ export class SubscriptionGateway {
             return SubscriptionGatewayValues.rejected("forbidden");
         return this.#resolveTrusted(kind, request, source, session);
     }
-    async #resolveTrusted(kind, request, source, session) {
+    /**
+     * Builds detached trusted reader and actor facts after policy admission.
+     *
+     * @param kind Requested subscription operation.
+     * @param request The request being processed.
+     * @param source Decoded incoming subscription request.
+     * @param session Resolved gateway session or explicit public principal.
+     * @returns Prepared operation or a structured context rejection.
+     */ async #resolveTrusted(kind, request, source, session) {
         const contextRequest = SubscriptionGatewayValues.decode(kind, request.wire.bytes, request.transport);
         if (contextRequest === undefined)
             return SubscriptionGatewayValues.rejected("malformed-request");
-        const context = SubscriptionGatewayValues.trustedContext(await this.#options.contexts.resolve(session.principal, contextRequest, this.#options.clock));
+        const resolved = await this.#options.contexts.resolve(session.principal, contextRequest, this.#options.clock);
+        const context = SubscriptionGatewayValues.trustedContext(resolved);
+        const reader = this.#trustedReader(session.principal, resolved);
         const nowMs = this.#nowMs();
-        const expiresAtMs = session.expiresAt === undefined
-            ? undefined
-            : SubscriptionGatewayValues.timestampMs(session.expiresAt.seconds, session.expiresAt.nanos);
-        if (nowMs === undefined ||
-            (this.#options.publicAccess !== true && expiresAtMs === undefined) ||
-            (expiresAtMs !== undefined && expiresAtMs <= nowMs) ||
-            !SubscriptionGatewayValues.matches(source.requestedContext, context))
+        const expiresAtMs = this.#expiresAtMs(session.expiresAt);
+        if (nowMs === undefined || !this.#validContext(source, context, nowMs, expiresAtMs))
             return SubscriptionGatewayValues.rejected("denied");
         return {
             source,
             context,
+            reader,
             expiresAtMs,
             nowMs,
         };
     }
-    #nowMs() {
+    /**
+     * Converts a verified session expiry into the gateway clock's millisecond unit.
+     *
+     * @param value Verified session expiry timestamp, if present.
+     * @returns The expiry in epoch milliseconds.
+     */
+    #expiresAtMs(value) {
+        return value === undefined
+            ? undefined
+            : SubscriptionGatewayValues.timestampMs(value.seconds, value.nanos);
+    }
+    /**
+     * Detaches the verified principal and current authority facts from the resolver.
+     *
+     * @param principal Verified principal from session resolution.
+     * @param resolved Resolved context and authority facts.
+     * @returns The detached verified reader facts.
+     */
+    #trustedReader(principal, resolved) {
+        return snapshotTrustedReader({
+            ...(this.#options.publicAccess === true ? {} : { principal }),
+            ...(this.#options.publicAccess === true || resolved.authorityFacts === undefined
+                ? {}
+                : { authorityFacts: resolved.authorityFacts }),
+        });
+    }
+    /**
+     * Checks session time and the resolver's trusted actor/tenant against the request.
+     *
+     * @param source Decoded incoming subscription request.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @returns The validated actor context.
+     */
+    #validContext(source, context, nowMs, expiresAtMs) {
+        return ((this.#options.publicAccess === true || expiresAtMs !== undefined) &&
+            (expiresAtMs === undefined || expiresAtMs > nowMs) &&
+            SubscriptionGatewayValues.matches(source.requestedContext, context));
+    }
+    /**
+     * Reads the configured clock as finite epoch milliseconds.
+     *
+     * @returns Current epoch milliseconds, if valid.
+     */ #nowMs() {
         const now = this.#options.clock.now();
         return SubscriptionGatewayValues.timestampMs(now.seconds, now.nanos);
     }
-    async #perform(prepared, updates, signal) {
-        const { source, context, expiresAtMs, nowMs } = prepared;
+    /**
+     * Runs the prepared subscription operation after security checks.
+     *
+     * @param prepared Policy-admitted subscription operation.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The admitted subscription outcome.
+     */ async #perform(prepared, updates, signal) {
+        const { source, context, reader, expiresAtMs, nowMs } = prepared;
         const rewritten = SubscriptionGatewayValues.rewrite(source, context);
         if (source.kind === "subscribe")
-            return this.#subscribe(rewritten, context, expiresAtMs);
+            return this.#subscribe(rewritten, context, reader, expiresAtMs);
         const id = source.subscription.id?.value;
         if (id === undefined || id.length === 0)
             return SubscriptionGatewayValues.rejected("denied");
         return source.kind === "activate"
-            ? this.#activate(id, context, nowMs, expiresAtMs, updates ?? SubscriptionGatewayValues.discardUpdate, signal)
-            : this.#cancel(id, context, nowMs);
+            ? this.#activate(id, context, reader, nowMs, expiresAtMs, updates ?? SubscriptionGatewayValues.discardUpdate, signal)
+            : this.#cancel(id, context, nowMs, reader);
     }
-    async #activate(id, context, nowMs, expiresAtMs, updates, signal) {
-        const activeController = new AbortController();
-        const active = activeController.signal;
-        const abort = () => {
-            activeController.abort();
-        };
+    /**
+     * Verifies membership and activates a retained subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The update stream after admission.
+     */ async #activate(id, context, reader, nowMs, expiresAtMs, updates, signal) {
         if (signal?.aborted)
             return SubscriptionGatewayValues.rejected("denied");
         if (this.#options.publicAccess === true)
             this.#clearPublicPending(id);
-        signal?.addEventListener("abort", abort, { once: true });
-        const expiry = expiresAtMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                activeController.abort();
-            }, Math.max(0, expiresAtMs - nowMs));
         let activationFailure;
         let outcome = SubscriptionGatewayValues.rejected("denied");
         try {
-            const result = await this.#options.bindings.activate({
-                id,
-                context,
-                nowMs,
-                signal: active,
-                onDefinition: (definition, effectSignal) => this.#forwardActivate(definition, updates, effectSignal),
+            outcome = await this.#activationEffect(id, context, reader, nowMs, expiresAtMs, updates, signal);
+        }
+        catch (error) {
+            activationFailure = this.#activationError(error);
+        }
+        if (this.#options.publicAccess === true)
+            await this.#publicActivationCleanup(id, context, reader, nowMs, activationFailure);
+        if (activationFailure !== undefined)
+            throw activationFailure;
+        return outcome;
+    }
+    /**
+     * Preserves a non-Error activation failure as a throwable cause.
+     *
+     * @param error The failure being classified or propagated.
+     * @returns The structured activation error.
+     */
+    #activationError(error) {
+        return error instanceof Error
+            ? error
+            : new Error("Public subscription activation failed with a non-Error value.", {
+                cause: error,
             });
-            outcome =
-                result.kind === "activated"
-                    ? { kind: "activated" }
-                    : SubscriptionGatewayValues.rejected("denied");
+    }
+    /**
+     * Releases a public definition while retaining both activation and cleanup failures.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param activationFailure Failure raised while activating the subscription.
+     * @returns Completion after the operation settles.
+     */
+    async #publicActivationCleanup(id, context, reader, nowMs, activationFailure) {
+        try {
+            await this.#cancel(id, context, this.#nowMs() ?? nowMs, reader);
+        }
+        catch (error) {
+            const cleanupFailure = error instanceof Error
+                ? error
+                : new Error("Public subscription cleanup failed with a non-Error value.", {
+                    cause: error,
+                });
+            if (activationFailure !== undefined)
+                throw new AggregateError([activationFailure, cleanupFailure], "public subscription cleanup failed");
+            throw cleanupFailure;
+        }
+    }
+    /**
+     * Runs one reader-bound binding activation under cancellation and session expiry.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The tracked activation effect.
+     */
+    async #activationEffect(id, context, reader, nowMs, expiresAtMs, updates, signal) {
+        const activeController = new AbortController();
+        const active = activeController.signal;
+        /**
+         * Cancels this activation when the caller aborts.
+         */
+        const abort = () => {
+            activeController.abort();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        const expiry = this.#activationExpiry(expiresAtMs, nowMs, activeController);
+        try {
+            const result = await this.#activateBinding(id, context, reader, nowMs, active, updates);
+            return result.kind === "activated"
+                ? { kind: "activated" }
+                : SubscriptionGatewayValues.rejected("denied");
         }
         catch (error) {
             if (error instanceof Error && error.message === "binding-busy")
-                outcome = SubscriptionGatewayValues.rejected("binding-busy");
-            else
-                activationFailure =
-                    error instanceof Error
-                        ? error
-                        : new Error("Public subscription activation failed with a non-Error value.", {
-                            cause: error,
-                        });
+                return SubscriptionGatewayValues.rejected("binding-busy");
+            throw error;
         }
         finally {
             if (expiry !== undefined)
                 clearTimeout(expiry);
             signal?.removeEventListener("abort", abort);
         }
-        let cleanupFailure;
-        if (this.#options.publicAccess === true)
-            try {
-                await this.#cancel(id, context, this.#nowMs() ?? nowMs);
-            }
-            catch (error) {
-                cleanupFailure =
-                    error instanceof Error
-                        ? error
-                        : new Error("Public subscription cleanup failed with a non-Error value.", {
-                            cause: error,
-                        });
-            }
-        if (activationFailure !== undefined) {
-            if (cleanupFailure !== undefined)
-                throw new AggregateError([activationFailure, cleanupFailure], "public subscription cleanup failed");
-            throw activationFailure;
-        }
-        if (cleanupFailure !== undefined)
-            throw cleanupFailure;
-        return outcome;
     }
-    #cancel(id, context, nowMs) {
+    /**
+     * Cancels activation when the admitted reader session reaches its expiry.
+     *
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param nowMs The current time in milliseconds.
+     * @param controller Abort controller for the active operation.
+     * @returns The pending activation expiry.
+     */
+    #activationExpiry(expiresAtMs, nowMs, controller) {
+        return expiresAtMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                controller.abort();
+            }, Math.max(0, expiresAtMs - nowMs));
+    }
+    /**
+     * Sends one reader-bound activation to the durable binding port.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param signal The cancellation signal for this operation.
+     * @param updates The admitted subscription update sink.
+     * @returns The activated reader-bound definition.
+     */
+    #activateBinding(id, context, reader, nowMs, signal, updates) {
+        return this.#options.bindings.activate({
+            id,
+            context,
+            reader: ReaderIdentities.from(reader),
+            nowMs,
+            signal,
+            onDefinition: (definition, effectSignal) => this.#forwardActivate({ ...definition, reader }, updates, effectSignal),
+        });
+    }
+    /**
+     * Verifies reader membership and removes a retained subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param reader The verified reader facts for this operation.
+     * @returns The cancellation acknowledgment.
+     */ #cancel(id, context, nowMs, reader = {}) {
+        const identity = ReaderIdentities.from(reader);
         const active = this.#cancellations.get(id) ?? [];
-        const matching = active.find((entry) => SubscriptionGatewayValues.contextsEqual(entry.context, context));
+        const matching = active.find((entry) => SubscriptionGatewayValues.contextsEqual(entry.context, context) &&
+            ReaderIdentities.matches(entry.reader, identity));
         if (matching !== undefined)
             return matching.promise;
-        const promise = this.#cancelOnce(id, context, nowMs);
-        const entry = { context: clone(ActorContextSchema, context), promise };
+        const promise = this.#cancelOnce(id, context, nowMs, reader);
+        const entry = { context: clone(ActorContextSchema, context), reader: identity, promise };
         active.push(entry);
         this.#cancellations.set(id, active);
         // spine-log-boundary: auth.subscription_cancel_finally_observer
@@ -561,13 +785,22 @@ export class SubscriptionGateway {
             .catch(() => undefined);
         return promise;
     }
-    async #cancelOnce(id, context, nowMs) {
+    /**
+     * Serializes one cancellation against concurrent work for its ID.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param reader The verified reader facts for this operation.
+     * @returns The cancellation outcome.
+     */ async #cancelOnce(id, context, nowMs, reader) {
         try {
             const result = await this.#options.bindings.cancel({
                 id,
                 context,
+                reader: ReaderIdentities.from(reader),
                 nowMs,
-                onDefinition: (definition, effectSignal) => this.#forwardCancel(definition, effectSignal),
+                onDefinition: (definition, effectSignal) => this.#forwardCancel({ ...definition, reader }, effectSignal),
             });
             if (result.kind === "denied")
                 return SubscriptionGatewayValues.rejected("denied");
@@ -580,43 +813,32 @@ export class SubscriptionGateway {
             throw error;
         }
     }
-    async #subscribe(bytes, context, expiresAtMs) {
+    /**
+     * Validates and retains a reader-bound subscription definition.
+     *
+     * @param bytes The serialized message bytes.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @returns The new subscription definition.
+     */ async #subscribe(bytes, context, reader, expiresAtMs) {
         const wire = await this.#options.bindings.create({
             topic: { kind: "subscription-topic", bytes: bytes.slice() },
+            reader: ReaderIdentities.from(reader),
             ...(expiresAtMs === undefined ? {} : { whenExpires: expiresAtMs }),
         });
+        const admittedWire = { ...wire, reader };
         const id = fromBinary(SubscriptionSchema, wire.bytes).id?.value;
         if (id === undefined || id.length === 0)
             throw new Error("retained subscription has no ID");
         const controller = new AbortController();
         try {
-            await this.#receiveBackend(wire, controller);
-            const nowMs = this.#nowMs();
-            if (nowMs === undefined || (expiresAtMs !== undefined && expiresAtMs <= nowMs)) {
-                await this.#compensateDefinition(wire, controller);
-                await this.#options.bindings.cancel({
-                    id,
-                    context,
-                    nowMs: nowMs ?? expiresAtMs ?? 0,
-                    onDefinition: () => Promise.resolve(),
-                });
-                return SubscriptionGatewayValues.rejected("denied");
-            }
-            if (expiresAtMs !== undefined)
-                this.scheduleExpiry(expiresAtMs);
-            if (this.#options.publicAccess === true)
-                this.#schedulePublicPending(id, context);
-            return { kind: "subscribed", wire: SubscriptionGatewayValues.copyPublic(wire) };
+            await this.#receiveBackend(admittedWire, controller);
+            return await this.#confirmCreated(id, context, reader, expiresAtMs, admittedWire, controller);
         }
         catch (error) {
             try {
-                await this.#compensateDefinition(wire, controller);
-                await this.#options.bindings.cancel({
-                    id,
-                    context,
-                    nowMs: this.#nowMs() ?? expiresAtMs ?? 0,
-                    onDefinition: () => Promise.resolve(),
-                });
+                await this.#discardCreated(id, context, reader, this.#nowMs() ?? expiresAtMs ?? 0, admittedWire, controller);
                 // spine-log-boundary: auth.subscription_recovered_cleanup
             }
             catch {
@@ -625,7 +847,59 @@ export class SubscriptionGateway {
             throw error;
         }
     }
-    #schedulePublicPending(id, context) {
+    /**
+     * Returns an admitted public definition only while its reader session remains valid.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns The confirmed retained definition.
+     */
+    async #confirmCreated(id, context, reader, expiresAtMs, wire, controller) {
+        const nowMs = this.#nowMs();
+        if (nowMs === undefined || (expiresAtMs !== undefined && expiresAtMs <= nowMs)) {
+            await this.#discardCreated(id, context, reader, nowMs ?? expiresAtMs ?? 0, wire, controller);
+            return SubscriptionGatewayValues.rejected("denied");
+        }
+        if (expiresAtMs !== undefined)
+            this.scheduleExpiry(expiresAtMs);
+        if (this.#options.publicAccess === true)
+            this.#schedulePublicPending(id, context);
+        return {
+            kind: "subscribed",
+            wire: { kind: "public-subscription", bytes: wire.bytes.slice() },
+        };
+    }
+    /**
+     * Compensates a created definition before it can escape admission.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */
+    async #discardCreated(id, context, reader, nowMs, wire, controller) {
+        await this.#compensateDefinition(wire, controller);
+        await this.#options.bindings.cancel({
+            id,
+            context,
+            reader: ReaderIdentities.from(reader),
+            nowMs,
+            onDefinition: () => Promise.resolve(),
+        });
+    }
+    /**
+     * Schedules activation retry for a public subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     */ #schedulePublicPending(id, context) {
         this.#clearPublicPending(id);
         const timer = setTimeout(() => {
             if (this.#publicPendingTimers.get(id) !== timer)
@@ -641,24 +915,52 @@ export class SubscriptionGateway {
         }, SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS);
         this.#publicPendingTimers.set(id, timer);
     }
-    #retryPublicPending(id, context) {
+    /**
+     * Retries pending public activation after backend availability changes.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     */ #retryPublicPending(id, context) {
         if (!this.#closed && !this.#publicPendingTimers.has(id))
             this.#schedulePublicPending(id, context);
     }
-    #clearPublicPending(id) {
+    /**
+     * Clears the pending public activation timer for an ID.
+     *
+     * @param id The stable identifier for this record.
+     */ #clearPublicPending(id) {
         const timer = this.#publicPendingTimers.get(id);
         if (timer !== undefined)
             clearTimeout(timer);
         this.#publicPendingTimers.delete(id);
     }
-    async #receiveBackend(wire, controller) {
+    /**
+     * Attaches the native backend subscription after admission.
+     *
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */ async #receiveBackend(wire, controller) {
         return SubscriptionGatewayValues.withTimeout(this.#options.creator.subscribe(SubscriptionGatewayValues.copyPublic(wire), controller.signal, this.#limits.maxBackendEnvelopeBytes), this.#limits.operationTimeoutMs, controller);
     }
-    async #compensateDefinition(wire, controller) {
+    /**
+     * Removes a definition after a failed backend subscription step.
+     *
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */ async #compensateDefinition(wire, controller) {
         const signal = controller.signal.aborted ? new AbortController().signal : controller.signal;
         await this.#options.creator.cancel({ wire: SubscriptionGatewayValues.copyPublic(wire) }, signal);
     }
-    async #forwardActivate(definition, updates, signal) {
+    /**
+     * Forwards activation with the verified reader assertion.
+     *
+     * @param definition The serialized subscription definition.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns Completion after the operation settles.
+     */ async #forwardActivate(definition, updates, signal) {
         const privateWire = SubscriptionGatewayValues.copyPublic(definition);
         try {
             const publicSubscription = fromBinary(SubscriptionSchema, definition.bytes);
@@ -683,7 +985,13 @@ export class SubscriptionGateway {
             privateWire.bytes.fill(0);
         }
     }
-    async #forwardCancel(definition, signal) {
+    /**
+     * Forwards cancellation with the verified reader assertion.
+     *
+     * @param definition The serialized subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @returns Completion after the operation settles.
+     */ async #forwardCancel(definition, signal) {
         const privateWire = SubscriptionGatewayValues.copyPublic(definition);
         try {
             await this.#options.creator.cancel({ wire: privateWire }, signal);
@@ -715,7 +1023,11 @@ const SubscriptionGatewayValues = Object.freeze({
      * @returns Copied public subscription bytes.
      */
     copyPublic(wire) {
-        return { kind: wire.kind, bytes: wire.bytes.slice() };
+        return {
+            kind: wire.kind,
+            bytes: wire.bytes.slice(),
+            ...(wire.reader === undefined ? {} : { reader: snapshotTrustedReader(wire.reader) }),
+        };
     },
     /**
      * Builds a successful subscription response.