@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/dist/server/node-coordinator.js

@@ -15,17 +15,23 @@ import * as http2 from "node:http2";
 import { randomUUID } from "node:crypto";
 import { clone, create, equals, fromBinary, toBinary } from "@bufbuild/protobuf";
 import { EmptySchema } from "@bufbuild/protobuf/wkt";
-import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { Code, ConnectError, createClient, } from "@connectrpc/connect";
 import { connectNodeAdapter, createGrpcTransport, Http2SessionManager, } from "@connectrpc/connect-node";
 import { BackendMembershipKernel, } from "@spine-event-engine/deployment/spi/backend-membership";
 import { SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS } from "@spine-event-engine/core/spi/subscription-lifecycle";
+import { Validate } from "@spine-event-engine/core";
+import { ReaderForwarding, } from "@spine-event-engine/core/spi/reader-forwarding";
+import { ReaderIdentities, snapshotTrustedReader, } from "@spine-event-engine/core/spi/trusted-reader";
 import { AckSchema, ResponseSchema, StatusSchema, } from "@spine-event-engine/proto";
-import { QueryResponseSchema, CommandService, QueryService, SubscriptionIdSchema, SubscriptionSchema, SubscriptionService, SubscriptionUpdateSchema, TopicSchema, } from "@spine-event-engine/proto/client";
+import { AppQueryResponseSchema, AppQuerySchema, QueryResponseSchema, QuerySchema, CommandService, QueryService, SubscriptionIdSchema, SubscriptionSchema, SubscriptionService, SubscriptionUpdateSchema, TopicSchema, } from "@spine-event-engine/proto/client";
+import { ReadRequestStatus } from "../services/read-request-status.js";
+import { TrustedReaderIngress, } from "../services/trusted-reader-ingress.js";
+import { NativeOperation } from "../services/native-operation.js";
+import { ServerEnvironment } from "./server-environment.js";
 const defaultHost = "127.0.0.1";
 const defaultPort = 0;
 const defaultMessageMaxBytes = 4_194_304;
 const gracefulSessionDrainMs = 100;
-const subscriptionQueueLimit = 100;
 /**
  * Hosts generated unary services in front of managed complete replicas.
  *
@@ -34,6 +40,13 @@ const subscriptionQueueLimit = 100;
 export class NodeCoordinator {
     // prettier-ignore
     #members;
+    #readerAdmission;
+    #forwardingProof;
+    #readers = new Map();
+    #children = new Map();
+    #logicalForChild = new Map();
+    #readMaxBytes;
+    #subscriptionQueueCapacity;
     #unaryKernel;
     #subscriptionKernel;
     #server;
@@ -59,6 +72,7 @@ export class NodeCoordinator {
     #close;
     #networkClose;
     #draining = false;
+    #admissionShutdown = new AbortController();
     #membershipReconciliation = Promise.resolve();
     /**
      * Creates the native node coordinator around its HTTP/2 listener and member source.
@@ -67,26 +81,48 @@ export class NodeCoordinator {
      * @param server The HTTP/2 server.
      * @param address The listening address.
      * @param sessions Tracked HTTP/2 sessions.
+     * @param subscriptionQueueCapacity Resolved bound for each managed subscriber.
      */
-    constructor(options, server, address, sessions) {
+    constructor(options, server, address, sessions, subscriptionQueueCapacity) {
         this.#members = options.members;
-        this.#unaryKernel = new BackendMembershipKernel(NodeCoordinatorValues.unaryKernelOptions());
-        this.#subscriptionKernel = new BackendMembershipKernel(NodeCoordinatorValues.unaryKernelOptions(options.members));
+        this.#readerAdmission = options.readerAdmission;
+        this.#forwardingProof = options.forwardingProof;
+        this.#readMaxBytes = options.readMaxBytes ?? defaultMessageMaxBytes;
+        this.#subscriptionQueueCapacity = subscriptionQueueCapacity;
+        this.#unaryKernel = new BackendMembershipKernel(NodeCoordinatorValues.unaryKernelOptions(undefined, this.#forwardingProof, this.#readMaxBytes, (bytes) => this.#readerFor(bytes)));
+        this.#subscriptionKernel = this.#makeSubscriptionKernel(options.members);
         this.#server = server;
         this.#sessions = sessions;
         this.host = address.address;
         this.port = address.port;
         this.baseUrl = `http://${NodeCoordinatorValues.formatHostForUrl(this.host)}:${this.port.toString()}`;
         const reconcile = () => {
-            this.#membershipReconciliation = this.#membershipReconciliation
-                .then(() => this.#reconcile(), () => this.#reconcile())
-                .catch(() => undefined);
+            this.#scheduleReconciliation();
         };
         this.#stopMembers = [
             options.members.onReadyMembersChange(reconcile),
             options.members.onRelayMembersChange(reconcile),
         ];
     }
+    /**
+     * Builds the subscription kernel with reader provenance for each child.
+     *
+     * @param members The available backend member source.
+     * @returns The native subscription kernel.
+     */
+    #makeSubscriptionKernel(members) {
+        return new BackendMembershipKernel(NodeCoordinatorValues.unaryKernelOptions(members, this.#forwardingProof, this.#readMaxBytes, (bytes) => this.#readerFor(bytes), (definition, child) => {
+            this.#rememberChild(definition, child);
+        }));
+    }
+    /**
+     * Serializes membership refresh after readiness or relay changes.
+     */
+    #scheduleReconciliation() {
+        this.#membershipReconciliation = this.#membershipReconciliation
+            .then(() => this.#reconcile(), () => this.#reconcile())
+            .catch(() => undefined);
+    }
     /**
      * Opens one generated unary-service listener.
      *
@@ -94,37 +130,44 @@ export class NodeCoordinator {
      * @returns The running private Coordinator.
      */
     static async open(options) {
+        const subscriptionQueueCapacity = ServerEnvironment.instance().subscriptionQueueCapacity;
         const { host, port, readMaxBytes, writeMaxBytes } = this.#listenerOptions(options);
         // eslint-disable-next-line prefer-const -- routes capture the Coordinator before the listener exists.
         let coordinator;
         const sessions = new Set();
         const server = http2.createServer(connectNodeAdapter({
             routes: (router) => {
-                router.service(CommandService, {
-                    post: async (command, context) => {
-                        return coordinator.#post(command, context);
-                    },
-                });
-                router.service(QueryService, {
-                    read: async (query, context) => {
-                        return coordinator.#read(query, context);
-                    },
-                });
-                router.service(SubscriptionService, {
-                    subscribe: (topic, context) => coordinator.#subscribe(topic, context),
-                    activate: (subscription, context) => coordinator.#activate(subscription, context),
-                    cancel: (subscription, context) => coordinator.#cancel(subscription, context),
-                });
+                this.#routes(router, () => coordinator);
             },
             readMaxBytes,
             writeMaxBytes,
         }));
         this.#trackSessions(server, sessions);
         const address = await NodeCoordinatorValues.listen(server, host, port);
-        coordinator = new NodeCoordinator(options, server, address, sessions);
+        coordinator = new NodeCoordinator(options, server, address, sessions, subscriptionQueueCapacity);
         await coordinator.#reconcile();
         return coordinator;
     }
