node-autotask 0.18.0 → 0.20.0

package/dist/{chunk-VYUZZIEE.js → chunk-GA6UCX3Z.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-VV2UUW2J.js";
+} from "./chunk-2T77J2ZM.js";
 
 // src/auth.ts
 var AUTH_HEADERS = {
@@ -1536,6 +1536,7 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_MAINTENANCE_MAX_WAIT_MS = 36e5;
 var DEFAULT_MAINTENANCE_POLL_MS = 3e4;
+var MAINTENANCE_WINDOW_MAX_MS = 4 * 36e5;
 var DEFAULT_MAX_CONCURRENT = 10;
 var DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 var DEFAULT_MAX_SCAN_RECORDS = 500;
@@ -2073,6 +2074,88 @@ function refusedFilterShape(filter) {
 // src/http.ts
 import { AsyncLocalStorage } from "async_hooks";
 
+// src/latest-count-cache.ts
+var LATEST_COUNT_CACHE_TTL_MS = 3e4;
+var LATEST_COUNT_CACHE_MAX_ENTRIES = 4096;
+var LatestCountCache = class {
+  /** The TTL in ms. */
+  ttlMs;
+  /** The entry bound (applies to STORED entries). */
+  maxEntries;
+  store = /* @__PURE__ */ new Map();
+  /** The invalidation epoch (the `ReadCache` pattern — issue #139): bumped
+   * by `clear()`; capture it before a wire read and pass it to `set` so a
+   * probe in flight across a write cannot re-store its stale answer. */
+  epochCounter = 0;
+  constructor(ttlMs, maxEntries = LATEST_COUNT_CACHE_MAX_ENTRIES) {
+    if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+      throw new AutotaskConfigError(`latestCountCache.ttlMs must be a positive integer (got ${String(ttlMs)})`);
+    }
+    if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+      throw new AutotaskConfigError(`latestCountCache.maxEntries must be a positive integer (got ${String(maxEntries)})`);
+    }
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+  /** The composite key: (resource plan key, canonical filter serialisation)
+   * — the `\u0000` separator is unencodable in a filter value, so no two
+   * (resource, conditions) pairs collide. */
+  static key(resourceKey, conditions) {
+    return `${resourceKey}\0${JSON.stringify(conditions ?? [])}`;
+  }
+  /** The live entry's count, or `undefined` (absent OR expired — an expired
+   * entry is purged lazily on this read). */
+  get(key) {
+    const entry = this.store.get(key);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /** The invalidation epoch: bumped by `clear()`; capture it before a wire
+   * read and pass it to `set` so a probe in flight across a write cannot
+   * re-store its stale answer (issue #139, the `ReadCache` pattern). */
+  get epoch() {
+    return this.epochCounter;
+  }
+  /** Store a SUCCESSFUL plain-number count under `key`, live for `ttlMs`.
+   * `epoch` is the invalidation epoch the caller captured BEFORE its wire
+   * read: a probe that straddled a `clear()` (a write) is dropped, never
+   * re-stored with its pre-write body (issue #139). Past the cap: purge
+   * expired entries first, then evict the oldest-inserted (Map iteration
+   * order = insertion order). */
+  set(key, value, epoch = this.epochCounter) {
+    if (epoch !== this.epochCounter) return;
+    if (!Number.isFinite(value)) return;
+    const entry = { value, expiresAt: Date.now() + this.ttlMs };
+    if (!this.store.has(key) && this.store.size >= this.maxEntries) {
+      for (const [k, e] of this.store) {
+        if (e.expiresAt <= Date.now()) this.store.delete(k);
+      }
+      if (this.store.size >= this.maxEntries) {
+        const oldest = this.store.keys().next();
+        if (!oldest.done) this.store.delete(oldest.value);
+      }
+    }
+    this.store.set(key, entry);
+  }
+  /** Drop one entry (absent = no-op). Issue #157: the stale-LOW recovery
+   *  deletes the cached total before its one fresh wire re-probe, so the
+   *  re-probe cannot be served by the entry it is meant to replace. */
+  delete(key) {
+    this.store.delete(key);
+  }
+  /** Clear every entry (a real write through the owning client — the
+   * write-then-read re-fetch rule) and bump the invalidation epoch: a
+   * `set` captured before this `clear` is discarded (issue #139). */
+  clear() {
+    this.epochCounter += 1;
+    this.store.clear();
+  }
+};
+
 // src/relationships.ts
 var RELATIONSHIP_ZONE = {
   "zone": "ww29",
@@ -8305,7 +8388,7 @@ var RELATIONSHIP_MAP = {
     ],
     "naturalKeys": {
       "hasSearch": true,
-      "searchCovers": "title only (contains); ticketNumber lookups use resolve / findByTicketNumber",
+      "searchCovers": "title only (contains \u2014 the vendor's contains match is looser than a literal substring (case/token matching): a search can return MORE hits than a local title-substring check (measured 2026-10-19: 25 vs 24); a per-field contains filter in tickets.query is the precise tool); ticketNumber lookups use resolve / findByTicketNumber",
       "findBy": [
         "findByTicketNumber"
       ]
@@ -10252,8 +10335,8 @@ var EMPTY_REASON_STAMPS = {
 var POINTER_NOTES = {
   "ticket_history.query": `W1 (ww29 (australia-nz) live 2026-10-04; vendor contract change live-verified 2026-10-06): the vendor requires ticket_history.query to be supplied with exactly ONE ticketID-equals filter \u2014 an unfiltered call 500s by contract (10-06 text: "When querying the TicketHistory entity you are required to supply one and only one ticketID equals filter"). WITH the filter the query WORKS (live 2026-10-06: rows returned, hasMore true \u2014 a single {op:'eq', field:'ticketID', value:<id>} condition; the filter vocabulary is eq/noteq/gt/gte/lt/lte/beginsWith/endsWith/contains/exist/notExist/in/notIn/and/or). tickets.timeline / tickets.fullContext remain the convenient composites; raw history rows come from the filtered query.`,
   "time_entries.create": `W-A3 (ww29 (australia-nz) live 2026-10-04; drift re-verified 2026-10-06): the vendor now refuses ALL time-entry writes for this API-only user with "API-only user cannot be selected for this field" (10-04 text: "The specified AssignedResourceID and AssignedRoleID combination is not currently defined"). UNSATISFIABLE for an API-only integration user: the resources table is blind (0 rows) and the only selectable resource is the user's own API-only record, which the vendor refuses. createForResource \u2014 stage-11 PROVEN (8 live creates, 10-04) \u2014 is walled by the SAME drift (confirm-100 receipt 2026-10-06). Tenant evidence that valid pairs exist: postedWithin rows (resourceID 31131373 / 29869529 with roleID 29682834) \u2014 human resources the API user cannot select.`,
-  "time_entries.getPosted": `W-D3 (ww29 (australia-nz) live 2026-10-04, re-verified live 2026-10-15): this zone's TimeEntry entity exposes NO posted-state filter field \u2014 the vendor rejects postingStatus, postedDate and status with "Unable to find X in the TimeEntry Entity" (live field-existence oracle 2026-10-04: only dateWorked / resourceID / ticketID / taskID resolve as filter fields). Re-probed 2026-10-15 (ww29 re-probe campaign): time_entries.getPosted live 500, vendor body verbatim 'Unable to find postedDate in the TimeEntry Entity.' \u2014 a vendor endpoint defect on AU03, not a transient fault: posted cannot be filtered server-side on this zone \u2014 use time_entries.postedWithin (the dateWorked window, live-verified working) or read time_entries.query and derive posted-state from the fields your zone's entity exposes`,
-  "time_entries.getUnposted": `W-D3 (ww29 (australia-nz) live 2026-10-04, re-verified live 2026-10-15): this zone's TimeEntry entity exposes NO posted-state filter field \u2014 the vendor rejects postingStatus, postedDate and status with "Unable to find X in the TimeEntry Entity" (live field-existence oracle 2026-10-04: only dateWorked / resourceID / ticketID / taskID resolve as filter fields). Re-probed 2026-10-15 (ww29 re-probe campaign): time_entries.getUnposted live 500, vendor body verbatim 'Unable to find postedDate in the TimeEntry Entity.' \u2014 a vendor endpoint defect on AU03, not a transient fault: unposted cannot be filtered server-side on this zone \u2014 use time_entries.postedWithin (the dateWorked window, live-verified working) or read time_entries.query and derive posted-state from the fields your zone's entity exposes`,
+  "time_entries.getPosted": "W-D3 (ww29 (australia-nz) live 2026-10-04, re-verified live 2026-10-15): this zone's TimeEntry entity exposes NO posted-state filter field \u2014 the vendor rejects postingStatus, postedDate and status with \"Unable to find X in the TimeEntry Entity\" (live field-existence oracle 2026-10-04: only dateWorked / resourceID / ticketID / taskID resolve as filter fields). Re-probed 2026-10-15 (ww29 re-probe campaign): time_entries.getPosted live 500, vendor body verbatim 'Unable to find postedDate in the TimeEntry Entity.' \u2014 a vendor endpoint defect on AU03, not a transient fault: posted cannot be filtered server-side on this zone \u2014 use time_entries.postedWithin (the dateWorked window, live-verified working \u2014 omit the `posted` narrowing on this zone: it sends postedDate, which the zone 500s) or read time_entries.query and derive posted-state from the fields your zone's entity exposes",
+  "time_entries.getUnposted": "W-D3 (ww29 (australia-nz) live 2026-10-04, re-verified live 2026-10-15): this zone's TimeEntry entity exposes NO posted-state filter field \u2014 the vendor rejects postingStatus, postedDate and status with \"Unable to find X in the TimeEntry Entity\" (live field-existence oracle 2026-10-04: only dateWorked / resourceID / ticketID / taskID resolve as filter fields). Re-probed 2026-10-15 (ww29 re-probe campaign): time_entries.getUnposted live 500, vendor body verbatim 'Unable to find postedDate in the TimeEntry Entity.' \u2014 a vendor endpoint defect on AU03, not a transient fault: unposted cannot be filtered server-side on this zone \u2014 use time_entries.postedWithin (the dateWorked window, live-verified working \u2014 omit the `posted` narrowing on this zone: it sends postedDate, which the zone 500s) or read time_entries.query and derive posted-state from the fields your zone's entity exposes",
   "authenticate.get": "W2: authenticate.get is DESIGNATOR-ONLY \u2014 it returns the designator identity, not a tenant data surface; a miss/empty here is not a data-empty signal (no emptyReason is attached by design \u2014 a false reason would be worse than none)"
 };
 var BLIND_SURFACE_INVENTORY = {
@@ -14779,9 +14862,21 @@ function backoffDelay(attempt) {
   const exp = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
   return Math.floor(exp / 2 + Math.random() * (exp / 2));
 }
-function isMaintenancePage(err) {
-  const snippet = typeof err.details?.bodySnippet === "string" ? err.details.bodySnippet : "";
-  return /maintenance|temporarily unavailable|service unavailable|outage|downtime|down for/i.test(snippet);
+var MAINTENANCE_PROBE_BYTES = 256;
+function maintenanceProbe(text) {
+  return Buffer.from(text, "utf8").subarray(0, MAINTENANCE_PROBE_BYTES).toString("utf8");
+}
+function looksLikeMaintenanceText(text) {
+  return /maintenance|temporarily unavailable|service unavailable|outage|downtime|down for/i.test(
+    maintenanceProbe(text)
+  );
+}
+function isHtmlLike(contentType, body) {
+  if (contentType !== null && /text\/html|application\/xhtml/i.test(contentType)) return true;
+  return body.trimStart().startsWith("<");
+}
+function maintenanceExhaustedAction(maxWaitMs, waits) {
+  return `The zone stayed in a maintenance window for ${Math.round(maxWaitMs / 6e4)} min \u2014 the SDK waited and retried ${waits} time(s) and gave up. Re-run after the window (the observed median is about 2 h; the ceiling is 4 h \u2014 MAINTENANCE_WINDOW_MAX_MS), or raise maintenanceMaxWaitMs.`;
 }
 function parseRetryAfter(value) {
   if (value === null || value.length === 0) return void 0;
@@ -14875,6 +14970,11 @@ var HttpClient = class {
   fieldCache;
   /** Resource-name cache for `operations.expandResourceNames` (issue #80: the default instance when `resourceNameCache` is absent; undefined only when the user set `false` explicitly, issue #65). */
   resourceNameCache;
+  /** The `latest` walk's count-probe cache (issue #127: the short-TTL
+   * per-client count cache — ALWAYS on, process-internal: no config
+   * surface, no served keys; the plain `count` op and `operations.aggregate`
+   * bypass it by construction and promise fresh totals). */
+  latestCountCache;
   /** Resolved update fallback gate (issue #34; OFF by default). */
   update;
   auth;
@@ -14940,6 +15040,7 @@ var HttpClient = class {
     this.readCache = config.readCache;
     this.fieldCache = config.fieldCache;
     this.resourceNameCache = config.resourceNameCache;
+    this.latestCountCache = new LatestCountCache(LATEST_COUNT_CACHE_TTL_MS);
     this.update = config.update;
     this.zone = config.zone;
     this.reResolveZoneOn401 = config.reResolveZoneOn401;
@@ -15217,6 +15318,7 @@ var HttpClient = class {
     const maintenancePollMs = opts.maintenancePollMs ?? this.maintenancePollMs;
     let firstMaintenanceAt;
     let maintenanceWaits = 0;
+    let maintenanceBudgetSpent = false;
     const started = Date.now();
     let deadlineAt = started + timeoutMs;
     const callerSignal = opts.signal ?? ambientSignal.getStore();
@@ -15437,12 +15539,13 @@ var HttpClient = class {
               httpStatus: status,
               suggestedAction: "The zone returned a non-JSON 2xx body; verify baseUrl points at the REST API."
             });
-            if (err2.code === "UNEXPECTED_CONTENT_TYPE" && maintenanceMaxWaitMs > 0 && isMaintenancePage(err2)) {
+            if (err2.code === "UNEXPECTED_CONTENT_TYPE" && maintenanceMaxWaitMs > 0 && looksLikeMaintenanceText(text)) {
               const now = Date.now();
               firstMaintenanceAt ??= now;
               const remaining = maintenanceMaxWaitMs - (now - firstMaintenanceAt);
               if (remaining > 0) {
                 const wait = Math.min(maintenancePollMs, remaining);
+                if (wait >= remaining) maintenanceBudgetSpent = true;
                 maintenanceWaits += 1;
                 this.logger.warn?.(
                   `[autotask] maintenance window on ${method} ${opts.path}; waiting ${Math.round(wait / 1e3)}s (retry ${maintenanceWaits}, up to ${Math.round(maintenanceMaxWaitMs / 6e4)} min)`,
@@ -15453,6 +15556,7 @@ var HttpClient = class {
                 await pause(wait);
                 continue;
               }
+              maintenanceBudgetSpent = true;
             }
             if (err2.code === "UNEXPECTED_CONTENT_TYPE" && retriable5xx && attempt < maxRetries) {
               const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
@@ -15467,17 +15571,27 @@ var HttpClient = class {
                 continue;
               }
             }
-            if (maintenanceWaits > 0 && err2.code === "UNEXPECTED_CONTENT_TYPE") {
+            const pageSnippet = typeof err2.details?.bodySnippet === "string" ? err2.details.bodySnippet : "";
+            if (maintenanceWaits > 0) {
               err2.details = {
                 ...err2.details ?? {},
                 maintenance: {
                   waits: maintenanceWaits,
                   waitedMs: Date.now() - (firstMaintenanceAt ?? Date.now()),
                   maxWaitMs: maintenanceMaxWaitMs,
-                  exhausted: true
+                  exhausted: maintenanceBudgetSpent
                 }
               };
-              err2.suggestedAction = `The zone stayed in a maintenance window for ${Math.round(maintenanceMaxWaitMs / 6e4)} min \u2014 the SDK waited and retried ${maintenanceWaits} time(s) and gave up. Re-run after the window (typically under 30 min), or raise maintenanceMaxWaitMs.`;
+              if (maintenanceBudgetSpent) {
+                err2.suggestedAction = maintenanceExhaustedAction(maintenanceMaxWaitMs, maintenanceWaits);
+              }
+            }
+            if (err2.code === "UNEXPECTED_CONTENT_TYPE" && !looksLikeMaintenanceText(text) && isHtmlLike(res.headers.get("Content-Type"), text)) {
+              err2.details = { ...err2.details ?? {}, maintenancePatternMiss: true };
+              this.logger.debug?.(
+                `[autotask] non-JSON body did not match the maintenance vocabulary on ${method} ${opts.path}: ${pageSnippet}`,
+                correlationId
+              );
             }
             attachEmptyReasonDetails(err2);
             throw err2;
@@ -15489,13 +15603,38 @@ var HttpClient = class {
           break;
         }
         let body;
+        let nonJsonBody;
         if (text.length > 0) {
           try {
             body = JSON.parse(text);
           } catch {
             body = text;
+            nonJsonBody = text;
           }
         }
+        const nonJsonSnippet = nonJsonBody === void 0 ? void 0 : bodySnippet(nonJsonBody, this.redactPersonalData);
+        const nonJsonIsMaintenance = nonJsonBody !== void 0 && looksLikeMaintenanceText(nonJsonBody);
+        const nonJsonIsHtmlCandidate = nonJsonBody !== void 0 && isHtmlLike(res.headers.get("Content-Type"), nonJsonBody);
+        const nonJsonMaintenanceMayWait = nonJsonIsMaintenance && retriable5xx;
+        if (nonJsonBody !== void 0 && maintenanceMaxWaitMs > 0 && nonJsonMaintenanceMayWait) {
+          const now = Date.now();
+          firstMaintenanceAt ??= now;
+          const remaining = maintenanceMaxWaitMs - (now - firstMaintenanceAt);
+          if (remaining > 0) {
+            const wait = Math.min(maintenancePollMs, remaining);
+            if (wait >= remaining) maintenanceBudgetSpent = true;
+            maintenanceWaits += 1;
+            this.logger.warn?.(
+              `[autotask] maintenance window on ${method} ${opts.path} (HTTP ${status}); waiting ${Math.round(wait / 1e3)}s (retry ${maintenanceWaits}, up to ${Math.round(maintenanceMaxWaitMs / 6e4)} min)`,
+              correlationId
+            );
+            deadlineAt = Date.now() + wait + timeoutMs;
+            armDeadline(deadlineAt - Date.now());
+            await pause(wait);
+            continue;
+          }
+          maintenanceBudgetSpent = true;
+        }
         const deterministic500 = status >= 500 && isDeterministicVendor500(parseVendorErrors(body));
         const retryableStatus = status === 429 || status >= 500;
         if (retryableStatus && !deterministic500 && attempt < maxRetries && (status === 429 ? retriable : retriable5xx)) {
@@ -15537,6 +15676,32 @@ var HttpClient = class {
           credentialShapeExpectation(headers, this.auth)
         );
         err.correlationId = correlationId;
+        if (maintenanceWaits > 0) {
+          err.details = {
+            ...err.details ?? {},
+            maintenance: {
+              waits: maintenanceWaits,
+              waitedMs: Date.now() - (firstMaintenanceAt ?? Date.now()),
+              maxWaitMs: maintenanceMaxWaitMs,
+              exhausted: maintenanceBudgetSpent
+            }
+          };
+          if (maintenanceBudgetSpent) {
+            err.suggestedAction = maintenanceExhaustedAction(maintenanceMaxWaitMs, maintenanceWaits);
+          }
+        }
+        if (nonJsonBody !== void 0) {
+          if (nonJsonIsMaintenance && !retriable5xx) {
+            err.details = { ...err.details ?? {}, maintenanceDetected: true };
+            err.suggestedAction = `A maintenance-shaped page answered ${method} ${opts.path} (HTTP ${status}); it was NOT waited out or re-sent \u2014 a non-2xx edge page can arrive after the request was forwarded, so verify the record before re-issuing (only a GET or an explicitly idempotent-flagged call waits this window out).`;
+          } else if (!nonJsonIsMaintenance && nonJsonIsHtmlCandidate) {
+            err.details = { ...err.details ?? {}, maintenancePatternMiss: true };
+            this.logger.debug?.(
+              `[autotask] non-JSON body did not match the maintenance vocabulary on ${method} ${opts.path}: ${nonJsonSnippet}`,
+              correlationId
+            );
+          }
+        }
         if (status === 401 && zoneRetry !== void 0) {
           err.details = {
             ...err.details ?? {},
@@ -15609,6 +15774,7 @@ var HttpClient = class {
       clearTimeout(deadlineTimer);
       if (!(method === "GET" || opts.idempotent === true)) {
         this.readCache?.clear();
+        this.latestCountCache.clear();
         const nameOp = typeof opts.operation === "string" ? opts.operation : void 0;
         const nameDot = nameOp !== void 0 ? nameOp.indexOf(".") : -1;
         if (this.resourceNameCache !== void 0 && nameOp !== void 0 && nameDot > 0 && nameOp.slice(0, nameDot) === "resources") {
@@ -17268,17 +17434,56 @@ var BaseResource = class {
     const bigB = typeof b === "number" ? BigInt(String(b)) : BigInt(b);
     return bigA < bigB ? -1 : bigA > bigB ? 1 : 0;
   }
+  /** Issue #127: the `latest` walk's count probes through the per-client
+   *  short-TTL count cache (`LatestCountCache` — fixed 30 s TTL, the
+   *  memory guard; cleared on every real write through this client, the
+   *  write-then-read re-fetch rule). Only a SUCCESSFUL plain-number vendor
+   *  count answer is stored: the blind-surface / pinned-empty sentinels are
+   *  RECORDS and pass through un-stored (the plan-pinned stamps stay fresh
+   *  and re-derive on every call), and an error rejects before any store.
+   *  The key is (resource plan key, canonical filter serialisation — the
+   *  normalised conditions' JSON): the initial `count(F)` probe and every
+   *  `id gt T` threshold probe are separate entries, and a re-asked
+   *  "top N" within the TTL makes ZERO extra count calls (its probes all
+   *  hit — the bracket/search sequence is deterministic given the counts).
+   *  Issue #157: two corrections to the snapshot trade. (1) A total of 0 is
+   *  NEVER stored — a 0 is rare and cheap to re-probe, and a cached 0 fed
+   *  the false-empty branch (a repeat after an out-of-band insert returned
+   *  no rows without walking). (2) `fresh: true` DELETES the entry before
+   *  the wire read and re-stores the fresh answer — the ONE re-probe the
+   *  stale-LOW recovery in `latestWalk` is allowed. Counts are snapshots,
+   *  not contracts: the truncation guard covers the growth-of-total
+   *  direction; a stale-LOW total within the TTL is resolved by that one
+   *  fresh re-probe (never by the guard alone). The plain `count` op and
+   *  `operations.aggregate` call `countGlobal` directly and promise fresh
+   *  totals — this wrapper is used ONLY on the latest-walk probe path.
+   */
+  async latestProbeCount(filter, opts = {}) {
+    const cache = this.http.latestCountCache;
+    const key = LatestCountCache.key(this.config.key, normalizedConditions(filter));
+    if (opts.fresh === true) {
+      cache.delete(key);
+    } else {
+      const hit = cache.get(key);
+      if (hit !== void 0) return { value: hit, cached: true };
+    }
+    const epoch = cache.epoch;
+    const res = await this.countGlobal({ filter });
+    const value = res;
+    if (typeof value === "number" && value !== 0) cache.set(key, value, epoch);
+    return { value, cached: false };
+  }
   /** Issue #59: one `latest` threshold count probe — a ROWLESS
    *  `count(F ∧ id gt T)` call (the vendor caps — ≤500 OR-conditions,
    *  8000 chars serialised — leave a single `gt` condition room on any
-   *  filter). The `BlindCountResult` sentinel (a record, not a number —
+   *  filter). Issue #127: it rides the per-client short-TTL count cache — the same (resource, conditions) probe within the 30 s window is reused (zero vendor calls); a sentinel answer is never cached. The `BlindCountResult` sentinel (a record, not a number —
    *  the declared `number` return is the documented under-type) unwraps to
    *  its `count` value (always 0): at or above the max matching id the
    *  count is 0, which is exactly the bracket-termination signal. */
   async countAboveId(baseConds, t) {
     const value = t <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(t) : t.toString();
-    const res = await this.countGlobal({ filter: [...baseConds, { op: "gt", field: "id", value }] });
-    return typeof res === "object" && res !== null && "count" in res ? res.count : res;
+    const probed = await this.latestProbeCount([...baseConds, { op: "gt", field: "id", value }]);
+    return typeof probed.value === "object" && probed.value !== null && "count" in probed.value ? probed.value.count : probed.value;
   }
   /**
    * Issue #59: the `latest: N` mechanism — the N highest-`id` rows,
@@ -17296,8 +17501,11 @@ var BaseResource = class {
    *      1 + ceil(C/500) <= 6, independent of table size. A truncated walk
    *      (the vendor's rows disagree with its own count) is
    *      LATEST_WINDOW_INCOMPLETE — the top-N of a truncated set is
-   *      unprovable. Sort id-descending; return the top N (a set of
-   *      C < N returns itself).
+   *      unprovable — EXCEPT issue #157: when `C` came from the CACHE, the
+   *      total is re-probed ONCE fresh (the stale-LOW recovery: a larger
+   *      fresh total continues the walk against it; the refusal stands only
+   *      when the fresh probe confirms the cached value). Sort
+   *      id-descending; return the top N (a set of C < N returns itself).
    *    - `C > 2500` → THRESHOLD mode: find the smallest id threshold `T`
    *      with `count(F ∧ id gt T) <= N` by exponential bracketing
    *      (T = 1, 2, 4, …) + binary search — each probe ONE rowless count
@@ -17324,13 +17532,25 @@ var BaseResource = class {
    *    answer.
    * `includeFields` always carries `id` (the P1 id-append,
    * `buildQueryRequest`), which `latest` sorts on. Pure read; no mutation
-   * paths involved.
+   * paths involved. Issue #127: every count probe of this walk (the
+   * initial `count(F)` + the `id gt T` threshold probes) rides the
+   * per-client short-TTL count cache (30 s; a real write through this
+   * client clears it) — a re-asked "top N" within the window reuses the
+   * probes (zero extra vendor count calls); sentinel answers are never
+   * cached (the plan-pinned stamps stay fresh), and a 0 total is never
+   * cached either (issue #157: a 0 is cheap to re-probe and a cached 0
+   * would shadow an out-of-band insert). The stale-LOW direction is closed
+   * by the ONE fresh re-probe above; the stale-HIGH direction is safe by
+   * construction (threshold mode re-probes fresh `id gt T` counts and
+   * full-set mode ends when the cursor exhausts). The plain `count` op and
+   * `operations.aggregate` bypass the cache by construction and promise
+   * fresh totals.
    */
   async latestWalk(params, limit, latest) {
     const baseConds = normalizedConditions(params.filter) ?? [];
-    const probe = await this.countGlobal(params);
-    if (typeof probe === "object" && probe !== null) {
-      const rec = probe;
+    const probe = await this.latestProbeCount(params.filter);
+    if (typeof probe.value === "object" && probe.value !== null) {
+      const rec = probe.value;
       if (rec.blindSurface !== void 0) {
         return this.latestBlindWalk(params, limit, latest);
       }
@@ -17338,47 +17558,60 @@ var BaseResource = class {
       this.stampEmptyQueryResult(result, params);
       return result;
     }
-    const total = probe;
-    if (total === 0) {
-      const result = { items: [], fetched: 0, hasMore: false, pagesWalked: 0 };
-      this.stampEmptyQueryResult(result, params);
-      return result;
-    }
-    if (total <= BOUNDED_QUERY_MAX_LIMIT) {
-      const { items: items2, pages: pages2, guard: guard2, sliced: sliced2, cursor: cursor2 } = await this.walkBounded(params, total);
-      if (this.walkTruncated(total, { itemsLength: items2.length, guard: guard2, sliced: sliced2, cursor: cursor2 })) {
-        throw this.latestWindowIncompleteError(total);
+    let total = probe.value;
+    let cacheSourced = probe.cached;
+    let reProbed = false;
+    for (; ; ) {
+      if (total === 0) {
+        const result = { items: [], fetched: 0, hasMore: false, pagesWalked: 0 };
+        this.stampEmptyQueryResult(result, params);
+        return result;
       }
-      return this.finishLatest(items2, latest, pages2);
-    }
-    let probes = 1;
-    const spend = () => {
-      probes += 1;
-      if (probes > LATEST_MAX_COUNT_PROBES) throw this.latestThresholdUnresolvedError();
-    };
-    let lo = 0n;
-    let hi = 0n;
-    for (let t = 1n; ; t = t << 1n) {
-      spend();
-      if (await this.countAboveId(baseConds, t) <= latest) {
-        hi = t;
-        break;
+      if (total <= BOUNDED_QUERY_MAX_LIMIT) {
+        const { items: items2, pages: pages2, guard: guard2, sliced: sliced2, cursor: cursor2 } = await this.walkBounded(params, total);
+        if (this.walkTruncated(total, { itemsLength: items2.length, guard: guard2, sliced: sliced2, cursor: cursor2 })) {
+          if (cacheSourced && !reProbed) {
+            reProbed = true;
+            const fresh = await this.latestProbeCount(params.filter, { fresh: true });
+            if (typeof fresh.value === "number" && fresh.value > total) {
+              total = fresh.value;
+              cacheSourced = false;
+              continue;
+            }
+          }
+          throw this.latestWindowIncompleteError(total);
+        }
+        return this.finishLatest(items2, latest, pages2);
       }
-      lo = t;
-    }
-    while (hi - lo > 1n) {
-      const mid = lo + hi >> 1n;
-      spend();
-      if (await this.countAboveId(baseConds, mid) <= latest) hi = mid;
-      else lo = mid;
-    }
-    const windowValue = hi <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(hi) : hi.toString();
-    const window = [...baseConds, { op: "gte", field: "id", value: windowValue }];
-    const { items, pages, guard, sliced, cursor } = await this.walkBounded({ ...params, filter: window }, latest + 1);
-    if (this.walkTruncated(latest + 1, { itemsLength: items.length, guard, sliced, cursor })) {
-      throw this.latestWindowIncompleteError(latest + 1);
+      let probes = reProbed ? 2 : 1;
+      const spend = () => {
+        probes += 1;
+        if (probes > LATEST_MAX_COUNT_PROBES) throw this.latestThresholdUnresolvedError();
+      };
+      let lo = 0n;
+      let hi = 0n;
+      for (let t = 1n; ; t = t << 1n) {
+        spend();
+        if (await this.countAboveId(baseConds, t) <= latest) {
+          hi = t;
+          break;
+        }
+        lo = t;
+      }
+      while (hi - lo > 1n) {
+        const mid = lo + hi >> 1n;
+        spend();
+        if (await this.countAboveId(baseConds, mid) <= latest) hi = mid;
+        else lo = mid;
+      }
+      const windowValue = hi <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(hi) : hi.toString();
+      const window = [...baseConds, { op: "gte", field: "id", value: windowValue }];
+      const { items, pages, guard, sliced, cursor } = await this.walkBounded({ ...params, filter: window }, latest + 1);
+      if (this.walkTruncated(latest + 1, { itemsLength: items.length, guard, sliced, cursor })) {
+        throw this.latestWindowIncompleteError(latest + 1);
+      }
+      return this.finishLatest(items, latest, pages);
     }
-    return this.finishLatest(items, latest, pages);
   }
   /** The shared `latest` completion: the (provably complete or
    *  stamp-scoped) set sorted id-descending, top N taken. `hasMore: false`
@@ -18702,6 +18935,7 @@ export {
   DEFAULT_MAX_RETRIES,
   DEFAULT_MAINTENANCE_MAX_WAIT_MS,
   DEFAULT_MAINTENANCE_POLL_MS,
+  MAINTENANCE_WINDOW_MAX_MS,
   DEFAULT_MAX_CONCURRENT,
   DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_MAX_SCAN_RECORDS,

package/dist/{chunk-W2WSZOZA.js → chunk-JEJUFXHX.js}

@@ -127,13 +127,13 @@ import {
   VersionInformationResource,
   VersionResource,
   ZoneInformationResource
-} from "./chunk-HXOWEYV3.js";
+} from "./chunk-XSYJB4IW.js";
 import {
   AutotaskConfigError,
   HttpClient,
   resolveConfig,
   runWithSignal
-} from "./chunk-VYUZZIEE.js";
+} from "./chunk-GA6UCX3Z.js";
 
 // src/client.ts
 var AutotaskClient = class {