stitchkit 0.59.3 → 0.60.0

package/dist/testing.js

@@ -2,16 +2,21 @@ import {
   AgentMessageSchema,
   AgentRunSchema
 } from "./index-vtjgx3vv.js";
+import {
+  createApplication
+} from "./index-1zencgcb.js";
+import"./index-8eywc9zv.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
   RealtimeRequestTimeoutError
 } from "./index-557by2db.js";
+import"./index-dk6e56g0.js";
 import {
   mcpProjectionCandidate,
   prepareProjectedMcpTools,
   projectToolSurface
-} from "./index-1tkyng3g.js";
+} from "./index-vkk06pv1.js";
 import"./index-6djpbnda.js";
 import {
   toJsonSchema
@@ -19,9 +24,11 @@ import {
 import {
   createClient,
   createClients
-} from "./index-mr617n62.js";
+} from "./index-svqhcrrj.js";
 import"./index-48ffdxgk.js";
-import"./index-y2rb7dwx.js";
+import {
+  joinRoutePath
+} from "./index-pzyt11ch.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";
@@ -378,73 +385,649 @@ async function runAgentStoreConformance(config) {
     throw new Error("Abandon recovery did not atomically terminalize its assistant record");
   }
 }
+// src/testing/managed-resource-conformance-contract.ts
+import { z } from "zod";
+var ManagedResourceConformanceScenarioIdSchema = z.enum([
+  "clean-shutdown",
+  "partial-start-rollback",
+  "readiness-rejection",
+  "completion-before-ready",
+  "required-late-completion",
+  "optional-late-completion",
+  "activation-rejection",
+  "shutdown-during-startup",
+  "force-after-stalled-close"
+]);
+var ManagedResourceConformanceScenarioSchema = z.discriminatedUnion("id", [
+  z.object({ id: z.literal("clean-shutdown"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("partial-start-rollback"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("readiness-rejection"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("completion-before-ready"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("required-late-completion"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("optional-late-completion"), required: z.literal(false) }).readonly(),
+  z.object({ id: z.literal("activation-rejection"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("shutdown-during-startup"), required: z.literal(true) }).readonly(),
+  z.object({ id: z.literal("force-after-stalled-close"), required: z.literal(true) }).readonly()
+]);
+var ManagedResourceConformancePhaseSchema = z.enum([
+  "start",
+  "readiness",
+  "completion",
+  "activate",
+  "stop-admission",
+  "drain",
+  "close",
+  "force",
+  "dispose"
+]);
+var ManagedResourceConformanceTraceOutcomeSchema = z.enum([
+  "enter",
+  "resolve",
+  "reject"
+]);
+var ManagedResourceConformanceTraceEntrySchema = z.object({
+  sequence: z.number().int().nonnegative(),
+  phase: ManagedResourceConformancePhaseSchema,
+  outcome: ManagedResourceConformanceTraceOutcomeSchema
+}).strict().readonly();
+
+class ManagedResourceConformanceError extends Error {
+  scenarioId;
+  expected;
+  trace;
+  code = "MANAGED_RESOURCE_CONFORMANCE_FAILED";
+  constructor(scenarioId, expected, trace, detail) {
+    const observed = trace.length === 0 ? "(empty)" : trace.map((entry) => `${entry.phase}:${entry.outcome}`).join(" -> ");
+    super(`[stitchkit] managed resource conformance "${scenarioId}" failed: ${detail}; ` + `expected ${expected.join(" -> ")}; observed ${observed}`);
+    this.scenarioId = scenarioId;
+    this.expected = expected;
+    this.trace = trace;
+    this.name = "ManagedResourceConformanceError";
+  }
+}
+
+// src/testing/managed-resource-conformance-driver.ts
+function controlledPromise() {
+  const deferred = Promise.withResolvers();
+  let settled = false;
+  deferred.promise.catch(() => {
+    return;
+  });
+  return {
+    promise: deferred.promise,
+    resolve() {
+      if (settled)
+        return false;
+      settled = true;
+      deferred.resolve();
+      return true;
+    },
+    reject(error) {
+      if (settled)
+        return false;
+      settled = true;
+      deferred.reject(error);
+      return true;
+    }
+  };
+}
+
+class ManagedResourceConformanceTrace {
+  entries = [];
+  waiters = new Set;
+  record(phase, outcome) {
+    const entry = ManagedResourceConformanceTraceEntrySchema.parse({
+      sequence: this.entries.length,
+      phase,
+      outcome
+    });
+    this.entries.push(entry);
+    for (const waiter of this.waiters) {
+      if (waiter.phase !== phase || waiter.outcome !== outcome)
+        continue;
+      this.waiters.delete(waiter);
+      waiter.resolve();
+    }
+  }
+  has(phase, outcome) {
+    return this.entries.some((entry) => entry.phase === phase && entry.outcome === outcome);
+  }
+  count(phase, outcome) {
+    return this.entries.filter((entry) => entry.phase === phase && entry.outcome === outcome).length;
+  }
+  waitFor(phase, outcome = "enter") {
+    if (this.has(phase, outcome))
+      return Promise.resolve();
+    return new Promise((resolve) => this.waiters.add({ phase, outcome, resolve }));
+  }
+}
+function createManagedResourceConformanceGates(trace) {
+  const startup = controlledPromise();
+  const readiness = controlledPromise();
+  const completion = controlledPromise();
+  const activation = controlledPromise();
+  const close = controlledPromise();
+  const force = controlledPromise();
+  const gateFor = (phase) => {
+    if (phase === "start")
+      return startup;
+    if (phase === "readiness")
+      return readiness;
+    if (phase === "completion")
+      return completion;
+    if (phase === "activate")
+      return activation;
+    if (phase === "close")
+      return close;
+    return force;
+  };
+  const resolve = (phase) => {
+    if (gateFor(phase).resolve())
+      trace.record(phase, "resolve");
+  };
+  return {
+    controls: {
+      startup: startup.promise,
+      readiness: readiness.promise,
+      completion: completion.promise,
+      activation: activation.promise,
+      close: close.promise,
+      force: force.promise
+    },
+    resolve,
+    reject(phase, error) {
+      if (gateFor(phase).reject(error))
+        trace.record(phase, "reject");
+    },
+    releaseAll() {
+      resolve("start");
+      resolve("readiness");
+      resolve("completion");
+      resolve("activate");
+      resolve("close");
+      resolve("force");
+    }
+  };
+}
+async function observePhase(trace, phase, invoke) {
+  trace.record(phase, "enter");
+  try {
+    const value = await invoke();
+    trace.record(phase, "resolve");
+    return value;
+  } catch (error) {
+    trace.record(phase, "reject");
+    throw error;
+  }
+}
+function optionalPhase(resource, trace, phase, invoke) {
+  if (!invoke)
+    return {};
+  return {
+    [phase]: (context) => observePhase(trace, phase, () => invoke.call(resource, context))
+  };
+}
+function observeManagedResource(resource, required, trace) {
+  const start = async (context) => {
+    trace.record("start", "enter");
+    try {
+      const value = await resource.start(context);
+      trace.record("start", "resolve");
+      if (value === undefined)
+        return;
+      return value;
+    } catch (error) {
+      trace.record("start", "reject");
+      throw error;
+    }
+  };
+  return {
+    id: resource.id,
+    required,
+    start,
+    ...optionalPhase(resource, trace, "activate", resource.activate),
+    ...resource.stopAdmission ? {
+      stopAdmission: (context) => observePhase(trace, "stop-admission", () => resource.stopAdmission?.call(resource, context))
+    } : {},
+    ...optionalPhase(resource, trace, "drain", resource.drain),
+    ...optionalPhase(resource, trace, "close", resource.close),
+    ...optionalPhase(resource, trace, "force", resource.force)
+  };
+}
+
+// src/testing/managed-resource-conformance-scenarios.ts
+var MANAGED_RESOURCE_CONFORMANCE_SCENARIOS = ManagedResourceConformanceScenarioSchema.array().parse([
+  { id: "clean-shutdown", required: true },
+  { id: "partial-start-rollback", required: true },
+  { id: "readiness-rejection", required: true },
+  { id: "completion-before-ready", required: true },
+  { id: "required-late-completion", required: true },
+  { id: "optional-late-completion", required: false },
+  { id: "activation-rejection", required: true },
+  { id: "shutdown-during-startup", required: true },
+  { id: "force-after-stalled-close", required: true }
+]);
+var EXPECTED_TRACE = {
+  "clean-shutdown": [
+    "start:enter",
+    "start:resolve",
+    "readiness:resolve",
+    "activate:enter",
+    "activate:resolve",
+    "stop-admission:enter",
+    "drain:enter",
+    "close:enter",
+    "close:resolve"
+  ],
+  "partial-start-rollback": ["start:enter", "start:reject", "close:enter", "close:resolve"],
+  "readiness-rejection": [
+    "start:enter",
+    "start:resolve",
+    "readiness:reject",
+    "close:enter",
+    "close:resolve"
+  ],
+  "completion-before-ready": [
+    "start:enter",
+    "start:resolve",
+    "completion:reject",
+    "close:enter",
+    "close:resolve"
+  ],
+  "required-late-completion": [
+    "activate:resolve",
+    "completion:reject",
+    "stop-admission:enter",
+    "drain:enter",
+    "close:enter"
+  ],
+  "optional-late-completion": [
+    "activate:resolve",
+    "completion:reject",
+    "stop-admission:enter",
+    "drain:enter",
+    "close:enter"
+  ],
+  "activation-rejection": [
+    "readiness:resolve",
+    "activate:enter",
+    "activate:reject",
+    "close:enter",
+    "close:resolve"
+  ],
+  "shutdown-during-startup": ["start:enter", "start:resolve", "close:enter", "close:resolve"],
+  "force-after-stalled-close": [
+    "stop-admission:enter",
+    "drain:enter",
+    "close:enter",
+    "force:enter",
+    "force:resolve"
+  ]
+};
+function outcomeOf(promise) {
+  return promise.then(() => ({ status: "resolved" }), (error) => ({ status: "rejected", error }));
+}
+function requireCondition(condition, detail) {
+  if (!condition)
+    throw new Error(detail);
+}
+function observedTrace(trace) {
+  return trace.entries.map((entry) => `${entry.phase}:${entry.outcome}`);
+}
+function requireTrace(runtime) {
+  const expected = EXPECTED_TRACE[runtime.scenario.id];
+  const observed = observedTrace(runtime.trace);
+  let cursor = 0;
+  for (const entry of observed) {
+    if (entry === expected[cursor])
+      cursor += 1;
+  }
+  requireCondition(cursor === expected.length, `phase trace omitted or reordered "${expected[cursor] ?? "unknown"}"`);
+}
+async function phaseOrSettlement(trace, phase, settlement) {
+  return Promise.race([
+    trace.waitFor(phase).then(() => "phase"),
+    settlement.then(() => "settled", () => "settled")
+  ]);
+}
+async function startSuccessfully(runtime) {
+  const starting = runtime.application.start();
+  const startOutcome = outcomeOf(starting);
+  await runtime.trace.waitFor("start");
+  runtime.gates.resolve("start");
+  runtime.gates.resolve("readiness");
+  const activation = await Promise.race([
+    runtime.trace.waitFor("activate").then(() => ({ status: "resolved" })),
+    startOutcome
+  ]);
+  if (activation.status === "rejected")
+    throw activation.error;
+  runtime.gates.resolve("activate");
+  const outcome = await startOutcome;
+  requireCondition(outcome.status === "resolved", "application did not complete successful startup");
+}
+async function closeNormally(runtime) {
+  const shuttingDown = runtime.application.shutdown();
+  const close = await phaseOrSettlement(runtime.trace, "close", shuttingDown);
+  if (close === "phase")
+    runtime.gates.resolve("close");
+  const outcome = await outcomeOf(shuttingDown);
+  requireCondition(outcome.status === "resolved", "application shutdown rejected");
+}
+async function expectStartupFailure(runtime, starting) {
+  const close = await phaseOrSettlement(runtime.trace, "close", starting);
+  if (close === "phase")
+    runtime.gates.resolve("close");
+  const outcome = await outcomeOf(starting);
+  if (outcome.status === "resolved") {
+    await closeNormally(runtime);
+    throw new Error("application startup unexpectedly resolved");
+  }
+  requireCondition(runtime.trace.count("close", "enter") === 1, "attempted resource was not closed once");
+  await runtime.application.shutdown();
+}
+function waitForSnapshot(application, predicate) {
+  const deferred = Promise.withResolvers();
+  let unsubscribe = () => {
+    return;
+  };
+  unsubscribe = application.subscribe((snapshot) => {
+    if (!predicate(snapshot))
+      return;
+    unsubscribe();
+    deferred.resolve(snapshot);
+  });
+  return deferred.promise;
+}
+async function cleanShutdown(runtime) {
+  await startSuccessfully(runtime);
+  await closeNormally(runtime);
+  requireCondition(runtime.application.getSnapshot().lifecycle === "stopped", "clean shutdown did not stop the application");
+}
+async function partialStartRollback(runtime) {
+  const starting = runtime.application.start();
+  await runtime.trace.waitFor("start");
+  runtime.gates.reject("start", new Error("controlled partial startup rejection"));
+  await expectStartupFailure(runtime, starting);
+}
+async function readinessRejection(runtime) {
+  const starting = runtime.application.start();
+  await runtime.trace.waitFor("start");
+  runtime.gates.resolve("start");
+  await runtime.trace.waitFor("start", "resolve");
+  runtime.gates.reject("readiness", new Error("controlled readiness rejection"));
+  runtime.gates.resolve("activate");
+  await expectStartupFailure(runtime, starting);
+}
+async function completionBeforeReady(runtime) {
+  const starting = runtime.application.start();
+  await runtime.trace.waitFor("start");
+  runtime.gates.resolve("start");
+  await runtime.trace.waitFor("start", "resolve");
+  runtime.gates.reject("completion", new Error("controlled early completion rejection"));
+  runtime.gates.resolve("readiness");
+  runtime.gates.resolve("activate");
+  await expectStartupFailure(runtime, starting);
+}
+async function lateCompletion(runtime) {
+  await startSuccessfully(runtime);
+  const expectedHealth = runtime.scenario.required ? "unhealthy" : "degraded";
+  const changed = waitForSnapshot(runtime.application, (snapshot2) => snapshot2.health === expectedHealth);
+  runtime.gates.reject("completion", new Error("controlled late completion rejection"));
+  const snapshot = await changed;
+  requireCondition(snapshot.lifecycle === "ready", "late completion changed lifecycle ownership");
+  requireCondition(snapshot.health === expectedHealth, "late completion projected the wrong health");
+  requireCondition(snapshot.ready === !runtime.scenario.required, "late completion projected the wrong readiness");
+  requireCondition(snapshot.admission.accepting === !runtime.scenario.required, "late completion projected the wrong admission state");
+  await closeNormally(runtime);
+}
+async function activationRejection(runtime) {
+  const starting = runtime.application.start();
+  await runtime.trace.waitFor("start");
+  runtime.gates.resolve("start");
+  await runtime.trace.waitFor("start", "resolve");
+  runtime.gates.resolve("readiness");
+  await runtime.trace.waitFor("activate");
+  runtime.gates.reject("activate", new Error("controlled activation rejection"));
+  await expectStartupFailure(runtime, starting);
+}
+async function shutdownDuringStartup(runtime) {
+  const starting = runtime.application.start();
+  await runtime.trace.waitFor("start");
+  const shuttingDown = runtime.application.shutdown();
+  runtime.gates.resolve("start");
+  const close = await phaseOrSettlement(runtime.trace, "close", shuttingDown);
+  if (close === "phase")
+    runtime.gates.resolve("close");
+  const [startOutcome, shutdownOutcome] = await Promise.all([
+    outcomeOf(starting),
+    outcomeOf(shuttingDown)
+  ]);
+  requireCondition(startOutcome.status === "rejected", "startup won the shutdown race");
+  requireCondition(shutdownOutcome.status === "resolved", "shutdown race rejected");
+  requireCondition(!runtime.trace.has("activate", "enter"), "resource activated after shutdown won");
+}
+async function forceAfterStalledClose(runtime) {
+  await startSuccessfully(runtime);
+  const controller = new AbortController;
+  const shuttingDown = runtime.application.shutdown({
+    gracePeriodMs: 60000,
+    forceTimeoutMs: 60000,
+    signal: controller.signal
+  });
+  await runtime.trace.waitFor("close");
+  controller.abort();
+  const force = await phaseOrSettlement(runtime.trace, "force", shuttingDown);
+  if (force === "phase")
+    runtime.gates.resolve("force");
+  const result = await shuttingDown;
+  requireCondition(runtime.trace.count("close", "enter") === 1, "close was not invoked exactly once");
+  requireCondition(runtime.trace.count("force", "enter") === 1, "unfinished close did not invoke force");
+  requireCondition(result.outcome === "forced", "forced shutdown reported a clean outcome");
+  requireCondition(result.reason === "signal", "forced shutdown lost its signal reason");
+  runtime.gates.resolve("close");
+}
+function expectedManagedResourceConformanceTrace(scenarioId) {
+  return EXPECTED_TRACE[scenarioId];
+}
+async function executeManagedResourceConformanceScenario(scenario, resource, gates, trace) {
+  const application = createApplication({
+    id: `conformance-${scenario.id}`,
+    resources: [observeManagedResource(resource, scenario.required, trace)]
+  });
+  const runtime = { scenario, application, gates, trace };
+  if (scenario.id === "clean-shutdown")
+    await cleanShutdown(runtime);
+  else if (scenario.id === "partial-start-rollback")
+    await partialStartRollback(runtime);
+  else if (scenario.id === "readiness-rejection")
+    await readinessRejection(runtime);
+  else if (scenario.id === "completion-before-ready")
+    await completionBeforeReady(runtime);
+  else if (scenario.id === "required-late-completion" || scenario.id === "optional-late-completion") {
+    await lateCompletion(runtime);
+  } else if (scenario.id === "activation-rejection")
+    await activationRejection(runtime);
+  else if (scenario.id === "shutdown-during-startup")
+    await shutdownDuringStartup(runtime);
+  else
+    await forceAfterStalledClose(runtime);
+  requireTrace(runtime);
+}
+
+// src/testing/managed-resource-conformance.ts
+var DEFAULT_WATCHDOG_TIMEOUT_MS = 2000;
+
+class ManagedResourceConformanceWatchdogError extends Error {
+  phase;
+  constructor(phase) {
+    super(`emergency watchdog expired during ${phase}`);
+    this.phase = phase;
+    this.name = "ManagedResourceConformanceWatchdogError";
+  }
+}
+async function withWatchdog(promise, timeoutMs, phase) {
+  let timer;
+  const watchdog = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new ManagedResourceConformanceWatchdogError(phase)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, watchdog]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+}
+function detailOf(error) {
+  if (error instanceof ManagedResourceConformanceWatchdogError)
+    return error.message;
+  if (error instanceof Error)
+    return error.message;
+  return "unknown conformance failure";
+}
+async function runScenario(config, scenario, watchdogTimeoutMs) {
+  const trace = new ManagedResourceConformanceTrace;
+  const gates = createManagedResourceConformanceGates(trace);
+  const fixture = await withWatchdog(Promise.resolve().then(() => config.createFixture({ scenario, controls: gates.controls })), watchdogTimeoutMs, "factory").catch((error) => {
+    throw new ManagedResourceConformanceError(scenario.id, expectedManagedResourceConformanceTrace(scenario.id), trace.entries, detailOf(error));
+  });
+  let failure;
+  const execution = executeManagedResourceConformanceScenario(scenario, fixture.resource, gates, trace);
+  execution.catch(() => {
+    return;
+  });
+  let settlementIncomplete = false;
+  try {
+    await withWatchdog(execution, watchdogTimeoutMs, "scenario");
+  } catch (error) {
+    failure = { value: error };
+  } finally {
+    gates.releaseAll();
+    if (failure?.value instanceof ManagedResourceConformanceWatchdogError) {
+      try {
+        await withWatchdog(execution, watchdogTimeoutMs, "settlement");
+      } catch (error) {
+        if (error instanceof ManagedResourceConformanceWatchdogError) {
+          settlementIncomplete = true;
+        } else {
+          failure = { value: error };
+        }
+      }
+    }
+    trace.record("dispose", "enter");
+    try {
+      await withWatchdog(Promise.resolve(fixture.dispose()), watchdogTimeoutMs, "dispose");
+      trace.record("dispose", "resolve");
+    } catch (error) {
+      trace.record("dispose", "reject");
+      if (failure === undefined)
+        failure = { value: error };
+    }
+    if (settlementIncomplete) {
+      try {
+        await withWatchdog(execution, watchdogTimeoutMs, "settlement");
+        settlementIncomplete = false;
+      } catch (error) {
+        if (error instanceof ManagedResourceConformanceWatchdogError) {
+          const original = failure?.value;
+          failure = {
+            value: new Error(`${detailOf(original)}; execution remained live after fixture disposal`)
+          };
+        } else {
+          settlementIncomplete = false;
+          failure = { value: error };
+        }
+      }
+    }
+  }
+  if (failure !== undefined) {
+    if (failure.value instanceof ManagedResourceConformanceError)
+      throw failure.value;
+    throw new ManagedResourceConformanceError(scenario.id, expectedManagedResourceConformanceTrace(scenario.id), trace.entries, detailOf(failure.value));
+  }
+}
+async function runManagedResourceConformance(config) {
+  const watchdogTimeoutMs = config.watchdogTimeoutMs ?? DEFAULT_WATCHDOG_TIMEOUT_MS;
+  if (!Number.isSafeInteger(watchdogTimeoutMs) || watchdogTimeoutMs <= 0) {
+    throw new TypeError("[stitchkit] managed resource conformance watchdogTimeoutMs must be positive");
+  }
+  const selected = new Set((config.scenarios ?? MANAGED_RESOURCE_CONFORMANCE_SCENARIOS.map((scenario) => scenario.id)).map((scenario) => ManagedResourceConformanceScenarioIdSchema.parse(scenario)));
+  if (selected.size === 0) {
+    throw new TypeError("[stitchkit] managed resource conformance scenarios must not be empty");
+  }
+  for (const scenario of MANAGED_RESOURCE_CONFORMANCE_SCENARIOS) {
+    if (!selected.has(scenario.id))
+      continue;
+    await runScenario(config, scenario, watchdogTimeoutMs);
+  }
+}
 // src/testing/surface-conformance.ts
-import { z as z2 } from "zod";
+import { z as z3 } 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()
+import { z as z2 } from "zod";
+var HttpMethodSchema = z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var ToolTransportSchema = z2.enum(["MCP", "AGENT", "CLI"]);
+var SurfaceTransportSchema = z2.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
+var SurfaceSchemaDigestsSchema = z2.object({
+  params: z2.string().nullable(),
+  input: z2.string().nullable(),
+  output: z2.string().nullable(),
+  multipart: z2.string().nullable()
 });
-var SurfaceManifestOperationSchema = z.object({
-  kind: z.enum(["contract", "runtime"]),
-  service: z.string(),
-  action: z.string(),
+var SurfaceManifestOperationSchema = z2.object({
+  kind: z2.enum(["contract", "runtime"]),
+  service: z2.string(),
+  action: z2.string(),
   method: HttpMethodSchema,
-  scope: z.string().nullable(),
-  description: z.string(),
+  scope: z2.string().nullable(),
+  description: z2.string(),
   schemas: SurfaceSchemaDigestsSchema,
-  http: z.array(z.object({ method: HttpMethodSchema, path: z.string() }))
+  http: z2.array(z2.object({ method: HttpMethodSchema, path: z2.string() }))
 });
-var SurfaceManifestToolSchema = z.object({
-  kind: z.enum(["contract", "runtime"]),
-  service: z.string(),
-  action: z.string(),
-  name: z.string(),
-  input: z.string()
+var SurfaceManifestToolSchema = z2.object({
+  kind: z2.enum(["contract", "runtime"]),
+  service: z2.string(),
+  action: z2.string(),
+  name: z2.string(),
+  input: z2.string()
 });
-var SurfaceManifestToolSurfaceSchema = z.object({
+var SurfaceManifestToolSurfaceSchema = z2.object({
   transport: ToolTransportSchema,
-  surface: z.string().nullable(),
-  tools: z.array(SurfaceManifestToolSchema)
+  surface: z2.string().nullable(),
+  tools: z2.array(SurfaceManifestToolSchema)
 });
-var SurfaceManifestCliCommandSchema = z.object({
-  name: z.string(),
-  description: z.string(),
-  input: z.string(),
-  output: z.string().nullable()
+var SurfaceManifestCliCommandSchema = z2.object({
+  name: z2.string(),
+  description: z2.string(),
+  input: z2.string(),
+  output: z2.string().nullable()
 });
-var SurfaceManifestExtensionSchema = z.object({
-  name: z.string(),
+var SurfaceManifestExtensionSchema = z2.object({
+  name: z2.string(),
   transport: SurfaceTransportSchema
 });
-var SurfaceRealtimeSchemaPairSchema = z.object({
-  input: z.string(),
-  output: z.string()
+var SurfaceRealtimeSchemaPairSchema = z2.object({
+  input: z2.string(),
+  output: z2.string()
 });
-var SurfaceManifestRealtimeEventSchema = z.object({
-  contract: z.string(),
-  direction: z.enum(["serverToClient", "clientToServer"]),
-  event: z.string(),
+var SurfaceManifestRealtimeEventSchema = z2.object({
+  contract: z2.string(),
+  direction: z2.enum(["serverToClient", "clientToServer"]),
+  event: z2.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)
+var SurfaceManifestSchema = z2.object({
+  manifestVersion: z2.literal(2),
+  digestVersion: z2.literal(1),
+  operations: z2.array(SurfaceManifestOperationSchema),
+  toolSurfaces: z2.array(SurfaceManifestToolSurfaceSchema),
+  realtimeContracts: z2.array(z2.string()),
+  realtime: z2.array(SurfaceManifestRealtimeEventSchema),
+  cliOnly: z2.array(SurfaceManifestCliCommandSchema),
+  extensions: z2.array(SurfaceManifestExtensionSchema)
 });
 function compareCodepoints(left, right) {
   if (left < right)
@@ -494,10 +1077,6 @@ function presentationDigest(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}`;
 }
@@ -583,7 +1162,7 @@ function buildSurfaceManifest(config) {
         continue;
       const route = {
         method: method.method,
-        path: joinPath(prefix, service.prefix, method.path)
+        path: joinRoutePath(prefix, service.prefix, method.path)
       };
       if (!operation.http.some((entry) => entry.method === route.method && entry.path === route.path)) {
         operation.http.push(route);
@@ -729,47 +1308,47 @@ actual: ${actual}`);
 }
 
 // src/testing/surface-conformance.ts
-var RealtimeRejectionObservationSchema = z2.object({
-  direction: z2.enum([
+var RealtimeRejectionObservationSchema = z3.object({
+  direction: z3.enum([
     "client-inbound",
     "client-outbound",
     "server-inbound",
     "server-outbound"
   ]),
-  phase: z2.enum(["arguments", "acknowledgement"]),
-  reason: z2.enum([
+  phase: z3.enum(["arguments", "acknowledgement"]),
+  reason: z3.enum([
     "unknown-event",
     "invalid-arguments",
     "invalid-acknowledgement-value",
     "missing-acknowledgement"
   ]),
-  fault: z2.enum(["peer", "local"])
+  fault: z3.enum(["peer", "local"])
 });
 var ObservationFields = {
-  code: z2.string().optional(),
-  data: z2.unknown().optional(),
-  diagnostic: z2.string().optional(),
-  handlerCalls: z2.number().int().nonnegative().optional()
+  code: z3.string().optional(),
+  data: z3.unknown().optional(),
+  diagnostic: z3.string().optional(),
+  handlerCalls: z3.number().int().nonnegative().optional()
 };
-var RealtimeDisconnectObservationSchema = z2.object({
-  phase: z2.enum(["before-invoke", "in-flight"])
+var RealtimeDisconnectObservationSchema = z3.object({
+  phase: z3.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"),
+var TransportObservationSchema = z3.discriminatedUnion("outcome", [
+  z3.object({ outcome: z3.literal("success"), ...ObservationFields }),
+  z3.object({ outcome: z3.literal("validation_error"), ...ObservationFields }),
+  z3.object({ outcome: z3.literal("domain_error"), ...ObservationFields }),
+  z3.object({ outcome: z3.literal("aborted"), ...ObservationFields }),
+  z3.object({
+    outcome: z3.literal("realtime_rejected"),
     ...ObservationFields,
     rejection: RealtimeRejectionObservationSchema
   }),
-  z2.object({
-    outcome: z2.literal("disconnected"),
+  z3.object({
+    outcome: z3.literal("disconnected"),
     ...ObservationFields,
     disconnect: RealtimeDisconnectObservationSchema
   }),
-  z2.object({ outcome: z2.literal("timeout"), ...ObservationFields })
+  z3.object({ outcome: z3.literal("timeout"), ...ObservationFields })
 ]);
 function scenarioOutcome(scenario) {
   if (scenario === "event" || scenario === "acknowledgement")
@@ -1081,6 +1660,12 @@ function createHandlerTestClients(config) {
   return createClients(config.contracts, createTestClientConfig(config), config.contractConfig);
 }
 export {
+  ManagedResourceConformanceError,
+  ManagedResourceConformancePhaseSchema,
+  ManagedResourceConformanceScenarioIdSchema,
+  ManagedResourceConformanceScenarioSchema,
+  ManagedResourceConformanceTraceEntrySchema,
+  ManagedResourceConformanceTraceOutcomeSchema,
   RealtimeDisconnectObservationSchema,
   RealtimeRejectionObservationSchema,
   SurfaceManifestExtensionSchema,
@@ -1103,6 +1688,7 @@ export {
   createRealtimeProbeDriver,
   defineRealtimeProbe,
   runAgentStoreConformance,
+  runManagedResourceConformance,
   runSurfaceProbes,
   serializeSurfaceValue
 };