+    /**
+     * Registers native service routes after the listener receives its Coordinator instance.
+     *
+     * @param router Connect router for the private listener.
+     * @param current Returns the initialized Coordinator at request time.
+     */
+    static #routes(router, current) {
+        router.service(CommandService, {
+            post: (command, context) => current().#post(command, context),
+        });
+        router.service(QueryService, {
+            read: (query, context) => current().#read(query, context),
+            execute: (query, context) => current().#execute(query, context),
+        });
+        router.service(SubscriptionService, {
+            subscribe: (topic, context) => current().#subscribe(topic, context),
+            activate: (subscription, context) => current().#activate(subscription, context),
+            cancel: (subscription, context) => current().#cancel(subscription, context),
+        });
+    }
     /**
      * Validates private listener and message limits before opening the server.
      *
@@ -157,6 +200,7 @@ export class NodeCoordinator {
      * @returns Completion after bounded Coordinator cleanup.
      */
     close() {
+        this.#admissionShutdown.abort();
         this.#close ??= this.#closeOnce().catch((error) => {
             this.#close = undefined;
             throw error;
@@ -181,46 +225,238 @@ export class NodeCoordinator {
         await this.#membershipReconciliation;
         await this.#subscriptionKernel.close();
     }
+    /**
+     * Admits a command reader and forwards the command to a managed child.
+     *
+     * @param command Command envelope from the native client.
+     * @param context The trusted context for this operation.
+     * @returns Child acknowledgment after forwarding.
+     */
     async #post(command, context) {
-        const request = {
-            kind: "command",
-            command,
-            context,
-            response: create(AckSchema),
-        };
-        await this.#forward(request);
-        return request.response;
+        return this.#runAdmitted("spine.client.CommandService", "Post", toBinary(CommandService.method.post.input, command), context, async (reader, signal) => {
+            const request = {
+                kind: "command",
+                command,
+                context,
+                reader,
+                signal,
+                response: create(AckSchema),
+            };
+            await this.#forward(request);
+            return request.response;
+        });
     }
+    /**
+     * Admits a read reader and forwards the query to a managed child.
+     *
+     * @param query Query envelope from the native client.
+     * @param context The trusted context for this operation.
+     * @returns Child read response after forwarding.
+     */
     async #read(query, context) {
-        const request = {
-            kind: "query",
-            query,
-            context,
-            response: create(QueryResponseSchema),
-        };
-        await this.#forward(request);
-        return request.response;
+        return this.#runAdmitted("spine.client.QueryService", "Read", toBinary(QuerySchema, query), context, async (reader, signal) => {
+            ReadRequestStatus.check("query", () => Validate.check(QuerySchema, query));
+            const request = {
+                kind: "query",
+                query,
+                context,
+                reader,
+                signal,
+                response: create(QueryResponseSchema),
+            };
+            await this.#forward(request);
+            return request.response;
+        });
+    }
+    /**
+     * Admits an App Query and forwards it to a ready application replica.
+     *
+     * @param query App Query envelope.
+     * @param context Native RPC context.
+     * @returns The application replica's response.
+     */
+    async #execute(query, context) {
+        return this.#runAdmitted("spine.client.QueryService", "Execute", toBinary(QueryService.method.execute.input, query), context, async (reader, signal) => {
+            ReadRequestStatus.check("query", () => Validate.check(AppQuerySchema, query));
+            const request = {
+                kind: "app-query",
+                query,
+                context,
+                reader,
+                signal,
+                response: create(AppQueryResponseSchema),
+            };
+            await this.#forward(request);
+            return request.response;
+        });
     }
