stitchkit 0.108.4 → 0.109.0

package/dist/index-t5sjh517.js

@@ -0,0 +1,100 @@
+// src/tools/schema/json-schema-origin.ts
+import { z } from "zod";
+var JSON_SCHEMA_OBJECT_GUARD = Symbol.for("stitchkit.tools.json-schema-object-guard-origin.v1");
+function mark(schema) {
+  if (Reflect.get(schema, JSON_SCHEMA_OBJECT_GUARD) === true)
+    return;
+  const marked = Reflect.defineProperty(schema, JSON_SCHEMA_OBJECT_GUARD, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false
+  });
+  if (!marked)
+    throw new Error("Cannot mark a restored JSON Schema object guard");
+}
+function markObjectGuard(schema) {
+  if (schema.in instanceof z.ZodTransform && schema.out instanceof z.ZodObject && schema.in.def.checks?.length) {
+    mark(schema);
+    return true;
+  }
+  return false;
+}
+function markJsonSchemaObjectGuards(schema) {
+  const visited = new WeakMap;
+  const visit = (current) => {
+    const known = visited.get(current);
+    if (known !== undefined)
+      return known;
+    visited.set(current, false);
+    if (current instanceof z.ZodPipe) {
+      const guarded = markObjectGuard(current);
+      visit(current.out);
+      visited.set(current, guarded);
+      return guarded;
+    }
+    if (current instanceof z.ZodObject) {
+      for (const field of Object.values(current.shape))
+        visit(field);
+      const catchall = current.def.catchall;
+      if (catchall)
+        visit(catchall);
+      return false;
+    }
+    if (current instanceof z.ZodArray) {
+      visit(current.element);
+      return false;
+    }
+    if (current instanceof z.ZodTuple) {
+      for (const item of current.def.items)
+        visit(item);
+      if (current.def.rest)
+        visit(current.def.rest);
+      return false;
+    }
+    if (current instanceof z.ZodRecord) {
+      visit(current.keyType);
+      visit(current.valueType);
+      return false;
+    }
+    if (current instanceof z.ZodUnion) {
+      for (const option of current.def.options)
+        visit(option);
+      return false;
+    }
+    if (current instanceof z.ZodIntersection) {
+      const leftGuarded = visit(current.def.left);
+      const rightGuarded = visit(current.def.right);
+      const guarded = leftGuarded || rightGuarded;
+      if (guarded)
+        mark(current);
+      visited.set(current, guarded);
+      return guarded;
+    }
+    if (current instanceof z.ZodOptional || current instanceof z.ZodExactOptional || current instanceof z.ZodNullable || current instanceof z.ZodDefault || current instanceof z.ZodPrefault || current instanceof z.ZodNonOptional || current instanceof z.ZodCatch || current instanceof z.ZodReadonly || current instanceof z.ZodLazy) {
+      const guarded = visit(current.unwrap());
+      if (guarded)
+        mark(current);
+      visited.set(current, guarded);
+      return guarded;
+    }
+    return false;
+  };
+  visit(schema);
+}
+function jsonSchemaObjectCoercionMembers(schema) {
+  if (Reflect.get(schema, JSON_SCHEMA_OBJECT_GUARD) !== true)
+    return;
+  if (schema instanceof z.ZodPipe && schema.out instanceof z.ZodObject) {
+    return [schema.out];
+  }
+  if (schema instanceof z.ZodIntersection) {
+    return [schema.def.left, schema.def.right];
+  }
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodExactOptional || schema instanceof z.ZodNullable || schema instanceof z.ZodDefault || schema instanceof z.ZodPrefault || schema instanceof z.ZodNonOptional || schema instanceof z.ZodCatch || schema instanceof z.ZodReadonly || schema instanceof z.ZodLazy) {
+    return [schema.unwrap()];
+  }
+  return;
+}
+
+export { markJsonSchemaObjectGuards, jsonSchemaObjectCoercionMembers };

package/dist/{index-yz8x0hbx.js → index-tpk71wqn.js}

