node-autotask 0.21.0 → 0.24.0

package/docs/API.md

@@ -1,6 +1,6 @@
 # API Reference — node-autotask
 
-> Generated from: `src/` (core modules), `src/errors.ts`, `src/config.ts`,
+> Generated from: `src/` (core modules), `src/errors/`, `src/config/`,
 > `src/pagination.ts`, `src/query.ts`, `src/operations/`, and the capability
 > registry (`capabilities.json` + `capabilities.plan.json`). The normative
 > architecture is `ARCHITECTURE.md`; this reference documents the public
@@ -49,7 +49,7 @@ Integration endpoints are on their own accessors: `authenticateResource.get()`
 `zoneInformation.get(user?)` (the swagger-required `user` query param
 defaults to the configured UserName — the vendor 404s the param-less call).
 
-### 1.2 `config.ts` — configuration + zone catalog
+### 1.2 `config/` — configuration + zone catalog
 
 `AutotaskConfig` / `ResolvedAutotaskConfig` + the 23-zone catalog
 (`ZONE_CATALOG`, `ZONES`, `DEFAULT_ZONE`), `zoneUrl()`, `resolveBaseUrl()`,
@@ -76,7 +76,7 @@ endpoint (`client.authenticateResource.get()` → `AuthTokenResultModel
 { authToken, expiration }`), which is a credential probe, not a stored-token
 flow.
 
-### 1.4 `http.ts` — HTTP transport
+### 1.4 `http/` — HTTP transport
 
 Native global `fetch` (Node >= 24) — zero runtime dependencies across the
 whole package. `HttpClient.request<T>(opts): Promise<T>` is the single
@@ -101,7 +101,7 @@ Every 2xx JSON body also passes through the response redaction transform
 (`redactResponseBody`, section 10) at this single choke point — secret fields
 always, personal/business-sensitive data by default.
 
-### 1.5 `errors.ts` — error hierarchy
+### 1.5 `errors/` — error hierarchy
 
 `AutotaskError` is the base: every error carries the structured contract —
 `code` (stable SCREAMING_SNAKE machine code), `category`, `retryable`,
@@ -593,7 +593,7 @@ diagnostic is appended as a separate field, and a 401 is still never retried.
 
 `circuitBreaker: { enabled: true }` opts into the optional circuit breaker
 at the transport (OFF by default — without it, behaviour is byte-identical
-to before; no env overrides — `src/config.ts` never reads `process.env`).
+to before; no env overrides — `src/config/` never reads `process.env`).
 Vendor health is HOST-scoped (a zone outage hits every tenant on that
 zone), so the key is the lowercased host of the resolved base URL
 (`buildBreakerKey` — the same derivation as `buildTenantKey`'s host part,
@@ -940,11 +940,18 @@ MCP-independent: no MCP imports, no zod.
 
 Bounded multi-resource text search. Runs each requested resource's OWN
 `search` helper (server-side bounded `contains` — never a listAll scan)
-across the selected resources with one limit budget. `resources` defaults to
-`WORKFLOW_RESOURCES`; `limit` defaults to 25 per resource, clamped to the
-vendor max of 500. Resources without a `search` helper are skipped and
-REPORTED (the `skipped` array), never errored. Returns
-`{ query, results: [{ resource, matches }], skipped }`.
+across the selected resources. `resources` defaults to `WORKFLOW_RESOURCES`;
+`limit` is **per resource** (default 25, clamped to the vendor max of 500), so
+a sweep over N resources can return up to N x `limit` matches. Optional
+`totalLimit` (positive integer) caps the whole sweep: resources are searched in
+request order, each asked for `min(limit, remaining)`; once the cap is met the
+rest are not queried and are listed in `notSearched`, and `truncated` is true
+when more matches may exist (a resource was not searched, or a searched
+resource returned exactly the quota it was asked for, `min(limit, remaining)`). Resources without a
+`search` helper are skipped and REPORTED (the `skipped` array), never errored.
+Returns `{ query, results: [{ resource, matches }], skipped }`; with
+`totalLimit` the result also carries `notSearched` and `truncated`, and
+without it the result is unchanged.
 
 ### 7.2 `resolveAny(client, identifier, opts?)`
 
@@ -1025,8 +1032,8 @@ dry-run envelope) is that path's — not a second implementation.
 The three MCP mode tools (`autotask_read` / `autotask_write` /
 `autotask_delete`) dispatch through the SAME router as `invoke` with the mode
 pinned (`InvokeMode = 'read' | 'write' | 'delete'`; the mode predicate is the
-registry `effect`, verified one-to-one: 961 read / 198 write / 54
-destructive of the 1213 ops). `invoke()` itself is UNCHANGED — the
+registry `effect`, verified one-to-one: 963 read / 198 write / 54
+destructive of the 1217 ops). `invoke()` itself is UNCHANGED — the
 programmatic escape hatch, its mode derived from the record, so it can never
 be cross-mode-refused.
 