+    /**
+     * Verifies forwarded or direct reader facts at the managed ingress.
+     *
+     * @param service Canonical RPC service.
+     * @param method Canonical RPC method.
+     * @param request Canonical request bytes.
+     * @param context Native transport context.
+     * @param signal Host-managed operation lifetime.
+     * @returns Captured reader admission and invalidation.
+     */
+    #admit(service, method, request, context, signal) {
+        return TrustedReaderIngress.admit({
+            service,
+            method,
+            request,
+            headers: context.requestHeader,
+            peer: context,
+            signal,
+            maxBytes: this.#readMaxBytes,
+            ...this.#readerAdmission,
+        });
+    }
+    /**
+     * Holds one unary operation through admission and child work.
+     *
+     * @typeParam T Native response type.
+     * @param service Canonical RPC service.
+     * @param method Canonical RPC method.
+     * @param bytes Canonical request bytes.
+     * @param context Original peer metadata.
+     * @param work Verified action using the effective signal.
+     * @returns Result while admission remains valid.
+     */
+    async #runAdmitted(service, method, bytes, context, work) {
+        const operation = new NativeOperation(context.signal, this.#admissionShutdown.signal);
+        try {
+            const admission = await this.#admit(service, method, bytes, context, operation.signal);
+            operation.link(admission.invalidated);
+            operation.check();
+            const result = await work(admission.reader, operation.signal);
+            operation.check();
+            return result;
+        }
+        finally {
+            operation.close();
+        }
+    }
+    /**
+     * Validates and retains a reader-bound subscription definition.
+     *
+     * @param topic Framework subscription Topic.
+     * @param context The trusted context for this operation.
+     * @returns The new subscription definition.
+     */
     async #subscribe(topic, context) {
