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

package/dist/services/spine-services.js

@@ -11,16 +11,18 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
+var _a;
 import { randomUUID } from "node:crypto";
 import { Code, ConnectError } from "@connectrpc/connect";
-import { clone, create, ScalarType } from "@bufbuild/protobuf";
+import { clone, create, equals, toBinary, ScalarType, } from "@bufbuild/protobuf";
+import { ReaderIdentities, snapshotTrustedReader, } from "@spine-event-engine/core/spi/trusted-reader";
 import { AnySchema, BoolValueSchema, BytesValueSchema, DoubleValueSchema, EmptySchema, FloatValueSchema, Int32ValueSchema, Int64ValueSchema, StringValueSchema, UInt32ValueSchema, UInt64ValueSchema, } from "@bufbuild/protobuf/wkt";
-import { TypeUrls, AnyPacker } from "@spine-event-engine/core";
-import { CommandIdSchema, TenantIdSchema, ValidationErrorSchema, VersionSchema, } from "@spine-event-engine/proto";
+import { TypeUrls, AnyPacker, Validate } from "@spine-event-engine/core";
+import { CommandIdSchema, CommandValidationError as CommandValidationErrorCode, TenantIdSchema, ValidationErrorSchema, VersionSchema, } from "@spine-event-engine/proto";
 import { ErrorSchema } from "@spine-event-engine/proto";
 import { CommandService } from "@spine-event-engine/proto/client";
 import { CompositeFilter_CompositeOperator, Filter_Operator, } from "@spine-event-engine/proto/client";
-import { EntityStateWithVersionSchema as EntityStateVersionSchema, OrderBy_Direction, QueryResponseSchema, } from "@spine-event-engine/proto/client";
+import { EntityStateWithVersionSchema as EntityStateVersionSchema, OrderBy_Direction, QueryResponseSchema, QuerySchema, } from "@spine-event-engine/proto/client";
 import { QueryService } from "@spine-event-engine/proto/client";
 import { SubscriptionIdSchema, SubscriptionSchema, SubscriptionUpdateSchema, TopicSchema, } from "@spine-event-engine/proto/client";
 import { SubscriptionService } from "@spine-event-engine/proto/client";
@@ -36,12 +38,20 @@ import { CommandValidationError } from "../bus/command-errors.js";
 import { TransitionValidationError } from "../repository/command-errors.js";
 import {} from "../stand/stand.js";
 import { QueryReader } from "./query-reader.js";
+import { AppQueryExecution } from "./app-query-execution.js";
+import { ReadRequestStatus } from "./read-request-status.js";
+import { TrustedReaderIngress } from "./trusted-reader-ingress.js";
 import { RegisteredTargets } from "./registered-targets.js";
 import { emitServerError, emitServerWarning } from "../server/server-log.js";
+import { ServerEnvironment } from "../server/server-environment.js";
 import { managedChildSubscriptionAccess } from "../server/managed-child-subscription.js";
 import {} from "../stand/subscription-registry.js";
+import { ReadSideFilterEngine } from "../stand/read-side-filter-engine.js";
+import { SubscriptionReadFilters, } from "../stand/subscription-read-filters.js";
 const serviceLoggers = new WeakMap();
 const serviceInstances = new WeakSet();
+const serviceAppQueries = new WeakMap();
+const serviceReadFilters = new WeakMap();
 /**
  * Small route registrar for the first public Spine gRPC service slice.
  *
@@ -58,7 +68,8 @@ const serviceInstances = new WeakSet();
  * Queries allow at most 100 IDs, 16 simple filters, 8 composites, and 8 orderings.
  * Use proto column names such as `open_task_count`, not generated TS local names
  * such as `openTaskCount`. Invalid columns, values, operators, and query shapes
- * return stable `INVALID_QUERY` responses before Stand storage is read.
+ * reject with structured `INVALID_ARGUMENT` and `INVALID_QUERY` details before
+ * Stand storage is read.
  *
  * `SubscriptionService.Subscribe` accepts known state targets with
  * `include_all` or validated ID/field filters and known event targets exposed
@@ -74,7 +85,9 @@ const serviceInstances = new WeakSet();
  * rejected-command payload forms and stack trace from their client-facing
  * context.
  * Application code remains on generated domain event messages through handler
- * dispatch. Unknown or duplicate activation IDs complete without updates.
+ * dispatch. Unknown or expired activation IDs fail with `NOT_FOUND` and
+ * `UNKNOWN_SUBSCRIPTION` details. A duplicate active activation completes
+ * without another update stream.
  * Cancellation of unknown or already-cleaned IDs returns OK after admission to
  * the bounded unknown-removal pool.
  */
@@ -87,8 +100,10 @@ export class SpineServices {
     #activationTails = new Map();
     #removals = new Map();
     #unknownRemovals = new Set();
-    #queueLimit;
+    #queueCapacity;
     #subscriptionLimit;
+    #readerAdmission;
+    #readMaxBytes;
     /**
      * Creates service adapters over built bounded contexts.
      *
@@ -97,8 +112,10 @@ export class SpineServices {
     constructor(options) {
         serviceInstances.add(this);
         this.#contexts = Object.freeze([...options.contexts]);
-        this.#queueLimit = ServiceValues.positiveInteger(options.queueLimit ?? ServiceValues.defaultQueueLimit);
+        this.#queueCapacity = ServerEnvironment.instance().subscriptionQueueCapacity;
         this.#subscriptionLimit = ServiceValues.subscriptionLimit(options.subscriptionLimit ?? ServiceValues.defaultSubscriptionLimit);
+        this.#readerAdmission = options.readerAdmission;
+        this.#readMaxBytes = options.readMaxBytes ?? 4_194_304;
         this.#registerSignalRoutes();
         this.#registerStateRoutes(new RegisteredTargets(this.#contexts));
     }
@@ -151,18 +168,119 @@ export class SpineServices {
      * @returns Returns the registered router.
      */
     register(router) {
+        this.#registerUnary(router);
+        this.#registerSubscriptions(router);
+        return router;
+    }
+    /**
+     * Registers admitted Command and Query routes.
+     *
+     * @param router Connect service router.
+     */
+    #registerUnary(router) {
         router.service(CommandService, {
-            post: (command) => this.#post(command),
+            post: async (command, context) => {
+                await this.#admit("spine.client.CommandService", "Post", toBinary(CommandService.method.post.input, command), context);
+                return this.#post(command);
+            },
         });
         router.service(QueryService, {
-            read: (query) => this.#read(query),
+            read: async (query, context) => {
+                const detached = clone(QuerySchema, query);
+                const reader = await this.#admit("spine.client.QueryService", "Read", toBinary(QuerySchema, detached), context);
+                return this.#read(detached, reader, context?.signal);
+            },
+            execute: async (query, context) => {
+                const detached = clone(QueryService.method.execute.input, query);
+                const reader = await this.#admit("spine.client.QueryService", "Execute", toBinary(QueryService.method.execute.input, detached), context);
+                return this.#executeAppQuery(detached, reader, context.signal);
+            },
         });
+    }
+    /**
+     * Executes a detached App Query with facts established by a trusted admission port.
+     *
+     * @param query Captured application query envelope.
+     * @param reader Verified current invocation facts.
+     * @param signal Current invocation cancellation, when available.
+     * @returns One paired response from the Server-selected handler.
+     */
+    #executeAppQuery(query, reader, signal) {
+        const queries = serviceAppQueries.get(this);
+        if (queries === undefined)
+            return Promise.reject(new ConnectError("App Query execution is unavailable.", Code.Unimplemented));
+        return queries.execute(query, reader, signal);
+    }
+    /**
+     * Registers reader-bound subscription routes.
+     *
+     * @param router Connect service router.
+     */
+    #registerSubscriptions(router) {
         router.service(SubscriptionService, {
-            subscribe: (topic) => this.#subscribe(topic),
-            activate: (subscription) => this.#activate(subscription),
-            cancel: (subscription) => this.#cancel(subscription),
+            subscribe: (topic, context) => this.#subscribeAdmitted(topic, context),
+            activate: (subscription, context) => this.#activateAdmitted(subscription, context),
+            cancel: (subscription, context) => this.#cancelAdmitted(subscription, context),
         });
