stitchkit 0.114.2 → 0.116.0

package/dist/react/keyboard/layers.d.ts

@@ -94,6 +94,8 @@ export interface KeyLayerState<E extends LayerKeyEvent, S extends LayerScope<S>>
 export interface KeyLayerHandle<E extends LayerKeyEvent, S extends LayerScope<S>> {
     update(state: KeyLayerState<E, S>): void;
     remove(): void;
+    /** Put a removed layer back in the place it held, without counting as an activation. */
+    restore(): void;
 }
 /** Where the stack listens. A `Window` is one. */
 export interface KeyListenerTarget<E> {

package/dist/react/keyboard/layers.d.ts.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"broadcast-state.d.ts","sourceRoot":"","sources":["../../src/telegram/broadcast-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,eAAO,MAAM,8BAA8B;;;;;EAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,QAAA,MAAM,YAAY,iDAAyD,CAAC;AAC5E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAItE,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;oBASrB,CAAC;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAErD,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAAC;AAIlF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMtD;AAKD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAM9E;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAO9C;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,SAAS,0BAA0B,EAAE,EACjD,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,+FAA+F;AAC/F,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBpF;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAW5B"}
+{"version":3,"file":"broadcast-state.d.ts","sourceRoot":"","sources":["../../src/telegram/broadcast-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,eAAO,MAAM,8BAA8B;;;;;EAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,QAAA,MAAM,YAAY,iDAAyD,CAAC;AAC5E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAItE,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;oBASrB,CAAC;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAErD,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAAC;AAIlF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMtD;AAID,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAM9E;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAO9C;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,SAAS,0BAA0B,EAAE,EACjD,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,+FAA+F;AAC/F,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBpF;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAW5B"}

package/dist/telegram/budget-transformer.d.ts

@@ -16,7 +16,7 @@
  * grammY is named in the declarations and never imported at run time.
  */
 import type { Transformer } from 'grammy';
-import type { TelegramOutboundBudget } from './outbound-budget.js';
+import type { TelegramOutboundBudget, TelegramOutboundCallOptions } from './outbound-budget.js';
 /**
  * A grammY client transformer that runs every Bot API call under `budget`.
  *
@@ -30,6 +30,9 @@ import type { TelegramOutboundBudget } from './outbound-budget.js';
  * `TelegramNotDispatchedError`: nothing was sent. A cancellation after the
  * request was handed on is the client's ordinary error and the outcome is
  * unknown, not a definite failure.
+ *
+ * `options.lane` applies to every call through this client: a campaign installs
+ * `{ lane: 'bulk' }` on its own `Api`, and replies stay ahead of it.
  */
-export declare function telegramBudgetTransformer(budget: TelegramOutboundBudget): Transformer;
+export declare function telegramBudgetTransformer(budget: TelegramOutboundBudget, options?: TelegramOutboundCallOptions): Transformer;
 //# sourceMappingURL=budget-transformer.d.ts.map

package/dist/telegram/budget-transformer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"budget-transformer.d.ts","sourceRoot":"","sources":["../../src/telegram/budget-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA4BhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,WAAW,CAsBrF"}
+{"version":3,"file":"budget-transformer.d.ts","sourceRoot":"","sources":["../../src/telegram/budget-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AA4B7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,2BAA2B,GACpC,WAAW,CA4Bb"}

package/dist/telegram/outbound-budget.d.ts

@@ -13,9 +13,15 @@
  * `forwardMessages` cost their message ids, and the follow-up call to action
  * after an album is one more message.
  *
- * **It paces; it does not retry.** A 429 pauses every sender of the token for
- * the wait Telegram stated (or a declared fallback when it stated none). A
- * network failure or a 5xx is returned to the caller unchanged: repeating a
+ * Two lanes share that one rate. An `interactive` call is granted before any
+ * `bulk` call that is waiting, so a person's reply never queues behind a
+ * campaign; a campaign runs at whatever rate replies leave it.
+ *
+ * **It paces; it does not retry.** A 429 on a method that spends the budget
+ * pauses every sender of the token for the wait Telegram stated (or a declared
+ * fallback when it stated none). A 429 on an edit or a read concerns that call
+ * and pauses nothing. A network failure or a 5xx is returned to the caller
+ * unchanged: repeating a
  * send whose external outcome is unknown is the caller's decision, and a
  * primitive that retried it would turn one unknown message into two.
  *
@@ -25,6 +31,8 @@
  * saved burst at start and again after a 429 pause, which is exactly the
  * stampede a shared budget exists to prevent.
  */
+/** Whose turn comes first. `interactive` answers a person; `bulk` is a campaign. */
+export type TelegramOutboundLane = 'interactive' | 'bulk';
 export interface TelegramOutboundBudgetConfig {
     /** The bot token whose sends share this budget. It is never returned or logged. */
     readonly token: string;
@@ -52,31 +60,38 @@ export interface TelegramOutboundBudgetStats {
     readonly granted: number;
     /** Weighted messages admitted: an album of three counts as three. */
     readonly messages: number;
-    /** Calls waiting for their turn. */
+    /** Calls waiting for their turn, in both lanes. */
     readonly queued: number;
+    /** How many of them are in the `bulk` lane. */
+    readonly queuedBulk: number;
     readonly messagesPerSecond: number;
     /** How much of the current 429 pause is still ahead, in milliseconds. */
     readonly pausedForMs: number;
 }
+export interface TelegramOutboundCallOptions {
+    /** Default `interactive`. */
+    readonly lane?: TelegramOutboundLane;
+}
 /**
  * A token's outbound budget. `run` is the narrow adapter a client transformer
  * calls around its own send; it gates, pauses on 429 and never retries.
  */
 export interface TelegramOutboundBudget {
     /**
-     * Run one Bot API call under the budget. A non-send method passes through
-     * without spending a message. A 429 pauses every sender of the token, whether
-     * `send` throws it or resolves with the Bot API's `{ ok: false, … }` body, as
-     * a client transformer's `send` does. The error is rethrown, or the response
-     * returned, unchanged and the call is not repeated.
+     * Run one Bot API call under the budget, in the `interactive` lane by default.
+     * A non-send method passes through without spending a message. A 429 on a send
+     * pauses every sender of the token, whether `send` throws it or resolves with
+     * the Bot API's `{ ok: false, … }` body, as a client transformer's `send` does;
+     * a 429 on a non-send method pauses nothing. The error is rethrown, or the
+     * response returned, unchanged and the call is not repeated.
      */
-    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>): Promise<T>;
+    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>, options?: TelegramOutboundCallOptions): Promise<T>;
     /**
      * Wait until `cost` messages fit. The wait rejects with `signal.reason`
      * without spending a token; a granted call owns its slots even if its later
      * send is aborted, which the caller must not repeat as a definite failure.
      */
-    acquire(cost: number, signal?: AbortSignal): Promise<void>;
+    acquire(cost: number, signal?: AbortSignal, options?: TelegramOutboundCallOptions): Promise<void>;
     /** Pause every sender of this token for at least `milliseconds`. Never shortens an existing pause. */
     pause(milliseconds: number): void;
     /** Pause the token after a rate-limited refusal; another failure does nothing. */

package/dist/telegram/outbound-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwEH,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AAyMD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}
+{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAwEH,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AA6ND;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}

package/dist/tools/cli/download.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/download.ts"],"names":[],"mappings":"AAIA,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAE5D,oFAAoF;AACpF,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,OAAO,CAAC,CAyBlB"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/download.ts"],"names":[],"mappings":"AAOA,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAE5D,oFAAoF;AACpF,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,OAAO,CAAC,CA8ClB"}

