@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/control-plane/gateway-scope-enforcement.d.ts

@@ -0,0 +1,68 @@
+/**
+ * gateway-scope-enforcement.ts
+ *
+ * Per-client delivery enforcement for the control-plane event fan-out. Two
+ * orthogonal, AND-ed filters live here:
+ *   1. Scope: some wire channels declare a read scope (e.g. `session-update` ⇒
+ *      `read:sessions`); a scoped-down token cannot receive a channel it was not
+ *      granted.
+ *   2. Domain: a broadcast event (published via `ControlPlaneGateway.publishEvent`,
+ *      i.e. NOT flowing through a runtime-bus `onDomain` subscription) carries a
+ *      `RuntimeEventDomain` tag; a client that opted into a narrower set of
+ *      domains only receives events whose domain is in that set.
+ */
+import type { RuntimeEventDomain } from '../runtime/events/index.js';
+/**
+ * Wire events whose descriptor declares a read scope. Enforced per-client on the
+ * web SSE/WS fan-out so a scoped-down token cannot receive a channel it was not
+ * granted. In-process/local/service clients and admin tokens bypass (the
+ * single-admin-token model collapses scopes — see method-catalog-events.ts).
+ */
+export declare const CHANNEL_REQUIRED_SCOPE: Readonly<Record<string, string>>;
+/** The subset of a live client this decision needs. */
+export interface ScopedClientView {
+    readonly kind: string;
+    readonly admin?: boolean | undefined;
+    readonly scopes?: readonly string[] | undefined;
+}
+/**
+ * Whether a live client may receive a scope-gated channel. Only web SSE/WS
+ * clients (which carry a principal's scopes) are filtered; in-process/local and
+ * service ('daemon') clients are trusted and always pass, and an admin token
+ * bypasses (single-admin-token model — scopes collapse). A `*` scope is a
+ * wildcard grant. A principal-scoped client is filtered only when it carries an
+ * explicit scopes array; internal streams with no scopes stay trusted.
+ */
+export declare function clientMaySeeScopedChannel(client: ScopedClientView, requiredScope: string): boolean;
+/**
+ * Maps a manually-broadcast wire event (published via
+ * `ControlPlaneGateway.publishEvent`) to the `RuntimeEventDomain` a client must
+ * have subscribed to in order to receive it. These events do NOT flow through a
+ * runtime-bus `onDomain` subscription — that path is already domain-scoped by the
+ * subscription itself — so without this map the fan-out ignored the subscriber's
+ * declared domains and over-delivered (e.g. `session-update` reached the webui,
+ * which declares no `session` domain and dropped it as inert).
+ *
+ * An event ABSENT from this map carries no domain tag and is delivered to every
+ * scope-permitted client regardless of its subscribed domains (deliver-all). That
+ * keeps domain scoping strictly opt-in narrowing: a newly-added broadcast event
+ * cannot be silently dropped just because it is not yet tagged here. New verbs
+ * (later waves) should register their broadcast events in this map.
+ */
+export declare const EVENT_DOMAIN: Readonly<Record<string, RuntimeEventDomain>>;
+/**
+ * Whether a live client that subscribed to `clientDomains` should receive
+ * `event` under the domain filter.
+ *
+ * `clientDomains === null` means the client did NOT opt into domain narrowing
+ * (it connected with no `?domains=` param) and receives everything it is
+ * scope-permitted to see — today's behavior, preserved. This null=deliver-all
+ * default is the only migration-safe choice: an empty-set-means-nothing default
+ * would silently black out every consumer that did not opt in.
+ *
+ * An event with no `EVENT_DOMAIN` tag is always delivered (untagged ⇒ inert to
+ * the domain filter), so narrowing can only ever remove events we can positively
+ * attribute to a domain the client did not subscribe to.
+ */
+export declare function clientMayReceiveEventDomain(clientDomains: ReadonlySet<RuntimeEventDomain> | null, event: string): boolean;
+//# sourceMappingURL=gateway-scope-enforcement.d.ts.map

package/dist/platform/control-plane/gateway-scope-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-scope-enforcement.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/gateway-scope-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnE,CAAC;AAEF,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAKlG;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAcrE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC,GAAG,IAAI,EACrD,KAAK,EAAE,MAAM,GACZ,OAAO,CAKT"}

package/dist/platform/control-plane/gateway-scope-enforcement.js