-        return router;
+    }
+    /**
+     * Keeps direct in-process Subscribe validation synchronous while admitting native peers.
+     *
+     * @param topic Requested subscription topic.
+     * @param context Native transport context, absent for direct in-process calls.
+     * @returns Subscription or admitted native operation promise.
+     */
+    #subscribeAdmitted(topic, context) {
+        if (context === undefined)
+            return this.#subscribe(topic, { kind: "anonymous" });
+        return this.#admit("spine.client.SubscriptionService", "Subscribe", toBinary(TopicSchema, topic), context).then((reader) => this.#subscribe(topic, ReaderIdentities.from(reader)));
+    }
+    /**
+     * Keeps direct in-process Cancel synchronous while admitting native peers.
+     *
+     * @param subscription Requested subscription definition.
+     * @param context Native transport context, absent for direct in-process calls.
+     * @returns Cancel acknowledgment or admitted native operation promise.
+     */
+    #cancelAdmitted(subscription, context) {
+        if (context === undefined)
+            return this.#cancel(subscription, { kind: "anonymous" });
+        return this.#admit("spine.client.SubscriptionService", "Cancel", toBinary(SubscriptionSchema, subscription), context).then((reader) => this.#cancel(subscription, ReaderIdentities.from(reader)));
+    }
+    /**
+     * Verifies one native reader assertion before service side effects.
+     *
+     * @param service Canonical RPC service.
+     * @param method Canonical RPC method.
+     * @param bytes Canonical request bytes.
+     * @param context Native transport context when called through Connect.
+     * @returns Detached trusted reader facts.
+     */
+    async #admit(service, method, bytes, context) {
+        if (context === undefined)
+            return Object.freeze({});
+        return TrustedReaderIngress.admit({
+            service,
+            method,
+            request: bytes,
+            headers: context.requestHeader,
+            peer: context,
+            maxBytes: this.#readMaxBytes,
+            ...this.#readerAdmission,
+        });
+    }
+    /**
+     * Verifies activation before entering the subscription lifecycle generator.
+     *
+     * @param subscription Native activation request.
+     * @param context Native transport context.
+     * @returns Admitted subscription update stream.
+     */
+    async *#activateAdmitted(subscription, context) {
+        const captured = clone(SubscriptionSchema, subscription);
+        const signal = context?.signal;
+        const reader = await this.#admit("spine.client.SubscriptionService", "Activate", toBinary(SubscriptionSchema, captured), context);
+        yield* this.#activate(captured, snapshotTrustedReader(reader), signal);
     }
     /**
      * Resolves a public Command route before attempting dispatch.
@@ -172,13 +290,28 @@ export class SpineServices {
      */
     async #post(command) {
         const messageId = command.id && AnyPacker.pack(CommandIdSchema, command.id);
-        const typeUrl = command.message?.typeUrl;
-        if (typeUrl === undefined || typeUrl.length === 0)
-            return ServiceValues.commandErrorAck(messageId, "INVALID_COMMAND", "Command message type is required.");
+        try {
+            CommandValidationError.checkEnvelope(command);
+        }
+        catch (error) {
+            const failure = ServiceValues.commandPostError(error);
+            return ServiceValues.commandErrorAck(messageId, failure.type, failure.message, failure.code, failure.details);
+        }
+        const typeUrl = command.message.typeUrl;
         const admission = this.#commandAdmission(command, messageId, typeUrl);
         if ("ack" in admission)
             return admission.ack;
-        const { route } = admission;
+        return this.#dispatchCommand(admission.route, command, messageId);
+    }
+    /**
+     * Dispatches an admitted Command and maps its completed or failed outcome.
+     *
+     * @param route Selected Command route.
+     * @param command Validated Command envelope.
+     * @param messageId Packed ID for the acknowledgement.
+     * @returns The completed Command acknowledgement.
+     */
+    async #dispatchCommand(route, command, messageId) {
         try {
             await route.context.commandBus().post(command);
             return create(AckSchema, {
@@ -193,7 +326,7 @@ export class SpineServices {
             this.#logCommandPostFailure(route, command, error);
             return create(AckSchema, {
                 messageId,
-                status: ServiceValues.errorStatus(postError.type, postError.message, postError.details),
+                status: ServiceValues.errorStatus(postError.type, postError.message, postError.details, postError.code),
             });
         }
     }
@@ -209,7 +342,7 @@ export class SpineServices {
         const route = this.#commandRoutes.get(typeUrl);
         if (route === undefined) {
             return {
-                ack: ServiceValues.commandErrorAck(messageId, "UNSUPPORTED_COMMAND", "No bounded context accepted the command."),
+                ack: ServiceValues.commandErrorAck(messageId, "spine.core.CommandValidationError", "No bounded context accepted the command.", CommandValidationErrorCode.UNSUPPORTED_COMMAND),
             };
         }
         const tenantError = ServiceValues.tenantMismatch(route.context.isMultitenant, ServiceValues.commandTenant(command), "command");
@@ -246,19 +379,23 @@ export class SpineServices {
      * Validates a public state query before reading its registered Stand.
      *
      * @param query Public query request.
-     * @returns States or a stable query error response.
+     * @param reader Verified facts from current admission.
+     * @param signal Current request cancellation.
+     * @returns States for an admitted Query.
+     * @throws ConnectError for invalid input or a sanitized read failure.
      */
-    async #read(query) {
+    async #read(query, reader, signal) {
+        ReadRequestStatus.check("query", () => Validate.check(QuerySchema, query));
         const target = query.target;
         const route = this.#readRoute(target);
         if (target === undefined || route === undefined) {
-            return ServiceValues.queryErrorResponse("UNSUPPORTED_QUERY_TARGET", "No bounded context owns query target.");
+            throw ReadRequestStatus.invalid("query", true, "No bounded context owns query target.");
         }
         const queryError = ServiceValues.validateReadQuery(query, target, route);
         if (queryError !== undefined) {
-            return ServiceValues.queryErrorResponse(queryError.type, queryError.message);
+            throw ReadRequestStatus.invalid("query", false, queryError.message);
         }
-        return this.#readValidated(query, target, route);
+        return this.#readValidated(query, target, route, reader, signal);
     }
     /**
      * Resolves the effective tenant and executes an already validated read.
@@ -266,49 +403,96 @@ export class SpineServices {
      * @param query Validated public query.
      * @param target Registered query target.
      * @param route Route containing the target Stand and schema.
-     * @returns States or a stable tenant/read error response.
+     * @param reader Verified current invocation facts.
+     * @param signal Current request cancellation.
+     * @returns States when tenant admission and storage read succeed.
      */
-    async #readValidated(query, target, route) {
+    async #readValidated(query, target, route, reader, signal) {
         const tenantId = ServiceValues.tenantValue(query.context?.tenantId);
         const tenantError = ServiceValues.tenantMismatch(route.context.isMultitenant, tenantId, "query");
         if (tenantError !== undefined) {
-            return ServiceValues.queryErrorResponse(tenantError.type, tenantError.message);
+            throw ReadRequestStatus.tenant(tenantError.type, tenantError.message);
         }
         try {
             const effective = EffectiveTenants.current(route.context.isMultitenant, tenantId);
             const destination = EffectiveTenants.destination(effective, route.context.isMultitenant);
-            return await this.#query(route, ServiceValues.createReadPlan(target, query, route), destination);
+            return await this.#query(route, ServiceValues.createReadPlan(target, query, route), destination, query, reader, signal);
         }
         catch (error) {
             if (error instanceof TenantUnknownError)
                 throw TenantStatuses.unknown(error);
-            return ServiceValues.queryErrorResponse("QUERY_READ_ERROR", "Query read failed.");
+            throw ReadRequestStatus.technical(error, "Query read failed.");
         }
     }
-    #readRoute(target) {
+    /**
+     * Finds the registered Entity state route for a query target.
+     *
+     * @param target Declared query or Topic target.
+     * @returns The matching read route, if present.
+     */ #readRoute(target) {
         return target === undefined ? undefined : this.#stateRoutes.get(target.type);
     }
-    async #query(route, plan, tenantId) {
-        const results = await QueryReader.read(route.context.stand(), route.schema, plan, tenantId, ServiceValues.queryResultLimit);
+    /**
+     * Executes a validated Entity state read through its registered route.
+     *
+     * @param route Registered target route with schema and tenancy.
+     * @param plan Validated Entity read plan.
+     * @param tenantId Declared Proto tenant identifier.
+     * @param query Validated public query with effective actor data.
+     * @param reader Verified current invocation facts.
+     * @param signal Current request cancellation.
+     * @returns The Entity query response.
+     */ async #query(route, plan, tenantId, query, reader, signal) {
+        const facts = {
+            operation: { kind: "query", query },
+            ...(query.context === undefined ? {} : { actorContext: query.context }),
+            ...(tenantId === undefined ? {} : { effectiveTenant: tenantId }),
+            producingContext: route.context,
+            ...reader,
+            ...(signal === undefined ? {} : { signal }),
+        };
+        const results = await QueryReader.read(route.context.stand(), route.schema, plan, tenantId, ServiceValues.queryResultLimit, query, facts);
+        const visible = await this.#visibleStates(route, results, facts);
         return create(QueryResponseSchema, {
             response: ServiceValues.okResponse(),
-            message: results.map((result) => ServiceValues.packVersionedState(route.schema, result)),
+            message: visible.map((result) => ServiceValues.packVersionedState(route.schema, result)),
         });
     }