+        const operation = new NativeOperation(context.signal, this.#admissionShutdown.signal);
+        try {
+            const admission = await this.#admit("spine.client.SubscriptionService", "Subscribe", toBinary(TopicSchema, topic), context, operation.signal);
+            operation.link(admission.invalidated);
+            operation.check();
+            const subscription = await this.#subscribeReader(topic, admission.reader, operation.signal);
+            try {
+                operation.check();
+            }
+            catch (error) {
+                return await this.#compensateSubscribe(subscription, error);
+            }
+            return subscription;
+        }
+        finally {
+            operation.close();
+        }
+    }
+    /**
+     * Removes a committed definition after a failed final admission check.
+     *
+     * @param subscription Created logical definition.
+     * @param error Final admission failure.
+     * @returns Rejected completion after conditional cleanup.
+     */
+    async #compensateSubscribe(subscription, error) {
+        this.#clearPendingActivation(subscription);
+        try {
+            await this.#cancelDefinition(toBinary(SubscriptionSchema, subscription), new AbortController().signal);
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], "Coordinator Subscribe cleanup failed.");
+        }
+        throw error;
+    }
+    /**
+     * Creates a reader-bound definition under its native operation lifetime.
+     *
+     * @param topic Framework subscription Topic.
+     * @param reader Detached authenticated facts.
+     * @param signal Effective cancellation.
+     * @returns Created logical definition.
+     */
+    async #subscribeReader(topic, reader, signal) {
+        ReadRequestStatus.check("topic", () => Validate.check(TopicSchema, topic));
         if (this.#draining)
             throw new ConnectError("Managed application is closing.", Code.Unavailable);
         const subscription = create(SubscriptionSchema, {
             id: create(SubscriptionIdSchema, { value: `s-${randomUUID()}` }),
             topic,
         });
+        const id = subscription.id?.value;
+        if (id === undefined)
+            throw new Error("Created subscription has no ID.");
+        const definition = toBinary(SubscriptionSchema, subscription);
+        this.#readers.set(id, reader);
         try {
-            await this.#subscriptionKernel.subscribe(toBinary(SubscriptionSchema, subscription), context.signal);
+            await this.#createDefinition(definition, signal);
         }
         catch (error) {
+            if (!(error instanceof AggregateError))
+                this.#forgetReader(id);
+            if (signal.aborted && !(error instanceof AggregateError))
+                throw new ConnectError("Reader operation cancelled.", Code.Canceled);
             throw this.#availabilityError(error);
         }
-        if (this.#isDraining()) {
-            await this.#cancelDefinition(toBinary(SubscriptionSchema, subscription), context.signal);
+        if (this.#isDraining() || signal.aborted) {
+            await this.#cancelDefinition(definition, new AbortController().signal);
             throw new ConnectError("Managed application is closing.", Code.Unavailable);
         }
         this.#schedulePendingActivation(subscription);
         return subscription;
     }
+    /**
+     * Cancels a pending child creation when the requesting reader loses authority.
+     *
+     * @param definition Logical subscription definition.
+     * @param signal Reader operation lifetime.
+     * @returns Completion after creation or conditional cancellation settles.
+     */
+    async #createDefinition(definition, signal) {
+        let cancellation;
+        const abort = () => {
+            cancellation = this.#cancelDefinition(definition, new AbortController().signal);
+            void cancellation.catch(() => undefined);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        let failed = false;
+        let primary;
+        try {
+            await this.#subscriptionKernel.subscribe(definition, signal);
+        }
+        catch (error) {
+            failed = true;
+            primary = error;
+        }
+        finally {
+            signal.removeEventListener("abort", abort);
+        }
+        if (signal.aborted && cancellation === undefined)
+            abort();
+        try {
+            await cancellation;
+        }
+        catch (cleanup) {
+            throw new AggregateError(failed ? [primary, cleanup] : [cleanup], "Subscription cancellation failed.");
+        }
+        if (failed)
+            throw primary;
+        if (signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
+    }
     /**
      * Reads current admission state after an asynchronous backend Subscribe.
      *
@@ -229,7 +465,32 @@ export class NodeCoordinator {
     #isDraining() {
         return this.#draining;
     }
+    /**
+     * Verifies membership and activates a retained subscription.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param context The trusted context for this operation.
+     * @returns The update stream after admission.
+     */
     async *#activate(subscription, context) {
+        const operation = new NativeOperation(context.signal, this.#admissionShutdown.signal);
+        try {
+            await this.#admitActivation(subscription, context, operation);
+            operation.check();
+            yield* this.#relayActivation(subscription, operation);
+        }
+        finally {
+            operation.close();
+        }
+    }
+    /**
+     * Relays one admitted definition through ACK and complete child iteration.
+     *
+     * @param subscription Retained logical definition.
+     * @param operation Host-managed activation lifetime.
+     * @returns ACK and surviving updates.
+     */
+    async *#relayActivation(subscription, operation) {
         if (this.#draining)
             throw new ConnectError("Managed application is closing.", Code.Unavailable);
         const definition = toBinary(SubscriptionSchema, subscription);
@@ -238,46 +499,84 @@ export class NodeCoordinator {
         const abort = () => {
             overflow.abort();
         };
-        context.signal.addEventListener("abort", abort, { once: true });
-        if (context.signal.aborted)
+        operation.signal.addEventListener("abort", abort, { once: true });
+        if (operation.signal.aborted)
             abort();
-        const updates = new SubscriptionUpdateQueue(subscriptionQueueLimit, abort);
-        const activation = this.#activateChild(definition, subscription, updates, overflow.signal);
+        const updates = new SubscriptionUpdateQueue(this.#subscriptionQueueCapacity, abort);
+        const ack = Promise.withResolvers();
+        const activation = this.#activateChild(definition, subscription, updates, ack, overflow.signal);
         let failure;
         try {
-            for await (const update of updates)
+            const ready = await ack.promise;
+            operation.check();
+            if (ready !== undefined)
+                yield ready;
+            for await (const update of updates) {
+                operation.check();
                 yield update;
+            }
         }
         catch (error) {
             failure = NodeCoordinatorValues.error(error);
         }
         finally {
-            context.signal.removeEventListener("abort", abort);
+            operation.signal.removeEventListener("abort", abort);
             overflow.abort();
             updates.close();
             await this.#finishActivation(definition, activation, failure);
         }
     }
+    /**
+     * Admits and validates a reader-bound activation before changing pending state.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param context The trusted context for this operation.
+     * @returns Completion after the operation settles.
+     */
+    async #admitActivation(subscription, context, operation) {
+        const admission = await this.#admit("spine.client.SubscriptionService", "Activate", toBinary(SubscriptionSchema, subscription), context, operation.signal);
+        operation.link(admission.invalidated);
+        operation.check();
+        ReadRequestStatus.check("subscription", () => Validate.check(SubscriptionSchema, subscription));
+        ReadRequestStatus.checkLifecycleCriterion(subscription);
+        this.#requireReader(subscription, admission.reader);
+    }
     /**
      * Relays accepted child updates through the bounded logical stream.
      *
      * @param definition The validated child subscription bytes.
      * @param subscription The logical subscription exposed to callers.
      * @param updates The bounded caller stream queue.
+     * @param ack The separate activation acknowledgment gate.
      * @param signal Cancels the active child relay.
      * @returns Completion after the backend activation ends.
      */
-    #activateChild(definition, subscription, updates, signal) {
+    #activateChild(definition, subscription, updates, ack, signal) {
         return this.#subscriptionKernel
             .activate(definition, async (childUpdate) => {
+            if (signal.aborted)
+                return;
             const update = fromBinary(SubscriptionUpdateSchema, childUpdate);
             update.subscription = clone(SubscriptionSchema, subscription);
+            if (update.response?.status?.status.case === "ok" && update.update.case === undefined) {
+                ack.resolve(update);
+                return;
+            }
             await updates.push(update);
         }, signal)
             .finally(() => {
+            ack.resolve(undefined);
             updates.close();
         });
     }
+    /**
+     * Finishes one activated stream and clears pending state.
+     *
+     * @param definition The serialized subscription definition.
+     * @param activation Activation task and its stream state.
+     * @param previousFailure Earlier lifecycle failure.
+     * @returns Completion after the operation settles.
+     */
     async #finishActivation(definition, activation, previousFailure) {
         const failures = previousFailure === undefined ? [] : [previousFailure];
         try {
@@ -298,16 +597,51 @@ export class NodeCoordinator {
         if (failures.length > 1)
             throw new AggregateError(failures, "Coordinator activation cleanup failed.");
     }
+    /**
+     * Verifies reader membership and removes a retained subscription.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param context The trusted context for this operation.
+     * @returns The cancellation acknowledgment.
+     */
     async #cancel(subscription, context) {
+        return this.#runAdmitted("spine.client.SubscriptionService", "Cancel", toBinary(SubscriptionSchema, subscription), context, (reader, signal) => this.#cancelReader(subscription, reader, signal));
+    }
+    /**
+     * Checks reader binding before removing an existing definition.
+     *
+     * @param subscription Logical definition.
+     * @param reader Detached authenticated facts.
+     * @param signal Effective cancellation.
+     * @returns Cancellation acknowledgment.
+     */
+    async #cancelReader(subscription, reader, signal) {
+        ReadRequestStatus.check("subscription", () => Validate.check(SubscriptionSchema, subscription));
+        ReadRequestStatus.checkLifecycleCriterion(subscription);
+        const id = subscription.id?.value;
+        if (id !== undefined && this.#readers.has(id))
+            this.#requireReader(subscription, reader);
+        else
+            return create(ResponseSchema, {
+                status: create(StatusSchema, { status: { case: "ok", value: create(EmptySchema) } }),
+            });
         this.#clearPendingActivation(subscription);
-        await this.#cancelDefinition(toBinary(SubscriptionSchema, subscription), context.signal);
+        await this.#cancelDefinition(toBinary(SubscriptionSchema, subscription), signal);
         return create(ResponseSchema, {
             status: create(StatusSchema, { status: { case: "ok", value: create(EmptySchema) } }),
         });
     }
+    /**
+     * Forwards a verified request to the selected managed child.
+     *
+     * @param request The request being processed.
+     * @returns Completion after the operation settles.
+     */
     async #forward(request) {
         if (this.#draining)
             throw new ConnectError("No ready application replica is available.", Code.Unavailable);
+        if (request.signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
         try {
             await this.#unaryKernel.forward(request);
         }
@@ -315,11 +649,22 @@ export class NodeCoordinator {
             throw this.#availabilityError(error);
         }
     }
+    /**
+     * Maps child transport failure to the public availability status.
+     *
+     * @param error The failure being classified or propagated.
+     * @returns The public transport error.
+     */
     #availabilityError(error) {
         return error instanceof Error && error.message === "backend membership is unavailable."
             ? new ConnectError("No ready application replica is available.", Code.Unavailable)
             : error;
     }
+    /**
+     * Starts the activation handshake expiry for a new subscription.
+     *
+     * @param subscription The subscription definition being processed.
+     */
     #schedulePendingActivation(subscription) {
         const id = NodeCoordinatorValues.requiredValue(subscription.id?.value, "Coordinator subscription definition is missing an ID.");
         this.#clearPendingActivation(subscription);
@@ -332,18 +677,98 @@ export class NodeCoordinator {
         pending.timer.unref();
         this.#pendingActivations.set(id, pending);
     }
+    /**
+     * Forwards cancellation of a native subscription definition.
+     *
+     * @param definition The serialized subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @returns Completion after the operation settles.
+     */
     #cancelDefinition(definition, signal) {
         const id = NodeCoordinatorValues.requiredValue(fromBinary(SubscriptionSchema, definition).id?.value, "Coordinator subscription definition is missing an ID.");
         const active = this.#cancellations.get(id);
         if (active !== undefined)
             return active;
-        const cancellation = this.#subscriptionKernel.cancel(definition, signal).finally(() => {
+        const cancellation = this.#subscriptionKernel
+            .cancel(definition, signal)
+            .then(() => {
+            this.#forgetReader(id);
+        })
+            .finally(() => {
             if (this.#cancellations.get(id) === cancellation)
                 this.#cancellations.delete(id);
         });
         this.#cancellations.set(id, cancellation);
         return cancellation;
     }
+    /**
+     * Verifies and refreshes the reader before subscription effects.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param reader The verified reader facts for this operation.
+     */
+    #requireReader(subscription, reader) {
+        const id = subscription.id?.value;
+        const previous = id === undefined ? undefined : this.#readers.get(id);
+        if (id === undefined || previous === undefined)
+            throw ReadRequestStatus.unknownSubscription();
+        if (!ReaderIdentities.matches(ReaderIdentities.from(previous), ReaderIdentities.from(reader)))
+            throw new ConnectError("Subscription reader is not authorized.", Code.PermissionDenied);
+        this.#readers.set(id, reader);
+        for (const child of this.#children.get(id) ?? [])
+            this.#readers.set(child, reader);
+    }
+    /**
+     * Associates one native child with the admitted logical reader.
+     *
+     * @param definition The serialized subscription definition.
+     * @param child The native child subscription definition.
+     */
+    #rememberChild(definition, child) {
+        const id = fromBinary(SubscriptionSchema, definition).id?.value;
+        const childId = fromBinary(SubscriptionSchema, child).id?.value;
+        if (id === undefined || childId === undefined)
+            return;
+        const logicalId = this.#logicalForChild.get(id) ?? (this.#readers.has(id) ? id : undefined);
+        if (logicalId === undefined)
+            return;
+        const children = this.#children.get(logicalId) ?? new Set();
+        children.add(childId);
+        this.#children.set(logicalId, children);
+        this.#logicalForChild.set(childId, logicalId);
+        const reader = this.#readers.get(id);
+        if (reader !== undefined)
+            this.#readers.set(childId, reader);
+    }
+    /**
+     * Returns current detached facts for a logical or child subscription.
+     *
+     * @param bytes The serialized message bytes.
+     * @returns The verified reader for this subscription.
+     */
+    #readerFor(bytes) {
+        const id = fromBinary(SubscriptionSchema, bytes).id?.value;
+        const reader = id === undefined ? undefined : this.#readers.get(id);
+        return reader === undefined ? undefined : snapshotTrustedReader(reader);
+    }
+    /**
+     * Removes a finished logical definition and its current child mappings.
+     *
+     * @param id The stable identifier for this record.
+     */
+    #forgetReader(id) {
+        this.#readers.delete(id);
+        for (const child of this.#children.get(id) ?? []) {
+            this.#readers.delete(child);
+            this.#logicalForChild.delete(child);
+        }
+        this.#children.delete(id);
+    }
+    /**
+     * Removes a pending activation timer and its tracking entry.
+     *
+     * @param subscription The subscription definition being processed.
+     */
     #clearPendingActivation(subscription) {
         const id = subscription.id?.value;
         if (id === undefined)