@@ -1041,27 +1048,27 @@ be cross-mode-refused.
 - everything else is the governor's, unchanged: the dry-run-first default
   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 1213 ops × 3 modes, zero wire).
+  Pinned by the full-surface suite (`test/operations/invoke/modes.test.ts`:
+  all 1214 ops × 3 modes, zero wire).
 
 **Harness approval policy (recommended).** Require approval on every tool
-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 **601 tools** (the 588
+whose MCP annotation is `readOnlyHint !== true` — today exactly **256
+   tools**: the 254 dedicated write/delete tools (198 `effect=write` + 56
+   `effect=destructive`, every one of them has a dedicated tool) +
+`autotask_write` + `autotask_delete`. The remaining **603 tools** (the 590
 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).
-Refined class for the highest-risk ops: the **55 tools with
-`destructiveHint: true`** (54 dedicated delete tools + `autotask_delete`)
+Refined class for the highest-risk ops: the **57 tools with
+`destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`)
 additionally require `confirm === <operation key>` even inside
 `autotask_delete`, and the 3 approval-gated writes
 (`configuration_items.moveConfigurationItem`, `contacts.moveToCompany`,
 `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 254 above) and remove any `autotask_invoke` entry. The rule is
+(approve the 256 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.
 
@@ -1120,7 +1127,7 @@ const applied = await recovery(client, { resource: 'configuration_item_dns_recor
   preserved) + the boundary note in `warnings[]` (the SAME generated note
   `recovery` serves — the describe and dry-run channels cannot drift).
   Pinned by `test/operations/recovery.test.ts` (11 tests) + the full-surface
-  governor suite (`test/operations/invoke-modes.test.ts`).
+  governor suite (`test/operations/invoke/modes.test.ts`).
 
 ### 7.6 `fetchMany(client, items, opts?)` / `fetchByIds(client, items, opts?)` — bulk fetch by ids
 
@@ -1303,6 +1310,105 @@ const n = await aggregate(client, 'billing_items.query', [{ field: 'companyID',
 const fold = await aggregate(client, 'time_entries.query', [{ field: 'dateWorked', op: 'gte', value: '2026-09-01' }], { groupBy: ['ticketID'], sum: ['hoursWorked'], top: 10 });
 ```
 
+### 7.9 `uiLink(client, input)` / `buildUiLink(input)` — Autotask UI deep links (issue #202)
+
+Pure, **zero-wire** builder of ExecuteCommand deep links:
+`https://ww<N>.autotask.net/Autotask/AutotaskExtend/ExecuteCommand.aspx?Code=<Command>&<Param>=<value>`.
+`input` is `{ entity, id | ticketNumber, host? }`; the op returns `{ url }`, or
+`{ url: null, reason }` when no UI host can be derived. Reachable as
+`operations.uiLink` through `invoke` / `autotask_read`; `buildUiLink` is the
+in-process helper (returns the URL or `undefined`; it also accepts `zone` /
+`baseUrl` to derive the host).
+
+| `entity` | Link |
+| --- | --- |
+| `time_entries` | `Code=EditTimeEntry&WorkEntryID=<id>` |
+| `tickets` | `Code=OpenTicketDetail&TicketID=<id>` or `&TicketNumber=<T…>` |
+| `tasks` | `Code=OpenTaskDetail&TaskID=<id>` |
+| `projects` | `Code=OpenProject&ProjectID=<id>` |
+| `companies` / `contacts` / `contracts` | `OpenAccount&AccountID` / `OpenContact&ContactID` / `OpenContract&ContractID` |
+| `configuration_items` | `Code=EditInstalledProduct&InstalledProductID=<id>` |
+
+- **Host derivation:** `ww<N>` comes from the client's live REST base
+  (`webservices<N>`); a base without `<N>` (`pre-release-de`/`-es`, a custom
+  host) yields no link — a host is never guessed. Pass `host: 'ww<N>.autotask.net'`
+  to name it.
+- **Safety:** ids are positive safe integers; `ticketNumber` must match
+  `^T\d{8}\.\d{4}$` and is only valid for `tickets`; exactly one of
+  `id` / `ticketNumber`; an unknown entity, bad id or bad host is a typed
+  `CONFIG_ERROR` naming the valid values — no vendor string is interpolated.
+- **Caveats:** the user must be logged in and their security level applies (a
+  link grants no access); ExecuteCommand opens a popup; an invalid query string
+  shows an error page; there is no `OpenTimeEntry` command. The op never checks
+  the record exists. Unverified live: the `ww<N>` ↔ `webservices<N>` mapping for
+  each catalog zone (`zoneInformation.get().webUrl` is the authority) and that
+  `WorkEntryID` equals the REST time-entry `id`.
+
+
+### 7.10 `moveToTicket` — governed create-verify-delete moves (issue #197)
+
+`time_entries.moveToTicket(sourceId, toTicketId, opts)` and
+`ticket_charges.moveToTicket(sourceId, toTicketId, opts)` re-parent a record the
+vendor will not re-parent by update (probed live: an update of `ticketID`
+returns success and keeps the old value). Both run on one shared engine
+(`src/resources/special/_shared/move-engine.ts`); notes are different —
+`ticket_notes` update with a new `ticketID` (parent-scoped) does move a note, and
+notes cannot be deleted, so they never use create-then-delete.
+
+- **Governed:** effect `destructive`; dry-run first (a GET-only preview that
+  returns the create payload); apply needs `dryRun: false` and
+  `confirm: '<resource>.moveToTicket'`. Options: `maxSourceAgeDays` (default 14,
+  lowerable never raised), `lastModifiedDate` (stale guard), `maxRetries` (reads only).
+- **Hard invariants (typed `MOVE_*` refusal, zero writes, re-run at apply):**
+  source exists and is on a ticket (task/internal refused), target exists and is
+  open, target differs from the source ticket, source not billed/posted
+  (`billing_items` by `timeEntryID`; unreadable fails closed) or approved, no
+  attachments (a delete destroys them), not older than the age limit, and no twin
+  already on the target (checked in the preview and again immediately before the POST).
+- **Apply order:** POST (once, never retried) -> read the new record back and compare
+  -> re-read the source (any drift rolls the new record back) -> DELETE the source.
+- **Result:** `{ status: 'moved' | 'moved_source_absent' | 'moved_manual_delete',
+  sourceId, newId, correlationId, snapshot, facts, manualAction? }`. Every other
+  outcome throws `MoveRefusedError` whose `details.status` is `failed` (nothing
+  changed), `partial` (both records exist) or `unknown`; details carry ids, never values.
+  The SDK stores nothing — persist `snapshot` if you need it.
+- **Manual GUI path:** a refusal that a person can finish in the UI (billed,
+  approved, attachments, too old) and a source delete the vendor refuses carry
+  `manualAction: { action: 'delete_source', uiLink, reason }`. `uiLink` is an
+  `operations.uiLink` deep link: the time entry itself (its edit page), or the
+  parent ticket for a charge (no ExecuteCommand code exists for charges). It is
+  `null` when no UI host can be derived from the client base.
+- **Caveats:** the new record gets a fresh create date and creator; creating and
+  deleting may trigger notifications, SLA and workflow rules the API cannot
+  suppress; vendor acceptance of the create is not validated by a dry run.
+  Contract fields are copied only when the target ticket has the same company and contract.
+
+### 7.11 Finding the ticket for a piece of work (issue #210)
+
+- `tickets.search(query, { limit?, companyID?, includeFields? })` — the bounded `contains` on `title`, now
+  optionally scoped to one company (a `companyID eq` leaf and-joined server-side with the title match) and
+  projected to the listed columns (`id` is always returned). `searchWithDetail` takes the same bag. Malformed
+  `companyID` / `includeFields` are refused before any request. Other resources' `search` is unchanged.
+- `time_entries.recentTickets(from, to, { resourceID, companyID?, tz?, limit? })` — the distinct tickets a
+  resource logged time against in an inclusive `dateWorked` window (`YYYY-MM-DD`; UTC days, or the local days in
+  `tz`). One bounded time-entry read (`dateWorked` + `resourceID`; `limit` 1-500, default 500, bounds the
+  **entries** scanned) plus `id in [...]` ticket reads (100 ids each). Result `{ items, entriesRead,
+  entriesWithoutTicket, unresolvedTicketIDs, window, truncated }`; each item carries `ticketID`, `ticketNumber`,
+  `title`, `status`, `assignedResourceID`, `companyID`, `entryCount`, `totalHours`, `lastWorked`, newest first.
+  TimeEntry has no `companyID`, so `companyID` is applied **after the join**, client-side on the ticket rows'
+  own `companyID` (the ticket read is not company-filtered on the wire). Entries on other companies' tickets
+  still consume `limit`; those tickets are only counted in `excludedTickets` (ids are not returned), and
+  `unresolvedTicketIDs` holds only tickets the read did not return at all (deleted or invisible, dropped from
+  `items` when `companyID` is set). `truncated: true` (same meaning as `postedWithin`) means the rollup covers
+  the scanned entries only; narrow the window. `search` refuses an unknown option key (a misspelt `companyId`
+  can't silently widen the search), and drops an empty `userDefinedFields` the vendor appends to projected rows.
+- **`tz` on the `dateWorked` ops** (`recentTickets`, `postedWithin`, `dateWorkedWindow`, `customRange` and the relative
+  windows): the vendor stores `dateWorked` as a date-only value at 00:00 UTC, so the wire bounds are always whole UTC days.
+  For `recentTickets` / `postedWithin` / `dateWorkedWindow` / `customRange` the `from`/`to` days ARE the days, so `tz` is
+  validated but never shifts them. For the relative windows (`today`, `last7`, `lastFullMonth`, ...) `tz` picks which
+  calendar dates the window covers in that zone and the bounds are whole UTC days of those dates. (Before 0.24.0 a `tz`
+  behind UTC, e.g. `America/Los_Angeles`, selected the NEXT UTC day; live-verified 2026-10-23.)
+
 ## 8. Resource surface (128 resources)
 
 <!-- BEGIN GENERATED:api-per-entity -->
@@ -1544,7 +1650,7 @@ cannot drift from the plan):
 - `EMPTY_REASON_STAMPS` (issue #14) — resource → op → the typed empty-reason
   `{ surface, kind, note, authority, remedy }` (`plan.emptyReasons`, the
   ww29-sweep-pinned 184 rows): the runtime lookup `base.ts` attaches to
-  0/empty count/query results + the update dry-run envelope, and `http.ts`
+  0/empty count/query results + the update dry-run envelope, and the HTTP transport (`src/http/`)
   attaches to the typed error's `details` (the SAME generated data the plan
   serves — the result channel and the plan cannot drift). The
   `blind-surface` kind is ABSENT by design: `base.ts` synthesizes it from
@@ -1706,15 +1812,16 @@ resource paths, of which **40** expose a create op (the stampable set; the
   the validation-layer spelling `InternallAllocationCodeID` is rejected by the
   deserializer (key oracle, S9b §5: the gate-1 error text names the validation
   layer, not the body key).
-- **2026-10-06 vendor drift (confirm-100)**: the vendor now refuses ALL
-  time-entry writes for this API-only user with
-  "API-only user cannot be selected for this field" — `create` **and**
-  `createForResource` (stage-11 proven, 8 live creates 2026-10-04) alike.
-  The wall is vendor eligibility, not missing tenant data: valid (resource,
-  role) pairs exist in the tenant (postedWithin rows: resourceID
-  31131373 / 29869529 with roleID 29682834) but belong to human resources
-  the API user cannot select. Unsatifiable for an API-only integration
-  user; the typed W-A3 pointer note carries this.
+- **2026-10-06 vendor drift (confirm-100), re-scoped 2026-10-21 (#195)**: a
+  (resource, role) pair that selects the API-only user's own resource was
+  refused with "API-only user cannot be selected for this field" — `create`
+  and `createForResource` (stage-11 proven, 8 live creates 2026-10-04)
+  alike. This is a pair-scoped wall, not a blanket refusal: live
+  `time_entries.create` calls succeeded on 2026-10-21 (pair not recorded);
+  the authorised pair set has NOT been re-adjudicated by a live probe. Valid
+  (resource, role) pairs exist in the tenant (postedWithin rows: resourceID
+  31131373 / 29869529 with roleID 29682834). The typed W-A3 pointer note
+  carries this.
 
 ### 11.5 Company-create side effect
 
@@ -1731,7 +1838,7 @@ redacted `vendorError` naming the offending field and a deterministic
 quirk**: the error contract labels 500s `retryable: true` ("the server error is
 transient") even when the 500 is a *deterministic* missing-field rejection —
 retrying with the same body fails identically; fix the field instead
-(`src/errors.ts` sets `retryable: true` for `SERVER_ERROR` and for every
+(`src/errors/` 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`:
@@ -1826,7 +1933,7 @@ synthesis. The 9 registry-backed records — `tickets` / `companies` /
 `.create` + `time_entries.create` / `time_entries.createForResource` — render
 the override verbatim, and every example passes its own record's `inputSchema`
 (the governor dispatch validator; pinned by
-`test/scripts/mcp-surface-guidance.test.ts`). The `configuration_items`
+`test/scripts/mcp-surface/create-examples.test.ts`). The `configuration_items`
 body documents the §11.3 product wall, not a working create;
 `time_entries.create` points at `createForResource` (the linkage-aware
 method). The plan's 12-target list also names `tickets.createIfNotExists`,
@@ -1920,9 +2027,9 @@ so the answer to "why is this empty?" is data, not speculation:
   (`ticket_history.query` W1: the vendor requires exactly ONE ticketID-eq
   filter — unfiltered 500s by contract; WITH the filter the query WORKS
   (live 2026-10-06) → `tickets.timeline` / `tickets.fullContext` stay the
-  composites; `time_entries.create` W-A3: the API-only-resource wall
-  ("API-only user cannot be selected for this field" — 2026-10-06 drift,
-  `createForResource` walled by the same drift); `authenticate.get` W2:
+  composites; `time_entries.create` W-A3: the pair-scoped wall on the
+  API-only user's own resource ("API-only user cannot be selected for this
+  field" — 2026-10-06; creates succeeded 2026-10-21, pair not recorded); `authenticate.get` W2:
   designator-only;
   `time_entries.getPosted` / `time_entries.getUnposted` W-D3: this zone's
   TimeEntry entity exposes no posted-state filter field — the working read
@@ -2053,11 +2160,10 @@ into one predicted-failure-free attempt.
   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.
+  name and default semantics. Both accept `opts.tz` (an IANA zone, validated)
+  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.
 - **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
@@ -2458,7 +2564,7 @@ what makes it usable as a recovery signal from inside the client.
   lifetime, like a cache); no change to the served MCP/n8n text (transport
   behaviour, like #34).
 
-Pins: `test/transport-zone-reresolve.test.ts` (11 pins, mock wire only —
+Pins: `test/transport-zone-reresolve/*.test.ts` (11 pins, mock wire only —
 no vendor wire in tests; the 10 issue-required + the breaker probe
 host-pinning pin).
 
@@ -2602,6 +2708,17 @@ 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).
 
+**Per-part projection (issue #200)**: `companies.fullProfile` accepts
+`fields?: { locations?, contacts?, notes?, projects?, openTickets? }` — each a
+non-empty list of exact vendor field names — and `locationLimit?: number`
+(default 50, 1-500). A listed part serves ONLY those fields (sent as
+`IncludeFields`, then picked client-side); an absent part keeps the full model,
+and without `fields` the call and result are unchanged. An unknown part key, an
+empty/non-array list or a field name unknown to the part's vendored field
+catalog is a typed `CONFIG_ERROR` before any request. `capped`, `absent` and
+`parts` semantics are unchanged; with `names: true` the siblings appear only for
+the id fields you kept.
+
 **Composite wiring (issue #77)**: the full-context composites
 (`tickets.fullContext`, `companies.fullProfile`,
 `configuration_items.profile`, `projects.getContext`) accept an
@@ -2675,7 +2792,11 @@ additive, and mirrors the family:
   (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
+  for the wire (vendor filter values stay second-precision UTC ISO) — for
+  `billing_items` and `invoices`. The `time_entries` family is DATE-ONLY
+  (`dateWorked` is stored at 00:00 UTC): the zone picks the calendar DATES and
+  the wire bounds are whole UTC days of them; explicit `from`/`to` days are never
+  shifted (0.24.0; a zone-converted instant window picked the wrong day behind UTC). 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`)
@@ -2686,8 +2807,8 @@ additive, and mirrors the family:
 - **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).
+  with the contract above (date-only for time entries), so the whole window family accepts
+  the same `tz` option (default UTC unchanged).
 - **Shape and wire** — each op is exactly ONE bounded query (`MaxRecords`
   1-500, default 500 — the hard cap, issue #128: a call without `limit` takes
   the first 500 rows in id order; a window with more than 500 matching rows
@@ -3155,12 +3276,12 @@ returns the contract's reconciled P&L over a date window:
   `effect: 'read'`, `dryRun: false`, the closed-bag `inputSchema` (the
   signature-audited arg map in `scripts/lib/args-derive.mjs`); the emitted
   method delegates to the hand-written special module
-  (`src/resources/special/contracts.ts`). The MCP projection serves
+  (`src/resources/special/contracts/profitability.ts` and its `profitability.*.ts` siblings). The MCP projection serves
   `autotask_contract_profitability` (catalog + manifest); the N8N
   manifests legitimately EXCLUDE the op — `contracts` is not an n8n
   curated entity (the curation rule is evidence-based: the daily support
   subset is ticket/contact/company/resource/time_entry only).
-- **Test pins.** `test/resources/contracts.profitability.test.ts`: the
+- **Test pins.** `test/resources/contracts.profitability.*.test.ts` (revenue, rate-ladder, cost-ladder, bounds, warnings): the
   hand-computed 2-month synthetic fixture (every figure derived from the
   fixture rows; `wires.issued = 20` with the exact queue; every wire pinned
   in issue order; the structural exclusions + zero-mutating recorded paths;
@@ -3177,7 +3298,7 @@ returns the contract's reconciled P&L over a date window:
   charge cost/period-type/line-type classifiers, the Block Hours
   `contract_blocks` path, T&M unposted pricing + the time-referenced old
   ticket, the exclusive window ends, the month-level `coverage_gaps`).
-  `test/resources/profitability-degradation.test.ts`: the empty-tenant
+  `test/resources/contracts.profitability.degradation.test.ts`: the empty-tenant
   13-wire suite (every part degrades, zero tool failure), the dangling
   customer FK, the non-404 customer fault (`absent`), a bounded-part fault
   (`absent` + `coverage_gaps`, the call resolves), the resources blind-list get-fallback (rung 3 from the

package/docs/N8N-ADAPTER.md

@@ -16,11 +16,11 @@ knowledge**:
 | entity catalog (138 entity metadata entries, 121 resource dirs) | `constants/entities.ts` + `resources/<dir>/description.ts` | the SDK's 128 resource accessors + the capability registry (`capabilities.json`) |
 | per-entity operations (get/getMany/count/create/update/delete + specials) | `resources/<dir>/execute.ts` switch cases | SDK primitive + helper operations, one per registry row |
 | auth (3 headers + optional impersonation) | `helpers/http/headers.ts` | `src/auth.ts` (swagger casing) + fail-closed config |
-| zone catalog (23 zones) | the node credential definition | `src/config.ts` `ZONE_CATALOG` |
+| zone catalog (23 zones) | the node credential definition | `src/config/zones.ts` `ZONE_CATALOG` |
 | pagination (nextPageUrl cursor walk, `PAGINATION.MAX_PAGES` = 1000) | `helpers/pagination.ts` | `src/pagination.ts` (same cursor-follow walk — POST the filter to the absolute `nextPageUrl`, rebased to the client base URL — + 1000-page guard) |
 | filter grammar (13 operators + and/or, caps) | `constants/filters.ts` | `src/query.ts` |
-| envelopes (item/page/operation/count unwrapping) | `helpers/request.ts` + per-op unwrapping | `src/http.ts` + the pinned envelopes in the registry |
-| error mapping | `errorHandler` + `error.constants` | `src/errors.ts` (the class → code → status hierarchy) |
+| envelopes (item/page/operation/count unwrapping) | `helpers/request.ts` + per-op unwrapping | `src/http/envelope.ts` + the pinned envelopes in the registry |
+| error mapping | `errorHandler` + `error.constants` | `src/errors/` (the class → code → status hierarchy) |
 | dry-run / stale / audit guards | inline per operation | `src/operations/invoke.ts` governor + the pinned `DryRunResult` envelope |
 
 What remains in the node is the **n8n wiring**: credential UI, trigger

package/examples/mcp/errors.ts

@@ -0,0 +1,135 @@
+/**
+ * errors.ts — result shaping: the structured success/DRY results and the
+ * typed error payload (the SDK AutotaskError contract, served verbatim).
+ */
+import type { AutotaskError } from 'node-autotask';
+import { unknownKeysRefusal } from 'node-autotask/operations';
+import {
+  UNTRUSTED_CLOSE,
+  UNTRUSTED_CLOSE_NEUTRALISED,
+  UNTRUSTED_OPEN,
+  UNTRUSTED_OPEN_NEUTRALISED,
+  wrapUntrusted,
+} from 'node-autotask/untrusted';
+import type { ToolReturn } from './types.js';
+
+export const DRY_NOTE = 'No Autotask credentials in the environment (set AUTOTASK_TRACKING_IDENTIFIER, AUTOTASK_USERNAME, AUTOTASK_SECRET, optionally AUTOTASK_ZONE). The call was validated and NOT issued.';
+
+/** A successful structured result. `outputSchema` describes `structuredContent`. */
+export function ok(text: string, structuredContent: Record<string, unknown>): ToolReturn {
+  return { content: [{ type: 'text', text }], structuredContent };
+}
+
+/** A DRY-mode structured result (no request was issued). */
+export function dryResult(opId: string): ToolReturn {
+  return ok(`DRY mode — "${opId}" was NOT issued (no credentials in the environment).`, { dry_mode: true, operation: opId, note: DRY_NOTE } satisfies Record<string, unknown>);
+}
+
+/** Surface the SDK error contract so a model can self-correct: what failed, whether to retry, what to do next. Credentials never appear in an error message.
+ *
+ * `details` is passed through verbatim (issue #9/#14): the additive
+ * machine-checked extras — the typed `emptyReason` / `pointerNote` on a
+ * plan-pinned op's failure, the `operations.recovery` refusal payload
+ * (`candidateIds` / marker info), the #13 shape-drift extras — ride the
+ * served payload exactly as they do on the typed client's `AutotaskError`.
+ * The content is plan-derived (or the caller's own echoed token): never a
+ * credential, never free vendor prose beyond the already-published notes.
+ *
+ * Issue #24: `details.bodySnippet` is the ONE host-sourced free-text value
+ * that can ride the details (a host-supplied baseUrl can serve arbitrary HTML
+ * as the UNEXPECTED_CONTENT_TYPE snippet) — when `untrustedWrap` is on,
+ * exactly that value is wrapped in `<untrusted_content>`; the rest of the
+ * details stays verbatim (machine-checked / plan-derived).
+ *
+ * `vendorError` (issue #33): the deep-redacted vendor body rides the served
+ * payload (it is set upstream by `errorFromStatus` — redaction already ran
+ * before the payload is built). A STRING body is host-sourced free text and
+ * gets the SAME `<untrusted_content>` treatment as `details.bodySnippet`
+ * (wrapped when `untrustedWrap` is on, served raw when off); a parsed
+ * (non-string) body is a redacted copy — served structured, and with
+ * `untrustedWrap` on its string leaves get the SAME marker neutralisation
+ * `wrapUntrusted` applies, so a vendor body cannot forge a wrapper boundary.
+ * Absent or empty body → NO `vendorError` key: the unpinned payload stays
+ * byte-identical on the wire (an undefined key drops out of the JSON text).
+ */
+/**
+ * Issue #33 QA minor: a parsed (non-string) vendor body is served structured, so
+ * `wrapUntrusted` cannot wrap it as a whole. With `untrustedWrap` on, apply the
+ * same marker neutralisation to every string leaf instead — a vendor body
+ * containing the literal wrapper markers cannot forge a boundary.
+ */
+function neutraliseParsedMarkers(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value
+      .split(UNTRUSTED_OPEN)
+      .join(UNTRUSTED_OPEN_NEUTRALISED)
+      .split(UNTRUSTED_CLOSE)
+      .join(UNTRUSTED_CLOSE_NEUTRALISED);
+  }
+  if (Array.isArray(value)) return value.map(neutraliseParsedMarkers);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[k] = neutraliseParsedMarkers(v);
+    return out;
+  }
+  return value;
+}
+
+export function errorContent(err: unknown, untrustedWrap = false): ToolReturn {
+  const e = err as Partial<AutotaskError> | undefined;
+  const message = err instanceof Error ? err.message : String(err);
+  let details = e?.details;
+  if (
+    untrustedWrap &&
+    details !== undefined &&
+    details !== null &&
+    typeof (details as Record<string, unknown>).bodySnippet === 'string'
+  ) {
+    details = {
+      ...(details as Record<string, unknown>),
+      bodySnippet: wrapUntrusted((details as Record<string, unknown>).bodySnippet),
+    };
+  }
+  // issue #33: the redacted vendor body under a fixed key (absent/empty →
+  // undefined → no key on the wire — see the doc block).
+  const vendorErrorRaw = e?.vendorError;
+  const vendorError: unknown =
+    typeof vendorErrorRaw === 'string'
+      ? vendorErrorRaw === ''
+        ? undefined
+        : untrustedWrap
+          ? wrapUntrusted(vendorErrorRaw)
+          : vendorErrorRaw
+      : vendorErrorRaw !== undefined && vendorErrorRaw !== null
+        ? untrustedWrap
+          ? neutraliseParsedMarkers(vendorErrorRaw)
+          : vendorErrorRaw
+        : undefined;
+  const payload = {
+    error: true,
+    code: e?.code,
+    category: e?.category,
+    retryable: e?.retryable,
+    httpStatus: e?.httpStatus,
+    operation: e?.operation,
+    vendorError,
+    suggestedAction: e?.suggestedAction,
+    correlationId: e?.correlationId,
+    resourceIds: e?.resourceIds,
+    details,
+    message,
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(payload) }], isError: true };
+}
+
+/**
+ * The handler-side typed refusal for a tool call (issue #3). Runs the
+ * SDK's shared closed-set check (`unknownKeysRefusal`) against the tool's
+ * valid top-level keys and, on a refusal, serves the full error contract
+ * through the same `errorContent` path the rest of the refusals use.
+ * Returns null when every key is known (no refusal).
+ */
+export function closedArgsError(raw: unknown, validKeys: readonly string[]): ToolReturn | null {
+  const refusal = unknownKeysRefusal(raw, validKeys, 'argument');
+  return refusal === null ? null : errorContent(refusal);
+}