@cleocode/contracts 2026.5.130 → 2026.5.131

package/dist/gateway/rpc/version.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FROZEN protocol version for the `gateway/rpc` v1.0 wire contract.
+ *
+ * The CLI-RPC transport adapter (`@cleocode/runtime/gateway/rpc`) and any RPC
+ * client MUST agree on this value. The wire format is newline-delimited JSON
+ * (NDJSON): one {@link GatewayRpcFrame} per line over a unix-domain socket —
+ * the same framing discipline as the FROZEN `supervisor-ipc` v1.0 contract
+ * (`packages/contracts/src/supervisor-ipc/`), but a SEPARATE message set: this
+ * carries `DispatchRequest`/`DispatchResponse` over the gateway, not supervisor
+ * process-control messages.
+ *
+ * Bump only via a new major contract revision in a new directory, never edit
+ * this value in place — see {@link GATEWAY_RPC_MESSAGE_KINDS} for the frozen
+ * v1.0 message set.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7464 | NDJSON framing}
+ * @task T11449
+ * @epic T11254
+ * @saga T11243
+ * @packageDocumentation
+ */
+/**
+ * The frozen `gateway/rpc` protocol version string.
+ *
+ * Both the TS drift test (`__tests__/freeze.test.ts`) and the adapter's
+ * version-negotiation handshake pin this exact value. A frame whose
+ * `protocol_version` differs from this is rejected with an `error` frame.
+ */
+export declare const GATEWAY_RPC_PROTOCOL_VERSION: "1.0.0";
+/**
+ * Default base name for the RPC unix-socket channel.
+ *
+ * Callers resolve the concrete socket path under the CLEO home (e.g.
+ * `<cleoHome>/<basename>.sock`); the adapter itself takes the resolved path so
+ * the runtime stays free of any `@cleocode/paths` dependency. Mirrors
+ * {@link SUPERVISOR_IPC_CHANNEL_BASENAME} from the supervisor-ipc contract.
+ */
+export declare const GATEWAY_RPC_CHANNEL_BASENAME: "cleo-gateway-rpc";
+//# sourceMappingURL=version.d.ts.map

package/dist/gateway/rpc/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../src/gateway/rpc/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAG,OAAgB,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAG,kBAA2B,CAAC"}

package/dist/gateway/rpc/version.js

@@ -0,0 +1,39 @@
+/**
+ * FROZEN protocol version for the `gateway/rpc` v1.0 wire contract.
+ *
+ * The CLI-RPC transport adapter (`@cleocode/runtime/gateway/rpc`) and any RPC
+ * client MUST agree on this value. The wire format is newline-delimited JSON
+ * (NDJSON): one {@link GatewayRpcFrame} per line over a unix-domain socket —
+ * the same framing discipline as the FROZEN `supervisor-ipc` v1.0 contract
+ * (`packages/contracts/src/supervisor-ipc/`), but a SEPARATE message set: this
+ * carries `DispatchRequest`/`DispatchResponse` over the gateway, not supervisor
+ * process-control messages.
+ *
+ * Bump only via a new major contract revision in a new directory, never edit
+ * this value in place — see {@link GATEWAY_RPC_MESSAGE_KINDS} for the frozen
+ * v1.0 message set.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7464 | NDJSON framing}
+ * @task T11449
+ * @epic T11254
+ * @saga T11243
+ * @packageDocumentation
+ */
+/**
+ * The frozen `gateway/rpc` protocol version string.
+ *
+ * Both the TS drift test (`__tests__/freeze.test.ts`) and the adapter's
+ * version-negotiation handshake pin this exact value. A frame whose
+ * `protocol_version` differs from this is rejected with an `error` frame.
+ */
+export const GATEWAY_RPC_PROTOCOL_VERSION = '1.0.0';
+/**
+ * Default base name for the RPC unix-socket channel.
+ *
+ * Callers resolve the concrete socket path under the CLEO home (e.g.
+ * `<cleoHome>/<basename>.sock`); the adapter itself takes the resolved path so
+ * the runtime stays free of any `@cleocode/paths` dependency. Mirrors
+ * {@link SUPERVISOR_IPC_CHANNEL_BASENAME} from the supervisor-ipc contract.
+ */
+export const GATEWAY_RPC_CHANNEL_BASENAME = 'cleo-gateway-rpc';
+//# sourceMappingURL=version.js.map

