node-autotask 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Minor: the plan hash moves `913f1120...` -> `08cf890f...` (new `caveats` channel, `createGuidance` data hygiene, `opts` on every `get` input schema), so the next release is 0.34.0 and a consumer re-pins once.
+
+### Added
+
+- **#244: `allowAssumed?: boolean` on `tickets.statusSemantics`, `tickets.forResource` and `companies.fullProfile`** (default `true`, behaviour unchanged). With `false`, an unreadable status picklist or one with no closed label throws `AutotaskError` code `STATUS_SEMANTICS_UNRESOLVED` instead of falling back to the assumed `[5]`. `companies.fullProfile` also takes `excludeStatusIds`, so an operator pin reaches every open-ticket consumer.
+- **#248: `tickets.forResource({ countOnly: true })`** returns `{ resourceID, scope, primary, secondary, both, open, capped, closedStatus }` with no ticket rows (typed overload). Primary goes through the same count path as `tickets.count`; secondary is a de-duplicated ids-only read. No new registry op.
+- **#249: per-operation `caveats` channel** on operation metadata: `{ kind, fields?, remedyOp?, note }`, closed kind set (`not-persisted`), unknown kinds fail at build time. `time_entries.update` and `ticket_charges.update` serve "ticketID does NOT persist" as data. `pointerNote` and `metadata.usage` are unchanged.
+- **#250: `fresh: true` on every `<resource>.get(id, { fresh })` and on `invokeRead`** bypasses the read-cache lookup and refreshes the entry. `invokeRead` honours it only on `<resource>.get` and refuses it elsewhere before any request. Every `get` input schema gains the optional `opts` argument.
+- **#246: `blocker.unsatisfiableViaApi`** (attachments, opportunities), **`row.parentCompany`** (`{ via, resource, field }`, derived by a one-hop rule; 32 rows, `tasks` via `projectID`), **`referenceField`** on the five contract rows, and **`effectiveRequiredFields().unproven` / `.conditional`**.
+
+### Fixed
+
+- **#245: `tickets.forResource` `capped` is exact** (limit + 1 / next-page check), and closed secondary tickets under `openOnly` are no longer listed in `unresolvedIds` (one extra unfiltered `id in` read per chunk, only when ids are missing under `openOnly`). Docs now say results sort ascending by id.
+
+### Changed
+
+- **#246: `createGuidance` blocker `message` / `remedy` are clean model-facing text**; maintainer provenance moved into `vendorEvidence` (entries prefixed `maintainer provenance (...)`, plain text, not JSON). `delete-absent` rows (8) are now kind `ok` with the missing DELETE in `deleteBoundary`; the kind stays in the closed set with 0 rows and the build fails if a row carries it. `non-mutable` is documented as blocking creates (0 rows). A build clause fails on provenance patterns.
+- **`effectiveRequiredFields().fields` is the unconditional set**: `contracts.create` no longer returns `estimatedRevenue` / `estimatedHours` / `estimatedCost` there; they are in `conditional` (`contractType` 1).
+- Docs reconciled: 97 `createGuidance` rows (one per create op) and 99 `zoneFacts.resources` entries.
+
+### Consumer notes (iit-mcp-autotask re-pin)
+
+- Pass `allowAssumed: false` where an answer must not rest on the assumed `[5]`; pass `excludeStatusIds` to `companies.fullProfile`.
+- `blocker.message` / `remedy` and `parentCompany`, `unsatisfiableViaApi`, `referenceField` are now clean data: the fixed blocker-sentence map can be dropped where these carry the fact. Treat `kind: 'delete-absent'` as gone (0 rows) and read `effectiveRequiredFields().conditional` / `.unproven`.
+- Use `forResource({ countOnly: true })` for "how many tickets" questions.
+- Serve `metadata.caveats` instead of the hard-coded `time_entries.update` "ticketID does NOT persist" note.
+- Use `get(id, { fresh: true })` / `invokeRead({ fresh: true })` for read-backs instead of clearing `http.readCache`.
+- **Simple-get detection:** every id-addressed `get` `inputSchema` gained `opts` (125 records; the 62 root gets go from 1 key to 2). A consumer that detects a simple get with `Object.keys(inputSchema).length === 1` must count the non-`opts` keys instead. `opts` is closed (`{ fresh?: boolean }`): a positional bag with a non-boolean `fresh` or an unknown key is refused before any request, and a direct `get(id, null)` is an empty bag (`invokeRead` still refuses a null bag as a wrong-typed `opts`).
+- `forResource({ countOnly: true })` follows the link table's next-page links (up to 20 pages of 500) so `secondary` is exact below 10,000 links; `limit` is not validated there.
+
+## [0.33.0] - 2026-10-27
+
 Minor: the plan hash moves (a new op, and `contacts.create` / `contacts.update` lose the `sensitive` flag), so the next release is 0.33.0.
 
 ### Added