+    /**
+     * Applies this Server's outward policy after BC source policy and storage work.
+     *
+     * @param route Registered Entity result schema.
+     * @param results States returned by the producing context.
+     * @param facts Verified current Query facts.
+     * @returns Surviving states without replenishing removed records.
+     */
+    async #visibleStates(route, results, facts) {
+        const filters = serviceReadFilters.get(this);
+        if (filters === undefined)
+            return results;
+        const visible = [];
+        for (const result of results) {
+            const state = await filters.apply(route.schema, result.state, facts);
+            if (state !== null)
+                visible.push({ ...result, state });
+        }
+        return visible;
+    }
     /**
      * Validates a topic synchronously and checks live membership before registry creation.
      *
      * @param topic Requested subscription topic.
      * @returns Created subscription after admission.
+     * @param reader The verified reader facts for this operation.
      */
-    #subscribe(topic) {
+    #subscribe(topic, reader) {
+        ReadRequestStatus.check("topic", () => Validate.check(TopicSchema, topic));
         const route = this.#subscriptionRoute(topic);
-        ServiceValues.validateTopic(topic);
-        ServiceValues.createSubscriptionShape(topic, route);
+        ServiceValues.checkTopicSemantics(topic, route);
         const tenantId = ServiceValues.topicTenant(topic);
         const tenantError = ServiceValues.tenantMismatch(route.context.isMultitenant, tenantId, "subscription");
         if (tenantError !== undefined) {
-            throw new ConnectError(tenantError.message, Code.InvalidArgument);
+            throw ReadRequestStatus.tenant(tenantError.type, tenantError.message);
         }
         const subscription = create(SubscriptionSchema, {
             id: create(SubscriptionIdSchema, { value: `s-${randomUUID()}` }),
@@ -320,46 +504,115 @@ export class SpineServices {
         }
         const registry = boundedContextAccess.subscriptionRegistry(route.context);
         return TenantStatuses.require(route.context, tenantId, async () => {
-            await registry.create(subscription);
+            await registry.create(subscription, reader);
         }).then(() => clone(SubscriptionSchema, subscription));
     }
-    async *#activate(subscription) {
+    /**
+     * Verifies membership and activates a retained subscription.
+     *
+     * @param subscription The subscription definition being processed.
+     * @param reader The verified reader facts for this operation.
+     * @returns The update stream after admission.
+     */ async *#activate(subscription, reader, signal) {
+        ReadRequestStatus.check("subscription", () => Validate.check(SubscriptionSchema, subscription));
+        ReadRequestStatus.checkLifecycleCriterion(subscription);
         const id = subscription.id?.value;
         if (id === undefined) {
             return;
         }
-        const record = await this.#activationRecord(id);
+        const record = await this.#activationRecord(id, ReaderIdentities.from(reader), signal);
         if (record === undefined)
             return;
+        yield* this.#streamSubscription(record, reader);
+    }
+    /**
+     * Delivers one activation in source order while honoring its cancellation.
+     *
+     * @param record Attached subscription and existing admission queue.
+     * @param reader Verified facts of this activation.
+     * @returns ACK followed by surviving filtered data updates.
+     */
+    async *#streamSubscription(record, reader) {
         try {
+            const facts = _a.#subscriptionFacts(record, reader);
+            if (record.delivery.closed)
+                return;
             yield create(SubscriptionUpdateSchema, {
                 subscription: clone(SubscriptionSchema, record.subscription),
                 response: ServiceValues.okResponse(),
             });
             for (;;) {
-                const update = await record.delivery.next();
-                if (update === undefined) {
+                const work = await record.delivery.next();
+                if (work === undefined)
                     return;
+                const update = await record.delivery.settle(this.#filteredSubscription(work, facts));
+                if (update === undefined)
+                    return;
+                if (update !== null) {
+                    if (record.delivery.signal.aborted)
+                        return;
+                    yield update;
                 }
-                yield update;
+                record.delivery.advance();
             }
         }
+        catch (error) {
+            record.delivery.close();
+            throw ReadRequestStatus.technical(error, "Subscription filtering failed.");
+        }
         finally {
-            if (!record.delivery.closed) {
-                await this.#removeSubscription(id);
+            if (this.#subscriptions.get(record.id) === record) {
+                if (record.delivery.closed)
+                    this.#removeDetachedSubscription(record.id);
+                else
+                    await this.#removeSubscription(record.id);
             }
         }
     }
+    /**
+     * Captures the original Topic and authenticated activation facts for policy code.
+     *
+     * @param record Current source route and canonical subscription.
+     * @param reader Verified facts of this activation.
+     * @returns Subscription operation context with a live cancellation signal.
+     */
+    static #subscriptionFacts(record, reader) {
+        const topic = record.subscription.topic;
+        if (topic === undefined)
+            throw new TypeError("Activated subscription Topic is missing.");
+        return {
+            operation: { kind: "subscription", subscription: record.subscription, topic },
+            ...(topic.context === undefined ? {} : { actorContext: topic.context }),
+            ...(record.tenantId === undefined ? {} : { effectiveTenant: record.tenantId }),
+            producingContext: record.route.context,
+            ...reader,
+            signal: record.delivery.signal,
+        };
+    }
+    /**
+     * Applies the producing BC policy before this Server's final policy.
+     *
+     * @param work Queued matched update and lazy BC capability.
+     * @param facts Trusted activation and original Topic facts.
+     * @returns Surviving update or null for an empty domain-data batch.
+     */
+    async #filteredSubscription(work, facts) {
+        const source = await work.filter(facts);
+        return source === null
+            ? null
+            : SubscriptionReadFilters.apply(source, serviceReadFilters.get(this), facts);
+    }
     /**
      * Serializes one native activation and returns its attached record.
      *
      * @param id The logical subscription identifier.
      * @returns The attached record, or undefined when admission fails.
+     * @param reader The verified reader facts for this operation.
      */
-    async #activationRecord(id) {
+    async #activationRecord(id, reader, signal) {
         let attached;
         await this.#serializeActivation(id, async () => {
-            attached = await this.#startActivationRecord(id);
+            attached = await this.#startActivationRecord(id, reader, signal);
         });
         return attached;
     }
@@ -368,14 +621,17 @@ export class SpineServices {
      *
      * @param id The logical subscription identifier.
      * @returns The attached record, or undefined when unavailable.
+     * @param reader The verified reader facts for this operation.
      */
-    async #startActivationRecord(id) {
+    async #startActivationRecord(id, reader, signal) {
         const record = this.#subscriptions.get(id) ?? (await this.#findSubscription(id));
         if (record === undefined)
-            return undefined;
+            throw ReadRequestStatus.unknownSubscription();
+        if (!ReaderIdentities.matches(record.reader, reader))
+            throw this.#readerDenied();
         let attached;
         await this.#requireSubscriptionTenant(record, async () => {
-            attached = await this.#activateKnownRecord(record, id);
+            attached = await this.#activateKnownRecord(record, id, reader, signal);
         });
         return attached;
     }