@@ -354,6 +779,13 @@ export class NodeCoordinator {
         clearTimeout(pending.timer);
         this.#pendingActivations.delete(id);
     }
+    /**
+     * Expires an unactivated subscription after its handshake window.
+     *
+     * @param id The stable identifier for this record.
+     * @param pending Pending activation or retry state.
+     * @returns Completion after the operation settles.
+     */
     async #expirePendingActivation(id, pending) {
         if (this.#pendingActivations.get(id) !== pending)
             return;
@@ -367,6 +799,11 @@ export class NodeCoordinator {
                 this.#schedulePendingActivation(fromBinary(SubscriptionSchema, pending.definition));
         }
     }
+    /**
+     * Reconciles managed child subscriptions after topology changes.
+     *
+     * @returns Completion after the operation settles.
+     */
     #reconcile() {
         if (this.#members.onRelaySynchronized !== undefined)
             return this.#subscriptionKernel
@@ -377,6 +814,11 @@ export class NodeCoordinator {
             this.#subscriptionKernel.reconcile(this.#members.relayMembers()),
         ]).then(() => undefined);
     }
+    /**
+     * Runs shutdown once while concurrent callers await the same completion.
+     *
+     * @returns Completion after the operation settles.
+     */
     async #closeOnce() {
         this.#stopMembers.forEach((stop) => {
             stop();