@@ -14,7 +14,7 @@ import {
 import {
   ToolExecutionControlError2,
   isToolExecutionControlError2
-} from "./index-dm2fv45z.js";
+} from "./index-k4v2kq4q.js";
 import {
   agentDurableEventId2
 } from "./index-mnkk1ffz.js";

package/dist/{index-mep4sb48.js → index-x5xs71dw.js}

@@ -13,15 +13,15 @@ import {
   parseToolCallArguments,
   toolResultFromError,
   observed
-} from "./index-dm2fv45z.js";
+} from "./index-k4v2kq4q.js";
 import {
   collectTools2,
   createToolRunner,
   formatToolError
-} from "./index-2s6fpehp.js";
+} from "./index-ryv32myz.js";
 import {
   collectToolSurface
-} from "./index-cx2nh595.js";
+} from "./index-3wm2xp2a.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS2,
   DEFAULT_PROCESS_SIGNALS,

package/dist/telegram/update-intake-work.d.ts

@@ -0,0 +1,39 @@
+import type { TelegramUpdateAttemptIntakeConfig, TelegramUpdateEnvelope, TelegramUpdateIntakeConfig, TelegramUpdateStoreStep } from './update-intake.js';
+import type { StoredTelegramUpdateExhaustion, TelegramUpdateAttemptIdentity, TelegramUpdateDurableStore, TelegramUpdateFencedStore, TelegramUpdateStore } from './update-store.js';
+type TelegramUpdateAnyIntakeConfig<TUpdate extends TelegramUpdateEnvelope> = TelegramUpdateIntakeConfig<TUpdate> | TelegramUpdateAttemptIntakeConfig<TUpdate>;
+export type TelegramUpdateStoreErrorReporter = (error: unknown, step: TelegramUpdateStoreStep) => void;
+/** One shared concurrency budget for ordinary attempts and exhaustion delivery. */
+export interface TelegramUpdateWorkSlots {
+    take(): Promise<void>;
+    release(): void;
+}
+export declare function createTelegramUpdateWorkSlots(maxConcurrent: number): TelegramUpdateWorkSlots;
+export interface TelegramUpdateExhaustionScheduler {
+    schedule(row: StoredTelegramUpdateExhaustion, active: boolean): boolean;
+    pending(): readonly Promise<void>[];
+}
+/** Deliver recoverable terminal obligations without creating another durable queue. */
+export declare function createTelegramUpdateExhaustionScheduler<TUpdate extends TelegramUpdateEnvelope>(options: {
+    readonly config: TelegramUpdateAnyIntakeConfig<TUpdate>;
+    readonly store: TelegramUpdateDurableStore | undefined;
+    readonly now: () => number;
+    readonly slots: TelegramUpdateWorkSlots;
+    readonly parse: (body: string) => Record<string, unknown> | undefined;
+    readonly reportStoreError: TelegramUpdateStoreErrorReporter;
+}): TelegramUpdateExhaustionScheduler;
+/** Build the claim/renew/settle state machine for one update attempt. */
+export declare function createTelegramUpdateAttemptRunner<TUpdate extends TelegramUpdateEnvelope>(options: {
+    readonly config: TelegramUpdateAnyIntakeConfig<TUpdate>;
+    readonly store: TelegramUpdateStore;
+    readonly fenced: TelegramUpdateFencedStore | undefined;
+    readonly durable: TelegramUpdateDurableStore | undefined;
+    readonly now: () => number;
+    readonly retry: (error: unknown, attempt: number) => number | false;
+    readonly maxAttempts: number;
+    readonly leaseMs: number;
+    readonly reportStoreError: TelegramUpdateStoreErrorReporter;
+    readonly scheduleExhaustion: (row: StoredTelegramUpdateExhaustion) => void;
+    readonly ownershipLostReason: (identity: TelegramUpdateAttemptIdentity) => unknown;
+}): (update: Record<string, unknown>, updateId: number) => Promise<void>;
+export {};
+//# sourceMappingURL=update-intake-work.d.ts.map