@@ -385,21 +641,32 @@ export class SpineServices {
      * @param record Discovered subscription record.
      * @param id Canonical subscription ID.
      * @returns Attached record, if activation remains eligible.
+     * @param reader The verified reader facts for this operation.
      */
-    async #activateKnownRecord(record, id) {
+    async #activateKnownRecord(record, id, reader, signal) {
         if (record.delivery.active)
             return undefined;
         const activation = await boundedContextAccess
             .subscriptionRegistry(record.route.context)
-            .activate(create(SubscriptionIdSchema, { value: id }));
-        if (activation.kind === "missing" || activation.kind === "expired" || record.delivery.closed)
+            .activate(create(SubscriptionIdSchema, { value: id }), reader);
+        if (activation.kind === "denied")
+            throw this.#readerDenied();
+        if (!("entry" in activation))
+            throw ReadRequestStatus.unknownSubscription();
+        if (!equals(SubscriptionSchema, record.subscription, activation.entry.subscription))
+            throw ReadRequestStatus.unknownSubscription();
+        if (record.delivery.closed)
             return undefined;
         try {
             this.#subscriptions.set(id, record);
-            await this.#activateRecord(record);
+            record.delivery.track(signal);
+            await this.#activateRecord(record, activation.entry);
+            await this.#checkAttachedRecord(record, id, reader, signal);
             return record;
         }
         catch (error) {
+            if (record.delivery.invalidated)
+                throw error;
             try {
                 await this.#removeSubscription(id);
             }
@@ -409,7 +676,30 @@ export class SpineServices {
             throw error;
         }
     }
-    async #serializeActivation(id, work) {
+    /**
+     * Rejects an entry removed or replaced before its first activation ACK.
+     * @param record Attached delivery that may have been invalidated.
+     * @param id Canonical subscription ID.
+     * @param reader Reader admitted by the earlier activation.
+     * @param signal Transport cancellation, which ends the stream normally.
+     */
+    async #checkAttachedRecord(record, id, reader, signal) {
+        if (!record.delivery.invalidated || signal?.aborted === true)
+            return;
+        const current = await boundedContextAccess
+            .subscriptionRegistry(record.route.context)
+            .get(create(SubscriptionIdSchema, { value: id }));
+        if (current !== undefined && !ReaderIdentities.matches(current.reader, reader))
+            throw this.#readerDenied();
+        throw ReadRequestStatus.unknownSubscription();
+    }
+    /**
+     * Serializes activation callbacks for the same subscription ID.
+     *
+     * @param id The stable identifier for this record.
+     * @param work Accepted lifecycle operation.
+     * @returns Completion after the operation settles.
+     */ async #serializeActivation(id, work) {
         const previous = this.#activationTails.get(id) ?? Promise.resolve();
         let finish = () => undefined;
         const settled = new Promise((resolve) => {
@@ -432,79 +722,131 @@ export class SpineServices {
      *
      * @param subscription Subscription identity supplied by the caller.
      * @returns Cancellation response after any required membership check.
+     * @param reader The verified reader facts for this operation.
      */
-    #cancel(subscription) {
+    #cancel(subscription, reader) {
+        ReadRequestStatus.check("subscription", () => Validate.check(SubscriptionSchema, subscription));
+        ReadRequestStatus.checkLifecycleCriterion(subscription);
         const id = subscription.id?.value;
         if (id === undefined) {
             return ServiceValues.okResponse();
         }
-        return this.#cancelKnown(id);
+        return this.#cancelKnown(id, reader);
     }
     /**
      * Checks the canonical record's tenant before cancellation side effects.
      *
      * @param id Subscription ID with a possible shared-registry record.
      * @returns Successful cancellation response after removal.
+     * @param reader The verified reader facts for this operation.
      */
-    async #cancelKnown(id) {
-        const record = this.#subscriptions.get(id) ?? (await this.#findSubscription(id));
+    async #cancelKnown(id, reader) {
+        const live = this.#subscriptions.get(id);
+        const record = live ?? (await this.#findSubscription(id));
         if (record === undefined)
-            await this.#removeSubscription(id);
-        else
-            await this.#requireSubscriptionTenant(record, () => this.#removeSubscription(id));
+            return ServiceValues.okResponse();
+        if (!ReaderIdentities.matches(record.reader, reader))
+            throw this.#readerDenied();
+        await this.#requireSubscriptionTenant(record, async () => {
+            if (live !== undefined)
+                return this.#removeSubscription(id, reader);
+            await this.#registryOperation(record.route.context, async () => {
+                const outcome = await boundedContextAccess
+                    .subscriptionRegistry(record.route.context)
+                    .delete(create(SubscriptionIdSchema, { value: id }), reader);
+                if (outcome === "denied")
+                    throw this.#readerDenied();
+            });
+        });
         return ServiceValues.okResponse();
     }
+    /**
+     * Returns a sanitized denial for a foreign or legacy-bound subscription.
+     *
+     * @returns The reader authorization error.
+     */
+    #readerDenied() {
+        return new ConnectError("Subscription reader is not authorized.", Code.PermissionDenied);
+    }
     /**
      * Checks the discovered subscription tenant before tenant-specific control work.
      *
      * @param record Canonical shared-registry subscription record.
      * @param onReady Complete admitted one-shot mutation, if present.
+     * @returns Completion after the operation settles.
      */
     async #requireSubscriptionTenant(record, onReady) {
         await TenantStatuses.require(record.route.context, record.tenantId, onReady);
     }
-    #subscriptionRoute(topic) {
+    /**
+     * Finds the registered state or event route for a Topic target.
+     *
+     * @param topic Framework subscription Topic.
+     * @returns The matching subscription route.
+     */ #subscriptionRoute(topic) {
         const target = topic.target;
         const route = target === undefined
             ? undefined
             : (this.#stateRoutes.get(target.type) ?? this.#eventRoutes.get(target.type));
         if (target === undefined || route === undefined) {
-            throw new ConnectError("Unsupported subscription target.", Code.InvalidArgument);
+            throw ReadRequestStatus.invalid("topic", true, "Unsupported subscription target.");
         }
         return route;
     }
-    async #activateRecord(record) {
-        const consumer = await boundedContextAccess.consumeSubscription(record.route.context, record.id, (update) => {
-            record.delivery.push(update);
+    /**
+     * Attaches delivery for the validated retained subscription.
+     *
+     * @param record The durable subscription record.
+     * @returns Completion after the operation settles.
+     * @param expected Exact entry activated for this reader.
+     */ async #activateRecord(record, expected) {
+        const consumer = await boundedContextAccess.consumeSubscription(record.route.context, record.id, (work) => {
+            record.delivery.push(work);
             if (record.delivery.closed)
                 this.#removeDetachedSubscription(record.id);
-        });
+        }, () => {
+            if (this.#subscriptions.get(record.id) === record)
+                this.#subscriptions.delete(record.id);
+            record.delivery.invalidate();
+        }, expected);
         record.delivery.attach(consumer);
         managedChildSubscriptionAccess.installed(record.id);
     }
-    #removeSubscription(id) {
+    /**
+     * Serializes removal of a retained subscription and its delivery.
+     *
+     * @param id The stable identifier for this record.
+     * @param reader The verified reader facts for this operation.
+     * @returns Completion after the operation settles.
+     */ #removeSubscription(id, reader) {
         const existing = this.#removals.get(id);
         if (existing !== undefined) {
             return existing.settled;
         }
         const record = this.#subscriptions.get(id);
         const unknown = record === undefined;
+        if (reader !== undefined && unknown)
+            return Promise.resolve();
         if (unknown && this.#unknownRemovals.size >= this.#subscriptionLimit) {
             return Promise.reject(new ConnectError("Subscription cancellation capacity is exhausted.", Code.ResourceExhausted));
         }
         if (unknown) {
             this.#unknownRemovals.add(id);
         }
-        else {
+        else if (reader === undefined) {
             record.delivery.close();
             this.#subscriptions.delete(id);
         }
         const removal = ServiceValues.createSubscriptionRemoval();
         this.#removals.set(id, removal);
-        void this.#runRemoval(id, removal, record, unknown);
+        void this.#runRemoval(id, removal, record, unknown, reader);
         return removal.settled;
     }
-    #removeDetachedSubscription(id) {
+    /**
+     * Cleans up delivery after a subscription record is detached.
+     *
+     * @param id The stable identifier for this record.
+     */ #removeDetachedSubscription(id) {
         // spine-log-boundary: server.subscription_cleanup_failure
         void this.#removeSubscription(id).catch(() => {
             const logger = serviceLoggers.get(this);
@@ -517,12 +859,27 @@ export class SpineServices {
             }
         });
     }