@@ -0,0 +1,91 @@
+/**
+ * gateway-scope-enforcement.ts
+ *
+ * Per-client delivery enforcement for the control-plane event fan-out. Two
+ * orthogonal, AND-ed filters live here:
+ *   1. Scope: some wire channels declare a read scope (e.g. `session-update` ⇒
+ *      `read:sessions`); a scoped-down token cannot receive a channel it was not
+ *      granted.
+ *   2. Domain: a broadcast event (published via `ControlPlaneGateway.publishEvent`,
+ *      i.e. NOT flowing through a runtime-bus `onDomain` subscription) carries a
+ *      `RuntimeEventDomain` tag; a client that opted into a narrower set of
+ *      domains only receives events whose domain is in that set.
+ */
+/**
+ * Wire events whose descriptor declares a read scope. Enforced per-client on the
+ * web SSE/WS fan-out so a scoped-down token cannot receive a channel it was not
+ * granted. In-process/local/service clients and admin tokens bypass (the
+ * single-admin-token model collapses scopes — see method-catalog-events.ts).
+ */
+export const CHANNEL_REQUIRED_SCOPE = {
+    'session-update': 'read:sessions',
+};
+/**
+ * Whether a live client may receive a scope-gated channel. Only web SSE/WS
+ * clients (which carry a principal's scopes) are filtered; in-process/local and
+ * service ('daemon') clients are trusted and always pass, and an admin token
+ * bypasses (single-admin-token model — scopes collapse). A `*` scope is a
+ * wildcard grant. A principal-scoped client is filtered only when it carries an
+ * explicit scopes array; internal streams with no scopes stay trusted.
+ */
+export function clientMaySeeScopedChannel(client, requiredScope) {
+    if (client.kind !== 'web')
+        return true;
+    if (client.admin)
+        return true;
+    if (client.scopes === undefined)
+        return true;
+    return client.scopes.includes(requiredScope) || client.scopes.includes('*');
+}
+/**
+ * Maps a manually-broadcast wire event (published via
+ * `ControlPlaneGateway.publishEvent`) to the `RuntimeEventDomain` a client must
+ * have subscribed to in order to receive it. These events do NOT flow through a
+ * runtime-bus `onDomain` subscription — that path is already domain-scoped by the
+ * subscription itself — so without this map the fan-out ignored the subscriber's
+ * declared domains and over-delivered (e.g. `session-update` reached the webui,
+ * which declares no `session` domain and dropped it as inert).
+ *
+ * An event ABSENT from this map carries no domain tag and is delivered to every
+ * scope-permitted client regardless of its subscribed domains (deliver-all). That
+ * keeps domain scoping strictly opt-in narrowing: a newly-added broadcast event
+ * cannot be silently dropped just because it is not yet tagged here. New verbs
+ * (later waves) should register their broadcast events in this map.
+ */
+export const EVENT_DOMAIN = {
+    'session-update': 'session',
+    'approval-update': 'permissions',
+    // W3-S3: sessions.detach's `session-detached` is TODAY a payload discriminant
+    // inside the `session-update` channel (session-broker.ts publishUpdate wraps
+    // it), so it is already domain-scoped by the entry above. This tag is
+    // defense-in-depth: if the discriminant is ever promoted to a top-level
+    // broadcast, it stays in the session domain instead of silently deliver-all.
+    'session-detached': 'session',
+    // W5-S1: sessions.delete's `session-deleted` is likewise a payload discriminant
+    // inside `session-update` today (already domain-scoped by the entry above); this
+    // tag is the same defense-in-depth as `session-detached` if it is ever promoted
+    // to a top-level broadcast.
+    'session-deleted': 'session',
+};
+/**
+ * Whether a live client that subscribed to `clientDomains` should receive
+ * `event` under the domain filter.
+ *
+ * `clientDomains === null` means the client did NOT opt into domain narrowing
+ * (it connected with no `?domains=` param) and receives everything it is
+ * scope-permitted to see — today's behavior, preserved. This null=deliver-all
+ * default is the only migration-safe choice: an empty-set-means-nothing default
+ * would silently black out every consumer that did not opt in.
+ *
+ * An event with no `EVENT_DOMAIN` tag is always delivered (untagged ⇒ inert to
+ * the domain filter), so narrowing can only ever remove events we can positively
+ * attribute to a domain the client did not subscribe to.
+ */
+export function clientMayReceiveEventDomain(clientDomains, event) {
+    if (clientDomains === null)
+        return true;
+    const domain = EVENT_DOMAIN[event];
+    if (domain === undefined)
+        return true;
+    return clientDomains.has(domain);
+}

package/dist/platform/control-plane/gateway-utils.d.ts

@@ -34,4 +34,21 @@ export declare function hasReplayScope(scope: ControlPlaneEventReplayScope): boo
 export declare function canReplayEventToClient(event: ScopedControlPlaneRecentEvent, options: ControlPlaneReplayClientOptions): boolean;
 export declare function stripReplayScope(event: ScopedControlPlaneRecentEvent): ControlPlaneRecentEvent;
 export declare function pruneDisconnectedClientRecords(clients: Map<string, ControlPlaneClientRecord>, now?: number): void;