@@ -395,16 +837,16 @@ export class NodeCoordinator {
  * @internal
  */
 export class SubscriptionUpdateQueue {
+    #active;
     #updates = [];
     #waiters = [];
-    #delivered = [];
     #limit;
     #onOverflow;
     #closed = false;
     /**
      * Creates one terminal bounded update queue.
      *
-     * @param limit Limits retained updates before terminal closure.
+     * @param limit Maximum waiting updates beyond one active update.
      * @param onOverflow Aborts the public relay when the queue reaches its bound.
      */
     constructor(limit, onOverflow = () => undefined) {
@@ -420,18 +862,22 @@ export class SubscriptionUpdateQueue {
     push(update) {
         if (this.#closed)
             return Promise.resolve();
-        const waiter = this.#waiters.shift();
-        if (waiter !== undefined) {
-            waiter({ value: update, done: false });
-            return Promise.resolve();
-        }
-        if (this.#updates.length >= this.#limit) {
+        if (this.#active !== undefined && this.#updates.length >= this.#limit) {
             this.#onOverflow();
             this.close();
             return Promise.resolve();
         }
-        this.#updates.push(update);
-        return new Promise((resolve) => this.#delivered.push(resolve));
+        return new Promise((resolve) => {
+            const entry = { update, delivered: false, resolve };
+            if (this.#active === undefined) {
+                this.#active = entry;
+                const waiter = this.#waiters.shift();
+                if (waiter !== undefined)
+                    waiter(this.#deliver(entry));
+            }
+            else
+                this.#updates.push(entry);
+        });
     }
     /**
      * Closes the queue and releases all waiting producers and consumers.
@@ -440,11 +886,20 @@ export class SubscriptionUpdateQueue {
         if (this.#closed)
             return;
         this.#closed = true;
-        this.#updates.length = 0;
+        this.#active?.resolve();
+        this.#active = undefined;
+        for (const update of this.#updates.splice(0))
+            update.resolve();
         for (const waiter of this.#waiters.splice(0))
             waiter({ value: undefined, done: true });
-        for (const delivered of this.#delivered.splice(0))
-            delivered();
+    }
+    /**
+     * Resolves one waiting consumer with the next queued subscription update.
+     */
+    #deliver(entry) {
+        entry.delivered = true;
+        entry.resolve();
+        return { value: entry.update, done: false };
     }
     /**
      * Returns queued updates until the terminal close.
@@ -454,13 +909,12 @@ export class SubscriptionUpdateQueue {
     [Symbol.asyncIterator]() {
         return {
             next: () => {
-                const update = this.#updates.shift();
-                if (update !== undefined) {
-                    this.#delivered.shift()?.();
-                    return Promise.resolve({ value: update, done: false });
-                }
                 if (this.#closed)
                     return Promise.resolve({ value: undefined, done: true });
+                if (this.#active?.delivered)
+                    this.#active = this.#updates.shift();
+                if (this.#active !== undefined)
+                    return Promise.resolve(this.#deliver(this.#active));
                 return new Promise((resolve) => this.#waiters.push(resolve));
             },
         };
@@ -472,20 +926,35 @@ const NodeCoordinatorValues = Object.freeze({
      *
      * @param members The ready member source when available.
      * @returns The configured membership kernel options.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @param readerFor Reader lookup for a retained subscription.
+     * @param onRememberChild Records a native child ID for its logical subscription.
      */
-    unaryKernelOptions(members) {
-        // The Coordinator deliberately uses only the kernel's member lifecycle and
-        // one-shot forwarding operations. Subscription fan-out is owned by T-0208.
+    unaryKernelOptions(members, issuer, maxBytes = defaultMessageMaxBytes, readerFor, onRememberChild) {
         return {
-            create: (member) => Promise.resolve(NodeCoordinatorValues.client(member, members)),
+            create: (member) => Promise.resolve(NodeCoordinatorValues.client(member, members, issuer, maxBytes, readerFor, onRememberChild)),
             memberKey: (member) => `${member.slot.toString()}/${member.incarnation}`,
             sameMember: (left, right) => left.endpoint === right.endpoint,
             definitionKey: (definition) => fromBinary(SubscriptionSchema, definition).id?.value,
-            childDefinition: NodeCoordinatorValues.childDefinition,
+            childDefinition: (definition, member) => NodeCoordinatorValues.rememberChildDefinition(definition, member, onRememberChild),
             childSize: (child) => child.byteLength,
             ...NodeCoordinatorValues.activationAckOptions(members),
         };
     },
+    /**
+     * Builds and records a child definition before member subscription.
+     *
+     * @param definition The serialized subscription definition.
+     * @param member The selected backend member.
+     * @param onRememberChild Records a native child ID for its logical subscription.
+     * @returns The retained managed-child definition.
+     */
+    rememberChildDefinition(definition, member, onRememberChild) {
+        const child = NodeCoordinatorValues.childDefinition(definition, member);
+        onRememberChild?.(definition, child);
+        return child;
+    },
     /**
      * Builds strict child ACK validation for the subscription membership kernel.
      *
@@ -526,49 +995,178 @@ const NodeCoordinatorValues = Object.freeze({
      * @param member The discovered backend member.
      * @param members The ready member source when available.
      * @returns The member transport client.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @param readerFor Reader lookup for a retained subscription.
+     * @param onRememberChild Records a native child ID for its logical subscription.
      */
-    client(member, members) {
+    client(member, members, issuer, maxBytes = defaultMessageMaxBytes, readerFor, onRememberChild) {
         const manager = new Http2SessionManager(member.endpoint);
         const transport = createGrpcTransport({ baseUrl: member.endpoint, sessionManager: manager });
         return {
-            forward: (request) => NodeCoordinatorValues.forward(transport, request),
-            close: () => {
-                manager.abort();
-                return Promise.resolve();
-            },
-            subscribe: async (definition, signal) => {
-                const subscription = fromBinary(SubscriptionSchema, definition);
-                const created = await createClient(SubscriptionService, transport).subscribe(NodeCoordinatorValues.requiredValue(subscription.topic, "Coordinator subscription definition is missing a Topic."), { signal });
-                return toBinary(SubscriptionSchema, created);
-            },
-            activate: (child, updates, signal) => NodeCoordinatorValues.activateChild(transport, member, members, child, updates, signal),
-            dispose: async (child, signal) => {
-                const subscription = fromBinary(SubscriptionSchema, child);
-                members?.onChildSubscriptionCancelled?.(member, subscription);
-                await createClient(SubscriptionService, transport).cancel(subscription, { signal });
-            },
+            forward: (request) => NodeCoordinatorValues.forward(transport, request, issuer, maxBytes),
+            close: () => NodeCoordinatorValues.closeManager(manager),
+            subscribe: (definition, signal) => NodeCoordinatorValues.subscribeChild(transport, definition, signal, readerFor?.(definition), issuer, maxBytes, onRememberChild),
+            ...NodeCoordinatorValues.childOperations(transport, member, members, issuer, maxBytes, readerFor),
         };
     },
     /**
-     * Sends one native Command or Query to a ready member.
+     * Closes the transport manager for a departed native member.
+     *
+     * @param manager Native session manager.
+     * @returns Completion after the operation settles.
+     */
+    closeManager(manager) {
+        manager.abort();
+        return Promise.resolve();
+    },
+    /**
+     * Returns streaming and cancellation operations for a native member.
+     *
+     * @param transport The connected native transport.
+     * @param member The selected backend member.
+     * @param members The available backend member source.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @param readerFor Reader lookup for a retained subscription.
+     * @returns The managed-child operations.
+     */
+    childOperations(transport, member, members, issuer, maxBytes, readerFor) {
+        return {
+            activate: NodeCoordinatorValues.activation(transport, member, members, issuer, maxBytes, readerFor),
+            dispose: (child, signal) => NodeCoordinatorValues.cancelChild(transport, member, members, child, signal, readerFor?.(child), issuer, maxBytes),
+        };
+    },
+    /**
+     * Captures native member context for one child stream.
+     *
+     * @param transport The connected native transport.
+     * @param member The selected backend member.
+     * @param members The available backend member source.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @param readerFor Reader lookup for a retained subscription.
+     * @returns The activation stream completion.
+     */
+    activation(transport, member, members, issuer, maxBytes, readerFor) {
+        return (child, updates, signal) => NodeCoordinatorValues.activateChild(transport, member, members, child, updates, signal, readerFor?.(child), issuer, maxBytes);
+    },
+    /**
+     * Creates one native child and records any backend-assigned ID.
+     *
+     * @param transport The connected native transport.
+     * @param definition The serialized subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @param onRememberChild Records a native child ID for its logical subscription.
+     * @returns The managed-child subscription.
+     */
+    async subscribeChild(transport, definition, signal, reader, issuer, maxBytes, onRememberChild) {
+        const subscription = fromBinary(SubscriptionSchema, definition);
+        const topic = NodeCoordinatorValues.requiredValue(subscription.topic, "Coordinator subscription definition is missing a Topic.");
+        const headers = await NodeCoordinatorValues.readerHeaders("Subscribe", toBinary(TopicSchema, topic), reader, issuer, maxBytes);
+        if (signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
+        const created = await createClient(SubscriptionService, transport).subscribe(topic, {
+            signal,
+            ...(headers === undefined ? {} : { headers }),
+        });
+        const bytes = toBinary(SubscriptionSchema, created);
+        onRememberChild?.(definition, bytes);
+        return bytes;
+    },
+    /**
+     * Cancels one native child with the same verified reader as its creation.
+     *
+     * @param transport The connected native transport.
+     * @param member The selected backend member.
+     * @param members The available backend member source.
+     * @param child The native child subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @returns Completion after the operation settles.
+     */
+    async cancelChild(transport, member, members, child, signal, reader, issuer, maxBytes) {
+        const subscription = fromBinary(SubscriptionSchema, child);
+        const headers = await NodeCoordinatorValues.readerHeaders("Cancel", child, reader, issuer, maxBytes);
+        if (signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
+        members?.onChildSubscriptionCancelled?.(member, subscription);
+        await createClient(SubscriptionService, transport).cancel(subscription, {
+            signal,
+            ...(headers === undefined ? {} : { headers }),
+        });
+    },
+    /**
+     * Sends one native Command, entity read, or App Query to a ready member.
      *
      * @param transport The connected native transport.
      * @param request The request to forward.
      * @returns Empty routing bytes after the response is assigned.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
      */
-    async forward(transport, request) {
+    async forward(transport, request, issuer, maxBytes = defaultMessageMaxBytes) {
+        const headers = await NodeCoordinatorValues.forwardHeaders(request, issuer, maxBytes);
+        if (request.signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
         if (request.kind === "command") {
-            const response = await transport.unary(CommandService.method.post, request.context.signal, request.context.timeoutMs(), NodeCoordinatorValues.applicationHeaders(request.context.requestHeader), request.command);
+            await NodeCoordinatorValues.forwardCommand(transport, request, headers);
+        }
+        else if (request.kind === "query") {
+            const response = await transport.unary(QueryService.method.read, request.signal, request.context.timeoutMs(), headers, request.query);
             NodeCoordinatorValues.responseMetadata(response.header, response.trailer, request.context);
             request.response = response.message;
         }
         else {
-            const response = await transport.unary(QueryService.method.read, request.context.signal, request.context.timeoutMs(), NodeCoordinatorValues.applicationHeaders(request.context.requestHeader), request.query);
+            const response = await transport.unary(QueryService.method.execute, request.signal, request.context.timeoutMs(), headers, request.query);
             NodeCoordinatorValues.responseMetadata(response.header, response.trailer, request.context);
             request.response = response.message;
         }
         return new Uint8Array();
     },
+    /**
+     * Invokes the Command branch and retains its native response metadata.
+     *
+     * @param transport The selected native child transport.
+     * @param request The admitted Command and response slot.
+     * @param headers Operation-bound verified-reader metadata.
+     * @returns Completion after assigning the native response.
+     */
+    async forwardCommand(transport, request, headers) {
+        const response = await transport.unary(CommandService.method.post, request.signal, request.context.timeoutMs(), headers, request.command);
+        NodeCoordinatorValues.responseMetadata(response.header, response.trailer, request.context);
+        request.response = response.message;
+    },
+    /**
+     * Encodes verified reader facts into one exact native unary operation.
+     *
+     * @param request The request being processed.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @returns The operation-bound forwarding headers.
+     */
+    async forwardHeaders(request, issuer, maxBytes) {
+        const service = request.kind === "command" ? "spine.client.CommandService" : "spine.client.QueryService";
+        const method = request.kind === "command" ? "Post" : request.kind === "query" ? "Read" : "Execute";
+        const value = request.kind === "command"
+            ? toBinary(CommandService.method.post.input, request.command)
+            : request.kind === "query"
+                ? toBinary(QuerySchema, request.query)
+                : toBinary(AppQuerySchema, request.query);
+        const headers = NodeCoordinatorValues.applicationHeaders(request.context.requestHeader);
+        if (issuer === undefined &&
+            (request.reader.principal !== undefined || request.reader.authorityFacts !== undefined))
+            throw new ConnectError("Managed reader forwarding is unavailable.", Code.Internal);
+        if (issuer !== undefined)
+            for (const [name, entry] of Object.entries(await ReaderForwarding.seal(service, method, value, request.reader, issuer, maxBytes)))
+                headers.set(name, entry);
+        return headers;
+    },
     /**
      * Streams validated updates from one native child subscription.
      *
@@ -579,25 +1177,61 @@ const NodeCoordinatorValues = Object.freeze({
      * @param updates The logical update sink.
      * @param signal Cancels child activation.
      * @returns Completion after the child stream closes.
+     * @param reader The verified reader facts for this operation.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
      */
-    async activateChild(transport, member, members, child, updates, signal) {
+    async activateChild(transport, member, members, child, updates, signal, reader, issuer, maxBytes = defaultMessageMaxBytes) {
         const subscription = fromBinary(SubscriptionSchema, child);
+        const headers = await NodeCoordinatorValues.readerHeaders("Activate", child, reader, issuer, maxBytes);
+        if (signal.aborted)
+            throw new ConnectError("Reader operation cancelled.", Code.Canceled);
         members?.onChildSubscriptionActivated?.(member, subscription);
         for await (const update of createClient(SubscriptionService, transport).activate(subscription, {
             signal,
+            ...(headers === undefined ? {} : { headers }),
         })) {
-            const topic = subscription.topic;
-            const updateTopic = update.subscription?.topic;
-            if (update.subscription?.id?.value !== subscription.id?.value ||
-                topic === undefined ||
-                updateTopic === undefined ||
-                !equals(TopicSchema, updateTopic, topic))
-                throw new Error("Backend child update does not match its subscription.");
+            NodeCoordinatorValues.checkChildUpdate(subscription, update);
             await updates(toBinary(SubscriptionUpdateSchema, update));
         }
     },
     /**
-     * Copies backend response metadata into the public context.
+     * Rejects a native update for a different child ID or Topic.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param update Native subscription update.
+     */
+    checkChildUpdate(subscription, update) {
+        const topic = subscription.topic;
+        const updateTopic = update.subscription?.topic;
+        if (update.subscription?.id?.value !== subscription.id?.value ||
+            topic === undefined ||
+            updateTopic === undefined ||
+            !equals(TopicSchema, updateTopic, topic))
+            throw new Error("Backend child update does not match its subscription.");
+    },
+    /**
+     * Encodes one verified reader against the exact child subscription RPC.
+     *
+     * @param method The canonical RPC method name.
+     * @param value Canonical child subscription RPC bytes.
+     * @param reader The verified reader facts for this operation.
+     * @param issuer The configured forwarding proof producer.
+     * @param maxBytes The existing native message-size bound.
+     * @returns The canonical reader assertion headers.
+     */
+    async readerHeaders(method, value, reader, issuer, maxBytes) {
+        if (reader === undefined)
+            return undefined;
+        if (issuer === undefined) {
+            if (reader.principal !== undefined || reader.authorityFacts !== undefined)
+                throw new ConnectError("Managed reader forwarding is unavailable.", Code.Internal);
+            return undefined;
+        }
+        return new Headers(await ReaderForwarding.seal("spine.client.SubscriptionService", method, value, reader, issuer, maxBytes));
+    },
+    /**
+     * Snapshots backend response metadata into the public context.
      *
      * @param headers Headers received from the backend.
      * @param trailers Trailers received from the backend.
@@ -610,7 +1244,7 @@ const NodeCoordinatorValues = Object.freeze({
             context.responseTrailer.append(name, value);
     },
     /**
-     * Copies application headers for forwarding.
+     * Snapshots application headers for forwarding.
      *
      * @param headers Headers received from the backend.
      * @returns Forwardable application headers.
@@ -622,7 +1256,9 @@ const NodeCoordinatorValues = Object.freeze({
                 name === "te" ||
                 name === "user-agent" ||
                 name.startsWith("grpc-") ||
-                name.startsWith("connect-"))
+                name.startsWith("connect-") ||
+                name === "spine-internal-reader" ||
+                name === "spine-internal-reader-proof")
                 forwarded.delete(name);
         }
         return forwarded;