-    async #runRemoval(id, removal, record, unknown) {
+    /**
+     * Executes serialized subscription cleanup for one ID.
+     *
+     * @param id The stable identifier for this record.
+     * @param removal Shared subscription-removal task.
+     * @param record The durable subscription record.
+     * @param unknown Unrecognized route or filter value.
+     * @param reader The verified reader facts for this operation.
+     * @returns Completion after the operation settles.
+     */ async #runRemoval(id, removal, record, unknown, reader) {
         try {
             if (record !== undefined) {
-                await boundedContextAccess
+                const deleted = await boundedContextAccess
                     .subscriptionRegistry(record.route.context)
-                    .delete(create(SubscriptionIdSchema, { value: id }));
+                    .delete(create(SubscriptionIdSchema, { value: id }), reader);
+                if (deleted === "denied")
+                    throw this.#readerDenied();
+                if (reader !== undefined) {
+                    record.delivery.close();
+                    this.#subscriptions.delete(id);
+                }
             }
             else {
                 await this.#deleteUnknownSubscription(id);
@@ -545,6 +902,7 @@ export class SpineServices {
      * Deletes an unknown subscription from every configured context registry.
      *
      * @param id Subscription ID to remove.
+     * @returns Completion after the operation settles.
      */
     async #deleteUnknownSubscription(id) {
         await Promise.all(ServiceValues.uniqueContexts(this.#contexts).map((context) => this.#registryOperation(context, async () => {
@@ -553,7 +911,12 @@ export class SpineServices {
                 .delete(create(SubscriptionIdSchema, { value: id }));
         })));
     }
-    async #findSubscription(id) {
+    /**
+     * Loads a retained subscription record by opaque ID.
+     *
+     * @param id The stable identifier for this record.
+     * @returns The retained record, if present.
+     */ async #findSubscription(id) {
         const subscriptionId = create(SubscriptionIdSchema, { value: id });
         for (const context of ServiceValues.uniqueContexts(this.#contexts)) {
             let entry;
@@ -577,7 +940,8 @@ export class SpineServices {
                 subscription: clone(SubscriptionSchema, subscription),
                 shape: ServiceValues.createSubscriptionShape(canonicalTopic, route),
                 tenantId,
-                queueLimit: this.#queueLimit,
+                queueCapacity: this.#queueCapacity,
+                ...(entry.reader === undefined ? {} : { reader: entry.reader }),
             });
         }
         return undefined;
@@ -593,12 +957,35 @@ export class SpineServices {
         return boundedContextAccess.admitServiceRegistryOperation(context, onOperation);
     }
 }
