node-autotask 0.21.0 → 0.24.0

package/dist/operations/index.d.cts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, f4 as BlindSurfaceInfo, f5 as RelationshipResource, f6 as BlindSurfaceInventory, f7 as BlindSurfaceRow, f8 as CreateBlockerKind, f9 as CreateGuidanceReport, fa as FieldCacheKind, g as AutotaskConfigError } from '../index-ByWYfNog.cjs';
-export { fb as FIELD_CACHE_KINDS } from '../index-ByWYfNog.cjs';
-import { I as Identifier, cE as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-BXtKN1M5.cjs';
-export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BXtKN1M5.cjs';
+import { a as AutotaskClient, ea as BlindSurfaceInfo, eb as RelationshipResource, ec as BlindSurfaceInventory, ed as BlindSurfaceRow, ee as CreateBlockerKind, ef as CreateGuidanceReport, Z as ZoneName, eg as FieldCacheKind, i as AutotaskConfigError } from '../index-C0OwQhon.cjs';
+export { eh as FIELD_CACHE_KINDS } from '../index-C0OwQhon.cjs';
+import { I as Identifier, cG as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-BVtycq-6.cjs';
+export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BVtycq-6.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
 
 /**
@@ -20,8 +20,10 @@ declare const WORKFLOW_RESOURCES: readonly string[];
 interface SearchAcrossResourcesOptions {
     /** Resource keys to search (default: the five workflow resources). */
     resources?: readonly string[];
-    /** Max matches per resource (default 25, max 500). */
+    /** Max matches PER RESOURCE (default 25, max 500) — a sweep over N resources can return up to N x limit matches; use `totalLimit` to cap the whole sweep. */
     limit?: number;
+    /** Optional cap on matches ACROSS ALL resources (positive integer). Resources are searched in request order, each asked for `min(limit, remaining)`; once the cap is met the remaining resources are not queried and are listed in `notSearched`. Absent = no cap and the result is unchanged. */
+    totalLimit?: number;
 }
 /** One searched resource's matches (compact shapes; `Summary = full record`). */
 interface SearchAcrossResourcesRow {
@@ -35,6 +37,10 @@ interface SearchAcrossResourcesResult {
     results: SearchAcrossResourcesRow[];
     /** Requested keys without a `search` helper — skipped and reported, never errored. */
     skipped: string[];
+    /** Only with `totalLimit`: resources that HAVE a `search` helper but were not queried because the cap was already met, in request order. */
+    notSearched?: string[];
+    /** Only with `totalLimit`: true when more matches may exist — some resource was not searched, or a searched resource returned exactly the quota it was asked for (`min(limit, remaining)`). */
+    truncated?: boolean;
 }
 /** One fetchMany item: a single-record GET by vendor numeric id. */
 interface FetchManyItem {
@@ -449,6 +455,68 @@ interface CreateGuidanceOptions {
  */
 declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<CreateGuidanceReport>;
 
+/** entity (plan resource key) -> ExecuteCommand `Code` + id parameter name. */
+declare const ENTITIES: {
+    readonly time_entries: {
+        readonly code: "EditTimeEntry";
+        readonly param: "WorkEntryID";
+    };
+    readonly tickets: {
+        readonly code: "OpenTicketDetail";
+        readonly param: "TicketID";
+    };
+    readonly tasks: {
+        readonly code: "OpenTaskDetail";
+        readonly param: "TaskID";
+    };
+    readonly projects: {
+        readonly code: "OpenProject";
+        readonly param: "ProjectID";
+    };
+    readonly companies: {
+        readonly code: "OpenAccount";
+        readonly param: "AccountID";
+    };
+    readonly contacts: {
+        readonly code: "OpenContact";
+        readonly param: "ContactID";
+    };
+    readonly contracts: {
+        readonly code: "OpenContract";
+        readonly param: "ContractID";
+    };
+    readonly configuration_items: {
+        readonly code: "EditInstalledProduct";
+        readonly param: "InstalledProductID";
+    };
+};
+type UiLinkEntity = keyof typeof ENTITIES;
+declare const UI_LINK_ENTITIES: UiLinkEntity[];
+/** The input of `buildUiLink` / `operations.uiLink`. */
+interface UiLinkInput {
+    /** The plan resource key of the record: one of UI_LINK_ENTITIES. */
+    entity: string;
+    /** The vendor numeric id (positive safe integer). */
+    id?: number;
+    /** Tickets only: the displayed ticket number (`T20240101.0001`); exclusive with `id`. */
+    ticketNumber?: string;
+    /** Explicit UI host (`ww<N>.autotask.net`), overriding derivation. */
+    host?: string;
+    /** A zone name from the catalog (derives the host the same way as the client base). */
+    zone?: ZoneName;
+    /** A REST base URL (e.g. the client's) to derive the host from. */
+    baseUrl?: string;
+}
+/** Build the deep link, or `undefined` when no UI host can be derived. Throws a typed CONFIG_ERROR on bad input. */
+declare function buildUiLink(input: UiLinkInput): string | undefined;
+/** The `operations.uiLink` result: the URL, or null with the reason no host could be derived. */
+interface UiLinkResult {
+    url: string | null;
+    reason?: string;
+}
+/** Zero-wire meta op: build the deep link from the client's live REST base (or an explicit `host`). */
+declare function uiLink(client: AutotaskClient, input: UiLinkInput): Promise<UiLinkResult>;
+
 /** The pinned wire cap: `resources × include` above it is refused
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
@@ -762,82 +830,6 @@ interface RecoveryOptions {
  */
 declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: RecoveryOptions): Promise<RecoveryResult>;
 
-/**
- * `operations.invoke` — the registry-driven call path with the WRITE
- * GOVERNOR (ARCHITECTURE section 19.5 R2–R4).
- *
- * The generated registry lists EVERY implemented operation; this module is
- * the deterministic call path for ones that are not a typed convenience of
- * their own. The MCP mode tools (`autotask_read` / `autotask_write` /
- * `autotask_delete`) dispatch through the same router with the mode pinned;
- * `invoke()` itself stays the programmatic escape hatch — its mode is derived
- * from the record, so it can never be cross-mode-refused.
- * It is deliberately MCP-independent — plain SDK code, no MCP import.
- *
- * ```ts
- * import { invoke } from 'node-autotask/operations';
- *
- * await invoke(client, 'companies.get', [3]);                                   // read: one request
- * await invoke(client, 'companies.update', [3, { companyName: 'A' }]);         // write: DRY RUN by default
- * await invoke(client, 'companies.update', [3, { companyName: 'A' }], { dryRun: false }); // apply
- * await invoke(client, 'companies.delete', [3], { dryRun: false, confirm: 'companies.delete' }); // destructive
- * ```
- *
- * Governor rules (pinned):
- * - the operation key must EXACTLY match a registry record (unknown keys
- *   refuse before any request);
- * - a mode-pinned call (the mode tools) REFUSES a cross-mode op before any
- *   request (the mode is the registry `effect`: read → `read`, write →
- *   `write`, destructive → `delete`; the refusal message carries the op key
- *   + the effect + the correct target tool — zero wire, it throws before
- *   holder/method resolution);
- * - a read REFUSES `dryRun: true` (a read has no dry run to run);
- * - a write is DRY-RUN-FIRST: unless the caller passes `dryRun: false`, the
- *   call travels with `dryRun: true` and the real mutating request is never
- *   issued (the result is the pinned `DryRunResult`, `simulated: true`);
- * - a destructive or approval-gated operation (registry `effect` +
- *   `flags`) REFUSES without its confirmation flag: `confirm` must equal the
- *   operation key exactly (no booleans, no fuzzy matching) — in BOTH dry-run
- *   and apply mode (the deliberate act is the call, not the write);
- * - query operations (`<resource>.query`) are routed to the resource's
- *   `queryBounded` (server-side pagination): ONE invoke call returns a
- *   bounded, complete-enough result — the vendor cursor walk happens inside
- *   the SDK; the caller passes `limit` as the TOTAL cap (default 500, max
- *   2500) and never owns a stream. `queryAll` keeps its raw behavior (the
- *   unbounded walk; the catalog text steers the caller away for normal work);
- * - the governor OPTIONS object is closed: an unknown option key (a typo of
- *   `dryRun` / `confirm` / `lastModifiedDate`) is refused pre-request (the
- *   key is named + the valid keys listed — never the values);
- * - the query-family params bag (`args[0]` for `query` / `queryAll` /
- *   `count`) is CLOSED at its top level: the valid key set is per-verb
- *   (PARAMS_BAG_KEYS — for `query` routed to `queryBounded`:
- *   filter / limit / latest / includeFields / via / fieldCheck) and an unknown key
- *   (`filters`, `lmit`, `pageSize`, `cursor`, …) is refused pre-request
- *   with a typed error naming the key + the valid keys + a did-you-mean
- *   (`last` → `latest`, issue #59); entity bodies,
- *   UDF maps and the filter tree stay open (strictness applies to tool
- *   arguments, not vendor payloads);
- * - the caller's `args` are validated against the record's declared
- *   `inputSchema` BEFORE the method is applied (pre-request, zero wire):
- *   MORE args than the declared positional list are REFUSED, FEWER than the
- *   required count are REFUSED, and scalar-typed args (number/string) are
- *   loosely type-checked — each refusal is a shape-teaching message naming
- *   the operation, the declared arg list (names + types) and the count
- *   passed (never the values — redaction discipline). v0.2.0 behavior
- *   change: extra args were SILENTLY DROPPED (the JS call ignores them);
- *   v0.3.0 refuses them, so a wrong-arity call can never shadow the
- *   governed trailing bag or land in the wrong positional slot. The
- *   governed `{ dryRun, lastModifiedDate? }` bag is NOT a declared arg —
- *   it travels through the invoke options and is appended by the router.
- *
- * Dispatch calls the SAME typed method the SDK publishes, with the caller's
- * `args` in the method's positional order; for writes the governed
- * `{ dryRun, lastModifiedDate? }` bag is appended as the method's final
- * `MutationOpts` argument. Every guard that path already has (bounded scans,
- * the stale check, the dry-run envelope) is that path's, not a second
- * implementation.
- */
-
 /** True for an operation that needs a deliberate act before it runs (R4). */
 declare function needsConfirmation(record: CapabilityRecord): boolean;
 /**
@@ -845,6 +837,7 @@ declare function needsConfirmation(record: CapabilityRecord): boolean;
  * verified one-to-one over all registry records.
  */
 type InvokeMode = 'read' | 'write' | 'delete';
+
 /**
  * Validate the caller's positional args against the record's declared
  * `inputSchema` (A-F2). Refusals are pre-request (zero wire) and shape-
@@ -852,8 +845,7 @@ type InvokeMode = 'read' | 'write' | 'delete';
  * and the count passed — never the values.
  *
  * Rules (the v0.2.0 → v0.3.0 tightening):
- * - MORE args than the declared positional list → REFUSED (v0.2.0 silently
- *   dropped them);
+ * - MORE args than the declared positional list → REFUSED;
  * - FEWER args than the required count → REFUSED (they would have landed in
  *   the wrong positional slot — a bare scalar where an object belongs);
  * - scalar-typed args (number/string/number[]/object) get a loose typeof
@@ -863,6 +855,7 @@ type InvokeMode = 'read' | 'write' | 'delete';
  * bare conditions array is refused here, not after the walk has started.
  */
 declare function validateDispatchArgs(record: CapabilityRecord, argsIn: readonly unknown[] | null | undefined): void;
+
 /** The CLOSED params-bag key set per query-family verb (`args[0]`).
  *  `query` routes to `queryBounded`, whose method reads only
  *  filter / limit / includeFields / via — `maxRecords` is ignored by it
@@ -907,6 +900,7 @@ declare function validateInvokeOptions(opts: Record<string, unknown> | undefined
  * MCP client's `list_tools`, which serves the tool's inputSchema.
  */
 declare function unknownKeysRefusal(raw: unknown, validKeys: readonly string[], subject: string, operation?: string): AutotaskConfigError | null;
+
 /**
  * Invoke one registry operation through its typed SDK method — the legacy
  * path (programmatic escape hatch). The mode is derived from the registry
@@ -934,4 +928,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, aggregate, blindSurfaces, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.d.ts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, f4 as BlindSurfaceInfo, f5 as RelationshipResource, f6 as BlindSurfaceInventory, f7 as BlindSurfaceRow, f8 as CreateBlockerKind, f9 as CreateGuidanceReport, fa as FieldCacheKind, g as AutotaskConfigError } from '../index-DSnuyiTr.js';
-export { fb as FIELD_CACHE_KINDS } from '../index-DSnuyiTr.js';
-import { I as Identifier, cE as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-BXtKN1M5.js';
-export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BXtKN1M5.js';
+import { a as AutotaskClient, ea as BlindSurfaceInfo, eb as RelationshipResource, ec as BlindSurfaceInventory, ed as BlindSurfaceRow, ee as CreateBlockerKind, ef as CreateGuidanceReport, Z as ZoneName, eg as FieldCacheKind, i as AutotaskConfigError } from '../index-CZ94y401.js';
+export { eh as FIELD_CACHE_KINDS } from '../index-CZ94y401.js';
+import { I as Identifier, cG as EmptyReasonInfo, dI as PickListValue, a as FilterCondition } from '../index-BVtycq-6.js';
+export { hp as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-BVtycq-6.js';
 import { CapabilityRecord } from '../capabilities.js';
 
 /**
@@ -20,8 +20,10 @@ declare const WORKFLOW_RESOURCES: readonly string[];
 interface SearchAcrossResourcesOptions {
     /** Resource keys to search (default: the five workflow resources). */
     resources?: readonly string[];
-    /** Max matches per resource (default 25, max 500). */
+    /** Max matches PER RESOURCE (default 25, max 500) — a sweep over N resources can return up to N x limit matches; use `totalLimit` to cap the whole sweep. */
     limit?: number;
+    /** Optional cap on matches ACROSS ALL resources (positive integer). Resources are searched in request order, each asked for `min(limit, remaining)`; once the cap is met the remaining resources are not queried and are listed in `notSearched`. Absent = no cap and the result is unchanged. */
+    totalLimit?: number;
 }
 /** One searched resource's matches (compact shapes; `Summary = full record`). */
 interface SearchAcrossResourcesRow {
@@ -35,6 +37,10 @@ interface SearchAcrossResourcesResult {
     results: SearchAcrossResourcesRow[];
     /** Requested keys without a `search` helper — skipped and reported, never errored. */
     skipped: string[];
+    /** Only with `totalLimit`: resources that HAVE a `search` helper but were not queried because the cap was already met, in request order. */
+    notSearched?: string[];
+    /** Only with `totalLimit`: true when more matches may exist — some resource was not searched, or a searched resource returned exactly the quota it was asked for (`min(limit, remaining)`). */
+    truncated?: boolean;
 }
 /** One fetchMany item: a single-record GET by vendor numeric id. */
 interface FetchManyItem {
@@ -449,6 +455,68 @@ interface CreateGuidanceOptions {
  */
 declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<CreateGuidanceReport>;
 
+/** entity (plan resource key) -> ExecuteCommand `Code` + id parameter name. */
+declare const ENTITIES: {
+    readonly time_entries: {
+        readonly code: "EditTimeEntry";
+        readonly param: "WorkEntryID";
+    };
+    readonly tickets: {
+        readonly code: "OpenTicketDetail";
+        readonly param: "TicketID";
+    };
+    readonly tasks: {
+        readonly code: "OpenTaskDetail";
+        readonly param: "TaskID";
+    };
+    readonly projects: {
+        readonly code: "OpenProject";
+        readonly param: "ProjectID";
+    };
+    readonly companies: {
+        readonly code: "OpenAccount";
+        readonly param: "AccountID";
+    };
+    readonly contacts: {
+        readonly code: "OpenContact";
+        readonly param: "ContactID";
+    };
+    readonly contracts: {
+        readonly code: "OpenContract";
+        readonly param: "ContractID";
+    };
+    readonly configuration_items: {
+        readonly code: "EditInstalledProduct";
+        readonly param: "InstalledProductID";
+    };
+};
+type UiLinkEntity = keyof typeof ENTITIES;
+declare const UI_LINK_ENTITIES: UiLinkEntity[];
+/** The input of `buildUiLink` / `operations.uiLink`. */
+interface UiLinkInput {
+    /** The plan resource key of the record: one of UI_LINK_ENTITIES. */
+    entity: string;
+    /** The vendor numeric id (positive safe integer). */
+    id?: number;
+    /** Tickets only: the displayed ticket number (`T20240101.0001`); exclusive with `id`. */
+    ticketNumber?: string;
+    /** Explicit UI host (`ww<N>.autotask.net`), overriding derivation. */
+    host?: string;
+    /** A zone name from the catalog (derives the host the same way as the client base). */
+    zone?: ZoneName;
+    /** A REST base URL (e.g. the client's) to derive the host from. */
+    baseUrl?: string;
+}
+/** Build the deep link, or `undefined` when no UI host can be derived. Throws a typed CONFIG_ERROR on bad input. */
+declare function buildUiLink(input: UiLinkInput): string | undefined;
+/** The `operations.uiLink` result: the URL, or null with the reason no host could be derived. */
+interface UiLinkResult {
+    url: string | null;
+    reason?: string;
+}
+/** Zero-wire meta op: build the deep link from the client's live REST base (or an explicit `host`). */
+declare function uiLink(client: AutotaskClient, input: UiLinkInput): Promise<UiLinkResult>;
+
 /** The pinned wire cap: `resources × include` above it is refused
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
@@ -762,82 +830,6 @@ interface RecoveryOptions {
  */
 declare function recovery(client: AutotaskClient, input: RecoveryInput, opts?: RecoveryOptions): Promise<RecoveryResult>;
 
-/**
- * `operations.invoke` — the registry-driven call path with the WRITE
- * GOVERNOR (ARCHITECTURE section 19.5 R2–R4).
- *
- * The generated registry lists EVERY implemented operation; this module is
- * the deterministic call path for ones that are not a typed convenience of
- * their own. The MCP mode tools (`autotask_read` / `autotask_write` /
- * `autotask_delete`) dispatch through the same router with the mode pinned;
- * `invoke()` itself stays the programmatic escape hatch — its mode is derived
- * from the record, so it can never be cross-mode-refused.
- * It is deliberately MCP-independent — plain SDK code, no MCP import.
- *
- * ```ts
- * import { invoke } from 'node-autotask/operations';
- *
- * await invoke(client, 'companies.get', [3]);                                   // read: one request
- * await invoke(client, 'companies.update', [3, { companyName: 'A' }]);         // write: DRY RUN by default
- * await invoke(client, 'companies.update', [3, { companyName: 'A' }], { dryRun: false }); // apply
- * await invoke(client, 'companies.delete', [3], { dryRun: false, confirm: 'companies.delete' }); // destructive
- * ```
- *
- * Governor rules (pinned):
- * - the operation key must EXACTLY match a registry record (unknown keys
- *   refuse before any request);
- * - a mode-pinned call (the mode tools) REFUSES a cross-mode op before any
- *   request (the mode is the registry `effect`: read → `read`, write →
- *   `write`, destructive → `delete`; the refusal message carries the op key
- *   + the effect + the correct target tool — zero wire, it throws before
- *   holder/method resolution);
- * - a read REFUSES `dryRun: true` (a read has no dry run to run);
- * - a write is DRY-RUN-FIRST: unless the caller passes `dryRun: false`, the
- *   call travels with `dryRun: true` and the real mutating request is never
- *   issued (the result is the pinned `DryRunResult`, `simulated: true`);
- * - a destructive or approval-gated operation (registry `effect` +
- *   `flags`) REFUSES without its confirmation flag: `confirm` must equal the
- *   operation key exactly (no booleans, no fuzzy matching) — in BOTH dry-run
- *   and apply mode (the deliberate act is the call, not the write);
- * - query operations (`<resource>.query`) are routed to the resource's
- *   `queryBounded` (server-side pagination): ONE invoke call returns a
- *   bounded, complete-enough result — the vendor cursor walk happens inside
- *   the SDK; the caller passes `limit` as the TOTAL cap (default 500, max
- *   2500) and never owns a stream. `queryAll` keeps its raw behavior (the
- *   unbounded walk; the catalog text steers the caller away for normal work);
- * - the governor OPTIONS object is closed: an unknown option key (a typo of
- *   `dryRun` / `confirm` / `lastModifiedDate`) is refused pre-request (the
- *   key is named + the valid keys listed — never the values);
- * - the query-family params bag (`args[0]` for `query` / `queryAll` /
- *   `count`) is CLOSED at its top level: the valid key set is per-verb
- *   (PARAMS_BAG_KEYS — for `query` routed to `queryBounded`:
- *   filter / limit / latest / includeFields / via / fieldCheck) and an unknown key
- *   (`filters`, `lmit`, `pageSize`, `cursor`, …) is refused pre-request
- *   with a typed error naming the key + the valid keys + a did-you-mean
- *   (`last` → `latest`, issue #59); entity bodies,
- *   UDF maps and the filter tree stay open (strictness applies to tool
- *   arguments, not vendor payloads);
- * - the caller's `args` are validated against the record's declared
- *   `inputSchema` BEFORE the method is applied (pre-request, zero wire):
- *   MORE args than the declared positional list are REFUSED, FEWER than the
- *   required count are REFUSED, and scalar-typed args (number/string) are
- *   loosely type-checked — each refusal is a shape-teaching message naming
- *   the operation, the declared arg list (names + types) and the count
- *   passed (never the values — redaction discipline). v0.2.0 behavior
- *   change: extra args were SILENTLY DROPPED (the JS call ignores them);
- *   v0.3.0 refuses them, so a wrong-arity call can never shadow the
- *   governed trailing bag or land in the wrong positional slot. The
- *   governed `{ dryRun, lastModifiedDate? }` bag is NOT a declared arg —
- *   it travels through the invoke options and is appended by the router.
- *
- * Dispatch calls the SAME typed method the SDK publishes, with the caller's
- * `args` in the method's positional order; for writes the governed
- * `{ dryRun, lastModifiedDate? }` bag is appended as the method's final
- * `MutationOpts` argument. Every guard that path already has (bounded scans,
- * the stale check, the dry-run envelope) is that path's, not a second
- * implementation.
- */
-
 /** True for an operation that needs a deliberate act before it runs (R4). */
 declare function needsConfirmation(record: CapabilityRecord): boolean;
 /**
@@ -845,6 +837,7 @@ declare function needsConfirmation(record: CapabilityRecord): boolean;
  * verified one-to-one over all registry records.
  */
 type InvokeMode = 'read' | 'write' | 'delete';
+
 /**
  * Validate the caller's positional args against the record's declared
  * `inputSchema` (A-F2). Refusals are pre-request (zero wire) and shape-
@@ -852,8 +845,7 @@ type InvokeMode = 'read' | 'write' | 'delete';
  * and the count passed — never the values.
  *
  * Rules (the v0.2.0 → v0.3.0 tightening):
- * - MORE args than the declared positional list → REFUSED (v0.2.0 silently
- *   dropped them);
+ * - MORE args than the declared positional list → REFUSED;
  * - FEWER args than the required count → REFUSED (they would have landed in
  *   the wrong positional slot — a bare scalar where an object belongs);
  * - scalar-typed args (number/string/number[]/object) get a loose typeof
@@ -863,6 +855,7 @@ type InvokeMode = 'read' | 'write' | 'delete';
  * bare conditions array is refused here, not after the walk has started.
  */
 declare function validateDispatchArgs(record: CapabilityRecord, argsIn: readonly unknown[] | null | undefined): void;
+
 /** The CLOSED params-bag key set per query-family verb (`args[0]`).
  *  `query` routes to `queryBounded`, whose method reads only
  *  filter / limit / includeFields / via — `maxRecords` is ignored by it
@@ -907,6 +900,7 @@ declare function validateInvokeOptions(opts: Record<string, unknown> | undefined
  * MCP client's `list_tools`, which serves the tool's inputSchema.
  */
 declare function unknownKeysRefusal(raw: unknown, validKeys: readonly string[], subject: string, operation?: string): AutotaskConfigError | null;
+
 /**
  * Invoke one registry operation through its typed SDK method — the legacy
  * path (programmatic escape hatch). The mode is derived from the registry
@@ -934,4 +928,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[], opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, WORKFLOW_RESOURCES, aggregate, blindSurfaces, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };