@lostgradient/weft 0.2.0

package/dist/server/interactive-operations.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The interactively-used subset of operations that MUST carry a longer-form
+ * `description` (in addition to the mandatory `summary` that every operation
+ * has). These are the operations a human or agent reaches for directly:
+ * workflow lifecycle control, schedule CRUD, review handling, and worker
+ * control. The remaining operations (raw storage, bulk mutations, diagnostics,
+ * internal metrics) may omit `description`.
+ *
+ * This list is the single source of truth consumed by
+ * `scripts/check-catalog-completeness.ts`. Update it together with the
+ * operations it names.
+ *
+ * @module server/interactive-operations
+ */
+/** Operation names that must declare a `description`. */
+export declare const INTERACTIVE_OPERATION_NAMES: ReadonlyArray<string>;
+/** Whether the named operation must declare a longer-form `description`. */
+export declare function isInteractiveOperation(name: string): boolean;

package/dist/server/interactive-operations.js

@@ -0,0 +1,28 @@
+export const INTERACTIVE_OPERATION_NAMES = [
+  "weft.workflows.start",
+  "weft.workflows.get",
+  "weft.workflows.list",
+  "weft.workflows.signal",
+  "weft.workflows.query",
+  "weft.workflows.update",
+  "weft.workflows.cancel",
+  "weft.workflows.timeout",
+  "weft.workflows.resume",
+  "weft.workflows.replay",
+  "weft.schedules.create",
+  "weft.schedules.get",
+  "weft.schedules.list",
+  "weft.schedules.update",
+  "weft.schedules.cancel",
+  "weft.schedules.pause",
+  "weft.schedules.resume",
+  "weft.reviews.list",
+  "weft.reviews.get",
+  "weft.reviews.decision.submit",
+  "weft.workers.list",
+  "weft.workers.drain"
+];
+const INTERACTIVE_OPERATION_SET = new Set(INTERACTIVE_OPERATION_NAMES);
+export function isInteractiveOperation(name) {
+  return INTERACTIVE_OPERATION_SET.has(name);
+}

package/dist/server/json-rpc-dispatch.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Transport-neutral JSON-RPC dispatcher. Every JSON-RPC transport adapter
+ * (HTTP POST, WebSocket frame, stdio session) calls `dispatchJsonRpc`
+ * with the raw body and a dispatch context; the dispatcher parses the
+ * body, resolves each request via `executeOperation`, and produces the
+ * wire-level response shape.
+ *
+ * Track 8 design decision 13: batches dispatch SEQUENTIALLY in request
+ * order. Response order matches request order by construction —
+ * notifications are dropped from the response array, so the returned
+ * indices are the non-notification request indices.
+ *
+ * Notifications invoke the operation (for side effects) but produce no
+ * response. An all-notification batch returns `kind: 'notification-batch'`
+ * so transport adapters can translate it to HTTP 204 / no-response
+ * appropriately.
+ */
+import { type JsonRpcResponse } from './json-rpc-protocol.ts';
+import { type OperationRegistry } from './operation-catalog.ts';
+import { type TransportKind } from './operation-fault.ts';
+import { type Principal } from './principal.ts';
+export type DispatchJsonRpcContext = {
+    readonly principal: Principal;
+    readonly engine: unknown;
+    readonly transport: Extract<TransportKind, 'jsonRpcHttp' | 'jsonRpcWebSocket' | 'jsonRpcStdio'>;
+    readonly registry: OperationRegistry;
+};
+/**
+ * Result of dispatching a JSON-RPC body. Shapes:
+ *   - `single`: a single request → one response (success or error).
+ *   - `notification`: a single notification → no response.
+ *   - `batch`: a batch with at least one non-notification → an array of
+ *     responses in request order.
+ *   - `notification-batch`: a batch where every item is a notification
+ *     → no response body on the wire (HTTP 204, etc.).
+ */
+export type DispatchJsonRpcResult = {
+    readonly kind: 'single';
+    readonly response: JsonRpcResponse;
+} | {
+    readonly kind: 'notification';
+} | {
+    readonly kind: 'batch';
+    readonly responses: ReadonlyArray<JsonRpcResponse>;
+} | {
+    readonly kind: 'notification-batch';
+};
+/** Parse the raw body and dispatch each request. */
+export declare function dispatchJsonRpc(body: unknown, context: DispatchJsonRpcContext): Promise<DispatchJsonRpcResult>;