package/dist/tools/cli/publication-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publication-storage.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/publication-storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,YAAY,CAAC;AAE3E,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,UAAU,CAAC;CACnB;AACD,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACvD,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,mBAAmB,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAKvC;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAcnB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAiB1C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,YAAY,EAAE,OAAO,GACpB,MAAM,EAAE,CAuCV;AA4BD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BzB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf;AAKD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAkBjB"}
+{"version":3,"file":"publication-storage.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/publication-storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,YAAY,CAAC;AAE3E,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,UAAU,CAAC;CACnB;AACD,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACvD,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,mBAAmB,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAKvC;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAcnB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAiB1C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,YAAY,EAAE,OAAO,GACpB,MAAM,EAAE,CAuCV;AA4BD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BzB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf;AAKD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/tools/cli/publication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/publication.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,EAGL,KAAK,qBAAqB,EAI3B,MAAM,wBAAwB,CAAC;AAoBhC,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGhB,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAoThE;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAU/B"}
+{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/publication.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EAGL,KAAK,qBAAqB,EAI3B,MAAM,wBAAwB,CAAC;AAoBhC,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGhB,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAoThE;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAU/B"}

package/dist/tools/cli/view.d.ts

@@ -1,12 +1,18 @@
 import type { CliResultView } from './args-view.js';
-/** What a view produces: a JSON value, or the one human-facing shape. */
+/**
+ * What a view produces: a JSON value, or the one human-facing shape. `order` is the order of
+ * a grouped object's keys, which an object cannot hold once a key looks like an integer.
+ */
 export type CliViewOutput = {
     kind: 'json';
     data: unknown;
+    order?: readonly string[];
 } | {
     kind: 'text';
     text: string;
 };
+/** One grouped view in its own order, spaced as the CLI spaces any JSON it prints. */
+export declare function stringifyGroups(data: unknown, order: readonly string[], compact: boolean): string;
 /** Compute the requested view, or refuse it with a message naming the field. */
 export declare function renderCliView(data: unknown, view: CliResultView): CliViewOutput;
 //# sourceMappingURL=view.d.ts.map

package/dist/tools/cli/view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/view.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwK7F,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CA+B/E"}
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/view.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAuGnC,sFAAsF;AACtF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,OAAO,GACf,MAAM,CAMR;AA6GD,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CAgC/E"}

package/llms/agent-runtime.txt

@@ -301,17 +301,27 @@ approval input fails the run with a private diagnostic rather than starting a fr
 `read_output`. Every call passes a required host authorization callback. An optional async/sync
 `authorizePath({ path })` is the one operation-independent policy for direct file access and
 discovery: direct read/write/edit refuses a denied path, while listing, glob and search omit it.
-Denial is recursive on every surface — direct access and discovery base paths ask about `.` and each
-ancestor, outermost first, stopping at the first refusal, so denying `credentials` denies everything
+Denial is recursive on every surface — direct access asks about each named ancestor and the file,
+outermost first, stopping at the first refusal; discovery rooted at `.` also asks about `.`.
+Thus denying `credentials` denies everything
 under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
-depth N costs N+1 questions. Directory decisions happen before descent; file decisions and
+depth N costs N questions for direct access. Directory decisions happen before descent; file decisions and
 `search_files.include` happen before opening content. Requested paths use `/`: a backslash is
 refused rather than normalised, because the workspace walk reads it as a separator and every
 authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
-descriptor-relative resolution: each ancestor is opened without following symlinks and remains
-pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
+descriptor-relative resolution: each ancestor is opened without following symlinks. Reads and edits
+stay pinned through authorization; `write_file` plans before it and opens the parent after, because
+the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
-only through opened directories. Linux traverses `/proc/self/fd`; macOS uses the package's
+only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
+A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
+case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
+NUL bytes are refused before either host policy sees a path.
+Reads and edits open file candidates without blocking on special files, then require a regular
+file. A writerless FIFO therefore refuses instead of occupying a filesystem worker. `write_file`
+supplies the exact missing-directory plan as `createsDirectories` to host authorization; the
+descriptor walk may create only those entries. An ancestor that disappears after approval refuses
+with `CONFLICT`, without expanding that plan. Linux traverses `/proc/self/fd`; macOS uses the package's
 architecture-specific Node-API `openat` backend. Unsupported platforms, including FreeBSD until a
 real backend is qualified, fail closed. The package needs no install-time compiler or script.
 Other platforms fail these filesystem operations closed because Node exposes no equivalent

package/llms/cli.txt

@@ -612,6 +612,29 @@ myapp generate "a fox" --wait --output-dir ./out
 myapp generate "a fox" --wait --json > result.json &
 ```
 
+### Download filesystem boundary
+
+`--output-dir` resolves the explicitly configured root once before fetching and pins that
+one directory for the whole batch. An initial root alias (including a symbolic link) selects
+its canonical directory; missing components are created through pinned parents. The root
+capability continues to name the same directory if another actor renames it or replaces its
+pathname. The original spelling printed in `saved` is a display path, not a re-open of the root.
+
+Each media name becomes a direct child. Downloads atomically replace an existing file,
+symbolic link (including a dangling link), or hard link without changing the inode a link
+points to. An existing directory refuses replacement. Ordinary files retain their permission
+bits; new files use `0666 & ~umask`. Replacing writes a new file beside the old one, so it needs
+write permission on the directory, gives the file to the process user, replaces a read-only
+file, and refuses a bind-mounted one. Symlinks inside a contained parent path are never followed.
+The successful operation's JSON remains on stdout when a download fails; per-file diagnostics
+go to stderr and any failed file makes the exit non-zero. Already saved files remain saved.
+
+This filesystem protection supports Linux and macOS. On Linux it uses directory descriptors;
+on macOS it uses the packaged native backend. A bundled or compiled macOS CLI must use
+[`createNativePackaging`](./native-io.md) from `stitchkit/files/packaging` at build
+time. Missing native support and unsupported platforms, including Windows, refuse the download;
+CLI commands without downloads continue to work. There is no weaker path-based fallback.
+
 ## Aggregate views
 
 The CLI's audience is agents, scripts and `jq`, so output is JSON. That settles
@@ -647,16 +670,27 @@ myapp item_list --sort messages --top 5 --json                # the same five, a
 myapp item_list --sort name --ascending                       # ordered the other way
 ```
 
-Groups come back largest first for the same reason. A record that carries no
+Groups come back largest first for the same reason, in the printed bytes even when a key looks
+like a number; a reader that parses them into a JavaScript object reorders such keys itself.
+A string equal to `null` or `(absent)` is quoted, so it stays apart from the missing value. A record that carries no
 value for the sort field sorts **last in both directions**: it is not the
 smallest, it is not on the scale at all, and letting it lead an ascending list
 would answer a question nobody asked.
 
-Three rules worth knowing before you rely on them:
+Rules worth knowing before you rely on them:
 
-- **A field the result does not carry is a presentation error.** A group of zero
+- **A field no record carries in a nonempty collection is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
+  Plain and dotted field paths read own properties only at every segment; inherited
+  properties are not record data. Own keys named `constructor`, `prototype` or `toString`
+  are ordinary fields.
+- **An empty collection is a successful answer.** Count and grouped sums return `{}`,
+  an ungrouped sum returns `0`, and sorted records return `[]`. Tables keep their header
+  and separator without data rows. This applies both to a direct `[]` and to the single
+  array field of an envelope such as `{ items: [], total: 0 }`. With no records, field
+  presence cannot be checked, so a misspelled field answers empty too; malformed paths, unsafe
+  `__proto__` segments and a field of the envelope itself (`--sum total` here) still refuse.
 - **An aggregate needs a collection** — the result itself when it is an array,
   or the single array field of a result object. An aggregate over a scalar, or
   over an object with two array fields, is refused rather than guessed.

package/llms/process.txt

@@ -522,8 +522,8 @@ a static loader enters a bundle.
 
 Only these calls load the addon, and only on macOS: process identity (`observeProcessInstance`
 and `probeProcessOwner`), every exclusive lock (`withExclusiveLock` and what is built on it, such
-as the file state store and the diagnostic journal) and the contained file operations of the Agent
-coding tools. Without the addon a lock still works, but it cannot record or check its owner's
+as the file state store and the diagnostic journal), the contained file operations of the Agent
+coding tools and `--output-dir` downloads of `stitchkit/cli`. Without the addon a download refuses, and a lock still works, but it cannot record or check its owner's
 identity, so a lock held by a crashed owner is not reclaimed. The managed file boundary
 (`createManagedFileBoundary` and the transfer tools built on it), atomic writes and the chunk
 spool never load it, on any operating system. The package is free of import side effects

