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

package/dist/services/query-reader.d.ts

@@ -2,18 +2,43 @@ import type { MessageSchema } from "@spine-event-engine/core";
 import type { TenantId } from "@spine-event-engine/proto";
 import { type Query } from "@spine-event-engine/proto/client";
 import type { NormalizedQueryPlan } from "@spine-event-engine/storage";
-import type { Stand, StandReadResult } from "../stand/stand.js";
+import { type Stand, type StandReadResult } from "../stand/stand.js";
+import type { ReadSideContext } from "../stand/read-side-filter.js";
+/**
+ * Callback notified when a typed Stand query is read.
+ */
 type QueryReaderObserver = (query: Readonly<Query>) => void;
+/**
+ * Describes typed Stand queries and the testing-only read observer.
+ */
+interface QueryReaderAccess {
+    /**
+     * Reads a typed state through its Stand while retaining the actual query context.
+     * @typeParam Schema Registered state schema.
+     * @param stand Context read facade.
+     * @param schema Requested state schema.
+     * @param plan Normalized storage plan.
+     * @param tenantId Effective tenant.
+     * @param candidateLimit Existing query candidate limit.
+     * @param query Original submitted Query, if present.
+     * @param readSide Trusted invocation context, if present.
+     * @returns Visible state records.
+     */
+    read<Schema extends MessageSchema>(stand: Stand, schema: Schema, plan: NormalizedQueryPlan<unknown>, tenantId: TenantId | undefined, candidateLimit: number, query?: Query, readSide?: ReadSideContext): Promise<readonly StandReadResult<Schema>[]>;
+    /**
+     * Observes original queries for tests without changing read execution.
+     * @param onRead Observer called with a detached Query.
+     * @returns Handle that removes this observer.
+     */
+    observe(onRead: QueryReaderObserver): {
+        readonly close: () => void;
+    };
+}
 /**
  * Executes normalized Entity query plans against a Stand and exposes a testing-only read observer.
  *
  * @internal
  */
-export declare const QueryReader: Readonly<{
-    readonly read: <Schema extends MessageSchema>(stand: Stand, schema: Schema, plan: NormalizedQueryPlan<unknown>, tenantId: TenantId | undefined, candidateLimit: number, query?: Query) => Promise<readonly StandReadResult<Schema>[]>;
-    readonly observe: (onRead: QueryReaderObserver) => {
-        readonly close: () => void;
-    };
-}>;
+export declare const QueryReader: Readonly<QueryReaderAccess>;
 export {};
 //# sourceMappingURL=query-reader.d.ts.map

