stitchkit 0.107.0 → 0.108.1

package/dist/entrypoints/telegram.js

@@ -2,18 +2,23 @@ import {
   backoffDelay
 } from "../index-g6a3na27.js";
 import"../index-2kbysk9s.js";
-import"../index-7r74re56.js";
+import"../index-bh2ht9y5.js";
 import {
   attemptExclusiveLock
-} from "../index-bnf8s6v3.js";
+} from "../index-t2bsd0hm.js";
 import {
+  TelegramNotDispatchedError2,
+  isTelegramNotDispatchedError,
   TELEGRAM_SEND_FAILURE_REASONS2,
   classifyTelegramSendFailure2
-} from "../index-e05cjgtf.js";
+} from "../index-xvj9h8yh.js";
 import {
   TELEGRAM_TEXT_LIMIT2,
   truncateTelegramHtml2
 } from "../index-nmaqxdx7.js";
+import {
+  untilAborted
+} from "../index-a5qr2rj6.js";
 import {
   raceAbort
 } from "../index-b0kddvzw.js";
@@ -24,6 +29,9 @@ import {
   MAX_TIMER_MS,
   sleep
 } from "../index-eemvahkc.js";
+import {
+  assertPositiveSafeInteger
+} from "../index-0s4xebbg.js";
 import {
   BOT_TOKEN_SECRET
 } from "../index-sznqf8fx.js";
@@ -72,6 +80,8 @@ async function callTelegramBotApi(call) {
   } catch (error) {
     if (call.signal?.aborted)
       throw call.signal.reason;
+    if (isTelegramNotDispatchedError(error))
+      throw error;
     const kind = error instanceof Error ? error.name : "Error";
     throw new Error(`Telegram ${call.method} request failed (${kind})`);
   }
@@ -888,6 +898,328 @@ function telegramOperatorSender(config) {
     ...config.fetch && { fetch: config.fetch }
   });
 }