package/llms/react-keyboard.txt

@@ -89,6 +89,17 @@ together, only `scope` tells the stack which one is inside.
 **`active`** (default `true`) switches a layer off without unmounting it;
 becoming active again puts it on top of its kind.
 
+Layers register, adopt options and clean up in the browser's layout-effect phase.
+Call the hook before a layout effect that dispatches a key: that effect sees the
+committed `active`, handler and scope immediately, without waiting for passive
+effects. Rendering alone never changes the stack; an abandoned render leaves the
+last committed layer intact. A Suspense boundary that hides committed content
+disconnects its layout effects, so a layer behind the fallback goes quiet and
+returns to its place on reveal. The same lifecycle backs `useEscapeLayer` and a
+zone's outside-key layer. Server rendering installs no listener and does not
+access `window`. The browser phase is chosen when the module loads, so a test
+that installs a DOM does so before it imports these hooks.
+
 **Fields keep their keys.** Keys pressed in an input, a text area, a select, an
 editable region, a combobox, a slider or any area marked `data-local-keys` do not
 reach layers — except Escape, which a field that wants it keeps with
@@ -140,6 +151,11 @@ function ChatList({ chats, openId, open }) {
 | `ignore(event)` | — | a key that is the application's own right now — return `true` and the zone leaves it whole; see [dragging](#a-zone-inside-a-drag-and-drop-list) |
 | `onReveal(id)` | — | focus went to an item with no element yet — a row of a virtualized list outside the rendered range; scroll it in, and focus lands on it when it mounts |
 
+`role: 'none'` adds neither a container/item role nor `aria-orientation` or
+`aria-selected`; native links and buttons keep their semantics. The orientation
+still controls which arrows move focus. Only listbox and tablist zones emit
+`aria-orientation` (vertical by default).
+
 The callbacks return `false` to leave the key to the page, anything else takes
 it. A key the zone does not take bubbles on to the layers — in a vertical list
 ← and → are not the list's keys, so the section switch above hears them.
@@ -420,9 +436,9 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `useKeyLayer` | hook | put a layer on the window's one key stack — asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
+| `useKeyLayer` | hook | put a layer on the window's one key stack; registration, options and cleanup follow the browser layout-effect phase, before later layout effects in the caller; asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
 | `useEscapeLayer` | hook | an `overlay`, `local` or `route` layer for Escape: one press closes one level |
-| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value |
+| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value; `role: 'none'` omits roles, `aria-orientation` and `aria-selected`, preserving native link/button semantics |
 | `nextZoneIndex` | function | where a move lands in a list of a given length: an index, `'before-start'` or `'after-end'` |
 | `isKeyFieldTarget` | function | whether a key was pressed in a field or a `data-local-keys` area, the test layers use |
 | `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields`, `phase` — `'capture'` is for a `local` layer only: it hears a key before the element that has focus does, as a menu over a text field must, and a key it takes goes no further |

package/llms/stitchkit.txt

@@ -86,13 +86,13 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 59 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 61 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 24 of the 59 minors since 0.56.2, most recently 0.113.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 61 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -104,7 +104,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 59 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 61 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/telegram.txt

@@ -122,6 +122,13 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   a follow-up call to action after an album costs one more. Reads and edits
   (`getMe`, `getFile`, `editMessage*`, `deleteMessage`, `sendChatAction`) do not
   spend the budget.
+- **Two lanes share one rate.** A call is `interactive` by default; a campaign passes
+  `{ lane: 'bulk' }` to `run` or `acquire`, or installs
+  `telegramBudgetTransformer(budget, { lane: 'bulk' })` on its own `Api`. A waiting
+  interactive call is granted first, so a reply never queues behind recipients;
+  the wait it can still see is the interval of the grant before it, up to one
+  album. Bulk runs at whatever rate replies leave, and the sum never exceeds
+  `messagesPerSecond`.
 - **The first send after idle is immediate; the rest are spaced.** This is a
   strict budget, not a bucket that saves a burst: at 24/s the next send is due
   one interval later. A 429 pauses the whole token; when it resumes, one send
@@ -133,8 +140,8 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   The refusal may be thrown or returned: a client transformer sits below the
   place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
   a `GrammyError`, so `run` reads that body too and hands it back unchanged.
-  A 429 from an edit or a read is still a fact about the token and pauses later
-  sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
+  A 429 from an edit or a read concerns that call and pauses nothing; `budget.pauseAfter`
+  remains for a caller who decides otherwise. A network failure is rethrown unchanged and stays `unknown`; a 5xx
   is rethrown unchanged and stays `server-error`. Neither is retried by the
   budget or pauses the token — repeating a send whose outcome is unknown is a
   decision, not a primitive's silent guess.
@@ -608,7 +615,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` / `TelegramOutboundCallOptions` / `TelegramOutboundLane` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, an `interactive` lane granted before `bulk`, `run(method, payload, signal, send, { lane })` as the transformer adapter (a 429 on a send pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |