node-autotask 0.8.3 → 0.10.0

package/docs/API.md

@@ -37,7 +37,7 @@ const autotask = new AutotaskClient({
   // maxRetries: 3,
   // maxConcurrent: 10,
   // rateLimit: { perHour: 10_000 },   // perHour: null = explicitly disabled
-  // resolution: { maxScanRecords: 500, maxScanPages: 4 },
+  // resolution: { maxScanRecords: 500, maxScanPages: 4, scanOnMiss: false },
   // logger: console,
   // onAudit: (event) => { /* one event per completed request */ },
 });
@@ -117,8 +117,9 @@ server; a blank 2xx on a call that expects a result; `details = { httpStatus,
 method }`) — both classified and documented in section 2.1.
 `isDeterministicVendor500(entries)` (over the `parseVendorErrors` output) is
 the documented HEURISTIC phrase matcher for deterministic vendor
-field-validation 500s (`exceeds maximum length` to start — it holds only
-wording seen in real responses): it drives the transport's no-retry decision
+field-validation 500s (`exceeds maximum length`, `Missing Required Field` and `Value does not
+exist for the required field` — it holds only wording seen in real responses; the last two were
+live-verified on `company_notes.create`): it drives the transport's no-retry decision
 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`
@@ -144,7 +145,13 @@ served payload verbatim).
 `buildFilter(conditions)` wraps caller conditions (multiple top-level
 conditions are `and`-wrapped); `validateFilter` enforces the vendor caps
 (section 5 below). `buildQueryRequest` produces the `QueryModel` wire body
-(`{ MaxRecords, IncludeFields?, filter }`).
+(`{ MaxRecords, IncludeFields?, filter }`). `normalizedConditions` is the
+shared filter-shape gate of the query family (every query-family entry
+point routes through it pre-request): the `filter` param accepts a
+conditions array or `{ filter: [...] }`, and `undefined`/`null` are the
+unfiltered call; any other defined shape is REFUSED pre-request with a
+typed `AutotaskConfigError` (zero wire) — never silently dropped.
+
 
 ### 1.8 `logger.ts` + `utils/`
 
@@ -196,6 +203,8 @@ status → what the vendor does that triggers it.
 |-------|------|----------|--------|----------------|
 | `AutotaskError` | `AUTOTASK_ERROR` / `HTTP_<status>` | server | unmapped | any non-mapped HTTP status |
 | `AutotaskConfigError` | `CONFIG_ERROR` | validation | — (client-side) | fail-closed constructor validation; unknown `invoke` operation; cross-mode `invoke` refusal (the mode tools); bad zone/baseUrl; missing client accessor |
+| `AutotaskConfigError` | `LATEST_THRESHOLD_UNRESOLVED` | policy | — (no call beyond the 64 count probes) | `queryBounded latest`: the id-threshold count probes exhausted the 64-call budget without resolving a window — `suggestedAction` names the date-window narrowing (issue #59) |
+| `AutotaskConfigError` | `LATEST_WINDOW_INCOMPLETE` | policy | — (the walk refuses to continue) | `queryBounded latest`: the walk truncated (the limit with a live next cursor, or the 1000-page guard) — a truncated enumeration's top-N-by-id is unprovable, so the op refuses instead of a possibly-wrong answer — `suggestedAction` names the date-window narrowing (issue #59) |
 | `AutotaskNetworkError` | `NETWORK_ERROR` | network | — | `fetch` failure (DNS, connection reset) — retryable |
 | `AutotaskTimeoutError` | `TIMEOUT` | timeout | — | whole-call budget (`timeoutMs`) exceeded — retryable |
 | `BadRequestError` | `BAD_REQUEST` | validation | 400 | malformed request/filter; the vendor body's field errors are parsed into `vendorError` |
@@ -210,7 +219,7 @@ status → what the vendor does that triggers it.
 | `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; idempotent methods retry per policy, a write makes ONE call — 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) |
-| `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`); a cap-tripped bounded client scan (never a silent `null`); a numeric-id miss |
+| `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`); 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 |
 | `StaleObjectError` | `STALE_OBJECT` | conflict | — | the caller-supplied `lastModifiedDate` no longer matches the vendor's current value (no `If-Match`/ETag exists) |
@@ -319,8 +328,8 @@ upstream call (it breaks out before the retry decision — the parsed body is
 already in hand at the retry site), and the mapped error keeps the
 `ServerError` class + `SERVER_ERROR` code + status 500 but carries
 `retryable: false`, `details.deterministic: true`, and a deterministic
