node-autotask 0.39.4 → 0.41.0

package/docs/API.md

@@ -2,9 +2,8 @@
 
 > Generated from: `src/` (core modules), `src/errors/`, `src/config/`,
 > `src/pagination.ts`, `src/query.ts`, `src/operations/`, and the capability
-> registry (`capabilities.json` + `capabilities.plan.json`). The normative
-> architecture is `ARCHITECTURE.md`; this reference documents the public
-> surface of v0.1.0 (the 121-entity MVP set). The per-entity table in
+> registry (`capabilities.json` + `capabilities.plan.json`). `ARCHITECTURE.md` is a historical v0.1 design record; this reference documents the public
+> surface (see `capabilities.json` for the current resource set). The per-entity table in
 > section 8 is generated by `npm run docs:render` — do not hand-edit it.
 
 ## 1. Core modules
@@ -14,7 +13,7 @@
 The top-level facade. The constructor validates fail-closed (section 6 of
 `ARCHITECTURE.md`) — invalid configuration throws `AutotaskConfigError` and
 construction issues no request. The client exposes one read-only accessor per
-resource (128, incl. the 7 integration endpoints) plus `config` and the
+resource (incl. the integration endpoints) plus `config` and the
 shared `http` transport:
 
 ```ts
@@ -94,7 +93,7 @@ allows <= 10 concurrent), one correlation id per request (surfaced on every
 error and to `onAudit`), and the opt-in client-side hourly budget tracker
 (`rateLimit.perHour`, default off — a sliding one-hour window that waits for a slot within the call deadline, else throws `RateLimitError` with `retryAfter`; the API allows 10,000 req/hour). The tracker is PER PROCESS: it counts only this client's attempts and cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the only cross-integration signal; the local count is `client.hourlyBudget()`, section 3.2.1). Under the `agent` config profile the exhaustion `suggestedAction` says stop or narrow the query — never raise the limit.
 Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; the same wait recognises the page at any status for calls safe to re-send (a GET or an explicitly idempotent-flagged call — an unflagged mutation makes ONE send with `details.maintenanceDetected`): section 2.1; otherwise a GET or idempotent-flagged call retries and a write makes one call); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
-Per-tenant 429 cooldown gate (`cooldown`, ON by default): once a 429 surfaces from the transport (retries spent, a `Retry-After` too long to wait out, or a non-retriable method), the client records a cooldown deadline for that tenant (lowercased `UserName` + lowercased host — impersonation does not change the key), and every further call for that tenant fails LOCALLY — before the semaphore, the hourly limiter and fetch, with zero upstream calls — with a `RateLimitError` (`code: 'RATE_LIMITED_COOLDOWN'`, `notSent: true`, `retryAfter` = remaining seconds; no credentials appear in the message) until the deadline passes. Duration is `Retry-After` clamped to `cooldown.maxMs` (default 15 minutes), or `cooldown.defaultMs` (default 60 s) when the header is missing or unparseable; the thread-threshold 429 (vendor code `Itgenatr005`, which clears in seconds) arms only a short window: min(`Retry-After`, 10 s), default 5 s. A 2xx from a call that got through clears the gate early; expiry is lazy (the first call after the deadline deletes the entry and proceeds); a hostile `Retry-After` (huge, zero, negative, non-numeric) is clamped to the cap or falls back to the default, so a lock-out is always bounded. `thresholdInformation.get()` bypasses the gate so a throttled tenant can still read its own headroom (a 2xx from it clears the gate; a 429 re-arms it). The default store is the in-process in-memory map shared by every client instance (capped at 1024 entries, evicting the earliest deadline first — failing open); `cooldown: { enabled: false }` disables the gate and `cooldown.store` injects a custom `CooldownStore` (the interface leaves room for a shared/Redis-backed store). Gated calls emit an audit event marked `notSent` and do not count toward `rateLimit.perHour`. Limits worth knowing: the gate is per process — other processes and integrations on the same tenant are invisible to it (`thresholdInformation` is the only cross-integration signal); it can mask early recovery if the vendor window clears before `Retry-After`; a process that loads both the ESM and the CJS build gets two default stores (the default store is deliberately not anchored on `globalThis`) — inject one shared `CooldownStore` if you need cross-build sharing.
+Per-tenant 429 cooldown gate (`cooldown`, ON by default): once a 429 surfaces from the transport (retries spent, a `Retry-After` too long to wait out, or a non-retriable method), the client records a cooldown deadline for that tenant (lowercased `UserName` + lowercased host — impersonation does not change the key), and every further call for that tenant fails LOCALLY — before the semaphore, the hourly limiter and fetch, with zero upstream calls — with a `RateLimitError` (`code: 'RATE_LIMITED_COOLDOWN'`, `notSent: true`, `retryAfter` = remaining seconds; no credentials appear in the message) until the deadline passes. Duration is `Retry-After` clamped to `cooldown.maxMs` (default 15 minutes), or `cooldown.defaultMs` (default 60 s) when the header is missing or unparseable; the thread-threshold 429 (vendor code `Itgenatr005`, which clears in seconds) arms only a short window: min(`Retry-After`, 10 s), default 5 s. A 2xx from a call that got through clears the gate early; expiry is lazy (the first call after the deadline deletes the entry and proceeds); a hostile `Retry-After` (huge, zero, negative, non-numeric) is clamped to the cap or falls back to the default, so a lock-out is always bounded. `thresholdInformation.get()` bypasses the gate so a throttled tenant can still read its own headroom (a 2xx from it clears the gate; a 429 re-arms it). The state is one in-process map shared by every client instance (expired entries are swept when a new cooldown is armed); `cooldown: { enabled: false }` disables the gate. Gated calls emit an audit event marked `notSent` and do not count toward `rateLimit.perHour`. Limits worth knowing: the gate is per process — other processes and integrations on the same tenant are invisible to it (`thresholdInformation` is the only cross-integration signal); it can mask early recovery if the vendor window clears before `Retry-After`; a process that loads both the ESM and the CJS build gets two maps (deliberately not anchored on `globalThis`).
 
 Credential-shaped fields are redacted in audit payloads by default.
 Every 2xx JSON body also passes through the response redaction transform
@@ -145,17 +144,11 @@ live-verified on `company_notes.create`): it drives the transport's no-retry dec
 and the `errorFromStatus` override that marks a matching 500 permanent
 (`retryable: false`, `details.deterministic: true`, a field-catalog
 `suggestedAction`) while keeping the `ServerError` class + `SERVER_ERROR`
-code + status 500 (issue #23 — the shared signal for the #26 breaker
-predicate). A third house class is thrown by the transport's pre-send gate
-(issue #26): `CircuitBreakerError` (`CIRCUIT_BREAKER_OPEN`, policy,
-`notSent: true` — the call was refused locally and never sent;
-`retryable: true` with `retryAfter` = the remaining open seconds (absent
-for the half-open probe-wait refusal) — a DELIBERATE divergence from #6's
-`RATE_LIMITED_COOLDOWN` refusal (`retryable: false`): the open period is
-bounded and advertised via `retryAfter`, so retrying the SAME call after
-the wait is the correct caller behaviour; `details = { state: 'open' |
-'half-open', retryAfterMs, failureCount }` rides the error and the MCP
-served payload verbatim).
+code + status 500 (issue #23). A third house class is thrown by the transport's pre-send gate
+(issue #285): `MaintenanceError` (`MAINTENANCE`, server, `notSent: true` — the zone's
+maintenance gate is open and the call was refused locally and never sent;
+`retryable: true` with `retryAfter` = seconds to the next probe slot;
+`details = { since, retryAfterMs }` — section 3.2.2).
 
 ### 1.6 `pagination.ts` — page walk
 
@@ -261,7 +254,7 @@ status → what the vendor does that triggers it.
 | `ServerError` | `SERVER_ERROR` | server | 5xx | vendor 5xx — retryable — EXCEPT a deterministic field-validation 500 (a known phrase, `isDeterministicVendor500`): same class/code/status, `retryable: false` + `details.deterministic: true` (issue #23) |
 | `UnexpectedContentTypeError` | `UNEXPECTED_CONTENT_TYPE` | server | 2xx (non-JSON body + a non-JSON-ish `Content-Type`) | the edge serves a non-JSON page (maintenance) — the vendor never processed the request; `details = { httpStatus, contentType, bodySnippet (256 B) }` — retryable (advisory). A non-JSON `2xx` maintenance page is waited out up to `maintenanceMaxWaitMs` (default 1 h) for reads AND writes; at `4xx`/`5xx` the page is waited out only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes one send and carries `details.maintenanceDetected` (issue #114); a wait that ran is reported on the surfaced error as `details.maintenance` (section 2.1) |
 | `EmptyResponseError` | `EMPTY_RESPONSE` | server | 2xx (empty body, `expectBody`) | a blank 2xx on a call that expects a result (non-DELETE by default — section 2.1); `details = { httpStatus, method }` — retryable for non-DELETE (advisory: the loop never retries 2xx) |
-| `CircuitBreakerError` | `CIRCUIT_BREAKER_OPEN` | policy | — (call not sent) | the host circuit breaker (issue #26, opt-in) is open — refused LOCALLY before the request (zero upstream calls, no hourly stamp) — `notSent: true`, `retryAfter` = remaining open seconds — **retryable: true** (the deliberate divergence from #6's not-retryable cooldown refusal: the open period is bounded and advertised; section 3.2.2) |
+| `MaintenanceError` | `MAINTENANCE` | server | — (refused, not sent) or the page's status | the zone is in its maintenance window (issue #285): either the gate refused the call LOCALLY (zero upstream calls, no hourly stamp, `notSent: true`) or the call itself received the maintenance page and did not wait it out (`httpStatus` set, `details.maintenanceDetected`); `retryAfter`, `details.since` — **retryable: true**, except an unflagged write answered at a non-2xx status (outcome unknown; section 3.2.2) |
 | `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`, labeled in `details.idRefs`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
 | `PaginationLimitError` | `PAGINATION_LIMIT` | policy | — | a page walk that would exceed the 1000-page guard (`suggestedAction` names the tighter filter) |
 | `QueryTooLongError` | `QUERY_TOO_LONG` | policy | — | caller-requested `via: 'get'` whose serialized URL would exceed the 2048-char GET cap — the SDK never silently degrades to POST |
@@ -281,12 +274,9 @@ body fails identically on retry — issue #23). `UNEXPECTED_CONTENT_TYPE` and
 `EMPTY_RESPONSE` are retryable (advisory — the transport retries a non-JSON 2xx
 per policy on idempotent methods only, and never retries a blank 2xx).
 `RATE_LIMITED_COOLDOWN` is not retryable before its deadline — it is a local
-gate and the call was never sent. `CIRCUIT_BREAKER_OPEN` is retryable with
-`notSent: true` + `retryAfter` = the remaining open seconds — the host
-circuit breaker's local refusal (issue #26): the deliberate divergence from
-`RATE_LIMITED_COOLDOWN`'s not-retryable — the open period is bounded and
-advertised, so retrying the SAME call after the wait is the correct caller
-behaviour (service health, not request shape — no narrowing needed).
+gate and the call was never sent. `MAINTENANCE` is retryable with
+`notSent: true` + `retryAfter` — the zone's maintenance gate refused the call
+locally (issue #285); retry the SAME call after the window.
 `suggestedAction` is deterministic next-step text only (never free prose
 from the vendor).
 
@@ -324,7 +314,7 @@ transport reads the header:
 
 | `Content-Type` on the response | outcome |
 |---|---|
-| non-JSON-ish (`text/*` — incl. `text/json` — or anything not `application/json*` / a plus-json suffix) | `UNEXPECTED_CONTENT_TYPE` (server, retryable — advisory; `details = { httpStatus, contentType, bodySnippet }`) |
+| non-JSON-ish (`text/*` — incl. `text/json` — or anything not `application/json*` / a plus-json suffix) | `UNEXPECTED_CONTENT_TYPE` (server, retryable — advisory; `details = { httpStatus, contentType, bodySnippet }`); a body that reads as the maintenance page is `MAINTENANCE` instead (section 3.2.2) |
 | JSON-ish (`application/json*`, a plus-json suffix) | `INVALID_RESPONSE` (status quo — the #13/W-A7 shape-drift key; a wrong-shape 2xx is a shape-level failure, not a transport one) |
 | ABSENT | `INVALID_RESPONSE` (status quo — conservative; the maintenance-page premise carries a header) |
 
@@ -357,8 +347,8 @@ notice:
 - a non-JSON **`4xx`/`5xx`** page is waited out and retried only for calls that
   are **safe to re-send** (`retriable5xx`: a `GET` or an explicitly
   `idempotent`-flagged call). An UNFLAGGED mutation answered with such a page
-  makes **exactly one send** and surfaces the status's own error with
-  `details.maintenanceDetected = true` and a verify-before-reissuing action — a
+  makes **exactly one send** and surfaces `MaintenanceError` (`retryable:
+  false`) with `details.maintenanceDetected = true` and a verify-before-reissuing action — a
   proxy can serve that page AFTER forwarding the write, so the outcome is
   unknown (the §2.2 write rule is intact).
 
@@ -368,7 +358,9 @@ observed ceiling is 4 h (`MAINTENANCE_WINDOW_MAX_MS`; 19 live windows:
 30–240 min, median ≈ 2 h) — an unattended worker should pass
 `maintenanceMaxWaitMs: MAINTENANCE_WINDOW_MAX_MS`. The wait does not consume
 `maxRetries`, each post-wait attempt gets a fresh `timeoutMs`, and a caller
-`AbortSignal` interrupts the wait. A non-JSON HTML-ish page that does not look
+`AbortSignal` interrupts the wait. Only one call per zone waits at a time: the
+first page opens the zone's maintenance gate and every other call fails fast
+with `MAINTENANCE` (section 3.2.2). A non-JSON HTML-ish page that does not look
 like a maintenance notice (for example a wrong `baseUrl` serving a web site, or
 a stock proxy page) is surfaced at once with
 `details.maintenancePatternMiss = true` and the 256-byte snippet logged at
@@ -448,7 +440,7 @@ carries `notSent: true` is row 1, not row 3):
 
 | # | condition | state | retryable | why |
 |---|-----------|-------|-----------|-----|
-| 1 | `notSent === true` (the cooldown gate's / circuit breaker's local refusal) | `failed` | the error's own flag | the request never reached the vendor; the breaker's refusal retries the same call after the wait, the cooldown's is `retryable: false` (wait, then narrow the query first) |
+| 1 | `notSent === true` (the cooldown gate's / maintenance gate's local refusal) | `failed` | the error's own flag | the request never reached the vendor; the maintenance refusal retries the same call after the window, the cooldown's is `retryable: false` (wait, then narrow the query first) |
 | 2 | `httpStatus` in 400..499 except 429 | `failed` | `false` | the vendor answered; the write is definitely not applied |
 | 3 | `httpStatus === 429` | `failed` | `true` | a pre-processing refusal — retry once the cooldown / Retry-After allows |
 | 4 | `httpStatus === 500` and `parseVendorErrors(vendorError)` returns a non-empty array | `failed` | `false` | a deterministic business-rule rejection — the same body fails identically on retry |
@@ -513,21 +505,18 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
 | `timeoutMs` | 30 000 | — | whole-call budget, incl. retries |
 | `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps three legs (issues #105/#109): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network + non-JSON 2xx legs (GET + flagged only) |
 | `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the first 256 bytes of a non-JSON body read as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page. A `2xx` page is waited out for reads AND writes (edge-served before execution); a `4xx`/`5xx` page only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes ONE send and carries `details.maintenanceDetected` (a proxy can serve the page after forwarding). JSON bodies never enter. Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A non-matching HTML-ish page stamps `details.maintenancePatternMiss`. Observed ceiling 4 h: `MAINTENANCE_WINDOW_MAX_MS` (19 windows: 30–240 min, median ≈ 2 h) |
-| `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page |
+| `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page, and the maintenance gate's probe interval (section 3.2.2) |
 | `maxConcurrent` | 10 | 10 (vendor) | concurrency guard |
 | `profile` | `library` | — | `library` = today's defaults (changes nothing); `agent` = the conservative `AGENT_PROFILE` limits for LLM-driven workloads (below). Resolution: explicit config > profile > library default |
 | `maxResponseBytes` | 67 108 864 (64 MiB) | — | largest response body read; above it the call throws `RESPONSE_TOO_LARGE` (non-retryable) |
 | `rateLimit.perHour` | off | 10 000 (vendor) | opt-in client-side hourly limiter (sliding window; waits within the call deadline, else `RateLimitError`). `null` is the explicit "disabled" value (beats the profile). The limiter is **per process** — it cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the tenant-wide readout; `client.hourlyBudget()` is the local one) |
-| `cooldown` | on | 15 min (`cooldown.maxMs`) | per-tenant 429 cooldown gate (issue #6) — after a surfaced 429, further calls for that tenant (lowercased username + host) fail locally (`RATE_LIMITED_COOLDOWN`, `notSent: true`) until the deadline; `enabled: false` disables; `defaultMs` is the missing-`Retry-After` window (60 s); `store` injects a custom `CooldownStore` |
-| `circuitBreaker` | off | — | opt-in per-host circuit breaker (issue #26): `failureThreshold` (5) counted failures inside `failureWindowMs` (10 s) open the circuit for `openTimeoutMs` (30 s); `successesToClose` (2) probe successes close it; `halfOpenProbes` (default `= successesToClose`; validated `>= successesToClose`) bounds the half-open probes. Key = the host of the base URL (host-only — on a shared host, one tenant's outage opens the circuit for that host's other tenants; section 3.2.2). `thresholdInformation.get()` bypasses the refusal (the outcome is still recorded); `store` / `isFailure` inject the store / the failure predicate |
+| `cooldown` | on | 15 min (`cooldown.maxMs`) | per-tenant 429 cooldown gate (issue #6) — after a surfaced 429, further calls for that tenant (lowercased username + host) fail locally (`RATE_LIMITED_COOLDOWN`, `notSent: true`) until the deadline; `enabled: false` disables; `defaultMs` is the missing-`Retry-After` window (60 s) |
 | `resolution.maxScanRecords` | 500 | — | bounded client-scan cap (section 7, `resolve`) |
 | `resolution.maxScanPages` | 4 | — | bounded client-scan cap |
 | `resolution.scanOnMiss` | `false` | — | re-check a bare-value `resolve` miss with the bounded client scan (exact match on the search fields). Off: the server filter's zero items is a complete non-match (`null`, one call) |
 | `logger` | `NoopLogger` | — | request log sink |
 | `redactPersonalData` | `true` | — | response redaction for PII + confidential fields (section 10); `false` = raw personal data, secrets still redacted |
-| `cache` | on | — | `{ ttlMs?, perResourceTtlMs? }` read-through cache for get-by-id and `resolve` (issue #80: default-on — absent = the default instance, 5 min + the default per-resource table; `false` = off, the uncached path bit-for-bit). Snapshot at fetch time; a real write through the same client clears the cache and mutation-path reads bypass it. `perResourceTtlMs` (issue #32): a resource plan key -> ms map — a named resource expires on its own TTL, every other resource falls back to `ttlMs`; operator entries OVERRIDE the plan-derived default table `DEFAULT_PER_RESOURCE_TTL_MS` (`src/cache-ttl-tables.ts` — reference class 1h vs default class 5min), which IS the default map (applied by default since #80; section 11.15) |
-| `fieldCache` | on | `maxEntities` 256 | `{ ttlMs?, maxEntities? }` live field-metadata channel for the entityInformation trio (`getEntityInfo` / `getFieldInfo` / `getUdfInfo`) (issue #80: default-on — absent = the default instance, 5 min; `false` = the uncached wire path, bit-for-bit) — see section 11.14. With it `false` the trio is the uncached wire path, bit-for-bit. Live reads are snapshots at fetch time; a vendor drift (a deterministic validation 500, or an INVALID_RESPONSE on a metadata read) invalidates the named entity's entries; a record write never invalidates (it says nothing about the field catalog). Empty results are never cached; concurrent callers share one in-flight request |
-| `resourceNameCache` | on | `maxEntries` 1024 | `{ ttlMs?, maxEntries? }` resource-name channel for `operations.expandResourceNames` (issue #65; issue #80: default-on — absent = the default instance, 1 h; `false` = the uncached per-id path) — see section 11.21. With it `false` the op is the uncached per-id path (per-call de-duplication still applies). Live names are snapshots at fetch time; a `resources` write through the same client clears the channel, writes elsewhere show up once `ttlMs` expires. Failures are never cached; a vendor true not-found IS cached as a blind marker (a repeat miss costs no wire) |
+| `cache` | on | read 4096 / field 256 entries | `{ ttlMs?, fieldTtlMs?, store? }` the SDK's in-memory caches (issue #286; one block): single-record reads (get-by-id, the id branch of `resolve`, composite FK reads, `operations.expandResourceNames` names) live `ttlMs` (default 5 min; the reference tables `REFERENCE_ENTITIES` live 1 h), entity field metadata lives `fieldTtlMs` (default 5 min). `false` = every channel off. A real write through the client clears the record cache; a vendor drift signal drops one entity's field metadata (section 11.14). Lists, queries, counts, mutations and errors are never cached. `fieldCache`, `resourceNameCache` and `cache.perResourceTtlMs` were removed in 0.40.0 (the first two are refused) |
 | `update` | off | — | `{ putFallback?: boolean }` opt-in PUT item-path fallback for a 404'd non-collectionUpdate update route (issue #34) — see section 11.16. A TYPED 404 retries ONCE as `PUT /{Entity}/{id}` with the caller's fields merged onto a fresh unredacted read (never a null-clearing partial); collectionUpdate routes, `raw: true` updates and every non-404 fault are never retried — a declined gate throws the self-explaining error naming the route, the status and the opt-in |
 | `reResolveZoneOn401` | off | — | opt-in zone re-resolution on 401 (issue #43) — see section 11.19. A 401 on a relative path against a CATALOG base makes ONE unauthenticated vendor zone-discovery call; if the tenant's zone base has moved, the client re-points its live base URL (process-lifetime, observable via `http.baseUrl`) and retries the SAME request ONCE. An explicit `baseUrl` and an absolute path are never re-pointed; a resolved base identical to the live one, or a discovery fault, propagates today's typed 401 untouched (zero retry); a retry that 401s again carries `details.zoneRecovery = { from, to, retried: true }` |
 | `hostPolicy` | off | — | opt-in config-time HOST BOUNDS (skill 3.5.0 / L2) — see section 11.20. `{ blockPrivateHosts?: boolean; allowedOrigins?: readonly string[] }`: the RESOLVED base URL (explicit `baseUrl` or zone-derived) must pass every ACTIVE bound at construction time, pre-wire; a violation throws the typed `HostPolicyDeniedError` (`HOST_POLICY_DENIED`, category `policy`, `retryable: false`) naming the offending origin. `blockPrivateHosts: true` refuses a LITERAL private / loopback / link-local host (IPv4 10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, 0/8; IPv6 `::1`, `fc00::/7`, `fe80::/10`, IPv4-mapped `::ffff:a.b.c.d`); `allowedOrigins` is an EXACT normalised-origin allow-list. Checks run on the canonical `new URL(origin).host` — HOSTNAMES are never blocked (no DNS lookups); the private bound is checked FIRST and WINS; a present block with no active bound is refused fail-closed; with `reResolveZoneOn401: true` the same bounds gate the discovery-provided re-point target (a refused host is a discovery fault) |
@@ -590,88 +579,41 @@ shell-quoting/line-break artifacts — check your env load (…)`) or was clean
 likely cause`). The message and `suggestedAction` are unchanged — the
 diagnostic is appended as a separate field, and a 401 is still never retried.
 
-#### 3.2.2 The per-host circuit breaker (issue #26)
-
-`circuitBreaker: { enabled: true }` opts into the optional circuit breaker
-at the transport (OFF by default — without it, behaviour is byte-identical
-to before; no env overrides — `src/config/` never reads `process.env`).
-Vendor health is HOST-scoped (a zone outage hits every tenant on that
-zone), so the key is the lowercased host of the resolved base URL
-(`buildBreakerKey` — the same derivation as `buildTenantKey`'s host part,
-without the username). Consequences:
-
-- **A different host is unaffected**; a different tenant on the SAME host
-  (different credentials — including a per-tenant pooled client on a
-  shared-host gateway) SHARES the circuit: one tenant's outage opens the
-  breaker for that host's other tenants too. That is the documented
-  consequence of the host-only key; `enabled` is off by default, so nothing
-  changes unless opted in.
-- The breaker is PER PROCESS (like the #6 gate and the hourly tracker): in
-  an N-process gateway there are N independent breakers per host — during a
-  half-open window at a downed host, up to N × `halfOpenProbes` probes go
-  upstream (one admission set per process); the state is not shared across
-  processes. Keep the process count small when the vendor is maintenance-
-  prone, or size `halfOpenProbes` accordingly.
-- The state rides the STORE, not the client: the default store is the
-  in-process in-memory map shared by every client instance (capped at 1024
-  entries, evicting the oldest last-activity first — failing open;
-  deliberately not `globalThis`-anchored — the #6 two-builds note applies),
-  so a pool LRU eviction of a tenant client loses nothing (an
-  evicted-then-recreated tenant on the same host hits the same state).
-  `store` injects a custom `CircuitBreakerStore` (the same get/set/delete
-  shape as `CooldownStore`, over the richer per-key state
-  `{ failures, openedAt, successes, probes, windowOpenedAt? }`;
-  `windowOpenedAt` is the open-window identity a probe's settlement is
-  pinned to — persist it as-is, and keep every process sharing a store on
-  the same version, since a build that re-arms an entry without it leaves
-  newer pinned probes voided with their slot unreleased).
-
-**States (timer-free — derived from `Date.now()` lazily at each request,
-exactly like the #6 cooldown):** `closed` (no entry / nothing armed — a
-healthy host leaves no store entry) → at `failureThreshold` counted
-failures strictly inside the sliding `failureWindowMs` window, the circuit
-OPENS (`openedAt` recorded) → while open, calls are refused LOCALLY in the
-same pre-send slot as the #6 cooldown gate (OUTSIDE the retry loop, before
-the hourly limiter, the semaphore and fetch: zero fetches, no hourly
-stamp, the audit event carries `notSent: true` + `errorCode:
-'CIRCUIT_BREAKER_OPEN'`) → after `openTimeoutMs` the state is half-open
-(the lazy transition): up to `halfOpenProbes` probes go upstream (further
-calls while the probe budget is in flight are refused with
-`details.state: 'half-open'` and no defined `retryAfter` — there is no
-defined wait; a probe verdict clears the refusal); a probe SUCCESS counts
-toward `successesToClose` (reached → closed, counters reset, the entry
-deleted); a probe FAILURE re-arms the open period from now. A counted
-failure is the SURFACED outcome (after the transport's own retries) —
-retries are the transport's business; the breaker counts the call's end.
-
-**The default failure predicate** (injectable via
-`circuitBreaker.isFailure`; the default `isBreakerFailure` counts exactly):
-`NETWORK_ERROR`, `TIMEOUT`, a vendor 429 (keyed on the STATUS — a surfaced
-429 may carry an adopted vendor machine code, e.g. the thread-threshold
-`Itgenatr005`), a 5xx EXCEPT the deterministic field-validation 500 (keyed
-on #23's `details.deterministic` signal — by that signal only), and
-`UNEXPECTED_CONTENT_TYPE` (the #24 maintenance page, by code — NEVER
-`INVALID_RESPONSE`: the W-A7 shape-drift and the #13 marker-recovery key
-are untouched). Never counted: `ABORTED` (a caller's cancellation says
-nothing about service health), any 4xx, and local/policy refusals
-(`notSent` — the cooldown gate's or the breaker's own; a call that never
-reached the vendor is never a service failure).
-
-**Validation (fail-closed at construction, the #6 pattern):** every number
-must be a positive integer; `halfOpenProbes` MUST be `>= successesToClose`
-(a breaker that can never close is a misconfiguration — refused); the
-store must implement `get`/`set`/`delete`; `isFailure` must be a function.
-Validation runs even with `enabled: false`.
-
-**The threshold bypass (the #6 precedent):** `thresholdInformation.get()`
-bypasses the REFUSAL so a downed host can still be probed for headroom —
-its outcome is still RECORDED: a 2xx counts toward `successesToClose`
-(closes toward recovery); a counted failure re-arms the open period. An
-already-aborted caller signal still wins over an open-circuit refusal (the
-abort error, not the breaker error).
-
-Surfacing breaker state in the doctor is a FOLLOW-UP (not requested by the
-issue); the state is inspectable through the injected/default store.
+#### 3.2.2 The per-zone maintenance gate (issue #285)
+
+Autotask takes each zone down for a weekly maintenance window; the edge then
+serves an HTML maintenance page (recognised at any status when the 256-byte
+head of a non-JSON body contains `maintenance`, `outage`, `downtime` or
+`down for`; a JSON body never is). Generic 503 wording (`service
+unavailable`, `temporarily unavailable`) is NOT the signature: such a page
+keeps the ordinary 5xx retry leg and never opens the gate. The gate is process-wide, keyed by the
+lowercased host of the live base URL, and always on:
+
+- The first call that sees the page OPENS the zone's gate (`since` = now).
+- While open, every other call on the zone is refused LOCALLY in the pre-send
+  slot (after the #6 cooldown check, before the hourly limiter, the semaphore
+  and fetch: zero fetches, no hourly stamp, the audit event carries
+  `notSent: true` + `errorCode: 'MAINTENANCE'`) with `MaintenanceError`.
+- One call per `maintenancePollMs` is admitted as the PROBE (single-flight: a
+  call that is waiting the window out owns the probe slot for its whole wait).
+  The first non-maintenance response from the zone, from any call, CLOSES it.
+- The call that saw the page (or the admitted probe) waits the window out up
+  to `maintenanceMaxWaitMs`, polling every `maintenancePollMs`, when it is
+  safe to re-send (section 2.1). Every call that receives the page and does
+  not wait it out (wait off, budget spent, another call owns the probe slot,
+  or an unflagged write at a non-2xx status) throws the same
+  `MaintenanceError`, with `httpStatus` set, no `notSent`, and
+  `details.maintenanceDetected` + the 256-byte `bodySnippet`; the unflagged
+  non-2xx write is `retryable: false` with a verify-first action (its outcome
+  is unknown). So a consumer maps one code: `MAINTENANCE`.
+  `maintenanceMaxWaitMs: 0` disables the wait (fail fast); the gate still opens. A maintenance page never takes
+  the generic retry leg.
+- A non-matching HTML page (a wrong `baseUrl` serving a web site) never opens
+  the gate; it surfaces with `details.maintenancePatternMiss`.
+- Only the page signature is detected: a window that answers with refused or
+  reset connections surfaces as `NETWORK_ERROR` and does not open the gate.
+- The state is per process (like the #6 gate and the hourly tracker); an
+  N-process gateway sends up to N probes per interval.
 
 ### 3.3 `onAudit(event)`
 
@@ -680,8 +622,8 @@ One event per completed request (never called before the request settles):
 errorCode?, notSent? }` — `body` is the request body with credential-shaped
 fields redacted by default; `status` is absent when the request failed before
 a response; `notSent: true` marks a call that was refused locally by the
-tenant cooldown gate or the circuit breaker (section 3.2.2 — disambiguate on
-`errorCode`: `RATE_LIMITED_COOLDOWN` vs `CIRCUIT_BREAKER_OPEN`); in either
+tenant cooldown gate or the zone maintenance gate (section 3.2.2 — disambiguate on
+`errorCode`: `RATE_LIMITED_COOLDOWN` vs `MAINTENANCE`); in either
 case nothing reached the wire.
 
 ## 4. Pagination contract
@@ -777,33 +719,9 @@ carry paging parameters.
     `limit >= latest` (above that the returned count is governed by
     `latest`; `limit` is the blind-branch walk window). `latest` is
     query-verb-ONLY (`queryAll` / `count` bags are unchanged).
-    **The count-probe cache (issue #127).** 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 plan key, canonical filter serialisation).
-    A re-asked "top N" within 30 s makes ZERO extra vendor count calls for
-    every CACHED probe (full-set AND threshold mode); a probe that answered
-    0 is deliberately re-wired (a 0 is never cached — see below), so a
-    threshold search that hit a 0 pays those probes again. A real write
-    through the SAME client
-    clears the cache — and a probe still in flight across the write is
-    DISCARDED by the cache's invalidation epoch (issue #139: its pre-write
-    answer must not re-anchor a stale top-N within the TTL — the next
-    `latest` re-probes). Never cached: the blind-surface / pinned-empty
-    sentinels (the plan-pinned stamps stay fresh and re-derive on every
-    call), errors, and anything outside the probe path — the plain `count`
-    op and `operations.aggregate` call the vendor count directly and
-    promise fresh totals. A write made ELSEWHERE (another client, the
-    Autotask UI) shows up once the 30 s TTL expires — that is the
-    documented snapshot trade. The truncation guard covers the
-    growth-of-total direction; a stale-LOW total within the TTL is NOT
-    left to it: when a full-set walk truncates against a cached total,
-    the SDK re-probes the total ONCE fresh (invalidating the entry) and
-    continues the walk to a larger fresh total — the
-    `LATEST_WINDOW_INCOMPLETE` refusal stands only when the fresh probe
-    confirms the cached value (bounded: at most one extra count probe per
-    walk). 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.
+    **Count probes are never cached** (issue #286 removed the issue #127
+    count cache): every `latest` call pays its own count probes, so a
+    repeated "top N" sees the vendor's current totals.
   - **`noteChars: N` (issue #61) — the opt-in per-field free-text cap.**
     `N` (integer >= 1, pre-request validated, zero wire) caps EVERY
     string value in the resource's untrusted-class free-text fields
@@ -975,16 +893,15 @@ types, type-only) alongside `./capabilities` and `./operations`.
 
 ### Pooled clients and the shared read cache (`./pool` subpath, issue #219 N6)
 
-`createClientPool({ maxSize?, idleTtlMs?, factory?, sharedReadCache? })` keeps
+`createClientPool({ maxSize?, sharedReadCache? })` keeps
 one `AutotaskClient` per credential tuple (`{ get, delete, clear, size }`) so a
 multi-tenant gateway reuses each tenant's limiter state. Each pooled client has
 its own read cache, so a write through one client never cleared what another
 client of the SAME tenant would serve — a post-write read-back routed to a
-re-created client (a `delete(config)` on a 401, an LRU eviction, an idle
-expiry) could return the pre-write snapshot for up to the resource TTL
+re-created client (a `delete(config)` on a 401 or an LRU eviction) could return the pre-write snapshot for up to the resource TTL
 (contacts: 5 min).
 
-**Default (shared):** the pool OWNS one `ReadCache` per credential tuple and
+**Default (shared):** the pool OWNS one record `TtlCache` per credential tuple and
 hands it to every client it builds for that tuple (via the `cache.store`
 config seam), so any write through any pooled client of that tenant voids the
 read cache for all of them and a read-back is never served the pre-write
@@ -993,8 +910,8 @@ entries still expire on their own TTL), is pruned at `maxSize` and dropped by
 `clear()`. `sharedReadCache: false` restores per-client caches (then route a
 post-write read-back through the writing client). `cache: false` opts the tuple
 out entirely. `cache.store` is otherwise a plain advanced seam: a supplied
-`ReadCache` instance is used as-is, and `ttlMs` / `perResourceTtlMs` beside it
-refuse (the instance owns its TTLs).
+`TtlCache` instance is used as-is, and `ttlMs` beside it refuses (the instance
+owns its TTL).
 
 ### Fresh single-record reads (`fresh: true`, issue #250)
 
@@ -1155,7 +1072,7 @@ be cross-mode-refused.
 whose MCP annotation is `readOnlyHint !== true` — today exactly **267
    tools**: the 265 dedicated write/delete tools (209 `effect=write` + 56
    `effect=destructive`, every one of them has a dedicated tool) +
-`autotask_write` + `autotask_delete`. The remaining **635 tools** (the 622 dedicated read tools + the 10 core read tools + `autotask_read` +
+`autotask_write` + `autotask_delete`. The remaining **634 tools** (the 621 dedicated read tools + the 10 core read tools + `autotask_read` +
 `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true`
 and are safe ungated: every op they can route is `effect=read` (zero
 mutating requests — pinned by the test inventory, §6 of the split design).
@@ -1299,7 +1216,7 @@ the authority read (section 11.2).
 one wire verb is `GET /V1.0/Resources/{id}`, an id of any other vendor
 entity (a ticket / company / contact / billing-code id) resolves to an
 unrelated person's name when it collides with a live staff id (and the
-wrong name then sticks in the default-on `resourceNameCache` under that id
+wrong name then sticks in the default-on read cache under that id
 until TTL — a one-off mis-feed keeps serving it; section 11.21), or to a
 misleading `blind: true` marker when it does not. An `AutotaskError`'s
 legacy `resourceIds` may carry exactly those (the field is unlabeled —
@@ -1335,17 +1252,14 @@ the unlabeled field.
   resolved, blind, failed }`.
 - **Wire cost**: `N` unique ids cold = `N` GETs; warm (inside the TTL of
   the channel below) = 0.
-- **Cache**: the `resourceNameCache` channel (section 11.21) —
-  each distinct id is fetched at most once per cache lifetime (the blind
-  marker is cached too: a repeat miss costs no wire; a failure is never
-  cached). Default-on (issue #80) — with `false` the op is the uncached per-id
-  path (per-call de-duplication still applies). A `resources` write
-  through the same client clears the channel; a rename made elsewhere
-  shows up once `ttlMs` expires (the documented staleness contract). A
-  `fresh: true` call bypasses BOTH the name cache AND the ReadCache (the
-  per-id `resources.get` fetches live and refreshes the ReadCache entry as
-  well) — a rename made elsewhere is served on the very next fresh call,
-  never a stale snapshot (issue #77).
+- **Cache**: the record cache (section 11.21) — each distinct id is
+  fetched at most once per cache lifetime (the not-found marker is cached
+  too: a repeat miss costs no wire; a failure is never cached). With
+  `cache: false` the op is the uncached per-id path (per-call
+  de-duplication still applies). Any write through the same client clears
+  it; a rename made elsewhere shows up once `ttlMs` expires. A
+  `fresh: true` call bypasses and refreshes the cache — a rename made
+  elsewhere is served on the very next fresh call (issue #77).
 
 ```ts
 import { expandResourceNames } from 'node-autotask/operations';
@@ -1488,9 +1402,10 @@ notes cannot be deleted, so they never use create-then-delete.
   optionally scoped to one company (a `companyID eq` leaf and-joined server-side with the title match) and
   projected to the listed columns (`id` is always returned). `searchWithDetail` takes the same bag. Malformed
   `companyID` / `includeFields` are refused before any request. Other resources' `search` is unchanged.
-- **Deprecated (issue #278, since 0.38.0; removed in the next minor):** `time_entries.recentTickets` is a
-  strict subset of an aggregate grouped by ticket now that relation filters (§5) and default labels (§11.27)
-  exist. Replacement (1-2 calls instead of 2+):
+- `search` refuses an unknown option key (a misspelt `companyId` can't silently widen the search), and drops an
+  empty `userDefinedFields` the vendor appends to projected rows.
+- **Hours per ticket for a resource** (`time_entries.recentTickets` was removed in 0.41.0, issue #290): aggregate
+  the time entries grouped by ticket, using relation filters (§5) and default labels (§11.27):
 
   ```ts
   const res = await aggregate(client, 'time_entries.query', [
@@ -1505,22 +1420,9 @@ notes cannot be deleted, so they never use create-then-delete.
 
   For per-ticket status / assignee / company use `operations.fetchByIds` on the group ticket ids (labels
   included: `statusLabel`, `assignedResourceIDName`, `companyIDName`).
-- `time_entries.recentTickets(from, to, { resourceID, companyID?, tz?, limit? })` — the distinct tickets a
-  resource logged time against in an inclusive `dateWorked` window (`YYYY-MM-DD`; UTC days, or the local days in
-  `tz`). One bounded time-entry read (`dateWorked` + `resourceID`; `limit` 1-500, default 500, bounds the
-  **entries** scanned) plus `id in [...]` ticket reads (100 ids each). Result `{ items, entriesRead,
-  entriesWithoutTicket, unresolvedTicketIDs, window, truncated }`; each item carries `ticketID`, `ticketNumber`,
-  `title`, `status`, `assignedResourceID`, `companyID`, `entryCount`, `totalHours`, `lastWorked`, newest first.
-  TimeEntry has no `companyID`, so `companyID` is applied **after the join**, client-side on the ticket rows'
-  own `companyID` (the ticket read is not company-filtered on the wire). Entries on other companies' tickets
-  still consume `limit`; those tickets are only counted in `excludedTickets` (ids are not returned), and
-  `unresolvedTicketIDs` holds only tickets the read did not return at all (deleted or invisible, dropped from
-  `items` when `companyID` is set). `truncated: true` (same meaning as `postedWithin`) means the rollup covers
-  the scanned entries only; narrow the window. `search` refuses an unknown option key (a misspelt `companyId`
-  can't silently widen the search), and drops an empty `userDefinedFields` the vendor appends to projected rows.
-- **`tz` on the `dateWorked` ops** (`recentTickets`, `postedWithin`, `dateWorkedWindow`, `customRange` and the relative
+- **`tz` on the `dateWorked` ops** (`postedWithin`, `dateWorkedWindow`, `customRange` and the relative
   windows): the vendor stores `dateWorked` as a date-only value at 00:00 UTC, so the wire bounds are always whole UTC days.
-  For `recentTickets` / `postedWithin` / `dateWorkedWindow` / `customRange` the `from`/`to` days ARE the days, so `tz` is
+  For `postedWithin` / `dateWorkedWindow` / `customRange` the `from`/`to` days ARE the days, so `tz` is
   validated but never shifts them. For the relative windows (`today`, `last7`, `lastFullMonth`, ...) `tz` picks which
   calendar dates the window covers in that zone and the bounds are whole UTC days of those dates. (Before 0.24.0 a `tz`
   behind UTC, e.g. `America/Los_Angeles`, selected the NEXT UTC day; live-verified 2026-10-23.)
@@ -1585,8 +1487,7 @@ resolver holds a status literal: the move engine's closed-target refusal,
 `tickets.forResource(resourceID, opts?)` lists the tickets assigned to one
 resource, as primary assignee, secondary resource, or both (the `scope` option,
 default `both`; the seam is `Tickets.assignedResourceID` for primary and the
-`TicketSecondaryResources` link table for secondary). It follows
-`time_entries.recentTickets`: two bounded reads (a `Tickets/query` on
+`TicketSecondaryResources` link table for secondary). Two bounded reads (a `Tickets/query` on
 `assignedResourceID` and a `TicketSecondaryResources/query` on `resourceID`,
 both `id in [...]`-chunked when the link set is large) unioned client-side —
 deliberately not the cross-field grouped `or`, whose live semantics are
@@ -1814,7 +1715,7 @@ const lob = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-0
 // lob.rows[i].keys.lineOfBusiness → { id: 7, name: '<level2>', division: '<level1>' } | { id: null, label: 'no LOB assigned' }
 ```
 
-## 8. Resource surface (135 resources)
+## 8. Resource surface
 
 <!-- BEGIN GENERATED:api-per-entity -->
 Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page guarded), `queryBounded` (server-side pagination — one call walks the cursor until `limit` TOTAL records, default 500 / max 2500, with a `hasMore` flag; the MCP `query` surface, routed by `invoke`), `queryAll` (collect → `T[]` — the unbounded raw walk), `count`, `get` (id → record; `item: null` → `NotFoundError`), `create` / `update` / `delete` (where the vendor defines them — mutations take a `MutationOpts` bag: `{ dryRun, lastModifiedDate?, maxRetries? }` (issue #105: `maxRetries` overrides the configured retry budget for every request the mutation issues; `0` = exactly one send per request)), plus the helper floor where the plan declares it: `resolve` (all 121), `search` (40 — bounded contains on the resource text field), `getContext` (5 workflow resources), `findBy<Field>` (3), `createIfNotExists` (14). Entity metadata on every resource: `getEntityInfo`, `getFieldInfo`, `getUdfInfo` (UDF-capable 16). Parent-scoped children take `(parentId, id)` on the CRUD methods and require `parentId` on `createIfNotExists` (the scoped create POSTs the scoped collection; the dedup query stays global); `query`/`count`/`resolve`/`search` stay global (narrow with a `parentField` filter). Scoped `update` PATCHes the collection (the vendor keys the record by the id in the body).
@@ -1829,7 +1730,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `checklist_libraries` | ChecklistLibrary | entity | extended | no | query, count, get, create, update, delete, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_checklistLibrary_get |
 | `checklist_library_checklist_items` | ChecklistLibraryChecklistItem | entity | extended | yes (checklist_libraries) | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_checklistLibraryChecklistItem_get |
 | `classification_icons` | ClassificationIcon | entity | advanced | no | query, count, get, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_classificationIcon_get |
-| `companies` | Company | entity | core | no | query, count, get, create, update, resolve, search, getContext | fullProfile, getEntityInfo, getFieldInfo, getUdfInfo, searchByDomain, searchByIdentity, unbilledWork, upsertByName | autotask_company_get |
+| `companies` | Company | entity | core | no | query, count, get, create, update, resolve, search, getContext | fullProfile, getEntityInfo, getFieldInfo, getUdfInfo, prepareCrmWrite, searchByDomain, searchByIdentity, unbilledWork, upsertByName | autotask_company_get |
 | `company_alerts` | CompanyAlert | entity | extended | yes (companies) | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_companyAlert_get |
 | `company_locations` | CompanyLocation | entity | extended | yes (companies) | query, count, get, create, update, delete, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_companyLocation_get |
 | `company_notes` | CompanyNote | entity | extended | yes (companies) | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_companyNote_get |
@@ -1870,8 +1771,9 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `contract_service_units` | ContractServiceUnit | entity | extended | yes (contracts) | query, count, get, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_contractServiceUnit_get |
 | `contract_services` | ContractService | entity | extended | yes (contracts) | query, count, get, create, update, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_contractService_get |
 | `contract_ticket_purchases` | ContractTicketPurchases | entity | extended | yes (contracts) | query, count, get, create, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_contractTicketPurchase_get |
-| `contracts` | Contract | entity | extended | no | query, count, get, create, update, resolve, search | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo, profitability | autotask_contract_get |
+| `contracts` | Contract | entity | extended | no | query, count, get, create, update, resolve, search | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, profitability | autotask_contract_get |
 | `countries` | Country | entity | advanced | no | query, count, get, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_country_get |
+| `currencies` | Currency | entity | advanced | no | query, count, get, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_currency_get |
 | `departments` | Department | entity | extended | no | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_department_get |
 | `domain_registrars` | DomainRegistrar | entity | extended | no | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_DomainRegistrar_get |
 | `expense_item_attachments` | ExpenseItemAttachment | entity | extended | yes (expense_items) | query, count, get, create, delete, resolve | download, getEntityInfo, getFieldInfo, getUdfInfo | autotask_expenseItemAttachment_get |
@@ -1935,7 +1837,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `ticket_categories` | TicketCategory | entity | extended | no | query, count, get, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketCategories_get |
 | `ticket_category_field_defaults` | TicketCategoryFieldDefault | entity | extended | yes (ticket_categories) | query, count, get, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketCategoryFieldDefaults_get |
 | `ticket_change_request_approvals` | TicketChangeRequestApproval | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketChangeRequestApprovals_get |
-| `ticket_charges` | TicketCharge | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve, search | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketCharge_get |
+| `ticket_charges` | TicketCharge | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve, search | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo, moveToTicket | autotask_ticketCharge_get |
 | `ticket_checklist_items` | TicketChecklistItem | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketChecklistItem_get |
 | `ticket_checklist_libraries` | TicketChecklistLibrary | entity | extended | yes (tickets) | create, resolve | attachToDocument, getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketChecklistLibrary |
 | `ticket_history` | TicketHistory | entity | extended | no | query, count, get, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketHistory_get |
@@ -1944,8 +1846,8 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `ticket_notes` | TicketNote | entity | extended | yes (tickets) | query, count, get, create, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketNote_get |
 | `ticket_secondary_resources` | TicketSecondaryResource | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketSecondaryResources_get |
 | `ticket_webhooks` | TicketWebhook | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketWebhook_get |
-| `tickets` | Ticket | entity | core | no | query, count, get, create, update, resolve, search, getContext | changeStatus, findByTicketNumber, forResource, fullContext, getEntityInfo, getFieldInfo, getUdfInfo, openWithNoteAndAssign, slaHealthCheck, statusSemantics, summary, timeline | autotask_ticket_get |
-| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | approve, createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, postedWithin, today, yesterday | autotask_timeEntry_get |
+| `tickets` | Ticket | entity | core | no | query, count, get, create, update, resolve, search, getContext | changeStatus, findByTicketNumber, forResource, fullContext, getEntityInfo, getFieldInfo, getUdfInfo, lineOfBusiness, openWithNoteAndAssign, slaHealthCheck, statusSemantics, summary, timeline | autotask_ticket_get |
+| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | approve, createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, moveToTicket, postedWithin, today, yesterday | autotask_timeEntry_get |
 | `time_entry_attachments` | TimeEntryAttachment | entity | extended | yes (time_entries) | query, count, get, create, delete, resolve | download, getEntityInfo, getFieldInfo, getUdfInfo | autotask_timeEntryAttachment_get |
 | `time_off_requests` | TimeOffRequest | entity | extended | no | query, count, get, resolve | approve, getEntityInfo, getFieldInfo, getUdfInfo, reject | autotask_timeOffRequest_get |
 | `inventory_products` | InventoryProduct | entity | extended | no | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo, stockedItemsAdd, stockedItemsRemove, stockedItemsTransfer | autotask_inventoryProduct_get |
@@ -1957,7 +1859,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `threshold_information` | — | integration | core | no | get | — | autotask_threshold_information |
 | `zone_information` | — | integration | advanced | no | get | — | autotask_zone_information |
 
-129 resources (122 entity + 7 integration). Rows are generated from the registry — do not hand-type.
+128 resources (121 entity + 7 integration). Rows are generated from the registry — do not hand-type.
 <!-- END GENERATED:api-per-entity -->
 
 **`companies.search` include_family (issue #59).** `companies.search` is
@@ -2890,10 +2792,10 @@ reality*), so the point-in-time pins (`operations.createGuidance`, the
 `zoneFacts` lists) are only as fresh as their `verifiedAt`. The live
 channel is the refresh side of that pair:
 
-**Config (on by default; `false` opts out):** `fieldCache: { ttlMs?, maxEntities? }` — a
-separate block from `cache` (different key — entity vs resource+id —,
-different lifetime, different invalidation signal: drift vs write). With
-it `false` there is no `FieldCache` instance at all and the
+**Config (on by default; `cache: false` opts out):** `cache: { fieldTtlMs? }` — a
+separate `TtlCache` instance from the record cache (different key — entity vs
+resource+id —, different lifetime, different invalidation signal: drift vs
+write). With `cache: false` there is no field cache at all and the
 `getEntityInfo` / `getFieldInfo` / `getUdfInfo` trio is the uncached wire
 path, bit-for-bit; absent, the default instance is built and the trio
 goes through one private helper
@@ -3039,52 +2941,18 @@ closed bag, the W-A4 sentence in the served purpose, and the
 `udfCapable` / `getUdfInfo` / `getFieldInfo` row invariants);
 `test/scripts/g16-field-catalog.test.ts` is the tripwire.
 
-### 11.15 Per-resource read-cache TTLs (issue #32)
-
-One `ttlMs` forces the operator to choose the worst case for the two very
-different reads an agent session mixes: reference tables that change on a
-human timescale (countries, departments, roles, billing codes, services)
-and records that change minute to minute (tickets, time entries). The
-override makes the choice per resource:
-
-**Config (the default map; `false` opts out):** `cache: { ttlMs?,
-perResourceTtlMs?: Record<string, number> } | false` — every value is a
-positive integer, validated fail-closed in `resolveConfig` exactly like
-`ttlMs` (wrong type / non-integer / non-positive → `AutotaskConfigError`
-at construction). Issue #80: the plan-derived table
-`DEFAULT_PER_RESOURCE_TTL_MS` IS the default per-resource map — with the
-operator map absent, every plan resource rides its table row (the 1h
-reference class / the 5min default class) and a plan-unnamed path expires
-on `ttlMs`; operator entries OVERRIDE table entries per resource (the
-effective map is operator entry > table entry > `ttlMs`).
-
-**The key contract (pinned):** the entry's TTL is the override for the
-**plan key of the entity the read path points to** — the cache key is
-still the wire path (`/V1.0/<Entity>/<id>`, unchanged), and the base read
-path keys the TTL by the entity of that path. A cross-entity read
-therefore expires on the READ entity's override: a contact read through
-`tickets.getContext` is stored under the contact's key (the plan-derived
-path index `RESOURCE_KEY_BY_PATH`), so a `contacts`/`resources` override
-bounds it, not the ticket's. A path the plan does not name falls back to
-`ttlMs` (the entry, not the call, decides the expiry).
-
-**The plan-derived default table (not hand-written):** the plan carries
-no staleness marker (the closed `kind` set is entity/integration), so the
-reference SET is a pinned design decision in `scripts/lib/cache-ttl.mjs`
-— the issue's own motivation names the human-timescale lookup tables
-(countries, departments, roles, billing_codes, services) and the prior
-art (the independent WYRE-AI `calculateResponseTTL`) adds phases. The
-table STRUCTURE is plan-derived: `src/cache-ttl-tables.ts` (the 7th
-generated artifact, planHash-stamped, regenerated by
-`generate-capabilities`) carries one row per plan resource — reference
-class 1h (`CACHE_TTL_REFERENCE_MS`) vs default class 5min
-(`CACHE_TTL_DEFAULT_MS`) — so a plan change regenerates the split, and a
-hand-written table would be the one drift hazard. It is a REFERENCE for
-building the operator's map (spread + per-operator pins, e.g.
-`{ ...DEFAULT_PER_RESOURCE_TTL_MS, tickets: 60_000 }`), never applied
-implicitly. MCP: nothing new served; the config is operator-side.
-Gate: `check-capabilities` clause 8a + `test/scripts/cache-ttl-artifact.test.ts`
-(byte-equal re-derivation — the table regenerates with the plan).
+### 11.15 Read-cache TTLs (issue #32, simplified in #286)
+
+Reference tables change on a human timescale; records change minute to
+minute. The record cache therefore keys its TTL on the entity segment of the
+cached read path (`readTtlFor` in `src/cache.ts`): the tables in
+`REFERENCE_ENTITIES` (BillingCodes, Countries, Departments, Phases, Roles,
+Services) live `REFERENCE_TTL_MS` (1 h, or `ttlMs` when that is longer);
+every other record lives `cache.ttlMs` (default 5 min). The key is the wire
+path, so a cross-entity read (a contact read through `tickets.getContext`)
+expires on the READ entity's TTL, and a not-found marker on its path's TTL.
+The per-resource override map (`cache.perResourceTtlMs`) and the generated
+per-resource table were removed in 0.40.0.
 
 ### 11.16 The opt-in PUT item-path fallback for a 404'd update route (issue #34)
 
@@ -3208,9 +3076,7 @@ config surface, no new ops) and pins the two hazards the issue names:
 - **The FK parts are cached; the ticket root stays fresh.** The
   reference-table FK parts ride the normal cached get-by-id path (the #32
   keying: each part is stored under the read entity's path and expires on
-  that entity's per-resource TTL — the plan-derived 5min non-reference
-  class via `DEFAULT_PER_RESOURCE_TTL_MS`, or the operator's
-  `perResourceTtlMs` pin). The ticket read itself is FRESH (`fetchRecordRaw`
+  that entity's TTL (section 11.15). The ticket read itself is FRESH (`fetchRecordRaw`
   with `fresh: true`): the composite root is always the live record —
   caching is scoped to the reference-table FK parts only (a repeat
   `getContext` wires exactly the ticket; a repeat `fullContext` wires the
@@ -3219,7 +3085,7 @@ config surface, no new ops) and pins the two hazards the issue names:
   the current (cacheable) root behaviour.
 - **Negative cache, no poisoning.** A vendor NOT-FOUND on an FK part (the
   404 or the 200 `item: null` signal) is stored as an 'absent' marker in
-  the SAME `ReadCache` under a namespaced key the positive path never
+  the SAME record cache under a namespaced key the positive path never
   constructs (the `.get` / `resolve` single-record read paths are bit-
   for-bit untouched): a repeat composite serves 'absent' with zero wire
   for that part. The marker expires on the read entity's TTL and dies
@@ -3250,7 +3116,7 @@ config surface, no new ops) and pins the two hazards the issue names:
 
 - **Opt-in names/labels ride these same channels (issue #77).** The
   composites' opt-in `names` siblings resolve over the existing
-  default-on channels (the name cache / the ReadCache / the fieldCache —
+  default-on channels (the record cache / the field cache —
   no new cache) with a separate name-read budget (`maxNameReads`,
   default 20, lowerable never raised) — see section 11.21 for the
   per-field-class wiring.
@@ -3305,21 +3171,12 @@ what makes it usable as a recovery signal from inside the client.
   transport's size cap): today's typed 401 propagates
   byte-identically — zero retry (the recovery must not turn a credential
   fault into a discovery fault).
-- **State hygiene.** The transport's per-host state (the tenant rate key
-  and the circuit-breaker key, both keyed on the base URL) is RE-DERIVED
-  on the re-point, so the re-pointed host starts FRESH — no cooldown /
-  breaker / tenant-rate inheritance from the stale host (conservative: the
-  stale host's armed entries stay in the shared stores for the other
-  clients that still talk to it; nothing is copied across). A circuit-
-  breaker PROBE admitted on the stale host is pinned to that host's key:
-  if the call re-points, the probe is voided (its outcome was measured on
-  a different host) — the re-pointed host's probe budget / close count is
-  never touched by a stale-host probe, and the stale host's admitted
-  budget dangles for the rest of the open period (bounded, conservative,
-  nothing crosses hosts). The probe is equally pinned to the open WINDOW
-  it was admitted in (issue #271): a probe that settles after that window
-  closed and re-opened is voided the same way — the newer window's probe
-  budget / close count is never touched by a stale-window probe. The
+- **State hygiene.** The transport's per-host gate keys (the tenant
+  cooldown key and the maintenance-gate key, both keyed on the base URL) are
+  RE-DERIVED on the re-point, so the re-pointed host starts FRESH — no
+  cooldown / maintenance-gate inheritance from the stale host (its armed
+  entries stay for the other clients that still talk to it; nothing is copied
+  across). The
   re-point is
   recorded on the client: the live base URL is observable via
   `http.baseUrl` (the configured `config.baseUrl` stays the
@@ -3341,9 +3198,8 @@ what makes it usable as a recovery signal from inside the client.
   lifetime, like a cache); no change to the served MCP/n8n text (transport
   behaviour, like #34).
 
-Pins: `test/transport-zone-reresolve/*.test.ts` (11 pins, mock wire only —
-no vendor wire in tests; the 10 issue-required + the breaker probe
-host-pinning pin).
+Pins: `test/transport-zone-reresolve/*.test.ts` (mock wire only — no vendor
+wire in tests).
 
 ### 11.20 Config-time host bounds — `hostPolicy` (skill 3.5.0 / L2, audit-fix A1)
 
@@ -3416,74 +3272,19 @@ Pins: `test/config-host-policy.test.ts` (10 pins — the exported helper is
 CONSUMED by the tests, never re-implemented; mock wire only, no vendor
 wire).
 
-### 11.21 Resource name expansion and the name cache (issue #65, default-on since #80)
+### 11.21 Resource name expansion (issue #65; names in the read cache since #286)
 
 `operations.expandResourceNames` (section 7.7) resolves vendor numeric
-resource ids to display names with PER-ID `resources.get` reads ONLY.
-Its channel is `resourceNameCache: { ttlMs?, maxEntries? }` — ON by
-default (issue #80: absent builds the default instance, 1 h / 1024
-entries); `resourceNameCache: false` is the uncached per-id path,
-bit-for-bit (per-call de-duplication is unconditional).
-
-**The channel** (`src/resourceNameCache.ts` — a THIRD cache channel
-beside `cache` and `fieldCache`; a separate channel, NOT shared with
-either):
-
-- **Key space**: `resources:<id>` (the canonical id). Disjoint from the
-  ReadCache (wire-PATH keys) and the FieldCache (`resource:kind` keys —
-  the closed three-kind metadata set). The namespace leaves a documented
-  path to future FK tables — v1 serves `resources` only.
-- **What is stored**: exactly the two deterministic vendor answers — the
-  resolved name `{ name, blind: false }` and the vendor's TRUE not-found
-  blind marker `{ name: null, blind: true }` (the issue-#36
-  absent-marker precedent: a repeat miss costs no wire). A 200 WITH a
-  record but NO name part is NOT stored (a transient partial record
-  must not stick for the whole TTL). A FAILURE is never cached
-  (a fault rejects before any `set` can run).
-- **In-flight de-duplication**: concurrent callers for the same id share
-  ONE wire request (the promise is dropped on settle, success OR
-  failure — the fieldCache two-armed pattern).
-- **Cap / TTL**: `ttlMs` an optional positive integer, default 1 h (fail-closed
-  `AutotaskConfigError`); `maxEntries` default 1024
-  (`RESOURCE_NAME_CACHE_MAX_ENTRIES`); past the cap → purge expired
-  first, then evict the oldest-inserted (lazy purge on read).
-- **Scoped invalidation**: a real write to the `resources` resource
-  through the same client (a rename via this client) clears the channel;
-  a write to ANY OTHER resource never invalidates (it says nothing about
-  names — the fieldCache "an ordinary record write never invalidates"
-  rule, scoped variant). The existing ReadCache all-write clear is
-  UNCHANGED.
-- **Coexistence with the ReadCache** (when BOTH are configured): the
-  op's per-id `get` rides the ReadCache transparently (a ReadCache hit
-  inside its TTL costs zero wire and the name is then stored in the name
-  cache — double layering, disjoint key spaces). A `resources` write
-  clears BOTH; a write to another resource clears only the ReadCache. A
-  `fresh: true` call bypasses BOTH channels and refreshes both (the
-  per-id GET fetches live — issue #77: a rename made elsewhere is served
-  on the very next fresh call, never a stale snapshot).
-- **Zero interaction with the #64 field-cache surface**: `FIELD_CACHE_KINDS`
-  stays the closed `['info','fields','udf']`; the fieldCatalog bag, its
-  honesty wording and the `changeStatus` live guard and its
-  `getFieldInfo` path are bit-for-bit untouched. The only shared code is
-  the `http.request` completion hook, which gains ONE
-  scoped-invalidation line (the fieldCache drift block and the readCache
-  all-write clear are unmodified).
-- **NO new row in `src/cache-ttl-tables.ts`** (stated so the absence is
-  not hunted): the artifact's row set is pinned at exactly one row per
-  PLAN RESOURCE, and issue #65 adds a plan OPERATION, not a plan
-  resource. The rows — including `resources: 300000`, the ReadCache
-  per-resource TTL REFERENCE for `resources.get` record reads — are
-  unchanged; the name channel's TTL is the operator's
-  `resourceNameCache.ttlMs`, not the table's row. Only the artifact's
-  `planHash` header line re-stamps (the plan bytes move).
-
-**Staleness contract**: a resource renamed OUTSIDE this client (the UI,
-another integration) serves its old name until `ttlMs` expires (or a
-local `resources` write clears the channel) — the exact staleness trade
-every house cache documents ("a cached read is a snapshot AT FETCH
-TIME"). A `fresh: true` call closes the gap immediately: it bypasses
-BOTH the name cache and the ReadCache and refreshes both, so the rename
-is served on the very next fresh call (issue #77).
+resource ids to display names with PER-ID `resources.get` reads ONLY. The
+names live in the record cache (section 11.15), not a channel of their own:
+a resolved id is the cached `/V1.0/Resources/{id}` record, and the vendor's
+true not-found is the same not-found marker the composite FK reads store
+(`contextAbsentKey`), so a repeat id (resolved OR blind) inside the TTL costs
+zero wire. A failure is never cached. Any real write through the client
+clears names with the rest of the record cache; a rename made elsewhere
+shows up once `cache.ttlMs` expires, or at once with `fresh: true` (the
+per-id GET fetches live and refreshes the entry, issue #77). `cache: false`
+is the uncached per-id path; per-call de-duplication is always on.
 
 **Per-part projection (issue #200)**: `companies.fullProfile` accepts
 `fields?: { locations?, contacts?, notes?, projects?, openTickets? }` — each a
@@ -3505,10 +3306,9 @@ output is byte-identical) + `maxNameReads?: number` (default 20,
 lowerable, never raised). With `names: true`, the siblings ride the
 EXISTING default-on channels — no new cache: resource ids (creator /
 owner / lead / the time-entry resource) resolve through
-`operations.expandResourceNames` (name cache → ReadCache → one wire read
+`operations.expandResourceNames` (read cache → one wire read
 per distinct uncached id); record-FK names (role / billing code /
-contract) ride the per-resource single-record gets (ReadCache, the
-per-resource TTLs, the #36 absent-marker contract untouched); the CLOSED
+contract) ride the per-resource single-record gets (the record cache, the #36 absent-marker contract untouched); the CLOSED
 picklist scope (owner-approved list: the ticket fields
 `status` / `priority` / `ticketType` / `issueType` / `subIssueType` /
 `source` / `queue` ONLY — project / company picklists stay label-less)
@@ -3528,7 +3328,7 @@ rows and the reason rows.
 
 **AC mapping**: AC1 (opt-in; the explicit-`false` output unchanged) —
 the op is invoked only on request and the channel is default-on (issue
-#80; `resourceNameCache: false` keeps the uncached per-id path
+#80; `cache: false` keeps the uncached per-id path
 bit-for-bit — the explicit-`false` pins are that proof). AC2 (each
 distinct id fetched at most once per cache lifetime) —
 per-call de-duplication is ALWAYS on (zero-config); with the channel
@@ -3541,10 +3341,8 @@ only wire verb is the per-id GET; the module imports no query builder
 (static guarantee) and the tests assert METHOD + PATH on every wire
 call.
 
-Pins: `test/operations/expandResourceNames.test.ts` (11 pins — the plan
-row's `tests[]`) + `test/resource-name-cache.test.ts` (7 pins — the
-class unit + the client-option wiring + the scoped invalidation; mock
-wire only, synthetic data, no vendor wire).
+Pins: `test/operations/expandResourceNames.test.ts` (the plan row's `tests[]`)
+and `test/resources/cache-write-invalidation.test.ts` (mock wire only).
 
 ### 11.22 Timezone-anchored date windows for billing items and invoices (issue #66)
 
@@ -4154,8 +3952,8 @@ keys of `operations.aggregate`, and the found records of `operations.fetchMany`
   invoke `<resource>.query` op when the summary matters.
 - Opt out per call: `names: false` (query bag key, aggregate opts, fetchMany /
   fetchByIds opts). A non-boolean `names` is refused pre-request.
-- Caches: picklists ride the fieldCache, staff names the resource name cache,
-  record names the ReadCache (all default-on; invalidated as documented in §3 —
+- Caches: picklists ride the field cache, staff and record names the record
+  cache (all default-on; invalidated as documented in §3 —
   a write through the client clears the affected resource's entries, TTL
   otherwise). A warm call costs zero extra vendor calls; a cold one costs one
   field-metadata GET for the resource plus one GET per distinct uncached id.