+/**
+ * Replay recent traffic to a freshly-connected client. Mirrors live delivery:
+ * canReplayEventToClient applies the kind/route/surface/domain-name filters, and
+ * the EVENT_DOMAIN broadcast-domain filter is applied on top so a domain-narrowed
+ * client is not handed a replayed broadcast (e.g. session-update) for a domain it
+ * did not subscribe to.
+ *
+ * `replayDomains` MUST be the same null-or-set value the caller registered on the
+ * live client (`LiveControlPlaneClient.domains`) — null when the client did NOT
+ * opt into narrowing (deliver-all, matching live), a `Set` when it did. Do NOT
+ * derive this from `options.domains` here: by the time options reaches this
+ * function it has already been normalized (empty/undefined domains fall back to
+ * DEFAULT_DOMAINS, which excludes e.g. 'permissions'), so re-deriving from it
+ * would always look "explicit" and silently narrow every default consumer's
+ * replay — the bug this parameter exists to prevent.
+ */
+export declare function replayRecentTraffic(recentEvents: readonly ScopedControlPlaneRecentEvent[], send: (event: string, payload: unknown, id?: string) => void, options: ControlPlaneReplayClientOptions, replayDomains: ReadonlySet<RuntimeEventDomain> | null, sinceId?: string): void;
 //# sourceMappingURL=gateway-utils.d.ts.map

package/dist/platform/control-plane/gateway-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-utils.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/gateway-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAE5G,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D,eAAO,MAAM,qBAAqB,EAAE,wBAMnC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,SAAS,kBAAkB,EAexD,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,GAAG,SAAS,CAAC;CACjE;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAKD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASnI;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,4BAA4B,CASjG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAAG,kBAAkB,EAAE,CAGhH;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAQ3E;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,6BAA6B,EACpC,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAcT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,6BAA6B,GAAG,uBAAuB,CAO9F;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC9C,GAAG,SAAa,GACf,IAAI,CAUN"}
+{"version":3,"file":"gateway-utils.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/gateway-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAE5G,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAG3D,eAAO,MAAM,qBAAqB,EAAE,wBAMnC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,SAAS,kBAAkB,EAexD,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,GAAG,SAAS,CAAC;CACjE;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAKD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASnI;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,4BAA4B,CASjG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAAG,kBAAkB,EAAE,CAGhH;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAQ3E;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,6BAA6B,EACpC,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAcT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,6BAA6B,GAAG,uBAAuB,CAO9F;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC9C,GAAG,SAAa,GACf,IAAI,CAUN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,SAAS,6BAA6B,EAAE,EACtD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,EAC5D,OAAO,EAAE,+BAA+B,EACxC,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC,GAAG,IAAI,EACrD,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAUN"}

package/dist/platform/control-plane/gateway-utils.js

@@ -1,4 +1,5 @@
 import { isRuntimeEventDomain } from '../runtime/events/index.js';
+import { clientMayReceiveEventDomain } from './gateway-scope-enforcement.js';
 export const DEFAULT_SERVER_CONFIG = {
     enabled: false,
     host: '127.0.0.1',
@@ -95,3 +96,32 @@ export function pruneDisconnectedClientRecords(clients, now = Date.now()) {
         clients.delete(client.id);
     }
 }
+/**
+ * Replay recent traffic to a freshly-connected client. Mirrors live delivery:
+ * canReplayEventToClient applies the kind/route/surface/domain-name filters, and
+ * the EVENT_DOMAIN broadcast-domain filter is applied on top so a domain-narrowed
+ * client is not handed a replayed broadcast (e.g. session-update) for a domain it
+ * did not subscribe to.
+ *
+ * `replayDomains` MUST be the same null-or-set value the caller registered on the
+ * live client (`LiveControlPlaneClient.domains`) — null when the client did NOT
+ * opt into narrowing (deliver-all, matching live), a `Set` when it did. Do NOT
+ * derive this from `options.domains` here: by the time options reaches this
+ * function it has already been normalized (empty/undefined domains fall back to
+ * DEFAULT_DOMAINS, which excludes e.g. 'permissions'), so re-deriving from it
+ * would always look "explicit" and silently narrow every default consumer's
+ * replay — the bug this parameter exists to prevent.
+ */
+export function replayRecentTraffic(recentEvents, send, options, replayDomains, sinceId) {
+    const sinceIndex = sinceId ? recentEvents.findIndex((event) => event.id === sinceId) : -1;
+    const window = sinceIndex >= 0
+        ? recentEvents.slice(0, sinceIndex).reverse()
+        : recentEvents.slice(0, 20).reverse();
+    for (const recentEvent of window) {
+        if (!canReplayEventToClient(recentEvent, options))
+            continue;
+        if (!clientMayReceiveEventDomain(replayDomains, recentEvent.event))
+            continue;
+        send(recentEvent.event, recentEvent.payload, recentEvent.id);
+    }
+}