package/MCP_TOOL_CATALOG.json

@@ -1,7 +1,7 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-27T11:39:16.203Z",
-  "planHash": "913f1120488735c2e607cda13f9d551b11b3e6534d8a4b8310857d0bbd2fdb45",
+  "generatedAt": "2026-10-27T22:23:07.797Z",
+  "planHash": "08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1",
   "metaTools": [
     {
       "name": "autotask_catalog",

package/MCP_TOOL_MANIFEST.md

@@ -1,6 +1,6 @@
 # MCP Tool Manifest — node-autotask
 
-<!-- GENERATED by scripts/project-mcp-tools.mjs at 2026-10-27T11:39:16.407Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-mcp-tools.mjs at 2026-10-27T22:23:07.655Z — do not hand-edit. -->
 
 Mechanical MCP projection of the capability registry (generator-design section 7, ARCHITECTURE section 19.5).
 Tool names are the plan `mcpTool` columns (entity-first `autotask_<entity>_<verb>`); descriptions are the
@@ -8,7 +8,7 @@ registry `purpose` + a mechanical bounds/flags sentence; annotations derive from
 Curation edits live ONLY in `MCP_TOOL_OVERRIDES.json` (records `{ tool, field, newValue, reason }`).
 
 Registry: 1280 operations; projected tools: 896 (one per registry op with a non-null `mcpTool`);
-not projected (catalog/describe material): 384. planHash: `913f1120488735c2…`
+not projected (catalog/describe material): 384. planHash: `08cf890fa1b2b505…`
 
 ## Always-on core tier (CORE_RULE — computed, never a hand list)
 
@@ -1012,8 +1012,8 @@ the projection projects what the registry has and reports the gap so the Toolsmi
 
 ## Meta
 
-- generatedAt: 2026-10-27T11:39:16.407Z
-- planHash: 913f1120488735c2e607cda13f9d551b11b3e6534d8a4b8310857d0bbd2fdb45
+- generatedAt: 2026-10-27T22:23:07.655Z
+- planHash: 08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1
 - registry records: 1280
 - projected tools: 896
 - core tier: 15

package/N8N_MCP_MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "schema": "node-autotask n8n consumer mcp projection v1",
-  "generatedAt": "2026-10-27T11:39:16.557Z",
+  "generatedAt": "2026-10-27T22:23:07.920Z",
   "generator": "scripts/project-n8n-mcp.mjs",
   "inputs": {
     "capabilities": "capabilities.json (the capability registry — the single source of truth)",
@@ -3893,6 +3893,6 @@
     "approvalGatedWrites": 2,
     "destructiveExcluded": 4
   },
-  "capabilitiesHash": "ba97b65fc4424ba19d524a07a92892920d809ab6aa37fc7c79d849725e73861b",
+  "capabilitiesHash": "4d850b84e72acda55dc952629b05d99549026251567d7b9fa7f0e12ffa921d5e",
   "curationHash": "e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b"
 }

package/N8N_MCP_MANIFEST.md

@@ -1,6 +1,6 @@
 # N8N MCP Manifest — node-autotask (consumer projection)
 
-<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-27T11:39:16.557Z — do not hand-edit. -->
+<!-- GENERATED by scripts/project-n8n-mcp.mjs at 2026-10-27T22:23:07.920Z — do not hand-edit. -->
 
 The n8n CONSUMER projection of the capability registry: the canonical source for what the
 n8n-side MCP tools must expose. The SDK is canonical — this is a projection of it, never a
@@ -289,6 +289,6 @@ only via a recorded change to `n8n-mcp.curation.json`.
 
 ## Meta
 
-- generatedAt: 2026-10-27T11:39:16.557Z
-- capabilitiesHash: ba97b65fc4424ba19d524a07a92892920d809ab6aa37fc7c79d849725e73861b
+- generatedAt: 2026-10-27T22:23:07.920Z
+- capabilitiesHash: 4d850b84e72acda55dc952629b05d99549026251567d7b9fa7f0e12ffa921d5e
 - curationHash: e19117ce73e38d9aded3be7e7f077a4e185d2e10294622b76c17d67f63cf9e3b