node-autotask 0.33.0 → 0.37.0

package/docs/API.md

@@ -270,6 +270,7 @@ status → what the vendor does that triggers it.
 | `DeleteBoundaryError` | `DELETE_BOUNDARY` | policy | — | `operations.recovery` `action: 'delete'` on a resource the vendored spec defines no DELETE for — refused PRE-SEARCH (zero wire; the boundary is the spec-derived plan audit, never a raw vendor 405; issue #9) |
 | `MarkerUnsafeIdError` | `MARKER_UNSAFE_ID` | policy | — | a `operations.recovery` match whose id is beyond `Number.MAX_SAFE_INTEGER` (unaddressable through the typed delete surface) — refused with the typed code, never a silent skip (issue #9, P1) |
 | `RecoveryTruncatedError` | `RECOVERY_TRUNCATED` | policy | — | the `operations.recovery` marker search tripped its match cap (more matches than `limit`) — refused instead of a silent truncation / silent empty (issue #9) |
+| `AutotaskError` | `BUDGET_EXCEEDED` | policy | — (the call that would exceed it is not sent) | `operations.revenueRollup`: the pre-walk estimate exceeds `maxVendorCalls` (refused before any stream; `details: { phase: 'estimate', estimate, budget, suggestions }`) or the counting wrapper reached the budget mid-walk (`phase: 'walk'`; the partial fold is discarded) — `suggestedAction` names the narrowing (issue #234) |
 
 Retryable by contract: `NETWORK_ERROR`, `TIMEOUT`, `RATE_LIMITED`,
 `SERVER_ERROR` (429/5xx) — with ONE exception: a deterministic vendor
@@ -953,6 +954,31 @@ 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).
 
+### Fresh single-record reads (`fresh: true`, issue #250)
+
+A write made ELSEWHERE (another process, the Autotask UI, a client with a
+private cache) does not void this client's read cache, so a read-back can be
+served a snapshot. Every single-record `get` takes a trailing per-call
+`{ fresh: true }` — `client.companies.get(id, { fresh: true })`, parent-scoped
+`client.companyAlerts.get(parentId, id, { fresh: true })` — which skips the
+cache LOOKUP, always issues the wire read and refreshes the entry with the
+response (the default, no option or `fresh: false`, is the unchanged cached
+read). Through the governed path pass `invokeRead(client, 'companies.get',
+[id], { fresh: true })`: `InvokeOptions.fresh` is honoured ONLY on a
+`<resource>.get` read; any other operation, a write, or a non-boolean value
+refuses pre-request (zero wire). It affects the one read only: it never clears
+other entries (unlike `http.readCache.clear()`).
+
+Stale-response safety: the read cache does not coalesce concurrent reads (every
+miss and every `fresh` call issues its own request), so a `fresh` read never
+joins a read that started before a write. A read in flight across a write
+through the same cache (including the pool's shared per-tenant cache, whose
+epoch the write bumps) has its late store discarded, so a pre-write response is
+never re-cached; the in-flight caller itself still receives the response it
+asked for. Not covered: a write on a client whose cache is private (pool
+`sharedReadCache: false`) is invisible to
+the other client's cache — use `fresh` there.
+
 ## 7. Operations surface (`./operations` subpath)
 
 Cross-resource helpers live in `src/operations/` (placement locked —
@@ -1081,13 +1107,13 @@ be cross-mode-refused.
   and the `confirm === <op key>` gate (all 54 deletes; the 3 approval-gated
   writes — inside `autotask_write` too) apply exactly as in `invoke`.
   Pinned by the full-surface suite (`test/operations/invoke/modes.test.ts`:
-  all 1275 ops × 3 modes, zero wire).
+  all 1281 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
 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 **634 tools** (the 621 dedicated read tools + the 10 core read tools + `autotask_read` +
+`autotask_write` + `autotask_delete`. The remaining **635 tools** (the 622 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).
@@ -1484,7 +1510,14 @@ is closed when its label is complete, completed, closed, cancelled, canceled or
 resolved. When the catalog cannot be read, or carries no recognisable closed
 label, the historical id `5` stands in with `source: 'assumed'` and a `note`
 that says so. Passing `excludeStatusIds` reports those ids instead
-(`source: 'picklist'` — an explicit caller choice). No module outside this
+(`source: 'picklist'` — an explicit caller choice). `allowAssumed: false`
+(default `true`, behaviour unchanged) refuses the fallback: an unreadable
+catalog or one with no closed label throws an `AutotaskError` with code
+`STATUS_SEMANTICS_UNRESOLVED` instead of returning `[5]`; the same option is
+accepted by `tickets.forResource` and `companies.fullProfile`, and
+`companies.fullProfile` also takes `excludeStatusIds` (an operator pin reaches
+its `openTickets` part, with no catalog read). In `fullProfile` the throw comes
+at the `openTickets` read, after the company and the four other part reads. No module outside this
 resolver holds a status literal: the move engine's closed-target refusal,
 `companies.fullProfile`'s `openTickets` part and `tickets.forResource`'s
 `openOnly` all call it and carry the disclosure (`closedStatusIds` /
@@ -1499,21 +1532,233 @@ default `both`; the seam is `Tickets.assignedResourceID` for primary and the
 both `id in [...]`-chunked when the link set is large) unioned client-side —
 deliberately not the cross-field grouped `or`, whose live semantics are
 unverified. Result: `{ resourceID, scope, openOnly, tickets, primaryIds,
-secondaryIds, bothIds, counts, capped, unresolvedIds, closedStatus }`, newest
-first by `id` desc, each ticket projected to `id`, `ticketNumber`, `title`,
+secondaryIds, bothIds, counts, capped, unresolvedIds, closedStatus }`, ascending
+by `id`, each ticket projected to `id`, `ticketNumber`, `title`,
 `status`, `assignedResourceID`, `companyID`. `openOnly: true` applies the
 resolved open filter server-side (`status notIn` the closed ids, or a single
 `not-eq` leaf) and re-applies it client-side so a server that ignores the leaf
 cannot widen the answer; `closedStatus` carries the disclosure above.
 `limit` (1-500, default 100) caps the returned tickets — `capped: true` means
-the cap bit, and the link read is capped at 500 rows (`capped` also reflects
-that). `unresolvedIds` lists ids the ticket read did not return (deleted or
-invisible). `excludeStatusIds` overrides the closed set for this call.
+rows were actually left out (the primary read asks for `limit + 1` rows; exactly
+`limit` rows is not capped), and the link read is one 500-row page (`capped` is
+true when the vendor reports a further page; `countOnly` below pages further). `unresolvedIds` lists ids the
+ticket read did not return (deleted or invisible); under `openOnly`, tickets the
+open filter dropped because they are closed are NOT listed (one extra unfiltered
+id read per chunk tells them apart). `excludeStatusIds` overrides the closed set for this
+call.
+
+`countOnly: true` (issue #248) returns counts only, no ticket rows:
+`{ resourceID, scope, primary, secondary, both, open, capped, closedStatus }`
+(typed overloads: `countOnly: true` narrows the return type to
+`TicketsForResourceCountResult`). Every figure counts OPEN tickets (`openOnly`
+and `limit` do not apply). `primary` is the `tickets.count` path with the filter
+`assignedResourceID eq R` and the open leaf, so it equals that call;
+`secondary` is the de-duplicated count of open secondary ticket ids (the link
+table has no status, so the open filter is an ids-only `id in` read per 100
+link ids); `both` is the overlap and `open` the union
+(`primary + secondary - both`). The link read follows the vendor's next-page
+links (ids only, 500 per page) up to 20 pages, so the count is exact below
+10,000 links; `capped: true` means the cap was hit with pages remaining, so
+`secondary`, `both` and `open` may undercount; it is never a silent undercount.
+The secondary read re-applies the open filter client-side, and `limit` is not
+validated (it does not apply). With `scope` `primary`/`secondary` only that side is
+read and `both` is 0.
+
+### 7.14 `revenueRollup(client, opts)` — revenue by dimension, budgeted (issues #234, #235, #236)
+
+One read call answers "revenue for Recurring Service + Fixed Price contracts
+over a window, by account vertical": the registry op `operations.revenueRollup`
+(MCP tool `autotask_revenue_rollup`, tier extended).
+
+- **Scope** (exactly one, REQUIRED — no scope is refused with zero wire):
+  `companyIDs` | `ownerResourceID` (resolved to company ids by one projected
+  `companies` query) | `contractIDs` | `tenantWide: true`. A company scope
+  filters on the LINE's `companyID` (attribution is by the line's company).
+- **Window**: `dateFrom` / `dateTo` (`YYYY-MM-DD`, both REQUIRED, inclusive,
+  whole UTC days, at most 36 months), invoice-date basis.
+  The window is whole calendar days sent to the vendor as bare `YYYY-MM-DD`
+  bounds; that was verified on a tenant ahead of UTC only, and tenants behind
+  UTC are unverified.
+- **Revenue** = Σ `billing_items.internalCurrencyTotalAmount` (ex-tax, internal
+  currency) over the lines of NON-VOIDED invoices (`isVoided eq false`
+  server-side) in the window, folded in integer cents.
+  `includedValue` = Σ(`internalCurrencyExtendedPrice` − total) is
+  informational and never added to revenue. Credits (negative lines) are
+  netted and also reported per row. A line whose `internalCurrencyTotalAmount`
+  / `internalCurrencyExtendedPrice` is missing or null falls back to the
+  local-currency `totalAmount` / `extendedPrice` (as contract profitability
+  does), everywhere those fields are read (revenue, `includedValue`, the
+  non-chargeable class and value); never silently: one
+  `coverage.blindSurfaces` entry gives the count of such lines.
+- **`contractTypes`** (ids or exact labels) default to the live picklist
+  labels that START with `Recurring` or `Fixed` (case-insensitive,
+  `/^\s*(recurring|fixed)\b/i`: `Non-Recurring` does not match); the resolved map is echoed in
+  `coverage.contractTypeMap`. No match is a `CONFIG_ERROR` listing the live
+  labels and ids. `contractCategories` filters the same way, and when given
+  its resolved map is echoed in `coverage.contractCategoryMap` (`{ "<id>":
+  label }`, absent otherwise). A label shared by several live picklist ids
+  selects every one of them.
+- **`groupBy`** (default `['vertical', 'contractType']`): `vertical`
+  (`companies.marketSegmentID`), `contractType`, `contractCategory`,
+  `company`, `month` (the invoice month), `billingItemKind`, and the join
+  dimensions (#235):
+  - `contract` — `{ id, name }` (`contractName` joins the contract fetch).
+  - `lineOfBusiness` — per billing line (`organizationalLevelAssociationID`;
+    no contract-pointer fallback): three batch `id in` fetches (associations,
+    level1s, level2s) give `{ id: associationId, name: level2Name (the Line of
+    Business), division: level1Name }`. Lines without a pointer form their own
+    row `{ id: null, label: 'no LOB assigned' }`, and
+    `coverage.lineOfBusiness = { noPointer: { amount, lines }, note }` carries
+    their amount (LOB figures are floors). A row's `contracts` is "contracts
+    with at least one line in this LOB", so per-LOB counts can sum to more than
+    `totals.contracts`.
+  - `resource` — labour lines only (`billingItemType` Labor / Labor
+    Adjustment, or the FK fallback): `timeEntryID` → time entry → resource,
+    `{ id: resourceID, name: 'First Last' }`. Non-labour lines, and labour
+    lines with no time entry (e.g. an adjustment), are `{ id: null, label: 'n/a' }`.
+  - `billingCode` — `billingCodeID` → billing code `{ id, name }`; a line
+    without one is `{ id: null, label: 'none' }`.
+
+  Each row key is `{ id, label?, name?, division? }`: picklist text in
+  `label`; vendor entity text (untrusted — company, contract, LOB level2,
+  resource and billing-code names) in `name`, and the LOB division (level1
+  name, also untrusted) in `division`. Missing values get their own row
+  (`unassigned`, `uncategorised`, `no LOB assigned`, `n/a`, `none`); a value
+  the picklist does not serve stays id-only and is listed in
+  `coverage.blindSurfaces`. A join id the `id in` fetch does not return is
+  never guessed: the line goes to `coverage.excluded.unresolvedAssociations`
+  (association or its level1/level2), `unresolvedTimeEntries` (time entry or
+  its resource) or `unresolvedBillingCodes`, with its amount. These buckets
+  (and `coverage.lineOfBusiness`) appear only when their dimension is grouped;
+  the line projection grows by `organizationalLevelAssociationID`,
+  `timeEntryID` / the type fields and `billingCodeID` the same way.
+- **Rows** are sorted by revenue descending, then ids; `top` (default 100,
+  max 100) keeps the head and folds the tail into `rowsTruncated`. `totals`
+  always cover every row.
+- **`coverage.excluded`**: voided invoices (count + header amount; under a
+  company / owner scope only the voided invoices whose HEADER `companyID` is
+  in scope; omitted for a `contractIDs` scope, since an invoice header cannot
+  be attributed to a contract, and noted in `coverage.notes`), uncontracted
+  lines, other contract types (per label), other contract categories (per
+  label; a label shared by several live ids is keyed `label (id)`, so ids
+  are never merged) and
+  unresolved contracts / companies (ids the `id in` fetch did not return; an
+  unresolved contract is never counted as uncontracted), each with an amount
+  and a line count. Every line is in exactly one place, so `totals.revenue` +
+  Σ the excluded line buckets = Σ the lines fetched (lines are de-duplicated
+  by id before the fold).
+- **`coverage.zeroTotalInvoices`** `{ count, amount, lines }` is an
+  informational overlay, NOT an excluded bucket: the zero-total invoices in
+  scope (tenant-wide: all; company / owner scope: header company in scope or
+  carrying an in-scope line; `contractIDs`: carrying a scoped line) and the
+  amount / count of their lines. Those lines are still folded into rows or the
+  excluded buckets.
+- **`includeNonChargeable`** (#236, default `false`; when `false` the call,
+  its wire and its output are byte-identical to leaving it out): adds
+  `nonChargeable: { contractCovered: { value, hours, lines }, nonBillable:
+  { value, hours, lines } }` to every row and to `totals`. It is NEVER added to
+  `revenue` / `totals.revenue`. Classes per line: non-billable =
+  `nonBillable` true; contract-covered = billable with
+  `internalCurrencyExtendedPrice` > 0 and `internalCurrencyTotalAmount` = 0.
+  `value` = Σ `internalCurrencyExtendedPrice` (integer cents); `hours` = Σ
+  `quantity` on labour lines, Labor Adjustment (type 2) included (it adjusts
+  labour hours, and `billingLineType` already classes it as labour). The
+  invoiced part comes from the revenue line stream (+ `nonBillable`,
+  `quantity` and the type fields); the uninvoiced part is a second unsliced
+  stream `invoiceID notExist` with `itemDate` in the window (+ the same
+  scope). Uninvoiced lines have no invoice date, so they are windowed and
+  month-keyed on `itemDate` (stated in `coverage.notes`). They are keyed
+  through the same joins (one fetch over both streams, so only ids the
+  invoiced lines did not already need are added); uninvoiced lines that are
+  uncontracted or of another contract type / category are outside the
+  request. A non-chargeable line, invoiced or uninvoiced, whose row cannot be
+  resolved (an unresolved contract / company or a join miss) goes to
+  `coverage.excluded.unresolvedNonChargeable` (amount = Σ value); an invoiced
+  one is also in its revenue excluded bucket. The default `maxVendorCalls` becomes 150 (an explicit
+  value wins; cap 200).
+- **`coverage.reconciliation`**: header `invoiceTotal` vs Σ line `totalAmount`
+  per invoice (tolerance 0 cents; `totalAmount`, so a multi-currency tenant
+  gives no false delta). Tenant-wide it covers every invoice; a company scope
+  covers the invoices whose header company is in scope; a `contractIDs`
+  scope skips it (noted).
+- **Budget** (`maxVendorCalls`, default 90, max 200): every vendor call goes
+  through a counting wrapper. Before any stream the op counts the window's
+  non-voided invoices and the invoiced lines (`itemDate` in the window, a
+  proxy for the lines of those invoices) and estimates
+  `calls so far + 1 (voided; not for a contractIDs scope) + invoice pages + line pages (one per 500-invoice
+  chunk + overflow) + one line count per 500-invoice chunk (the per-chunk line gate) + uninvoiced pages (includeNonChargeable: its count is in
+  "calls so far", ≥ 1 page) + each join's id-fetch chunks`. A join's chunks
+  default to `ceil(min(lines + uninvoiced, invoices) / 500)` (contracts,
+  companies, LOB associations, billing codes); time entries use
+  `ceil((lines + uninvoiced) / 500)` (one per labour line, the labour share is
+  unknown pre-walk); LOB level1s / level2s and resources count one chunk each
+  (small org / staff tables). Over budget it REFUSES with `BUDGET_EXCEEDED`
+  (`details: { phase: 'estimate', estimate, budget, suggestions }`, the
+  message names the narrowings that apply: `maxVendorCalls: N` (while N is
+  within the cap), a later `dateFrom`, a scope, and, when raising the budget
+  cannot help (estimate past the cap), `includeNonChargeable: false`, fewer
+  `groupBy` dimensions, `contractIDs`, or a shorter id list (only for a list of
+  more than one id); at least one suggestion is always present. Only a raised
+  `maxVendorCalls` and a later `dateFrom` carry an estimate: the invoice
+  stream is tenant-wide in every scope and the line stream costs at least one
+  page and one count per chunk of 500 of those invoices, so a scope or shape
+  narrowing does not reduce that part, and when the refusal offers one its
+  message says it may still be refused; when nothing narrower exists the
+  only suggestion is the cap, and it says the call will be refused at that
+  estimate even at the cap). A budget
+  below the sizing overhead (the labels, owner query and count calls that run
+  before the estimate exists: at least 4 calls for the default shape, more with
+  `ownerResourceID`, `includeNonChargeable` or more picklist dimensions) is
+  the same refusal (`phase: 'estimate'`), with `estimate` = that minimum and
+  `suggestions: [{ maxVendorCalls }]`; the full estimate is named once the
+  call is sized.
+  Mid-walk the wrapper throws `BUDGET_EXCEEDED` (`phase: 'walk'`) before the
+  call that would exceed the budget. The wrapper counts LOGICAL requests: the
+  transport retries a 429 / 5xx internally (up to `maxRetries` each) below
+  it, and those retries are not counted in the budget, `vendorCalls` or
+  `tenantHourlyShare`. A 429 propagates as `RATE_LIMITED`. These fail as
+  `INVALID_RESPONSE`: a blind gate count (`reason: 'blind_count'`); the invoice
+  stream, each invoice-chunk line stream and the uninvoiced stream
+  (`includeNonChargeable`) whose DISTINCT ids differ from their gate count
+  (`reason: 'count_mismatch'`, `details.stream` names it: a page that repeats
+  one row and drops another is caught; each line chunk is counted on exactly
+  its stream's filter); and a line whose invoice is not among the streamed
+  invoices (`reason: 'orphan_line'`). Retry on a count race (data that changes
+  mid-walk). A repeated voided header is counted once, but a DROPPED voided
+  header is undetectable (there is no voided count call), so
+  `coverage.excluded.voidedInvoices` is a floor under vendor paging drift. Every fault discards the fold: a result is always
+  complete. `coverage.vendorCalls` is the exact logical-request count (joins
+  included; transport retries excluded); ~50
+  calls for a 12-month tenant-wide report on the reference tenant, ~115 with
+  `includeNonChargeable`. `resource` on 12 months tenant-wide adds ~15-25
+  calls and can refuse at the default 90 (the refusal names N).
+  An `ownerResourceID` that owns more than 100 companies is a `CONFIG_ERROR`
+  after at most one page past the 100th id (the resolution stops there).
+- **Limits**: amounts are rounded to cents per line (`Math.round(x * 100)`)
+  before summing, on the assumption that the vendor sends at most 2 decimals;
+  a 3-decimal amount can drift, and reconciliation (header vs line totals)
+  flags the delta. Non-chargeable `hours` are rounded to hundredths per line
+  before summing. A row that holds only non-chargeable work has revenue 0, so
+  it sorts above rows with negative revenue (net credits). The estimate costs
+  the voided stream as one page and assumes distinct contracts / companies
+  ≤ invoices; a window with more than 500 voided invoices, or (with
+  `includeNonChargeable`) many uninvoiced lines on contracts that never
+  invoiced in the window, can exceed it, and such a call fails mid-walk with
+  `BUDGET_EXCEEDED` (`phase: 'walk'`) rather than returning a partial result.
+
+```ts
+import { revenueRollup } from 'node-autotask/operations';
+const r = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30' });
+// r.rows[0] → { keys: { vertical: { id: 12, label: 'Retail' }, contractType: { id: 7, label: 'Recurring Service' } }, revenue, credits, includedValue, contracts, items }
+const lob = await revenueRollup(client, { tenantWide: true, dateFrom: '2025-07-01', dateTo: '2026-06-30',
+  contractTypes: ['Recurring Service'], groupBy: ['vertical', 'lineOfBusiness'], includeNonChargeable: true });
+// lob.rows[i].keys.lineOfBusiness → { id: 7, name: '<level2>', division: '<level1>' } | { id: null, label: 'no LOB assigned' }
+```
 
 ## 8. Resource surface (135 resources)
 
 <!-- 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 15). 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).
+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).
 
 | resource key | apiEntity | kind | tier | parent | standard ops present | special ops | mcpTool |
 |--------------|-----------|------|------|--------|----------------------|-------------|---------|
@@ -2088,6 +2333,64 @@ own. A match that `get(id)` would return can be invisible to the lookup, so a
 missed dedup can issue a duplicate create; treat dedup there as best-effort
 until the zone is re-verified.
 
+### 11.8a Structured `zoneFacts.quirks` entries (issue #253)
+
+The per-resource `quirks` on the `zoneFacts` block (§11.7) is structured, not
+free text — a `string[]` of campaign prose (dates, tenant names, operator
+advice) cannot ride to a model, but a clean statement + a filterable scope
+can. Each entry (`StructuredQuirk`):
+
+- `kind` — the closed 13-set (unknown kinds fail `capabilities:check`, clause
+  23, listing the valid set): `not-persisted` · `blind-surface` ·
+  `integer-picklist` · `wire-type` · `required-in-body` · `not-in-body` ·
+  `parent-scoped` · `field-constraint` · `vendor-managed-side-effect` ·
+  `cascade-delete` · `access-denied` · `unknown-field-noop` · `capability-note`
+  — four of the set are extensions forced by specific migrated strings:
+  `not-in-body` (the scoped-path-vs-body distinction), `field-constraint`
+  (live-verified VALUE constraints), `unknown-field-noop` (the vendor's
+  silent 200 on unknown fields), and `capability-note` (affirmative
+  capabilities).
+  Adding a kind later = one-line extension of the clause's `QUIRK_KINDS` + a
+  plan comment citing the issue; the clause id stays stable.
+- `ops` — the ops the fact applies to: the closed set `{count, create, query,
+  update, delete, all}` plus the host's own plan `specialOps` (membership
+  against the plan — the set never hard-codes what the plan already declares).
+  A server about to execute `billing_codes.count` keeps exactly the entries
+  whose `ops` include `count`. `archive` is deliberately not in the set (no
+  archive verb in the plan's op vocabulary).
+- `fields` — optional; the specific wire/model fields the fact constrains
+  (no membership check — names like `internalBillingCodeID` are by definition
+  outside the vendored spec).
+- `statement` — the clean model-facing sentence: tenant-neutral, date-free,
+  instruction-free.
+- `evidence` — the verbatim campaign string (the provenance home; frozen and
+  exempt from the hygiene gate — the same standing as `vendorEvidence` on the
+  same surface).
+
+**The clause 23 hygiene gate**
+(`scripts/lib/checks/clause23-structured-quirks.mjs`): a build clause that
+fails when a `statement` carries one of the enforced provenance pattern
+classes — clause 15's `PROVENANCE_PATTERNS` (campaign markers, tenant ids,
+branch names, ISO and short dates, 6+ digit ids, …) plus the #253 overrides
+(`live-verified` / `live-proven` / `proven` / `unproven`, `S9b`-style run
+codes, `UI-only`, `ask the operator|admin|vendor`, `australia-nz`, `node
+rule`, slash dates and month-name dates in both orders, `last`/`next`/`this`
++ a relative unit, ordinals like `the 21st`, `tenant` + a 5+ digit id,
+`cleanup`, and zone codes like `ww29` even mid-token) — or when an entry is
+shape-invalid (unknown kind, an op outside the closed set, an empty
+statement/evidence). The gate is a PATTERN FLOOR: it enforces the listed
+pattern classes; it is not a natural-language guarantee, so a well-formed
+date, tenant name or operator instruction in an unlisted shape can slip.
+`evidence` is NEVER gated. The 2026-10-28 migration replaced the old 11-host
+`string[]` in place: 28 raw strings → 28 structured entries, every old
+string preserved verbatim as its entry's `evidence`.
+
+**Consumer contract** (served via `relationshipMap(k).zoneFacts.quirks`,
+§9.1): filter entries on `ops`, feed `entry.statement` to the model, and
+treat `entry.evidence` with the same trust you already apply to
+`vendorEvidence` on this surface (plan-grade provenance, not model-facing
+prose). The old `string[]` shape is gone.
+
 ### 11.9 Delete-boundary awareness + the one-call recovery (issue #9)
 
 The §11.1 wall (7 live-verified 405 endpoints) is now a **spec-derived
@@ -2238,38 +2541,84 @@ budget or guessing:
 
 ### 11.12 Zone-fact create guidance (issue #12)
 
-**`operations.createGuidance`** (`{ resources? }`) serves the plan's zone
-facts per child resource — ZERO vendor calls: the `createOp` key, the
-parent-scoping, the live-proven prefix, the `unproven` flag, and the
-blocker: `{ kind, message, vendorEvidence? }`. The backing plan table is the
-94-resource `zoneFacts.resources`; the 92 create-guidance rows (the 2
-remaining entries — `billing_codes` / `resources`, the blind no-create
-tables — carry zone quirks only) are drift-guarded by clause 15. The stage-11
-live write campaign's decoded knowledge: 92 create entities with the EXACT required-field sets and
-verbatim vendor error evidence (the 500 field-validation ladders, §11.6),
-the blind FK walls (`referenceField` naming the reference table that is
-blind for this API user — no valid id can be read back), and the 9th kind
-`unknown` for the wall-adjacent rows (e.g. `ticket_checklist_libraries`
-W-A7 drift — the 200 that is not the specced envelope). An agent that reads
-the row before its create attempt converts a multi-iteration vendor ladder
-into one predicted-failure-free attempt.
+**`operations.createGuidance`** (`{ resources?, kind? }`) serves the plan's zone
+facts per create op — ZERO vendor calls: the `createOp` key, the
+parent-scoping, the live-proven prefix, the `unproven` flag, the blocker
+`{ kind, message, remedy, referenceField?, unsatisfiableViaApi?, requires? }`,
+the exact vendor text in `vendorEvidence`, and the spec-derived
+`deleteBoundary`.
+
+**Row counts.** The backing plan table `zoneFacts.resources` has 99 entries;
+97 of them carry a `createGuidance` row — exactly one per plan create op, set
+equality guarded by clause 15 — and the other 2 (`billing_codes`,
+`resources`, the blind no-create tables) carry zone quirks only. Earlier
+revisions of this section quoted 92 or 94; the counts are 99 entries / 97 rows.
+`counts.total` is 97 and `counts.byKind` sums to it.
+
+**Model-facing by construction (issue #246).** `blocker.message` and
+`blocker.remedy` are written for the consumer of the guidance: they carry no
+campaign markers, branch names, W-codes, dates, tenant record ids or
+maintainer instructions. Anything of that kind that is worth keeping lives in
+`vendorEvidence` (entries prefixed `maintainer provenance`), next to the
+verbatim vendor text. Clause 15 fails the build when a message or remedy
+matches a provenance pattern. A consumer that renders a blocker can therefore
+serve `message`/`remedy` as they are.
+
+**Blocker kinds.** The closed set is `ok`, `blind-reference`, `blind-parent`,
+`picklist-unexposed`, `undocumented-ladder`, `resource-role-pair`,
+`delete-absent`, `non-mutable` and `unknown`.
+
+- `delete-absent` is **not** a create blocker. A resource with no vendor
+  DELETE created fine; that is the delete boundary (`deleteBoundary.available:
+  false`, plus the `metadata.deleteBoundary` stamp on the create op). The
+  eight rows that carried the kind (`tickets`, `companies`, `phases`,
+  `company_notes`, ...) are now kind `ok` with the boundary on
+  `deleteBoundary`; the kind is reserved (still accepted by the `kind` filter,
+  0 rows) and clause 15 fails a row that carries it.
+- `non-mutable` **is** a create blocker: the vendor refuses the create write
+  itself for the entity. No row carries it today.
+- `blind-reference` rows always name `referenceField` (the field whose
+  referenced table is blind for this API user), including the contract
+  billing-rule / exclusion / service / bundle rows.
+- `blocker.unsatisfiableViaApi: true` is the structured flag for creates the
+  API cannot satisfy for any input: exactly the `picklist-unexposed` rows (the
+  attachment `Type` picklist) and the `undocumented-ladder` row
+  (`opportunities`). Clause 15 holds the flag and the kind in step.
+
+**Where to read the company (issue #246).** Some resources have no `companyID`
+of their own. `row.parentCompany?: { via, resource, field }` says which parent
+record carries it: `tasks` serves `{ via: 'projectID', resource: 'projects',
+field: 'companyID' }` (read the project, then its `companyID`). The hint is
+derived from the vendored spec (a resource with no `companyID` whose scoping
+parent field points at a parent that has one) and clause 15 requires the plan
+row to equal that derivation, so it cannot drift. A resource with its own
+`companyID` carries no hint.
 
 **Which required set wins (issue #219 N4).** Three sources answer "what does
 this create really require", at different coverage: the live-proven prefix
-(92 rows — the fields a live create actually demanded, in vendor-demand
-order), the hand-authored zone set `createRequiredSet` (6 resources), and the
-vendor field catalog's `isRequired` (the spec opinion — wrong for 68 of the
-75 resources that carry a proven prefix). The precedence is FIXED:
-**live-proven > zone > spec**, and the source is named on the result.
-`effectiveRequiredFields(record, zoneFacts)` in `node-autotask/operations` is
-the only place in the SDK that compares the three; every
-`operations.createGuidance` row carries its result as
-`requiredFields: { fields, from: 'live-proven' | 'zone' | 'spec' }`
-(`contacts.create` → the four live-proven fields, not the empty spec list).
-A value-conditioned prefix (e.g. `contracts.create`'s type-1
-`estimatedRevenue`/`estimatedHours`/`estimatedCost`) is returned whole with
-`from: 'live-proven'` — the condition is typed on the row (see the next
-paragraph), so read it before treating the list as unconditional.
+(the fields a live create actually demanded, in vendor-demand order), the
+hand-authored zone set `createRequiredSet`, and the vendor field catalog's
+`isRequired` (the spec opinion, wrong for most resources that carry a proven
+prefix). The precedence is FIXED: **live-proven > zone > spec**, and the source
+is named on the result. `effectiveRequiredFields(record, zoneFacts)` in
+`node-autotask/operations` is the only place in the SDK that compares the
+three; every `operations.createGuidance` row carries its result as
+`requiredFields: { fields, from, unproven, conditional? }`
+(`contacts.create` returns the four live-proven fields, not the empty spec list).
+
+- `fields` is the **unconditional** set. A field the row gates on a picklist
+  value (`requiresByValue`) is removed from it: `contracts.create` returns
+  `status, contractType, contractName, startDate, endDate,
+  timeReportingRequiresStartAndStopTimes, companyID`, and
+  `estimatedRevenue` / `estimatedHours` / `estimatedCost` appear only in
+  `conditional` (contractType 1 needs all three, 3/4/6/8 need
+  `estimatedRevenue`). **Changed in 0.34.0:** the type-1 triple was previously
+  returned inside `fields`.
+- `conditional?` is the row's `requiresByValue`, copied as typed gates; it is
+  absent when the row declares none.
+- `unproven` is `true` when no live create is known to succeed with the set:
+  the plan row is unproven (the create still failed after the prefix), or the
+  set is only the vendor spec's opinion. It is additive on the result.
 
 **Structured create requirements (issue #219 N3).** The blocker channel is a
 CLASS of wall, not a statement of what the vendor wants; and the campaign
@@ -2305,6 +2654,32 @@ clause that stops this fact from being lost a second time. The create op's
 registry record carries the same typed block as `metadata.createRequirements`
 (the `autotask_describe` channel).
 
+### 11.12a Per-operation caveats (issue #249)
+
+An operation record may carry `metadata.caveats`, an optional list of
+structured facts about the operation itself, served wherever operation
+metadata is (the `autotask_describe` channel, `capabilities.json`,
+`node-autotask/capabilities`). One row shape over a CLOSED kind set:
+
+```ts
+{ kind: 'not-persisted'; fields?: string[]; note: string; remedyOp?: string }
+```
+
+- `not-persisted`: the op accepts the listed `fields` but the vendor does not
+  store them. `fields` is required for this kind; `remedyOp` names the plan
+  operation that does what this one cannot.
+- First rows: `time_entries.update` and `ticket_charges.update` declare
+  `{ kind: 'not-persisted', fields: ['ticketID'], remedyOp:
+  '<resource>.moveToTicket' }`.
+- The kind set is closed at build time: `scripts/generate-capabilities.mjs`
+  throws on an unknown kind or a malformed row, and gate clause 22 also checks
+  that every named field exists on the resource model and every `remedyOp` is
+  a plan operation.
+- Purely additive: `metadata.usage`, `metadata.pointerNote` and every other
+  served field are unchanged, and a record without caveats has no `caveats`
+  key. Unlike `pointerNote`, caveats ride the describe channel only (they are
+  not attached to error details).
+
 ### 11.13 Posted state from billing items (W-D3), `getPosted` / `getUnposted` / `postedWithin`, and drifted-create marker recovery (issues #10/#13/#237)
 
 - **W-D3 (live, ww29, re-verified 2026-10-27)** — this zone's TimeEntry entity
@@ -2325,12 +2700,14 @@ registry record carries the same typed block as `metadata.createRequirements`
   condition is ever sent. The join is one `BillingItems` query per 250 ids;
   the entry read is capped at 500, so a call costs at most 1 read + 2 joins
   and a window with more than 500 entries returns the first 500 with
-  `hasMore` / `truncated` true. A 429 or vendor fault propagates as a typed
+  `hasMore` / `truncated` true and a `nextCursor` to continue from (or use
+  `countOnly` for the window's totals; see the paging bullet below). A 429 or vendor fault propagates as a typed
   error. The API user therefore needs BillingItems read permission; a permission fault propagates as a typed error.
 - **`time_entries.getPosted(opts?)` / `getUnposted(opts?)`** — `opts` is
-  `{ limit?, ticketID?, dateFrom?, dateTo? }` (`dateFrom`/`dateTo`:
+  `{ limit?, ticketID?, dateFrom?, dateTo?, cursor?, countOnly?, maxVendorCalls? }`
+  (the paging options: see the paging bullet below; `dateFrom`/`dateTo`:
   inclusive `dateWorked` days, `YYYY-MM-DD`, never tz-shifted). They return
-  `{ items, hasMore, window, approvedCount, unapprovedCount }` (a breaking
+  `{ items, hasMore, window, nextCursor, unconfirmed, approvedCount, unapprovedCount }` (a breaking
   change from the bare `TimeEntry[]`, 0.32.0): `getPosted` items are entries
   a billing item references; `getUnposted` items are entries none references.
   `approvedCount` / `unapprovedCount` are informational (items with / without
@@ -2343,7 +2720,7 @@ registry record carries the same typed block as `metadata.createRequirements`
   guard forbids Date positionals), one bounded read (`limit` 1-500, default
   500 — the hard cap, issue #128: a larger window needs `time_entries.query`
   with the same `dateWorked` filter, its 2500-row walk cap) returning
-  `{ items, postedCount, unpostedCount, window, truncated }`; the counts come
+  `{ items, postedCount, unpostedCount, window, nextCursor, unconfirmed, truncated }`; the counts come
   from the billing-item join (any billing item referencing the entry), `opts.posted` narrows client-side after the join
   (true = posted only, false = unposted only, omitted = both); the counts still split every entry read (before the narrowing), so `items.length` can differ from their sum and `ticketID` /
   `resourceID` narrow the read. Live evidence for the visibility class
@@ -2365,6 +2742,57 @@ registry record carries the same typed block as `metadata.createRequirements`
   but, since 0.24.0, it never shifts the bounds: `dateWorked` is a date-only
   value at 00:00 UTC, so `from`/`to` are the days (see §7.11). The same `tz`
   opt is on every date-window op — see §11.22.
+- **Paging past 500 entries and whole-window totals (issue #242)** — all four
+  ops (`getPosted`, `getUnposted`, `postedWithin`, `dateWorkedWindow`) take
+  three more options:
+  - `cursor?: string` — every rows result now carries `nextCursor: string | null`
+    (the vendor's next-page cursor for the entry read). Pass it back as
+    `opts.cursor` with the **same** window and filters to read the next page;
+    each call stays one entry page (the vendor's continuation page, up to 500
+    entries; `limit` sizes the first page only) plus at most 2 joins. Loop
+    until `nextCursor` is `null` to enumerate a busy window. An off-origin
+    cursor, or a same-origin cursor whose path is not the TimeEntries
+    continuation (`/V1.0/TimeEntries/query/next`), or a cursor longer than
+    2,048 characters, is refused (`RESPONSE_REJECTED`) before any request. Every rows result also carries
+    `unconfirmed: number`: the entries on this page whose billing-item join
+    page was truncated. They are withheld from `items` (getPosted /
+    getUnposted) and from both counts (postedWithin / dateWorkedWindow, which
+    also withhold them from `items` when `posted` is set; with `posted`
+    omitted they stay in `items`, unclassified), so a cursor loop does not
+    see them as posted or unposted; `unconfirmed` is 0 normally, and when it is
+    above 0 `hasMore` / `truncated` is also true. Sum it across a loop to know
+    how many entries went unclassified (or use `countOnly`, which refuses
+    instead).
+  - `countOnly?: true` — returns only the whole window's totals:
+    `{ window, total, postedCount, unpostedCount, vendorCalls, estimate, budget }`
+    (typed overloads select `TimeEntriesPostedCountResult`). One
+    `TimeEntries/query/count` call sizes the window; then every entry page is
+    read ids-only (`IncludeFields: ['id']`, following the vendor cursor) and
+    joined at 250 ids per join, and the window is counted again after the walk.
+    `total` = `postedCount + unpostedCount` (de-duplicated by id). The call
+    fails with `INVALID_RESPONSE` (`details: { reason: 'count_mismatch',
+    streamed, counted, recounted }`) when the distinct-id total equals NEITHER
+    the count before the walk NOR the count after it (a page repeated one entry
+    and dropped another); a total equal to either count is accepted, so a
+    window that grows or shrinks by the time the walk ends still succeeds, and
+    one that changes mid-walk can fail or pass depending on timing: retry.
+    `limit` and `posted` do not apply; `cursor` is rejected with `countOnly`
+    (CONFIG_ERROR).
+  - `maxVendorCalls?: number` — the `countOnly` budget (integer 1-200,
+    default 30). The estimate is `1 + max(1, ceil(n / 500)) + ceil(n / 250) + 1`
+    (the last 1 is the re-count) from the count `n` (the live week of 1,321 entries costs 11). The budget
+    and `vendorCalls` count logical requests; transport retries of a 429 /
+    5xx (up to `maxRetries` each) are not counted. Over budget
+    the call throws `BUDGET_EXCEEDED` (category `policy`, `details: { estimate,
+    budget, total, issued }`, a `suggestedAction` naming a narrower window or
+    `maxVendorCalls >= estimate`) after the count call and before any page
+    read. The same code stops a walk that needs more calls than estimated
+    (more entries than counted, or an extra page such as an empty
+    continuation page) before the call that would exceed the budget, the
+    closing re-count included; its `suggestedAction` names a narrower window
+    or a `maxVendorCalls` above the budget, never `>= estimate`. A
+    truncated join throws `RESOLUTION_TRUNCATED`, and a 429 propagates as
+    `RATE_LIMITED`: the total is complete or not returned.
 - **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
@@ -2462,10 +2890,17 @@ there is no second entity-type table.
 parallel field system, and the served row states it rather than leaving it
 inferred. With the `udf` include, the row's `udf` list holds the UDF
 DEFINITIONS the vendor's `entityInformation/userDefinedFields` channel
-returns — `name`, `label`, `type`, `isRequired`, `isReadOnly`, `isPickList`,
-`isReference`, `referenceEntityType`, `picklistValues` (the values ride the
-`labels: true` opt, zero extra wire), `defaultValue`. A UDF definition never
-appears in the plan artifact (it is tenant-specific). The row also carries
+returns, projected to `name`, `label` (when non-empty), `type`, `isRequired`,
+`isReadOnly`, `filterable: 'udf-marker'`, `isPickList`, `maxLength`,
+`referenceEntityType`, `targetResource`, `targetEnumerable`, and
+`picklistValues` (the values ride the `labels: true` opt, zero extra wire;
+present only for a picklist that exposes values). The vendor's `isReference`
+and `defaultValue` are not projected. A UDF definition never
+appears in the plan artifact (it is tenant-specific). The row's `udfCapable`
+is the plan resource flag (16 resources), which every capability record also
+carries as `CapabilityRecord.udfCapable` (issue #254); every vendor entity has
+a `getUdfInfo` catalog endpoint, so that op's presence does not make a
+resource UDF-capable. The row also carries
 `udfFilter: 'udf-marker'` and `udfWriteShape: 'merge'` exactly when it is
 `udfCapable`: a filter on a UDF NAME is accepted by the vendor only with the
 `udf: true` marker, so a UDF field row serves `filterable: 'udf-marker'` and