package/dist/server/json-rpc-dispatch.js

@@ -0,0 +1,92 @@
+import { listMcpTools } from "../mcp/tools.js";
+import { faultToJsonRpcError } from "./fault-to-json-rpc.js";
+import { parseJsonRpcRequest } from "./json-rpc-parse.js";
+import {
+  JSON_RPC_VERSION
+} from "./json-rpc-protocol.js";
+import { generateOpenRpcDocument } from "./openrpc.js";
+import { executeOperation } from "./operation-catalog.js";
+const DISCOVER_METHOD_NAME = "rpc.discover";
+export async function dispatchJsonRpc(body, context) {
+  const parsed = parseJsonRpcRequest(body);
+  if (parsed.kind === "parse-error")
+    return {
+      kind: "single",
+      response: {
+        jsonrpc: JSON_RPC_VERSION,
+        error: { code: parsed.code, message: parsed.message },
+        id: null
+      }
+    };
+  if (parsed.kind === "invalid-request")
+    return {
+      kind: "single",
+      response: {
+        jsonrpc: JSON_RPC_VERSION,
+        error: { code: parsed.code, message: parsed.message },
+        id: parsed.id
+      }
+    };
+  if (parsed.kind === "single") {
+    if (parsed.isNotification) {
+      await dispatchOne(parsed.request, context);
+      return { kind: "notification" };
+    }
+    return { kind: "single", response: await dispatchOne(parsed.request, context) };
+  }
+  return dispatchBatch(parsed, context);
+}
+async function dispatchBatch(parsed, context) {
+  const responses = [];
+  for (const item of parsed.items) {
+    const response = await dispatchBatchItem(item, context);
+    if (response !== void 0)
+      responses.push(response);
+  }
+  if (responses.length === 0)
+    return { kind: "notification-batch" };
+  return { kind: "batch", responses };
+}
+async function dispatchBatchItem(item, context) {
+  if (item.kind === "invalid")
+    return {
+      jsonrpc: JSON_RPC_VERSION,
+      error: { code: item.code, message: item.message },
+      id: item.id
+    };
+  if (item.isNotification) {
+    await dispatchOne(item.request, context);
+    return;
+  }
+  return dispatchOne(item.request, context);
+}
+async function dispatchOne(request, context) {
+  const id = request.id ?? null;
+  if (request.method === DISCOVER_METHOD_NAME) {
+    const mcpToolProvider = asMcpToolProvider(context.engine), document = generateOpenRpcDocument({
+      registry: context.registry,
+      transports: ["http", "websocket"],
+      ...mcpToolProvider === null ? {} : { mcpTools: listMcpTools(mcpToolProvider) }
+    });
+    return { jsonrpc: JSON_RPC_VERSION, result: document, id };
+  }
+  const result = await executeOperation(request.method, request.params ?? {}, {
+    principal: context.principal,
+    engine: context.engine,
+    transport: context.transport,
+    registry: context.registry
+  });
+  if (result.ok)
+    return { jsonrpc: JSON_RPC_VERSION, result: result.value, id };
+  const error = faultToJsonRpcError(result.fault);
+  return {
+    jsonrpc: JSON_RPC_VERSION,
+    error: { code: error.code, message: error.message, data: error.data },
+    id
+  };
+}
+function asMcpToolProvider(engine) {
+  if (engine !== null && typeof engine === "object" && "listWorkflowDefinitions" in engine && typeof engine.listWorkflowDefinitions === "function")
+    return engine;
+  return null;
+}

