stitchkit 0.106.1 → 0.108.0

package/dist/internal/darwin-binding-error.d.ts

@@ -1,11 +1,19 @@
+/** Error code of a generated beside-loader that runs inside a bundle built without the packaging plugin. */
+export declare const NATIVE_NOT_PACKAGED = "STITCHKIT_NATIVE_NOT_PACKAGED";
 declare const messages: {
     architecture: string;
+    packaging: string;
     resolve: string;
     load: string;
     surface: string;
 };
 type Stage = keyof typeof messages;
 export declare function darwinNativeCode(cause: unknown): string | undefined;
+/**
+ * Which stage a failed addon load stopped at: a bundle built without the packaging plugin, an
+ * addon that is not where the loader looked, or one that was found and did not load.
+ */
+export declare function darwinLoadStage(cause: unknown): 'packaging' | 'resolve' | 'load';
 /** Live callers retain the original Error; operator JSON only carries safe loader evidence. */
 export declare class DarwinBackendError extends Error {
     readonly stage: Stage;
@@ -14,7 +22,7 @@ export declare class DarwinBackendError extends Error {
     toJSON(): {
         name: string;
         code: string;
-        stage: "architecture" | "load" | "resolve" | "surface";
+        stage: "architecture" | "load" | "packaging" | "resolve" | "surface";
         architecture: NodeJS.Architecture;
         message: string;
         nativeCode: string | undefined;

package/dist/internal/darwin-binding-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"darwin-binding-error.d.ts","sourceRoot":"","sources":["../../src/internal/darwin-binding-error.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,QAAQ;IACZ,YAAY;IACZ,OAAO;IACP,IAAI;IACJ,OAAO;CACR,CAAC;AACF,KAAK,KAAK,GAAG,MAAM,OAAO,QAAQ,CAAC;AAYnC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAanE;AAED,+FAA+F;AAC/F,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAFvB,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,YACW,KAAK,EAAE,KAAK,EACrB,KAAK,CAAC,EAAE,OAAO,EAIhB;IACD,MAAM;;;;;;;MASL;CACF"}
+{"version":3,"file":"darwin-binding-error.d.ts","sourceRoot":"","sources":["../../src/internal/darwin-binding-error.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,eAAO,MAAM,mBAAmB,kCAAkC,CAAC;AAEnE,QAAA,MAAM,QAAQ;IACZ,YAAY;IACZ,SAAS;IAET,OAAO;IACP,IAAI;IACJ,OAAO;CACR,CAAC;AACF,KAAK,KAAK,GAAG,MAAM,OAAO,QAAQ,CAAC;AAanC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAanE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAMhF;AAED,+FAA+F;AAC/F,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAFvB,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,YACW,KAAK,EAAE,KAAK,EACrB,KAAK,CAAC,EAAE,OAAO,EAIhB;IACD,MAAM;;;;;;;MASL;CACF"}

package/dist/internal/darwin-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"darwin-binding.d.ts","sourceRoot":"","sources":["../../src/internal/darwin-binding.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9E;AAID,wBAAgB,iBAAiB,IAAI,aAAa,CAkCjD"}
+{"version":3,"file":"darwin-binding.d.ts","sourceRoot":"","sources":["../../src/internal/darwin-binding.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9E;AAID,wBAAgB,iBAAiB,IAAI,aAAa,CA4BjD"}

package/dist/internal/process-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../../src/internal/process-identity.ts"],"names":[],"mappings":"AA8CA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,SAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBtF;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,YAAY,MAAM,SAA4B,GAClD,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAY3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../../src/internal/process-identity.ts"],"names":[],"mappings":"AA6DA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,SAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBtF;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,YAAY,MAAM,SAA4B,GAClD,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAY3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,OAAO,CAAC,CAsBlB"}

package/dist/internal/until-aborted.d.ts

@@ -0,0 +1,9 @@
+/** The signal's reason, or the `AbortError` a signal aborted without one stands for. */
+export declare function abortReason(signal: AbortSignal): unknown;
+/**
+ * `pending`, or the signal's reason as soon as it aborts. Each call owns its listener and removes
+ * it when `pending` settles: one promise shared by every call would retain each result for as long
+ * as the signal lives. `pending` itself is not cancelled, only no longer waited for.
+ */
+export declare function untilAborted<T>(pending: Promise<T>, signal: AbortSignal): Promise<T>;
+//# sourceMappingURL=until-aborted.d.ts.map

package/dist/internal/until-aborted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"until-aborted.d.ts","sourceRoot":"","sources":["../../src/internal/until-aborted.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAoBpF"}

package/dist/internal/upgrade-affects.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The machine line of a breaking changelog item: what it touches, in a form a
+ * consumer's tooling reads without guessing from prose.
+ *
+ *   **Affects:** `stitchkit/files/packaging` createNativePackaging(delivery: 'embedded')
+ *   **Affects:** `stitchkit/contract`, `stitchkit/server` AppError; `stitchkit` ApiError
+ *   **Affects:** `stitchkit/process` behaviour
+ *   **Affects:** `stitchkit/agent-runtime/harness-tools` *
+ *
+ * Targets are separated by `; `. A target is one or more backticked entrypoints
+ * (`, ` between them) and then either export names (`, ` between them, each with
+ * an optional parenthesised qualifier naming the option or member), `behaviour`
+ * for a change of semantics no import name reveals, or `*` for every import of
+ * the entrypoint (a removed leaf). The whole line stays on one line.
+ *
+ * Pure: shared by the release gate, which refuses a breaking item without it,
+ * and by `stitchkit upgrade`, which matches it against a project's imports.
+ */
+/** One export a breaking item changes, with what about it changed. */
+export interface UpgradeAffectedSymbol {
+    readonly name: string;
+    /** The option or member the change is about, as written, e.g. `delivery: 'embedded'`. */
+    readonly qualifier?: string;
+}
+/** What one target of an `**Affects:**` line touches in one entrypoint. */
+export type UpgradeAffectsTarget = {
+    readonly entrypoint: string;
+    readonly kind: 'symbols';
+    readonly symbols: readonly UpgradeAffectedSymbol[];
+} | {
+    readonly entrypoint: string;
+    readonly kind: 'behaviour';
+} | {
+    readonly entrypoint: string;
+    readonly kind: 'any-import';
+};
+/** One top-level `- ` item of a breaking section, with its lines as written. */
+export interface UpgradeBreakingItemText {
+    readonly markdown: string;
+}
+/** The line could not be read; `reason` says which part is malformed. */
+export declare class UpgradeAffectsError extends Error {
+    readonly name = "UpgradeAffectsError";
+}
+/**
+ * The top-level items of a breaking section. An item opens with a `- `, `* ` or
+ * `+ ` bullet at column zero outside a fence; indented and blank lines continue
+ * it, and the next unindented line closes it.
+ */
+export declare function breakingItems(section: string): UpgradeBreakingItemText[];
+/**
+ * The text after `**Affects:**` in an item, or undefined when it declares none.
+ * An item carries at most one such line; a second is refused, never dropped.
+ */
+export declare function affectsLineOf(itemMarkdown: string): string | undefined;
+/** Every target of an `**Affects:**` line; throws `UpgradeAffectsError` on a malformed one. */
+export declare function parseAffectsLine(line: string): UpgradeAffectsTarget[];
+//# sourceMappingURL=upgrade-affects.d.ts.map

package/dist/internal/upgrade-affects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-affects.d.ts","sourceRoot":"","sources":["../../src/internal/upgrade-affects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD,GACD;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAEjE,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAOD,yEAAyE;AACzE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAyB;CAChD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,EAAE,CA6BxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiBtE;AAyDD,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAGrE"}

package/dist/internal/upgrade-plan.d.ts

@@ -7,11 +7,31 @@
  * consumer recovers the plan without cloning the repository or being told the
  * range by whoever cut the release.
  */
+import { type UpgradeAffectsTarget } from './upgrade-affects.js';
+/** One breaking item of a release, with its machine line when it declares one. */
+export interface UpgradeBreakingItem {
+    version: string;
+    /** The backticked entrypoints the item leads with. */
+    entrypoints: string[];
+    /** The item's bold title, or its first line. */
+    title: string;
+    /** What the item touches; `undefined` for an item written before the `**Affects:**` line. */
+    affects: UpgradeAffectsTarget[] | undefined;
+    /** The item's own `**Who must act:**`, or its section's. */
+    whoMustAct: string;
+    markdown: string;
+}
 export interface UpgradeBreakingChange {
     version: string;
     whoMustAct: string;
     markdown: string;
+    items: UpgradeBreakingItem[];
 }
+/**
+ * The heading that marks a changelog section as breaking. The release gate and `stitchkit upgrade`
+ * read it through this one expression, so a heading one accepts is a heading the other finds.
+ */
+export declare const BREAKING_HEADING: RegExp;
 /** Extract every breaking section crossed by an exact `from` (exclusive) → `to` (inclusive) upgrade. */
 export declare function planUpgrade(changelog: string, from: string, to: string): UpgradeBreakingChange[];
 export declare function renderUpgradePlan(changes: readonly UpgradeBreakingChange[], from: string, to: string): string;

package/dist/internal/upgrade-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade-plan.d.ts","sourceRoot":"","sources":["../../src/internal/upgrade-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsBD,wGAAwG;AACxG,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,qBAAqB,EAAE,CAgCzB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CASR"}
+{"version":3,"file":"upgrade-plan.d.ts","sourceRoot":"","sources":["../../src/internal/upgrade-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,OAAO,EAAE,oBAAoB,EAAE,GAAG,SAAS,CAAC;IAC5C,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAA2C,CAAC;AA2EzE,wGAAwG;AACxG,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,qBAAqB,EAAE,CAgCzB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CASR"}

package/dist/internal/upgrade-usage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether a breaking item touches one project: the plan's `**Affects:**` lines
+ * against the names the project imports from `stitchkit`.
+ *
+ * Pure over source text. The scanner reads static `import`/`export … from`
+ * declarations at a statement start (named, aliased, `type`, default, namespace,
+ * `export *`), bare imports, and `import()` / `require()` of a literal specifier,
+ * and the script blocks of `.vue` and `.svelte` files. Comments and the contents
+ * of strings and templates are blanked first, so a commented-out import or one
+ * written inside a string is not a use; it does not evaluate code, so a
+ * specifier built at run time is invisible to it, and a regular-expression literal that holds a
+ * quote or a comment marker can hide what follows it.
+ */
+import type { UpgradeAffectsTarget } from './upgrade-affects.js';
+import type { UpgradeBreakingItem } from './upgrade-plan.js';
+/** One project file, by a path relative to the project root. */
+export interface ProjectSource {
+    readonly path: string;
+    readonly text: string;
+}
+/** One name a file imports from one stitchkit entrypoint; `*` for a namespace, star or dynamic import. */
+export interface StitchkitImport {
+    readonly path: string;
+    readonly line: number;
+    readonly entrypoint: string;
+    readonly name: string;
+}
+export type UpgradeVerdict = {
+    readonly kind: 'affects';
+    readonly uses: readonly StitchkitImport[];
+} | {
+    readonly kind: 'not-used';
+} | {
+    readonly kind: 'behavioural';
+    readonly files: readonly string[];
+} | {
+    readonly kind: 'not-declared';
+    readonly files: readonly string[];
+};
+export interface UpgradeItemVerdict {
+    readonly item: UpgradeBreakingItem;
+    readonly verdict: UpgradeVerdict;
+}
+/** Every name the given sources import from a `stitchkit` entrypoint. */
+export declare function scanStitchkitImports(sources: readonly ProjectSource[]): StitchkitImport[];
+/** One verdict per item, in plan order. */
+export declare function upgradeVerdicts(items: readonly UpgradeBreakingItem[], imports: readonly StitchkitImport[]): UpgradeItemVerdict[];
+/** The verdicts as the Markdown section `stitchkit upgrade` prints after the plan. */
+export declare function renderUpgradeVerdicts(verdicts: readonly UpgradeItemVerdict[]): string;
+/** The verdicts as the `--json` document's items. */
+export declare function upgradeVerdictsJson(verdicts: readonly UpgradeItemVerdict[]): {
+    version: string;
+    entrypoints: string[];
+    title: string;
+    whoMustAct: string;
+    affects: UpgradeAffectsTarget[] | null;
+    verdict: "affects" | "behavioural" | "not-declared" | "not-used";
+    uses?: readonly StitchkitImport[] | undefined;
+    files?: readonly string[] | undefined;
+}[];
+//# sourceMappingURL=upgrade-usage.d.ts.map

package/dist/internal/upgrade-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-usage.d.ts","sourceRoot":"","sources":["../../src/internal/upgrade-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0GAA0G;AAC1G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAsHD,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,eAAe,EAAE,CA+BzF;AAyBD,2CAA2C;AAC3C,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,kBAAkB,EAAE,CAiBtB;AASD,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAoBrF;AAED,qDAAqD;AACrD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE;;;;;;;;;IAa1E"}

package/dist/telegram/bot-api.d.ts

@@ -7,6 +7,7 @@
  * Telegram's own structured answer, because `classifyTelegramSendFailure`
  * reads `error_code` and `parameters.retry_after` before it ever reads prose.
  */
+import type { TelegramFetch } from './transport.js';
 /**
  * The secret half of a bot token — what follows the bot's numeric id and the
  * colon. The id stays readable: it is the bot's public user id, and the only
@@ -40,14 +41,19 @@ export interface TelegramBotApiCall {
     /** A local Bot API server, e.g. `http://127.0.0.1:8081`. Default: Telegram's. */
     readonly apiRoot?: string;
     readonly signal?: AbortSignal;
-    readonly fetch?: typeof fetch;
+    /**
+     * Default: the global `fetch`. `createTelegramBotTransport()` separates a request that never
+     * left (`TelegramNotDispatchedError`, safe to repeat) from one whose outcome is unknown.
+     */
+    readonly fetch?: TelegramFetch;
 }
 /**
  * Call one Bot API method and return its `result`.
  *
- * A refusal throws `TelegramBotApiError`; a transport failure throws an error
- * whose message names the method and never the URL, since the URL holds the
- * token.
+ * A refusal throws `TelegramBotApiError`; a request that never left throws the
+ * transport's `TelegramNotDispatchedError` unchanged; any other transport failure
+ * throws an error whose message names the method and never the URL, since the URL
+ * holds the token.
  */
 export declare function callTelegramBotApi(call: TelegramBotApiCall): Promise<unknown>;
 //# sourceMappingURL=bot-api.d.ts.map

package/dist/telegram/bot-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bot-api.d.ts","sourceRoot":"","sources":["../../src/telegram/bot-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAyB,CAAC;AAEnE,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAID,gFAAgF;AAChF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7F,YACE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;KAChD,EAQF;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAQD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAuCnF"}
+{"version":3,"file":"bot-api.d.ts","sourceRoot":"","sources":["../../src/telegram/bot-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAyB,CAAC;AAEnE,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAID,gFAAgF;AAChF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7F,YACE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;KAChD,EAQF;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAQD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyCnF"}

package/dist/telegram/broadcast.d.ts

@@ -15,6 +15,7 @@
  */
 import type { TelegramBroadcastFailure } from './broadcast-failure.js';
 import { type TelegramBroadcastRecipient } from './broadcast-state.js';
+import type { TelegramFetch } from './transport.js';
 export type { TelegramBroadcastOutcome, TelegramBroadcastRecipient } from './broadcast-state.js';
 export interface TelegramBroadcastSend {
     readonly recipient: TelegramBroadcastRecipient;
@@ -91,7 +92,7 @@ export interface TelegramBroadcastSenderConfig {
     readonly token: string;
     readonly message: TelegramBroadcastMessage;
     readonly apiRoot?: string;
-    readonly fetch?: typeof fetch;
+    readonly fetch?: TelegramFetch;
 }
 /** The standard `send`: `sendMessage` or `copyMessage` through the Bot API, no bot library. */
 export declare function telegramBroadcastSender(config: TelegramBroadcastSenderConfig): TelegramBroadcastConfig['send'];

package/dist/telegram/broadcast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/telegram/broadcast.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/telegram/broadcast.ts"],"names":[],"mappings":"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"}

package/dist/telegram/not-dispatched.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a Bot API request stopped before any byte of it was written: the address lookup, the
+ * connection, or the request itself (a body that could not be read).
+ */
+export type TelegramNotDispatchedStage = 'lookup' | 'connect' | 'request';
+/**
+ * The request provably never reached Telegram, so sending it again cannot duplicate a message.
+ * Thrown only before the first byte is written; any failure after that is an ordinary error,
+ * because the request may have arrived. Its message names no address that carries the token.
+ */
+export declare class TelegramNotDispatchedError extends Error {
+    readonly stage: TelegramNotDispatchedStage;
+    readonly name = "TelegramNotDispatchedError";
+    readonly code = "TELEGRAM_NOT_DISPATCHED";
+    constructor(stage: TelegramNotDispatchedStage, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * This error, whichever copy of the package made it: its name and code identify it. Only this
+ * error is known to carry no address, so it is the one a sender passes through unchanged.
+ */
+export declare function isTelegramNotDispatchedError(error: unknown): error is TelegramNotDispatchedError;
+/** Whether `error`, or an error it wraps, is a request that never left. */
+export declare function isTelegramNotDispatched(error: unknown, depth?: number): boolean;
+//# sourceMappingURL=not-dispatched.d.ts.map

package/dist/telegram/not-dispatched.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-dispatched.d.ts","sourceRoot":"","sources":["../../src/telegram/not-dispatched.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1E;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAIjD,QAAQ,CAAC,KAAK,EAAE,0BAA0B;IAH5C,SAAkB,IAAI,gCAAgC;IACtD,QAAQ,CAAC,IAAI,6BAA6B;IAC1C,YACW,KAAK,EAAE,0BAA0B,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG9B;CACF;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,0BAA0B,CAOrC;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAO1E"}

package/dist/telegram/operator-channel.d.ts

@@ -15,6 +15,7 @@
  */
 import { type TelegramOperatorDedupe } from './operator-dedupe.js';
 import { type TelegramSendFailure } from './send-failure.js';
+import type { TelegramFetch } from './transport.js';
 export type TelegramChatId = number | string;
 export interface TelegramOperatorMessage {
     readonly chatId: TelegramChatId;
@@ -83,7 +84,7 @@ export interface TelegramOperatorSenderConfig {
     readonly apiRoot?: string;
     /** Default: plain text, so an operator message never fails on entity parsing. */
     readonly parseMode?: 'HTML' | 'MarkdownV2';
-    readonly fetch?: typeof fetch;
+    readonly fetch?: TelegramFetch;
 }
 /**
  * The standard `send`: `sendMessage` through the Bot API, no bot library. With

package/dist/telegram/operator-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAyB7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,MAAM;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,MAAM;IAClE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5D,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAClE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,MAAM;IAC5D,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;CACf;AAeD,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK,EACzE,MAAM,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC5C,uBAAuB,CAAC,MAAM,CAAC,CA+JjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAaD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,6BAA6B,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAkB/C"}

package/dist/telegram/send-failure.d.ts

@@ -31,7 +31,7 @@
  * chat Telegram does not know is usually a bad identifier on our side — a
  * defect in our data, not a fact about a person.
  */
-export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'rate-limited' | 'message-invalid' | 'server-error' | 'unknown';
+export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'rate-limited' | 'message-invalid' | 'server-error' | 'not-dispatched' | 'unknown';
 export interface TelegramSendFailure {
     reason: TelegramSendFailureReason;
     /** Telegram's `error_code`, when the failure carried one. */
@@ -59,9 +59,10 @@ export interface TelegramSendFailure {
     /**
      * How the reason was reached. `parameters` and `status` are Telegram stating
      * its own answer in a structured field; `description` is us reading its
-     * prose, which changes without notice.
+     * prose, which changes without notice; `transport` is the transport stating
+     * that the request never left (`TelegramNotDispatchedError`).
      */
-    evidence: 'parameters' | 'status' | 'description' | 'none';
+    evidence: 'parameters' | 'status' | 'description' | 'transport' | 'none';
 }
 /**
  * Every reason, for a consumer that maps each one to its own code or text. A

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AA6CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAyD/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;CAC1E;AA+CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA4D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/dist/telegram/transport-connect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The part of a Node `net.Socket` / `tls.TLSSocket` the transport uses, so its declarations need
+ * no Node types. A socket emits `connect` (or `secureConnect` when `encrypted`), `data`, `end`,
+ * `close` and `error`.
+ */
+export interface TelegramBotTransportSocket {
+    readonly encrypted?: boolean;
+    once(event: 'connect' | 'secureConnect' | 'end' | 'close', listener: () => void): unknown;
+    once(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    write(data: Uint8Array): unknown;
+    destroy(): unknown;
+}
+/** Opens one socket to one address; `servername` is set for TLS to a host name. */
+export type TelegramBotTransportOpen = (target: {
+    readonly address: string;
+    readonly port: number;
+    readonly tls: boolean;
+    readonly servername: string | undefined;
+}) => TelegramBotTransportSocket;
+/** Every address of a host, in the system resolver's order. */
+export type TelegramBotTransportResolve = (host: string) => Promise<readonly string[]>;
+export interface TelegramConnectPolicy {
+    readonly resolve: TelegramBotTransportResolve;
+    readonly open: TelegramBotTransportOpen;
+    /** Real milliseconds one round waits for a connection. */
+    readonly attemptMs: number;
+    /** Real milliseconds after which no new connection round starts. */
+    readonly budgetMs: number;
+}
+export declare const resolveAll: TelegramBotTransportResolve;
+export declare const openSocket: TelegramBotTransportOpen;
+/**
+ * A connected socket to `host`, or `TelegramNotDispatchedError`: nothing has been written yet,
+ * so every failure here leaves the request unsent. An abort rejects with the signal's reason.
+ */
+export declare function establish(host: string, port: number, tls: boolean, policy: TelegramConnectPolicy, signal: AbortSignal | undefined): Promise<TelegramBotTransportSocket>;
+//# sourceMappingURL=transport-connect.d.ts.map

package/dist/telegram/transport-connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-connect.d.ts","sourceRoot":"","sources":["../../src/telegram/transport-connect.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe,GAAG,KAAK,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC1F,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAChE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC;IAClE,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACjC,OAAO,IAAI,OAAO,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,KAAK,0BAA0B,CAAC;AAEjC,+DAA+D;AAC/D,MAAM,MAAM,2BAA2B,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;AAEvF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAOD,eAAO,MAAM,UAAU,EAAE,2BAC0D,CAAC;AAEpF,eAAO,MAAM,UAAU,EAAE,wBAQgB,CAAC;AAkG1C;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,0BAA0B,CAAC,CAuCrC"}

package/dist/telegram/transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A Bot API transport that knows whether its request left.
+ *
+ * `fetch` folds establishing the connection and waiting for the answer into one failure, and
+ * from that failure nobody can say whether Telegram saw the message. A sender that must never
+ * duplicate a message then treats every network failure as "maybe delivered" and never repeats
+ * it, so a route that only sometimes fails to connect loses messages outright.
+ *
+ * This transport connects first and writes the request only on an established connection.
+ * Until the first byte is written, every failure is `TelegramNotDispatchedError`: the request
+ * certainly did not leave and repeating it is safe. After that, a failure is an ordinary error,
+ * because the request may have arrived. Addresses come in the system resolver's order with no
+ * family forced; the next address starts after a short delay (Happy Eyeballs), and a round with
+ * no connection is repeated with new sockets inside a bounded budget.
+ */
+import { type TelegramBotTransportOpen, type TelegramBotTransportResolve } from './transport-connect.js';
+export type { TelegramBotTransportOpen, TelegramBotTransportResolve, TelegramBotTransportSocket, } from './transport-connect.js';
+/** What the Bot API senders call: a URL and a request, answered by a `Response`. */
+export type TelegramFetch = (url: string, init: RequestInit) => Promise<Response>;
+export interface TelegramBotTransportOptions {
+    /** Real milliseconds one connection round waits. Default 2000: one kernel SYN retry fits. */
+    readonly connectAttemptMs?: number;
+    /** Real milliseconds after which no new connection round starts. Default 5000. */
+    readonly connectBudgetMs?: number;
+    /** Real milliseconds from the written request to the end of the answer. Default 30 000. */
+    readonly responseTimeoutMs?: number;
+    /** Largest answer read, in bytes. Default 1 MiB. */
+    readonly maxResponseBytes?: number;
+    /** Address lookup. Default: the system resolver, every address in its order. */
+    readonly resolve?: TelegramBotTransportResolve;
+    /** Socket factory. Default: TLS (ALPN `http/1.1`) for `https:`, plain TCP for `http:`. */
+    readonly open?: TelegramBotTransportOpen;
+}
+/**
+ * A `fetch` for the Bot API senders (`callTelegramBotApi`, `telegramBroadcastSender`,
+ * `telegramOperatorSender`) that separates "not sent" from "unknown". Pass it as their `fetch`:
+ * a failure before the request is written throws `TelegramNotDispatchedError`, which
+ * `classifyTelegramSendFailure` reads as `not-dispatched` (retryable); any later failure stays
+ * an outcome nobody can know. Speaks HTTP/1.1 over `https:` (and `http:` for a local Bot API
+ * server); it does not use a proxy.
+ */
+export declare function createTelegramBotTransport(options?: TelegramBotTransportOptions): TelegramFetch;
+//# sourceMappingURL=transport.d.ts.map

package/dist/telegram/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/telegram/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAIL,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAEjC,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,6FAA6F;IAC7F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,2BAA2B,CAAC;IAC/C,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC;CAC1C;AA+MD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,aAAa,CAyCf"}

package/dist/telegram/webhook.d.ts

@@ -18,6 +18,7 @@
  * recovered from it. Errors and reports name hosts only — a foreign webhook's
  * path may itself be a secret.
  */
+import type { TelegramFetch } from './transport.js';
 /** `takeoverFrom` when there is no webhook to take over — the bot polls, or is new. */
 export declare const TELEGRAM_WEBHOOK_NONE = "none";
 export interface TelegramWebhookConfig {
@@ -28,7 +29,7 @@ export interface TelegramWebhookConfig {
     readonly secret: string;
     /** A local Bot API server. Default: Telegram's. */
     readonly apiRoot?: string;
-    readonly fetch?: typeof fetch;
+    readonly fetch?: TelegramFetch;
     readonly signal?: AbortSignal;
 }
 export interface ClaimTelegramWebhookConfig extends TelegramWebhookConfig {

package/dist/telegram/webhook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/telegram/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB;AAChC,sCAAsC;AACpC,iBAAiB;AACnB,6DAA6D;GAC3D,cAAc;AAChB,2EAA2E;GACzE,eAAe,CAAC;AAEpB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,EAa5D;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAcD,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUrF;AA+BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAS/B;AAED,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,QAAQ,CAAC,CAUnB"}
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/telegram/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAOjD,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB;AAChC,sCAAsC;AACpC,iBAAiB;AACnB,6DAA6D;GAC3D,cAAc;AAChB,2EAA2E;GACzE,eAAe,CAAC;AAEpB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,EAa5D;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAcD,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUrF;AA+BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAS/B;AAED,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,QAAQ,CAAC,CAUnB"}

package/dist/testing/manual-clock.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Manual time for tests of schedules, retries and deadlines.
+ *
+ * Time stands still until the test moves it, and due timers fire strictly in deadline order
+ * (ties in scheduling order), so "retry after 5 s" runs in milliseconds and the same way every
+ * time. It satisfies every timer boundary Stitchkit accepts: `ManagedScheduleClock`,
+ * `DurabilityClock`, `RevisionSignalClock` and `BoundedAdmissionClock`.
+ *
+ * Between firings the clock yields to the **real event loop** (`setImmediate` turns), not just to
+ * microtasks: an async continuation that schedules the next timer often waits on I/O (a socket,
+ * a file), and without a real turn `advance(10_000)` would skip a retry the code meant to arm at
+ * the fifth second. When the work in flight has no bounded length (a request over a socket, a
+ * hash in a thread pool), the code under test `hold`s the clock for its duration; the clock does
+ * not move while a hold is open and waits for it in real time, up to `holdLimitMs`, then fails
+ * naming every open hold. A held operation that itself waits for the clock (a deadline it is
+ * timing out on) `park`s its hold, or the deadline it waits for would never come.
+ */
+/** Cancels one scheduled callback; calling it again is harmless. */
+export interface ManualClockTimer {
+    cancel(): void;
+}
+/** An open hold: the clock stays where it is until `release`, unless the hold is parked. */
+export interface ManualClockHold {
+    /** Ends the hold. */
+    release(): void;
+    /** The held work now waits for the clock itself; returns the function that ends the park. */
+    park(): () => void;
+}
+export interface ManualClockOptions {
+    /** Monotonic start, in milliseconds. Default `0`. */
+    readonly startMs?: number;
+    /** Wall-clock instant at `startMs`. Default `2026-01-01T00:00:00.000Z`. */
+    readonly wallStart?: Date;
+    /** Real event-loop turns yielded after each firing. Default `8`. */
+    readonly yieldTurns?: number;
+    /** Real milliseconds the clock waits for open holds before failing. Default `5000`. */
+    readonly holdLimitMs?: number;
+}
+export interface ManualClockUntilOptions {
+    /** Manual milliseconds per step while no timer is pending. Default `100`. */
+    readonly stepMs?: number;
+    /** Manual milliseconds after which `until` fails. Default `600_000`. */
+    readonly limitMs?: number;
+}
+export interface ManualClock {
+    /** Monotonic milliseconds. */
+    now(): number;
+    /** The wall clock that moves with `now`. */
+    wallNow(): Date;
+    /** Runs `callback` once the clock reaches `now() + delayMs` (negative delays fire next). */
+    schedule(callback: () => void, delayMs: number): ManualClockTimer;
+    /**
+     * Moves time by `ms`, firing every timer due on the way in deadline order and yielding to the
+     * event loop after each, so a timer armed by a fired callback inside the window fires too.
+     * A callback that throws rejects `advance` with that error.
+     */
+    advance(ms: number): Promise<void>;
+    /**
+     * Moves time from deadline to deadline (by `stepMs` while nothing is pending) until `done()`
+     * holds; resolves with the manual milliseconds that took. Fails with `MANUAL_CLOCK_LIMIT`
+     * once `limitMs` of manual time pass, naming how many timers are pending.
+     */
+    until(done: () => boolean, options?: ManualClockUntilOptions): Promise<number>;
+    /** How many timers wait. A timer leaked past a component's `close()` shows here. */
+    pending(): number;
+    /** Holds time while unbounded real work runs; `reason` names it if the hold outlives the limit. */
+    hold(reason: string): ManualClockHold;
+}
+/** `MANUAL_CLOCK_HOLD_TIMEOUT`: open holds outlived `holdLimitMs`; `MANUAL_CLOCK_LIMIT`: `until` ran out. */
+export type ManualClockErrorCode = 'MANUAL_CLOCK_HOLD_TIMEOUT' | 'MANUAL_CLOCK_LIMIT';
+/** A manual clock refused to go on; the message and `holds` name what did not finish. */
+export declare class ManualClockError extends Error {
+    readonly code: ManualClockErrorCode;
+    /** Reasons of the open, unparked holds (`MANUAL_CLOCK_HOLD_TIMEOUT` only). */
+    readonly holds: readonly string[];
+    readonly name = "ManualClockError";
+    constructor(code: ManualClockErrorCode, message: string, 
+    /** Reasons of the open, unparked holds (`MANUAL_CLOCK_HOLD_TIMEOUT` only). */
+    holds?: readonly string[]);
+}
+export declare function createManualClock(options?: ManualClockOptions): ManualClock;
+//# sourceMappingURL=manual-clock.d.ts.map

package/dist/testing/manual-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-clock.d.ts","sourceRoot":"","sources":["../../src/testing/manual-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,OAAO,IAAI,IAAI,CAAC;IAChB,6FAA6F;IAC7F,IAAI,IAAI,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,GAAG,IAAI,MAAM,CAAC;IACd,4CAA4C;IAC5C,OAAO,IAAI,IAAI,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAClE;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,OAAO,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,oFAAoF;IACpF,OAAO,IAAI,MAAM,CAAC;IAClB,mGAAmG;IACnG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;CACvC;AAED,6GAA6G;AAC7G,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,oBAAoB,CAAC;AAEtF,yFAAyF;AACzF,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,IAAI,EAAE,oBAAoB;IAEnC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE;IALnC,SAAkB,IAAI,sBAAsB;IAC5C,YACW,IAAI,EAAE,oBAAoB,EACnC,OAAO,EAAE,MAAM;IACf,8EAA8E;IACrE,KAAK,GAAE,SAAS,MAAM,EAAO,EAGvC;CACF;AAUD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA+H/E"}