stitchkit 0.76.2 → 0.78.0

package/dist/testing.js

@@ -1,18 +1,27 @@
+import {
+  ApplicationIdSchema,
+  ApplicationShutdownResultSchema,
+  ApplicationSnapshotSchema
+} from "./index-anyqnqcv.js";
 import {
   AgentMessageSchema,
   AgentRunSchema
 } from "./index-x1th9s8c.js";
 import {
-  createApplication
-} from "./index-hvftzz91.js";
-import"./index-2k4yrqkc.js";
-import"./index-8eywc9zv.js";
+  managedResourceDependencyId
+} from "./index-2k4yrqkc.js";
+import {
+  DEFAULT_STREAM_LINE_BYTES,
+  inputIsQuery,
+  parseSSE,
+  readBoundedUtf8Lines
+} from "./index-56fm73re.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
-  RealtimeRequestTimeoutError
-} from "./index-7b188kmz.js";
-import"./index-3z73fh2c.js";
+  RealtimeRequestTimeoutError,
+  ShutdownOptionsSchema
+} from "./index-1ckavx4h.js";
 import {
   mcpProjectionCandidate,
   prepareProjectedMcpTools,
@@ -21,21 +30,642 @@ import {
 import {
   toJsonSchema
 } from "./index-cby4ar3v.js";
+import"./index-efm026pw.js";
 import {
-  createClient,
-  createClients
-} from "./index-58jzmnn4.js";
-import"./index-1rxswfbv.js";
-import"./index-nt1mp8km.js";
-import {
-  joinRoutePath
+  ContractStreamFrameSchema,
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+  joinRoutePath,
+  parseTrailingWildcard
 } from "./index-vj3vvpaa.js";
-import"./index-0w9abg87.js";
 import {
-  isRecord
+  isRecord,
+  mapObject,
+  typedEntries
 } from "./index-qyrqwr4c.js";
+import {
+  AppError
+} from "./index-0w9abg87.js";
 import"./index-6k1937bx.js";
 
+// src/browser/cancellation.ts
+class RequestCancellationError extends Error {
+  cause;
+  constructor(cause) {
+    super(cause === "caller" ? "Request was aborted" : "Request timed out");
+    this.cause = cause;
+    this.name = "RequestCancellationError";
+  }
+}
+function createRequestCancellation(caller, timeoutMs) {
+  if (!caller && timeoutMs === undefined) {
+    return { signal: undefined, run: (operation) => operation() };
+  }
+  const timeoutController = timeoutMs === undefined ? undefined : new AbortController;
+  const signal = caller && timeoutController ? AbortSignal.any([caller, timeoutController.signal]) : caller ?? timeoutController?.signal;
+  let cause;
+  let timer;
+  const abortFromCaller = () => {
+    if (cause)
+      return;
+    cause = "caller";
+  };
+  if (caller?.aborted)
+    abortFromCaller();
+  else
+    caller?.addEventListener("abort", abortFromCaller, { once: true });
+  if (timeoutMs !== undefined && timeoutController) {
+    timer = setTimeout(() => {
+      if (cause)
+        return;
+      cause = "timeout";
+      timeoutController.abort(new DOMException("Request timed out", "TimeoutError"));
+    }, timeoutMs);
+  }
+  return {
+    signal,
+    async run(operation) {
+      try {
+        if (cause === "caller")
+          throw cancellationError(cause);
+        return await operation(signal);
+      } catch (error) {
+        if (cause)
+          throw cancellationError(cause);
+        throw error;
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+        caller?.removeEventListener("abort", abortFromCaller);
+      }
+    }
+  };
+}
+function cancellationError(cause) {
+  return new RequestCancellationError(cause);
+}
+
+// src/browser/http.ts
+import ky, {
+  isHTTPError,
+  isNetworkError,
+  isTimeoutError
+} from "ky";
+
+// src/browser/request-id.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function responseTraceId(response) {
+  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
+}
+
+// src/browser/http.ts
+var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
+function messageForCode(code, message) {
+  return message !== undefined && message.length > 0 ? message : `${code} (no message supplied)`;
+}
+
+class ApiError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, status = 0, details, message, hint, traceId, options) {
+    super(messageForCode(code, message), options);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "ApiError";
+    Object.defineProperty(this, API_ERROR_BRAND, { value: true });
+  }
+  static is(error) {
+    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
+  }
+}
+function refuseLocally(path, message) {
+  return new ApiError("VALIDATION_ERROR", 0, { issues: [{ path, code: "invalid_type", message }] }, message);
+}
+function parseApiErrorBody(body) {
+  if (!isRecord(body) || !isRecord(body.error))
+    return null;
+  const error = body.error;
+  if (typeof error.code !== "string")
+    return null;
+  return {
+    code: error.code,
+    message: typeof error.message === "string" ? error.message : undefined,
+    details: error.details,
+    hint: typeof error.hint === "string" ? error.hint : undefined
+  };
+}
+
+// src/browser/client-multipart.ts
+function isFileDescriptor(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
+}
+function isMultipartFile(value) {
+  return value instanceof Blob || isFileDescriptor(value);
+}
+function appendMultipartFile(form, field, file) {
+  const sink = form;
+  sink.append(field, file);
+}
+function appendFormFields(formData, values, skipKeys) {
+  for (const [key, value] of Object.entries(values)) {
+    if (skipKeys.has(key) || value === undefined || value === null)
+      continue;
+    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+}
+function buildMultipartForm(descriptor, values) {
+  const formData = new FormData;
+  const fileFields = new Set(Object.keys(descriptor.files));
+  for (const [field, policy] of Object.entries(descriptor.files)) {
+    const value = values[field];
+    if (value === undefined) {
+      if (policy.required !== false) {
+        throw refuseLocally(field, `Missing multipart file field: ${field}`);
+      }
+      continue;
+    }
+    if (policy.multiple === true) {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw refuseLocally(field, `Multipart file field "${field}" must be a non-empty array`);
+      }
+      for (const file of value) {
+        if (!isMultipartFile(file)) {
+          throw refuseLocally(field, `Invalid multipart file field: ${field}`);
+        }
+        appendMultipartFile(formData, field, file);
+      }
+      continue;
+    }
+    if (!isMultipartFile(value)) {
+      throw refuseLocally(field, `Invalid multipart file field: ${field}`);
+    }
+    appendMultipartFile(formData, field, value);
+  }
+  appendFormFields(formData, values, fileFields);
+  return formData;
+}
+
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+}
+function collectQueryParams(args, endpoint) {
+  const params = {};
+  let hasParams = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
+      params[key] = value;
+      hasParams = true;
+      continue;
+    }
+    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
+    throw refuseLocally(key, `${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+  }
+  return hasParams ? params : undefined;
+}
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function resolvePathPrefix(config, args) {
+  if (!config?.pathPrefix)
+    return "";
+  if (typeof config.pathPrefix === "string")
+    return config.pathPrefix;
+  const keys = config.stripPrefixKeys ?? [];
+  if (!hasStringKeys(args, keys)) {
+    const missing = keys.find((key) => typeof args[key] !== "string");
+    throw refuseLocally(String(missing), `Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
+}
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  const wildcard = parseTrailingWildcard(path);
+  if (wildcard)
+    names.push(wildcard.name);
+  return names;
+}
+function fillPathParams(path, args) {
+  const wildcard = parseTrailingWildcard(path);
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw refuseLocally(String(key), `Missing path param: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (!wildcard)
+    return filled;
+  const wildcardValue = args[wildcard.name];
+  if (wildcardValue === undefined || wildcardValue === null) {
+    throw refuseLocally(wildcard.name, `Missing path param: ${wildcard.name}`);
+  }
+  const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -(wildcard.name.length + 1))}${remainder}`;
+  return filled;
+}
+function stripConsumedArgs(args, path, scopeKeys) {
+  const consumed = new Set(scopeKeys);
+  for (const name of extractParamNames(path))
+    consumed.add(name);
+  const remaining = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key) && value !== undefined)
+      remaining[key] = value;
+  }
+  return remaining;
+}
+function appendQuery(relativeUrl, params) {
+  if (!params)
+    return relativeUrl;
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, String(item));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search.size > 0 ? `${relativeUrl}?${search}` : relativeUrl;
+}
+function planClientRequest(endpoint, contractPrefix, args, config) {
+  let pathPrefix = resolvePathPrefix(config, args);
+  if (pathPrefix && !pathPrefix.endsWith("/"))
+    pathPrefix += "/";
+  if (pathPrefix.startsWith("/"))
+    pathPrefix = pathPrefix.slice(1);
+  const endpointPath = endpoint.path === "/" ? "" : endpoint.path;
+  let relativeUrl = fillPathParams(`${pathPrefix}${contractPrefix}${endpointPath}`, args);
+  if (relativeUrl.endsWith("/"))
+    relativeUrl = relativeUrl.slice(0, -1);
+  const remainingArgs = stripConsumedArgs(args, endpoint.path, config?.stripPrefixKeys ?? []);
+  if (inputIsQuery(endpoint.method)) {
+    relativeUrl = appendQuery(relativeUrl, collectQueryParams(remainingArgs, endpoint));
+  }
+  return { relativeUrl, remainingArgs };
+}
+function joinClientBaseUrl(baseUrl, relativeUrl) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
+  return `${base}${path}`;
+}
+// src/browser/stream.ts
+function parseFailure(raw, error, onParseError) {
+  const failure = error instanceof Error ? error : new Error(String(error));
+  if (!onParseError)
+    throw failure;
+  onParseError(raw, failure);
+}
+async function* parseNDJSON(response, options) {
+  try {
+    for await (const rawLine of readBoundedUtf8Lines(response, options?.maxLineBytes ?? DEFAULT_STREAM_LINE_BYTES, options?.finalLine === "require-newline")) {
+      const line = (rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine).trim();
+      if (line === "")
+        continue;
+      try {
+        yield JSON.parse(line);
+      } catch (error) {
+        parseFailure(line, error, options?.onParseError);
+      }
+    }
+  } catch (error) {
+    parseFailure("", error, options?.onParseError);
+  }
+}
+
+// src/browser/contract-stream.ts
+function sourceFor(response, descriptor) {
+  const options = {
+    maxLineBytes: descriptor.maxFrameBytes ?? DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+    finalLine: descriptor.finalLine
+  };
+  return descriptor.format === "sse" ? parseSSE(response, options) : parseNDJSON(response, options);
+}
+async function* readContractStream(response, descriptor, abort) {
+  let ended = false;
+  let terminalSeen = descriptor.terminal === undefined;
+  const source = sourceFor(response, descriptor);
+  try {
+    for (;; ) {
+      const next = await source.next();
+      if (next.done)
+        break;
+      let candidate = next.value;
+      if (descriptor.framing !== "item") {
+        const parsedFrame = ContractStreamFrameSchema.safeParse(candidate);
+        if (!parsedFrame.success) {
+          throw new ApiError("STREAM_PROTOCOL_ERROR", 0, undefined, "Stream frame did not match the protocol envelope");
+        }
+        const frame = parsedFrame.data;
+        if (frame.type === "error") {
+          throw new ApiError(frame.error.code, 0, frame.error.details, frame.error.message, frame.error.hint);
+        }
+        if (frame.type === "end") {
+          if (!terminalSeen) {
+            throw new ApiError("STREAM_TERMINAL_MISSING", 0, undefined, "Stream completed before its declared terminal item");
+          }
+          ended = true;
+          return;
+        }
+        candidate = frame.data;
+      }
+      const parsedItem = descriptor.item.safeParse(candidate);
+      if (!parsedItem.success) {
+        throw new ApiError("STREAM_ITEM_INVALID", 0, undefined, "Stream item did not match its contract");
+      }
+      const item = parsedItem.data;
+      const terminal = descriptor.terminal?.safeParse(item).success ?? false;
+      if (terminal)
+        terminalSeen = true;
+      if (terminal && descriptor.completion === "terminal") {
+        abort();
+        await source.return(undefined);
+        ended = true;
+      }
+      yield item;
+      if (ended)
+        return;
+    }
+    if (descriptor.framing === "item") {
+      if (terminalSeen)
+        return;
+      throw new ApiError("STREAM_TERMINAL_MISSING", 0, undefined, "Stream completed before its declared terminal item");
+    }
+    if (!ended) {
+      throw new ApiError("STREAM_TRUNCATED", 0, undefined, "Stream ended without its protocol terminal frame");
+    }
+  } finally {
+    abort();
+    await source.return(undefined);
+  }
+}
+
+class OwnedContractStream {
+  #inner;
+  #abort;
+  constructor(inner, abort) {
+    this.#inner = inner;
+    this.#abort = abort;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  next() {
+    return this.#inner.next();
+  }
+  return() {
+    this.#abort();
+    return this.#inner.return(undefined);
+  }
+  throw(error) {
+    this.#abort();
+    return this.#inner.throw(error);
+  }
+}
+function parseContractStream(response, descriptor, abort) {
+  return new OwnedContractStream(readContractStream(response, descriptor, abort), abort);
+}
+
+// src/browser/client.ts
+function withTimeout(options, endpoint) {
+  const responseType = endpoint.rawResponse || "stream" in endpoint ? "response" : endpoint.output ? undefined : "void";
+  if (endpoint.timeout === undefined && responseType === undefined)
+    return options;
+  return {
+    ...options,
+    ...endpoint.timeout !== undefined && { timeout: endpoint.timeout },
+    ...responseType && { responseType }
+  };
+}
+function withOutput(endpoint, result, abortStream) {
+  if (endpoint.rawResponse)
+    return result;
+  if ("stream" in endpoint && endpoint.stream) {
+    return result.then((value) => {
+      if (!(value instanceof Response)) {
+        abortStream?.();
+        throw new Error("Streaming endpoint did not return a Response");
+      }
+      return parseContractStream(value, endpoint.stream, abortStream ?? (() => {
+        return;
+      }));
+    }, (error) => {
+      abortStream?.();
+      throw error;
+    });
+  }
+  const schema = endpoint.output;
+  return result.then((value) => {
+    if (!schema) {
+      if (value === undefined || value === null)
+        return;
+      throw new Error("Server returned data for an endpoint with no output contract");
+    }
+    if (value === undefined) {
+      throw new Error("Server returned no body for an endpoint with an output contract");
+    }
+    return schema.parse(value);
+  });
+}
+function createClient(contract, configOrClient, contractConfig) {
+  const client = {};
+  const makeExecutor = isHttpAdapter(configOrClient) ? (endpoint) => createHttpExecutor(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchExecutor(endpoint, contract.meta.prefix, configOrClient, contractConfig);
+  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
+    if (endpoint.expose && !endpoint.expose.includes("HTTP"))
+      continue;
+    setClientMethod(client, key, createEndpointMethod(endpoint, makeExecutor(endpoint), contractConfig));
+  }
+  return client;
+}
+function createClients(contracts, configOrClient, contractConfig) {
+  return mapObject(contracts, (_key, contract) => createClient(contract, configOrClient, contractConfig));
+}
+function isHttpAdapter(value) {
+  return typeof value === "object" && "get" in value && typeof value.get === "function";
+}
+function setClientMethod(target, key, method) {
+  target[key] = method;
+}
+function createEndpointMethod(endpoint, execute, contractConfig) {
+  const hasScopedArguments = (contractConfig?.stripPrefixKeys?.length ?? 0) > 0;
+  if (endpointHasArguments(endpoint) || hasScopedArguments) {
+    const method2 = (requestArgs) => settle(execute, readClientRequestArgs(requestArgs), undefined);
+    return Object.assign(method2, {
+      withOptions: (...args) => {
+        refuseExtraWithOptionsArguments(endpoint, args.length, 2);
+        return settle(execute, readClientRequestArgs(args[0]), readClientRequestOptions(args[1]));
+      }
+    });
+  }
+  const method = () => settle(execute, {}, undefined);
+  return Object.assign(method, {
+    withOptions: (...args) => {
+      refuseExtraWithOptionsArguments(endpoint, args.length, 1);
+      return settle(execute, {}, readClientRequestOptions(args[0]));
+    }
+  });
+}
+function settle(execute, requestArgs, options) {
+  try {
+    return execute(requestArgs, options);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+function refuseExtraWithOptionsArguments(endpoint, received, expected) {
+  if (received <= expected)
+    return;
+  const shape = expected === 1 ? "withOptions(options)" : "withOptions(args, options)";
+  throw new TypeError(`${endpoint.method} ${endpoint.path}: this endpoint declares ${expected === 1 ? "no input" : "an input"}, so its method is ${shape} — it received ${received} arguments. ` + "An extra argument here is dropped, and a request options object in the dropped position " + "sends the request without them: an abort signal placed there never reaches the server.");
+}
+function createHttpExecutor(endpoint, prefix, client, config) {
+  const httpMethod = endpoint.method.toLowerCase();
+  return (requestArgs, options) => {
+    const plan = planClientRequest(endpoint, prefix, requestArgs, config);
+    const streamAbort = "stream" in endpoint ? new AbortController : undefined;
+    const requestOptions = streamAbort ? {
+      ...options,
+      signal: options?.signal ? AbortSignal.any([options.signal, streamAbort.signal]) : streamAbort.signal
+    } : options;
+    const finishStream = streamAbort ? () => streamAbort.abort() : undefined;
+    if (endpoint.multipart) {
+      if (httpMethod === "get" || httpMethod === "head" || httpMethod === "delete") {
+        throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
+      }
+      const formData = buildMultipartForm(endpoint.multipart, plan.remainingArgs);
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(requestOptions, endpoint)), finishStream);
+    }
+    if (httpMethod === "get" || httpMethod === "head") {
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(requestOptions, endpoint)), finishStream);
+    }
+    if (httpMethod === "delete") {
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(requestOptions, endpoint)), finishStream);
+    }
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(requestOptions, endpoint)), finishStream);
+  };
+}
+function createFetchExecutor(endpoint, prefix, config, contractConfig) {
+  const executeFetch = config.fetch ?? globalThis.fetch;
+  return async (requestArgs, options) => {
+    const plan = planClientRequest(endpoint, prefix, requestArgs, contractConfig);
+    const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
+    const headers = {
+      Accept: "application/json",
+      ...typeof config.headers === "function" ? config.headers() : config.headers
+    };
+    const streamAbort = "stream" in endpoint ? new AbortController : undefined;
+    const requestSignal = streamAbort ? options?.signal ? AbortSignal.any([options.signal, streamAbort.signal]) : streamAbort.signal : options?.signal;
+    const openTimeoutMs = endpoint.timeout ?? config.timeout ?? 30000;
+    const cancellation = streamAbort ? {
+      signal: requestSignal,
+      async run(operation) {
+        let timedOut = false;
+        const timer = setTimeout(() => {
+          timedOut = true;
+          streamAbort.abort(new DOMException("Request timed out", "TimeoutError"));
+        }, openTimeoutMs);
+        try {
+          if (options?.signal?.aborted)
+            throw new RequestCancellationError("caller");
+          return await operation(requestSignal);
+        } catch (error) {
+          if (timedOut)
+            throw new RequestCancellationError("timeout");
+          if (options?.signal?.aborted)
+            throw new RequestCancellationError("caller");
+          throw error;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+    } : createRequestCancellation(requestSignal, openTimeoutMs);
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && Object.keys(plan.remainingArgs).length > 0;
+    if (hasBody)
+      headers["Content-Type"] = "application/json";
+    try {
+      return await cancellation.run(async (signal) => {
+        const body = endpoint.multipart ? buildMultipartForm(endpoint.multipart, plan.remainingArgs) : hasBody ? JSON.stringify(plan.remainingArgs) : undefined;
+        const res = await executeFetch(url, {
+          method: endpoint.method,
+          headers,
+          credentials: config.credentials,
+          signal,
+          ...body !== undefined && { body }
+        });
+        if (!res.ok) {
+          await throwForErrorResponse(res, config, { error: res.statusText });
+        }
+        if (endpoint.rawResponse)
+          return res;
+        if ("stream" in endpoint && endpoint.stream) {
+          return parseContractStream(res, endpoint.stream, () => streamAbort?.abort());
+        }
+        if (!endpoint.output) {
+          const text = await res.text();
+          if (text.length > 0) {
+            throw new Error("Server returned data for an endpoint with no output contract");
+          }
+          return;
+        }
+        return endpoint.output.parse(await res.json());
+      });
+    } catch (error) {
+      if (error instanceof RequestCancellationError) {
+        throw new ApiError(error.cause === "caller" ? "REQUEST_ABORTED" : "REQUEST_TIMEOUT", 0, undefined, error.message);
+      }
+      if (ApiError.is(error))
+        throw error;
+      const message = error instanceof Error ? error.message : undefined;
+      throw new ApiError("UNKNOWN_ERROR", 0, message ? { message } : undefined, message, undefined, undefined, { cause: error });
+    }
+  };
+}
+function endpointHasArguments(endpoint) {
+  return Boolean(endpoint.params || endpoint.input || endpoint.multipart);
+}
+function readClientRequestArgs(requestArgs) {
+  if (requestArgs !== undefined && !isRecord(requestArgs)) {
+    throw new TypeError("Endpoint arguments must be an object");
+  }
+  return requestArgs ?? {};
+}
+function readClientRequestOptions(value) {
+  if (!isRecord(value))
+    throw new TypeError("Client request options must be an object");
+  const signal = value.signal;
+  if (signal === undefined)
+    return {};
+  if (!isAbortSignal(signal)) {
+    throw new TypeError("Client request signal must be an AbortSignal");
+  }
+  return { signal };
+}
+function isAbortSignal(value) {
+  return typeof value === "object" && value !== null && "aborted" in value && typeof value.aborted === "boolean" && "addEventListener" in value && typeof value.addEventListener === "function" && "removeEventListener" in value && typeof value.removeEventListener === "function";
+}
+async function throwForErrorResponse(res, config, fallbackBody) {
+  const body = await res.json().catch(() => fallbackBody);
+  config.onError?.(res.status, body);
+  const parsed = parseApiErrorBody(body);
+  if (parsed) {
+    throw new ApiError(parsed.code, res.status, parsed.details, parsed.message, parsed.hint, responseTraceId(res));
+  }
+  throw new ApiError("HTTP_ERROR", res.status, { body }, undefined, undefined, responseTraceId(res));
+}
+
 // src/agent-runtime/testing.ts
 function createAgentRaceBarrier(timeoutMs = 5000) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
@@ -1022,6 +1652,851 @@ function observeManagedResource(resource, required, trace) {
   };
 }
 
+// src/application/kernel.ts
+import { z as z2 } from "zod";
+
+// src/application/graph.ts
+function resolveResourceGraph(resources) {
+  const entries = resources.map((resource, declarationIndex) => ({
+    resource,
+    id: ApplicationIdSchema.parse(resource.id),
+    dependsOn: [...resource.dependsOn ?? []].map((dependency) => ApplicationIdSchema.parse(managedResourceDependencyId(dependency))),
+    required: resource.required ?? true,
+    declarationIndex
+  }));
+  const byId = new Map;
+  for (const entry of entries) {
+    if (byId.has(entry.id)) {
+      throw new Error(`[stitchkit] createApplication: duplicate resource id "${entry.id}"`);
+    }
+    byId.set(entry.id, entry);
+  }
+  for (const entry of entries) {
+    for (const dependencyId of entry.dependsOn) {
+      const dependency = byId.get(dependencyId);
+      if (!dependency) {
+        throw new Error(`[stitchkit] createApplication: resource "${entry.id}" depends on missing resource "${dependencyId}"`);
+      }
+      if (entry.required && !dependency.required) {
+        throw new Error(`[stitchkit] createApplication: required resource "${entry.id}" cannot depend on optional resource "${dependencyId}"`);
+      }
+    }
+  }
+  const pending = new Map(entries.map((entry) => [entry.id, entry]));
+  const resolved = new Set;
+  const ordered = [];
+  while (pending.size > 0) {
+    const ready = [...pending.values()].filter((entry) => entry.dependsOn.every((id) => resolved.has(id))).sort((left, right) => left.declarationIndex - right.declarationIndex);
+    if (ready.length === 0) {
+      throw new Error(`[stitchkit] createApplication: resource dependency cycle: ${[...pending.keys()].join(", ")}`);
+    }
+    for (const entry of ready) {
+      pending.delete(entry.id);
+      resolved.add(entry.id);
+      ordered.push(entry);
+    }
+  }
+  return ordered;
+}
+
+// src/application/kernel.ts
+class ResourceCompletionBeforeReadyError extends Error {
+  constructor(resourceId, cause) {
+    super(`[stitchkit] resource "${resourceId}" completed before reaching readiness`, {
+      ...cause !== undefined && { cause }
+    });
+    this.name = "ResourceCompletionBeforeReadyError";
+  }
+}
+
+class ApplicationStartupInterruptedError extends Error {
+  constructor() {
+    super("[stitchkit] application startup interrupted by shutdown");
+    this.name = "ApplicationStartupInterruptedError";
+  }
+}
+var ApplicationShutdownOptionsSchema = ShutdownOptionsSchema.pick({
+  gracePeriodMs: true,
+  forceTimeoutMs: true,
+  signal: true
+});
+var ApplicationShutdownBudgetSchema = ShutdownOptionsSchema.pick({
+  gracePeriodMs: true,
+  forceTimeoutMs: true
+});
+var ApplicationRestartInputSchema = z2.object({
+  resourceId: z2.string().min(1),
+  gracePeriodMs: z2.number().int().nonnegative().optional(),
+  forceTimeoutMs: z2.number().int().nonnegative().optional()
+}).strict().readonly();
+var ApplicationRestartOutcomeSchema = z2.enum(["restarted", "failed", "refused"]);
+var ApplicationRestartResultSchema = z2.object({
+  resourceId: z2.string(),
+  affected: z2.array(z2.string()).readonly(),
+  outcome: ApplicationRestartOutcomeSchema,
+  reason: z2.string().optional(),
+  durationMs: z2.number().int().nonnegative()
+}).strict().readonly();
+
+class ApplicationAdmissionError extends AppError {
+  constructor() {
+    super("APPLICATION_NOT_ACCEPTING", "Application is not accepting new operations", 503);
+    this.name = "ApplicationAdmissionError";
+  }
+}
+function isStartResult(value) {
+  return typeof value === "object" && value !== null;
+}
+function waitForAbort(signal) {
+  if (signal.aborted)
+    return Promise.resolve();
+  return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+async function untilDeadline(work, signal) {
+  const result = await Promise.race([
+    work.then((value) => ({ settled: true, value }), (error) => ({ settled: true, error })),
+    waitForAbort(signal).then(() => ({ settled: false }))
+  ]);
+  return result;
+}
+function createApplication(config) {
+  const id = ApplicationIdSchema.parse(config.id);
+  const ordered = resolveResourceGraph(config.resources ?? []);
+  const shutdownBudget = ApplicationShutdownBudgetSchema.parse(config.shutdown ?? {});
+  const reverse = [...ordered].reverse();
+  const reportFailure = (resourceId, phase, error) => {
+    if (!config.onResourceFailure)
+      return;
+    try {
+      Promise.resolve(config.onResourceFailure({ resourceId, phase, error })).catch(() => {
+        return;
+      });
+    } catch {}
+  };
+  const published = new Map;
+  const records = new Map;
+  for (const entry of ordered) {
+    records.set(entry.id, {
+      entry,
+      state: "registered",
+      health: "unknown",
+      healthReported: false,
+      everHealthy: false,
+      attempted: false,
+      activated: false,
+      closeInvoked: false,
+      closed: false,
+      failures: []
+    });
+  }
+  const epoch = crypto.randomUUID();
+  const listeners = new Set;
+  const lifetimeAbort = new AbortController;
+  const startupAbort = new AbortController;
+  let lifecycle = "created";
+  let revision = 0;
+  let changedAt = new Date().toISOString();
+  let accepting = false;
+  let accepted = 0;
+  let completed = 0;
+  let pending = 0;
+  let startPromise;
+  let shutdownPromise;
+  let shutdownRequested = false;
+  let activationComplete = false;
+  const pendingWaiters = new Set;
+  const aggregateHealth = () => {
+    if (lifecycle === "created" || lifecycle === "starting")
+      return "unknown";
+    let optionalUnhealthy = false;
+    for (const record of records.values()) {
+      if (record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+        return "unhealthy";
+      }
+      if (!record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+        optionalUnhealthy = true;
+      }
+    }
+    return optionalUnhealthy ? "degraded" : "healthy";
+  };
+  const isReady = () => lifecycle === "ready" && [...records.values()].every((record) => !record.entry.required || record.state === "ready" && record.health === "healthy");
+  const snapshot = () => ApplicationSnapshotSchema.parse({
+    id,
+    epoch,
+    revision,
+    lifecycle,
+    health: aggregateHealth(),
+    ready: isReady(),
+    capturedAt: new Date().toISOString(),
+    changedAt,
+    admission: { accepting, accepted, completed, pending },
+    resources: ordered.map((entry) => {
+      const record = records.get(entry.id);
+      if (!record)
+        throw new Error("Managed resource record disappeared");
+      return {
+        id: entry.id,
+        required: entry.required,
+        dependsOn: entry.dependsOn,
+        state: record.state,
+        health: record.health,
+        ready: record.state === "ready" && record.health === "healthy"
+      };
+    })
+  });
+  const publish = () => {
+    revision += 1;
+    changedAt = new Date().toISOString();
+    const value = snapshot();
+    for (const listener of listeners) {
+      try {
+        listener(value);
+      } catch {}
+    }
+    if (config.onSnapshot) {
+      Promise.resolve().then(() => config.onSnapshot?.(value)).catch(() => {});
+    }
+  };
+  const contextFor = (record, options = {}) => ({
+    applicationId: id,
+    signal: options.signal ?? lifetimeAbort.signal,
+    ...options.deadlineAt !== undefined && { deadlineAt: options.deadlineAt },
+    ...options.forceDeadlineAt !== undefined && {
+      forceDeadlineAt: options.forceDeadlineAt
+    },
+    now: () => performance.now(),
+    use(resource) {
+      const dependencyId = resource?.id;
+      if (typeof dependencyId !== "string" || dependencyId.length === 0) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}": use() takes a managed resource, and this one has no id`);
+      }
+      if (!record.entry.dependsOn.includes(dependencyId)) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}" used "${dependencyId}" without declaring it in dependsOn`);
+      }
+      if (!published.has(dependencyId)) {
+        throw new Error(`[stitchkit] resource "${record.entry.id}" used "${dependencyId}", which published no value from start()`);
+      }
+      return published.get(dependencyId);
+    },
+    reportHealth(health) {
+      if (record.state === "stopped")
+        return;
+      record.health = health;
+      record.healthReported = true;
+      if (health === "healthy")
+        record.everHealthy = true;
+      accepting = activationComplete && !shutdownRequested && isReady();
+      publish();
+    }
+  });
+  const markLateCompletion = (record, failure) => {
+    if (shutdownRequested || record.state === "stopping" || record.state === "stopped")
+      return;
+    if (failure) {
+      record.failures.push("completion");
+      reportFailure(record.entry.id, "completion", failure.error);
+    }
+    record.state = "failed";
+    record.health = "unhealthy";
+    accepting = activationComplete && isReady();
+    publish();
+  };
+  const closeAttempted = async () => {
+    const errors = [];
+    const rollbackStartedAt = performance.now();
+    const rollbackDeadlineAt = rollbackStartedAt + shutdownBudget.gracePeriodMs;
+    const rollbackForceDeadlineAt = rollbackDeadlineAt + shutdownBudget.forceTimeoutMs;
+    const rollbackAbort = new AbortController;
+    const rollbackTimer = setTimeout(() => rollbackAbort.abort(), Math.max(0, rollbackForceDeadlineAt - performance.now()));
+    try {
+      await closeEachAttempted(rollbackAbort.signal, errors, {
+        deadlineAt: rollbackDeadlineAt,
+        forceDeadlineAt: rollbackForceDeadlineAt
+      });
+    } finally {
+      clearTimeout(rollbackTimer);
+    }
+    return errors;
+  };
+  const closeEachAttempted = async (bound, errors, deadlines) => {
+    for (const entry of reverse) {
+      const record = records.get(entry.id);
+      if (!record?.attempted || record.closed)
+        continue;
+      record.state = "stopping";
+      try {
+        record.closeInvoked = true;
+        const settled = await untilDeadline(Promise.resolve(entry.resource.close?.(contextFor(record, { signal: startupAbort.signal, ...deadlines }))), bound);
+        if (!settled.settled) {
+          record.failures.push("close");
+          record.state = "failed";
+          const timedOut = new Error(`[stitchkit] resource "${entry.id}" did not finish closing during rollback`);
+          reportFailure(entry.id, "close", timedOut);
+          errors.push(timedOut);
+          publish();
+          break;
+        }
+        if (settled.error !== undefined)
+          throw settled.error;
+        record.closed = true;
+        record.state = "stopped";
+      } catch (error) {
+        record.failures.push("close");
+        record.state = "failed";
+        reportFailure(entry.id, "close", error);
+        errors.push(error);
+      }
+      publish();
+    }
+  };
+  const startEach = async (entries, signal) => {
+    for (const entry of entries) {
+      if (shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      const record = records.get(entry.id);
+      if (!record)
+        throw new Error("Managed resource record disappeared");
+      const dependencyFailed = entry.dependsOn.some((dependencyId) => records.get(dependencyId)?.state !== "ready");
+      if (dependencyFailed) {
+        record.state = "failed";
+        record.health = "unhealthy";
+        record.failures.push("start");
+        publish();
+        if (entry.required) {
+          throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable dependency`);
+        }
+        continue;
+      }
+      record.attempted = true;
+      record.state = "starting";
+      publish();
+      try {
+        const started = await entry.resource.start(contextFor(record, { signal }));
+        if (shutdownRequested || signal.aborted) {
+          throw new ApplicationStartupInterruptedError;
+        }
+        if (isStartResult(started)) {
+          record.runtime = started;
+          if (started.value !== undefined)
+            published.set(entry.id, started.value);
+          let resourceReady = started.ready === undefined;
+          let completionSettled = false;
+          let completionFailure;
+          const completion = started.completion?.then(() => {
+            completionSettled = true;
+            if (resourceReady)
+              markLateCompletion(record);
+          }, (error) => {
+            completionSettled = true;
+            completionFailure = error;
+            if (resourceReady)
+              markLateCompletion(record, { error });
+          });
+          if (started.ready && completion) {
+            const readiness = started.ready.then(() => "ready");
+            const completionBeforeReady = completion.then(() => "completion");
+            const first = await Promise.race([readiness, completionBeforeReady]);
+            if (first === "completion") {
+              throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+            }
+            resourceReady = true;
+            if (completionSettled) {
+              throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+            }
+          } else if (started.ready) {
+            await started.ready;
+            resourceReady = true;
+          } else if (completion) {}
+        }
+        if (shutdownRequested || signal.aborted) {
+          throw new ApplicationStartupInterruptedError;
+        }
+        record.state = "ready";
+        if (!record.healthReported) {
+          record.health = "healthy";
+          record.everHealthy = true;
+        }
+        publish();
+      } catch (error) {
+        const interrupted = shutdownRequested || signal.aborted;
+        if (!(error instanceof ApplicationStartupInterruptedError)) {
+          record.failures.push(error instanceof ResourceCompletionBeforeReadyError ? "completion" : record.runtime?.ready ? "ready" : "start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          reportFailure(entry.id, record.failures[record.failures.length - 1] ?? "start", error);
+          publish();
+        }
+        if (interrupted || entry.required)
+          throw error;
+      }
+    }
+  };
+  const activateEach = async (entries, signal) => {
+    for (const entry of entries) {
+      if (shutdownRequested || signal.aborted) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      const record = records.get(entry.id);
+      if (record?.state !== "ready")
+        continue;
+      const dependencyUnavailable = entry.dependsOn.some((dependencyId) => {
+        const dependency = records.get(dependencyId);
+        return dependency?.state !== "ready" || !dependency.activated;
+      });
+      if (dependencyUnavailable) {
+        record.failures.push("start");
+        record.state = "failed";
+        record.health = "unhealthy";
+        publish();
+        if (entry.required) {
+          throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable activation dependency`);
+        }
+        continue;
+      }
+      try {
+        await entry.resource.activate?.(contextFor(record));
+        if (shutdownRequested || signal.aborted) {
+          throw new ApplicationStartupInterruptedError;
+        }
+        record.activated = true;
+        if (entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+          const observed = `${record.state}/${record.health}`;
+          throw new Error(record.everHealthy ? `[stitchkit] required resource "${entry.id}" lost readiness during activation (${observed})` : `[stitchkit] required resource "${entry.id}" is not healthy (${observed}). A required resource must be healthy for the application to be ready; a resource that is expected to start degraded belongs behind \`required: false\`.`);
+        }
+      } catch (error) {
+        const interrupted = shutdownRequested || signal.aborted;
+        if (!(error instanceof ApplicationStartupInterruptedError)) {
+          record.failures.push("start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          reportFailure(entry.id, "start", error);
+          publish();
+        }
+        if (interrupted || entry.required)
+          throw error;
+      }
+    }
+  };
+  const subtreeOf = (resourceId) => {
+    const affected = new Set([resourceId]);
+    for (const entry of ordered) {
+      if (entry.dependsOn.some((dependencyId) => affected.has(dependencyId))) {
+        affected.add(entry.id);
+      }
+    }
+    return ordered.filter((entry) => affected.has(entry.id));
+  };
+  const closeOne = async (entry, record, signal, deadlines) => {
+    const context = () => contextFor(record, { ...deadlines, signal });
+    if (record.attempted && !record.closed) {
+      const phase = async (work, what) => {
+        const settled = await untilDeadline(Promise.resolve(work), signal);
+        if (!settled.settled) {
+          throw new Error(`[stitchkit] resource "${entry.id}" did not ${what} within the restart budget`);
+        }
+        if (settled.error !== undefined)
+          throw settled.error;
+      };
+      await phase(entry.resource.stopAdmission?.(context()), "stop admitting");
+      await phase(entry.resource.drain?.(context()), "drain");
+      record.closeInvoked = true;
+      await phase(entry.resource.close?.(context()), "close");
+    }
+    record.closed = false;
+    record.closeInvoked = false;
+    record.attempted = false;
+    record.activated = false;
+    record.state = "registered";
+    record.health = "unknown";
+    record.healthReported = false;
+    record.runtime = undefined;
+    published.delete(entry.id);
+  };
+  let restarting = Promise.resolve();
+  const runRestart = async (input) => {
+    const startedAt = Date.now();
+    const parsed = ApplicationRestartInputSchema.parse(input);
+    const affected = subtreeOf(parsed.resourceId);
+    const affectedIds = affected.map((entry) => entry.id);
+    const refuse = (reason) => ({
+      resourceId: parsed.resourceId,
+      affected: affectedIds,
+      outcome: "refused",
+      reason,
+      durationMs: Date.now() - startedAt
+    });
+    if (!records.has(parsed.resourceId)) {
+      return refuse(`no resource is registered as "${parsed.resourceId}"`);
+    }
+    if (shutdownRequested) {
+      return refuse("the application is shutting down");
+    }
+    if (lifecycle !== "ready") {
+      return refuse(`the application is ${lifecycle}, not ready`);
+    }
+    const budget = {
+      gracePeriodMs: parsed.gracePeriodMs ?? shutdownBudget.gracePeriodMs,
+      forceTimeoutMs: parsed.forceTimeoutMs ?? shutdownBudget.forceTimeoutMs
+    };
+    const closeDeadlineAt = performance.now() + budget.gracePeriodMs;
+    const deadlines = {
+      deadlineAt: closeDeadlineAt,
+      forceDeadlineAt: closeDeadlineAt + budget.forceTimeoutMs
+    };
+    const restartAbort = new AbortController;
+    const closeTimer = setTimeout(() => restartAbort.abort(), Math.max(0, deadlines.forceDeadlineAt - performance.now()));
+    const stillFailed = () => affectedIds.filter((id2) => records.get(id2)?.state === "failed");
+    try {
+      for (const entry of [...affected].reverse()) {
+        const record = records.get(entry.id);
+        if (record)
+          await closeOne(entry, record, restartAbort.signal, deadlines);
+      }
+      publish();
+      await startEach(affected, restartAbort.signal);
+      await activateEach(affected, restartAbort.signal);
+      publish();
+      const failed = stillFailed();
+      if (failed.length > 0) {
+        return {
+          resourceId: parsed.resourceId,
+          affected: affectedIds,
+          outcome: "failed",
+          reason: `did not come back: ${failed.join(", ")}`,
+          durationMs: Date.now() - startedAt
+        };
+      }
+      return {
+        resourceId: parsed.resourceId,
+        affected: affectedIds,
+        outcome: "restarted",
+        durationMs: Date.now() - startedAt
+      };
+    } catch (error) {
+      restartAbort.abort();
+      publish();
+      return {
+        resourceId: parsed.resourceId,
+        affected: affectedIds,
+        outcome: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - startedAt
+      };
+    } finally {
+      clearTimeout(closeTimer);
+    }
+  };
+  const runStart = async () => {
+    lifecycle = "starting";
+    publish();
+    let startFailure;
+    try {
+      await startEach(ordered, startupAbort.signal);
+      lifecycle = "ready";
+      publish();
+      await activateEach(ordered, startupAbort.signal);
+      if (shutdownRequested) {
+        throw new ApplicationStartupInterruptedError;
+      }
+      if (!isReady()) {
+        const blocking = [...records.values()].filter((record) => record.entry.required && (record.state !== "ready" || record.health !== "healthy")).map((record) => `${record.entry.id} (${record.state}/${record.health})`);
+        if (blocking.length === 0)
+          blocking.push("(none identified)");
+        const chosen = [...records.values()].some((record) => record.entry.required && record.health !== "healthy" && !record.everHealthy);
+        throw new Error(`[stitchkit] the application is not ready after startup — required ${blocking.length === 1 ? "resource" : "resources"} ${blocking.join(", ")}. A required resource must be healthy for the application to be ready; ${chosen ? "a resource that is expected to start degraded belongs behind `required: false`." : "this one was healthy and stopped being so — read `onResourceFailure` for the cause."}`);
+      }
+      activationComplete = true;
+      accepting = isReady();
+      publish();
+      return snapshot();
+    } catch (error) {
+      startFailure = error;
+    }
+    if (!shutdownRequested) {
+      const rollbackErrors = await closeAttempted();
+      lifecycle = "failed";
+      accepting = false;
+      publish();
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError([startFailure, ...rollbackErrors], "[stitchkit] application startup and rollback failed", { cause: startFailure });
+      }
+    }
+    throw startFailure;
+  };
+  const start = () => {
+    if (startPromise)
+      return startPromise;
+    if (lifecycle !== "created") {
+      return Promise.reject(new Error(`[stitchkit] application cannot start from lifecycle "${lifecycle}"`));
+    }
+    startPromise = runStart();
+    startPromise.catch(() => {
+      return;
+    });
+    return startPromise;
+  };
+  const acquire = () => {
+    if (!accepting || !isReady())
+      return null;
+    accepted += 1;
+    pending += 1;
+    publish();
+    let released = false;
+    return {
+      get released() {
+        return released;
+      },
+      release() {
+        if (released)
+          return;
+        released = true;
+        pending -= 1;
+        completed += 1;
+        if (pending === 0) {
+          for (const waiter of pendingWaiters)
+            waiter();
+          pendingWaiters.clear();
+        }
+        publish();
+      }
+    };
+  };
+  const run = async (work) => {
+    const lease = acquire();
+    if (!lease)
+      throw new ApplicationAdmissionError;
+    try {
+      return await work();
+    } finally {
+      lease.release();
+    }
+  };
+  const waitForPending = () => {
+    if (pending === 0)
+      return Promise.resolve();
+    return new Promise((resolve) => pendingWaiters.add(resolve));
+  };
+  const shutdown = (options) => {
+    if (shutdownPromise)
+      return shutdownPromise;
+    const requested = options ?? {};
+    const parsed = ApplicationShutdownOptionsSchema.parse({
+      gracePeriodMs: requested.gracePeriodMs ?? shutdownBudget.gracePeriodMs,
+      forceTimeoutMs: requested.forceTimeoutMs ?? shutdownBudget.forceTimeoutMs,
+      ...requested.signal !== undefined && { signal: requested.signal }
+    });
+    const startedAt = performance.now();
+    const graceDeadlineAt = startedAt + parsed.gracePeriodMs;
+    const forceDeadlineAt = graceDeadlineAt + parsed.forceTimeoutMs;
+    shutdownRequested = true;
+    accepting = false;
+    startupAbort.abort();
+    lifecycle = lifecycle === "created" ? "stopping" : "draining";
+    publish();
+    shutdownPromise = (async () => {
+      const gracefulAbort = new AbortController;
+      let forcedReason;
+      let gracefulFailed = [...records.values()].some((record) => record.attempted && record.closeInvoked && !record.closed);
+      const force = (reason) => {
+        if (forcedReason)
+          return;
+        forcedReason = reason;
+        gracefulAbort.abort();
+        lifetimeAbort.abort();
+      };
+      const graceTimer = setTimeout(() => force("deadline"), Math.max(0, graceDeadlineAt - performance.now()));
+      const onExternalAbort = () => force("signal");
+      parsed.signal?.addEventListener("abort", onExternalAbort, { once: true });
+      if (parsed.signal?.aborted)
+        force("signal");
+      if (startPromise) {
+        await untilDeadline(startPromise.catch(() => {
+          return;
+        }), gracefulAbort.signal);
+      }
+      const gracefulContext = (record) => contextFor(record, {
+        signal: gracefulAbort.signal,
+        deadlineAt: graceDeadlineAt,
+        forceDeadlineAt
+      });
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        try {
+          const result = await untilDeadline(Promise.resolve(entry.resource.stopAdmission?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!result.settled)
+            break;
+          if (result.error !== undefined)
+            throw result.error;
+        } catch (error) {
+          record.failures.push("admission");
+          reportFailure(entry.id, "admission", error);
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+        }
+      }
+      if (!gracefulAbort.signal.aborted && !gracefulFailed) {
+        const result = await untilDeadline(waitForPending(), gracefulAbort.signal);
+        if (!result.settled)
+          force("deadline");
+      }
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        record.state = "stopping";
+        publish();
+        try {
+          const drained = await untilDeadline(Promise.resolve(entry.resource.drain?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!drained.settled) {
+            force("deadline");
+            break;
+          }
+          if (drained.error !== undefined)
+            throw drained.error;
+        } catch (error) {
+          record.failures.push("drain");
+          reportFailure(entry.id, "drain", error);
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          break;
+        }
+      }
+      lifecycle = "stopping";
+      publish();
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed || record.closeInvoked)
+          continue;
+        try {
+          record.closeInvoked = true;
+          const closed = await untilDeadline(Promise.resolve(entry.resource.close?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!closed.settled) {
+            force("deadline");
+            break;
+          }
+          if (closed.error !== undefined)
+            throw closed.error;
+          record.closed = true;
+          record.state = "stopped";
+          publish();
+        } catch (error) {
+          record.failures.push("close");
+          reportFailure(entry.id, "close", error);
+          record.state = "failed";
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          publish();
+          break;
+        }
+      }
+      clearTimeout(graceTimer);
+      parsed.signal?.removeEventListener("abort", onExternalAbort);
+      const mustForce = forcedReason !== undefined || gracefulFailed;
+      const pendingOperationsAtForce = mustForce ? pending : 0;
+      if (mustForce) {
+        lifetimeAbort.abort();
+        const forceAbort = new AbortController;
+        const forceTimer = setTimeout(() => forceAbort.abort(), Math.max(0, forceDeadlineAt - performance.now()));
+        await Promise.all(reverse.map(async (entry) => {
+          const record = records.get(entry.id);
+          if (!record?.attempted || record.closed)
+            return;
+          try {
+            let cleanup;
+            if (entry.resource.force) {
+              cleanup = Promise.resolve(entry.resource.force(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close && !record.closeInvoked) {
+              record.closeInvoked = true;
+              cleanup = Promise.resolve(entry.resource.close(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close) {
+              record.failures.push("force");
+              reportFailure(entry.id, "force", new Error(`[stitchkit] resource "${entry.id}" was already closing and did not settle before the force deadline`));
+              return;
+            }
+            const forced = await untilDeadline(cleanup ?? Promise.resolve(), forceAbort.signal);
+            if (!forced.settled || forced.error !== undefined) {
+              record.failures.push("force");
+              reportFailure(entry.id, "force", forced.settled ? forced.error : new Error("[stitchkit] forced cleanup did not settle in time"));
+              return;
+            }
+            record.closed = true;
+            record.state = "stopped";
+          } catch (error) {
+            record.failures.push("force");
+            reportFailure(entry.id, "force", error);
+          }
+        }));
+        clearTimeout(forceTimer);
+      }
+      const cleanupComplete = [...records.values()].every((record) => !record.attempted || record.closed);
+      lifecycle = cleanupComplete ? "stopped" : "failed";
+      publish();
+      return ApplicationShutdownResultSchema.parse({
+        outcome: mustForce ? "forced" : "clean",
+        ...forcedReason && { reason: forcedReason },
+        cleanupComplete,
+        acceptedOperations: accepted,
+        completedOperations: completed,
+        pendingOperations: pending,
+        pendingOperationsAtForce,
+        resources: ordered.map((entry) => {
+          const record = records.get(entry.id);
+          if (!record)
+            throw new Error("Managed resource record disappeared");
+          return {
+            id: entry.id,
+            state: !record.attempted ? "not-started" : record.closed ? "closed" : "force-failed",
+            failures: record.failures
+          };
+        }),
+        durationMs: performance.now() - startedAt
+      });
+    })();
+    shutdownPromise.catch(() => {
+      return;
+    });
+    return shutdownPromise;
+  };
+  return {
+    id,
+    admission: { acquire, run },
+    start,
+    getSnapshot: snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(snapshot());
+      return () => listeners.delete(listener);
+    },
+    shutdown,
+    restart(input) {
+      const queued = restarting.then(() => runRestart(input));
+      restarting = queued.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+      return queued;
+    }
+  };
+}
+
 // src/testing/managed-resource-conformance-scenarios.ts
 var MANAGED_RESOURCE_CONFORMANCE_SCENARIOS = ManagedResourceConformanceScenarioSchema.array().parse([
   { id: "clean-shutdown", required: true },
@@ -1389,90 +2864,90 @@ async function runManagedResourceConformance(config) {
   }
 }
 // src/testing/surface-conformance.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/realtime/contract.ts
-import { z as z2 } from "zod";
-var RealtimeRejectDirectionSchema = z2.enum([
+import { z as z3 } from "zod";
+var RealtimeRejectDirectionSchema = z3.enum([
   "client-inbound",
   "client-outbound",
   "server-inbound",
   "server-outbound"
 ]);
-var RealtimeRejectPhaseSchema = z2.enum(["arguments", "acknowledgement"]);
-var RealtimeRejectReasonSchema = z2.enum([
+var RealtimeRejectPhaseSchema = z3.enum(["arguments", "acknowledgement"]);
+var RealtimeRejectReasonSchema = z3.enum([
   "unknown-event",
   "invalid-arguments",
   "invalid-acknowledgement-value",
   "missing-acknowledgement",
   "rejected-by-peer"
 ]);
-var RealtimeRejectFaultSchema = z2.enum(["peer", "local"]);
+var RealtimeRejectFaultSchema = z3.enum(["peer", "local"]);
 
 // src/testing/surface-manifest.ts
 import { createHash } from "node:crypto";
-import { z as z3 } from "zod";
-var HttpMethodSchema = z3.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
-var ToolTransportSchema = z3.enum(["MCP", "AGENT", "CLI"]);
-var SurfaceTransportSchema = z3.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
-var SurfaceSchemaDigestsSchema = z3.object({
-  params: z3.string().nullable(),
-  input: z3.string().nullable(),
-  output: z3.string().nullable(),
-  multipart: z3.string().nullable()
+import { z as z4 } from "zod";
+var HttpMethodSchema = z4.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var ToolTransportSchema = z4.enum(["MCP", "AGENT", "CLI"]);
+var SurfaceTransportSchema = z4.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
+var SurfaceSchemaDigestsSchema = z4.object({
+  params: z4.string().nullable(),
+  input: z4.string().nullable(),
+  output: z4.string().nullable(),
+  multipart: z4.string().nullable()
 });
-var SurfaceManifestOperationSchema = z3.object({
-  kind: z3.enum(["contract", "runtime"]),
-  service: z3.string(),
-  action: z3.string(),
+var SurfaceManifestOperationSchema = z4.object({
+  kind: z4.enum(["contract", "runtime"]),
+  service: z4.string(),
+  action: z4.string(),
   method: HttpMethodSchema,
-  scope: z3.string().nullable(),
-  description: z3.string(),
+  scope: z4.string().nullable(),
+  description: z4.string(),
   schemas: SurfaceSchemaDigestsSchema,
-  http: z3.array(z3.object({ method: HttpMethodSchema, path: z3.string() }))
+  http: z4.array(z4.object({ method: HttpMethodSchema, path: z4.string() }))
 });
-var SurfaceManifestToolSchema = z3.object({
-  kind: z3.enum(["contract", "runtime"]),
-  service: z3.string(),
-  action: z3.string(),
-  name: z3.string(),
-  input: z3.string()
+var SurfaceManifestToolSchema = z4.object({
+  kind: z4.enum(["contract", "runtime"]),
+  service: z4.string(),
+  action: z4.string(),
+  name: z4.string(),
+  input: z4.string()
 });
-var SurfaceManifestToolSurfaceSchema = z3.object({
+var SurfaceManifestToolSurfaceSchema = z4.object({
   transport: ToolTransportSchema,
-  surface: z3.string().nullable(),
-  tools: z3.array(SurfaceManifestToolSchema)
+  surface: z4.string().nullable(),
+  tools: z4.array(SurfaceManifestToolSchema)
 });
-var SurfaceManifestCliCommandSchema = z3.object({
-  name: z3.string(),
-  description: z3.string(),
-  input: z3.string(),
-  output: z3.string().nullable()
+var SurfaceManifestCliCommandSchema = z4.object({
+  name: z4.string(),
+  description: z4.string(),
+  input: z4.string(),
+  output: z4.string().nullable()
 });
-var SurfaceManifestExtensionSchema = z3.object({
-  name: z3.string(),
+var SurfaceManifestExtensionSchema = z4.object({
+  name: z4.string(),
   transport: SurfaceTransportSchema
 });
-var SurfaceRealtimeSchemaPairSchema = z3.object({
-  input: z3.string(),
-  output: z3.string()
+var SurfaceRealtimeSchemaPairSchema = z4.object({
+  input: z4.string(),
+  output: z4.string()
 });
-var SurfaceManifestRealtimeEventSchema = z3.object({
-  contract: z3.string(),
-  direction: z3.enum(["serverToClient", "clientToServer"]),
-  event: z3.string(),
+var SurfaceManifestRealtimeEventSchema = z4.object({
+  contract: z4.string(),
+  direction: z4.enum(["serverToClient", "clientToServer"]),
+  event: z4.string(),
   args: SurfaceRealtimeSchemaPairSchema,
   acknowledgement: SurfaceRealtimeSchemaPairSchema.nullable()
 });
-var SurfaceManifestSchema = z3.object({
-  manifestVersion: z3.literal(2),
-  digestVersion: z3.literal(1),
-  operations: z3.array(SurfaceManifestOperationSchema),
-  toolSurfaces: z3.array(SurfaceManifestToolSurfaceSchema),
-  realtimeContracts: z3.array(z3.string()),
-  realtime: z3.array(SurfaceManifestRealtimeEventSchema),
-  cliOnly: z3.array(SurfaceManifestCliCommandSchema),
-  extensions: z3.array(SurfaceManifestExtensionSchema)
+var SurfaceManifestSchema = z4.object({
+  manifestVersion: z4.literal(2),
+  digestVersion: z4.literal(1),
+  operations: z4.array(SurfaceManifestOperationSchema),
+  toolSurfaces: z4.array(SurfaceManifestToolSurfaceSchema),
+  realtimeContracts: z4.array(z4.string()),
+  realtime: z4.array(SurfaceManifestRealtimeEventSchema),
+  cliOnly: z4.array(SurfaceManifestCliCommandSchema),
+  extensions: z4.array(SurfaceManifestExtensionSchema)
 });
 function compareCodepoints(left, right) {
   if (left < right)
@@ -1753,37 +3228,37 @@ actual: ${actual}`);
 }
 
 // src/testing/surface-conformance.ts
-var RealtimeRejectionObservationSchema = z4.object({
+var RealtimeRejectionObservationSchema = z5.object({
   direction: RealtimeRejectDirectionSchema,
   phase: RealtimeRejectPhaseSchema,
   reason: RealtimeRejectReasonSchema,
   fault: RealtimeRejectFaultSchema
 });
 var ObservationFields = {
-  code: z4.string().optional(),
-  data: z4.unknown().optional(),
-  diagnostic: z4.string().optional(),
-  handlerCalls: z4.number().int().nonnegative().optional()
+  code: z5.string().optional(),
+  data: z5.unknown().optional(),
+  diagnostic: z5.string().optional(),
+  handlerCalls: z5.number().int().nonnegative().optional()
 };
-var RealtimeDisconnectObservationSchema = z4.object({
-  phase: z4.enum(["before-invoke", "in-flight"])
+var RealtimeDisconnectObservationSchema = z5.object({
+  phase: z5.enum(["before-invoke", "in-flight"])
 });
-var TransportObservationSchema = z4.discriminatedUnion("outcome", [
-  z4.object({ outcome: z4.literal("success"), ...ObservationFields }),
-  z4.object({ outcome: z4.literal("validation_error"), ...ObservationFields }),
-  z4.object({ outcome: z4.literal("domain_error"), ...ObservationFields }),
-  z4.object({ outcome: z4.literal("aborted"), ...ObservationFields }),
-  z4.object({
-    outcome: z4.literal("realtime_rejected"),
+var TransportObservationSchema = z5.discriminatedUnion("outcome", [
+  z5.object({ outcome: z5.literal("success"), ...ObservationFields }),
+  z5.object({ outcome: z5.literal("validation_error"), ...ObservationFields }),
+  z5.object({ outcome: z5.literal("domain_error"), ...ObservationFields }),
+  z5.object({ outcome: z5.literal("aborted"), ...ObservationFields }),
+  z5.object({
+    outcome: z5.literal("realtime_rejected"),
     ...ObservationFields,
     rejection: RealtimeRejectionObservationSchema
   }),
-  z4.object({
-    outcome: z4.literal("disconnected"),
+  z5.object({
+    outcome: z5.literal("disconnected"),
     ...ObservationFields,
     disconnect: RealtimeDisconnectObservationSchema
   }),
-  z4.object({ outcome: z4.literal("timeout"), ...ObservationFields })
+  z5.object({ outcome: z5.literal("timeout"), ...ObservationFields })
 ]);
 function scenarioOutcome(scenario) {
   if (scenario === "event" || scenario === "acknowledgement")