+// src/telegram/transport-connect.ts
+import { lookup } from "node:dns/promises";
+import { connect as connectTcp, isIP } from "node:net";
+import { connect as connectTls } from "node:tls";
+var NEXT_ADDRESS_DELAY_MS = 250;
+var MAX_ROUNDS = 3;
+var resolveAll = async (host) => (await lookup(host, { all: true, verbatim: true })).map((entry) => entry.address);
+var openSocket = ({ address, port, tls, servername }) => tls ? connectTls({
+  host: address,
+  port,
+  ...servername !== undefined && { servername },
+  ALPNProtocols: ["http/1.1"]
+}) : connectTcp({ host: address, port });
+var connectedEvent = (socket) => ("encrypted" in socket) && socket.encrypted ? "secureConnect" : "connect";
+function race(addresses, target, open, timeoutMs, signal) {
+  return new Promise((resolve) => {
+    const sockets = [];
+    const timers = [];
+    let failed = 0;
+    let started = 0;
+    let lastFailure;
+    let settled = false;
+    const finish = (winner) => {
+      if (settled)
+        return;
+      settled = true;
+      for (const timer of timers)
+        clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      for (const socket of sockets)
+        if (socket !== winner)
+          socket.destroy();
+      resolve(winner ? { socket: winner } : { failure: lastFailure });
+    };
+    const abort = () => finish(undefined);
+    const failOne = (cause) => {
+      lastFailure = cause;
+      if (++failed === addresses.length)
+        finish(undefined);
+      else
+        launchNext();
+    };
+    const launchNext = () => {
+      if (settled)
+        return;
+      const address = addresses[started++];
+      if (address === undefined)
+        return;
+      let socket;
+      try {
+        socket = open({ address, ...target });
+      } catch (cause) {
+        failOne(cause);
+        return;
+      }
+      sockets.push(socket);
+      socket.once(connectedEvent(socket), () => finish(socket));
+      socket.once("error", (cause) => {
+        socket.destroy();
+        failOne(cause);
+      });
+      if (started < addresses.length)
+        timers.push(setTimeout(launchNext, NEXT_ADDRESS_DELAY_MS));
+    };
+    timers.push(setTimeout(() => finish(undefined), timeoutMs));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+      finish(undefined);
+    else
+      launchNext();
+  });
+}
+function lookupWithin(host, policy, signal) {
+  return new Promise((resolve, reject) => {
+    const settle = (act) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      act();
+    };
+    const abort = () => settle(() => reject(signal?.reason));
+    const timer = setTimeout(() => settle(() => reject(new Error(`Address lookup took longer than ${policy.budgetMs} ms`))), policy.budgetMs);
+    if (signal?.aborted) {
+      abort();
+      return;
+    }
+    signal?.addEventListener("abort", abort, { once: true });
+    Promise.resolve().then(() => policy.resolve(host)).then((found) => settle(() => resolve(found)), (error) => settle(() => reject(error)));
+  });
+}
+async function establish(host, port, tls, policy, signal) {
+  const literal = isIP(host) !== 0;
+  let addresses;
+  if (literal)
+    addresses = [host];
+  else {
+    try {
+      addresses = await lookupWithin(host, policy, signal);
+    } catch (cause) {
+      signal?.throwIfAborted();
+      throw new TelegramNotDispatchedError2("lookup", "Telegram address lookup failed", {
+        cause
+      });
+    }
+  }
+  signal?.throwIfAborted();
+  if (addresses.length === 0)
+    throw new TelegramNotDispatchedError2("lookup", "Telegram address lookup returned nothing");
+  const target = { port, tls, servername: tls && !literal ? host : undefined };
+  const deadline = performance.now() + policy.budgetMs;
+  let lastFailure;
+  for (let round = 0;round < MAX_ROUNDS; round++) {
+    const left = deadline - performance.now();
+    if (left <= 0)
+      break;
+    const outcome = await race(addresses, target, policy.open, Math.min(policy.attemptMs, left), signal);
+    if (signal?.aborted && "socket" in outcome)
+      outcome.socket.destroy();
+    signal?.throwIfAborted();
+    if ("socket" in outcome)
+      return outcome.socket;
+    lastFailure = outcome.failure ?? lastFailure;
+  }
+  throw new TelegramNotDispatchedError2("connect", "Telegram connection was not established", {
+    cause: lastFailure
+  });
+}
+
+// src/telegram/transport.ts
+function chunkedBody(body) {
+  const parts = [];
+  let at = 0;
+  for (;; ) {
+    const lineEnd = body.indexOf(`\r
+`, at);
+    if (lineEnd < 0)
+      throw new Error("Telegram chunked answer was truncated");
+    const size = Number.parseInt(body.subarray(at, lineEnd).toString("latin1"), 16);
+    if (!Number.isSafeInteger(size) || size < 0)
+      throw new Error("Telegram chunked answer had an invalid chunk size");
+    if (size === 0)
+      return Buffer.concat(parts);
+    const start = lineEnd + 2;
+    if (start + size > body.length)
+      throw new Error("Telegram chunked answer was truncated");
+    parts.push(body.subarray(start, start + size));
+    at = start + size + 2;
+  }
+}
+function answerHead(raw) {
+  const headEnd = raw.indexOf(`\r
+\r
+`);
+  if (headEnd < 0)
+    return;
+  const [statusLine = "", ...lines] = raw.subarray(0, headEnd).toString("latin1").split(`\r
+`);
+  const status = /^HTTP\/1\.[01] (\d{3})/.exec(statusLine)?.[1];
+  if (status === undefined)
+    throw new Error("Telegram answer had an invalid status line");
+  if (Number(status) < 200)
+    throw new Error(`Telegram answer was an interim response (HTTP ${status}), not a final one`);
+  const headers = new Headers;
+  for (const line of lines) {
+    const colon = line.indexOf(":");
+    if (colon > 0)
+      headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
+  }
+  return { bodyStart: headEnd + 4, status: Number(status), headers };
+}
+var bodiless = (status) => status === 204 || status === 304;
+var isChunked = (headers) => /\bchunked\b/i.test(headers.get("transfer-encoding") ?? "");
+function declaredLength(headers) {
+  const raw = headers.get("content-length");
+  if (raw === null)
+    return;
+  const values = new Set(raw.split(",").map((value) => value.trim()));
+  const [only = ""] = values;
+  if (values.size !== 1 || !/^\d{1,15}$/.test(only))
+    throw new Error("Telegram answer had an invalid Content-Length");
+  return Number(only);
+}
+function answerComplete(raw) {
+  const head = answerHead(raw);
+  if (!head)
+    return false;
+  if (bodiless(head.status))
+    return true;
+  const body = raw.subarray(head.bodyStart);
+  if (isChunked(head.headers)) {
+    try {
+      chunkedBody(body);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const length = declaredLength(head.headers);
+  return length !== undefined && body.length >= length;
+}
+function parseAnswer(raw) {
+  const head = answerHead(raw);
+  if (!head)
+    throw new Error("Telegram answer ended inside its head");
+  const { status, headers } = head;
+  let body = raw.subarray(head.bodyStart);
+  if (isChunked(headers)) {
+    body = chunkedBody(body);
+    headers.delete("content-length");
+  } else {
+    const expected = declaredLength(headers);
+    if (expected !== undefined) {
+      if (body.length < expected)
+        throw new Error("Telegram answer body was truncated");
+      body = body.subarray(0, expected);
+    }
+  }
+  headers.delete("transfer-encoding");
+  return new Response(bodiless(status) ? null : new Uint8Array(body), { status, headers });
+}
+function exchange(socket, request, limits, signal) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    let done = false;
+    const finish = (error) => {
+      if (done)
+        return;
+      done = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      socket.destroy();
+      if (error !== undefined) {
+        reject(error);
+        return;
+      }
+      try {
+        resolve(parseAnswer(Buffer.concat(chunks)));
+      } catch (parseError) {
+        reject(parseError);
+      }
+    };
+    const abort = () => finish(signal?.reason);
+    const timer = setTimeout(() => finish(new Error(`Telegram answer took longer than ${limits.responseTimeoutMs} ms`)), limits.responseTimeoutMs);
+    socket.on("data", (chunk) => {
+      bytes += chunk.byteLength;
+      if (bytes > limits.maxResponseBytes) {
+        finish(new Error(`Telegram answer exceeded ${limits.maxResponseBytes} bytes`));
+        return;
+      }
+      chunks.push(chunk);
+      try {
+        if (answerComplete(Buffer.concat(chunks)))
+          finish(undefined);
+      } catch (error) {
+        finish(error);
+      }
+    });
+    socket.once("end", () => finish(undefined));
+    socket.once("close", () => finish(undefined));
+    socket.once("error", (error) => finish(error));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+      abort();
+    else
+      socket.write(request);
+  });
+}
+async function requestBytes(url, init, signal) {
+  let request;
+  let headers;
+  let body;
+  try {
+    request = new Request(url, { ...init, signal: null });
+    headers = [...request.headers].filter(([name]) => !["host", "content-length", "connection", "transfer-encoding"].includes(name));
+    const read = request.arrayBuffer();
+    body = new Uint8Array(await (signal ? untilAborted(read, signal) : read));
+  } catch (cause) {
+    signal?.throwIfAborted();
+    throw new TelegramNotDispatchedError2("request", "Telegram request body could not be read", {
+      cause
+    });
+  }
+  const head = [
+    `${request.method} ${url.pathname}${url.search} HTTP/1.1`,
+    `Host: ${url.host}`,
+    ...headers.map(([name, value]) => `${name}: ${value}`),
+    `Content-Length: ${body.byteLength}`,
+    "Connection: close",
+    "",
+    ""
+  ].join(`\r
+`);
+  return { head, body };
+}
+function createTelegramBotTransport(options = {}) {
+  const connectAttemptMs = options.connectAttemptMs ?? 2000;
+  const connectBudgetMs = options.connectBudgetMs ?? 5000;
+  const responseTimeoutMs = options.responseTimeoutMs ?? 30000;
+  const maxResponseBytes = options.maxResponseBytes ?? 1024 * 1024;
+  assertPositiveSafeInteger("connectAttemptMs", connectAttemptMs);
+  assertPositiveSafeInteger("connectBudgetMs", connectBudgetMs);
+  assertPositiveSafeInteger("responseTimeoutMs", responseTimeoutMs);
+  assertPositiveSafeInteger("maxResponseBytes", maxResponseBytes);
+  const policy = {
+    resolve: options.resolve ?? resolveAll,
+    open: options.open ?? openSocket,
+    attemptMs: connectAttemptMs,
+    budgetMs: connectBudgetMs
+  };
+  return async (url, init) => {
+    const signal = init.signal ?? undefined;
+    signal?.throwIfAborted();
+    const target = new URL(url);
+    const tls = target.protocol === "https:";
+    if (!tls && target.protocol !== "http:")
+      throw new TelegramNotDispatchedError2("request", `Telegram transport speaks http and https, not ${target.protocol}`);
+    const { head, body } = await requestBytes(target, init, signal);
+    signal?.throwIfAborted();
+    const socket = await establish(target.hostname.replace(/^\[|\]$/g, ""), Number(target.port || (tls ? 443 : 80)), tls, policy, signal);
+    return exchange(socket, Buffer.concat([Buffer.from(head, "latin1"), body]), { maxResponseBytes, responseTimeoutMs }, signal);
+  };
+}
 // src/telegram/update-intake.ts
 var SWEEP_BATCH = 100;
 function defaultRetry(error, attempt) {
@@ -1524,12 +1856,14 @@ export {
   TelegramBotApiError,
   TelegramBroadcastFailureSchema,
   TelegramLocalFileError,
+  TelegramNotDispatchedError2 as TelegramNotDispatchedError,
   TelegramWebhookClaimError,
   callTelegramBotApi,
   checkTelegramUpdateStore,
   checkTelegramWebhook,
   claimTelegramWebhook,
   classifyTelegramSendFailure2 as classifyTelegramSendFailure,
+  createTelegramBotTransport,
   createTelegramLocalFiles,
   createTelegramOperatorChannel,
   createTelegramOperatorDedupe,

package/dist/entrypoints/testing.d.ts

@@ -4,6 +4,7 @@
  */
 export * from '../testing/handler-clients.js';
 export { type ManagedResourceConformanceConfig, type ManagedResourceConformanceControls, ManagedResourceConformanceError, type ManagedResourceConformanceFactoryInput, type ManagedResourceConformanceFixture, type ManagedResourceConformancePhase, ManagedResourceConformancePhaseSchema, type ManagedResourceConformanceScenario, type ManagedResourceConformanceScenarioId, ManagedResourceConformanceScenarioIdSchema, ManagedResourceConformanceScenarioSchema, type ManagedResourceConformanceTraceEntry, ManagedResourceConformanceTraceEntrySchema, type ManagedResourceConformanceTraceOutcome, ManagedResourceConformanceTraceOutcomeSchema, runManagedResourceConformance, } from '../testing/managed-resource-conformance.js';
+export { createManualClock, type ManualClock, ManualClockError, type ManualClockErrorCode, type ManualClockHold, type ManualClockOptions, type ManualClockTimer, type ManualClockUntilOptions, } from '../testing/manual-clock.js';
 export { type CreateRealtimeProbeDriverConfig, createRealtimeProbeDriver, type DefineRealtimeProbeConfig, defineRealtimeProbe, type RealtimeProbeAdapter, type RealtimeProbeFixture, type RealtimeProbeScenario, } from '../testing/realtime-probe.js';
 export { assertSurfaceDiscovery, type ConformanceTransport, type RealtimeDisconnectObservation, RealtimeDisconnectObservationSchema, type RealtimeRejectionObservation, RealtimeRejectionObservationSchema, type RunSurfaceProbesConfig, runSurfaceProbes, type SurfaceDiscoveryObservation, type SurfaceProbe, type SurfaceProbeDriver, type SurfaceRealtimeDiscoveryObservation, type SurfaceToolDiscoveryObservation, type TransportObservation, TransportObservationSchema, } from '../testing/surface-conformance.js';
 export { assertSurfaceManifestSnapshot, buildSurfaceManifest, type IncompatibleSchemaPolicy, type McpSchemaValidationConfig, SURFACE_MANIFEST_VERSION, type SurfaceAgentProjection, type SurfaceManifest, type SurfaceManifestConfig, type SurfaceManifestExtension, SurfaceManifestExtensionSchema, type SurfaceManifestOperation, type SurfaceManifestOperationMcp, SurfaceManifestOperationMcpSchema, SurfaceManifestOperationSchema, type SurfaceManifestOperationToolView, SurfaceManifestOperationToolViewSchema, type SurfaceManifestRealtimeEvent, SurfaceManifestRealtimeEventSchema, SurfaceManifestSchema, type SurfaceManifestTool, SurfaceManifestToolSchema, type SurfaceManifestToolSurface, SurfaceManifestToolSurfaceSchema, type SurfaceMcpPreparation, SurfaceRealtimeSchemaPairSchema, type SurfaceRuntimeToolDefinition, SurfaceSchemaDigestsSchema, type SurfaceToolDefinition, type SurfaceToolExtension, } from '../testing/surface-manifest.js';

package/dist/entrypoints/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/entrypoints/testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,KAAK,gCAAgC,EACrC,KAAK,kCAAkC,EACvC,+BAA+B,EAC/B,KAAK,sCAAsC,EAC3C,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACpC,qCAAqC,EACrC,KAAK,kCAAkC,EACvC,KAAK,oCAAoC,EACzC,0CAA0C,EAC1C,wCAAwC,EACxC,KAAK,oCAAoC,EACzC,0CAA0C,EAC1C,KAAK,sCAAsC,EAC3C,4CAA4C,EAC5C,6BAA6B,GAC9B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,mCAAmC,EACnC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,mCAAmC,EACxC,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EACzB,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,iCAAiC,EACjC,8BAA8B,EAC9B,KAAK,gCAAgC,EACrC,sCAAsC,EACtC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,gCAAgC,EAChC,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,KAAK,4BAA4B,EACjC,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/entrypoints/testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EACL,KAAK,gCAAgC,EACrC,KAAK,kCAAkC,EACvC,+BAA+B,EAC/B,KAAK,sCAAsC,EAC3C,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACpC,qCAAqC,EACrC,KAAK,kCAAkC,EACvC,KAAK,oCAAoC,EACzC,0CAA0C,EAC1C,wCAAwC,EACxC,KAAK,oCAAoC,EACzC,0CAA0C,EAC1C,KAAK,sCAAsC,EAC3C,4CAA4C,EAC5C,6BAA6B,GAC9B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,mCAAmC,EACnC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,mCAAmC,EACxC,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EACzB,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,iCAAiC,EACjC,8BAA8B,EAC9B,KAAK,gCAAgC,EACrC,sCAAsC,EACtC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,gCAAgC,EAChC,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,KAAK,4BAA4B,EACjC,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAC"}

package/dist/entrypoints/testing.js

@@ -35,7 +35,10 @@ import"../index-fynr93w4.js";
 import {
   createClient2,
   createClients2
-} from "../index-zsqt5q98.js";
+} from "../index-p5kx5vqd.js";
+import {
+  assertPositiveSafeInteger
+} from "../index-0s4xebbg.js";
 import {
   compareCodeUnits,
   serializeCanonicalJson
@@ -645,6 +648,131 @@ async function runManagedResourceConformance(config) {
     await runScenario(config, scenario, watchdogTimeoutMs);
   }
 }
+// src/testing/manual-clock.ts
+class ManualClockError extends Error {
+  code;
+  holds;
+  name = "ManualClockError";
+  constructor(code, message, holds = []) {
+    super(message);
+    this.code = code;
+    this.holds = holds;
+  }
+}
+var DEFAULT_WALL_START = Date.parse("2026-01-01T00:00:00.000Z");
+function createManualClock(options = {}) {
+  const startMs = options.startMs ?? 0;
+  if (!Number.isFinite(startMs))
+    throw new RangeError("startMs must be a finite number");
+  const wallStart = options.wallStart?.getTime() ?? DEFAULT_WALL_START;
+  if (!Number.isFinite(wallStart))
+    throw new RangeError("wallStart must be a valid date");
+  const turns = options.yieldTurns ?? 8;
+  assertPositiveSafeInteger("yieldTurns", turns);
+  const holdLimitMs = options.holdLimitMs ?? 5000;
+  assertPositiveSafeInteger("holdLimitMs", holdLimitMs);
+  let now = startMs;
+  let order = 0;
+  let moving = false;
+  const timers = new Map;
+  const holds = new Map;
+  const activeHolds = () => [...holds.values()].filter((hold) => !hold.parked).map((hold) => hold.reason);
+  const settle = async () => {
+    for (let turn = 0;turn < turns; turn++)
+      await new Promise((resolve) => setImmediate(resolve));
+  };
+  const idle = async () => {
+    const started = performance.now();
+    for (let open = activeHolds();open.length > 0; open = activeHolds()) {
+      if (performance.now() - started > holdLimitMs)
+        throw new ManualClockError("MANUAL_CLOCK_HOLD_TIMEOUT", `Manual clock waited ${holdLimitMs} ms of real time for ${open.length} open hold(s): ${open.join(", ")}`, open);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    await settle();
+  };
+  const nextDue = (limit) => {
+    let best;
+    for (const entry of timers) {
+      const [, timer] = entry;
+      if (timer.at > limit)
+        continue;
+      if (!best || timer.at < best[1].at || timer.at === best[1].at && timer.order < best[1].order)
+        best = entry;
+    }
+    return best;
+  };
+  const move = async (target) => {
+    await idle();
+    for (let due = nextDue(target);due; due = nextDue(target)) {
+      const [id, timer] = due;
+      timers.delete(id);
+      now = Math.max(now, timer.at);
+      timer.callback();
+      await idle();
+    }
+    now = target;
+    await idle();
+  };
+  const clock = {
+    now: () => now,
+    wallNow: () => new Date(wallStart + (now - startMs)),
+    schedule(callback, delayMs) {
+      if (Number.isNaN(delayMs))
+        throw new RangeError("Timer delay must be a number");
+      const id = ++order;
+      timers.set(id, { at: now + Math.max(0, delayMs), order: id, callback });
+      return { cancel: () => void timers.delete(id) };
+    },
+    async advance(ms) {
+      if (!Number.isFinite(ms) || ms < 0)
+        throw new RangeError(`Manual clock cannot advance by ${ms} ms`);
+      if (moving)
+        throw new Error("Manual clock is already advancing; await that advance first");
+      moving = true;
+      try {
+        await move(now + ms);
+      } finally {
+        moving = false;
+      }
+    },
+    async until(done, { stepMs = 100, limitMs = 600000 } = {}) {
+      assertPositiveSafeInteger("stepMs", stepMs);
+      assertPositiveSafeInteger("limitMs", limitMs);
+      const from = now;
+      await idle();
+      while (!done()) {
+        if (now - from >= limitMs)
+          throw new ManualClockError("MANUAL_CLOCK_LIMIT", `Condition still false after ${now - from} ms of manual time (limit ${limitMs} ms, ${timers.size} timer(s) pending)`);
+        const next = nextDue(Number.POSITIVE_INFINITY);
+        const jump = next ? Math.max(0, next[1].at - now) : stepMs;
+        await clock.advance(Math.min(jump, from + limitMs - now));
+      }
+      return now - from;
+    },
+    pending: () => timers.size,
+    hold(reason) {
+      const id = ++order;
+      holds.set(id, { reason, parked: false });
+      return {
+        release: () => void holds.delete(id),
+        park() {
+          const hold = holds.get(id);
+          if (!hold || hold.parked)
+            return () => {
+              return;
+            };
+          hold.parked = true;
+          return () => {
+            const current = holds.get(id);
+            if (current)
+              current.parked = false;
+          };
+        }
+      };
+    }
+  };
+  return clock;
+}
 // src/testing/surface-conformance.ts
 import { z as z2 } from "zod";
 var RealtimeRejectionObservationSchema = z2.object({
@@ -1340,6 +1468,7 @@ export {
   ManagedResourceConformanceScenarioSchema,
   ManagedResourceConformanceTraceEntrySchema,
   ManagedResourceConformanceTraceOutcomeSchema,
+  ManualClockError,
   RealtimeDisconnectObservationSchema,
   RealtimeRejectionObservationSchema,
   SURFACE_MANIFEST_VERSION,
@@ -1359,6 +1488,7 @@ export {
   buildSurfaceManifest,
   createHandlerTestClient,
   createHandlerTestClients,
+  createManualClock,
   createRealtimeProbeDriver,
   defineRealtimeProbe,
   runManagedResourceConformance,

package/dist/files/native-artifact.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which Darwin loader an artifact carries: `packaged` (the static loader a packaging plugin
+ * wrote), `unpackaged` (the default loader, which refuses the addon inside a bundle) or
+ * `no-loader` (nothing in it loads the addon). An artifact with both reads `unpackaged`: one
+ * unpackaged loader is enough for its calls to refuse on macOS.
+ */
+export type NativeArtifactLoader = 'packaged' | 'unpackaged' | 'no-loader';
+/**
+ * Classify a built artifact (a JS bundle or a compiled executable) by the marker every generated
+ * loader carries, without running it. Reads the bytes only; builds made before the marker existed
+ * (0.107.0 and earlier) read `no-loader`.
+ */
+export declare function inspectNativeArtifact(bytes: Uint8Array): NativeArtifactLoader;
+//# sourceMappingURL=native-artifact.d.ts.map

package/dist/files/native-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-artifact.d.ts","sourceRoot":"","sources":["../../src/files/native-artifact.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;AAW3E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAI7E"}

package/dist/files/native-packaging-layout.d.ts

@@ -57,6 +57,11 @@ export declare function nativeAssetDigest(bytes: Uint8Array): {
  * second form into the first.
  */
 export type NativeLoaderResolution = 'static' | 'beside-loader';
+/**
+ * The string a generated loader carries as `module.exports.stitchkitNativeLoader`: `packaged` for
+ * the static loader a packaging plugin writes, `unpackaged` for the default beside-loader.
+ */
+export declare function nativeLoaderMarker(state: 'packaged' | 'unpackaged'): string;
 /** One lazy loader for package, companion and embedded delivery. */
 export declare function nativeLoaderSource(assets: Readonly<Record<string, string>>, resolution: NativeLoaderResolution): string;
 //# sourceMappingURL=native-packaging-layout.d.ts.map

package/dist/files/native-packaging-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-packaging-layout.d.ts","sourceRoot":"","sources":["../../src/files/native-packaging-layout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,aAU5B,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;kBAG7B,CAAC;AAEH,kGAAkG;AAClG,eAAO,MAAM,sBAAsB;;;;kBAIjC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;kBASpC,CAAC;AAEH,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAErF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,eAAe,CAAC;AAQhE,oEAAoE;AACpE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,UAAU,EAAE,sBAAsB,GACjC,MAAM,CA6CR"}
+{"version":3,"file":"native-packaging-layout.d.ts","sourceRoot":"","sources":["../../src/files/native-packaging-layout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,aAU5B,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;kBAG7B,CAAC;AAEH,kGAAkG;AAClG,eAAO,MAAM,sBAAsB;;;;kBAIjC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;kBASpC,CAAC;AAEH,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAErF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,eAAe,CAAC;AAQhE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAE3E;AAQD,oEAAoE;AACpE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,UAAU,EAAE,sBAAsB,GACjC,MAAM,CAiDR"}

package/dist/files/native-packaging-plugin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Structural Bun plugin protocol: declarations need no Bun runtime or ambient types.
+ */
+export type NativePackagingPlugin = {
+    name: string;
+    setup: (build: {
+        config: {
+            splitting?: boolean;
+            naming?: string | {
+                entry?: string;
+            };
+            entrypoints: string[];
+        };
+        onLoad: (options: {
+            filter: RegExp;
+        }, callback: (args: {
+            path: string;
+        }) => {
+            contents: string;
+            loader: 'js';
+        } | {
+            contents: Uint8Array;
+            loader: 'napi';
+        } | undefined) => unknown;
+        onResolve: (options: {
+            filter: RegExp;
+        }, callback: (args: {
+            path: string;
+            importer: string;
+        }) => {
+            path: string;
+            external: boolean;
+        } | undefined) => unknown;
+    }) => void;
+};
+/** The installed package a plugin belongs to: its root, its version and its loader file. */
+export interface NativePackagingOwner {
+    readonly root: string;
+    readonly version: string;
+    /** Absolute path of the default loader, as the published manifest names it. */
+    readonly loaderPath: string;
+    /** The manifest's relative loader path, the suffix every installation's loader shares. */
+    readonly loaderName: string;
+}
+/**
+ * The one Bun plugin of both deliveries: it swaps its own installation's default loader for a
+ * static one, hands Bun the verified bytes of each embedded addon, and keeps companion addons
+ * external to a build whose single entry is named exactly `entryPath`. A default loader of any
+ * other installation fails the build: the entry imports a `stitchkit` this plugin did not package,
+ * and an artifact that carried that loader would refuse the addon at run time.
+ */
+export declare function nativePlugin(owner: NativePackagingOwner, specifiers: Readonly<Record<string, string>>, embedded: ReadonlyMap<string, Uint8Array>, companionEntry: string | undefined): NativePackagingPlugin;
+//# sourceMappingURL=native-packaging-plugin.d.ts.map

package/dist/files/native-packaging-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-packaging-plugin.d.ts","sourceRoot":"","sources":["../../src/files/native-packaging-plugin.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,KAAK,EAAE;QACb,MAAM,EAAE;YACN,SAAS,CAAC,EAAE,OAAO,CAAC;YACpB,MAAM,CAAC,EAAE,MAAM,GAAG;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;YACrC,WAAW,EAAE,MAAM,EAAE,CAAC;SACvB,CAAC;QACF,MAAM,EAAE,CACN,OAAO,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,EAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE;YACf,IAAI,EAAE,MAAM,CAAC;SACd,KACG;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,IAAI,CAAA;SAAE,GAClC;YAAE,QAAQ,EAAE,UAAU,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GACxC,SAAS,KACV,OAAO,CAAC;QACb,SAAS,EAAE,CACT,OAAO,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,EAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE;YACf,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,MAAM,CAAC;SAClB,KAAK;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,OAAO,CAAA;SAAE,GAAG,SAAS,KAClD,OAAO,CAAC;KACd,KAAK,IAAI,CAAC;CACZ,CAAC;AAEF,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAmCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,oBAAoB,EAC3B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACzC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,CA8CvB"}