node-autotask 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-10-20
+
+**Filter pre-validation, the latest-probe count cache, and the window/search/aggregate served-text corrections (issues #125, #127, #128, #129, #130, #131).** The plan hash moves to `f6a579e0b7a8` (MINOR) — plan-pinned consumers must re-pin.
+
+**Invoke-bag filter field-name check (#125).** The bounded query op's invoke bag now name-checks the filter condition field names PRE-REQUEST — every leaf condition's `field` (grouping `and`/`or` recurses into `items`) against the same live-first authority as the #119b includeFields check (the tenant's live entity field metadata through the cache-aware channel, degrading to the vendored spec when that read faults). A refusal costs zero QUERY wire — the query POST and the count probe that anchors `latest` are never issued (a cold fieldCache performs one authority metadata GET first — zero on a warm one) — as one typed `CONFIG_ERROR` with the field-catalog pointer. Under a live-metadata FAULT the vendored spec is the authority, and the resource's plan-pinned live-only fields (the record's `metadata.liveOnlyFields` — the live entity carries them, the vendor model omits them: `time_entries.postedDate`/`postedOnTime`, the W-D3 spec gap) are exempt from the vendored refusal (issue #144 — the pre-#125 behaviour is preserved under degradation; a truly unknown name is still refused). The `count` verb's bag (closed to `filter` + the `fieldCheck` opt-out — issue #145) is name-checked the same way (issue #140 — the documented unchecked scope is the direct queryBounded/queryAll client paths AND the `operations.aggregate` filter, which is grammar-checked only — its groupBy/sum field names ARE checked; name-checking the aggregate filter is a separate follow-up, the op's own field whitelist being the different authority). The one `udf: true` condition per query is exempt (a tenant UDF name is absent from the vendored spec by definition); `fieldCheck: false` opts out of both name checks (the shape/grammar checks always run). Direct queryBounded/queryAll client paths remain unchecked by design (the #119b rule).
+
+**Latest-walk count-probe cache (#127).** The count-anchored `latest: N` mechanism is the query family's dominant latency term (20–45 s of serial rowless vendor count calls per invocation, live-measured 2026-10-19) — a re-asked "top N" within 30 s now makes ZERO extra vendor count calls. The walk's count probes (the initial `count(F)` + every `id gt T` threshold probe) are cached per client in a short-TTL in-process store (30 s TTL, 4096-entry memory guard, keyed by resource + canonical filter, cleared on any real write through the same client — a probe in flight across the write is discarded by the cache's invalidation epoch (issue #139 — the cleared cache is not re-populated with a pre-write count). Never cached: the blind-surface/pinned-empty sentinels (the plan-pinned stamps stay fresh), a total of 0, errors, and anything outside the probe path — the plain `count` op and `operations.aggregate` promise fresh totals. Process-internal: no served keys, no config surface; a write made elsewhere shows up once the 30 s TTL expires (the documented snapshot trade). The truncation guard covers the growth-of-total direction only (issue #157): a stale-LOW total within the TTL is resolved by ONE fresh re-probe of the total when a full-set walk truncates against a cached total — a larger fresh total continues the walk to it, and LATEST_WINDOW_INCOMPLETE stands only when the fresh probe confirms the cached value (bounded: at most one extra count probe per walk), never by the guard alone — and a total of 0 is never cached, so a repeated call after an out-of-band insert re-probes instead of returning a false empty.
+
+**Window ops default to the hard cap (#128).** The date-window family (time_entries/billing_items/invoices) silently defaulted to the first 25 rows; the default is now the 500-row hard cap, and the served text names the escalation path for >500 rows (the bounded query op with the same date-window filter, 2500-row walk cap). Envelope shapes unchanged.
+
+**postedWithin is a dateWorked window (#129).** The served text now states unambiguously that the window is on `dateWorked` (entries worked within [from, to]); "postedWithin" is the historical name — its 'posted' is the posted/unposted split counted over the returned rows (the `postedDate` exist/notExist narrowing + postedCount/unpostedCount), never a posted-date window. The postedDate-window variant is rejected: the vendored TimeEntryModel declares no postedDate filter and ww29-class zones 500 on postedDate filters only when the `posted` narrowing is set — `time_entries.dateWorkedWindow` is the unambiguous op.
+
+**Aggregate caps + the partial marker (#130).** The served `autotask_aggregate` text states the exact caps (2500-row scan = the bounded-query hard max; 100-group top cap, default top 25, larger top clamped never raised) and the explicit rule: a truncated aggregate (hasMore true or groupsTruncated true — totalScanned stays reported for reasoning) is a PARTIAL answer — never a tenant-wide total — with the escalation path (narrow the filter so the set fits the caps; the bounded query op with the same filter within its 2500-row walk cap; raw REST for the rest). The envelope flags were already honest (no code change — no new count keys, zero-sentinel rule); the partial-marker flags are now unit-pinned.
+
+**tickets.search scope (#131).** The served text names the searched-field scope: a vendor `contains` filter on title ONLY (no free-text search, no matched-field reporting), plus the vendor-contains caveat — looser than a literal substring (case/token matching), so 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. The issue's non-title-field hypothesis is not documented (unverified from source).
+
 ## [0.19.0] - 2026-10-19
 
 **Maintenance-page detection at any status, pattern-miss capture, and two manifest/packaging corrections (issues #114, #115, #123).** The plan hash moves to `078f288c2800` (MINOR) — plan-pinned consumers must re-pin.

package/MCP_TOOL_CATALOG.json

@@ -1,7 +1,7 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-19T07:20:54.559Z",
-  "planHash": "078f288c280029abcbc632ac9a842ba952296ef28872c28da67a08af6ed76475",
+  "generatedAt": "2026-10-20T01:49:50.366Z",
+  "planHash": "f6a579e0b7a8544f6e477a730d21a9ba031536392d8dbaeb2f73c61ca290ae91",
   "metaTools": [
     {
       "name": "autotask_catalog",
@@ -9891,7 +9891,7 @@
     {
       "operation": "time_entries.dateWorkedWindow",
       "tool": "autotask_timeEntry_date_worked_window",
-      "purpose": "The clearer-named alias for time_entries.postedWithin (issue #66): the dateWorked window read with the posted/unposted split, counted in one pass — same wire, same result (incl. truncated).",
+      "purpose": "The unambiguous-named alias for time_entries.postedWithin (issue #66): the dateWorked window read with the posted/unposted split, counted in one pass — same wire, same result (incl. truncated). The window is ON dateWorked (entries worked within [from, to]); \"postedWithin\" keeps its historical name (its \"posted\" is the posted/unposted split over the returned rows, never a posted-date window).",
       "preferredWhen": null,
       "backingOperation": "time_entries.dateWorkedWindow",
       "effect": "read",
@@ -10170,7 +10170,7 @@
     {
       "operation": "time_entries.postedWithin",
       "tool": "autotask_timeEntry_posted_within",
-      "purpose": "Get time entries worked within an inclusive dateWorked window with the posted/unposted split, counted in one pass (the window is ON the dateWorked field — the posted narrowing is a server-side postedDate exist|notExist predicate; the counts cover the returned rows only, truncated flags the capped window).",
+      "purpose": "Get time entries WORKED within an inclusive dateWorked window with the posted/unposted split, counted in one pass. The window is ON the dateWorked field — the name's \"posted\" is the posted/unposted SPLIT counted over the returned rows (the server-side postedDate exist|notExist predicate), never a posted-date window: no postedDate window op exists (the vendored TimeEntryModel declares no postedDate filter, and ww29-class zones 500 on postedDate filters ONLY WHEN the `posted` narrowing is set — omit `posted` on such zones — W-D3). The counts cover the returned rows only; truncated flags the capped window. time_entries.dateWorkedWindow is the unambiguous name.",
       "preferredWhen": null,
       "backingOperation": "time_entries.postedWithin",
       "effect": "read",
@@ -20634,7 +20634,7 @@
     {
       "operation": "tickets.search",
       "tool": "autotask_ticket_search",
-      "purpose": "Search ticket records by text (contains on the searchable fields).",
+      "purpose": "Search ticket records by text (a vendor contains filter on title only — the vendor exposes no free-text search and no matched-field reporting).",
       "preferredWhen": null,
       "backingOperation": "tickets.search",
       "effect": "read",
@@ -20725,7 +20725,7 @@
     {
       "operation": "operations.aggregate",
       "tool": "autotask_aggregate",
-      "purpose": "Fold any query surface into groups/sums/totals in one bounded call — or count it with the vendor count endpoint when no folding is needed — with blind-surface and truncation honesty; date fields bucket via the closed groupBy suffix <field>@month | @week | @year (ISO labels, UTC-anchored)",
+      "purpose": "Fold any query surface into groups/sums/totals in one bounded call — or count it with the vendor count endpoint when no folding is needed — with blind-surface and truncation honesty (caps documented: the walk scans at most 2500 rows and top keeps at most 100 groups — a truncated aggregate is a PARTIAL answer, never a tenant-wide total); date fields bucket via the closed groupBy suffix <field>@month | @week | @year (ISO labels, UTC-anchored)",
       "preferredWhen": "For existence checks and totals over any queryable table (count mode is one call vs a 50k-char page); group-by/sum folds the vendor has no endpoint for; a targeted read is cheaper when you need the rows",
       "backingOperation": "operations.aggregate",
       "effect": "read",