-`suggestedAction` naming the resource's `getFieldInfo` (the field catalog
-with `maxLength`). Any other 5xx body is byte-identical to before (retried
+`suggestedAction` pointing at `operations.fieldCatalog` (the field catalog
+with types, required and `maxLength`). Any other 5xx body is byte-identical to before (retried
 per policy, `retryable: true`) — the phrase list is a heuristic over wording
 seen on real responses; widen it only with new live evidence.
 
@@ -364,10 +373,12 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
 | `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 |
 | `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` | off | — | `{ ttlMs, perResourceTtlMs? }` opt-in read-through cache for get-by-id and `resolve` (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 (and an absent map) falls back to `ttlMs` (absent map = bit-for-bit the pre-#32 behaviour); the plan-derived default table `DEFAULT_PER_RESOURCE_TTL_MS` (`src/cache-ttl-tables.ts` — reference class 1h vs default class 5min) is a reference for building the map, never applied implicitly (section 11.15) |
-| `fieldCache` | off | `maxEntities` 256 | `{ ttlMs, maxEntities? }` opt-in live field-metadata channel for the entityInformation trio (`getEntityInfo` / `getFieldInfo` / `getUdfInfo`) — see section 11.14. With it unset 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 |
+| `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) |
 | `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) |
@@ -526,11 +537,16 @@ List reads are `GET|POST /V1.0/<E>/query` returning the pinned envelope:
 
 ```json
 { "items": [ "<Model>", ... ],
-  "pageDetails": { "count": 10, "requestCount": 1234,
-                   "prevPageUrl": null, "nextPageUrl": null } }
+  "pageDetails": { "count": 10, "requestCount": 10,
+                   "prevPageUrl": null, "nextPageUrl": "<cursor>" } }
 ```
 
-`requestCount` = total matching records; `count` = records on this page.
+`count` = records on this page. `requestCount` is NOT a match count: the
+vendor echoes the `MaxRecords` the request asked for (500 when omitted) —
+live-verified: `MaxRecords: 5` over 13,220 matches → `requestCount: 5`; a
+zero-match page with `MaxRecords: 10` → `requestCount: 10`. The vendor
+publishes no total on a page; the only authoritative total is `count()`
+(`POST /V1.0/<E>/query/count`). Whether more rows exist is `nextPageUrl`.
 Single-record reads (`GET /V1.0/<E>/{id}`) and count/entityInfo reads never
 carry paging parameters.
 
@@ -539,8 +555,12 @@ carry paging parameters.
   later pages POST the preserved filter to the ABSOLUTE `nextPageUrl`, rebased
   to the client base URL (same-origin cursors verbatim; cross-origin re-based —
   the node's custom-zone behaviour).
-- `Page<T>`: `{ items, page (1-based), pageSize, requestCount, hasMore
-  (nextPageUrl !== null), totalPages (ceil(requestCount / pageSize)) }`.
+- `Page<T>`: `{ items, page (1-based), pageSize, requestCount (the vendor
+  value verbatim — the MaxRecords echo, not a total), hasMore (nextPageUrl
+  !== null), totalPages }`. `totalPages` is the pages KNOWN so far —
+  `page + 1` while `hasMore`, else `page` (`page - 1` for an empty page after a full one; 0 for an empty result): a lower
+  bound mid-walk, exact on the last page. For a real page count use
+  `totalPagesFor(await r.count(filter), pageSize)`.
 - **Auto-stop** on a short/empty page (or a null cursor, which is `hasMore:
   false`).
 - **1000-page guard:** a walk that would fetch a 1001st page throws
@@ -563,6 +583,72 @@ carry paging parameters.
   when the limit or the guard truncated the walk and more records exist past
   the stop point; `pageDetails.count` is never surfaced (it is the current
   page's record count — `<resource>.count` is the total).
+  - **`latest: N` (issue #59) — the N highest-`id` rows without caller paging.**
+    The vendor has NO sort parameter (the vendored spec's `QueryModel` is
+    exactly `maxRecords` / `includeFields` / `filter`), so `latest` is a
+    COUNT-ANCHORED mechanism — the `id` primary key is the only order the SDK
+    can prove, and `id` rides every row (the `includeFields` id-append,
+    section 5 — `latest` DEPENDS on it). ONE rowless count probe decides the
+    mode: `C <= 2500` → the walk of the matching set is COMPLETE (1 count +
+    ≤5 walk pages, wire `1 + ceil(C/500) <= 6`, independent of table size) —
+    all `C` rows are collected, sorted id-descending, and the top `N`
+    returned (a set of `C < N` returns itself); `C > 2500` → a full walk
+    would be truncated and could not prove "highest id", so the SDK finds the
+    smallest id threshold `T` with `count(F ∧ id gt T) <= N` by exponential
+    bracketing + binary search (ONE rowless count call per probe; the total
+    budget is 64 probes — exhaustion throws the typed
+    `LATEST_THRESHOLD_UNRESOLVED`) and walks the window `F ∧ id gte T`
+    (≤6 pages) — the window holds exactly `N+1` rows (ids are unique primary
+    keys), so its top `N` ARE the `N` highest overall. `hasMore` is `false`
+    on a complete `latest` answer (complete FOR THE REQUEST — the table may
+    hold more rows; `<resource>.count` is the total). On a plan-pinned BLIND
+    surface the count cannot be trusted (a blind 0 proves nothing): the walk
+    runs up to `limit` (default 500) instead — a completing walk returns the
+    sorted top-N WITH the blind-surface sentinel stamp (the "highest id"
+    claim is scoped to the caller-visible enumeration), and a TRUNCATED walk
+    (the limit reached with a live next cursor, or the 1000-page guard)
+    throws the typed `LATEST_WINDOW_INCOMPLETE` — a truncated enumeration's
+    top-N-by-id is unprovable, so the op refuses instead of returning a
+    possibly-wrong answer. Both refusals carry a `suggestedAction` naming the
+    escape hatch: narrow with a **date window in `filter`** (or a smaller
+    `latest`) so the matching set fits the `limit` / the 2500-row full-set
+    mode — a date window is never REQUIRED, it is the natural narrowing that
+    makes everything cheap. `limit` and `latest` may coexist only when
+    `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).
+  - **`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
+    (notes/descriptions/UDF prose — the generated
+    `UNTRUSTED_FIELDS_BY_RESOURCE` set, the SAME plan column the
+    registry's `metadata.untrustedFields` channel stamps and the server
+    wraps). Each capped value becomes the first `N` chars + the explicit
+    marker `… [+N chars truncated]` (N = chars removed; deterministic —
+    no timestamps). The truncation runs at result-build — BEFORE the
+    server-side untrusted wrapper (the src/untrusted.ts contract: the
+    caller truncates first, then wraps; the marker rides INSIDE the value,
+    so the wrapper wraps the truncated value + marker) — and is
+    response-side only (zero wire). ABSENT = the raw, untruncated result
+    bit-for-bit; the additive `noteCharsTruncated` result field counts the
+    truncated fields and is present ONLY when > 0. The cap is
+    query-verb-ONLY (`queryAll` / `count` bags are unchanged; the raw
+    `.query()` walker is uncapped — section 8's `queryBounded` is the MCP
+    query surface the issue targets).
+  - **`fieldsPreset: name` (issue #61) — the closed includeFields
+    presets.** The named preset is resolved PRE-WALK to its `includeFields`
+    list (the vendor's own column selection rides the existing `IncludeFields`
+    wire path; `id` is always appended by the id-append — zero extra wire).
+    v1 ships the one preset the issue names: `billing_join` on
+    `billing_items` (the 14 join/measure columns — section 11.23). The
+    closed-bag refusals are pre-request (zero wire): unknown preset name
+    (the valid names are named), preset/resource mismatch (the preset and
+    its resource are named), and `fieldsPreset` + an explicit
+    `includeFields` in the same bag (both are named — no silent
+    precedence). The preset FIELD EXISTENCE is verified against the LIVE
+    field catalogue (the live-smoke check — the review correction's
+    mandate; the vendored spec is a non-authoritative guard only), not
+    against `MODEL_FIELD_SETS`.
 - Raw SDK reads are unchanged: `queryAll` (deterministic plain `T[]`,
   unbounded, 1000-page guarded) and `query` (stream, `for await ...`). The
   MCP surface steers the caller to the bounded `query` op; `queryAll` is for
@@ -585,8 +671,23 @@ Vendor filter structure (swagger `Filter`, recursive):
   contains, exist, notExist, in, notIn` + grouping `and`, `or`. **There is no
   `not` grouping operator** (G1 pinned): negation is expressed with
   `noteq`/`notExist`/`notIn`.