package/dist/services/query-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-reader.d.ts","sourceRoot":"","sources":["../../src/services/query-reader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEhE,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAI5D;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,SAAS,aAAa,EAC1C,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAClC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,cAAc,EAAE,MAAM,EACtB,KAAK,CAAC,EAAE,KAAK,KACV,OAAO,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACnF,CA+BC,CAAC"}
+{"version":3,"file":"query-reader.d.ts","sourceRoot":"","sources":["../../src/services/query-reader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAe,KAAK,KAAK,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAI5D;;GAEG;AACH,UAAU,iBAAiB;IACzB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,MAAM,SAAS,aAAa,EAC/B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAClC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,cAAc,EAAE,MAAM,EACtB,KAAK,CAAC,EAAE,KAAK,EACb,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAE/C;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACtE;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,iBAAiB,CA+ClD,CAAC"}

package/dist/services/query-reader.js

@@ -13,6 +13,7 @@
  */
 import { clone } from "@bufbuild/protobuf";
 import { QuerySchema } from "@spine-event-engine/proto/client";
+import { standAccess } from "../stand/stand.js";
 const observers = new Set();
 /**
  * Executes normalized Entity query plans against a Stand and exposes a testing-only read observer.
@@ -20,7 +21,19 @@ const observers = new Set();
  * @internal
  */
 export const QueryReader = Object.freeze({
-    read(stand, schema, plan, tenantId, candidateLimit, query) {
+    /**
+     * Reads the plan and forwards original query facts to Stand policy callbacks.
+     * @typeParam Schema Registered state schema.
+     * @param stand Context read facade.
+     * @param schema Requested state schema.
+     * @param plan Normalized storage plan.
+     * @param tenantId Effective tenant.
+     * @param candidateLimit Existing query candidate limit.
+     * @param query Original submitted Query, if present.
+     * @param readSide Trusted invocation context, if present.
+     * @returns Visible state records.
+     */
+    read(stand, schema, plan, tenantId, candidateLimit, query, readSide) {
         if (query !== undefined) {
             for (const observer of observers) {
                 try {
@@ -31,8 +44,15 @@ export const QueryReader = Object.freeze({
                 }
             }
         }
-        return stand.queryPlanVersioned(schema, { ...plan, candidateLimit }, tenantId === undefined ? {} : { tenantId });
+        const options = tenantId === undefined ? {} : { tenantId };
+        const selected = { ...plan, candidateLimit };
+        return readSide === undefined
+            ? stand.queryPlanVersioned(schema, selected, options)
+            : standAccess.queryPlanVersioned(stand, schema, selected, options, readSide);
     },
+    /**
+     * Registers a testing observer and returns a handle that removes it.
+     */
     observe(onRead) {
         observers.add(onRead);
         return Object.freeze({

package/dist/services/query-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-reader.js","sourceRoot":"","sources":["../../src/services/query-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,OAAO,EAAE,WAAW,EAAc,MAAM,kCAAkC,CAAC;AAO3E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAUnB,MAAM,CAAC,MAAM,CAAC;IACjB,IAAI,CACF,KAAY,EACZ,MAAc,EACd,IAAkC,EAClC,QAA8B,EAC9B,cAAsB,EACtB,KAAa;QAEb,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;gBACtC,CAAC;gBAAC,MAAM,CAAC;oBACP,+DAA+D;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,kBAAkB,CAC7B,MAAM,EACN,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,EAC3B,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAC3C,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAA2B;QACjC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"query-reader.js","sourceRoot":"","sources":["../../src/services/query-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,OAAO,EAAE,WAAW,EAAc,MAAM,kCAAkC,CAAC;AAG3E,OAAO,EAAE,WAAW,EAAoC,MAAM,mBAAmB,CAAC;AAQlF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;AAoCjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAgC,MAAM,CAAC,MAAM,CAAC;IACpE;;;;;;;;;;;OAWG;IACH,IAAI,CACF,KAAY,EACZ,MAAc,EACd,IAAkC,EAClC,QAA8B,EAC9B,cAAsB,EACtB,KAAa,EACb,QAA0B;QAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;gBACtC,CAAC;gBAAC,MAAM,CAAC;oBACP,+DAA+D;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,CAAC;QAC7C,OAAO,QAAQ,KAAK,SAAS;YAC3B,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC;YACrD,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjF,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAA2B;QACjC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/services/read-request-status.d.ts

@@ -0,0 +1,65 @@
+import type { Any } from "@bufbuild/protobuf/wkt";
+import { ConnectError } from "@connectrpc/connect";
+import { type Subscription } from "@spine-event-engine/proto/client";
+import type { TenantUnknownError } from "../context/tenant-unknown-error.js";
+/**
+ * Public read-side requests with distinct Spine validation enums.
+ */
+export type ReadRequestKind = "query" | "topic" | "subscription";
+/**
+ * Maps read-side validation to native Spine Error trailers and Connect details.
+ */
+export declare const ReadRequestStatus: {
+    /**
+     * Maps policy failures to sanitized transport codes without exposing private messages.
+     * @param error Policy, handler, or storage failure.
+     * @param message Public boundary failure message.
+     * @returns Sanitized recognized status or an internal error.
+     */
+    technical(error: unknown, message: string): ConnectError;
+    /**
+     * Creates a structured NotFound for a receiving context's missing membership.
+     *
+     * @param error Confirmed missing tenant from the target context.
+     * @returns Native and Connect status carrying the stable tenant type.
+     */
+    unknownTenant(error: TenantUnknownError): ConnectError;
+    /**
+     * Creates the status for a well-formed activation without a registry record.
+     *
+     * @returns A structured NotFound status for direct and managed clients.
+     */
+    unknownSubscription(): ConnectError;
+    /**
+     * Validates a complete request and sanitizes unexpected validator failures.
+     *
+     * @param kind The public request kind.
+     * @param validate Performs declared Protobuf validation.
+     */
+    check(kind: ReadRequestKind, validate: () => unknown): void;
+    /**
+     * Rejects unusable Topic criteria in lifecycle requests before record access.
+     *
+     * @param subscription Validated activation or cancellation request.
+     */
+    checkLifecycleCriterion(subscription: Subscription): void;
+    /**
+     * Maps tenant admission to a distinct structured status.
+     *
+     * @param type Existing tenant failure type.
+     * @param message Safe tenant explanation.
+     * @returns A structured InvalidArgument status.
+     */
+    tenant(type: string, message: string): ConnectError;
+    /**
+     * Creates an InvalidArgument status with an enum-qualified Spine Error.
+     *
+     * @param kind The invalid read-side request.
+     * @param unsupported Whether its target is not registered.
+     * @param message Safe public explanation.
+     * @param details Declared constraint violations, when available.
+     * @returns A transport error carrying native and Connect structured details.
+     */
+    invalid(kind: ReadRequestKind, unsupported: boolean, message: string, details?: Any): ConnectError;
+};
+//# sourceMappingURL=read-request-status.d.ts.map

package/dist/services/read-request-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-request-status.d.ts","sourceRoot":"","sources":["../../src/services/read-request-status.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAQ,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,cAAc,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;OAKG;qBACc,OAAO,WAAW,MAAM,GAAG,YAAY;IAaxD;;;;;OAKG;yBACkB,kBAAkB,GAAG,YAAY;IAkBtD;;;;OAIG;2BACoB,YAAY;IAanC;;;;;OAKG;gBACS,eAAe,YAAY,MAAM,OAAO,GAAG,IAAI;IAgB3D;;;;OAIG;0CACmC,YAAY,GAAG,IAAI;IAmBzD;;;;;;OAMG;iBACU,MAAM,WAAW,MAAM,GAAG,YAAY;IAUnD;;;;;;;;OAQG;kBAEK,eAAe,eACR,OAAO,WACX,MAAM,YACL,GAAG,GACZ,YAAY;CAmBhB,CAAC"}

package/dist/services/read-request-status.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { AnyPacker, ValidationException } from "@spine-event-engine/core";
+import { ErrorSchema, ValidationErrorSchema } from "@spine-event-engine/proto";
+import { QueryValidationError, SubscriptionValidationError, TopicValidationError, } from "@spine-event-engine/proto/client";
+/**
+ * Maps read-side validation to native Spine Error trailers and Connect details.
+ */
+export const ReadRequestStatus = {
+    /**
+     * Maps policy failures to sanitized transport codes without exposing private messages.
+     * @param error Policy, handler, or storage failure.
+     * @param message Public boundary failure message.
+     * @returns Sanitized recognized status or an internal error.
+     */
+    technical(error, message) {
+        const recognized = [
+            Code.Canceled,
+            Code.Unauthenticated,
+            Code.PermissionDenied,
+            Code.Unavailable,
+        ];
+        return new ConnectError(message, error instanceof ConnectError && recognized.includes(error.code) ? error.code : Code.Internal);
+    },
+    /**
+     * Creates a structured NotFound for a receiving context's missing membership.
+     *
+     * @param error Confirmed missing tenant from the target context.
+     * @returns Native and Connect status carrying the stable tenant type.
+     */
+    unknownTenant(error) {
+        const value = create(ErrorSchema, {
+            type: error.type,
+            code: Code.NotFound,
+            message: error.message,
+        });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(error.message, Code.NotFound, metadata, [{ desc: ErrorSchema, value }], error);
+    },
+    /**
+     * Creates the status for a well-formed activation without a registry record.
+     *
+     * @returns A structured NotFound status for direct and managed clients.
+     */
+    unknownSubscription() {
+        const message = "Subscription is unknown to this server.";
+        const value = create(ErrorSchema, {
+            type: "spine.client.SubscriptionValidationError",
+            code: SubscriptionValidationError.UNKNOWN_SUBSCRIPTION,
+            message,
+        });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.NotFound, metadata, [{ desc: ErrorSchema, value }]);
+    },
+    /**
+     * Validates a complete request and sanitizes unexpected validator failures.
+     *
+     * @param kind The public request kind.
+     * @param validate Performs declared Protobuf validation.
+     */
+    check(kind, validate) {
+        try {
+            validate();
+        }
+        catch (error) {
+            if (error instanceof ValidationException) {
+                throw ReadRequestStatus.invalid(kind, false, `${kind} validation failed.`, AnyPacker.pack(ValidationErrorSchema, error.asMessage()));
+            }
+            throw new ConnectError("Read request validation failed.", Code.Internal);
+        }
+    },
+    /**
+     * Rejects unusable Topic criteria in lifecycle requests before record access.
+     *
+     * @param subscription Validated activation or cancellation request.
+     */
+    checkLifecycleCriterion(subscription) {
+        const criterion = subscription.topic?.target?.criterion;
+        if (criterion?.case === "includeAll" && criterion.value)
+            return;
+        if (criterion?.case === "filters") {
+            const filters = criterion.value;
+            if ((filters.idFilter?.id.length ?? 0) > 0 || filters.filter.length > 0)
+                return;
+            throw ReadRequestStatus.invalid("subscription", false, "Subscription requires an ID filter or field filter.");
+        }
+        throw ReadRequestStatus.invalid("subscription", false, "Subscription requires filters or include_all = true.");
+    },
+    /**
+     * Maps tenant admission to a distinct structured status.
+     *
+     * @param type Existing tenant failure type.
+     * @param message Safe tenant explanation.
+     * @returns A structured InvalidArgument status.
+     */
+    tenant(type, message) {
+        const value = create(ErrorSchema, { type, code: Code.InvalidArgument, message });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.InvalidArgument, metadata, [
+            { desc: ErrorSchema, value },
+        ]);
+    },
+    /**
+     * Creates an InvalidArgument status with an enum-qualified Spine Error.
+     *
+     * @param kind The invalid read-side request.
+     * @param unsupported Whether its target is not registered.
+     * @param message Safe public explanation.
+     * @param details Declared constraint violations, when available.
+     * @returns A transport error carrying native and Connect structured details.
+     */
+    invalid(kind, unsupported, message, details) {
+        const type = `spine.client.${kind.charAt(0).toUpperCase()}${kind.slice(1)}ValidationError`;
+        const code = unsupported
+            ? kind === "query"
+                ? QueryValidationError.UNSUPPORTED_QUERY_TARGET
+                : TopicValidationError.UNSUPPORTED_TOPIC_TARGET
+            : kind === "query"
+                ? QueryValidationError.INVALID_QUERY
+                : kind === "topic"
+                    ? TopicValidationError.INVALID_TOPIC
+                    : SubscriptionValidationError.INVALID_SUBSCRIPTION;
+        const value = create(ErrorSchema, { type, code, message, details });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.InvalidArgument, metadata, [
+            { desc: ErrorSchema, value },
+        ]);
+    },
+};
+//# sourceMappingURL=read-request-status.js.map

package/dist/services/read-request-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-request-status.js","sourceRoot":"","sources":["../../src/services/read-request-status.ts"],"names":[],"mappings":"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"}

package/dist/services/spine-services.d.ts

@@ -1,7 +1,28 @@
 import type { ILogLayer } from "loglayer";
-import { type ConnectRouter } from "@connectrpc/connect";
-import { type BoundedContext } from "../context/bounded-context.js";
+import { type ConnectRouter, type HandlerContext } from "@connectrpc/connect";
+import type { ReaderProofVerifier } from "@spine-event-engine/core/spi/reader-forwarding";
+import { BoundedContext } from "../context/bounded-context.js";
+import { AppQueryExecution } from "./app-query-execution.js";
+import { type DirectReaderAuthenticator } from "./trusted-reader-ingress.js";
+import { ReadSideFilterEngine } from "../stand/read-side-filter-engine.js";
+/**
+ * Framework-only hooks for installing service read policies and App Query routing.
+ */
 interface SpineServicesAccess {
+    /**
+     * Attaches one Server's gRPC read policy before accepting requests.
+     *
+     * @param services Prepared service adapter.
+     * @param filters Registered policy engine.
+     */
+    installReadFilters(services: SpineServices, filters: ReadSideFilterEngine): void;
+    /**
+     * Attaches the Server-selected App Query capability before listener binding.
+     *
+     * @param services Adapter created for this Server.
+     * @param queries Exact-class handler table prepared by the Server.
+     */
+    installAppQueries(services: SpineServices, queries: AppQueryExecution): void;
     /**
      * Sets the server logger for service diagnostics.
      *
@@ -32,7 +53,8 @@ interface SpineServicesAccess {
  * 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
@@ -48,7 +70,9 @@ interface SpineServicesAccess {
  * 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.
  */
@@ -83,11 +107,16 @@ export interface SpineServicesOptions {
      */
     readonly contexts: readonly BoundedContext[];
     /**
-     * Maximum queued updates per active subscription before delivery is closed.
-     *
-     * Defaults to 100. Non-positive or non-finite values are coerced to 1.
+     * Existing native request-size bound used for internal reader assertions.
+     */
+    readonly readMaxBytes?: number;
+    /**
+     * Configured direct and trusted-peer authentication ports.
      */
-    readonly queueLimit?: number;
+    readonly readerAdmission?: Readonly<{
+        forwarded?: ReaderProofVerifier<HandlerContext>;
+        direct?: DirectReaderAuthenticator<HandlerContext>;
+    }>;
     /**
      * Maximum concurrent unknown-ID cancellation operations for this
      * `SpineServices` instance.

package/dist/services/spine-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spine-services.d.ts","sourceRoot":"","sources":["../../src/services/spine-services.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoF7E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAkB1F,UAAU,mBAAmB;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEhE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,aAAa;;IAuBxB;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB;IA4DzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CA6hB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAyBhC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC"}
+{"version":3,"file":"spine-services.d.ts","sourceRoot":"","sources":["../../src/services/spine-services.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUlG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAgF1F,OAAO,EAAE,cAAc,EAAwB,MAAM,+BAA+B,CAAC;AAOrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAwB,KAAK,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AASnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAY3E;;GAEG;AACH,UAAU,mBAAmB;IAC3B;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAEjF;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE7E;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEhE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,aAAa;;IAyBxB;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB;IA4DzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAg9B/C;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBA+ChC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC;QAClC,SAAS,CAAC,EAAE,mBAAmB,CAAC,cAAc,CAAC,CAAC;QAChD,MAAM,CAAC,EAAE,yBAAyB,CAAC,cAAc,CAAC,CAAC;KACpD,CAAC,CAAC;IAEH;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC"}