package/dist/telegram/update-intake-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-intake-work.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake-work.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,iCAAiC,EACjC,sBAAsB,EAEtB,0BAA0B,EAC1B,uBAAuB,EACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,8BAA8B,EAC9B,6BAA6B,EAC7B,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAExB,KAAK,6BAA6B,CAAC,OAAO,SAAS,sBAAsB,IACrE,0BAA0B,CAAC,OAAO,CAAC,GACnC,iCAAiC,CAAC,OAAO,CAAC,CAAC;AAE/C,MAAM,MAAM,gCAAgC,GAAG,CAC7C,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,uBAAuB,KAC1B,IAAI,CAAC;AAEV,mFAAmF;AACnF,MAAM,WAAW,uBAAuB;IACtC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,6BAA6B,CAAC,aAAa,EAAE,MAAM,GAAG,uBAAuB,CAiB5F;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,GAAG,EAAE,8BAA8B,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACxE,OAAO,IAAI,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;CACrC;AAED,uFAAuF;AACvF,wBAAgB,uCAAuC,CACrD,OAAO,SAAS,sBAAsB,EACtC,OAAO,EAAE;IACT,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,QAAQ,CAAC,gBAAgB,EAAE,gCAAgC,CAAC;CAC7D,GAAG,iCAAiC,CA4CpC;AAYD,yEAAyE;AACzE,wBAAgB,iCAAiC,CAC/C,OAAO,SAAS,sBAAsB,EACtC,OAAO,EAAE;IACT,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,gCAAgC,CAAC;IAC5D,QAAQ,CAAC,kBAAkB,EAAE,CAAC,GAAG,EAAE,8BAA8B,KAAK,IAAI,CAAC;IAC3E,QAAQ,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,6BAA6B,KAAK,OAAO,CAAC;CACpF,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CA+JvE"}

package/dist/telegram/update-intake.d.ts

@@ -18,7 +18,7 @@
  * `processing` whose lease nobody renewed. Delivery is at least once: a
  * handler that finished but could not be recorded as finished runs again.
  */
