stitchkit 0.54.0 → 0.56.0

package/dist/testing.js

@@ -1,9 +1,702 @@
+import {
+  RealtimeRequestDisconnectedError,
+  RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestTimeoutError
+} from "./index-557by2db.js";
+import {
+  mcpProjectionCandidate,
+  prepareProjectedMcpTools,
+  projectToolSurface
+} from "./index-6y759j86.js";
+import {
+  toJsonSchema
+} from "./index-cby4ar3v.js";
 import {
   createClient,
   createClients
-} from "./index-e1es808r.js";
+} from "./index-qh4xevf5.js";
 import"./index-48ffdxgk.js";
-import"./index-bmnhqtya.js";
+import {
+  isRecord
+} from "./index-7eq9va6e.js";
+import"./index-1bx83sw4.js";
+
+// src/testing/surface-conformance.ts
+import { z as z2 } from "zod";
+
+// src/testing/surface-manifest.ts
+import { createHash } from "node:crypto";
+import { z } from "zod";
+var HttpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var ToolTransportSchema = z.enum(["MCP", "AGENT", "CLI"]);
+var SurfaceTransportSchema = z.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
+var SurfaceSchemaDigestsSchema = z.object({
+  params: z.string().nullable(),
+  input: z.string().nullable(),
+  output: z.string().nullable(),
+  multipart: z.string().nullable()
+});
+var SurfaceManifestOperationSchema = z.object({
+  kind: z.enum(["contract", "runtime"]),
+  service: z.string(),
+  action: z.string(),
+  method: HttpMethodSchema,
+  scope: z.string().nullable(),
+  description: z.string(),
+  schemas: SurfaceSchemaDigestsSchema,
+  http: z.array(z.object({ method: HttpMethodSchema, path: z.string() }))
+});
+var SurfaceManifestToolSchema = z.object({
+  kind: z.enum(["contract", "runtime"]),
+  service: z.string(),
+  action: z.string(),
+  name: z.string(),
+  input: z.string()
+});
+var SurfaceManifestToolSurfaceSchema = z.object({
+  transport: ToolTransportSchema,
+  surface: z.string().nullable(),
+  tools: z.array(SurfaceManifestToolSchema)
+});
+var SurfaceManifestCliCommandSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  input: z.string(),
+  output: z.string().nullable()
+});
+var SurfaceManifestExtensionSchema = z.object({
+  name: z.string(),
+  transport: SurfaceTransportSchema
+});
+var SurfaceRealtimeSchemaPairSchema = z.object({
+  input: z.string(),
+  output: z.string()
+});
+var SurfaceManifestRealtimeEventSchema = z.object({
+  contract: z.string(),
+  direction: z.enum(["serverToClient", "clientToServer"]),
+  event: z.string(),
+  args: SurfaceRealtimeSchemaPairSchema,
+  acknowledgement: SurfaceRealtimeSchemaPairSchema.nullable()
+});
+var SurfaceManifestSchema = z.object({
+  manifestVersion: z.literal(2),
+  digestVersion: z.literal(1),
+  operations: z.array(SurfaceManifestOperationSchema),
+  toolSurfaces: z.array(SurfaceManifestToolSurfaceSchema),
+  realtimeContracts: z.array(z.string()),
+  realtime: z.array(SurfaceManifestRealtimeEventSchema),
+  cliOnly: z.array(SurfaceManifestCliCommandSchema),
+  extensions: z.array(SurfaceManifestExtensionSchema)
+});
+function compareCodepoints(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function canonicalValue(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalValue);
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalValue(value[key]);
+  }
+  return result;
+}
+function serializeSurfaceValue(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+function digestValue(value) {
+  return createHash("sha256").update(serializeSurfaceValue(value)).digest("hex").slice(0, 16);
+}
+function canonicalSchemaValue(value, parentKey) {
+  if (Array.isArray(value)) {
+    const entries = value.map((entry) => canonicalSchemaValue(entry));
+    return parentKey === "required" && entries.every((entry) => typeof entry === "string") ? entries.sort((left, right) => compareCodepoints(String(left), String(right))) : entries;
+  }
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalSchemaValue(value[key], key);
+  }
+  return result;
+}
+function schemaDigest(schema, io) {
+  if (!schema)
+    return null;
+  return digestValue(canonicalSchemaValue(toJsonSchema(schema, io, "any")));
+}
+function presentationDigest(schema) {
+  return digestValue(canonicalSchemaValue(schema));
+}
+function multipartDigest(value) {
+  return value === undefined ? null : digestValue(value);
+}
+function joinPath(...parts) {
+  const joined = parts.filter((part) => Boolean(part)).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+  return `/${joined}`;
+}
+function operationKey(kind, service, action) {
+  return `${kind}\x00${service}\x00${action}`;
+}
+function operationFrom(kind, source) {
+  return {
+    kind,
+    service: source.serviceName,
+    action: source.key,
+    method: source.method,
+    scope: source.scope ?? null,
+    description: source.desc,
+    schemas: {
+      params: schemaDigest(source.paramsSchema, "input"),
+      input: schemaDigest(source.inputSchema, "input"),
+      output: schemaDigest(source.outputSchema, "output"),
+      multipart: multipartDigest(source.multipart)
+    },
+    http: []
+  };
+}
+function operationFingerprint(source) {
+  const mcp = source.mcp ? {
+    inputRequired: source.mcp.inputRequired.map((request) => ({
+      key: request.key,
+      message: request.message,
+      schema: schemaDigest(request.schema, "input")
+    }))
+  } : null;
+  return serializeSurfaceValue({
+    method: source.method,
+    serviceName: source.serviceName,
+    key: source.key,
+    desc: source.desc,
+    scope: source.scope ?? null,
+    path: source.path ?? null,
+    expose: source.expose ? [...source.expose].sort(compareCodepoints) : null,
+    toolName: source.toolName ?? null,
+    annotations: source.annotations ?? null,
+    ui: source.ui ?? null,
+    mcp,
+    rawBody: source.rawBody ?? false,
+    rawResponse: source.rawResponse ?? false,
+    responseMeta: source.responseMeta ?? null,
+    maxJsonBodyBytes: source.maxJsonBodyBytes ?? null,
+    idempotent: source.idempotent ?? false,
+    contentType: source.contentType ?? null,
+    meta: source.meta ?? null,
+    schemas: {
+      params: schemaDigest(source.paramsSchema, "input"),
+      input: schemaDigest(source.inputSchema, "input"),
+      output: schemaDigest(source.outputSchema, "output"),
+      multipart: multipartDigest(source.multipart)
+    }
+  });
+}
+function sortTools(tools) {
+  return tools.sort((left, right) => compareCodepoints(left.name, right.name) || compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind));
+}
+function buildSurfaceManifest(config) {
+  const operations = new Map;
+  const operationFingerprints = new Map;
+  const operationDefinitions = new Map;
+  const addOperation = (kind, source) => {
+    const candidate = operationFrom(kind, source);
+    const key = operationKey(kind, candidate.service, candidate.action);
+    const definition = source.definitionToken ?? source;
+    const existing = operations.get(key);
+    if (!existing) {
+      operations.set(key, candidate);
+      operationFingerprints.set(key, operationFingerprint(source));
+      operationDefinitions.set(key, definition);
+      return candidate;
+    }
+    if (operationDefinitions.get(key) !== definition || operationFingerprints.get(key) !== operationFingerprint(source)) {
+      throw new Error(`Conflicting ${kind} operation identity ${candidate.service}.${candidate.action}`);
+    }
+    return existing;
+  };
+  const addHttp = (service, prefix) => {
+    for (const method of Object.values(service.methods)) {
+      const operation = addOperation("contract", method);
+      if (method.expose && !method.expose.includes("HTTP"))
+        continue;
+      const route = {
+        method: method.method,
+        path: joinPath(prefix, service.prefix, method.path)
+      };
+      if (!operation.http.some((entry) => entry.method === route.method && entry.path === route.path)) {
+        operation.http.push(route);
+      }
+    }
+  };
+  for (const service of config.services ?? []) {
+    addHttp(service, config.scopePrefixes?.[service.scope] ?? "");
+  }
+  for (const group of config.groups ?? []) {
+    for (const service of group.services)
+      addHttp(service, group.pathPrefix ?? "");
+  }
+  const toolSurfaces = [];
+  const addToolProjection = (transport, surface, projection, presentation = {}) => {
+    const projected = projectToolSurface(projection, transport, transport === "MCP" ? config.mcpPreparation ?? {} : presentation);
+    const collected = transport === "MCP" ? prepareProjectedMcpTools(projected.map(mcpProjectionCandidate), config.mcpPreparation ?? {}).map((prepared) => ({
+      ...prepared.tool,
+      presentationSchema: prepared.inputSchema
+    })) : projected;
+    const tools = [];
+    for (const entry of collected) {
+      const source = entry.kind === "contract" ? entry.source : {
+        definitionToken: entry.source,
+        method: entry.source.identity.method,
+        serviceName: entry.source.identity.serviceName,
+        key: entry.source.identity.action,
+        desc: entry.source.description,
+        ...entry.source.identity.scope !== undefined && {
+          scope: entry.source.identity.scope
+        },
+        inputSchema: entry.source.input,
+        ...entry.source.output !== undefined && {
+          outputSchema: entry.source.output
+        },
+        toolName: entry.source.name,
+        expose: entry.source.transports,
+        ...entry.source.annotations !== undefined && {
+          annotations: entry.source.annotations
+        },
+        ...entry.source.ui !== undefined && { ui: entry.source.ui },
+        ...entry.source.identity.meta !== undefined && {
+          meta: entry.source.identity.meta
+        },
+        ...entry.source.mcp !== undefined && { mcp: entry.source.mcp }
+      };
+      const operation = addOperation(entry.kind, source);
+      tools.push({
+        kind: entry.kind,
+        service: operation.service,
+        action: operation.action,
+        name: entry.name,
+        input: presentationDigest(entry.presentationSchema)
+      });
+    }
+    toolSurfaces.push({ transport, surface, tools: sortTools(tools) });
+  };
+  const shared = {
+    services: config.services,
+    runtimeTools: config.runtimeTools
+  };
+  const explicitMcp = config.toolSurfaces?.MCP;
+  const namedMcp = config.mcpSurfaces;
+  if (explicitMcp && namedMcp) {
+    throw new Error("Surface manifest MCP topology must use either one direct surface or named surfaces");
+  }
+  if (explicitMcp)
+    addToolProjection("MCP", null, explicitMcp);
+  if (namedMcp) {
+    for (const name of Object.keys(namedMcp).sort(compareCodepoints)) {
+      const projection = namedMcp[name];
+      if (projection)
+        addToolProjection("MCP", name, projection);
+    }
+  }
+  if (!explicitMcp && !namedMcp)
+    addToolProjection("MCP", null, shared);
+  const agent = config.toolSurfaces?.AGENT;
+  addToolProjection("AGENT", null, agent ?? shared, agent ?? {});
+  addToolProjection("CLI", null, config.toolSurfaces?.CLI ?? shared);
+  const realtime = [];
+  const realtimeContracts = Object.keys(config.realtime ?? {}).sort(compareCodepoints);
+  for (const contractName of realtimeContracts) {
+    const contract = config.realtime?.[contractName];
+    if (!contract)
+      continue;
+    for (const direction of ["serverToClient", "clientToServer"]) {
+      const registry = contract[direction];
+      for (const event of Object.keys(registry).sort(compareCodepoints)) {
+        const definition = registry[event];
+        if (!definition)
+          continue;
+        const argsInput = schemaDigest(definition.args, "input");
+        const argsOutput = schemaDigest(definition.args, "output");
+        if (!argsInput || !argsOutput)
+          throw new Error("Realtime args schema digest missing");
+        let acknowledgement = null;
+        if (definition.ack) {
+          const input = schemaDigest(definition.ack, "input");
+          const output = schemaDigest(definition.ack, "output");
+          if (!input || !output)
+            throw new Error("Realtime ack schema digest missing");
+          acknowledgement = { input, output };
+        }
+        realtime.push({
+          contract: contractName,
+          direction,
+          event,
+          args: { input: argsInput, output: argsOutput },
+          acknowledgement
+        });
+      }
+    }
+  }
+  const cliOnly = (config.cliCommands ?? []).map((command) => ({
+    name: command.name,
+    description: command.description,
+    input: schemaDigest(command.input, "input") ?? digestValue({}),
+    output: schemaDigest(command.output, "output")
+  })).sort((left, right) => compareCodepoints(left.name, right.name));
+  for (const operation of operations.values()) {
+    operation.http.sort((left, right) => compareCodepoints(left.path, right.path) || compareCodepoints(left.method, right.method));
+  }
+  return SurfaceManifestSchema.parse({
+    manifestVersion: 2,
+    digestVersion: 1,
+    operations: [...operations.values()].sort((left, right) => compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind)),
+    toolSurfaces: toolSurfaces.sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.surface ?? "", right.surface ?? "")),
+    realtimeContracts,
+    realtime,
+    cliOnly,
+    extensions: [...config.extensions ?? []].sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.name, right.name))
+  });
+}
+function assertSurfaceManifestSnapshot(manifest, snapshot) {
+  const actual = serializeSurfaceValue(SurfaceManifestSchema.parse(manifest));
+  const expected = serializeSurfaceValue(SurfaceManifestSchema.parse(snapshot));
+  if (actual !== expected) {
+    throw new Error(`Surface manifest diverged from its committed snapshot
+expected: ${expected}
+actual: ${actual}`);
+  }
+}
+
+// src/testing/surface-conformance.ts
+var RealtimeRejectionObservationSchema = z2.object({
+  direction: z2.enum([
+    "client-inbound",
+    "client-outbound",
+    "server-inbound",
+    "server-outbound"
+  ]),
+  phase: z2.enum(["arguments", "acknowledgement"]),
+  reason: z2.enum([
+    "unknown-event",
+    "invalid-arguments",
+    "invalid-acknowledgement-value",
+    "missing-acknowledgement"
+  ]),
+  fault: z2.enum(["peer", "local"])
+});
+var ObservationFields = {
+  code: z2.string().optional(),
+  data: z2.unknown().optional(),
+  diagnostic: z2.string().optional(),
+  handlerCalls: z2.number().int().nonnegative().optional()
+};
+var RealtimeDisconnectObservationSchema = z2.object({
+  phase: z2.enum(["before-invoke", "in-flight"])
+});
+var TransportObservationSchema = z2.discriminatedUnion("outcome", [
+  z2.object({ outcome: z2.literal("success"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("validation_error"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("domain_error"), ...ObservationFields }),
+  z2.object({ outcome: z2.literal("aborted"), ...ObservationFields }),
+  z2.object({
+    outcome: z2.literal("realtime_rejected"),
+    ...ObservationFields,
+    rejection: RealtimeRejectionObservationSchema
+  }),
+  z2.object({
+    outcome: z2.literal("disconnected"),
+    ...ObservationFields,
+    disconnect: RealtimeDisconnectObservationSchema
+  }),
+  z2.object({ outcome: z2.literal("timeout"), ...ObservationFields })
+]);
+function scenarioOutcome(scenario) {
+  if (scenario === "event" || scenario === "acknowledgement")
+    return "success";
+  if (scenario === "invalid_arguments" || scenario === "invalid_acknowledgement") {
+    return "realtime_rejected";
+  }
+  if (scenario === "disconnected" || scenario === "in_flight_disconnect") {
+    return "disconnected";
+  }
+  return "timeout";
+}
+function assertScenarioExpectation(scenario, expected) {
+  const outcome = scenarioOutcome(scenario);
+  if (expected.outcome !== outcome) {
+    throw new TypeError(`Realtime probe scenario "${scenario}" requires outcome "${outcome}"`);
+  }
+  if (expected.outcome === "realtime_rejected" && (scenario === "invalid_arguments" && expected.rejection.phase !== "arguments" || scenario === "invalid_acknowledgement" && expected.rejection.phase !== "acknowledgement")) {
+    throw new TypeError(`Realtime probe scenario "${scenario}" has incompatible rejection phase`);
+  }
+  if (scenario === "invalid_arguments" && expected.handlerCalls !== 0) {
+    throw new TypeError('Realtime probe scenario "invalid_arguments" requires handlerCalls: 0');
+  }
+  if (expected.outcome === "disconnected") {
+    const phase = scenario === "disconnected" ? "before-invoke" : "in-flight";
+    if (expected.disconnect.phase !== phase) {
+      throw new TypeError(`Realtime probe scenario "${scenario}" requires disconnect phase "${phase}"`);
+    }
+  }
+}
+function defineRealtimeProbe(config) {
+  const expected = TransportObservationSchema.parse(config.expected);
+  assertScenarioExpectation(config.scenario, expected);
+  return {
+    name: config.name,
+    fixture: { scenario: config.scenario, value: config.fixture },
+    transports: ["REALTIME"],
+    expected: { REALTIME: expected },
+    setup: config.setup,
+    teardown: config.teardown
+  };
+}
+function rejectionObservation(rejected) {
+  return RealtimeRejectionObservationSchema.parse(rejected);
+}
+function createRealtimeProbeDriver({
+  bind,
+  handlerCalls
+}) {
+  return {
+    async invoke(fixture, signal) {
+      let rejected;
+      const currentRejection = () => rejected;
+      const adapter = bind((event) => {
+        rejected = event;
+      }, fixture);
+      const connectedBefore = adapter.connected();
+      const callsBefore = handlerCalls?.();
+      const withCalls = (observation) => {
+        if (callsBefore === undefined || !handlerCalls)
+          return observation;
+        return { ...observation, handlerCalls: handlerCalls() - callsBefore };
+      };
+      try {
+        signal.throwIfAborted();
+        const data = await adapter.invoke(fixture, signal);
+        const observedRejection = currentRejection();
+        if (observedRejection) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: observedRejection.error.code,
+            rejection: rejectionObservation(observedRejection)
+          });
+        }
+        return withCalls({
+          outcome: "success",
+          ...data !== undefined && { data }
+        });
+      } catch (error) {
+        const observedRejection = currentRejection();
+        if (observedRejection) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: error instanceof RealtimeRequestInvalidAcknowledgementError ? error.code : observedRejection.error.code,
+            rejection: rejectionObservation(observedRejection)
+          });
+        }
+        if (error instanceof RealtimeRequestInvalidAcknowledgementError) {
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: error.code,
+            rejection: {
+              direction: "client-inbound",
+              phase: "acknowledgement",
+              reason: "invalid-acknowledgement-value",
+              fault: "peer"
+            }
+          });
+        }
+        if (error instanceof RealtimeRequestDisconnectedError) {
+          return withCalls({
+            outcome: "disconnected",
+            code: error.code,
+            disconnect: {
+              phase: connectedBefore ? "in-flight" : "before-invoke"
+            }
+          });
+        }
+        if (error instanceof RealtimeRequestTimeoutError) {
+          return withCalls({ outcome: "timeout", code: error.code });
+        }
+        if (signal.aborted && error === signal.reason) {
+          return withCalls({ outcome: "aborted" });
+        }
+        const parsedRejection = RealtimeRejectionObservationSchema.safeParse(typeof error === "object" && error !== null && "details" in error ? error.details : undefined);
+        if (parsedRejection.success) {
+          const code2 = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "REALTIME_CONTRACT_VIOLATION";
+          return withCalls({
+            outcome: "realtime_rejected",
+            code: code2,
+            rejection: parsedRejection.data
+          });
+        }
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+        return withCalls({
+          outcome: "domain_error",
+          ...code !== undefined && { code },
+          diagnostic: error instanceof Error ? error.message : String(error)
+        });
+      } finally {
+        await adapter.dispose?.();
+      }
+    }
+  };
+}
+function sorted(values) {
+  return [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+}
+function assertSameSet(label, expectedValues, actualValues) {
+  const expected = sorted(expectedValues);
+  const actual = sorted(actualValues);
+  if (serializeSurfaceValue(expected) === serializeSurfaceValue(actual))
+    return;
+  throw new Error(`${label} mismatch
+expected: ${expected.join(", ") || "(empty)"}
+actual: ${actual.join(", ") || "(empty)"}`);
+}
+function openApiOperations(document) {
+  return Object.entries(document.paths).flatMap(([path, item]) => Object.keys(item).filter((method) => ["get", "post", "put", "patch", "delete", "head"].includes(method)).map((method) => `${method.toUpperCase()}:${path}`));
+}
+function expectedToolNames(manifest, transport, surface) {
+  const projection = manifest.toolSurfaces.find((candidate) => candidate.transport === transport && candidate.surface === surface);
+  if (!projection) {
+    throw new Error(`${transport} surface "${surface ?? "(default)"}" is not declared in the manifest`);
+  }
+  return projection.tools.map((tool) => tool.name);
+}
+function assertSurfaceDiscovery(manifest, observed) {
+  if (observed.openApi) {
+    assertSameSet("HTTP/OpenAPI", manifest.operations.flatMap((operation) => operation.http.map((entry) => `${entry.method}:${entry.path.replace(/:([^/]+)/g, "{$1}")}`)), openApiOperations(observed.openApi));
+  }
+  for (const transport of ["MCP", "AGENT", "CLI"]) {
+    const names = observed[transport];
+    if (names) {
+      assertSameSet(`${transport} discovery`, expectedToolNames(manifest, transport, null), names);
+    }
+  }
+  for (const projection of observed.toolSurfaces ?? []) {
+    assertSameSet(`${projection.transport} surface "${projection.surface ?? "(default)"}" discovery`, expectedToolNames(manifest, projection.transport, projection.surface ?? null), projection.names);
+  }
+  for (const [contract, topology] of Object.entries(observed.realtime ?? {})) {
+    if (!manifest.realtimeContracts.includes(contract)) {
+      throw new Error(`REALTIME contract "${contract}" is not declared in the manifest`);
+    }
+    for (const direction of ["serverToClient", "clientToServer"]) {
+      assertSameSet(`REALTIME ${contract}.${direction} discovery`, manifest.realtime.filter((entry) => entry.contract === contract && entry.direction === direction).map((entry) => entry.event), topology[direction]);
+    }
+  }
+  if (observed.cliOnly) {
+    assertSameSet("CLI-only discovery", manifest.cliOnly.map((command) => command.name), observed.cliOnly);
+  }
+  for (const transport of [
+    "HTTP",
+    "MCP",
+    "AGENT",
+    "CLI",
+    "REALTIME"
+  ]) {
+    const names = observed.extensions?.[transport];
+    if (!names)
+      continue;
+    assertSameSet(`${transport} extension discovery`, manifest.extensions.filter((extension) => extension.transport === transport).map((extension) => extension.name), names);
+  }
+}
+function boundedObservation(observation, maxDiagnosticBytes) {
+  const parsed = TransportObservationSchema.parse(observation);
+  if (!parsed.diagnostic)
+    return parsed;
+  const bytes = new TextEncoder().encode(parsed.diagnostic);
+  if (bytes.byteLength <= maxDiagnosticBytes)
+    return parsed;
+  return {
+    ...parsed,
+    diagnostic: new TextDecoder().decode(bytes.slice(0, maxDiagnosticBytes))
+  };
+}
+async function runBounded(run, signal) {
+  if (signal.aborted) {
+    Promise.resolve().then(run).catch(() => {
+      return;
+    });
+    throw signal.reason;
+  }
+  let removeAbortListener = () => {
+    return;
+  };
+  const aborted = new Promise((_resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(run), aborted]);
+  } finally {
+    removeAbortListener();
+  }
+}
+async function runSurfaceProbes({
+  probes,
+  drivers,
+  signal,
+  timeoutMs = 1e4,
+  maxDiagnosticBytes = 4096
+}) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError("Surface probe timeoutMs must be a positive integer");
+  }
+  if (!Number.isInteger(maxDiagnosticBytes) || maxDiagnosticBytes <= 0) {
+    throw new TypeError("Surface probe maxDiagnosticBytes must be a positive integer");
+  }
+  for (const probe of probes) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const probeSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    let failed = false;
+    let failure;
+    try {
+      probeSignal.throwIfAborted();
+      if (probe.setup)
+        await runBounded(() => probe.setup?.(probeSignal), probeSignal);
+      for (const transport of probe.transports) {
+        probeSignal.throwIfAborted();
+        const driver = drivers[transport];
+        if (!driver) {
+          throw new Error(`Surface probe "${probe.name}" has no ${transport} driver`);
+        }
+        const actual = boundedObservation(await runBounded(() => driver.invoke(probe.fixture, probeSignal), probeSignal), maxDiagnosticBytes);
+        const expected = probe.expected[transport];
+        if (!expected) {
+          throw new Error(`Surface probe "${probe.name}" has no ${transport} expectation`);
+        }
+        if (serializeSurfaceValue(actual) !== serializeSurfaceValue(expected)) {
+          throw new Error(`Surface probe "${probe.name}" ${transport} mismatch
+expected: ${serializeSurfaceValue(expected)}
+actual: ${serializeSurfaceValue(actual)}`);
+        }
+      }
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    if (probe.teardown) {
+      try {
+        await runBounded(() => probe.teardown?.(probeSignal), probeSignal);
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          failure = error;
+        }
+      }
+    }
+    if (failed)
+      throw failure;
+  }
+}
 
 // src/testing.ts
 function resolveTestBaseUrl(origin, pathPrefix) {
@@ -31,6 +724,24 @@ function createHandlerTestClients(config) {
   return createClients(config.contracts, createTestClientConfig(config), config.contractConfig);
 }
 export {
+  RealtimeDisconnectObservationSchema,
+  RealtimeRejectionObservationSchema,
+  SurfaceManifestExtensionSchema,
+  SurfaceManifestOperationSchema,
+  SurfaceManifestRealtimeEventSchema,
+  SurfaceManifestSchema,
+  SurfaceManifestToolSchema,
+  SurfaceManifestToolSurfaceSchema,
+  SurfaceRealtimeSchemaPairSchema,
+  SurfaceSchemaDigestsSchema,
+  TransportObservationSchema,
+  assertSurfaceDiscovery,
+  assertSurfaceManifestSnapshot,
+  buildSurfaceManifest,
+  createHandlerTestClient,
   createHandlerTestClients,
-  createHandlerTestClient
+  createRealtimeProbeDriver,
+  defineRealtimeProbe,
+  runSurfaceProbes,
+  serializeSurfaceValue
 };