package/dist/server/json-rpc-framing.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared newline-delimited framing helper for JSON-RPC over stdio.
+ *
+ * The runtime stdio subcommand consumes this helper to turn newline-delimited
+ * byte chunks into complete JSON-RPC frames. Phase 6 locked in the framing
+ * contract against the original inline buffer logic; Phase 7 extracted that
+ * logic into this pure function.
+ *
+ * Contract:
+ *   - Input:  `buffer` (leftover from the previous call) + `chunk` (new
+ *             bytes decoded to string).
+ *   - Output: an array of `lines` (complete, newline-terminated, trimmed,
+ *             non-empty) plus a `buffer` to feed into the next call.
+ *   - Split:  on `\n`. `\r` is treated as surrounding whitespace and
+ *             trimmed — standard `trim()` behavior. CRLF framing works
+ *             transparently.
+ *   - Blanks: lines that are empty after `trim()` are silently dropped.
+ *             They are framing artifacts, not empty payloads — if every
+ *             caller had to filter them, eventually one would forget and
+ *             log a malformed-JSON warning on a legitimately blank frame.
+ *
+ * Pure: no I/O, no allocations beyond the returned arrays/string, no
+ * state. Safe to call from any context.
+ *
+ * **No built-in buffer bound.** A peer that never emits a newline can
+ * force the returned `buffer` to grow unboundedly across calls. The
+ * helper is deliberately primitive here — callers that cannot trust
+ * the peer (the Phase 13 runtime stdio session; any future network-
+ * facing consumer) MUST enforce their own max-frame cap and drop /
+ * fault the connection when the buffer exceeds it.
+ */
+export type FramingResult = {
+    readonly lines: ReadonlyArray<string>;
+    readonly buffer: string;
+};
+/**
+ * Append `chunk` to `buffer`, split off every complete newline-terminated
+ * frame, and return the extracted lines plus the leftover buffer.
+ *
+ * Lines are trimmed; empty lines (after trim) are dropped silently.
+ */
+export declare function splitNewlineDelimitedBuffer(buffer: string, chunk: string): FramingResult;

package/dist/server/json-rpc-framing.js

@@ -0,0 +1,15 @@
+export function splitNewlineDelimitedBuffer(buffer, chunk) {
+  let working = buffer + chunk;
+  const lines = [];
+  let newlineIndex = working.indexOf(`
+`);
+  while (newlineIndex !== -1) {
+    const line = working.slice(0, newlineIndex).trim();
+    working = working.slice(newlineIndex + 1);
+    if (line.length > 0)
+      lines.push(line);
+    newlineIndex = working.indexOf(`
+`);
+  }
+  return { lines, buffer: working };
+}

package/dist/server/json-rpc-http.d.ts

@@ -0,0 +1,33 @@
+/**
+ * POST `/jsonrpc` HTTP transport adapter.
+ *
+ * Takes an incoming `Request`, validates the method + content-type +
+ * body size, reads the body (bounded), and delegates dispatch to
+ * `dispatchJsonRpc`. Maps the dispatcher's `DispatchJsonRpcResult`
+ * onto an HTTP `Response` per JSON-RPC 2.0 spec conventions:
+ *
+ *   - single non-notification → HTTP 200 + JSON body
+ *   - single notification → HTTP 204 No Content
+ *   - batch with ≥1 response → HTTP 200 + JSON array body
+ *   - all-notification batch → HTTP 204 No Content
+ *
+ * Note: body-level errors (parse-error, invalid-request) come back in
+ * the JSON-RPC error envelope with `id: null` at HTTP 200 per spec.
+ * HTTP 4xx/5xx are reserved for transport-level concerns (wrong
+ * method, wrong content-type, body too large, server crash).
+ *
+ * The pre-read content-length guard rejects oversize bodies before
+ * allocating a buffer. The post-read size check is the backstop when
+ * the client omits content-length or lies.
+ */
+import type { OperationRegistry } from './operation-catalog.ts';
+import type { Principal } from './principal.ts';
+export type JsonRpcHttpContext = {
+    readonly registry: OperationRegistry;
+    readonly engine: unknown;
+    readonly principal: Principal;
+    /** Hard cap on request body size. Defaults to 1 MB. */
+    readonly maxBodyBytes?: number;
+};
+/** Handle a POST `/jsonrpc` request end-to-end. */
+export declare function handleJsonRpcHttpRequest(request: Request, context: JsonRpcHttpContext): Promise<Response>;

package/dist/server/json-rpc-http.js

@@ -0,0 +1,112 @@
+import { WeftError } from "../core/weft-error.js";
+import {
+  dispatchJsonRpc
+} from "./json-rpc-dispatch.js";
+const DEFAULT_MAX_BODY_BYTES = 1048576, CACHE_CONTROL_HEADERS = { "cache-control": "no-store" };
+function textResponse(body, status, extra) {
+  const headers = new Headers(extra);
+  headers.set("cache-control", "no-store");
+  return new Response(body, { status, headers });
+}
+export async function handleJsonRpcHttpRequest(request, context) {
+  const methodRejection = guardMethod(request);
+  if (methodRejection !== null)
+    return methodRejection;
+  const contentTypeRejection = guardContentType(request);
+  if (contentTypeRejection !== null)
+    return contentTypeRejection;
+  const maxBytes = context.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES, contentLengthRejection = guardContentLength(request.headers.get("content-length"), maxBytes);
+  if (contentLengthRejection !== null)
+    return contentLengthRejection;
+  let bodyBytes;
+  try {
+    bodyBytes = await readBodyBounded(request, maxBytes);
+  } catch (error) {
+    if (error instanceof RequestBodyTooLargeError)
+      return textResponse("Payload Too Large", 413);
+    return textResponse("Bad Request", 400);
+  }
+  const bodyText = new TextDecoder("utf-8").decode(bodyBytes), dispatchContext = {
+    registry: context.registry,
+    engine: context.engine,
+    principal: context.principal,
+    transport: "jsonRpcHttp"
+  }, result = await dispatchJsonRpc(bodyText, dispatchContext);
+  return dispatchResultToResponse(result);
+}
+function guardMethod(request) {
+  if (request.method === "POST")
+    return null;
+  return textResponse("Method Not Allowed", 405, { allow: "POST" });
+}
+function guardContentType(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (isJsonContentType(contentType))
+    return null;
+  return textResponse("Unsupported Media Type", 415);
+}
+function guardContentLength(header, maxBytes) {
+  if (header === null)
+    return null;
+  if (!CONTENT_LENGTH_PATTERN.test(header))
+    return textResponse("Bad Request", 400);
+  const declared = Number(header);
+  if (!Number.isSafeInteger(declared) || declared < 0)
+    return textResponse("Bad Request", 400);
+  if (declared > maxBytes)
+    return textResponse("Payload Too Large", 413);
+  return null;
+}
+function dispatchResultToResponse(result) {
+  switch (result.kind) {
+    case "notification":
+    case "notification-batch":
+      return new Response(null, { status: 204, headers: CACHE_CONTROL_HEADERS });
+    case "single":
+      return Response.json(result.response, { status: 200, headers: CACHE_CONTROL_HEADERS });
+    case "batch":
+      return Response.json(result.responses, { status: 200, headers: CACHE_CONTROL_HEADERS });
+  }
+}
+const CONTENT_LENGTH_PATTERN = /^(0|[1-9]\d*)$/;
+function isJsonContentType(contentType) {
+  const lowered = contentType.trim().toLowerCase(), [type = ""] = lowered.split(";");
+  return type.trim() === "application/json";
+}
+
+class RequestBodyTooLargeError extends WeftError {
+  constructor() {
+    super("RequestBodyTooLargeError", "body exceeds max bytes");
+  }
+}
+async function readBodyBounded(request, maxBytes) {
+  const body = request.body;
+  if (body === null)
+    return new Uint8Array(0);
+  const reader = body.getReader(), chunks = [];
+  let total = 0;
+  try {
+    while (!0) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      if (!value)
+        continue;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new RequestBodyTooLargeError;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}

package/dist/server/json-rpc-parse.d.ts

@@ -0,0 +1,69 @@
+/**
+ * JSON-RPC 2.0 request parser — accepts a raw body (string or already-
+ * parsed JSON) and returns a discriminated-union `ParseResult` that
+ * describes what the transport should dispatch.
+ *
+ * Track 8 design decisions this parser enforces:
+ *   - `params` MUST be absent or a JSON object. Array-form positional
+ *     params are rejected with `InvalidRequest` (-32600). This matches
+ *     OpenRPC's `paramStructure: "by-name"` contract and eliminates a
+ *     whole class of drift between REST (which has no positional form)
+ *     and JSON-RPC.
+ *   - `jsonrpc` MUST be the literal string `"2.0"`. No auto-upgrade
+ *     from 1.0 or 1.1.
+ *   - `method` MUST be a non-empty string. The name regex
+ *     (`validateOperationName` in `operation-catalog.ts`) is NOT
+ *     enforced here — the dispatcher treats an unknown name as
+ *     `MethodNotFound`, which is the spec's intended semantics.
+ *   - Notifications are requests with no `id` key. Explicit `id: null`
+ *     is a real request (not a notification) per spec — the parser
+ *     surfaces this via `isNotification: false`.
+ *
+ * The result is transport-neutral: HTTP POST, WebSocket frames, and
+ * stdio sessions all consume the same `ParseResult`.
+ */
+import { JSON_RPC_ERROR_CODES, type JsonRpcId, type JsonRpcRequest } from './json-rpc-protocol.ts';
+/**
+ * A request body that has been parsed successfully. Either a single
+ * request, a batch of per-item parse results, or a body-level error.
+ */
+export type ParseResult = {
+    readonly kind: 'parse-error';
+    readonly code: typeof JSON_RPC_ERROR_CODES.PARSE_ERROR;
+    readonly message: string;
+} | {
+    readonly kind: 'invalid-request';
+    readonly code: typeof JSON_RPC_ERROR_CODES.INVALID_REQUEST;
+    readonly message: string;
+    readonly id: JsonRpcId;
+} | {
+    readonly kind: 'single';
+    readonly request: JsonRpcRequest;
+    readonly isNotification: boolean;
+} | {
+    readonly kind: 'batch';
+    readonly items: ReadonlyArray<ParsedBatchItem>;
+};
+export type ParsedBatchItem = {
+    readonly kind: 'valid';
+    readonly request: JsonRpcRequest;
+    readonly isNotification: boolean;
+} | {
+    readonly kind: 'invalid';
+    readonly code: typeof JSON_RPC_ERROR_CODES.INVALID_REQUEST;
+    readonly message: string;
+    readonly id: JsonRpcId;
+};
+/**
+ * Parse a raw body into a transport-neutral `ParseResult`. Accepts
+ * either a string (will be JSON.parse'd) or an already-parsed value.
+ */
+/**
+ * Hard upper bound on batch size. A well-behaved client will stay well
+ * below this; the limit exists to make a hostile client's first attempt
+ * at memory/CPU exhaustion cheap to fail. Transport adapters (Phase 11
+ * HTTP, Phase 12 WebSocket, Phase 13 stdio) SHOULD enforce their own
+ * body/frame byte limits in addition to this item cap.
+ */
+export declare const MAX_JSON_RPC_BATCH_ITEMS = 100;
+export declare function parseJsonRpcRequest(body: unknown): ParseResult;

package/dist/server/json-rpc-parse.js

@@ -0,0 +1,139 @@
+import {
+  JSON_RPC_ERROR_CODES,
+  JSON_RPC_VERSION,
+  isValidJsonRpcId
+} from "./json-rpc-protocol.js";
+import { isPlainObject } from "./json-schema-utilities.js";
+export const MAX_JSON_RPC_BATCH_ITEMS = 100;
+export function parseJsonRpcRequest(body) {
+  let parsed;
+  if (typeof body === "string")
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      return {
+        kind: "parse-error",
+        code: JSON_RPC_ERROR_CODES.PARSE_ERROR,
+        message: "Parse error"
+      };
+    }
+  else
+    parsed = body;
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 0)
+      return {
+        kind: "invalid-request",
+        code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+        message: "Invalid Request",
+        id: null
+      };
+    if (parsed.length > MAX_JSON_RPC_BATCH_ITEMS)
+      return {
+        kind: "invalid-request",
+        code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+        message: `Invalid Request: batch size ${parsed.length} exceeds limit ${MAX_JSON_RPC_BATCH_ITEMS}`,
+        id: null
+      };
+    return {
+      kind: "batch",
+      items: parsed.map(parseBatchItem)
+    };
+  }
+  if (!isPlainObject(parsed))
+    return {
+      kind: "invalid-request",
+      code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+      message: "Request must be a JSON object or batch array",
+      id: null
+    };
+  return parseSingleObject(parsed);
+}
+function parseBatchItem(item) {
+  if (!isPlainObject(item))
+    return {
+      kind: "invalid",
+      code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+      message: "Batch item must be a JSON object",
+      id: null
+    };
+  const result = parseSingleObject(item);
+  if (result.kind === "single")
+    return { kind: "valid", request: result.request, isNotification: result.isNotification };
+  return {
+    kind: "invalid",
+    code: result.code,
+    message: result.message,
+    id: result.id
+  };
+}
+function parseSingleObject(object) {
+  const rawId = object.id, hasIdKey = "id" in object, idForError = isValidJsonRpcId(rawId) ? rawId : null, versionRejection = checkJsonRpcVersion(object, idForError);
+  if (versionRejection !== null)
+    return versionRejection;
+  const method = object.method, methodRejection = checkMethodField(method, idForError);
+  if (methodRejection !== null)
+    return methodRejection;
+  const paramsRejection = checkParamsField(object, idForError);
+  if (paramsRejection !== null)
+    return paramsRejection;
+  const idRejection = checkIdField(rawId, hasIdKey);
+  if (idRejection !== null)
+    return idRejection;
+  const isNotification = !hasIdKey, params = "params" in object ? object.params : void 0;
+  return { kind: "single", request: {
+    jsonrpc: JSON_RPC_VERSION,
+    method,
+    ...params === void 0 ? {} : { params },
+    ...hasIdKey ? { id: rawId } : {}
+  }, isNotification };
+}
+function checkJsonRpcVersion(object, idForError) {
+  if (object.jsonrpc === JSON_RPC_VERSION)
+    return null;
+  return {
+    kind: "invalid-request",
+    code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+    message: `jsonrpc field must be exactly "${JSON_RPC_VERSION}"`,
+    id: idForError
+  };
+}
+function checkMethodField(method, idForError) {
+  if (typeof method === "string" && method.length > 0)
+    return null;
+  return {
+    kind: "invalid-request",
+    code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+    message: "method field must be a non-empty string",
+    id: idForError
+  };
+}
+function checkParamsField(object, idForError) {
+  if (!("params" in object))
+    return null;
+  const rawParams = object.params;
+  if (Array.isArray(rawParams))
+    return {
+      kind: "invalid-request",
+      code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+      message: "positional params are not supported; use named params (params must be a JSON object)",
+      id: idForError
+    };
+  if (!isPlainObject(rawParams))
+    return {
+      kind: "invalid-request",
+      code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+      message: "params must be a JSON object (named params) or absent",
+      id: idForError
+    };
+  return null;
+}
+function checkIdField(rawId, hasIdKey) {
+  if (!hasIdKey || isValidJsonRpcId(rawId))
+    return null;
+  return {
+    kind: "invalid-request",
+    code: JSON_RPC_ERROR_CODES.INVALID_REQUEST,
+    message: "id must be a string, finite number, or null",
+    id: null
+  };
+}

package/dist/server/json-rpc-protocol.d.ts

@@ -0,0 +1,76 @@
+/**
+ * JSON-RPC 2.0 protocol constants and shared types.
+ *
+ * Single source of truth for the wire-level representation every
+ * JSON-RPC transport in this codebase consumes:
+ *   - Parse helpers (`json-rpc-parse.ts`, Phase 8)
+ *   - Dispatcher (`json-rpc-dispatch.ts`, Phase 8)
+ *   - HTTP adapter (`json-rpc-http.ts`, Phase 11)
+ *   - WebSocket adapter (`json-rpc-websocket.ts`, Phase 12)
+ *   - Runtime stdio session (`stdio-session.ts`, Phase 13)
+ *
+ * Reserved-spec error codes (-32700..-32603) keep their JSON-RPC 2.0
+ * meanings. Weft domain codes live in the -32010..-32099 band per
+ * Track 8 design decision 4.
+ */
+/** Literal `"2.0"` — the only `jsonrpc` version this runtime accepts. */
+export declare const JSON_RPC_VERSION: "2.0";
+export type JsonRpcVersion = typeof JSON_RPC_VERSION;
+/**
+ * Error codes carried on the wire in `JsonRpcError.code`.
+ *
+ * Reserved band (-32700..-32603) — JSON-RPC 2.0 spec.
+ * Weft domain band (-32010..-32099) — see `OperationFault` +
+ *   `fault-to-json-rpc.ts` for the mapping to `FaultCode`.
+ */
+export declare const JSON_RPC_ERROR_CODES: Readonly<{
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly UNAUTHORIZED: -32010;
+    readonly FORBIDDEN: -32011;
+    readonly NOT_FOUND: -32020;
+    readonly CONFLICT: -32021;
+    readonly UNPROCESSABLE: -32022;
+    readonly TIMEOUT: -32023;
+    readonly RATE_LIMITED: -32024;
+    readonly NOT_IMPLEMENTED: -32025;
+    readonly UNSUPPORTED_TRANSPORT: -32030;
+    readonly SUBSCRIPTION_OVERFLOW: -32031;
+    readonly ENGINE_FAILURE: -32099;
+}>;
+export type JsonRpcErrorCode = (typeof JSON_RPC_ERROR_CODES)[keyof typeof JSON_RPC_ERROR_CODES];
+/**
+ * A JSON-RPC request id. The spec allows string, number, or null.
+ * `null` is only valid when returned in error responses for requests
+ * whose id could not be parsed.
+ */
+export type JsonRpcId = string | number | null;
+/** Total runtime guard for `JsonRpcId`. Rejects NaN, Infinity, booleans, objects. */
+export declare function isValidJsonRpcId(value: unknown): value is JsonRpcId;
+/** Raw JSON-RPC request shape (pre-parse, as it arrives on the wire). */
+export type JsonRpcRequest = {
+    readonly jsonrpc: JsonRpcVersion;
+    readonly method: string;
+    readonly params?: Record<string, unknown> | undefined;
+    readonly id?: JsonRpcId | undefined;
+};
+/** JSON-RPC success response. */
+export type JsonRpcSuccessResponse = {
+    readonly jsonrpc: JsonRpcVersion;
+    readonly result: unknown;
+    readonly id: JsonRpcId;
+};
+/** JSON-RPC error response. */
+export type JsonRpcErrorResponse = {
+    readonly jsonrpc: JsonRpcVersion;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    };
+    readonly id: JsonRpcId;
+};
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;