package/dist/platform/control-plane/gateway.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeStore } from '../runtime/store/index.js';
 import type { RuntimeEventBus, RuntimeEventDomain } from '../runtime/events/index.js';
 import type { ControlPlaneClientDescriptor, ControlPlaneServerConfig, ControlPlaneSurfaceMessage } from './types.js';
-import type { FeatureFlagReader } from '../runtime/feature-flags/index.js';
+import { type FeatureFlagReader } from '../runtime/feature-flags/index.js';
 import { DEFAULT_DOMAINS, type ControlPlaneRecentEvent } from './gateway-utils.js';
 export type { ControlPlaneRecentEvent } from './gateway-utils.js';
 export interface ControlPlaneGatewayConfig {
@@ -19,6 +19,8 @@ export interface ControlPlaneEventStreamOptions {
     readonly principalId?: string | undefined;
     readonly principalKind?: 'user' | 'bot' | 'service' | 'token' | undefined;
     readonly scopes?: readonly string[] | undefined;
+    /** Admin token — scopes collapse; sees all channels. */
+    readonly admin?: boolean | undefined;
     readonly sessionId?: string | undefined;
     readonly routeId?: string | undefined;
     readonly surfaceId?: string | undefined;
@@ -30,6 +32,15 @@ interface LiveControlPlaneClient {
     readonly kind: 'tui' | 'web' | 'slack' | 'discord' | 'ntfy' | 'webhook' | 'homeassistant' | 'telegram' | 'google-chat' | 'signal' | 'whatsapp' | 'telephony' | 'imessage' | 'msteams' | 'bluebubbles' | 'mattermost' | 'matrix' | 'daemon';
     readonly surfaceId?: string | undefined;
     readonly routeId?: string | undefined;
+    /** Principal scopes (SSE/WS); `admin` collapses scopes (sees every channel). */
+    readonly scopes?: readonly string[] | undefined;
+    readonly admin?: boolean | undefined;
+    /**
+     * Subscribed domains for the broadcast (`publishEvent`) fan-out. `null` =
+     * deliver-all (client did not opt into narrowing); a non-null set narrows to
+     * tagged events in the set. For WS this is a live ref to the subscription set.
+     */
+    readonly domains: ReadonlySet<RuntimeEventDomain> | null;
     readonly send: (event: string, payload: unknown, id?: string) => void;
 }
 export declare class ControlPlaneGateway {
@@ -93,7 +104,6 @@ export declare class ControlPlaneGateway {
     subscribeWebSocketClient(clientId: string, domains: readonly RuntimeEventDomain[]): void;
     unsubscribeWebSocketClient(clientId: string, domains?: readonly RuntimeEventDomain[]): void;
     closeWebSocketClient(clientId: string, reason?: string): void;
-    private replayRecentTraffic;
     createEventStream(request: Request, options?: ControlPlaneEventStreamOptions): Response;
     renderWebUi(authTokenHint?: string): Response;
     private _scheduleControlPlaneSync;

package/dist/platform/control-plane/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/gateway.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/gateway.ts"],"names":[],"mappings":"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"}

package/dist/platform/control-plane/gateway.js

@@ -3,8 +3,10 @@ import { logger } from '../utils/logger.js';
 import { createDomainDispatch } from '../runtime/store/index.js';
 import { emitControlPlaneAuthGranted, emitControlPlaneClientConnected, emitControlPlaneClientDisconnected, emitControlPlaneSubscriptionCreated, emitControlPlaneSubscriptionDropped, emitStreamSubscriberConnected, emitStreamSubscriberDisconnected, } from '../runtime/emitters/index.js';
 import { renderControlPlaneGatewayWebUi } from './gateway-web-ui.js';
+import { buildGatewayDisabledResponseBody } from './gateway-disabled-response.js';
+import { CHANNEL_REQUIRED_SCOPE, clientMayReceiveEventDomain, clientMaySeeScopedChannel } from './gateway-scope-enforcement.js';
 import { isFeatureGateEnabled, requireFeatureGate } from '../runtime/feature-flags/index.js';
-import { DEFAULT_DOMAINS, DEFAULT_SERVER_CONFIG, canReplayEventToClient, hasReplayScope, normalizeRuntimeDomains, pruneDisconnectedClientRecords, serializeEnvelope, stripReplayScope, toClientDescriptor, } from './gateway-utils.js';
+import { DEFAULT_DOMAINS, DEFAULT_SERVER_CONFIG, hasReplayScope, normalizeRuntimeDomains, pruneDisconnectedClientRecords, replayRecentTraffic, serializeEnvelope, stripReplayScope, toClientDescriptor, } from './gateway-utils.js';
 export class ControlPlaneGateway {
     runtimeBus;
     dispatch;
@@ -14,7 +16,6 @@ export class ControlPlaneGateway {
     liveClients = new Map();
     websocketClients = new Map();
     recentMessages = [];
-    // Circular ring buffer for O(1) insert instead of O(n) unshift.
     _recentEventsRing;
     _recentEventsHead = 0;
     _recentEventsCount = 0;
@@ -31,7 +32,6 @@ export class ControlPlaneGateway {
                 out.push(entry);
             }
             else if (process.env.NODE_ENV !== 'production') {
-                // Dev-only: undefined slot despite valid count — ring buffer accounting bug.
                 logger.error('[ControlPlaneGateway] recentEvents: undefined slot at ring index', { head: this._recentEventsHead, count: this._recentEventsCount, index: idx, offset: i });
             }
         }
@@ -170,6 +170,7 @@ export class ControlPlaneGateway {
         if (!this.isEnabled())
             return;
         const record = this.rememberEvent(event, payload, filter);
+        const requiredScope = CHANNEL_REQUIRED_SCOPE[event];
         for (const client of this.liveClients.values()) {
             if (filter?.clientKind && client.kind !== filter.clientKind)
                 continue;
@@ -179,6 +180,11 @@ export class ControlPlaneGateway {
                 continue;
             if (filter?.surfaceId && client.surfaceId !== filter.surfaceId)
                 continue;
+            if (requiredScope && !clientMaySeeScopedChannel(client, requiredScope))
+                continue;
+            // Domain filter, AND-ed with scope (null = deliver-all; untagged = delivered).
+            if (!clientMayReceiveEventDomain(client.domains, event))
+                continue;
             client.send(event, payload, record.id);
         }
     }
@@ -256,18 +262,24 @@ export class ControlPlaneGateway {
             },
         };
         const traceId = `control-plane:${clientId}`;
+        // Live ref to the WS subscription set, shared with the liveClient (null = deliver-all).
+        const wsDomains = new Set();
+        const explicitDomains = (options.domains?.length ?? 0) > 0;
         this.clients.set(clientId, clientRecord);
         this.liveClients.set(clientId, {
             clientId,
             kind: options.clientKind ?? 'web',
             surfaceId: options.surfaceId,
             routeId: options.routeId,
+            scopes: options.scopes,
+            admin: options.admin,
+            domains: explicitDomains ? wsDomains : null,
             send,
         });
         this.websocketClients.set(clientId, {
             clientId,
             traceId,
-            domains: new Set(),
+            domains: wsDomains,
             unsubscribers: new Map(),
         });
         this.dispatch?.syncControlPlaneState({
@@ -309,7 +321,7 @@ export class ControlPlaneGateway {
         }
         this.subscribeWebSocketClient(clientId, selectedDomains);
         send('ready', { clientId, domains: selectedDomains, transport: 'websocket' });
-        this.replayRecentTraffic(send, { ...options, clientId, domains: selectedDomains });
+        replayRecentTraffic(this.recentEvents, send, { ...options, clientId, domains: selectedDomains }, explicitDomains ? wsDomains : null);
         return { clientId, domains: selectedDomains };
     }
     touchWebSocketClient(clientId, metadata = {}) {
@@ -443,20 +455,9 @@ export class ControlPlaneGateway {
             connectionState: [...this.clients.values()].some((client) => client.connected) ? 'connected' : 'disconnected',
         }, 'control-plane.gateway.ws-disconnect');
     }
-    replayRecentTraffic(send, options, sinceId) {
-        const sinceIndex = sinceId ? this.recentEvents.findIndex((event) => event.id === sinceId) : -1;
-        const recentEvents = sinceIndex >= 0
-            ? this.recentEvents.slice(0, sinceIndex).reverse()
-            : this.recentEvents.slice(0, 20).reverse();
-        for (const recentEvent of recentEvents) {
-            if (!canReplayEventToClient(recentEvent, options))
-                continue;
-            send(recentEvent.event, recentEvent.payload, recentEvent.id);
-        }
-    }
     createEventStream(request, options = {}) {
         if (!this.isEnabled()) {
-            return Response.json({ error: 'control-plane-gateway feature flag is disabled' }, { status: 503 });
+            return Response.json(buildGatewayDisabledResponseBody(), { status: 503 });
         }
         if (!this.runtimeBus) {
             return Response.json({ error: 'Runtime event bus unavailable' }, { status: 503 });
@@ -527,16 +528,11 @@ export class ControlPlaneGateway {
             });
         }
         let teardown = () => { };
-        // ReadableStream default HWM is 1, which causes startup `ready` + replay
-        // enqueues to drop subsequent chunks before any consumer has pulled. Raise HWM to
-        // 256 chunks so initial handshake + recent-traffic replay + live events fit without
-        // tripping the backpressure guard for a healthy consumer.
+        // HWM 256 (default 1 drops handshake/replay chunks before the consumer pulls).
         const stream = new ReadableStream({
             start: (controller) => {
                 const send = (event, payload, id) => {
-                    // Drop event if the stream's internal queue is full (backpressure guard).
-                    // desiredSize <= 0 means the consumer is falling behind; dropping prevents
-                    // unbounded memory growth from enqueued-but-unread chunks.
+                    // Backpressure guard: drop when the consumer is falling behind (desiredSize<=0).
                     if ((controller.desiredSize ?? 1) <= 0)
                         return;
                     controller.enqueue(encoder.encode(`${id ? `id: ${id}\n` : ''}event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`));
@@ -556,14 +552,18 @@ export class ControlPlaneGateway {
                     const record = this.rememberEvent(domain, serialized);
                     send(domain, serialized, record.id);
                 }));
+                // Opt-in narrowing (null=deliver-all, never the DEFAULT_DOMAINS fallback); reused below for replay.
+                const sseLiveDomains = (options.domains?.length ?? 0) > 0 ? new Set(selectedDomains) : null;
                 this.liveClients.set(clientId, {
                     clientId,
                     kind: options.clientKind ?? 'web',
                     surfaceId: options.surfaceId,
                     routeId: options.routeId,
+                    scopes: options.scopes,
+                    admin: options.admin,
+                    domains: sseLiveDomains,
                     send,
                 });
-                // emit STREAM_SUBSCRIBER_CONNECTED when the SSE client is registered.
                 emitStreamSubscriberConnected(this.runtimeBus, {
                     sessionId: options.sessionId ?? 'control-plane',
                     source: 'control-plane.gateway',
@@ -576,7 +576,6 @@ export class ControlPlaneGateway {
                 const heartbeat = setInterval(() => {
                     send('heartbeat', { clientId, ts: Date.now() });
                 }, 15_000);
-                // Don't block clean process exit.
                 heartbeat.unref?.();
                 teardown = () => {
                     clearInterval(heartbeat);
@@ -615,7 +614,6 @@ export class ControlPlaneGateway {
                             clientId,
                             reason: 'stream-closed',
                         });
-                        // emit STREAM_SUBSCRIBER_DISCONNECTED when the SSE client tears down.
                         emitStreamSubscriberDisconnected(this.runtimeBus, {
                             sessionId: options.sessionId ?? 'control-plane',
                             source: 'control-plane.gateway',
@@ -633,7 +631,7 @@ export class ControlPlaneGateway {
                     controller.close();
                 }, { once: true });
                 send('ready', { clientId, domains: selectedDomains });
-                this.replayRecentTraffic(send, { ...options, clientId, domains: selectedDomains }, lastEventId);
+                replayRecentTraffic(this.recentEvents, send, { ...options, clientId, domains: selectedDomains }, sseLiveDomains, lastEventId);
             },
             cancel: () => {
                 teardown();
@@ -649,7 +647,7 @@ export class ControlPlaneGateway {
     }
     renderWebUi(authTokenHint = '') {
         if (!this.isEnabled()) {
-            return Response.json({ error: 'control-plane-gateway feature flag is disabled' }, { status: 503 });
+            return Response.json(buildGatewayDisabledResponseBody(), { status: 503 });
         }
         return renderControlPlaneGatewayWebUi(authTokenHint);
     }
@@ -675,13 +673,11 @@ export class ControlPlaneGateway {
             payload,
             ...(replayScope && hasReplayScope(replayScope) ? { replayScope } : {}),
         };
-        // O(1) circular ring buffer write — no array shifting.
         this._recentEventsRing[this._recentEventsHead] = record;
         this._recentEventsHead = (this._recentEventsHead + 1) % this._recentEventsCapacity;
         if (this._recentEventsCount < this._recentEventsCapacity)
             this._recentEventsCount++;
         this._lastEventAt = record.createdAt;
-        // Debounced: coalesce N events/frame into 1 store sync.
         this._scheduleControlPlaneSync();
         return record;
     }

package/dist/platform/control-plane/index.d.ts

@@ -3,11 +3,15 @@ export type { ControlPlaneGatewayConfig, ControlPlaneEventStreamOptions, Control
 export { ControlPlaneGateway } from './gateway.js';
 export { GatewayMethodCatalog, } from './method-catalog.js';
 export type { GatewayEventDescriptor, GatewayEventListOptions, GatewayEventTransport, GatewayHttpBinding, GatewayMethodAccess, GatewayMethodDescriptor, GatewayMethodHandler, GatewayMethodInvocation, GatewayMethodInvocationContext, GatewayMethodListOptions, GatewayMethodSource, GatewayMethodTransport, } from './method-catalog.js';
-export type { FindSharedSessionOptions, SharedSessionMessage, SharedSessionParticipant, SharedSessionRecord, SharedSessionSubmission, SteerSharedSessionMessageInput, SubmitSharedSessionMessageInput, } from './session-types.js';
+export type { CreateSharedSessionInput, EnsureSharedSessionInput, FindSharedSessionOptions, ListSharedSessionsOptions, ParticipantRouteAttachInput, RegisterSharedSessionInput, SharedSessionRegisterResult, SharedSessionKind, SharedSessionMessage, SharedSessionParticipant, SharedSessionRecord, SharedSessionStatus, SharedSessionSubmission, SteerSharedSessionMessageInput, SubmitSharedSessionMessageInput, } from './session-types.js';
 export type { SharedSessionCompletion, SharedSessionContinuationRequest, SharedSessionContinuationResult, SharedSessionHelperModelOverride, SharedSessionInputIntent, SharedSessionInputRecord, SharedSessionInputState, SharedSessionRoutingIntent, } from './session-intents.js';
 export { SharedSessionBroker } from './session-broker.js';
+export { discoverLegacySessionSources, importLegacySessionStores, } from './session-store-importer.js';
+export type { LegacySessionSource, ImportLegacySessionsResult, } from './session-store-importer.js';
 export type { SharedApprovalRecord, SharedApprovalAuditRecord, SharedApprovalStatus, RequestSharedApprovalInput, } from './approval-broker.js';
 export { ApprovalBroker } from './approval-broker.js';
+export { buildModifiedEditArgs, readApprovalEditHunks, resolveApprovalHunkSelection, } from './approval-hunk-apply.js';
+export type { EditHunkLike, ApprovalHunkSelectionResolution } from './approval-hunk-apply.js';
 export type { ControlPlaneAuthMode, ControlPlaneAuthSnapshot } from '../../client-auth/control-plane-auth-snapshot.js';
 export type { MessageSource, ConversationMessageEnvelope } from './conversation-message.js';
 export { buildOperatorContract } from './operator-contract.js';
@@ -17,4 +21,5 @@ export { ARTIFACT_ATTACHMENT_SCHEMA, ARTIFACT_DESCRIPTOR_SCHEMA, } from './opera
 export { AUTOMATION_RUN_SCHEMA, ROUTE_BINDING_SCHEMA, } from './operator-contract-schemas-admin.js';
 export { SHARED_SESSION_INPUT_RECORD_SCHEMA, SHARED_SESSION_ROUTING_INTENT_SCHEMA, } from './operator-contract-schemas-runtime.js';
 export { KNOWLEDGE_INJECTION_PROMPT_SCHEMA, KNOWLEDGE_INJECTION_SCHEMA, } from './operator-contract-schemas-knowledge.js';
+export { registerW3S2GatewayMethods } from './routes/register-w3-s2.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/control-plane/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,gCAAgC,EAChC,+BAA+B,EAC/B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,kDAAkD,CAAC;AACvH,YAAY,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,kCAAkC,EAClC,oCAAoC,GACrC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,0CAA0C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,8BAA8B,EAC9B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,gCAAgC,EAChC,+BAA+B,EAC/B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAC9F,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,kDAAkD,CAAC;AACvH,YAAY,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,kCAAkC,EAClC,oCAAoC,GACrC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,0CAA0C,CAAC;AAElD,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/platform/control-plane/index.js

@@ -1,7 +1,9 @@
 export { ControlPlaneGateway } from './gateway.js';
 export { GatewayMethodCatalog, } from './method-catalog.js';
 export { SharedSessionBroker } from './session-broker.js';
+export { discoverLegacySessionSources, importLegacySessionStores, } from './session-store-importer.js';
 export { ApprovalBroker } from './approval-broker.js';
+export { buildModifiedEditArgs, readApprovalEditHunks, resolveApprovalHunkSelection, } from './approval-hunk-apply.js';
 export { buildOperatorContract } from './operator-contract.js';
 export { dispatchDaemonApiRoutes } from './routes/index.js';
 export { ARTIFACT_ACQUISITION_MODE_SCHEMA, ARTIFACT_FETCH_MODE_SCHEMA, } from './media-contract-schemas.js';
@@ -9,3 +11,5 @@ export { ARTIFACT_ATTACHMENT_SCHEMA, ARTIFACT_DESCRIPTOR_SCHEMA, } from './opera
 export { AUTOMATION_RUN_SCHEMA, ROUTE_BINDING_SCHEMA, } from './operator-contract-schemas-admin.js';
 export { SHARED_SESSION_INPUT_RECORD_SCHEMA, SHARED_SESSION_ROUTING_INTENT_SCHEMA, } from './operator-contract-schemas-runtime.js';
 export { KNOWLEDGE_INJECTION_PROMPT_SCHEMA, KNOWLEDGE_INJECTION_SCHEMA, } from './operator-contract-schemas-knowledge.js';
+// W3-S2 — fleet.*/checkpoints.*/sessions.search verb registration (see routes/register-w3-s2.ts).
+export { registerW3S2GatewayMethods } from './routes/register-w3-s2.js';

package/dist/platform/control-plane/invoke-input-validation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * invoke-input-validation.ts (W3-S1, Part B)
+ *
+ * A central, catalog-driven input gate for the gateway invoke layer. Before a
+ * resolved verb's handler (or its HTTP delegate) runs, the invocation's params
+ * are validated against the method catalog's `inputSchema`, returning an honest
+ * 400 instead of letting a wrong-typed or missing-required field reach a handler
+ * that would silently coerce or misbehave.
+ *
+ * Scope is deliberately the TYPED subset only:
+ *   - Object schemas that declare `properties` are structurally validated.
+ *   - Generic object schemas (object with no `properties`, e.g. an
+ *     additionalProperties-only "any JSON object") pass through unchanged — the
+ *     status quo — so no verb is falsely rejected for extra fields.
+ *   - A verb with no `inputSchema` is untyped and passes through.
+ *
+ * The validator is lenient on unknown keys (does NOT enforce
+ * `additionalProperties: false`): the goal is to reject provable type/shape
+ * mismatches, not to tighten every loose handler that historically tolerated
+ * extra fields. It reports the first violation it finds.
+ */
+import type { GatewayMethodDescriptor } from './method-catalog-shared.js';
+/** Structured result of a rejected invocation — same 400 shape the router uses. */
+export interface InvokeValidationError {
+    readonly code: 'INVALID_INPUT';
+    readonly detail: string;
+}
+/** How a descriptor's inputSchema is treated by the validate gate. */
+export type InvokeValidationDisposition = 'validated' | 'generic' | 'untyped';
+/**
+ * Classify an inputSchema for both the validate gate and coverage accounting:
+ *   - 'validated' — an object schema with declared properties (structurally checked)
+ *   - 'generic'   — an object schema with no properties (skipped)
+ *   - 'untyped'   — absent, or a non-object root we do not structurally validate (skipped)
+ */
+export declare function classifyInputSchema(schema: Record<string, unknown> | undefined): InvokeValidationDisposition;
+/**
+ * Validate an invocation's params against a verb's inputSchema. Returns an
+ * `InvokeValidationError` when a typed schema is violated, or null when the
+ * params conform, the schema is generic/untyped, or there is nothing to check.
+ *
+ * `params` is the request payload the verb receives (the invoke body for
+ * body-carrying verbs). `undefined` is treated as an empty object so a schema
+ * with required fields honestly reports them missing.
+ */
+export declare function validateInvocationInput(descriptor: GatewayMethodDescriptor, params: unknown): InvokeValidationError | null;
+/** Coverage tallies for the operator contract manifest: how many cataloged verbs
+ *  the invoke input gate structurally validates vs skips (generic/untyped). */
+export interface InvokeValidationCoverage {
+    readonly methods: number;
+    readonly validated: number;
+    readonly skippedGeneric: number;
+    readonly skippedUntyped: number;
+}
+export declare function summarizeInvokeValidationCoverage(methods: readonly GatewayMethodDescriptor[]): InvokeValidationCoverage;
+//# sourceMappingURL=invoke-input-validation.d.ts.map

package/dist/platform/control-plane/invoke-input-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-input-validation.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/invoke-input-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE1E,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAY9E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,2BAA2B,CAK5G;AAsFD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,uBAAuB,EACnC,MAAM,EAAE,OAAO,GACd,qBAAqB,GAAG,IAAI,CAM9B;AAED;+EAC+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,SAAS,uBAAuB,EAAE,GAC1C,wBAAwB,CAY1B"}