-import type { TelegramUpdateStore } from './update-store.js';
+import type { TelegramUpdateAttemptIdentity, TelegramUpdateFencedStore, TelegramUpdateStore } from './update-store.js';
 import type { TelegramUpdateAcceptance } from './webhook.js';
 /** An update as Telegram sends it; name grammY's `Update` to get its full type. */
 export interface TelegramUpdateEnvelope {
@@ -31,15 +31,32 @@ export interface TelegramUpdateFailure {
     /** `false` when the update was abandoned — no attempt follows. */
     readonly retrying: boolean;
 }
+/** One handler invocation under one immutable store claim. */
+export interface TelegramUpdateAttemptContext extends TelegramUpdateAttemptIdentity {
+    /** Pass this exact identity to a fenced store check inside the consumer's DB transaction. */
+    readonly fence: TelegramUpdateAttemptIdentity;
+    /** Aborted once renewal proves the attempt lost ownership or its last proven lease expires. */
+    readonly ownerLost: AbortSignal;
+}
+/** A terminal update failure recovered from the same durable update store. */
+export interface TelegramUpdateExhaustion<TUpdate extends TelegramUpdateEnvelope> extends TelegramUpdateAttemptIdentity {
+    readonly update: TUpdate;
+    readonly exhaustedAt: number;
+    readonly error: string;
+}
+/** A failed delivery of a durable terminal-update obligation. */
+export interface TelegramUpdateExhaustionFailure<TUpdate extends TelegramUpdateEnvelope> {
+    readonly exhaustion: TelegramUpdateExhaustion<TUpdate>;
+    readonly error: unknown;
+}
+/** The reason carried by `ownerLost` when an attempt no longer owns its lease. */
+export declare class TelegramUpdateOwnershipLostError extends Error {
+    readonly identity: TelegramUpdateAttemptIdentity;
+    constructor(identity: TelegramUpdateAttemptIdentity);
+}
 export type TelegramUpdateStoreStep = 'claim' | 'renew' | 'settle' | 'sweep';
-export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelope> {
-    readonly store: TelegramUpdateStore;
-    /**
-     * Handle one update — with grammY, `(update) => bot.handleUpdate(update)`.
-     * A grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored
-     * error see what the middleware threw.
-     */
-    readonly handle: (update: TUpdate) => unknown;
+/** Retry, lease, scheduling and observation options shared by both handler forms. */
+export interface TelegramUpdateIntakeOptions<TUpdate extends TelegramUpdateEnvelope> {
     /**
      * After a failed attempt: milliseconds until the next, or `false` to
      * abandon the update. Default: abandon what Telegram said repeating cannot
@@ -61,11 +78,31 @@ export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelo
     readonly maxConcurrent?: number;
     /** Every failed attempt. */
     readonly onFailure?: (failure: TelegramUpdateFailure) => void;
+    /**
+     * A durable final obligation. Resolving acknowledges it; throwing leaves it
+     * in the same store for a later sweep. Requires a `TelegramUpdateDurableStore`.
+     * Delivery is at least once, so persist by the supplied update/attempt identity.
+     */
+    readonly handleExhaustion?: (exhaustion: TelegramUpdateExhaustion<TUpdate>) => unknown;
+    /** An observational report that `handleExhaustion` threw; it never acknowledges the row. */
+    readonly onExhaustionFailure?: (failure: TelegramUpdateExhaustionFailure<TUpdate>) => void;
     /** The store refused a step; the update is retried when its lease lapses. */
     readonly onStoreError?: (error: unknown, step: TelegramUpdateStoreStep) => void;
     /** Default `Date.now`. */
     readonly now?: () => number;
 }
+/** Existing one-argument intake configuration. */
+export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelope> extends TelegramUpdateIntakeOptions<TUpdate> {
+    readonly store: TelegramUpdateStore;
+    /** Direct grammY handlers keep their optional second argument private. */
+    readonly handle: (update: TUpdate) => unknown;
+}
+/** Intake configuration for a handler that needs attempt ownership metadata. */
+export interface TelegramUpdateAttemptIntakeConfig<TUpdate extends TelegramUpdateEnvelope> extends TelegramUpdateIntakeOptions<TUpdate> {
+    readonly store: TelegramUpdateFencedStore;
+    /** Handle an update with its immutable attempt fence and ownership-loss signal. */
+    readonly handleAttempt: (update: TUpdate, context: TelegramUpdateAttemptContext) => unknown;
+}
 export interface TelegramUpdateIntake {
     /** Record one webhook body; handling starts after, once the intake is started. */
     accept(body: string): Promise<TelegramUpdateAcceptance>;
@@ -79,4 +116,5 @@ export interface TelegramUpdateIntake {
     close(): Promise<void>;
 }
 export declare function createTelegramUpdateIntake<TUpdate extends TelegramUpdateEnvelope>(config: TelegramUpdateIntakeConfig<TUpdate>): TelegramUpdateIntake;
+export declare function createTelegramUpdateIntake<TUpdate extends TelegramUpdateEnvelope>(config: TelegramUpdateAttemptIntakeConfig<TUpdate>): TelegramUpdateIntake;
 //# sourceMappingURL=update-intake.d.ts.map

package/dist/telegram/update-intake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,sBAAsB;IAChF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACrE,iBAAiB;IACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChF,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsED,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,sBAAsB,EAC/E,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAiJtB"}
+{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"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"}

package/dist/telegram/update-store-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-store-check.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAqG1D;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAC7D,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}
+{"version":3,"file":"update-store-check.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAiXxB;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAC7D,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}

package/dist/telegram/update-store-postgres.d.ts

@@ -13,7 +13,7 @@
  * Parameters carry explicit casts: a driver that sends a JS number as a
  * double still lands in a `bigint` column.
  */
-import type { TelegramUpdateStore } from './update-store.js';
+import type { TelegramUpdateDurableStore } from './update-store.js';
 /** Run one statement with `$1…$n` parameters; resolve with the rows it returned. */
 export type TelegramPostgresQuery = (text: string, parameters: readonly (string | number | null)[]) => Promise<readonly unknown[]>;
 export interface PostgresTelegramUpdateStoreConfig {
@@ -29,5 +29,5 @@ export interface PostgresTelegramUpdateStoreConfig {
 }
 /** The table and its index, for a migration. Safe to run twice. */
 export declare function postgresTelegramUpdateStoreSchema(table?: string): string;
-export declare function postgresTelegramUpdateStore(config: PostgresTelegramUpdateStoreConfig): TelegramUpdateStore;
+export declare function postgresTelegramUpdateStore(config: PostgresTelegramUpdateStoreConfig): TelegramUpdateDurableStore;
 //# sourceMappingURL=update-store-postgres.d.ts.map

package/dist/telegram/update-store-postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-store-postgres.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAA4B,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEpF,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,KAC5C,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAEjC,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAaD,mEAAmE;AACnE,wBAAgB,iCAAiC,CAAC,KAAK,SAAqB,GAAG,MAAM,CAapF;AAqBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iCAAiC,GACxC,mBAAmB,CAyGrB"}
+{"version":3,"file":"update-store-postgres.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAIV,0BAA0B,EAE3B,MAAM,gBAAgB,CAAC;AAExB,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,KAC5C,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAEjC,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAaD,mEAAmE;AACnE,wBAAgB,iCAAiC,CAAC,KAAK,SAAqB,GAAG,MAAM,CAepF;AA4HD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iCAAiC,GACxC,0BAA0B,CAmK5B"}

package/dist/telegram/update-store-sqlite.d.ts

@@ -6,7 +6,7 @@
  * Each rule of `TelegramUpdateStore` is one conditional statement, so a claim
  * is atomic across processes sharing the file.
  */
-import type { TelegramUpdateStore } from './update-store.js';
+import type { TelegramUpdateDurableStore } from './update-store.js';
 /** What this store needs of a SQLite handle; both runtimes' handles have it. */
 export interface TelegramSqliteDatabase {
     exec(sql: string): unknown;
@@ -22,5 +22,5 @@ export interface SqliteTelegramUpdateStoreConfig {
     /** Default `telegram_updates`. Created when missing. */
     readonly table?: string;
 }
-export declare function sqliteTelegramUpdateStore(config: SqliteTelegramUpdateStoreConfig): TelegramUpdateStore;
+export declare function sqliteTelegramUpdateStore(config: SqliteTelegramUpdateStoreConfig): TelegramUpdateDurableStore;
 //# sourceMappingURL=update-store-sqlite.d.ts.map

package/dist/telegram/update-store-sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-store-sqlite.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QACtF,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,+BAA+B,GACtC,mBAAmB,CAkFrB"}
+{"version":3,"file":"update-store-sqlite.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAKV,0BAA0B,EAE3B,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QACtF,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA+ID,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,+BAA+B,GACtC,0BAA0B,CAyI5B"}

package/dist/telegram/update-store.d.ts

@@ -12,7 +12,10 @@
  *   whose attempts are spent as `abandoned`;
  * - `renew` and `settle` act only while the record is still `processing` under
  *   the same attempt, so a process that lost its lease cannot overwrite the
- *   one that took it over.
+ *   one that took it over;
+ * - a durable abandonment keeps `settledAt` empty until the consumer has
+ *   handled its final obligation. It stays in this record and is never pruned
+ *   while it is pending.
  */
 export type TelegramUpdateState = 'pending' | 'processing' | 'failed' | 'completed' | 'abandoned';
 export type TelegramUpdateSettlement = {
@@ -32,6 +35,8 @@ export interface TelegramUpdateClaimOptions {
     readonly now: number;
     readonly leaseUntil: number;
     readonly maxAttempts: number;
+    /** Keep an attempts-spent abandonment pending until the consumer acknowledges it. */
+    readonly durableExhaustion?: boolean;
 }
 export interface TelegramUpdateDueQuery {
     readonly now: number;
@@ -43,6 +48,23 @@ export interface StoredTelegramUpdate {
     readonly updateId: number;
     readonly body: string;
 }
+/** The immutable identity of one claim, including a token that never repeats after pruning. */
+export interface TelegramUpdateAttemptIdentity {
+    readonly updateId: number;
+    readonly attempt: number;
+    readonly claimId: string;
+}
+/** A final failure waiting for the consumer's durable obligation. */
+export interface StoredTelegramUpdateExhaustion extends StoredTelegramUpdate, TelegramUpdateAttemptIdentity {
+    readonly exhaustedAt: number;
+    readonly error: string;
+}
+/** One ordered page of final failures still waiting for acknowledgement. */
+export interface TelegramUpdateExhaustionQuery {
+    readonly limit: number;
+    /** Continue strictly after this `update_id`; omit to begin at the first row. */
+    readonly afterUpdateId?: number;
+}
 export interface TelegramUpdateStore {
     /** Record a received update as `pending`; `false` when this `update_id` is already recorded. */
     add(update: StoredTelegramUpdate & {
@@ -51,7 +73,9 @@ export interface TelegramUpdateStore {
     /** Take a claimable update for one attempt; its number, or `undefined` when not taken. */
     claim(updateId: number, options: TelegramUpdateClaimOptions): Promise<number | undefined>;
     /** Extend the lease of this attempt; `false` when the attempt no longer holds the update. */
-    renew(updateId: number, attempt: number, leaseUntil: number): Promise<boolean>;
+    renew(updateId: number, attempt: number, leaseUntil: number, 
+    /** When supplied, a lease that already expired cannot be resurrected. */
+    now?: number): Promise<boolean>;
     /** End this attempt; ignored when the attempt no longer holds the update. */
     settle(updateId: number, attempt: number, settlement: TelegramUpdateSettlement): Promise<void>;
     /** Claimable updates in `update_id` order. */
@@ -59,9 +83,34 @@ export interface TelegramUpdateStore {
     /** Forget `completed` and `abandoned` updates settled before `before`; how many were forgotten. */
     prune(before: number): Promise<number>;
 }
+/** A store able to verify an immutable attempt fence inside the caller's transaction. */
+export interface TelegramUpdateFencedStore extends TelegramUpdateStore {
+    /** Atomically take one claim and return its persisted, globally unique identity. */
+    claimOwned(updateId: number, options: TelegramUpdateClaimOptions): Promise<TelegramUpdateAttemptIdentity | undefined>;
+    /** Extend only this exact claim's live lease. */
+    renewOwned(identity: TelegramUpdateAttemptIdentity, leaseUntil: number, now?: number): Promise<boolean>;
+    /** `true` only while this exact attempt still owns an unexpired lease. */
+    owns(identity: TelegramUpdateAttemptIdentity, at: number): Promise<boolean>;
+    /** Atomically settle only while this exact attempt still owns an unexpired lease. */
+    settleOwned(identity: TelegramUpdateAttemptIdentity, settlement: TelegramUpdateSettlement): Promise<boolean>;
+}
+/**
+ * The same update store with recoverable final-failure delivery.
+ *
+ * `exhaust` leaves the abandonment pending, `dueExhaustions` reads it after a
+ * restart, and `acknowledgeExhaustion` makes it eligible for ordinary pruning.
+ */
+export interface TelegramUpdateDurableStore extends TelegramUpdateFencedStore {
+    exhaust(identity: TelegramUpdateAttemptIdentity, exhaustion: {
+        readonly at: number;
+        readonly error: string;
+    }): Promise<boolean>;
+    dueExhaustions(query: TelegramUpdateExhaustionQuery): Promise<readonly StoredTelegramUpdateExhaustion[]>;
+    acknowledgeExhaustion(identity: TelegramUpdateAttemptIdentity, at: number): Promise<boolean>;
+}
 /**
  * A store in this process's memory — for tests, and for a bot that accepts
  * losing what was received but not handled when it restarts.
  */
-export declare function memoryTelegramUpdateStore(): TelegramUpdateStore;
+export declare function memoryTelegramUpdateStore(): TelegramUpdateDurableStore;
 //# sourceMappingURL=update-store.d.ts.map

package/dist/telegram/update-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-store.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,0FAA0F;IAC1F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1F,6FAA6F;IAC7F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,6EAA6E;IAC7E,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,8CAA8C;IAC9C,GAAG,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;IAC7E,mGAAmG;IACnG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAsBD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,CAsE/D"}
+{"version":3,"file":"update-store.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+FAA+F;AAC/F,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qEAAqE;AACrE,MAAM,WAAW,8BACf,SAAQ,oBAAoB,EAC1B,6BAA6B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,0FAA0F;IAC1F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1F,6FAA6F;IAC7F,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM;IAClB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,6EAA6E;IAC7E,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,8CAA8C;IAC9C,GAAG,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;IAC7E,mGAAmG;IACnG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,yFAAyF;AACzF,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,oFAAoF;IACpF,UAAU,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC,CAAC;IACtD,iDAAiD;IACjD,UAAU,CACR,QAAQ,EAAE,6BAA6B,EACvC,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,0EAA0E;IAC1E,IAAI,CAAC,QAAQ,EAAE,6BAA6B,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,qFAAqF;IACrF,WAAW,CACT,QAAQ,EAAE,6BAA6B,EACvC,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,OAAO,CACL,QAAQ,EAAE,6BAA6B,EACvC,UAAU,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,cAAc,CACZ,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,SAAS,8BAA8B,EAAE,CAAC,CAAC;IACtD,qBAAqB,CAAC,QAAQ,EAAE,6BAA6B,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9F;AAuBD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,0BAA0B,CAmKtE"}

package/dist/tools/cli/args-fields.d.ts

@@ -21,6 +21,12 @@ export declare function appendCliOptionValue(raw: Map<string, string[]>, name: s
  * scalar schema yields an empty map and every value is left as a string.
  */
 export declare function describeSchemaFields(schema: z.ZodType | undefined): Map<string, FieldInfo>;
+/**
+ * Resolve the declared leaf of a dotted option. An intersection's concrete
+ * constraint can refine a free member; a union with a free member stays raw,
+ * because coercion must not choose one accepted branch for the caller.
+ */
+export declare function describeSchemaPath(schema: z.ZodType | undefined, path: readonly string[]): FieldInfo | undefined;
 /** Strict boolean for a RESERVED option — an unrecognised value is a usage error, never a silent `true`. */
 /**
  * The token after a bare boolean flag, when it is the flag's value: exactly
@@ -33,7 +39,7 @@ export declare function separateBoolValue(next: string | undefined): boolean | u
 /** True for a value the reserved-boolean grammar already claims. */
 export declare function isReservedBoolWord(value: string): boolean;
 export declare function parseReservedBool(name: string, value: string): boolean;
-/** Best-effort coercion for a dotted-path leaf, where the schema type is unknown. */
+/** Preserve the legacy best-effort grammar for a wholly unknown passthrough option. */
 export declare function looseCoerce(value: string): unknown;
 /** Coerce the collected raw string value(s) for one field to its typed form. */
 export declare function coerceField(info: FieldInfo | undefined, values: string[], label: string): unknown;

package/dist/tools/cli/args-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,IAAI,CAaN;AAwGD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAI/E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}
+{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,IAAI,CAaN;AA6GD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAiFD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,GAAG,SAAS,CAGvB;AAKD,4GAA4G;AAC5G;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAI/E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}

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

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAsRD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAkDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAiSD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAkDvB"}

package/dist/tools/connections/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAKX;AAcD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAElF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,EAC/C,SAAS,EAAE,0BAA0B,GACpC,qBAAqB,EAAE,CAczB"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAI7D,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAQX;AAcD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAElF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,EAC/C,SAAS,EAAE,0BAA0B,GACpC,qBAAqB,EAAE,CAczB"}

package/dist/tools/schema/coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2KxB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoLxB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB"}

package/dist/tools/schema/json-schema-origin.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/**
+ * Record which structural pipes came from the one foreign JSON Schema boundary.
+ * The walk runs once after `z.fromJSONSchema`; coercion later reads only this
+ * provenance and never guesses from a transform's public shape or metadata.
+ */
+export declare function markJsonSchemaObjectGuards(schema: z.core.$ZodType): void;
+/**
+ * Schemas that can guide coercion at a proven foreign object boundary.
+ * Intersections need both branches: one carries the key guard, while another
+ * can carry nested object fields that also need recursive coercion.
+ */
+export declare function jsonSchemaObjectCoercionMembers(schema: z.core.$ZodType): readonly z.core.$ZodType[] | undefined;
+//# sourceMappingURL=json-schema-origin.d.ts.map

package/dist/tools/schema/json-schema-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-origin.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/json-schema-origin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAiExE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GACtB,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,SAAS,CAsBxC"}

package/llms/cli.2.txt

@@ -269,7 +269,7 @@ SDK nor the `ai` peer.
 | `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
-| `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, without the `stitchkit/tools` barrel |
+| `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |
 | `CliArgumentError` | class | the refusal `parseCliArgs` and the view flags raise; a CLI reports it and exits `2` |
 | `renderCliView` | function | compute an aggregate over a result (`--count-by`, `--sum`, `--top`, `--table`) — [guide](../guide/cli.md#aggregate-views) |
 | `createCliProfileStore` | function | named `0600` credential profiles resolved by name, with the never-substitute rule built in — [guide](../guide/cli.md#named-profiles) |

package/llms/cli.txt

@@ -244,12 +244,24 @@ string, the schema says what it should be:
 | `z.enum([...])`      | `--size large`                                 |
 | `z.array(z.string())`| `--tag a --tag b` → `["a","b"]`                |
 | `z.object({...})`    | `--opts '{"k":"v"}'` (JSON) or `--opts.k v`    |
+| `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
 Primitive literals use the same coercion through optional, nullable and default wrappers and as
 array elements. A literal set whose members have different primitive types stays lexical because
 argv has no type tag: for `z.literal([7, '007'])`, `--value 007` remains the string `"007"` rather
 than being guessed as the number `7`. The unchanged Zod schema makes the final admission decision.
+Object and record JSON keeps the same behavior when a CLI discovers a tool through MCP. Restored
+`propertyNames`, `minProperties` and `maxProperties` constraints still run before dispatch; CLI
+coercion does not execute application transforms.
+
+A dotted leaf follows the leaf schema, including through optional/nullable wrappers and restored
+MCP object guards. A declared number or boolean is coerced; a string stays byte-for-byte lexical.
+For a free `z.record(z.string(), z.unknown())`, argv provides no JSON type tag, so the dotted
+value also stays a string: `007`, `+007`, `1e3`, `true` and `false` keep those spellings.
+Use the whole-object JSON form when a free record value must be a JSON number or boolean. This
+avoids silently changing identifiers while keeping `z.record(..., z.number())` and
+`z.record(..., z.boolean())` explicitly typed.
 
 After a bare boolean flag, the next token is its value when it is exactly
 `true` or `false` — `--active false` turns it off, as it reads. Any other word

package/llms/stitchkit.txt

@@ -83,12 +83,12 @@ 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 53 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 54 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/agent-runtime` | server | evolving<br>_redefined in 23 of the 53 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 54 minors since 0.56.2, most recently 0.105.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 |
@@ -100,7 +100,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 13 of the 53 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 54 minors since 0.56.2, most recently 0.105.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 |
@@ -621,6 +621,13 @@ preserve facts the generic client cannot invent — for example a Unix transport
 an effect from `UNKNOWN_ERROR` alone; inspect the owned adapter's cause and retry
 only when it proves that dispatch did not happen.
 
+The same evidence survives when caller abort or the request deadline wins the
+race: the public code remains `REQUEST_ABORTED` or `REQUEST_TIMEOUT`, while
+the exact rejection produced by the transport remains in `ApiError.cause`.
+That cause is internal diagnostic data — it is not included by JSON/string
+rendering — so delivery state and trace metadata remain available without
+putting transport payloads or credentials in a client-facing error.
+
 For an endpoint without contract arguments, pass only the options object:
 
 ```ts