+- `gt` / `gte` / `in` on `id` are the SDK's own paging/threshold mechanism:
+  the `queryBounded` `latest` opt-in (section 4) probes and walks `id gt` /
+  `id gte` count windows, and the vendored spec's own `QueryModel` example is
+  exactly an `id gt` filter — the vendor-side acceptance across zone versions
+  is a maintainer live-smoke check (the SDK never assumes page order).
 - `buildFilter(conditions)` wraps the caller's conditions; multiple
   top-level conditions are `and`-wrapped (the node's behaviour).
+- **Refusal, not silent drop (issue #76):** the query-family `filter`
+  param accepts a conditions array (`FilterCondition[]`) or
+  `{ filter: [...] }`; `undefined`/`null` are the unfiltered call
+  (`[]` is the vendor-accepted no-filter wire shape). Every other defined
+  shape (a bare condition object, a bare group object, an object missing
+  the `filter` field, a string, a number) is REFUSED pre-request with a
+  typed `AutotaskConfigError` — zero wire — at every entry point (query,
+  queryBounded, cursor pages, count): a non-conformant filter is never
+  silently dropped into an unfiltered query. The gate is the shared
+  `normalizedConditions` (query.ts), so no entry point can drift.
 - **Vendor caps (`validateFilter`):** <= 500 OR-conditions; <= 1 UDF filter
   per query (`udf: true`); field length <= 128; description length <= 2000.
 - **GET vs POST:** the API caps the GET `search` JSON string at **2048 URL
@@ -595,7 +696,10 @@ Vendor filter structure (swagger `Filter`, recursive):
   serialized GET URL — over 2048 it throws `QueryTooLongError` (never a
   silent degradation).
 - `includeFields` passes through vendor column selection; the SDK never
-  invents column selection.
+  invents column selection — one exception: when `includeFields` is set the
+  SDK always appends `id` (the vendor omits `id` from a row unless it is
+  named in the selection, and every caller needs the id to act on the row —
+  issue #59).
 
 ## 6. Mutation safety
 
@@ -667,8 +771,8 @@ resource's `resolve` with the SAME identifier. Unlike single-resource
 `resolve`, **a miss does NOT throw**: the result lists per-resource
 candidates and the error code when a resource could not resolve (empty
 `candidates` = no match). Bare-value order per resource: numeric id, then
-the primary text field, exact match only; the bounded client-scan fallback
-(and its truncation cap) apply per resource. Returns
+the primary text field, exact match only; with `resolution.scanOnMiss` the
+bounded client-scan re-check (and its truncation cap) applies per resource. Returns
 `{ identifier, results: [{ resource, value, resolutionCost, scanned,
 scanTruncated, candidates, error? }], matches }`.
 
@@ -743,7 +847,7 @@ be cross-mode-refused.
 whose MCP annotation is `readOnlyHint !== true` — today exactly **254
 tools**: the 252 dedicated write/delete tools (198 `effect=write` + 54
 `effect=destructive`, every one of them has a dedicated tool) +
-`autotask_write` + `autotask_delete`. The remaining **571 tools** (the 558
+`autotask_write` + `autotask_delete`. The remaining **600 tools** (the 587
 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
@@ -817,6 +921,175 @@ const applied = await recovery(client, { resource: 'configuration_item_dns_recor
   Pinned by `test/operations/recovery.test.ts` (11 tests) + the full-surface
   governor suite (`test/operations/invoke-modes.test.ts`).
 
+### 7.6 `fetchMany(client, items, opts?)` / `fetchByIds(client, items, opts?)` — bulk fetch by ids
+
+Two cross-resource bulk reads with per-item typed results — one entry per
+input occurrence: `{ resource, id, found, value, error?: { code, httpStatus?,
+message } }`; a NOT_FOUND or fault on one item never aborts the rest; the
+result is `{ results, ok, failed }`. Both refuse pre-request (zero wire):
+non-numeric string ids (pointing at `autotask_resolve_any` — canonical
+integer strings above 2^53 pass with their exact digits), parent-scoped
+children (their `get` needs `parentId`), unknown `fields` keys (the complete
+problem list in one message), unsafe number ids (the canonical-string
+pointer). The op never fabricates rows: values come only from a vendor 2xx
+(query row or GET record); a miss is a typed outcome, never a null-padded
+row.
+
+- **`fetchMany`** — up to 20 items (mixed resources; the pinned
+  `FETCH_MANY_MAX_ITEMS`; over → `CONFIG_ERROR` pre-request, zero wire),
+  one sequential GET per item. Per-item `fields?: string[]` is a client-side
+  projection (the GET returns the full model; projection is post-fetch, zero
+  extra wire).
+  **Live field validation (opt-in `opts.liveFields`, issue #66)**: when
+  `true`, each item's `fields` validate against the tenant's **live** entity
+  field metadata (the existing cached metadata channel — with
+  `fieldCache` configured a warm cache costs zero wire; a cold run is one
+  `entityInformation/fields` GET per DISTINCT resource in the batch) instead
+  of the vendored-spec field set alone. A resource whose metadata is
+  unavailable (network fault, vendor 5xx) falls back to the vendored-spec
+  set for THAT resource only — unavailability never throws and never blocks
+  the batch. When available the live set is authoritative: a field it lacks
+  is refused even if the spec lists it, and a live field the spec lacks is
+  accepted — a tenant whose live TimeEntry entity exposes `postedDate` (the
+  live record carries it even when the vendored model omits it) may project
+  it once `liveFields: true`; the default spec-only path still refuses it.
+  The default (no `liveFields`) is today's vendored-spec-only validation,
+  bit-for-bit, zero metadata wire. Field discovery in both modes:
+  `operations.fieldCatalog`.
+- **`fetchByIds`** — up to 500 items (mixed resources; the pinned
+  `FETCH_BY_IDS_MAX_ITEMS`; `opts.maxItems` may lower the cap, never raise
+  it; over → `CONFIG_ERROR` pre-request, zero wire). **Query-first**: per
+  resource, the unique ids are chunked at 250 (the pinned
+  `FETCH_BY_IDS_CHUNK_SIZE` — the 250-id `in` condition serializes well under
+  the 8000-char vendor cap, and 250 is a deliberate chunk size well under the
+  500 vendor page max, so each chunk is a single page, no cursor walk) and fetched with one `id in`
+  query per chunk. Every id the chunk query does NOT return is re-tried with
+  a per-item `get` fallback before it is reported — the GET is the authority
+  on every surface, so a blind-surface query-miss is re-verified by the
+  authority read before a NOT_FOUND is served (the fallback is universal, not
+  limited to the plan-pinned blind surfaces). Wire cost: per resource
+  `ceil(uniqueIds/250)` query calls + one `get` per query-missed id — a
+  clean 500-id single-resource batch is **2 wire** (down from 500 sequential
+  GETs); the blind-surface worst case is 2 + up to 500 gets (fetchMany
+  parity, never worse). A chunk-level vendor fault faults every item of that
+  chunk (the chunk's `code`/`httpStatus`) and the remaining chunks still run
+  (input order is preserved across chunks and groups; a duplicate id gets its
+  own entry with the identical outcome over one wire fetch).
+
+### 7.7 `expandResourceNames(client, ids, opts?)` — resource name expansion (issue #65)
+
+The opt-in cross-resource helper that resolves vendor numeric resource
+ids (the `resourceID` values other tables expose WITHOUT names — the
+`resourceID` of time_entries / billing_items / tickets) to display names
+in one call. Wire shape: **one `GET /V1.0/Resources/{id}` per unique id,
+sequentially — no POST, no `/query`, no `id in`** (AC4 by construction:
+the module imports no query builder) — the resources table's count/query
+can be blind to the API user while per-id reads work, so an `id in`
+lookup on a blind table would silently return nothing; the per-id GET is
+the authority read (section 11.2).
+
+- **Input**: `ids: (number | string)[]` — vendor numeric resource ids
+  (safe integers, or the canonical integer string for ids above 2^53 —
+  the exact digits ride the wire URL verbatim). Non-numeric string ids
+  are refused pre-request pointing at `autotask_resolve_any` (the
+  complete problem list in one message, zero wire). Cap 500 per call
+  (the pinned `EXPAND_RESOURCE_NAMES_MAX_IDS`; `opts.maxIds` may lower
+  the cap, never raise it); over → `CONFIG_ERROR` pre-request, zero wire.
+- **Per-call de-duplication** is always on: repeated ids ride one wire
+  fetch; each occurrence gets its own row with the identical outcome.
+- **Per-row** `{ id, name, blind, error? }`:
+  - `name` = composed `firstName [middleName] lastName` (single spaces;
+    the vendor `Resource` model has NO single name field —
+    `suffix`/`initials` excluded; the raw parts via `operations.fetchByIds`
+    with `fields`);
+  - a record FOUND with no name part → `{ name: null, blind: false }`
+    (a vendor data gap — distinct from blind);
+  - a per-id miss (HTTP 404 or `200 item: null` — the vendor's TRUE
+    not-found) → `{ name: null, blind: true }`, the id kept, NO error, NO
+    throw (AC3 — the invisible-table case: at the per-id level the vendor
+    does not distinguish "table invisible to this user" from "record
+    absent", so both are blind);
+  - a transient typed fault (5xx class) → per-row
+    `error: { code, httpStatus?, message }` — never cached, one fault
+    never aborts the remaining ids.
+- **Result**: `{ results (input order, duplicates get identical rows),
+  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).
+
+```ts
+import { expandResourceNames } from 'node-autotask/operations';
+const { results, resolved, blind, failed } = await expandResourceNames(
+  client,
+  [101, 102, '103'], // vendor numeric resource ids (exact digits ride the wire verbatim)
+  { fresh: false },
+);
+```
+
+
+### 7.8 `aggregate(client, operation, filter, opts?)` — generic aggregate/count (issue #62)
+
+One op, two mode families (selected by the `opts` shape — the "one tool plus
+a cheap count" of issue #62). The `operation` is EXACTLY
+`<planResourceKey>.query` — a plan resource WITH a `query` row (the
+capability registry is the closed set; a special op, a `.count` row, or an
+unknown resource is refused pre-request, naming `autotask_catalog` — zero
+wire):
+
+| mode  | when                                        | wire                                                                  |
+|-------|---------------------------------------------|-----------------------------------------------------------------------|
+| `count` | NEITHER `groupBy` NOR `sum`               | ONE `POST /V1.0/<Entity>/query/count` (the vendor count endpoint — no walk) |
+| `group` | `groupBy` given (with or without `sum`)   | the house server-side-paginated `queryBounded` walk (page size `min(500, limit)`; the 1000-page guard) + the client-side fold |
+| `sum`   | `sum` only                               | the same walk + fold (the single empty-key group carries the sums)    |
+
+- **`filter`** = the query-bag filter grammar (section 4: 13 leaf operators +
+  and/or grouping; caps 500 OR-conditions / 1 UDF / 8000 chars; field names in
+  vendor casing via `operations.fieldCatalog`). An empty array / absent = the
+  unfiltered call (the vendor-accepted no-filter shape rides the wire as
+  `filter: []`; that is also the blind-predicate's stamp case).
+- **`groupBy` / `sum`** = exact vendor field names (validated against the
+  resource's vendored field set pre-request — a hallucinated field is a shape
+  error, not a silent fold-miss; the complete problem list in one typed error,
+  zero wire). Non-numeric/absent `sum` values contribute 0 (documented).
+- **`top`** (default 25, clamped 1..100) keeps the top-N groups (descending
+  count; the deterministic group-key order breaks ties). **`limit`** (default
+  2500 = the house `BOUNDED_QUERY_MAX_LIMIT`, clamped down to it) is the
+  total-record cap for the walk modes.
+- **count mode — the blind-count marking:** the S12-C blind-surface sentinel
+  rides through the base `count` wrap (filter-aware: a plan-pinned
+  `unfiltered-blind` surface stamps a 0 ONLY when the call is unfiltered — a
+  FILTERED 0 is a true zero, never a sentinel; a non-zero count is the plain
+  number). Result: `{ mode: 'count', count, blind, blindSurface? }` — a 0 on a
+  plan-pinned blind shape is marked `blind: true` with the typed sentinel,
+  never a silent absence.
+- **group/sum mode — the truncation honesty:** the walk's stamps ride through
+  (`blindSurface` / `emptyReason` on a 0-row walk); `hasMore` = the walk's
+  truncation flag — when true, `groups`/`sums` cover the RETURNED rows ONLY
+  (no silent partial sums); `totalScanned` = the walk's fetched record count;
+  `totalGroups` = the distinct groups found and `groupsTruncated` = `top` dropped some (an absent
+  and an explicit-null group field fold into one group keyed `null`).
+  A mid-walk vendor `429` propagates as the typed `RATE_LIMITED` error (the
+  partial fold is discarded — the error IS the answer). Zero mutating.
+
+```ts
+import { aggregate } from 'node-autotask/operations';
+// the cheap count — one vendor /query/count call (no walk):
+const n = await aggregate(client, 'billing_items.query', [{ field: 'companyID', op: 'eq', value: 30132785 }]);
+// the fold — the group-by the vendor has no endpoint for (bounded walk + client-side fold):
+const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 });
+```
+
 ## 8. Resource surface (128 resources)
 
 <!-- BEGIN GENERATED:api-per-entity -->
@@ -826,12 +1099,12 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|
 | `appointments` | Appointment | entity | extended | no | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_appointment_get |
 | `billing_codes` | BillingCode | entity | extended | no | query, count, get, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_billingCode_get |
-| `billing_items` | BillingItems | entity | extended | no | query, count, get, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_billingItems_get |
+| `billing_items` | BillingItems | entity | extended | no | query, count, get, update, resolve | customRange, getEntityInfo, getFieldInfo, getUdfInfo, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, today, yesterday | autotask_billingItems_get |
 | `change_request_links` | ChangeRequestLink | entity | extended | no | query, count, get, create, delete, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_changeRequestLinks_get |
 | `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, upsertByName | autotask_company_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 |
 | `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 |
@@ -881,7 +1154,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `expense_reports` | ExpenseReport | entity | extended | no | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_expenseReport_get |
 | `holiday_sets` | HolidaySet | entity | advanced | no | query, count, get, create, update, delete, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_holidaySet_get |
 | `holidays` | Holiday | entity | advanced | yes (holiday_sets) | query, count, get, create, update, delete, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_holiday_get |
-| `invoices` | Invoice | entity | extended | no | query, count, get, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo, markupHtml, markupXml, pdf | autotask_invoice_get |
+| `invoices` | Invoice | entity | extended | no | query, count, get, update, resolve | customRange, getEntityInfo, getFieldInfo, getUdfInfo, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, markupHtml, markupXml, pdf, today, yesterday | autotask_invoice_get |
 | `notification_history` | NotificationHistory | entity | advanced | no | query, count, get, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_notificationHistory_get |
 | `opportunities` | Opportunity | entity | extended | no | query, count, get, create, update, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_opportunity_get |
 | `opportunity_attachments` | OpportunityAttachment | entity | extended | yes (opportunities) | query, count, get, create, delete, resolve | download, getEntityInfo, getFieldInfo, getUdfInfo | autotask_opportunityAttachment_get |
@@ -941,7 +1214,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `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, fullContext, getEntityInfo, getFieldInfo, getUdfInfo, openWithNoteAndAssign, slaHealthCheck, summary, timeline | autotask_ticket_get |
-| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | createForResource, createIfNotExists, customRange, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, postedWithin, today, yesterday | autotask_timeEntry_get |
+| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, 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 |
@@ -956,6 +1229,37 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 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
+the contains channel for fuzzy names, abbreviations and family lookups
+(exact match is the resource's `resolve`). The closed opts bag is
+`{ limit?: number (1-500, default 25), includeFamily?: boolean }` — an
+unknown key is refused pre-request (zero wire, the valid keys named). With
+`includeFamily: true` each match gains a `family` block: `parentID` (the
+match's own `parentCompanyID` — zero extra wire: the field is on the
+returned row; `null` when absent), `childIDs` (ONE bounded single-page query
+per match — `parentCompanyID` eq, capped at 50 with the `childIDsTruncated`
+flag when that page came back full with a live next cursor — a short page,
+or a full page with a null cursor, is complete) and `blindNote` (the
+plan-pinned blind-surface caveat: `companies.query` is `unowned-blind` — the
+family, and the search hits themselves, are scoped to the caller-visible
+enumeration — a family is reported as SEEN BY THIS API USER, never as
+complete). Wire cost: 1 (the search) + matches × 1 (the child queries) —
+with the default limit 25 that is ≤ 26 wire; lower `limit` for large
+candidate sets. Default callers (no `includeFamily`) see bit-for-bit the
+existing behaviour (no `family` key on the rows).
+
+**The resolve miss channel (issue #59).** `resolve` is exact match only — a
+complete non-match returns `null` (resolve never widens to contains; the
+resource's search op is the contains-candidates channel). The two resolve
+ERROR outcomes carry a `suggestedAction` naming the channel (generic on the
+floor — for companies it reads `companies.search`): `RESOLUTION_AMBIGUOUS`
+(narrow the identifier to the full exact value, or run the resource's
+`search` — contains match — for candidate records to disambiguate) and
+`RESOLUTION_TRUNCATED` (the unverified miss — the opted-in
+`resolution.scanOnMiss` client scan tripped the caps without completing; retry with a more specific identifier, or
+narrow the search to fewer records — contains candidates: the resource's
+`search`).
+
 ### 8.1 Tasks — scoped mirrors and the out-of-scope task-adjacent entities (QoL note)
 
 `Projects/{id}/Tasks` and `ServiceCalls/{id}/Tasks` are read-only scoped
@@ -1207,8 +1511,8 @@ retrying with the same body fails identically; fix the field instead
 (`src/errors.ts` sets `retryable: true` for `SERVER_ERROR` and for every
 httpStatus >= 500). **Resolution (issue #23):** the *deterministic*
 validation 500 is no longer labelled retryable — a 500 whose `errors[]` text
-matches the documented heuristic phrases (`isDeterministicVendor500`,
-`exceeds maximum length` to start) makes exactly ONE upstream call (the
+matches the documented heuristic phrases (`isDeterministicVendor500`:
+`exceeds maximum length`, `Missing Required Field`, `Value does not exist for the required field`) makes exactly ONE upstream call (the
 transport skips the retry), keeps the `ServerError` class + `SERVER_ERROR`
 code + status 500, but carries `retryable: false`, `details.deterministic:
 true`, and a `suggestedAction` pointing at the field catalog
@@ -1511,6 +1815,23 @@ into one predicted-failure-free attempt.
   re-verified 2026-10-06: 12 unposted rows in the 2026-10-01..06 window —
   also the live evidence for the visibility class: unfiltered query 0 rows,
   windowed read has data).
+- **`truncated` + the `dateWorkedWindow` alias + `tz` (issue #66)** — the
+  result is now `{ items, postedCount, unpostedCount, window, truncated }`:
+  `truncated` is true when the bounded read came back with a live
+  `pageDetails.nextPageUrl` (more matching rows exist; `requestCount` is the
+  MaxRecords echo, not a total, so it cannot carry this signal) —
+  the posted/unposted counts then cover the returned rows ONLY (at most
+  `limit`); re-query with a wider window or a narrowing filter to reconcile
+  the totals. `time_entries.dateWorkedWindow(from, to, opts?)` is the
+  clearer-named alias: the same wire, the same result (incl. `truncated`),
+  its own op identity (plan row / MCP tool
+  `autotask_timeEntry_date_worked_window` / operation label) — the name
+  names the `dateWorked` field the window is on; `postedWithin` keeps its
+  name and default semantics. Both accept `opts.tz` (an IANA zone): the
+  `from`/`to` bounds become the LOCAL calendar days in that zone (from-day
+  start / to-day end, converted to UTC for the wire); omitted `tz` = UTC
+  days, the current behaviour bit-for-bit. The same `tz` opt is on every
+  date-window op — see §11.22.
 - **Drifted-create marker recovery (issue #13)** — where the plan pins a
   `responseDrift` row (the pinned resource: `ticket_checklist_libraries`,
   the W-A7 drift: the vendor answers 200 with a body that is not
@@ -1545,12 +1866,13 @@ 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 (off by default):** `fieldCache: { ttlMs, maxEntities? }` — a
+**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 unset there is no `FieldCache` instance at all and the
+it `false` there is no `FieldCache` instance at all and the
 `getEntityInfo` / `getFieldInfo` / `getUdfInfo` trio is the uncached wire
-path, bit-for-bit. When set, the trio goes through one private helper
+path, bit-for-bit; absent, the default instance is built and the trio
+goes through one private helper
 (`BaseResource.cachedMeta`, beside `cachedGet`) that stores the
 UNWRAPPED value, never caches an EMPTY result (an empty is not an answer
 — a transient vendor hiccup must not become a permanent lie), de-dupes
@@ -1568,7 +1890,9 @@ record write says nothing about the field catalog and never invalidates;
 the TTL is the other expiry path.
 
 **The on-demand op:** `operations.fieldCatalog(client, opts?)`
-(`{ resources?, include?, fresh? }` — default: the five workflow
+(`{ resources?, include?, fields?, labels?, fresh? }` — `fields` filters the
+fields-kind rows to the named fields and reports `unmatchedFields`; `labels`
+adds the picklist labels; default: the five workflow
 resources, `include: ['fields']`; the closed opts bag is documented in
 the registry record). One bounded entityInformation GET per resource ×
 kind; the wire cost `resources × include` is REFUSED pre-request above
@@ -1585,12 +1909,18 @@ a known key without a catalog → `CONFIG_ERROR`, an unknown key → typed
 **Honest scope (stated in the served text AND the result's `honesty`
 block):** the live catalog reports a field's SHAPE — existence,
 requiredness, type, `maxLength`, read-only, queryable, picklist-ness —
-and serves picklist VALUES where the vendor exposes them. It CANNOT
-resolve a picklist VALUE the vendor does not expose to this API user
-(the W-A4 wall — e.g. the attachments `Type` picklist): retrying the
-catalog will not surface a withheld value; that gap is vendor-side. The
-`honesty.picklistValues` field reports `partial` when any served row
-carries exposed values, `unexposed` otherwise.
+as FLAGS and NAMES; without the opt-in `labels: true` it serves no
+picklist VALUES at all. With `labels: true` the projected picklist rows
+(the `fields`-kind and `udf`-kind rows) carry the vendor's exposed
+picklist VALUES — the raw vendor entries `{ value, label, parentValue?, isActive?, ... }` (`value` a string)
+as-is, zero transform; the `labels` result flag names what the payload
+carries; the values ride the same cached channel, zero extra wire. It
+CANNOT resolve a picklist VALUE the vendor does not expose to this API
+user (the W-A4 wall — e.g. the attachments `Type` picklist): retrying
+the catalog will not surface a withheld value; that gap is vendor-side.
+The `honesty.picklistValues` field reports the vendor's WIRE exposure
+(`partial` when any raw row carried exposed values, `unexposed`
+otherwise) — informational, orthogonal to the `labels` opt.
 
 Served as `autotask_field_catalog` (extended tier — the 15-tool core
 surface is untouched; the tool is reachable through `autotask_read` /
@@ -1608,13 +1938,16 @@ 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 (additive; the off-by-default stance stands):** `cache: { ttlMs,
-perResourceTtlMs?: Record<string, number> }` — every value is a positive
-integer, validated fail-closed in `resolveConfig` exactly like `ttlMs`
-(wrong type / non-integer / non-positive → `AutotaskConfigError` at
-construction). With the map absent there is NO behaviour change: every
-resource expires on `ttlMs` (the R-F3a off-by-default contract and the
-existing cache pins stand bit-for-bit).
+**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
@@ -1790,10 +2123,11 @@ config surface, no new ops) and pins the two hazards the issue names:
   the record after the not-found) drops the stale marker and serves the
   record — a record that exists is never reported absent while a live
   positive read of it sits in the cache (pinned). The dry-run parent-
-  exists check shares this mechanism: for a genuinely absent parent it
-  re-derives the same verdict the base wire call would (zero wire when
-  the marker is live), and a positive parent read clears the marker for
-  it too. The
+  exists check does NOT share the marker (issue #80 — with the cache
+  default-on, a stale marker or a stale positive entry would corrupt the
+  verdict): it reads the parent FRESH (bypass + wire), so a vendor 404
+  re-derives the same verdict the base wire call would and a stale marker
+  cannot suppress the read. The
   documented trade: a record created elsewhere may serve 'absent' until the
   marker TTL (or a write through this client lands) — the opt-in staleness
   contract, same trade as the positive entries.
@@ -1801,8 +2135,16 @@ config surface, no new ops) and pins the two hazards the issue names:
   client clears the whole read cache (the existing transport behaviour),
   covering the FK parts and the negative marker together — the "someone
   changed a company name" case.
-- **Off by default stands.** With `cache` unset every composite call is
-  bit-for-bit the pre-#36 wire and result.
+- **Default-on since #80.** With `cache: false` every composite call is
+  bit-for-bit the pre-#36 wire and result; absent, composites ride the
+  default-on read cache (positive entries AND the absent markers).
+
+- **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 —
+  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.
 
 Pins: `test/resources/context-fk-cache.test.ts` (10 pins, mock wire only).
 
@@ -1961,6 +2303,304 @@ 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)
+
+`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).
+
+**Composite wiring (issue #77)**: the full-context composites
+(`tickets.fullContext`, `companies.fullProfile`,
+`configuration_items.profile`, `projects.getContext`) accept an
+additive `names?: boolean` opt (default OFF — the sibling keys are
+ABSENT from every served row and no name/label resolution runs, so the
+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
+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
+picklist scope (owner-approved list: the ticket fields
+`status` / `priority` / `ticketType` / `issueType` / `subIssueType` /
+`source` / `queue` ONLY — project / company picklists stay label-less)
+rides ONE `operations.fieldCatalog` `labels: true` call (zero extra wire
+on a warm fieldCache). The separate name-read budget counts COLD wire
+name reads only (cache hits are free of it); over-budget ids serve
+`name: null, capped: true` on the composite's name row + the top-level
+`truncated` marker — never an error. An unresolvable id serves the blind
+marker (`name: null, blind: true`); a picklist whose values the vendor
+does not expose to this API user serves `null` + the fieldCatalog
+reason row (the #64 W-A4 wall) — never an error. A picklist that IS served but does not
+contain the record's value serves `null` + a different reason row
+(`PICKLIST_VALUE_NOT_SERVED_NOTE`: an inactive or unexposed value) so the two conditions can be
+told apart. The `names` section
+(present on the result EXACTLY when `names: true`) carries the per-id
+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
+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
+configured, a repeat id (resolved OR blind) inside the TTL costs no
+wire; a failure is never cached (the AC governs the cache's stored
+answers, not faults). AC3 (the invisible-table case) — a per-id TRUE
+not-found → `{ name: null, blind: true }`, the id kept, no error, no
+throw, the op RESOLVES with the summary counts. AC4 (no `id in`) — the
+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).
+
+### 11.22 Timezone-anchored date windows for billing items and invoices (issue #66)
+
+The time-entry window helpers pinned their bounds to UTC (the API is UTC)
+while the node computes them in the configured timezone, and billing items /
+invoices had no window helpers at all. Issue #66 makes the zone EXPLICIT and
+additive, and mirrors the family:
+
+- **Two new window families** — the full mirror of the time-entry helpers
+  (the same 12 ops each: `today`, `yesterday`, `last24h`, `last7`, `last14`,
+  `last30`, `last90`, `lastFullWeek`, `lastFullFortnight`, `lastFullMonth`,
+  `lastFullQuarter`, `customRange`):
+  - `billing_items.<kind>(opts?)` — ONE bounded server-filtered query on
+    the billing item's date field **`itemDate`**
+    (`POST /V1.0/BillingItems/query`) → `Promise<BillingItems[]>`;
+  - `invoices.<kind>(opts?)` — ONE bounded server-filtered query on the
+    invoice's date-time field **`invoiceDateTime`**
+    (`POST /V1.0/Invoices/query`) → `Promise<Invoice[]>` (the invoices
+    model has no plain `invoiceDate` — `fromDate`/`toDate` are range
+    fields, not the invoice date).
+- **The zone contract (shared)** — `opts.tz` takes an explicit IANA zone
+  (e.g. `'Australia/Sydney'`); OMITTED `tz` = UTC, the current behaviour
+  bit-for-bit (the regression pin). With a zone, the window's calendar
+  day/period is computed in that zone's LOCAL calendar and converted to UTC
+  for the wire (vendor filter values stay second-precision UTC ISO). DST is
+  handled by inverting local midnights to UTC instants (a local day that
+  gains or loses an hour still pins both boundaries to its TRUE midnights —
+  never clock-hour arithmetic); `last24h` is rolling (`now − 24h → now`)
+  and TZ-invariant by construction. A zone `Intl.DateTimeFormat` rejects is
+  refused pre-request as a typed `CONFIG_ERROR` (zero wire). There is no
+  config-level timezone in v1 (the zone is per-call; a future
+  `config.timeZone` default would be an additive follow-up).
+- **The existing family gains the same opt** — the 12 `time_entries`
+  window ops (incl. `customRange`) plus `postedWithin` and its
+  `dateWorkedWindow` alias accept `opts.tz`
+  with the identical contract, so the whole window family is uniformly
+  timezone-anchored (default UTC unchanged).
+- **Shape and wire** — each op is exactly ONE bounded query (`MaxRecords`
+  1-500, default 25; the `itemDate` / `invoiceDateTime` `gte`/`lte` filter
+  rides the wire), and the result is the plain `items[]` array — no counts
+  (the time-entry family shape).
+
+### 11.23 Free-text caps and includeFields presets (issue #61)
+
+Issue #61 (the library remainder after the server-side split — TSV /
+`output_path` / the untrusted-wrapper opt-out live in the server repo)
+adds two opt-in keys to the bounded-query bag (section 4), both
+query-verb-ONLY and zero-wire or vendor-column-selection-only:
+
+- **`noteChars: N` — the free-text cap.** One integer (>= 1) caps EVERY
+  string value in the resource's untrusted-class free-text fields (the
+  generated `UNTRUSTED_FIELDS_BY_RESOURCE` set — the SAME plan column the
+  projection wraps) to `N` chars + the explicit marker
+  `… [+N chars truncated]` (N = chars removed). Truncation is at
+  result-build, copy-on-truncate (input records are never mutated), and
+  runs BEFORE the server adds its untrusted wrapper (section 12's
+  ordering note). Additive result field: `noteCharsTruncated` (the
+  truncated-field count; present only when > 0). Absent = the raw result
+  bit-for-bit.
+- **`fieldsPreset: name` — the closed preset list.** A preset is
+  `{ resource, fields }` — hand-curated (NOT plan-derived: a curation
+  choice, same class as n8n-mcp.curation.json), resolved pre-walk to the
+  walk's `includeFields` (the vendor's column selection; `id` always
+  appended). The v1 list is CLOSED at the one preset the issue names:
+
+  | preset | resource | fields (14) |
+  |---|---|---|
+  | `billing_join` | `billing_items` | `companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable` |
+
+  `billing_join` is the billing-item join read: the FK columns that join a
+  billing item to its company / ticket / project / time entry / contract
+  service / contract / billing code / expense item, plus the date and the
+  amount fields — the "common narrow read" the issue's example targets.
+- **The live check (the AC test for the presets).** Each preset's fields
+  are asserted to EXIST on the live resource against the LIVE field
+  catalogue (`operations.fieldCatalog` — the entityInformation/fields
+  channel; the #64 fieldCache idiom), NOT against `MODEL_FIELD_SETS`
+  (the vendored-spec projection — a cheap NON-AUTHORITATIVE subset guard
+  only; the spec can lag the live API). The check runs in the live round
+  (`npm run live-smoke` — read-only, one field-catalogue read per preset;
+  a missing field FAILS the run), not in `npm test`. The v1 field list's
+  LIVE existence is verified there — the offline proof is the spec-subset
+  guard only (the review correction's mandate, the `fetchMany.liveFields`
+  live-first idiom).
+- **Refusals (pre-request, zero wire, typed):** unknown preset name (the
+  valid names are named — the closed-set discipline), preset/resource
+  mismatch (the preset and its resource are named), `fieldsPreset` + an
+  explicit `includeFields` (both are named — no silent precedence), and
+  `noteChars` `0` / negative / non-integer.
+- **Backwards compatibility:** both keys are OPT-IN on a closed bag —
+  absent = the pre-#61 path bit-for-bit (the default-path zero-move is
+  pinned by the note-chars sidecar tests). New public exports:
+  `FIELD_PRESETS`, `FIELD_PRESET_NAMES`, `resolveFieldsPreset` and the
+  `FieldsPreset` type (additive; the public-surface gate passes as
+  additive-only). `UNTRUSTED_FIELDS_BY_RESOURCE` and
+  `noteCharsTruncationMarker` are internal. `src/untrusted.ts` is byte-identical
+  (the projection contract is untouched — the cap is a query-path
+  mechanism, not a projection change).
+
+
+### 11.24 The unbilled-work composite and the generic aggregate (issue #62)
+
+Issue #62 adds the two tools the issue names, both additive reads (the 0.9.0
+release carries them):
+
+- **`companies.unbilledWork(id, opts?)` — the unbilled-work composite.** One
+  call for a company's posted-but-uninvoiced work: its billing items (per
+  `source`), the time behind them, the per-ticket rollup, the unposted
+  anti-join section, ex-tax totals + hours, and the billing-vs-time warnings.
+  The join path is the correction's core: **the vendored time_entries model
+  carries NO company field** — the join goes through the company's tickets
+  (`ticketID`) AND the company's projects' tasks (`taskID`; the vendored tasks
+  model carries no companyID/ticketID, so tasks are reached via the company's
+  projects). `source` is the closed 4-set: `posted_uninvoiced` (default —
+  no `invoiceID` — `notExist`, the uninvoiced mark; live-verified that `eq 0` matches nothing), `invoice` (`invoiceID = invoiceId`;
+  the invoice record itself is NOT fetched in v1 — the items already carry
+  invoiceID/itemDate/amounts), `date_range` (`itemDate` window, both dates
+  required pre-request), `tickets` (`ticketID in ticketIds`; the time part
+  additionally joins those tickets directly). `dateFrom`/`dateTo` narrow the
+  `itemDate` window in EVERY source (and `dateWorked` on the time part).
+  `includeParent` (default true) pulls ONE level via `company.parentCompanyID`
+  (dangling → `parent: null`, parent parts empty — NOT an error). Per-part
+  `limit` (default 50, clamped 1..500) = the part's `MaxRecords` + the capped
+  lists (`warnings`, the `unposted` anti-join); each part flags `capped` /
+  `hasMore` + the typed `status` (`ok` / `blind` / `skipped` — the empty
+  join set SKIPS the time query with the honest note; a filtered empty part is
+  a TRUE zero). The unposted section = the fetched time entries whose id is in
+  no fetched billing item's `timeEntryID` (client-side anti-join, zero wire).
+  Warnings: `noTimeEntry` (billing items whose `timeEntryID` is empty/0) and
+  `hourDelta` (billed `quantity` ≠ entry `hoursWorked` — strict: the vendor
+  data is exact decimal hours, any mismatch is real; the epsilon alternative
+  is a one-line change). Totals: `preTax` = Σ `extendedPrice`, `hours` = Σ
+  time-entry `hoursWorked`, `entryCount`, with `totalAmount` / `taxDollars`
+  surfaced alongside (Q2 field choice); the per-ticket rollup and the totals
+  derive from the SAME folded rows (one source of truth). `includeNotes`
+  (default false) + `noteChars` (default 400) cap the note fields
+  (`summaryNotes` / `description`) with the #75 marker BEFORE the server-side
+  untrusted wrapper (section 12's ordering note; section 11.23). **Wire
+  budget: 6 bounded reads without a parent (company get + tickets + projects +
+  tasks + billing + time queries) and 7 with a parent; zero mutating;
+  `includeNotes`/`noteChars`/`rollup` add zero wire.** The join sets are
+  capped at 300 ids per `in` list (sorted, first N) so the serialised filter
+  stays under the 8000-char vendor cap — a company with a huge ticket/task set
+  truncates the JOIN SET (not the results) with a documented part note (Q3:
+  the wire caps refuse the honest alternative; the per-query `limit` is the
+  softer first bound).
+- **`operations.aggregate(operation, filter, opts?)` — the generic
+  aggregate/count** (section 7.8): the count-vs-walk split — the
+  groupBy/sum-absent mode is ONE vendor `POST /query/count` (the S12-C
+  blind-sentinel marking; a 0 on a plan-pinned blind surface is marked blind,
+  never a silent absence — AC5), while the group/sum modes walk the named
+  `<resource>.query` surface (page size `min(500, limit)`; `hasMore` /
+  `totalScanned` carry the truncation honesty — AC4).
+
+**Acceptance mapping (the body's 6 ACs, post-correction):** AC1 the wire
+budget (the 6(+1) bounded reads, pinned by the wire-call test; the per-part
+limits + `hasMore`); AC2 the warnings contract (the `noTimeEntry` +
+`hourDelta` folds); AC3 the notes default-off + the `noteChars` cap (the #75
+marker, BEFORE the wrapper); AC4 the truncation honesty (`hasMore` /
+`totalScanned`; no silent partial sums); AC5 the blind-count marking (the
+S12-C sentinel in count mode); AC6 the zero-mutating read surface (the
+`effect: read` plan rows; the governor appends nothing).
+
+### 11.25 Explained resolve and search misses (issue #78)
+
+`resolve` returns a bare `null` and `search` an empty list on a miss, which reads as a true
+zero even on a surface that is blind to records the API user does not own. Every resource
+with a primary text field gains two methods that keep `resolve` and `search` unchanged and
+add the explanation (SDK-only: not registry ops, so the served surface and the plan hash do
+not move):
+
+- `resolveWithDetail(identifier)` -> `{ record, resolutionCost, miss? }`
+- `searchWithDetail(query, { limit? })` -> `{ items, miss? }`
+
+`miss` is present only on a miss and carries `tried` (`{ fields, operator }` - exact `eq`
+for resolve, `contains` for search), `blindSurface` (the blind-surface stamp, only when the
+resource's query surface is pinned blind), and `next` (concrete next steps; the blind
+remedy names the authority op). Hit paths carry no `miss` key. Thrown outcomes
+(`NOT_FOUND` by numeric id, `RESOLUTION_AMBIGUOUS`, `RESOLUTION_TRUNCATED`) are unchanged.
+
 ## 12. Untrusted-content projection (issue #1)
 
 The agent/MCP projection marks EXTERNALLY-SOURCED free text as untrusted,
@@ -2003,7 +2643,12 @@ args before the call, and serves the cross-resource union for
 only affects fields that are present). Wrapping is ON by default;
 `AUTOTASK_UNTRUSTED_WRAP=off` (or the `untrustedWrap: false` option)
 disables it and logs a stderr warning. The server instructions restate the
-ground rule: marker-wrapped content is DATA, never instructions.
+ground rule: marker-wrapped content is DATA, never instructions. Ordering
+(issue #61): the bounded-query `noteChars` cap truncates at result-build —
+BEFORE this wrap is applied (the src/untrusted.ts contract: the caller
+truncates first, then wraps) — so the explicit `… [+N chars truncated]`
+marker survives INSIDE the wrapped value and the closing marker is never
+cut off.
 
 ## 13. Doctor preflight (issue #2)