package/dist/gateway/rpc/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/gateway/rpc/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAgB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,kBAA2B,CAAC"}

package/dist/gateway.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Gateway contract — the transport-agnostic CQRS dispatch shapes.
+ *
+ * Every operation flows through:
+ *   GatewayRequest → Middleware → DomainHandler → GatewayResponse
+ *
+ * These shapes were promoted verbatim from `packages/cleo/src/dispatch/types.ts`
+ * into `@cleocode/contracts/gateway` (R3-T2 · T11446 · SG-RUNTIME-UNIFICATION)
+ * so that EVERY transport adapter — CLI, MCP, RPC, HTTP — shares one canonical,
+ * zod-validated contract instead of the CLI owning a private copy. The CLI was
+ * the only historical transport (`Source = 'cli'`); {@link GatewaySource} now
+ * widens that to the four planned transports.
+ *
+ * Design: the zod schemas are the single source of truth (AC8 — runtime
+ * validation at untrusted transport boundaries such as MCP/RPC/HTTP). The TS
+ * types are derived via {@link https://zod.dev | z.infer}, so the static and
+ * runtime contracts can never drift. The behavioral contracts that zod cannot
+ * model (function types: {@link DomainHandler}, {@link Middleware},
+ * {@link DispatchNext}) remain TS-only and reference the inferred data types.
+ *
+ * @epic T4820
+ * @task T11446
+ * @saga T11243
+ */
+import type { LAFSPage, MVILevel } from '@cleocode/lafs';
+import { z } from 'zod';
+import type { CanonicalDomain, Gateway, Tier } from './dispatch/identity.js';
+import type { ProblemDetails } from './engine-result.js';
+export { CANONICAL_DOMAINS } from './dispatch/identity.js';
+export type { CanonicalDomain, Gateway, Tier };
+/**
+ * Frozen version of the gateway contract. Bump on any breaking change to the
+ * request/response/error shapes; the freeze + spec are owned by R3-T8 (T11452).
+ */
+export declare const GATEWAY_CONTRACT_VERSION: "1.0.0";
+/** The four canonical transports a gateway request can originate from. */
+export declare const GATEWAY_SOURCES: readonly ["cli", "mcp", "rpc", "http"];
+/** Where a gateway request originated. Widened from the historical CLI-only `'cli'`. */
+export declare const gatewaySourceSchema: z.ZodEnum<{
+    http: "http";
+    cli: "cli";
+    mcp: "mcp";
+    rpc: "rpc";
+}>;
+/** Where a gateway request originated. */
+export type GatewaySource = z.infer<typeof gatewaySourceSchema>;
+/**
+ * @deprecated Use {@link GatewaySource}. Retained as a structural alias so the
+ * historical `import type { Source }` sites keep compiling unchanged.
+ */
+export type Source = GatewaySource;
+/**
+ * Canonical request shape produced by every transport adapter. The dispatcher
+ * validates this against the OperationRegistry before passing it through the
+ * middleware pipeline and into a {@link DomainHandler}.
+ */
+export declare const dispatchRequestSchema: z.ZodObject<{
+    gateway: z.ZodCustom<Gateway, Gateway>;
+    domain: z.ZodString;
+    operation: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    source: z.ZodEnum<{
+        http: "http";
+        cli: "cli";
+        mcp: "mcp";
+        rpc: "rpc";
+    }>;
+    requestId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    originSessionId: z.ZodOptional<z.ZodString>;
+    executionSessionId: z.ZodOptional<z.ZodString>;
+    _fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    _mvi: z.ZodOptional<z.ZodCustom<MVILevel, MVILevel>>;
+}, z.core.$strip>;
+/** {@inheritDoc dispatchRequestSchema} */
+export type DispatchRequest = z.infer<typeof dispatchRequestSchema>;
+/** Rate-limit metadata attached to every response. */
+export declare const rateLimitMetaSchema: z.ZodObject<{
+    limit: z.ZodNumber;
+    remaining: z.ZodNumber;
+    resetMs: z.ZodNumber;
+    category: z.ZodString;
+}, z.core.$strip>;
+/** {@inheritDoc rateLimitMetaSchema} */
+export type RateLimitMeta = z.infer<typeof rateLimitMetaSchema>;
+/** Structured error shape (LAFS-compatible). */
+export declare const dispatchErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    fix: z.ZodOptional<z.ZodString>;
+    alternatives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        command: z.ZodString;
+    }, z.core.$strip>>>;
+    problemDetails: z.ZodOptional<z.ZodCustom<ProblemDetails, ProblemDetails>>;
+}, z.core.$strip>;
+/** {@inheritDoc dispatchErrorSchema} */
+export type DispatchError = z.infer<typeof dispatchErrorSchema>;
+/**
+ * Always-present metadata block on every {@link DispatchResponse}.
+ *
+ * The catch-all (`[key: string]: unknown`) makes this assignable to
+ * `Record<string, unknown>` in covariant positions, eliminating the T9767
+ * cast-chain anti-pattern at every responseMeta call site.
+ *
+ * @task T9767
+ */
+export declare const dispatchResponseMetaSchema: z.ZodObject<{
+    gateway: z.ZodCustom<Gateway, Gateway>;
+    domain: z.ZodString;
+    operation: z.ZodString;
+    timestamp: z.ZodString;
+    duration_ms: z.ZodNumber;
+    source: z.ZodEnum<{
+        http: "http";
+        cli: "cli";
+        mcp: "mcp";
+        rpc: "rpc";
+    }>;
+    requestId: z.ZodString;
+    rateLimit: z.ZodOptional<z.ZodObject<{
+        limit: z.ZodNumber;
+        remaining: z.ZodNumber;
+        resetMs: z.ZodNumber;
+        category: z.ZodString;
+    }, z.core.$strip>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    originSessionId: z.ZodOptional<z.ZodString>;
+    executionSessionId: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodUnknown>>;
+/** {@inheritDoc dispatchResponseMetaSchema} */
+export type DispatchResponseMeta = z.infer<typeof dispatchResponseMetaSchema>;
+/**
+ * Canonical response shape returned by the dispatcher. The CLI adapter
+ * translates this into cliOutput() / cliError() + process.exit(); other
+ * transports serialize it onto their wire.
+ */
+export declare const dispatchResponseSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        gateway: z.ZodCustom<Gateway, Gateway>;
+        domain: z.ZodString;
+        operation: z.ZodString;
+        timestamp: z.ZodString;
+        duration_ms: z.ZodNumber;
+        source: z.ZodEnum<{
+            http: "http";
+            cli: "cli";
+            mcp: "mcp";
+            rpc: "rpc";
+        }>;
+        requestId: z.ZodString;
+        rateLimit: z.ZodOptional<z.ZodObject<{
+            limit: z.ZodNumber;
+            remaining: z.ZodNumber;
+            resetMs: z.ZodNumber;
+            category: z.ZodString;
+        }, z.core.$strip>>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        originSessionId: z.ZodOptional<z.ZodString>;
+        executionSessionId: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>;
+    success: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodUnknown>;
+    page: z.ZodOptional<z.ZodCustom<LAFSPage, LAFSPage>>;
+    partial: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        fix: z.ZodOptional<z.ZodString>;
+        alternatives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            action: z.ZodString;
+            command: z.ZodString;
+        }, z.core.$strip>>>;
+        problemDetails: z.ZodOptional<z.ZodCustom<ProblemDetails, ProblemDetails>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** {@inheritDoc dispatchResponseSchema} */
+export type DispatchResponse = z.infer<typeof dispatchResponseSchema>;
+/**
+ * A single frame emitted by a streaming gateway operation. Unary transports
+ * (CLI) never see these; streaming transports (Studio SSE, RPC server-push)
+ * emit a sequence terminated by a `done` or `error` event.
+ */
+export declare const gatewayStreamEventSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        error: "error";
+        done: "done";
+        data: "data";
+    }>;
+    seq: z.ZodNumber;
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        fix: z.ZodOptional<z.ZodString>;
+        alternatives: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            action: z.ZodString;
+            command: z.ZodString;
+        }, z.core.$strip>>>;
+        problemDetails: z.ZodOptional<z.ZodCustom<ProblemDetails, ProblemDetails>>;
+    }, z.core.$strip>>;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+/** {@inheritDoc gatewayStreamEventSchema} */
+export type GatewayStreamEvent = z.infer<typeof gatewayStreamEventSchema>;
+/**
+ * Contract for domain handlers.
+ *
+ * Each canonical domain (tasks, session, memory, check, pipeline, orchestrate,
+ * tools, admin, nexus, sticky, intelligence) implements this interface.
+ */
+export interface DomainHandler {
+    /** Execute a read-only query operation. */
+    query(operation: string, params?: Record<string, unknown>): Promise<DispatchResponse>;
+    /** Execute a state-modifying mutation operation. */
+    mutate(operation: string, params?: Record<string, unknown>): Promise<DispatchResponse>;
+    /** Declared operations for introspection and validation. */
+    getSupportedOperations(): {
+        query: string[];
+        mutate: string[];
+    };
+}
+/** Async continuation that produces a {@link DispatchResponse}. */
+export type DispatchNext = () => Promise<DispatchResponse>;
+/**
+ * Middleware function signature. Receives the request and a `next`
+ * continuation; can short-circuit (e.g. rate-limit exceeded) or modify the
+ * request/response.
+ */
+export type Middleware = (request: DispatchRequest, next: DispatchNext) => Promise<DispatchResponse>;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

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