+_a = SpineServices;
 /**
  * Provides package-private service configuration seams.
  *
  * @internal
  */
 export const spineServicesAccess = Object.freeze({
+    /**
+     * Attaches Server-only outward read policies to its service adapter.
+     *
+     * @param services Prepared service adapter.
+     * @param filters Registered policy engine.
+     */
+    installReadFilters(services, filters) {
+        if (!serviceInstances.has(services))
+            throw new TypeError("Expected SpineServices instance.");
+        serviceReadFilters.set(services, filters);
+    },
+    /**
+     * Attaches this Server's prepared handler table without exposing registration options.
+     *
+     * @param services Adapter receiving its internal App Query capability.
+     * @param queries Selected handler table from Server preparation.
+     */
+    installAppQueries(services, queries) {
+        if (!serviceInstances.has(services))
+            throw new TypeError("Expected SpineServices instance.");
+        serviceAppQueries.set(services, queries);
+    },
     /**
      * Clears the logger installed for a closed service adapter.
      *
@@ -627,18 +1014,23 @@ export const spineServicesAccess = Object.freeze({
  * Buffers subscription updates and wakes active stream readers.
  */
 class SubscriptionDelivery {
+    #active;
     #queue = [];
     #waiters = [];
-    #queueLimit;
+    #controller = new AbortController();
+    #queueCapacity;
+    #activationSignal;
+    #onActivationAbort;
     #subscription;
     #closed = false;
+    #invalidated = false;
     /**
      * Sets the bounded update queue capacity.
      *
-     * @param queueLimit Maximum pending updates before closure.
+     * @param queueCapacity Maximum waiting updates beyond the active update.
      */
-    constructor(queueLimit) {
-        this.#queueLimit = queueLimit;
+    constructor(queueCapacity) {
+        this.#queueCapacity = queueCapacity;
     }
     /**
      * Checks whether a source attachment is active.
@@ -656,6 +1048,75 @@ class SubscriptionDelivery {
     get closed() {
         return this.#closed;
     }
+    /**
+     * Returns source invalidation separately from transport cancellation before the first ACK.
+     * @returns Whether the admitted canonical entry changed or disappeared.
+     */
+    get invalidated() {
+        return this.#invalidated;
+    }
+    /**
+     * Closes this delivery after the admitted source entry changes.
+     */
+    invalidate() {
+        if (this.#closed)
+            return;
+        this.#invalidated = true;
+        this.close();
+    }
+    /**
+     * Returns a cancellation signal for active policy when this consumer is removed.
+     *
+     * @returns Cancellation signal for the current activation.
+     */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /**
+     * Registers transport cancellation before the source attachment awaits.
+     *
+     * @param signal Cancellation of the admitted activation, when available.
+     */
+    track(signal) {
+        if (signal === undefined)
+            return;
+        if (signal.aborted) {
+            this.close();
+            return;
+        }
+        this.#activationSignal = signal;
+        this.#onActivationAbort = () => {
+            this.close();
+        };
+        signal.addEventListener("abort", this.#onActivationAbort, { once: true });
+    }
+    /**
+     * Stops waiting on one policy call when this activation closes.
+     *
+     * @param work The policy result; a late rejection remains observed by the race.
+     * @returns The result, or undefined after cancellation.
+     */
+    async settle(work) {
+        if (this.#closed) {
+            // spine-log-boundary: server.subscription_closed_policy_rejection
+            void work.catch(() => undefined);
+            return undefined;
+        }
+        let onAbort;
+        const closed = new Promise((resolve) => {
+            onAbort = () => {
+                resolve(undefined);
+            };
+            this.#controller.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            return await Promise.race([work, closed]);
+        }
+        finally {
+            if (onAbort !== undefined)
+                this.#controller.signal.removeEventListener("abort", onAbort);
+        }
+    }
     /**
      * Attaches a source subscription or immediately removes it after close.
      *
@@ -677,17 +1138,16 @@ class SubscriptionDelivery {
         if (this.#closed) {
             return;
         }
-        const waiter = this.#waiters.shift();
-        if (waiter === undefined) {
-            if (this.#queue.length >= this.#queueLimit) {
-                this.close();
-                return;
-            }
-            this.#queue.push(update);
+        if (this.#active === undefined) {
+            this.#active = update;
+            this.#waiters.shift()?.(update);
+            return;
         }
-        else {
-            waiter(update);
+        if (this.#queue.length >= this.#queueCapacity) {
+            this.close();
+            return;
         }
+        this.#queue.push(update);
     }
     /**
      * Reads the next queued update, waiting while the stream is open and empty.
@@ -695,12 +1155,22 @@ class SubscriptionDelivery {
      * @returns Next update, or `undefined` after closure.
      */
     next() {
-        const update = this.#queue.shift();
-        if (update !== undefined || this.#closed) {
-            return Promise.resolve(update);
-        }
+        if (this.#closed)
+            return Promise.resolve(undefined);
+        if (this.#active !== undefined)
+            return Promise.resolve(this.#active);
         return new Promise((resolve) => this.#waiters.push(resolve));
     }
+    /**
+     * Removes the consumed active update and promotes the next waiting update.
+     */
+    advance() {
+        if (this.#closed)
+            return;
+        this.#active = this.#queue.shift();
+        if (this.#active !== undefined)
+            this.#waiters.shift()?.(this.#active);
+    }
     /**
      * Closes the source subscription and completes all waiting readers.
      */
@@ -709,7 +1179,11 @@ class SubscriptionDelivery {
             return;
         }
         this.#closed = true;
+        this.#controller.abort();
+        if (this.#activationSignal !== undefined && this.#onActivationAbort !== undefined)
+            this.#activationSignal.removeEventListener("abort", this.#onActivationAbort);
         this.#queue.length = 0;
+        this.#active = undefined;
         this.#subscription?.unsubscribe();
         this.#subscription = undefined;
         for (const waiter of this.#waiters.splice(0)) {
@@ -719,6 +1193,8 @@ class SubscriptionDelivery {
 }
 /**
  * Builds an OK status for service responses.
+ *
+ * @returns The successful status.
  */
 function okStatus() {
     return create(StatusSchema, {
@@ -728,30 +1204,42 @@ function okStatus() {
         },
     });
 }
-function errorStatus(type, message, details) {
+/**
+ * Builds a structured status from a public validation error.
+ *
+ * @param type Registered target type URL.
+ * @param message Public validation or error message.
+ * @param details Structured validation details.
+ * @param code Public status code.
+ * @returns The structured error status.
+ */ function errorStatus(type, message, details, code) {
     return create(StatusSchema, {
         status: {
             case: "error",
             value: create(ErrorSchema, {
                 type,
                 message,
+                ...(code === undefined ? {} : { code }),
                 ...(details === undefined ? {} : { details }),
             }),
         },
     });
 }
-function okResponse() {
+/**
+ * Builds a successful subscription service response.
+ *
+ * @returns The OK response.
+ */ function okResponse() {
     return create(ResponseSchema, { status: okStatus() });
 }
-function errorResponse(type, message) {
-    return create(ResponseSchema, { status: errorStatus(type, message) });
-}
-function queryErrorResponse(type, message) {
-    return create(QueryResponseSchema, {
-        response: errorResponse(type, message),
-    });
-}
-function validateReadQuery(query, target, route) {
+/**
+ * Checks a read query envelope and target before routing.
+ *
+ * @param query Framework Entity read query.
+ * @param target Declared query or Topic target.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated read request.
+ */ function validateReadQuery(query, target, route) {
     const formatError = formatReadError(query.format, route);
     if (formatError !== undefined) {
         return formatError;
@@ -768,7 +1256,13 @@ function validateReadQuery(query, target, route) {
             return invalidCriterionError();
     }
 }
-function validateFilters(filters, route) {
+/**
+ * Checks target filters against the registered Entity schema.
+ *
+ * @param filters Target or subscription filter collection.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated target filters.
+ */ function validateFilters(filters, route) {
     const idCount = filters.idFilter?.id.length ?? 0;
     if (idCount > QueryLimits.idCount) {
         return invalidQueryError("QueryService.Read id_filter may contain at most 100 IDs.");
@@ -795,7 +1289,13 @@ function validateFilters(filters, route) {
         }
         : undefined;
 }
-function validateCompositeFilters(filters, route) {
+/**
+ * Checks nested composite filters and their traversal bounds.
+ *
+ * @param filters Target or subscription filter collection.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated composite filters.
+ */ function validateCompositeFilters(filters, route) {
     const pending = filters.map((filter) => ({ filter, depth: 0 }));
     const seen = new WeakSet();
     let compositeCount = 0;
@@ -819,7 +1319,13 @@ function validateCompositeFilters(filters, route) {
     }
     return undefined;
 }
-function validateQueryIds(ids, route) {
+/**
+ * Checks query ID Any payloads against the registered Entity ID.
+ *
+ * @param ids Opaque query or subscription IDs.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated query IDs.
+ */ function validateQueryIds(ids, route) {
     const schema = route.idField.message;
     if (schema === undefined || ids === undefined) {
         return undefined;
@@ -830,7 +1336,12 @@ function validateQueryIds(ids, route) {
     }
     return undefined;
 }
-function countSimpleFilters(filters) {
+/**
+ * Counts leaf filters in a nested subscription criterion.
+ *
+ * @param filters Target or subscription filter collection.
+ * @returns The number of simple filter nodes.
+ */ function countSimpleFilters(filters) {
     const pending = [...filters];
     let count = 0;
     while (pending.length > 0) {
@@ -842,7 +1353,13 @@ function countSimpleFilters(filters) {
     }
     return count;
 }
-function validateSimpleFilters(filters, route) {
+/**
+ * Checks field filters and their typed Any values.
+ *
+ * @param filters Target or subscription filter collection.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated simple filters.
+ */ function validateSimpleFilters(filters, route) {
     for (const filter of filters) {
         if (wireComparison(filter.operator) === undefined) {
             return unsupportedFilterError("QueryService.Read comparison operator is not supported.");
@@ -875,6 +1392,10 @@ function validateSimpleFilters(filters, route) {
 }
 /**
  * Checks query ordering and limits against the registered state route.
+ *
+ * @param format Declared filter value format.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The structured read error.
  */
 function formatReadError(format, route) {
     if (format === undefined) {
@@ -899,6 +1420,11 @@ function formatReadError(format, route) {
 }
 /**
  * Converts an accepted wire query into a storage plan for complete states.
+ *
+ * @param target Declared query or Topic target.
+ * @param query Framework Entity read query.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The validated Entity read plan.
  */
 function createReadPlan(target, query, route) {
     const predicate = target.criterion.case === "filters"
@@ -920,7 +1446,13 @@ function createReadPlan(target, query, route) {
         ...(format === undefined || format.limit === 0 ? {} : { limit: format.limit }),
     });
 }
-function normalizedFilters(filters, route) {
+/**
+ * Converts validated target filters to executable predicates.
+ *
+ * @param filters Target or subscription filter collection.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The normalized filter predicates.
+ */ function normalizedFilters(filters, route) {
     const predicates = [];
     if (filters.idFilter !== undefined) {
         predicates.push({
@@ -934,11 +1466,23 @@ function normalizedFilters(filters, route) {
         ? onlyPredicate
         : { kind: "all", predicates };
 }
-function decodeQueryIdValue(value, route) {
+/**
+ * Decodes an opaque query ID using the registered Entity ID schema.
+ *
+ * @param value Packed Entity ID Any from the query.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The typed Entity ID.
+ */ function decodeQueryIdValue(value, route) {
     const schema = route.idField.message;
     return schema === undefined ? decodeAnyValue(value) : decodeAnyValue(value, schema);
 }
-function normalizedComposite(filter, route) {
+/**
+ * Converts a validated composite filter to its execution form.
+ *
+ * @param filter One target or subscription filter.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The normalized composite criterion.
+ */ function normalizedComposite(filter, route) {
     const predicates = [
         ...filter.filter.map((child) => ({
             kind: "comparison",
@@ -953,19 +1497,35 @@ function normalizedComposite(filter, route) {
         predicates,
     };
 }
-function requiredFilterColumn(filter) {
+/**
+ * Resolves a declared state column for a field filter.
+ *
+ * @param filter One target or subscription filter.
+ * @returns The required state column.
+ */ function requiredFilterColumn(filter) {
     const column = filter.fieldPath?.fieldName[0];
     if (column !== undefined)
         return column;
     throw new TypeError("Validated query filter has no column.");
 }
-function requiredComparison(filter) {
+/**
+ * Maps a wire filter operator to a supported comparison.
+ *
+ * @param filter One target or subscription filter.
+ * @returns The required comparison operator.
+ */ function requiredComparison(filter) {
     const operator = wireComparison(filter.operator);
     if (operator !== undefined)
         return operator;
     throw new TypeError("Validated query filter has no supported comparison operator.");
 }
-function decodeColumnValue(filter, route) {
+/**
+ * Decodes a filter value for the target state column.
+ *
+ * @param filter One target or subscription filter.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The typed column value.
+ */ function decodeColumnValue(filter, route) {
     const column = filter.fieldPath?.fieldName[0] ?? "";
     if (column === "version" && filter.value !== undefined) {
         const value = AnyPacker.tryUnpack(filter.value, VersionSchema);
@@ -982,7 +1542,13 @@ function decodeColumnValue(filter, route) {
     const field = route.columnFields.get(column);
     return decodeAnyValue(filter.value, field?.fieldKind === "message" ? field.message : undefined);
 }
-function filterValueMatches(field, value) {
+/**
+ * Checks an Any filter value against the registered field schema.
+ *
+ * @param field Registered Protobuf field descriptor.
+ * @param value Packed field-filter value.
+ * @returns Whether the filter value has the expected type.
+ */ function filterValueMatches(field, value) {
     const schema = filterValueSchema(field);
     if (schema === undefined ||
         (schema.typeName !== AnySchema.typeName && value.typeUrl !== TypeUrls.derive(schema)))
@@ -1010,7 +1576,12 @@ function filterValueMatches(field, value) {
     }
     return typeof decoded === "number" && Number.isFinite(decoded);
 }
-function filterValueSchema(field) {
+/**
+ * Selects the Protobuf schema required for a state field filter.
+ *
+ * @param field Registered Protobuf field descriptor.
+ * @returns The declared filter-value schema.
+ */ function filterValueSchema(field) {
     if (field.fieldKind === "message")
         return field.message;
     if (field.fieldKind === "enum")
@@ -1040,7 +1611,13 @@ function filterValueSchema(field) {
         return StringValueSchema;
     return Int32ValueSchema;
 }
-function systemValueMatches(column, value) {
+/**
+ * Checks special state columns against a wire filter value.
+ *
+ * @param column Registered Entity state column.
+ * @param value Packed value for a system state column.
+ * @returns Whether the special value matches.
+ */ function systemValueMatches(column, value) {
     if (column === "version") {
         return (value.typeUrl === TypeUrls.derive(VersionSchema) &&
             AnyPacker.tryUnpack(value, VersionSchema) !== undefined);
@@ -1051,7 +1628,12 @@ function systemValueMatches(column, value) {
     }
     return false;
 }
-function supportsRange(field) {
+/**
+ * Checks whether a field type supports ordered comparisons.
+ *
+ * @param field Registered Protobuf field descriptor.
+ * @returns Whether range comparisons are supported.
+ */ function supportsRange(field) {
     if (field.fieldKind === "message") {
         return (field.message.typeName === "google.protobuf.Timestamp" ||
             field.message.typeName === "spine.core.Version");
@@ -1060,7 +1642,12 @@ function supportsRange(field) {
         field.scalar !== ScalarType.BOOL &&
         field.scalar !== ScalarType.BYTES);
 }
-function wireComparison(operator) {
+/**
+ * Maps a wire filter enum to the execution comparison.
+ *
+ * @param operator Wire filter comparison enum.
+ * @returns The comparison operator.
+ */ function wireComparison(operator) {
     if (operator === Filter_Operator.EQUAL)
         return "equal";
     if (operator === Filter_Operator.GREATER_THAN)
@@ -1073,25 +1660,43 @@ function wireComparison(operator) {
         return "lessOrEqual";
     return undefined;
 }
-function unsupportedFilterError(message) {
+/**
+ * Creates a structured error for an unsupported filter.
+ *
+ * @param message Public validation or error message.
+ * @returns The invalid-filter error.
+ */ function unsupportedFilterError(message) {
     return invalidQueryError(message);
 }
-function unsupportedFormatError(message) {
+/**
+ * Creates a structured error for an unsupported filter format.
+ *
+ * @param message Public validation or error message.
+ * @returns The invalid-format error.
+ */ function unsupportedFormatError(message) {
     return invalidQueryError(message);
 }
-function invalidQueryError(message) {
+/**
+ * Creates the structured invalid-query error.
+ *
+ * @param message Public validation or error message.
+ * @returns The invalid-query error.
+ */ function invalidQueryError(message) {
     return {
         type: "INVALID_QUERY",
         message,
     };
 }
-function invalidCriterionError() {
+/**
+ * Creates the structured invalid-subscription criterion error.
+ *
+ * @returns The invalid-criterion error.
+ */ function invalidCriterionError() {
     return {
         type: "INVALID_QUERY",
         message: "QueryService.Read requires filters or include_all = true.",
     };
 }
-const DEFAULT_QUEUE_LIMIT = 100;
 const DEFAULT_SUBSCRIPTION_LIMIT = 100;
 /**
  * Holds bounded request limits for QueryService.
@@ -1114,25 +1719,37 @@ const SubscriptionLimits = Object.freeze({
     pathComponentCount: 16,
     pathSegmentLength: 128,
 });
-function positiveInteger(value) {
-    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 1;
-}
-function subscriptionLimit(value) {
+/**
+ * Validates the configured maximum concurrent subscriptions.
+ *
+ * @param value Configured maximum concurrent subscriptions.
+ * @returns The accepted subscription limit.
+ */ function subscriptionLimit(value) {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new TypeError("SpineServices subscriptionLimit must be a positive safe integer.");
     }
     return value;
 }
-function createSubscriptionRecord(input) {
+/**
+ * Constructs an in-memory subscription record with its reader binding.
+ *
+ * @param input Fields for a new reader-bound subscription record.
+ * @returns The new subscription record.
+ */ function createSubscriptionRecord(input) {
     return {
         id: input.id,
         subscription: clone(SubscriptionSchema, input.subscription),
+        ...(input.reader === undefined ? {} : { reader: input.reader }),
         tenantId: input.tenantId === undefined ? undefined : clone(TenantIdSchema, input.tenantId),
-        delivery: new SubscriptionDelivery(input.queueLimit),
+        delivery: new SubscriptionDelivery(input.queueCapacity),
         ...input.shape,
     };
 }
-function createSubscriptionRemoval() {
+/**
+ * Creates a shared removal task for concurrent cancellation.
+ *
+ * @returns The removal task and its completion promise.
+ */ function createSubscriptionRemoval() {
     let reject;
     let resolve;
     const settled = new Promise((settle, fail) => {
@@ -1143,10 +1760,19 @@ function createSubscriptionRemoval() {
     });
     return { reject, resolve, settled };
 }
-function uniqueContexts(contexts) {
+/**
+ * Deduplicates registered bounded contexts for routing.
+ *
+ * @param contexts Built bounded contexts available for routing.
+ * @returns The distinct bounded contexts.
+ */ function uniqueContexts(contexts) {
     return [...new Set(contexts)];
 }
-function validateTopic(topic) {
+/**
+ * Checks Topic identity, context, target and criterion.
+ *
+ * @param topic Framework subscription Topic.
+ */ function validateTopic(topic) {
     if (topic.id?.value === undefined || topic.id.value.trim().length === 0) {
         throw new ConnectError("Subscription topic ID is required.", Code.InvalidArgument);
     }
@@ -1159,6 +1785,10 @@ function validateTopic(topic) {
 }
 /**
  * Validates a topic and returns its state or Event subscription shape.
+ *
+ * @param topic Framework subscription Topic.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The normalized subscription shape.
  */
 function createSubscriptionShape(topic, route) {
     const target = topic.target;
@@ -1184,6 +1814,8 @@ function createSubscriptionShape(topic, route) {
 }
 /**
  * Checks the supported event topic criteria.
+ *
+ * @param target Declared query or Topic target.
  */
 function validateEventSubscriptionTopic(target) {
     switch (target.criterion.case) {
@@ -1199,7 +1831,11 @@ function validateEventSubscriptionTopic(target) {
             throw new ConnectError("SubscriptionService.Subscribe requires filters or include_all = true.", Code.InvalidArgument);
     }
 }
-function validateSubscriptionFilterTree(filters) {
+/**
+ * Checks a Topic filter tree before accepting its definition.
+ *
+ * @param filters Target or subscription filter collection.
+ */ function validateSubscriptionFilterTree(filters) {
     if (filters.length > SubscriptionLimits.compositeCount) {
         throw new ConnectError("SubscriptionService.Subscribe may contain at most 8 composite filters.", Code.InvalidArgument);
     }
@@ -1220,7 +1856,13 @@ function validateSubscriptionFilterTree(filters) {
         enqueueSubscriptionFilterChildren(current.filter, current.depth, stack);
     }
 }
-function validateSubscriptionFilterNode(filter, depth, counts) {
+/**
+ * Checks one nested subscription filter node and its bounds.
+ *
+ * @param filter One target or subscription filter.
+ * @param depth Current composite-filter nesting depth.
+ * @param counts Current filter traversal counts.
+ */ function validateSubscriptionFilterNode(filter, depth, counts) {
     if (depth > SubscriptionLimits.compositeDepth) {
         throw new ConnectError("SubscriptionService.Subscribe composite filters may nest at most 8 levels.", Code.InvalidArgument);
     }
@@ -1247,7 +1889,13 @@ function validateSubscriptionFilterNode(filter, depth, counts) {
         throw new ConnectError("SubscriptionService.Subscribe may contain at most 8 composite filters.", Code.InvalidArgument);
     }
 }
-function enqueueSubscriptionFilterChildren(filter, depth, stack) {
+/**
+ * Queues nested filter children for bounded traversal.
+ *
+ * @param filter One target or subscription filter.
+ * @param depth Current composite-filter nesting depth.
+ * @param stack Pending filter traversal stack.
+ */ function enqueueSubscriptionFilterChildren(filter, depth, stack) {
     for (const nested of filter.compositeFilter) {
         if (depth + 1 > SubscriptionLimits.compositeDepth) {
             throw new ConnectError("SubscriptionService.Subscribe composite filters may nest at most 8 levels.", Code.InvalidArgument);
@@ -1257,6 +1905,9 @@ function enqueueSubscriptionFilterChildren(filter, depth, stack) {
 }
 /**
  * Checks a state filter path before resolving its fields.
+ *
+ * @param fieldPath Declared filter field path.
+ * @param label Diagnostic label for the invalid input.
  */
 function validateSubscriptionPath(fieldPath, label) {
     if (fieldPath.length === 0 || fieldPath.some((field) => field.trim().length === 0)) {
@@ -1269,7 +1920,13 @@ function validateSubscriptionPath(fieldPath, label) {
         throw new ConnectError(`SubscriptionService.Subscribe ${label} path components may contain at most 128 characters.`, Code.InvalidArgument);
     }
 }
-function decodeSubscriptionIdValue(value, route) {
+/**
+ * Decodes a subscription ID filter using the target ID schema.
+ *
+ * @param value Packed subscription ID Any.
+ * @param route Registered target route with schema and tenancy.
+ * @returns The typed subscription filter ID.
+ */ function decodeSubscriptionIdValue(value, route) {
     if (!isAny(value)) {
         throw new ConnectError("SubscriptionService.Subscribe id_filter values must be packed Any messages.", Code.InvalidArgument);
     }
@@ -1284,7 +1941,13 @@ function decodeSubscriptionIdValue(value, route) {
     }
     return decoded;
 }
-function decodeFieldFilterValue(value, schema) {
+/**
+ * Decodes a field-filter Any with its declared value schema.
+ *
+ * @param value Packed field-filter Any, if present.
+ * @param schema Registered Protobuf message schema.
+ * @returns The typed field-filter value.
+ */ function decodeFieldFilterValue(value, schema) {
     if (value === undefined || schema === undefined) {
         return decodeAnyValue(value);
     }
@@ -1294,7 +1957,13 @@ function decodeFieldFilterValue(value, schema) {
     }
     return decoded;
 }
-function decodeAnyValue(value, schema) {
+/**
+ * Decodes a known Any payload against its declared schema.
+ *
+ * @param value Packed Any payload, if present.
+ * @param schema Registered Protobuf message schema.
+ * @returns The decoded payload value.
+ */ function decodeAnyValue(value, schema) {
     if (value === undefined) {
         return undefined;
     }
@@ -1316,6 +1985,11 @@ function decodeAnyValue(value, schema) {
 }
 /**
  * Resolves a state filter path to generated message fields.
+ *
+ * @param schema Registered Protobuf message schema.
+ * @param fieldPath Declared filter field path.
+ * @param label Diagnostic label for the invalid input.
+ * @returns The registered field at the declared path.
  */
 function resolveMessagePath(schema, fieldPath, label) {
     let currentSchema = schema;
@@ -1335,14 +2009,30 @@ function resolveMessagePath(schema, fieldPath, label) {
         ...(leafSchema === undefined ? {} : { leafSchema }),
     });
 }
-function findMessageField(schema, name) {
+/**
+ * Finds a declared field in a registered Protobuf message.
+ *
+ * @param schema Registered Protobuf message schema.
+ * @param name Configured header or field name.
+ * @returns The matching field descriptor, if present.
+ */ function findMessageField(schema, name) {
     const fields = (schema?.fields ?? []);
     return fields.find((field) => field.name === name || field.localName === name);
 }
-function isMessage(value) {
+/**
+ * Recognizes a Protobuf message value.
+ *
+ * @param value Candidate value to inspect as a Protobuf message.
+ * @returns Whether the value is a message.
+ */ function isMessage(value) {
     return typeof value === "object" && value !== null && "$typeName" in value;
 }
-function isAny(value) {
+/**
+ * Recognizes a Protobuf Any message by its declared type name.
+ *
+ * @param value Candidate value to inspect as a Protobuf Any.
+ * @returns Whether the value is an Any message.
+ */ function isAny(value) {
     return isMessage(value) && value.$typeName === "google.protobuf.Any";
 }
 /**
@@ -1359,13 +2049,28 @@ function packVersionedState(schema, result) {
         version: result.version ?? create(VersionSchema),
     });
 }
-function commandTenant(command) {
+/**
+ * Extracts the declared tenant from a command actor context.
+ *
+ * @param command Framework command envelope.
+ * @returns The declared command tenant, if present.
+ */ function commandTenant(command) {
     return tenantValue(command.context?.actorContext?.tenantId);
 }
-function topicTenant(topic) {
+/**
+ * Extracts the declared tenant from a Topic actor context.
+ *
+ * @param topic Framework subscription Topic.
+ * @returns The Topic tenant, if present.
+ */ function topicTenant(topic) {
     return tenantValue(topic?.context?.tenantId);
 }
-function tenantValue(tenantId) {
+/**
+ * Extracts the tenant value from a Proto tenant identifier.
+ *
+ * @param tenantId Declared Proto tenant identifier.
+ * @returns The tenant value, if present.
+ */ function tenantValue(tenantId) {
     if (tenantId === undefined)
         return undefined;
     try {
@@ -1375,7 +2080,13 @@ function tenantValue(tenantId) {
         return undefined;
     }
 }
-function stateRouteIdField(schema, idField) {
+/**
+ * Finds the declared Entity ID field for a registered state route.
+ *
+ * @param schema Registered Protobuf message schema.
+ * @param idField Registered Entity ID field.
+ * @returns The Entity ID field descriptor.
+ */ function stateRouteIdField(schema, idField) {
     const field = findMessageField(schema, idField?.name ?? "") ??
         findMessageField(schema, idField?.localName ?? "") ??
         schema.fields[0] ??
@@ -1420,19 +2131,17 @@ const TenantStatuses = Object.freeze({
      * @returns Connect failure preserving its stable Spine error type.
      */
     unknown(error) {
-        return new ConnectError(error.message, Code.NotFound, undefined, [
-            {
-                desc: ErrorSchema,
-                value: create(ErrorSchema, {
-                    type: error.type,
-                    code: Code.NotFound,
-                    message: error.message,
-                }),
-            },
-        ], error);
+        return ReadRequestStatus.unknownTenant(error);
     },
 });
-function tenantMismatch(multitenant, tenantId, subject) {
+/**
+ * Checks a request tenant against bounded-context tenancy.
+ *
+ * @param multitenant Whether the bounded context requires a tenant.
+ * @param tenantId Declared Proto tenant identifier.
+ * @param subject Verified request subject.
+ * @returns The tenant mismatch status, if any.
+ */ function tenantMismatch(multitenant, tenantId, subject) {
     if (multitenant) {
         return tenantId === undefined
             ? {
@@ -1448,7 +2157,12 @@ function tenantMismatch(multitenant, tenantId, subject) {
             message: `Tenant is not applicable for this ${subject}.`,
         };
 }
-function commandPostError(error) {
+/**
+ * Maps a command-post failure to its public structured status.
+ *
+ * @param error The failure being classified or propagated.
+ * @returns The sanitized command status.
+ */ function commandPostError(error) {
     if (error instanceof TransitionValidationError) {
         return {
             type: error.type,
@@ -1458,7 +2172,8 @@ function commandPostError(error) {
     }
     if (error instanceof CommandValidationError) {
         return {
-            type: "COMMAND_VALIDATION_ERROR",
+            type: "spine.core.CommandValidationError",
+            code: CommandValidationErrorCode.INVALID_COMMAND,
             message: "Command payload validation failed.",
             details: AnyPacker.pack(ValidationErrorSchema, error.validationError),
         };
@@ -1543,6 +2258,24 @@ const VALUE_DECODERS = Object.freeze([
  * Groups non-public service contract, query, and subscription operations.
  */
 const ServiceValues = Object.freeze({
+    /**
+     * Maps supported Topic shape errors to structured public failures.
+     *
+     * @param topic Constraint-valid Topic to inspect.
+     * @param route Registered state or Event route.
+     */
+    checkTopicSemantics(topic, route) {
+        try {
+            ServiceValues.validateTopic(topic);
+            ServiceValues.createSubscriptionShape(topic, route);
+        }
+        catch (error) {
+            if (error instanceof ConnectError && error.code === Code.InvalidArgument) {
+                throw ReadRequestStatus.invalid("topic", false, error.rawMessage);
+            }
+            throw new ConnectError("Topic validation failed.", Code.Internal);
+        }
+    },
     /**
      * Checks one composite query filter and its current traversal bounds.
      *
@@ -1660,26 +2393,25 @@ const ServiceValues = Object.freeze({
      * Builds a stable Command rejection acknowledgement.
      *
      * @param messageId The packed Command ID, if supplied.
-     * @param type The public error code.
+     * @param type The error type.
      * @param message The public error message.
+     * @param code Numeric Proto error code when available.
+     * @param details Packed structured validation details when available.
      * @returns A sanitized Ack.
      */
-    commandErrorAck(messageId, type, message) {
-        return create(AckSchema, { messageId, status: errorStatus(type, message) });
+    commandErrorAck(messageId, type, message, code, details) {
+        return create(AckSchema, { messageId, status: errorStatus(type, message, details, code) });
     },
     commandTenant,
     createReadPlan,
     createSubscriptionRecord,
     createSubscriptionRemoval,
     createSubscriptionShape,
-    defaultQueueLimit: DEFAULT_QUEUE_LIMIT,
     defaultSubscriptionLimit: DEFAULT_SUBSCRIPTION_LIMIT,
     errorStatus,
     okResponse,
     okStatus,
-    positiveInteger,
     packVersionedState,
-    queryErrorResponse,
     queryResultLimit: QueryLimits.resultCount,
     stateRouteIdField,
     subscriptionLimit,