node-autotask 0.26.0 → 0.28.0

package/docs/API.md

@@ -930,6 +930,29 @@ rejects the batch once in-flight items settle; `signal` stops new items starting
 `node-autotask/resources` (resource classes) and `node-autotask/types` (entity
 types, type-only) alongside `./capabilities` and `./operations`.
 
+### Pooled clients and the shared read cache (`./pool` subpath, issue #219 N6)
+
+`createClientPool({ maxSize?, idleTtlMs?, factory?, sharedReadCache? })` keeps
+one `AutotaskClient` per credential tuple (`{ get, delete, clear, size }`) so a
+multi-tenant gateway reuses each tenant's limiter state. Each pooled client has
+its own read cache, so a write through one client never cleared what another
+client of the SAME tenant would serve — a post-write read-back routed to a
+re-created client (a `delete(config)` on a 401, an LRU eviction, an idle
+expiry) could return the pre-write snapshot for up to the resource TTL
+(contacts: 5 min).
+
+**Default (shared):** the pool OWNS one `ReadCache` per credential tuple and
+hands it to every client it builds for that tuple (via the `cache.store`
+config seam), so any write through any pooled client of that tenant voids the
+read cache for all of them and a read-back is never served the pre-write
+snapshot. The shared cache outlives a client entry's `delete`/eviction (its
+entries still expire on their own TTL), is pruned at `maxSize` and dropped by
+`clear()`. `sharedReadCache: false` restores per-client caches (then route a
+post-write read-back through the writing client). `cache: false` opts the tuple
+out entirely. `cache.store` is otherwise a plain advanced seam: a supplied
+`ReadCache` instance is used as-is, and `ttlMs` / `perResourceTtlMs` beside it
+refuse (the instance owns its TTLs).
+
 ## 7. Operations surface (`./operations` subpath)
 
 Cross-resource helpers live in `src/operations/` (placement locked —
@@ -1058,13 +1081,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 1214 ops × 3 modes, zero wire).
+  all 1275 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
-whose MCP annotation is `readOnlyHint !== true` — today exactly **256
-   tools**: the 254 dedicated write/delete tools (198 `effect=write` + 56
+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 **608 tools** (the 595
+`autotask_write` + `autotask_delete`. The remaining **631 tools** (the 618
 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
@@ -1077,7 +1100,7 @@ additionally require `confirm === <operation key>` even inside
 `resources.transferOwnership`) require the same confirm inside
 `autotask_write`. Migration: `autotask_invoke` is REPLACED by
 `autotask_read`/`autotask_write`/`autotask_delete` — update harness config
-(approve the 256 above) and remove any `autotask_invoke` entry. The rule is
+(approve the 267 above) and remove any `autotask_invoke` entry. The rule is
 derivable from the registry `effect` column (and the mode tools' fixed
 annotations) — it never needs a hand-maintained name list.
 
@@ -1418,7 +1441,77 @@ notes cannot be deleted, so they never use create-then-delete.
   calendar dates the window covers in that zone and the bounds are whole UTC days of those dates. (Before 0.24.0 a `tz`
   behind UTC, e.g. `America/Los_Angeles`, selected the NEXT UTC day; live-verified 2026-10-23.)
 
-## 8. Resource surface (128 resources)
+### 7.12 `timeEntries.approve` — time-entry approval levels (2026-10-26)
+
+`timeEntries.approve(id, opts?)` records one approval level for a time entry.
+The vendor keeps approvals in a separate entity (`BillingItemApprovalLevels`)
+and, by its own documentation, does not write the approval fields on the time
+entry when that record is created — so the helper is a composite:
+
+1. reads the time entry (also the whole dry run: one GET, zero writes),
+2. `POST /V1.0/BillingItemApprovalLevels` with
+   `{ timeEntryID, approvalResourceID, approvalLevel, approvalDateTime }`,
+3. updates the time entry with the vendor's own workaround —
+   `billingApprovalDateTime` + `billingApprovalResourceID`, one
+   collection-merge `PUT /V1.0/TimeEntries`,
+4. reads the entry back and compares the two fields.
+
+Defaults: `approvalResourceID` = the entry's own `resourceID`, `approvalLevel` =
+1, `approvalDateTime` = now. An entry with no `resourceID` and no caller pin is
+refused before any write.
+
+The result is `status: 'approved'` when the read-back matches, and
+`status: 'approval_fields_not_persisted'` (`persisted: false`) when the level
+record was created but the follow-up fields did not stick. The level id is
+returned either way: the vendor defines no DELETE for
+`BillingItemApprovalLevels`, so the record cannot be rolled back.
+`dryRun: true` returns the pinned envelope for the POST plus the same warning,
+with the single GET as the only wire call.
+
+Posting is not part of the operation (`/V1.0/BillingItems` exposes PUT/PATCH
+only), and the typed TimeEntry model omits the live-only `postedDate` /
+`postedOnTime` fields, so "approved and posted" is only detectable as a vendor
+error from the follow-up update.
+
+### 7.13 Ticket status semantics and per-resource tickets (issues #226 / #225)
+
+`tickets.statusSemantics(opts?)` resolves **which status ids mean closed** in the
+tenant. The closed set is a tenant picklist, not the constant `5`: the resolver
+reads `GET /V1.0/Tickets/entityInformation/fields` through the field-metadata
+cache (`tickets:fields`, the same entry `operations.fieldCatalog` warms, so a
+warm cache is zero wire) and reports
+`{ picklist, closedIds, source: 'picklist' | 'assumed', note }`. A status value
+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
+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` /
+`closedStatusSource`, or the part `note`) in their own output.
+
+`tickets.forResource(resourceID, opts?)` lists the tickets assigned to one
+resource, as primary assignee, secondary resource, or both (the `scope` option,
+default `both`; the seam is `Tickets.assignedResourceID` for primary and the
+`TicketSecondaryResources` link table for secondary). It follows
+`time_entries.recentTickets`: two bounded reads (a `Tickets/query` on
+`assignedResourceID` and a `TicketSecondaryResources/query` on `resourceID`,
+both `id in [...]`-chunked when the link set is large) unioned client-side —
+deliberately not the cross-field grouped `or`, whose live semantics are
+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`,
+`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.
+
+## 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).
@@ -1427,6 +1520,7 @@ 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_item_approval_levels` | BillingItemApprovalLevel | entity | extended | no | query, count, get, create | — | autotask_billingItemApprovalLevel_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 |
@@ -1482,11 +1576,15 @@ 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 |
+| `invoice_templates` | InvoiceTemplate | entity | advanced | no | query, count, get | getEntityInfo, getFieldInfo, getUdfInfo | autotask_invoiceTemplate_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 |
 | `opportunity_categories` | OpportunityCategory | entity | extended | no | query, count, get, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_opportunityCategories_get |
+| `organizational_level1s` | OrganizationalLevel1 | entity | advanced | no | query, count, get, create, update | getEntityInfo, getFieldInfo, getUdfInfo | autotask_organizationalLevel1_get |
+| `organizational_level2s` | OrganizationalLevel2 | entity | advanced | no | query, count, get, create, update | getEntityInfo, getFieldInfo, getUdfInfo | autotask_organizationalLevel2_get |
+| `organizational_level_associations` | OrganizationalLevelAssociation | entity | advanced | no | query, count, get, create, update | getEntityInfo, getFieldInfo, getUdfInfo | autotask_organizationalLevelAssociation_get |
 | `product_vendors` | ProductVendors | entity | extended | yes (products) | query, count, get, create, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_productVendor_get |
 | `products` | Product | entity | extended | no | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_product_get |
 | `project_charges` | ProjectCharge | entity | extended | yes (projects) | query, count, get, create, update, delete, resolve, search | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_projectCharge_get |
@@ -1510,6 +1608,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `resource_time_off_balances` | ResourceTimeOffBalance | entity | extended | yes (resources) | get, resolve | getByResource, getByYear, getEntityInfo, getFieldInfo, getUdfInfo | autotask_resourceTimeOffBalance_get |
 | `resources` | Resource | entity | core | no | query, count, get, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo, transferOwnership, whoAmI | autotask_resource_get |
 | `roles` | Role | entity | extended | no | query, count, get, create, update, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_role_get |
+| `sales_orders` | SalesOrder | entity | extended | no | query, count, get, update | getEntityInfo, getFieldInfo, getUdfInfo | autotask_salesOrder_get |
 | `service_call_task_resources` | ServiceCallTaskResource | entity | extended | yes (service_call_tasks) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_serviceCallTaskResource_get |
 | `service_call_tasks` | ServiceCallTask | entity | extended | yes (service_calls) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_serviceCallTask_get |
 | `service_call_ticket_resources` | ServiceCallTicketResource | entity | extended | yes (service_call_tickets) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_serviceCallTicketResource_get |
@@ -1526,6 +1625,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `tag_groups` | TagGroup | entity | advanced | no | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_tagGroup_get |
 | `tags` | Tag | entity | advanced | no | query, count, get, create, update, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_tag_get |
 | `task_secondary_resources` | TaskSecondaryResource | entity | extended | yes (tasks) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_taskSecondaryResources_get |
+| `tax_regions` | TaxRegion | entity | advanced | no | query, count, get, create, update | getEntityInfo, getFieldInfo, getUdfInfo | autotask_taxRegion_get |
 | `ticket_additional_configuration_items` | TicketAdditionalConfigurationItem | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketAdditionalConfigurationItem_get |
 | `ticket_additional_contacts` | TicketAdditionalContact | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | createIfNotExists, getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketAdditionalContact_get |
 | `ticket_attachments` | TicketAttachment | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | download, getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketAttachment_get |
@@ -1541,8 +1641,8 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `ticket_notes` | TicketNote | entity | extended | yes (tickets) | query, count, get, create, update, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketNote_get |
 | `ticket_secondary_resources` | TicketSecondaryResource | entity | extended | yes (tickets) | query, count, get, create, delete, resolve | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketSecondaryResources_get |
 | `ticket_webhooks` | TicketWebhook | entity | extended | yes (tickets) | query, count, get, create, update, delete, resolve, search | getEntityInfo, getFieldInfo, getUdfInfo | autotask_ticketWebhook_get |
-| `tickets` | Ticket | entity | core | no | query, count, get, create, update, resolve, search, getContext | changeStatus, findByTicketNumber, 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, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, postedWithin, today, yesterday | autotask_timeEntry_get |
+| `tickets` | Ticket | entity | core | no | query, count, get, create, update, resolve, search, getContext | changeStatus, findByTicketNumber, forResource, fullContext, getEntityInfo, getFieldInfo, getUdfInfo, openWithNoteAndAssign, slaHealthCheck, statusSemantics, summary, timeline | autotask_ticket_get |
+| `time_entries` | TimeEntry | entity | extended | no | query, count, get, create, update, delete, resolve | approve, createForResource, createIfNotExists, customRange, dateWorkedWindow, getEntityInfo, getFieldInfo, getPosted, getUdfInfo, getUnposted, last14, last24h, last30, last7, last90, lastFullFortnight, lastFullMonth, lastFullQuarter, lastFullWeek, postedWithin, today, yesterday | autotask_timeEntry_get |
 | `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 |
@@ -1554,7 +1654,7 @@ Standard methods (every resource, `BaseResource`): `query` (stream, 1000-page gu
 | `threshold_information` | — | integration | core | no | get | — | autotask_threshold_information |
 | `zone_information` | — | integration | advanced | no | get | — | autotask_zone_information |
 
-128 resources (121 entity + 7 integration). Rows are generated from the registry — do not hand-type.
+129 resources (122 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
@@ -1831,6 +1931,28 @@ resource paths, of which **40** expose a create op (the stampable set; the
   (resource, role) pairs exist in the tenant (postedWithin rows: resourceID
   31131373 / 29869529 with roleID 29682834). The typed W-A3 pointer note
   carries this.
+- **Derived fields (issue #219 N8, live ww29 2026-10-26 — twelve time entries
+  logged on ticket 530637)**: `hoursWorked` is recomputed from
+  `startDateTime`/`endDateTime` (a create sending `1.43` for a 14:00-15:26
+  block stored `1.5`; omitting it stored the same `1.5`; other entries stored
+  the exact elapsed time — 40 min → 0.6667, 110 min → 1.8333, 15 min →
+  0.25; the rounding rule is **UNVERIFIED**) and a later PATCH returns HTTP
+  success without persisting a correction (`FIELD_NOT_PERSISTED`) — the only
+  remedy is delete + recreate. `timeEntryType`, `contractID` and
+  `internalBillingCodeID` are inherited (from the ticket; the internal billing
+  code is mirrored from `billingCodeID`); `timeEntryType` is flagged
+  `readOnly`, which reads as "never send" but means "derived from the parent".
+  `billingApprovalLevelMostRecent` is derived by a DIFFERENT entity: the REST
+  approval write is a **create on `BillingItemApprovalLevels`** (create-only;
+  `billing_item_approval_levels` is a plan resource since 0.27.0), while
+  `billingApprovalResourceID` and `billingApprovalDateTime` are a documented
+  follow-up UPDATE of the entry, not the approval itself — a caller told to
+  "approve" must create the approval level row, not write two fields. The
+  field is also not a usable signal: it stayed `0` for those twelve entries
+  and for all 392,182 posted billing items in the tenant. The declaration is
+  plan-pinned (`resources.time_entries.derivedFields`, tokens only — §11.14)
+  and served on `operations.fieldCatalog` rows and the `time_entries`
+  `createGuidance` row.
 
 ### 11.5 Company-create side effect
 
@@ -2095,7 +2217,7 @@ calls — generated plan data, drift-guarded by `capabilities:check` clause
 14), so an agent can read "what is blind on this zone" without burning
 budget or guessing:
 
-- **`operations.blindSurfaces`** — the 116-surface inventory: per surface the
+- **`operations.blindSurfaces`** — the 124-surface inventory: per surface the
   kind (`unowned-blind` / `unfiltered-blind` / `unknown` — the 46
   data-with-rows surfaces ride `unknown` by design: the sweep's limit-2 read
   proves data, not the absence of it), the recorded `unfilteredRows` (0-2
@@ -2133,6 +2255,57 @@ 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.
 
+**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.
+
+**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
+receipt that DID say what it wanted is 300-char truncated on disk
+(`ticket_charges.create` preserves only `"A productID or a billingCodeID must b"`).
+So the requirement is **declared** where the fact is known, and the receipt
+stays evidence — never reconstructed:
+
+- `blocker.requires?: { anyOf?, allOf?, noneOf? }` — the vendor field names a
+  caller must supply (or must not) for the create to be accepted. Optional and
+  additive: a row without it keeps its exact shape.
+  `ticket_charges.create` and `project_charges.create` serve
+  `requires: { anyOf: ['productID', 'billingCodeID'] }`.
+- `createGuidance.requiresByValue?: [{ field, value, requires, values? }]` —
+  requirements conditioned on a picklist value, so a caller sees the condition
+  and can satisfy it before the attempt. `contracts.create` declares the
+  recorded `contractType` gates: type 1 → `estimatedRevenue` +
+  `estimatedHours` + `estimatedCost`; types 3, 4, 6, 8 → `estimatedRevenue`;
+  type 7 → `contractPeriodType` (+ `values: { contractPeriodType: 2 }`) and
+  `setupFee`. (Whether type 7 also needs `estimatedRevenue` is **UNVERIFIED**:
+  the recorded message names `estimatedRevenue` for types 1/3/4/6/8 only, and
+  this block reproduces that clause exactly rather than extending it.)
+- `createGuidance.rejectedValues?: [{ field, value }]` — picklist values the
+  vendor refuses (`contractType: 5`).
+
+The prose those fields used to live in is gone: the `contracts.create` message
+now POINTS at `requiresByValue` instead of restating the gates, so no consumer
+has to parse English. `check-capabilities` clause 20 holds the shape closed,
+checks every named field against the vendored model of the resource's
+`apiEntity`, and fails when a row's `vendorEvidence` states a one-of
+requirement (`"… or … must …"`) while the row declares no `requires` — the
+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.13 The posted/unposted wall (W-D3) + `postedWithin`, and drifted-create marker recovery (issues #10/#13)
 
 - **W-D3 (live, ww29, 2026-10-04, re-verified)** — this zone's TimeEntry
@@ -2251,6 +2424,64 @@ the field catalog; the seven integration singletons are refused typed —
 a known key without a catalog → `CONFIG_ERROR`, an unknown key → typed
 `RESOURCE_UNKNOWN` carrying the count + the `autotask_catalog` pointer).
 
+**Reference targets (issue #219 N1).** Every projected field row carries
+`targetResource: string | null` and `targetEnumerable: boolean`: the plan
+resource key the vendor `referenceEntityType` names, and whether that
+resource has a read (`query`/`get`) path, i.e. whether a caller can
+enumerate valid ids with it. The join is DERIVED from the generated
+registry — `resourceForEntityType(entityType)` in
+`node-autotask/operations` reads each resource's plan `apiEntity` (plus
+the singular entity name where the plan's `apiEntity` is the plural path
+segment) and returns `null` when the plan carries no such resource, so a
+consumer never hand-maps `"CompanyLocation"` -> `company_locations`. A
+row for a target the plan cannot enumerate reads `null` + `false`; the
+row carries no remedy, label or exposure claim (`plan.referenceTargets`
+is the only home for those). The same helper serves reference UDF rows —
+there is no second entity-type table.
+
+**User-defined fields (issue #219 N7).** `udfCapable` entities carry a
+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
+`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
+omits the vendor's `isQueryable` (true for UDFs, contradicted by the plain
+filter refusal), and a sent `userDefinedFields` list is MERGED by the vendor
+(a subset is correct). Object/array field rows declare
+`writeShape: 'merge' | 'replace-all'` (a scalar row carries none);
+`userDefinedFields` is `merge` at the row level. The row type
+(`FieldCatalogFieldRow`) is hand-written in `src/operations/fieldCatalog.ts`,
+not generated from the plan — the UDF vocabulary is a LIVE read.
+
+**Derived fields (issue #219 N8).** Some fields are OUTPUTS: the vendor
+recomputes them or inherits them, so a submitted value is not authoritative.
+The plan pins the declaration on the resource
+(`resources.<key>.derivedFields: [{ field, rule, writableRoute? }]`) and the
+catalog serves it twice: the resource row carries the whole `derivedFields`
+list (present exactly when the plan declares one, never filtered by the
+`fields` opt) and each matching projected field row carries
+`derived: { rule, writableRoute? }`. `rule` is a closed token, never a
+sentence: `elapsed(<startField>,<endField>)` (the vendor recomputes the value
+from those two timestamps), `parent` (inherited from the parent record),
+`mirror(<field>)` (the vendor copies that field) and `external` (written by
+another entity's op — `writableRoute` names the plan write op). The tokens are
+validated by `check-capabilities` clause 21, which also pins the
+`time_entries` set (see §11.4/§11.12): `hoursWorked` is
+`elapsed(startDateTime,endDateTime)`, `timeEntryType` and `contractID` are
+`parent`, `internalBillingCodeID` is `mirror(billingCodeID)`, and
+`billingApprovalLevelMostRecent` is `external` with
+`writableRoute: billing_item_approval_levels.create`. **`derived` is not
+`readOnly`:** `isReadOnly` (the vendor flag) means never write the field at
+all; `derived` means the vendor overwrites or inherits it — a field can be
+derived and not read-only (`hoursWorked` accepts a sent value and discards
+it). The registry stamps the same list as `metadata.derivedFields` on every
+record of the resource, so `autotask_describe` and the catalog cannot drift.
+
 **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 —
@@ -3355,6 +3586,11 @@ sentence (`UNTRUSTED_NOTE`, mirrored verbatim in
 `examples/mcp-register.ts` and `scripts/project-mcp-tools.mjs` so the
 served description equals the manifest's), and their WIRE `outputSchema`
 carries the field list as the `x-untrusted` extension (zod v4 `.meta`). The
+cross-resource tools (`resolveAny`, `searchAcrossResources`, the mode tools)
+carry `["*"]` instead of the union: the per-resource tools already list every
+field, the union only grows with each added resource, and the served surface has
+a hard token budget — `["*"]` states the stronger claim ("every text value here is
+vendor-authored") without repeating the catalog in five schemas. The
 reference server (`examples/mcp-register.ts`) wraps the affected fields in
 `<untrusted_content>` markers AFTER the SDK call (projection layer only —
 the SDK primitives stay raw), strips ONE outer wrapper from write/filter

package/examples/mcp/schemas.ts

@@ -6,7 +6,7 @@ import * as z from 'zod/v4';
 import type { StandardSchemaWithJSON } from '@modelcontextprotocol/server';
 import type { CapabilityRecord } from 'node-autotask/capabilities';
 import { WORKFLOW_RESOURCES } from 'node-autotask/operations';
-import { CROSS_RESOURCE_UNTRUSTED, untrustedFieldsOf } from './manifest.js';
+import { untrustedFieldsOf } from './manifest.js';
 
 // ---------------------------------------------------------------------------
 // Input fragments (zod v4) — the shapes the manifest's `input` column states.
@@ -109,6 +109,18 @@ export function dataField(description: string, fields: readonly string[]): z.Zod
   return fields.length > 0 ? base.meta({ 'x-untrusted': [...fields] }) : base;
 }
 
+/** The cross-resource wildcard result (search_across / resolve_any / a mode
+ *  tool): its untrusted set is the union over every resource, which grows with
+ *  each added resource and is already listed field-by-field on that resource's
+ *  own tools. On the wire it is therefore marked `["*"]` — "every text value in
+ *  this result is vendor-authored" — which is the stronger claim and does not
+ *  repeat the catalog in five schemas (the served surface has a hard budget).
+ *  The runtime redaction still uses the full union (`CROSS_RESOURCE_UNTRUSTED`
+ *  in tools-mode.ts); only the wire annotation is compacted. */
+export function crossDataField(description: string): z.ZodType {
+  return z.unknown().describe(description).meta({ 'x-untrusted': ['*'] });
+}
+
 /** One resolved record: `found: false` is a complete answer, not an error.
  *  The `record` field carries `x-untrusted` for the tool's resource. */
 export function oneOutput(rec: CapabilityRecord): z.ZodType {
@@ -139,7 +151,7 @@ export function hitsOutput(): z.ZodType {
   return z.object({
     query: z.string(),
     results: z.array(
-      z.object({ resource: z.string(), matches: z.array(dataField('Compact summary rows.', CROSS_RESOURCE_UNTRUSTED)) }),
+      z.object({ resource: z.string(), matches: z.array(crossDataField('Compact summary rows.')) }),
     ),
     skipped: z.array(z.string().describe('Requested resources without a search helper — reported, never errored.')),
   });
@@ -150,10 +162,7 @@ export function resolveAnyOutput(): z.ZodType {
   return z.object({
     identifier: z.union([z.string(), z.number()]),
     results: z.array(
-      dataField(
-        'Per-resource outcome: value (compact or null), resolutionCost, scanned, candidates/error on a miss.',
-        CROSS_RESOURCE_UNTRUSTED,
-      ),
+      crossDataField('Per-resource outcome: value (compact or null), resolutionCost, scanned, candidates/error on a miss.'),
     ),
     matches: z.array(z.string().describe('The resources that resolved to exactly one record.')),
   });
@@ -190,7 +199,7 @@ export function invokeOutput(): z.ZodType {
   return z.object({
     operation: z.string(),
     simulated: z.boolean(),
-    result: dataField('The SDK result — the pinned DryRunResult envelope for a simulated write.', CROSS_RESOURCE_UNTRUSTED),
+    result: crossDataField('The SDK result — the pinned DryRunResult envelope for a simulated write.'),
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,