package/dist/gateway.js

@@ -0,0 +1,171 @@
+/**
+ * Gateway contract — the transport-agnostic CQRS dispatch shapes.
+ *
+ * Every operation flows through:
+ *   GatewayRequest → Middleware → DomainHandler → GatewayResponse
+ *
+ * These shapes were promoted verbatim from `packages/cleo/src/dispatch/types.ts`
+ * into `@cleocode/contracts/gateway` (R3-T2 · T11446 · SG-RUNTIME-UNIFICATION)
+ * so that EVERY transport adapter — CLI, MCP, RPC, HTTP — shares one canonical,
+ * zod-validated contract instead of the CLI owning a private copy. The CLI was
+ * the only historical transport (`Source = 'cli'`); {@link GatewaySource} now
+ * widens that to the four planned transports.
+ *
+ * Design: the zod schemas are the single source of truth (AC8 — runtime
+ * validation at untrusted transport boundaries such as MCP/RPC/HTTP). The TS
+ * types are derived via {@link https://zod.dev | z.infer}, so the static and
+ * runtime contracts can never drift. The behavioral contracts that zod cannot
+ * model (function types: {@link DomainHandler}, {@link Middleware},
+ * {@link DispatchNext}) remain TS-only and reference the inferred data types.
+ *
+ * @epic T4820
+ * @task T11446
+ * @saga T11243
+ */
+import { isMVILevel } from '@cleocode/lafs';
+import { z } from 'zod';
+export { CANONICAL_DOMAINS } from './dispatch/identity.js';
+/**
+ * Frozen version of the gateway contract. Bump on any breaking change to the
+ * request/response/error shapes; the freeze + spec are owned by R3-T8 (T11452).
+ */
+export const GATEWAY_CONTRACT_VERSION = '1.0.0';
+// ---------------------------------------------------------------------------
+// GatewaySource — transport of origin
+// ---------------------------------------------------------------------------
+/** The four canonical transports a gateway request can originate from. */
+export const GATEWAY_SOURCES = ['cli', 'mcp', 'rpc', 'http'];
+/** Where a gateway request originated. Widened from the historical CLI-only `'cli'`. */
+export const gatewaySourceSchema = z.enum(GATEWAY_SOURCES);
+// ---------------------------------------------------------------------------
+// Foreign-type bridges (kept opaque to avoid re-deriving lafs/contracts schemas)
+// ---------------------------------------------------------------------------
+/** MVI verbosity level — validated through lafs's own {@link isMVILevel} guard (DRY SoT). */
+const mviLevelSchema = z.custom((v) => isMVILevel(v));
+/** LAFS pagination envelope — produced internally; carried opaquely across transports. */
+const lafsPageSchema = z.custom();
+/** RFC 9457 Problem Details — produced internally from CleoError.toProblemDetails(). */
+const problemDetailsSchema = z.custom();
+// ---------------------------------------------------------------------------
+// DispatchRequest
+// ---------------------------------------------------------------------------
+/**
+ * Canonical request shape produced by every transport adapter. The dispatcher
+ * validates this against the OperationRegistry before passing it through the
+ * middleware pipeline and into a {@link DomainHandler}.
+ */
+export const dispatchRequestSchema = z.object({
+    /** CQRS gateway (command/query). */
+    gateway: z.custom(),
+    /** Target domain (canonical name). */
+    domain: z.string(),
+    /** Domain-specific operation name. */
+    operation: z.string(),
+    /** Operation parameters (already sanitized by middleware). */
+    params: z.record(z.string(), z.unknown()).optional(),
+    /** Which transport this request came from. */
+    source: gatewaySourceSchema,
+    /** Unique request identifier for tracing. */
+    requestId: z.string(),
+    /** Bound session ID, if any. */
+    sessionId: z.string().optional(),
+    /** Root session that originated the workflow/saga, if any. */
+    originSessionId: z.string().optional(),
+    /** Specific execution instance for this command/step, if any. */
+    executionSessionId: z.string().optional(),
+    /** LAFS field selection: filter response data to these fields only. */
+    _fields: z.array(z.string()).optional(),
+    /** LAFS envelope verbosity. Defaults to 'standard'. 'custom' is server-set via _fields. */
+    _mvi: mviLevelSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// DispatchResponse + supporting shapes
+// ---------------------------------------------------------------------------
+/** Rate-limit metadata attached to every response. */
+export const rateLimitMetaSchema = z.object({
+    limit: z.number(),
+    remaining: z.number(),
+    resetMs: z.number(),
+    category: z.string(),
+});
+/** Structured error shape (LAFS-compatible). */
+export const dispatchErrorSchema = z.object({
+    /** Machine-readable error code (E_NOT_FOUND, E_VALIDATION_FAILED, …). */
+    code: z.string(),
+    /** LAFS exit code (1-99). */
+    exitCode: z.number().optional(),
+    /** Human-readable message. */
+    message: z.string(),
+    /** Additional structured details. */
+    details: z.record(z.string(), z.unknown()).optional(),
+    /** Copy-paste fix command. */
+    fix: z.string().optional(),
+    /** Alternative actions the caller can try. */
+    alternatives: z.array(z.object({ action: z.string(), command: z.string() })).optional(),
+    /** RFC 9457 Problem Details (populated from CleoError.toProblemDetails()). */
+    problemDetails: problemDetailsSchema.optional(),
+});
+/**
+ * Always-present metadata block on every {@link DispatchResponse}.
+ *
+ * The catch-all (`[key: string]: unknown`) makes this assignable to
+ * `Record<string, unknown>` in covariant positions, eliminating the T9767
+ * cast-chain anti-pattern at every responseMeta call site.
+ *
+ * @task T9767
+ */
+export const dispatchResponseMetaSchema = z
+    .object({
+    gateway: z.custom(),
+    domain: z.string(),
+    operation: z.string(),
+    timestamp: z.string(),
+    duration_ms: z.number(),
+    source: gatewaySourceSchema,
+    requestId: z.string(),
+    rateLimit: rateLimitMetaSchema.optional(),
+    /** Session ID that processed this request (T4959). */
+    sessionId: z.string().optional(),
+    /** Root session that originated the workflow/saga. */
+    originSessionId: z.string().optional(),
+    /** Specific execution instance for this command/step. */
+    executionSessionId: z.string().optional(),
+    /** Preserves protocol-level version for backward compat. */
+    version: z.string().optional(),
+})
+    .catchall(z.unknown());
+/**
+ * Canonical response shape returned by the dispatcher. The CLI adapter
+ * translates this into cliOutput() / cliError() + process.exit(); other
+ * transports serialize it onto their wire.
+ */
+export const dispatchResponseSchema = z.object({
+    /** Always-present metadata for every dispatch response. */
+    meta: dispatchResponseMetaSchema,
+    success: z.boolean(),
+    data: z.unknown().optional(),
+    page: lafsPageSchema.optional(),
+    partial: z.boolean().optional(),
+    error: dispatchErrorSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// GatewayStreamEvent — for streaming transports (SSE/HTTP, RPC server-push)
+// ---------------------------------------------------------------------------
+/**
+ * A single frame emitted by a streaming gateway operation. Unary transports
+ * (CLI) never see these; streaming transports (Studio SSE, RPC server-push)
+ * emit a sequence terminated by a `done` or `error` event.
+ */
+export const gatewayStreamEventSchema = z.object({
+    /** Frame kind: incremental data, terminal success, or terminal error. */
+    kind: z.enum(['data', 'done', 'error']),
+    /** Monotonic sequence number within the stream (0-based). */
+    seq: z.number(),
+    /** Payload for `data`/`done` frames. */
+    data: z.unknown().optional(),
+    /** Error detail for `error` frames. */
+    error: dispatchErrorSchema.optional(),
+    /** Correlates the stream back to its originating request. */
+    requestId: z.string(),
+});
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

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