node-autotask 0.25.0 → 0.27.0

package/dist/{chunk-VUGZKP33.js → chunk-42ZUISDH.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-EFR2XWRX.js";
+} from "./chunk-F7FVOXPQ.js";
 
 // src/auth.ts
 var AUTH_HEADERS = {
@@ -583,6 +583,111 @@ var MoveRefusedError = class extends AutotaskError {
   }
 };
 
+// src/cache.ts
+var READ_CACHE_MAX_ENTRIES = 4096;
+var ReadCache = class {
+  /** The configured TTL in ms (the fallback for resources without an override). */
+  ttlMs;
+  /** The per-resource TTL overrides (issue #32; absent = every resource uses `ttlMs`). */
+  perResourceTtlMs;
+  store = /* @__PURE__ */ new Map();
+  epochCounter = 0;
+  constructor(ttlMs, perResourceTtlMs) {
+    if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+      throw new AutotaskConfigError(`cache.ttlMs must be a positive integer (got ${ttlMs})`);
+    }
+    if (perResourceTtlMs !== void 0) {
+      if (perResourceTtlMs === null || typeof perResourceTtlMs !== "object" || Array.isArray(perResourceTtlMs)) {
+        throw new AutotaskConfigError(
+          `cache.perResourceTtlMs must be an object of resource key -> ms (got ${String(perResourceTtlMs)})`
+        );
+      }
+      for (const [key, value] of Object.entries(perResourceTtlMs)) {
+        if (key === "") {
+          throw new AutotaskConfigError("cache.perResourceTtlMs keys must be non-empty resource keys");
+        }
+        if (!Number.isInteger(value) || value <= 0) {
+          throw new AutotaskConfigError(
+            `cache.perResourceTtlMs.${key} must be a positive integer (got ${String(value)})`
+          );
+        }
+      }
+    }
+    this.ttlMs = ttlMs;
+    this.perResourceTtlMs = perResourceTtlMs;
+  }
+  /**
+   * The TTL (ms) for a resource plan key: the `perResourceTtlMs` override
+   * when the map is present and names the resource, else the base
+   * `ttlMs` (absent map, absent key, and `undefined` all fall back).
+   */
+  ttlFor(resource) {
+    if (resource !== void 0 && this.perResourceTtlMs !== void 0) {
+      const override = this.perResourceTtlMs[resource];
+      if (override !== void 0) return override;
+    }
+    return this.ttlMs;
+  }
+  /**
+   * Read-through lookup: the live entry's value, or `undefined` (absent OR
+   * expired — an expired entry is purged lazily on this read).
+   */
+  get(key) {
+    const entry = this.store.get(key);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return structuredClone(entry.value);
+  }
+  /** Store a successful read payload under `key`, live for `ttlFor(resource)`:
+   * the per-resource override (issue #32) when named, else `ttlMs`.
+   * `epoch` is the invalidation epoch the caller captured BEFORE its wire
+   * read: a read that straddled a `clear()` (a write) is dropped, never
+   * re-stored with its pre-write body. */
+  set(key, value, resource, epoch = this.epochCounter) {
+    if (epoch !== this.epochCounter) return;
+    if (this.store.size >= READ_CACHE_MAX_ENTRIES && this.purgeExpired() === 0) {
+      const oldest = this.store.keys().next();
+      if (!oldest.done) this.store.delete(oldest.value);
+    }
+    this.store.delete(key);
+    this.store.set(key, { value: structuredClone(value), expiresAt: Date.now() + this.ttlFor(resource) });
+  }
+  /** Drop every expired entry (returns the number removed). */
+  purgeExpired() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt <= now) {
+        this.store.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  /** Current entry count (live + not-yet-purged expired). */
+  get size() {
+    return this.store.size;
+  }
+  /** Drop one key (issue #36: a later positive outcome clears a stale 'absent' marker). */
+  delete(key) {
+    return this.store.delete(key);
+  }
+  /** The invalidation epoch: bumped by `clear()`; capture it before a wire
+   * read and pass it to `set` so a read in flight across a write cannot
+   * re-store its stale answer. */
+  get epoch() {
+    return this.epochCounter;
+  }
+  /** Drop everything (e.g. a caller that knows the tenant was reset). */
+  clear() {
+    this.epochCounter += 1;
+    this.store.clear();
+  }
+};
+
 // src/config/zones.ts
 var ZONE_CATALOG = {
   "pre-release": "https://webservices2.autotask.net/atservicesrest",
@@ -689,6 +794,7 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
   "appointments": 3e5,
   "authenticate": 3e5,
   "billing_codes": 36e5,
+  "billing_item_approval_levels": 3e5,
   "billing_items": 3e5,
   "change_request_links": 3e5,
   "checklist_libraries": 3e5,
@@ -737,6 +843,7 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
   "contract_ticket_purchases": 3e5,
   "contracts": 3e5,
   "countries": 36e5,
+  "currencies": 3e5,
   "departments": 36e5,
   "domain_registrars": 3e5,
   "entity_information": 3e5,
@@ -746,12 +853,16 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
   "holiday_sets": 3e5,
   "holidays": 3e5,
   "inventory_products": 3e5,
+  "invoice_templates": 3e5,
   "invoices": 3e5,
   "modules": 3e5,
   "notification_history": 3e5,
   "opportunities": 3e5,
   "opportunity_attachments": 3e5,
   "opportunity_categories": 3e5,
+  "organizational_level1s": 3e5,
+  "organizational_level2s": 3e5,
+  "organizational_level_associations": 3e5,
   "phases": 36e5,
   "product_vendors": 3e5,
   "products": 3e5,
@@ -774,6 +885,7 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
   "resource_time_off_balances": 3e5,
   "resources": 3e5,
   "roles": 36e5,
+  "sales_orders": 3e5,
   "service_call_task_resources": 3e5,
   "service_call_tasks": 3e5,
   "service_call_ticket_resources": 3e5,
@@ -791,6 +903,7 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
   "tags": 3e5,
   "task_secondary_resources": 3e5,
   "tasks": 3e5,
+  "tax_regions": 3e5,
   "threshold_information": 3e5,
   "ticket_additional_configuration_items": 3e5,
   "ticket_additional_contacts": 3e5,
@@ -818,6 +931,7 @@ var DEFAULT_PER_RESOURCE_TTL_MS = {
 var RESOURCE_KEY_BY_PATH = {
   "/V1.0/Appointments": "appointments",
   "/V1.0/BillingCodes": "billing_codes",
+  "/V1.0/BillingItemApprovalLevels": "billing_item_approval_levels",
   "/V1.0/BillingItems": "billing_items",
   "/V1.0/ChangeRequestLinks": "change_request_links",
   "/V1.0/ChecklistLibraries": "checklist_libraries",
@@ -866,6 +980,7 @@ var RESOURCE_KEY_BY_PATH = {
   "/V1.0/ContractTicketPurchases": "contract_ticket_purchases",
   "/V1.0/Contracts": "contracts",
   "/V1.0/Countries": "countries",
+  "/V1.0/Currencies": "currencies",
   "/V1.0/Departments": "departments",
   "/V1.0/DomainRegistrars": "domain_registrars",
   "/V1.0/ExpenseItemAttachments": "expense_item_attachments",
@@ -874,11 +989,15 @@ var RESOURCE_KEY_BY_PATH = {
   "/V1.0/HolidaySets": "holiday_sets",
   "/V1.0/Holidays": "holidays",
   "/V1.0/InventoryProducts": "inventory_products",
+  "/V1.0/InvoiceTemplates": "invoice_templates",
   "/V1.0/Invoices": "invoices",
   "/V1.0/NotificationHistory": "notification_history",
   "/V1.0/Opportunities": "opportunities",
   "/V1.0/OpportunityAttachments": "opportunity_attachments",
   "/V1.0/OpportunityCategories": "opportunity_categories",
+  "/V1.0/OrganizationalLevel1s": "organizational_level1s",
+  "/V1.0/OrganizationalLevel2s": "organizational_level2s",
+  "/V1.0/OrganizationalLevelAssociations": "organizational_level_associations",
   "/V1.0/Phases": "phases",
   "/V1.0/ProductVendors": "product_vendors",
   "/V1.0/Products": "products",
@@ -901,6 +1020,7 @@ var RESOURCE_KEY_BY_PATH = {
   "/V1.0/ResourceTimeOffBalances": "resource_time_off_balances",
   "/V1.0/Resources": "resources",
   "/V1.0/Roles": "roles",
+  "/V1.0/SalesOrders": "sales_orders",
   "/V1.0/ServiceCallTaskResources": "service_call_task_resources",
   "/V1.0/ServiceCallTasks": "service_call_tasks",
   "/V1.0/ServiceCallTicketResources": "service_call_ticket_resources",
@@ -918,6 +1038,7 @@ var RESOURCE_KEY_BY_PATH = {
   "/V1.0/Tags": "tags",
   "/V1.0/TaskSecondaryResources": "task_secondary_resources",
   "/V1.0/Tasks": "tasks",
+  "/V1.0/TaxRegions": "tax_regions",
   "/V1.0/TicketAdditionalConfigurationItems": "ticket_additional_configuration_items",
   "/V1.0/TicketAdditionalContacts": "ticket_additional_contacts",
   "/V1.0/TicketAttachments": "ticket_attachments",
@@ -1245,111 +1366,6 @@ function cooldownDurationMs(retryAfterSecs, opts) {
   return Math.min(rawMs, opts.maxMs);
 }
 
-// src/cache.ts
-var READ_CACHE_MAX_ENTRIES = 4096;
-var ReadCache = class {
-  /** The configured TTL in ms (the fallback for resources without an override). */
-  ttlMs;
-  /** The per-resource TTL overrides (issue #32; absent = every resource uses `ttlMs`). */
-  perResourceTtlMs;
-  store = /* @__PURE__ */ new Map();
-  epochCounter = 0;
-  constructor(ttlMs, perResourceTtlMs) {
-    if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
-      throw new AutotaskConfigError(`cache.ttlMs must be a positive integer (got ${ttlMs})`);
-    }
-    if (perResourceTtlMs !== void 0) {
-      if (perResourceTtlMs === null || typeof perResourceTtlMs !== "object" || Array.isArray(perResourceTtlMs)) {
-        throw new AutotaskConfigError(
-          `cache.perResourceTtlMs must be an object of resource key -> ms (got ${String(perResourceTtlMs)})`
-        );
-      }
-      for (const [key, value] of Object.entries(perResourceTtlMs)) {
-        if (key === "") {
-          throw new AutotaskConfigError("cache.perResourceTtlMs keys must be non-empty resource keys");
-        }
-        if (!Number.isInteger(value) || value <= 0) {
-          throw new AutotaskConfigError(
-            `cache.perResourceTtlMs.${key} must be a positive integer (got ${String(value)})`
-          );
-        }
-      }
-    }
-    this.ttlMs = ttlMs;
-    this.perResourceTtlMs = perResourceTtlMs;
-  }
-  /**
-   * The TTL (ms) for a resource plan key: the `perResourceTtlMs` override
-   * when the map is present and names the resource, else the base
-   * `ttlMs` (absent map, absent key, and `undefined` all fall back).
-   */
-  ttlFor(resource) {
-    if (resource !== void 0 && this.perResourceTtlMs !== void 0) {
-      const override = this.perResourceTtlMs[resource];
-      if (override !== void 0) return override;
-    }
-    return this.ttlMs;
-  }
-  /**
-   * Read-through lookup: the live entry's value, or `undefined` (absent OR
-   * expired — an expired entry is purged lazily on this read).
-   */
-  get(key) {
-    const entry = this.store.get(key);
-    if (entry === void 0) return void 0;
-    if (entry.expiresAt <= Date.now()) {
-      this.store.delete(key);
-      return void 0;
-    }
-    return structuredClone(entry.value);
-  }
-  /** Store a successful read payload under `key`, live for `ttlFor(resource)`:
-   * the per-resource override (issue #32) when named, else `ttlMs`.
-   * `epoch` is the invalidation epoch the caller captured BEFORE its wire
-   * read: a read that straddled a `clear()` (a write) is dropped, never
-   * re-stored with its pre-write body. */
-  set(key, value, resource, epoch = this.epochCounter) {
-    if (epoch !== this.epochCounter) return;
-    if (this.store.size >= READ_CACHE_MAX_ENTRIES && this.purgeExpired() === 0) {
-      const oldest = this.store.keys().next();
-      if (!oldest.done) this.store.delete(oldest.value);
-    }
-    this.store.delete(key);
-    this.store.set(key, { value: structuredClone(value), expiresAt: Date.now() + this.ttlFor(resource) });
-  }
-  /** Drop every expired entry (returns the number removed). */
-  purgeExpired() {
-    const now = Date.now();
-    let removed = 0;
-    for (const [key, entry] of this.store) {
-      if (entry.expiresAt <= now) {
-        this.store.delete(key);
-        removed += 1;
-      }
-    }
-    return removed;
-  }
-  /** Current entry count (live + not-yet-purged expired). */
-  get size() {
-    return this.store.size;
-  }
-  /** Drop one key (issue #36: a later positive outcome clears a stale 'absent' marker). */
-  delete(key) {
-    return this.store.delete(key);
-  }
-  /** The invalidation epoch: bumped by `clear()`; capture it before a wire
-   * read and pass it to `set` so a read in flight across a write cannot
-   * re-store its stale answer. */
-  get epoch() {
-    return this.epochCounter;
-  }
-  /** Drop everything (e.g. a caller that knows the tenant was reset). */
-  clear() {
-    this.epochCounter += 1;
-    this.store.clear();
-  }
-};
-
 // src/resourceNameCache.ts
 var RESOURCE_NAME_CACHE_MAX_ENTRIES = 1024;
 var RESOURCE_NAME_CACHE_BLIND_TTL_MS = 6e4;
@@ -1833,12 +1849,10 @@ function resolveResolution(config, agent) {
 }
 function resolveCaches(config) {
   const cacheBlock = config.cache === false || config.cache === void 0 ? void 0 : config.cache;
+  resolveReadCacheStore(cacheBlock);
   const fieldCacheBlock = config.fieldCache === false || config.fieldCache === void 0 ? void 0 : config.fieldCache;
   const resourceNameCacheBlock = config.resourceNameCache === false || config.resourceNameCache === void 0 ? void 0 : config.resourceNameCache;
-  const readCache = config.cache === false ? void 0 : new ReadCache(
-    cacheBlock?.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS,
-    { ...DEFAULT_PER_RESOURCE_TTL_MS, ...cacheBlock?.perResourceTtlMs }
-  );
+  const readCache = config.cache === false ? void 0 : cacheBlock?.store ?? buildReadCache(config);
   const fieldCache = config.fieldCache === false ? void 0 : new FieldCache(
     fieldCacheBlock?.ttlMs ?? DEFAULT_FIELD_CACHE_TTL_MS,
     fieldCacheBlock?.maxEntities ?? FIELD_CACHE_MAX_ENTITIES
@@ -1849,6 +1863,27 @@ function resolveCaches(config) {
   );
   return { readCache, fieldCache, resourceNameCache };
 }
+function resolveReadCacheStore(cacheBlock) {
+  if (cacheBlock === void 0 || cacheBlock === false || cacheBlock.store === void 0) return;
+  if (!(cacheBlock.store instanceof ReadCache)) {
+    throw new AutotaskConfigError(
+      "cache.store must be a ReadCache instance (import { ReadCache } from the SDK; the pool supplies its own)"
+    );
+  }
+  if (cacheBlock.ttlMs !== void 0 || cacheBlock.perResourceTtlMs !== void 0) {
+    throw new AutotaskConfigError(
+      "cache.store cannot be combined with cache.ttlMs or cache.perResourceTtlMs \u2014 the supplied ReadCache instance owns its TTLs"
+    );
+  }
+}
+function buildReadCache(config) {
+  if (config.cache === false) return void 0;
+  const cacheBlock = config.cache === void 0 ? void 0 : config.cache;
+  return new ReadCache(
+    cacheBlock?.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS,
+    { ...DEFAULT_PER_RESOURCE_TTL_MS, ...cacheBlock?.perResourceTtlMs }
+  );
+}
 function resolveConfig(config) {
   if (config === null || typeof config !== "object") {
     throw new AutotaskConfigError("AutotaskConfig is required");
@@ -2353,6 +2388,52 @@ var RELATIONSHIP_MAP = {
     "deleteBoundary": null,
     "markerField": null
   },
+  "billing_item_approval_levels": {
+    "resource": "billing_item_approval_levels",
+    "apiEntity": "BillingItemApprovalLevel",
+    "kind": "entity",
+    "path": "BillingItemApprovalLevels",
+    "parentScoped": false,
+    "tier": "extended",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": {
+      "createGuidance": {
+        "createOp": "billing_item_approval_levels.create",
+        "parentScoped": false,
+        "liveProvenPrefix": [],
+        "unproven": true,
+        "blocker": {
+          "kind": "unknown",
+          "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/time-entry-approve) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the conditions (timeEntryID and approvalResourceID must reference existing objects) and the side effect (TimeEntry.BillingApprovalLevelMostRecent is updated; approvalDateTime / approvalResourceID are not), but the acceptance of the model body is unverified.",
+          "remedy": "attempt one create against a time entry in a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+        },
+        "vendorEvidence": [
+          'Vendor help, BillingItemApprovalLevels entity page (fetched 2026-10-26): "describes a multi-level approval record for an Autotask time entry ... This option is only available through the REST API."',
+          'Vendor help, BillingItemApprovalLevels entity page (fetched 2026-10-26): "When the BillingItemApprovalLevels entity is created, the TimeEntry.BillingApprovalLevelMostRecent field is updated, but approvalDateTime and approvalResourceID are not. Instead, the approvalDateTime and approvalResourceID fields are editable on the TimeEntry entity. Workaround: ... create the BillingItemApprovalLevel and then follow that call up with an update to the TimeEntry to set the BillingApprovalDateTime and BillingApprovalResourceID fields."',
+          "api-docs.json: POST /V1.0/BillingItemApprovalLevels consumes definitions.BillingItemApprovalLevelModel and answers OperationResultModel \u2014 the entity defines no PUT, PATCH or DELETE path."
+        ],
+        "deleteBoundary": {
+          "available": false,
+          "note": "the vendor defines no DELETE for billing_item_approval_levels (spec-derived) \u2014 an approval level cannot be removed or corrected through the API; record cleanup is UI-only."
+        },
+        "zone": "ww29"
+      }
+    },
+    "deleteBoundary": {
+      "note": "the vendor defines no DELETE for billing_item_approval_levels (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 an approval level cannot be removed or corrected through the API; record cleanup is UI-only.",
+      "proof": "spec-derived"
+    },
+    "markerField": null
+  },
   "billing_items": {
     "resource": "billing_items",
     "apiEntity": "BillingItems",
@@ -5076,8 +5157,8 @@ var RELATIONSHIP_MAP = {
         "unproven": false,
         "blocker": {
           "kind": "ok",
-          "message": "live-PROVEN 2026-10-06 (confirm-100, marker CONF100-1791187382): the W-A6 'blind parent' was companyID \u2014 an OWNED company satisfies it (seed 30132785). Proven contractType values: 1, 3 (Fixed Price), 4 (Block hours), 6 (Retainer), 7 (Recurring Services), 8 (PerTicket incident); type 5 is an invalid picklist value. Type-specific extra fields: types 1/3/4/6/8 require estimatedRevenue (type 1 additionally estimatedHours + estimatedCost); type 7 additionally contractPeriodType (2 valid) + setupFee. Proven ids 30131842-30131847 (residue \u2014 no vendor DELETE for contracts).",
-          "remedy": "live-proven on ww29 2026-10-06 (confirm-100, marker CONF100-1791187382) \u2014 use the proven body / type gates from the message; residue records are ledgered (.run/confirm-100-20261006/CONFIRMATION-LEDGER.md section E; UI cleanup)"
+          "message": "live-PROVEN 2026-10-06 (confirm-100, marker CONF100-1791187382): the W-A6 'blind parent' was companyID \u2014 an OWNED company satisfies it (seed 30132785). Proven contractType values: 1, 3 (Fixed Price), 4 (Block hours), 6 (Retainer), 7 (Recurring Services), 8 (PerTicket incident). The type-conditioned field gates are declared in requiresByValue / rejectedValues on this row (issue #219 N3) \u2014 they are no longer restated in prose here. Proven ids 30131842-30131847 (residue \u2014 no vendor DELETE for contracts).",
+          "remedy": "live-proven on ww29 2026-10-06 (confirm-100, marker CONF100-1791187382) \u2014 send the body with the contractType you need and satisfy that value's requiresByValue gate (plus the contractPeriodType value it names); residue records are ledgered (.run/confirm-100-20261006/CONFIRMATION-LEDGER.md section E; UI cleanup)"
         },
         "vendorEvidence": [
           '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"contracts.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"25d4a730-6d6c-49ff-a038-96d3fd09165d","message":"Value does not exist for the required fiel',
@@ -5087,7 +5168,75 @@ var RELATIONSHIP_MAP = {
           "available": false,
           "note": "the vendor defines no DELETE for contracts (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only."
         },
-        "zone": "ww29"
+        "zone": "ww29",
+        "requiresByValue": [
+          {
+            "field": "contractType",
+            "value": 1,
+            "requires": {
+              "allOf": [
+                "estimatedRevenue",
+                "estimatedHours",
+                "estimatedCost"
+              ]
+            }
+          },
+          {
+            "field": "contractType",
+            "value": 3,
+            "requires": {
+              "allOf": [
+                "estimatedRevenue"
+              ]
+            }
+          },
+          {
+            "field": "contractType",
+            "value": 4,
+            "requires": {
+              "allOf": [
+                "estimatedRevenue"
+              ]
+            }
+          },
+          {
+            "field": "contractType",
+            "value": 6,
+            "requires": {
+              "allOf": [
+                "estimatedRevenue"
+              ]
+            }
+          },
+          {
+            "field": "contractType",
+            "value": 7,
+            "requires": {
+              "allOf": [
+                "contractPeriodType",
+                "setupFee"
+              ]
+            },
+            "values": {
+              "contractPeriodType": 2
+            }
+          },
+          {
+            "field": "contractType",
+            "value": 8,
+            "requires": {
+              "allOf": [
+                "estimatedRevenue"
+              ]
+            }
+          }
+        ],
+        "rejectedValues": [
+          {
+            "field": "contractType",
+            "value": 5
+          }
+        ]
       }
     },
     "deleteBoundary": {
@@ -5117,6 +5266,27 @@ var RELATIONSHIP_MAP = {
     "deleteBoundary": null,
     "markerField": null
   },
+  "currencies": {
+    "resource": "currencies",
+    "apiEntity": "Currency",
+    "kind": "entity",
+    "path": "Currencies",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": true,
+      "searchCovers": "name only (contains)",
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": null,
+    "deleteBoundary": null,
+    "markerField": null
+  },
   "departments": {
     "resource": "departments",
     "apiEntity": "Department",
@@ -5504,6 +5674,27 @@ var RELATIONSHIP_MAP = {
     "deleteBoundary": null,
     "markerField": null
   },
+  "invoice_templates": {
+    "resource": "invoice_templates",
+    "apiEntity": "InvoiceTemplate",
+    "kind": "entity",
+    "path": "InvoiceTemplates",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": null,
+    "deleteBoundary": null,
+    "markerField": null
+  },
   "invoices": {
     "resource": "invoices",
     "apiEntity": "Invoice",
@@ -5694,6 +5885,138 @@ var RELATIONSHIP_MAP = {
     "deleteBoundary": null,
     "markerField": null
   },
+  "organizational_level1s": {
+    "resource": "organizational_level1s",
+    "apiEntity": "OrganizationalLevel1",
+    "kind": "entity",
+    "path": "OrganizationalLevel1s",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": {
+      "createGuidance": {
+        "createOp": "organizational_level1s.create",
+        "parentScoped": false,
+        "liveProvenPrefix": [],
+        "unproven": true,
+        "blocker": {
+          "kind": "unknown",
+          "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevel1Model) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+          "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+        },
+        "vendorEvidence": [
+          "api-docs.json: POST /V1.0/OrganizationalLevel1s consumes definitions.OrganizationalLevel1Model and answers OperationResultModel \u2014 the entity defines no DELETE path."
+        ],
+        "deleteBoundary": {
+          "available": false,
+          "note": "the vendor defines no DELETE for organizational_level1s (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+        },
+        "zone": "ww29"
+      }
+    },
+    "deleteBoundary": {
+      "note": "the vendor defines no DELETE for organizational_level1s (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+      "proof": "spec-derived"
+    },
+    "markerField": null
+  },
+  "organizational_level2s": {
+    "resource": "organizational_level2s",
+    "apiEntity": "OrganizationalLevel2",
+    "kind": "entity",
+    "path": "OrganizationalLevel2s",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": {
+      "createGuidance": {
+        "createOp": "organizational_level2s.create",
+        "parentScoped": false,
+        "liveProvenPrefix": [],
+        "unproven": true,
+        "blocker": {
+          "kind": "unknown",
+          "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevel2Model) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+          "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+        },
+        "vendorEvidence": [
+          "api-docs.json: POST /V1.0/OrganizationalLevel2s consumes definitions.OrganizationalLevel2Model and answers OperationResultModel \u2014 the entity defines no DELETE path."
+        ],
+        "deleteBoundary": {
+          "available": false,
+          "note": "the vendor defines no DELETE for organizational_level2s (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+        },
+        "zone": "ww29"
+      }
+    },
+    "deleteBoundary": {
+      "note": "the vendor defines no DELETE for organizational_level2s (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+      "proof": "spec-derived"
+    },
+    "markerField": null
+  },
+  "organizational_level_associations": {
+    "resource": "organizational_level_associations",
+    "apiEntity": "OrganizationalLevelAssociation",
+    "kind": "entity",
+    "path": "OrganizationalLevelAssociations",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": {
+      "createGuidance": {
+        "createOp": "organizational_level_associations.create",
+        "parentScoped": false,
+        "liveProvenPrefix": [],
+        "unproven": true,
+        "blocker": {
+          "kind": "unknown",
+          "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevelAssociationModel) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+          "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+        },
+        "vendorEvidence": [
+          "api-docs.json: POST /V1.0/OrganizationalLevelAssociations consumes definitions.OrganizationalLevelAssociationModel and answers OperationResultModel \u2014 the entity defines no DELETE path."
+        ],
+        "deleteBoundary": {
+          "available": false,
+          "note": "the vendor defines no DELETE for organizational_level_associations (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+        },
+        "zone": "ww29"
+      }
+    },
+    "deleteBoundary": {
+      "note": "the vendor defines no DELETE for organizational_level_associations (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+      "proof": "spec-derived"
+    },
+    "markerField": null
+  },
   "product_vendors": {
     "resource": "product_vendors",
     "apiEntity": "ProductVendors",
@@ -5846,7 +6169,13 @@ var RELATIONSHIP_MAP = {
         "blocker": {
           "kind": "blind-parent",
           "message": "vendor 500 (stage-11 apply-matrix, marker FULL100W-1791110339): the create consumed the vendor field ladder and then failed on the parent reference \u2014 the parent table is blind (0 rows) for this API user, so no valid parent id exists to satisfy it (W-A6). The exact final vendor response is preserved verbatim in vendorEvidence (campaign receipt artifact, as recorded on disk).",
-          "remedy": "provision a parent record in the Autotask UI first \u2014 the projects table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id."
+          "remedy": "provision a parent record in the Autotask UI first \u2014 the projects table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id.",
+          "requires": {
+            "anyOf": [
+              "productID",
+              "billingCodeID"
+            ]
+          }
         },
         "vendorEvidence": [
           '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"project_charges.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"664ab2ea-408f-4834-a331-eb5dd55ac557","message":"A productID or a billingCodeID must '
@@ -6919,6 +7248,27 @@ var RELATIONSHIP_MAP = {
     },
     "markerField": "name"
   },
+  "sales_orders": {
+    "resource": "sales_orders",
+    "apiEntity": "SalesOrder",
+    "kind": "entity",
+    "path": "SalesOrders",
+    "parentScoped": false,
+    "tier": "extended",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": null,
+    "deleteBoundary": null,
+    "markerField": null
+  },
   "service_call_task_resources": {
     "resource": "service_call_task_resources",
     "apiEntity": "ServiceCallTaskResource",
@@ -7577,26 +7927,70 @@ var RELATIONSHIP_MAP = {
     "blindSurfaces": null,
     "zoneFacts": {
       "createGuidance": {
-        "createOp": "task_secondary_resources.create",
-        "parentScoped": true,
+        "createOp": "task_secondary_resources.create",
+        "parentScoped": true,
+        "liveProvenPrefix": [],
+        "unproven": true,
+        "blocker": {
+          "kind": "unknown",
+          "message": "vendor 500: reference rejection on r (exact vendor text preserved verbatim in vendorEvidence \u2014 campaign receipt artifact, as recorded on disk)",
+          "remedy": "the wall is opaque in the campaign record \u2014 inspect vendorEvidence for the exact vendor text, re-run the create with a live probe (dry-run first), and adjudicate against the vendored spec before retrying."
+        },
+        "vendorEvidence": [
+          '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"task_secondary_resources.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"d2783d1d-b23a-4c7d-9459-0089be7f9b0b","message":"Reference value on field: r'
+        ],
+        "deleteBoundary": {
+          "available": true,
+          "note": null
+        },
+        "zone": "ww29"
+      }
+    },
+    "deleteBoundary": null,
+    "markerField": null
+  },
+  "tax_regions": {
+    "resource": "tax_regions",
+    "apiEntity": "TaxRegion",
+    "kind": "entity",
+    "path": "TaxRegions",
+    "parentScoped": false,
+    "tier": "advanced",
+    "workflowResource": false,
+    "group": "B",
+    "parent": null,
+    "children": [],
+    "naturalKeys": {
+      "hasSearch": false,
+      "searchCovers": null,
+      "findBy": []
+    },
+    "blindSurfaces": null,
+    "zoneFacts": {
+      "createGuidance": {
+        "createOp": "tax_regions.create",
+        "parentScoped": false,
         "liveProvenPrefix": [],
         "unproven": true,
         "blocker": {
           "kind": "unknown",
-          "message": "vendor 500: reference rejection on r (exact vendor text preserved verbatim in vendorEvidence \u2014 campaign receipt artifact, as recorded on disk)",
-          "remedy": "the wall is opaque in the campaign record \u2014 inspect vendorEvidence for the exact vendor text, re-run the create with a live probe (dry-run first), and adjudicate against the vendored spec before retrying."
+          "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.TaxRegionModel) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+          "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
         },
         "vendorEvidence": [
-          '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"task_secondary_resources.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"d2783d1d-b23a-4c7d-9459-0089be7f9b0b","message":"Reference value on field: r'
+          "api-docs.json: POST /V1.0/TaxRegions consumes definitions.TaxRegionModel and answers OperationResultModel \u2014 the entity defines no DELETE path."
         ],
         "deleteBoundary": {
-          "available": true,
-          "note": null
+          "available": false,
+          "note": "the vendor defines no DELETE for tax_regions (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
         },
         "zone": "ww29"
       }
     },
-    "deleteBoundary": null,
+    "deleteBoundary": {
+      "note": "the vendor defines no DELETE for tax_regions (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+      "proof": "spec-derived"
+    },
     "markerField": null
   },
   "ticket_additional_configuration_items": {
@@ -7888,7 +8282,13 @@ var RELATIONSHIP_MAP = {
         "blocker": {
           "kind": "blind-parent",
           "message": "vendor 500 (stage-11 apply-matrix, marker FULL100W-1791110339): the create consumed the vendor field ladder and then failed on the parent reference \u2014 the parent table is blind (0 rows) for this API user, so no valid parent id exists to satisfy it (W-A6). The exact final vendor response is preserved verbatim in vendorEvidence (campaign receipt artifact, as recorded on disk).",
-          "remedy": "provision a parent record in the Autotask UI first \u2014 the tickets table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id."
+          "remedy": "provision a parent record in the Autotask UI first \u2014 the tickets table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id.",
+          "requires": {
+            "anyOf": [
+              "productID",
+              "billingCodeID"
+            ]
+          }
         },
         "vendorEvidence": [
           '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"ticket_charges.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"b9b6939b-ccc5-4e9d-9ea2-e2f47d064f63","message":"A productID or a billingCodeID must b'
@@ -8954,6 +9354,7 @@ var BLIND_SURFACE_STAMPS = {
   }
 };
 var DELETE_BOUNDARY_NOTES = {
+  "billing_item_approval_levels": "the vendor defines no DELETE for billing_item_approval_levels (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 an approval level cannot be removed or corrected through the API; record cleanup is UI-only.",
   "companies": "the vendor defines no DELETE for companies (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "company_notes": "the vendor defines no DELETE for company_notes (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "configuration_item_categories": "the vendor defines no DELETE for configuration_item_categories (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
@@ -8977,6 +9378,9 @@ var DELETE_BOUNDARY_NOTES = {
   "expense_items": "the vendor defines no DELETE for expense_items (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "expense_reports": "the vendor defines no DELETE for expense_reports (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "opportunities": "the vendor defines no DELETE for opportunities (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+  "organizational_level1s": "the vendor defines no DELETE for organizational_level1s (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+  "organizational_level2s": "the vendor defines no DELETE for organizational_level2s (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+  "organizational_level_associations": "the vendor defines no DELETE for organizational_level_associations (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "phases": "the vendor defines no DELETE for phases (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "product_vendors": "the vendor defines no DELETE for product_vendors (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "products": "the vendor defines no DELETE for products (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
@@ -8991,6 +9395,7 @@ var DELETE_BOUNDARY_NOTES = {
   "roles": "the vendor defines no DELETE for roles (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "services": "the vendor defines no DELETE for services (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "tasks": "the vendor defines no DELETE for tasks (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
+  "tax_regions": "the vendor defines no DELETE for tax_regions (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "ticket_checklist_libraries": "the vendor defines no DELETE for ticket_checklist_libraries (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "ticket_notes": "the vendor defines no DELETE for ticket_notes (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only.",
   "tickets": "the vendor defines no DELETE for tickets (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only."
@@ -10492,6 +10897,18 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "billing_codes count/query are pinned blind in this zone (plan.blindSurfaces pin, byte-identical sentinel) \u2014 the discovery sweep confirmed 0 rows unfiltered (limit-2 read, marker FULL100-SEED-1791096521); get(id) is the authority.",
       "proof": "live-verified"
     },
+    {
+      "resource": "billing_item_approval_levels",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "billing_item_approval_levels.get",
+      "note": "billing_item_approval_levels was added to the plan on 2026-10-26 (feat/time-entry-approve) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record; query by timeEntryID is the intended read.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "billing_items",
       "ops": [
@@ -11044,6 +11461,18 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "ww29 discovery sweep (marker FULL100-SEED-1791096521, 2026-10-04): the unfiltered limit-2 read returned 0 rows \u2014 INCONCLUSIVE (tenant-empty-for-user vs blind for this API user; a 0/empty result here proves nothing). countries.get is the authority for a specific record.",
       "proof": "discovery-sweep"
     },
+    {
+      "resource": "currencies",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "currencies.get",
+      "note": "Not swept: currencies was added after the ww29 discovery sweep, so no unfiltered read has been made for any tenant. Whether this API user sees currency rows through count/query is unknown; currencies.get is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "departments",
       "ops": [
@@ -11140,6 +11569,18 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "ww29 discovery sweep (marker FULL100-SEED-1791096521, 2026-10-04): the unfiltered limit-2 read returned 1 row(s) \u2014 data-full for this API user (unfiltered reads are safe here; no blind class assigned).",
       "proof": "discovery-sweep"
     },
+    {
+      "resource": "invoice_templates",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "invoice_templates.get",
+      "note": "invoice_templates was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "invoices",
       "ops": [
@@ -11200,6 +11641,42 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "ww29 discovery sweep (marker FULL100-SEED-1791096521, 2026-10-04): the unfiltered limit-2 read returned 2 row(s) \u2014 data-full for this API user (unfiltered reads are safe here; no blind class assigned).",
       "proof": "discovery-sweep"
     },
+    {
+      "resource": "organizational_level1s",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "organizational_level1s.get",
+      "note": "organizational_level1s was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
+    {
+      "resource": "organizational_level2s",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "organizational_level2s.get",
+      "note": "organizational_level2s was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
+    {
+      "resource": "organizational_level_associations",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "organizational_level_associations.get",
+      "note": "organizational_level_associations was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "phases",
       "ops": [
@@ -11440,6 +11917,18 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "ww29 discovery sweep (marker FULL100-SEED-1791096521, 2026-10-04): the unfiltered limit-2 read returned 2 row(s) \u2014 data-full for this API user (unfiltered reads are safe here; no blind class assigned).",
       "proof": "discovery-sweep"
     },
+    {
+      "resource": "sales_orders",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "sales_orders.get",
+      "note": "sales_orders was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "service_call_task_resources",
       "ops": [
@@ -11644,6 +12133,18 @@ var BLIND_SURFACE_INVENTORY = {
       "note": "ww29 discovery sweep (marker FULL100-SEED-1791096521, 2026-10-04): the unfiltered limit-2 read returned 2 row(s) \u2014 data-full for this API user (unfiltered reads are safe here; no blind class assigned).",
       "proof": "discovery-sweep"
     },
+    {
+      "resource": "tax_regions",
+      "ops": [
+        "count",
+        "query"
+      ],
+      "kind": "unknown",
+      "unfilteredRows": null,
+      "authority": "tax_regions.get",
+      "note": "tax_regions was added to the plan on 2026-10-26 (feat/guidance-contract-027) and has NEVER been swept \u2014 no discovery read has run against this zone, so the surface is unverified, not blind. get(id) is the authority for a specific record.",
+      "proof": "spec-derived"
+    },
     {
       "resource": "ticket_additional_configuration_items",
       "ops": [
@@ -11862,7 +12363,7 @@ var BLIND_SURFACE_INVENTORY = {
     }
   ],
   "counts": {
-    "total": 116,
+    "total": 124,
     "dataFull": 46,
     "blind": 69,
     "pinned": 6
@@ -11932,6 +12433,7 @@ var REACHABILITY_PROBE_DEFAULTS = {
   "defaultTargets": [
     "appointments",
     "billing_codes",
+    "billing_item_approval_levels",
     "billing_items",
     "change_request_links",
     "classification_icons",
@@ -11964,10 +12466,15 @@ var REACHABILITY_PROBE_DEFAULTS = {
     "contract_ticket_purchases",
     "contracts",
     "countries",
+    "currencies",
     "expense_items",
     "expense_reports",
+    "invoice_templates",
     "invoices",
     "notification_history",
+    "organizational_level1s",
+    "organizational_level2s",
+    "organizational_level_associations",
     "product_vendors",
     "products",
     "project_charges",
@@ -11982,6 +12489,7 @@ var REACHABILITY_PROBE_DEFAULTS = {
     "resource_roles",
     "resource_skills",
     "resources",
+    "sales_orders",
     "service_call_task_resources",
     "service_call_tasks",
     "service_call_ticket_resources",
@@ -11991,6 +12499,7 @@ var REACHABILITY_PROBE_DEFAULTS = {
     "skills",
     "subscription_periods",
     "subscriptions",
+    "tax_regions",
     "ticket_change_request_approvals",
     "ticket_charges",
     "ticket_history",
@@ -12031,6 +12540,28 @@ var CREATE_GUIDANCE = {
       },
       "zone": "ww29"
     },
+    {
+      "resource": "billing_item_approval_levels",
+      "createOp": "billing_item_approval_levels.create",
+      "parentScoped": false,
+      "liveProvenPrefix": [],
+      "unproven": true,
+      "blocker": {
+        "kind": "unknown",
+        "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/time-entry-approve) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the conditions (timeEntryID and approvalResourceID must reference existing objects) and the side effect (TimeEntry.BillingApprovalLevelMostRecent is updated; approvalDateTime / approvalResourceID are not), but the acceptance of the model body is unverified.",
+        "remedy": "attempt one create against a time entry in a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+      },
+      "vendorEvidence": [
+        'Vendor help, BillingItemApprovalLevels entity page (fetched 2026-10-26): "describes a multi-level approval record for an Autotask time entry ... This option is only available through the REST API."',
+        'Vendor help, BillingItemApprovalLevels entity page (fetched 2026-10-26): "When the BillingItemApprovalLevels entity is created, the TimeEntry.BillingApprovalLevelMostRecent field is updated, but approvalDateTime and approvalResourceID are not. Instead, the approvalDateTime and approvalResourceID fields are editable on the TimeEntry entity. Workaround: ... create the BillingItemApprovalLevel and then follow that call up with an update to the TimeEntry to set the BillingApprovalDateTime and BillingApprovalResourceID fields."',
+        "api-docs.json: POST /V1.0/BillingItemApprovalLevels consumes definitions.BillingItemApprovalLevelModel and answers OperationResultModel \u2014 the entity defines no PUT, PATCH or DELETE path."
+      ],
+      "deleteBoundary": {
+        "available": false,
+        "note": "the vendor defines no DELETE for billing_item_approval_levels (spec-derived) \u2014 an approval level cannot be removed or corrected through the API; record cleanup is UI-only."
+      },
+      "zone": "ww29"
+    },
     {
       "resource": "change_request_links",
       "createOp": "change_request_links.create",
@@ -12962,8 +13493,8 @@ var CREATE_GUIDANCE = {
       "unproven": false,
       "blocker": {
         "kind": "ok",
-        "message": "live-PROVEN 2026-10-06 (confirm-100, marker CONF100-1791187382): the W-A6 'blind parent' was companyID \u2014 an OWNED company satisfies it (seed 30132785). Proven contractType values: 1, 3 (Fixed Price), 4 (Block hours), 6 (Retainer), 7 (Recurring Services), 8 (PerTicket incident); type 5 is an invalid picklist value. Type-specific extra fields: types 1/3/4/6/8 require estimatedRevenue (type 1 additionally estimatedHours + estimatedCost); type 7 additionally contractPeriodType (2 valid) + setupFee. Proven ids 30131842-30131847 (residue \u2014 no vendor DELETE for contracts).",
-        "remedy": "live-proven on ww29 2026-10-06 (confirm-100, marker CONF100-1791187382) \u2014 use the proven body / type gates from the message; residue records are ledgered (.run/confirm-100-20261006/CONFIRMATION-LEDGER.md section E; UI cleanup)"
+        "message": "live-PROVEN 2026-10-06 (confirm-100, marker CONF100-1791187382): the W-A6 'blind parent' was companyID \u2014 an OWNED company satisfies it (seed 30132785). Proven contractType values: 1, 3 (Fixed Price), 4 (Block hours), 6 (Retainer), 7 (Recurring Services), 8 (PerTicket incident). The type-conditioned field gates are declared in requiresByValue / rejectedValues on this row (issue #219 N3) \u2014 they are no longer restated in prose here. Proven ids 30131842-30131847 (residue \u2014 no vendor DELETE for contracts).",
+        "remedy": "live-proven on ww29 2026-10-06 (confirm-100, marker CONF100-1791187382) \u2014 send the body with the contractType you need and satisfy that value's requiresByValue gate (plus the contractPeriodType value it names); residue records are ledgered (.run/confirm-100-20261006/CONFIRMATION-LEDGER.md section E; UI cleanup)"
       },
       "vendorEvidence": [
         '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"contracts.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"25d4a730-6d6c-49ff-a038-96d3fd09165d","message":"Value does not exist for the required fiel',
@@ -12973,7 +13504,75 @@ var CREATE_GUIDANCE = {
         "available": false,
         "note": "the vendor defines no DELETE for contracts (spec-derived: the vendored api-docs.json defines no DELETE on the entity's paths) \u2014 a create cannot be undone through the API; cleanup is UI-only."
       },
-      "zone": "ww29"
+      "zone": "ww29",
+      "requiresByValue": [
+        {
+          "field": "contractType",
+          "value": 1,
+          "requires": {
+            "allOf": [
+              "estimatedRevenue",
+              "estimatedHours",
+              "estimatedCost"
+            ]
+          }
+        },
+        {
+          "field": "contractType",
+          "value": 3,
+          "requires": {
+            "allOf": [
+              "estimatedRevenue"
+            ]
+          }
+        },
+        {
+          "field": "contractType",
+          "value": 4,
+          "requires": {
+            "allOf": [
+              "estimatedRevenue"
+            ]
+          }
+        },
+        {
+          "field": "contractType",
+          "value": 6,
+          "requires": {
+            "allOf": [
+              "estimatedRevenue"
+            ]
+          }
+        },
+        {
+          "field": "contractType",
+          "value": 7,
+          "requires": {
+            "allOf": [
+              "contractPeriodType",
+              "setupFee"
+            ]
+          },
+          "values": {
+            "contractPeriodType": 2
+          }
+        },
+        {
+          "field": "contractType",
+          "value": 8,
+          "requires": {
+            "allOf": [
+              "estimatedRevenue"
+            ]
+          }
+        }
+      ],
+      "rejectedValues": [
+        {
+          "field": "contractType",
+          "value": 5
+        }
+      ]
     },
     {
       "resource": "departments",
@@ -13219,6 +13818,66 @@ var CREATE_GUIDANCE = {
       },
       "zone": "ww29"
     },
+    {
+      "resource": "organizational_level1s",
+      "createOp": "organizational_level1s.create",
+      "parentScoped": false,
+      "liveProvenPrefix": [],
+      "unproven": true,
+      "blocker": {
+        "kind": "unknown",
+        "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevel1Model) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+        "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+      },
+      "vendorEvidence": [
+        "api-docs.json: POST /V1.0/OrganizationalLevel1s consumes definitions.OrganizationalLevel1Model and answers OperationResultModel \u2014 the entity defines no DELETE path."
+      ],
+      "deleteBoundary": {
+        "available": false,
+        "note": "the vendor defines no DELETE for organizational_level1s (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+      },
+      "zone": "ww29"
+    },
+    {
+      "resource": "organizational_level2s",
+      "createOp": "organizational_level2s.create",
+      "parentScoped": false,
+      "liveProvenPrefix": [],
+      "unproven": true,
+      "blocker": {
+        "kind": "unknown",
+        "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevel2Model) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+        "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+      },
+      "vendorEvidence": [
+        "api-docs.json: POST /V1.0/OrganizationalLevel2s consumes definitions.OrganizationalLevel2Model and answers OperationResultModel \u2014 the entity defines no DELETE path."
+      ],
+      "deleteBoundary": {
+        "available": false,
+        "note": "the vendor defines no DELETE for organizational_level2s (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+      },
+      "zone": "ww29"
+    },
+    {
+      "resource": "organizational_level_associations",
+      "createOp": "organizational_level_associations.create",
+      "parentScoped": false,
+      "liveProvenPrefix": [],
+      "unproven": true,
+      "blocker": {
+        "kind": "unknown",
+        "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.OrganizationalLevelAssociationModel) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+        "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+      },
+      "vendorEvidence": [
+        "api-docs.json: POST /V1.0/OrganizationalLevelAssociations consumes definitions.OrganizationalLevelAssociationModel and answers OperationResultModel \u2014 the entity defines no DELETE path."
+      ],
+      "deleteBoundary": {
+        "available": false,
+        "note": "the vendor defines no DELETE for organizational_level_associations (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+      },
+      "zone": "ww29"
+    },
     {
       "resource": "phases",
       "createOp": "phases.create",
@@ -13300,7 +13959,13 @@ var CREATE_GUIDANCE = {
       "blocker": {
         "kind": "blind-parent",
         "message": "vendor 500 (stage-11 apply-matrix, marker FULL100W-1791110339): the create consumed the vendor field ladder and then failed on the parent reference \u2014 the parent table is blind (0 rows) for this API user, so no valid parent id exists to satisfy it (W-A6). The exact final vendor response is preserved verbatim in vendorEvidence (campaign receipt artifact, as recorded on disk).",
-        "remedy": "provision a parent record in the Autotask UI first \u2014 the projects table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id."
+        "remedy": "provision a parent record in the Autotask UI first \u2014 the projects table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id.",
+        "requires": {
+          "anyOf": [
+            "productID",
+            "billingCodeID"
+          ]
+        }
       },
       "vendorEvidence": [
         '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"project_charges.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"664ab2ea-408f-4834-a331-eb5dd55ac557","message":"A productID or a billingCodeID must '
@@ -13804,6 +14469,26 @@ var CREATE_GUIDANCE = {
       },
       "zone": "ww29"
     },
+    {
+      "resource": "tax_regions",
+      "createOp": "tax_regions.create",
+      "parentScoped": false,
+      "liveProvenPrefix": [],
+      "unproven": true,
+      "blocker": {
+        "kind": "unknown",
+        "message": "never live-probed: this entity reached the plan on 2026-10-26 (feat/guidance-contract-027) after the stage-11 apply matrix closed, so no create has been attempted against a tenant. The vendor documents the model body (definitions.TaxRegionModel) and answers OperationResultModel, but acceptance of the body is unverified; the spec defines no DELETE on the entity's paths.",
+        "remedy": "attempt one create against a non-production tenant (dry-run first), then promote createGuidance to kind ok with its liveProvenPrefix; a refusal arrives as a vendor 500 whose errors[] text names the failing field."
+      },
+      "vendorEvidence": [
+        "api-docs.json: POST /V1.0/TaxRegions consumes definitions.TaxRegionModel and answers OperationResultModel \u2014 the entity defines no DELETE path."
+      ],
+      "deleteBoundary": {
+        "available": false,
+        "note": "the vendor defines no DELETE for tax_regions (spec-derived) \u2014 a record cannot be removed or corrected through the API; cleanup is UI-only."
+      },
+      "zone": "ww29"
+    },
     {
       "resource": "ticket_additional_configuration_items",
       "createOp": "ticket_additional_configuration_items.create",
@@ -13909,7 +14594,13 @@ var CREATE_GUIDANCE = {
       "blocker": {
         "kind": "blind-parent",
         "message": "vendor 500 (stage-11 apply-matrix, marker FULL100W-1791110339): the create consumed the vendor field ladder and then failed on the parent reference \u2014 the parent table is blind (0 rows) for this API user, so no valid parent id exists to satisfy it (W-A6). The exact final vendor response is preserved verbatim in vendorEvidence (campaign receipt artifact, as recorded on disk).",
-        "remedy": "provision a parent record in the Autotask UI first \u2014 the tickets table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id."
+        "remedy": "provision a parent record in the Autotask UI first \u2014 the tickets table is blind (0 rows) for this API user (W-A6), so no valid parent id can be read back; then retry the create with the real parent id.",
+        "requires": {
+          "anyOf": [
+            "productID",
+            "billingCodeID"
+          ]
+        }
       },
       "vendorEvidence": [
         '{"error":true,"code":"SERVER_ERROR","category":"server","retryable":true,"httpStatus":500,"operation":"ticket_charges.create","suggestedAction":"Retry with backoff; the server error is transient.","correlationId":"b9b6939b-ccc5-4e9d-9ea2-e2f47d064f63","message":"A productID or a billingCodeID must b'
@@ -14132,7 +14823,30 @@ var CREATE_GUIDANCE = {
         "available": true,
         "note": null
       },
-      "zone": "ww29"
+      "zone": "ww29",
+      "derived": [
+        {
+          "field": "hoursWorked",
+          "rule": "elapsed(startDateTime,endDateTime)"
+        },
+        {
+          "field": "timeEntryType",
+          "rule": "parent"
+        },
+        {
+          "field": "contractID",
+          "rule": "parent"
+        },
+        {
+          "field": "internalBillingCodeID",
+          "rule": "mirror(billingCodeID)"
+        },
+        {
+          "field": "billingApprovalLevelMostRecent",
+          "rule": "external",
+          "writableRoute": "billing_item_approval_levels.create"
+        }
+      ]
     },
     {
       "resource": "time_entry_attachments",
@@ -14161,7 +14875,7 @@ var CREATE_GUIDANCE = {
     }
   ],
   "counts": {
-    "total": 92,
+    "total": 97,
     "byKind": {
       "ok": 31,
       "blind-reference": 16,
@@ -14171,7 +14885,7 @@ var CREATE_GUIDANCE = {
       "resource-role-pair": 2,
       "delete-absent": 8,
       "non-mutable": 0,
-      "unknown": 12
+      "unknown": 17
     }
   }
 };
@@ -14400,6 +15114,10 @@ var UNTRUSTED_FIELDS_BY_RESOURCE = {
     "displayName",
     "name"
   ],
+  "currencies": [
+    "description",
+    "name"
+  ],
   "departments": [
     "description",
     "name"
@@ -14467,6 +15185,13 @@ var UNTRUSTED_FIELDS_BY_RESOURCE = {
   "holidays": [
     "holidayName"
   ],
+  "invoice_templates": [
+    "coveredByBlockRetainerContractLabel",
+    "coveredByRecurringServiceFixedPricePerTicketContractLabel",
+    "name",
+    "nonBillableLaborLabel",
+    "rateCostExpression"
+  ],
   "invoices": [
     "comments",
     "taxRegionName"
@@ -14515,6 +15240,14 @@ var UNTRUSTED_FIELDS_BY_RESOURCE = {
     "name",
     "nickname"
   ],
+  "organizational_level1s": [
+    "description",
+    "name"
+  ],
+  "organizational_level2s": [
+    "description",
+    "name"
+  ],
   "products": [
     "UDF1",
     "UDF10",
@@ -14652,6 +15385,34 @@ var UNTRUSTED_FIELDS_BY_RESOURCE = {
     "description",
     "name"
   ],
+  "sales_orders": [
+    "UDF1",
+    "UDF10",
+    "UDF11",
+    "UDF12",
+    "UDF13",
+    "UDF14",
+    "UDF15",
+    "UDF16",
+    "UDF17",
+    "UDF18",
+    "UDF19",
+    "UDF2",
+    "UDF20",
+    "UDF3",
+    "UDF4",
+    "UDF5",
+    "UDF6",
+    "UDF7",
+    "UDF8",
+    "UDF9",
+    "additionalBillToAddressInformation",
+    "additionalShipToAddressInformation",
+    "billToPostalCode",
+    "shipToCity",
+    "shipToState",
+    "title"
+  ],
   "service_calls": [
     "description"
   ],
@@ -14726,6 +15487,9 @@ var UNTRUSTED_FIELDS_BY_RESOURCE = {
   "tags": [
     "label"
   ],
+  "tax_regions": [
+    "name"
+  ],
   "ticket_attachments": [
     "title"
   ],
@@ -16248,6 +17012,38 @@ async function expandResourceNames(client, ids, opts = {}) {
   return { results, resolved, blind, failed };
 }
 
+// src/operations/entityType.ts
+function buildEntityTypeMap() {
+  const exact = {};
+  for (const [resource, entry] of Object.entries(RELATIONSHIP_MAP)) {
+    const apiEntity = entry.apiEntity;
+    if (typeof apiEntity !== "string" || apiEntity === "") continue;
+    if (exact[apiEntity] === void 0) exact[apiEntity] = resource;
+  }
+  const aliases = {};
+  for (const [apiEntity, resource] of Object.entries(exact)) {
+    if (!apiEntity.endsWith("s") || apiEntity.endsWith("ss")) continue;
+    const singular = apiEntity.slice(0, -1);
+    if (exact[singular] !== void 0 || aliases[singular] !== void 0) continue;
+    aliases[singular] = resource;
+  }
+  return { ...exact, ...aliases };
+}
+var ENTITY_TYPE_TO_RESOURCE = buildEntityTypeMap();
+var ENUMERABLE_RESOURCES = new Set(
+  CAPABILITIES.filter((rec) => rec.resource !== "operations" && (rec.operation === "query" || rec.operation === "get")).map(
+    (rec) => rec.resource
+  )
+);
+function resourceForEntityType(entityType) {
+  if (typeof entityType !== "string" || entityType === "") return null;
+  return ENTITY_TYPE_TO_RESOURCE[entityType] ?? null;
+}
+function isEnumerableResource(resource) {
+  if (typeof resource !== "string" || resource === "") return false;
+  return ENUMERABLE_RESOURCES.has(resource);
+}
+
 // src/operations/types.ts
 var WORKFLOW_RESOURCES = [
   "companies",
@@ -16261,24 +17057,36 @@ var WORKFLOW_RESOURCES = [
 var MAX_FIELD_CATALOG_WIRE = 60;
 var FIELD_CATALOG_HONESTY_NOTE = "Live field metadata reports the SHAPE of a field (existence, requiredness, type, maxLength, read-only, queryable, picklist-ness) as FLAGS and NAMES: picklist-ness as a flag (isPickList) and picklist field names (picklistFields). With the opt-in `labels: true`, picklist rows carry the vendor's exposed picklist VALUES (labels next to each value); without it the op serves no VALUES. It cannot resolve a picklist VALUE the vendor does not expose to this API user (the W-A4 wall \u2014 e.g. the attachments Type picklist): retrying the catalog will not surface a withheld value; that gap is vendor-side, not a client defect.";
 var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels"];
-function projectFieldRow(raw, labels = false) {
+function projectFieldRow(raw, labels = false, udf = false) {
   const r = typeof raw === "object" && raw !== null ? raw : {};
   const name = typeof r.name === "string" ? r.name : "";
   const type = typeof r.dataType === "string" ? r.dataType : typeof r.type === "string" ? r.type : "";
   const values = labels && r.isPickList === true && Array.isArray(r.picklistValues) && r.picklistValues.length > 0 ? r.picklistValues : void 0;
+  const referenceEntityType = typeof r.referenceEntityType === "string" ? r.referenceEntityType : "";
+  const targetResource = resourceForEntityType(referenceEntityType);
   return {
     name,
     ...typeof r.label === "string" && r.label !== "" ? { label: r.label } : {},
     type,
     isRequired: r.isRequired === true,
     isReadOnly: r.isReadOnly === true,
-    isQueryable: r.isQueryable === true,
+    // Issue #219 N7: a UDF row never serves the vendor's isQueryable (it is
+    // true for UDFs while a plain filter on a UDF name is refused); it serves
+    // the marker the filter actually needs.
+    ...udf ? { filterable: "udf-marker" } : { isQueryable: r.isQueryable === true },
     isPickList: r.isPickList === true,
+    ...isObjectOrArrayType(type) ? { writeShape: "replace-all" } : {},
     maxLength: typeof r.length === "number" ? r.length : null,
-    referenceEntityType: typeof r.referenceEntityType === "string" ? r.referenceEntityType : "",
+    referenceEntityType,
+    targetResource,
+    targetEnumerable: isEnumerableResource(targetResource),
     ...values !== void 0 ? { picklistValues: values } : {}
   };
 }
+function isObjectOrArrayType(type) {
+  const t = type.trim().toLowerCase();
+  return t === "object" || t === "array" || t === "collection" || t.endsWith("[]");
+}
 function exposesPicklistValues(raw) {
   const r = typeof raw === "object" && raw !== null ? raw : {};
   return Array.isArray(r.picklistValues) && r.picklistValues.length > 0;
@@ -16308,6 +17116,27 @@ function capabilitySets() {
   }
   return { fieldOps, udfOps, resources };
 }
+var derivedIndex = null;
+function derivedFieldsFor(resource) {
+  if (derivedIndex === null) {
+    derivedIndex = /* @__PURE__ */ new Map();
+    for (const rec of CAPABILITIES) {
+      const declared = rec.metadata?.derivedFields;
+      if (!Array.isArray(declared) || derivedIndex.has(rec.resource)) continue;
+      const rows = [];
+      for (const row of declared) {
+        if (typeof row?.field !== "string" || typeof row.rule !== "string") continue;
+        rows.push({
+          field: row.field,
+          rule: row.rule,
+          ...typeof row.writableRoute === "string" ? { writableRoute: row.writableRoute } : {}
+        });
+      }
+      derivedIndex.set(rec.resource, rows);
+    }
+  }
+  return derivedIndex.get(resource) ?? [];
+}
 function apiEntityFor(rec) {
   const m = /^GET \/V1\.0\/([^/]+)\/entityInformation\/fields$/.exec(rec.endpoint ?? "");
   if (m === null) {
@@ -16437,6 +17266,8 @@ async function sweepResource(ctx, resource, tally) {
     resource,
     apiEntity,
     udfCapable: ctx.udfOps.has(resource),
+    // Issue #219 N7: the UDF surface is declared with the mechanism, not a boolean.
+    ...ctx.udfOps.has(resource) ? { udfFilter: "udf-marker", udfWriteShape: "merge" } : {},
     unmatchedFields: [],
     required: [],
     readOnly: [],
@@ -16449,7 +17280,7 @@ async function sweepResource(ctx, resource, tally) {
   const fetches = kindFetches(holder, resource);
   if (fresh) cache?.invalidate(resource);
   const projectList = (kind, list) => {
-    const projected = list.map((f) => projectFieldRow(f, labels));
+    const projected = list.map((f) => projectFieldRow(f, labels, kind === "udf"));
     if (kind === "fields") applyFieldsFilter(projected, fieldsFilter, row);
     else row.udf = projected;
     for (const f of list) if (exposesPicklistValues(f)) tally.anyPicklistValues = true;
@@ -16489,6 +17320,19 @@ async function sweepResource(ctx, resource, tally) {
     }
   }
   row.cache = allCached ? { hit: true, age: ages.length > 0 ? Math.max(...ages) : 0 } : { hit: false, age: null };
+  const declared = derivedFieldsFor(resource);
+  if (declared.length > 0) {
+    const byField = new Map(declared.map((d) => [d.field, d]));
+    row.derivedFields = declared;
+    for (const field of row.fields ?? []) {
+      const derivation = byField.get(field.name);
+      if (derivation === void 0) continue;
+      field.derived = {
+        rule: derivation.rule,
+        ...derivation.writableRoute !== void 0 ? { writableRoute: derivation.writableRoute } : {}
+      };
+    }
+  }
   return row;
 }
 async function fieldCatalog(client, opts) {
@@ -16712,6 +17556,7 @@ async function resolveCompositeNames(http, plan, opts = {}) {
 var MODEL_FIELD_SETS = {
   "appointments": ["id", "createDateTime", "creatorResourceID", "description", "endDateTime", "resourceID", "startDateTime", "title", "updateDateTime"],
   "billing_codes": ["id", "afterHoursWorkType", "billingCodeType", "department", "description", "externalNumber", "generalLedgerAccount", "isActive", "isExcludedFromNewContracts", "markupRate", "name", "taxCategoryID", "unitCost", "unitPrice", "useType"],
+  "billing_item_approval_levels": ["id", "approvalDateTime", "approvalLevel", "approvalResourceID", "timeEntryID"],
   "billing_items": ["id", "accountManagerWhenApprovedID", "billingCodeID", "billingItemType", "companyID", "configurationItemID", "contractBlockID", "contractChargeID", "contractID", "contractServiceAdjustmentID", "contractServiceBundleAdjustmentID", "contractServiceBundleID", "contractServiceBundlePeriodID", "contractServiceID", "contractServicePeriodID", "description", "expenseItemID", "extendedPrice", "internalCurrencyExtendedPrice", "internalCurrencyRate", "internalCurrencyTaxDollars", "internalCurrencyTotalAmount", "invoiceID", "itemApproverID", "itemDate", "itemName", "lineItemFullDescription", "lineItemGroupDescription", "milestoneID", "nonBillable", "organizationalLevelAssociationID", "ourCost", "postedDate", "postedOnTime", "projectChargeID", "projectID", "purchaseOrderNumber", "quantity", "rate", "roleID", "serviceBundleID", "serviceID", "sortOrderID", "subType", "taskID", "taxDollars", "ticketChargeID", "ticketID", "timeEntryID", "totalAmount", "vendorID", "webServiceDate"],
   "change_request_links": ["id", "changeRequestTicketID", "problemOrIncidentTicketID"],
   "checklist_libraries": ["id", "description", "entityType", "isActive", "name"],
@@ -16758,6 +17603,7 @@ var MODEL_FIELD_SETS = {
   "contract_ticket_purchases": ["id", "contractID", "datePurchased", "endDate", "invoiceNumber", "isPaid", "paymentNumber", "paymentType", "perTicketRate", "startDate", "status", "ticketsPurchased", "ticketsUsed", "soapParentPropertyId"],
   "contracts": ["id", "billingPreference", "billToCompanyContactID", "billToCompanyID", "companyID", "contactID", "contactName", "contractCategory", "contractExclusionSetID", "contractName", "contractNumber", "contractPeriodType", "contractType", "description", "endDate", "estimatedCost", "estimatedHours", "estimatedRevenue", "exclusionContractID", "internalCurrencyOverageBillingRate", "internalCurrencySetupFee", "isCompliant", "isDefaultContract", "lastModifiedDateTime", "opportunityID", "organizationalLevelAssociationID", "overageBillingRate", "purchaseOrderNumber", "renewedContractID", "serviceLevelAgreementID", "setupFee", "setupFeeBillingCodeID", "startDate", "status", "timeReportingRequiresStartAndStopTimes", "userDefinedFields"],
   "countries": ["id", "addressFormatID", "countryCode", "displayName", "invoiceTemplateID", "isActive", "isDefaultCountry", "name", "purchaseOrderTemplateID", "quoteTemplateID"],
+  "currencies": ["id", "currencyNegativeFormat", "currencyPositiveFormat", "description", "displaySymbol", "exchangeRate", "isActive", "isInternalCurrency", "lastModifiedDateTime", "name", "updateResourceId"],
   "departments": ["id", "description", "name", "number", "primaryLocationID"],
   "domain_registrars": ["id", "name", "url"],
   "expense_item_attachments": ["id", "attachDate", "attachedByContactID", "attachedByResourceID", "attachmentType", "contentType", "creatorType", "expenseItemID", "expenseReportID", "fileSize", "fullPath", "impersonatorCreatorResourceID", "opportunityID", "parentID", "publish", "title", "data", "parentType", "soapParentPropertyId", "isTaskAttachment"],
@@ -16766,11 +17612,15 @@ var MODEL_FIELD_SETS = {
   "holiday_sets": ["id", "holidaySetDescription", "holidaySetName"],
   "holidays": ["id", "holidayDate", "holidayName", "holidaySetID", "soapParentPropertyId"],
   "inventory_products": ["id", "availableUnits", "backOrderQuantity", "bin", "createDateTime", "createdByResourceID", "inventoryLocationID", "onHandUnits", "pickedUnits", "productID", "quantityMaximum", "quantityMinimum", "referenceNumber", "reservedUnits", "unitsOnOrder"],
+  "invoice_templates": ["id", "coveredByBlockRetainerContractLabel", "coveredByRecurringServiceFixedPricePerTicketContractLabel", "currencyNegativeFormat", "currencyPositiveFormat", "dateFormat", "displayFixedPriceContractLabor", "displayRecurringServiceContractLabor", "displaySeparateLineItemForEachTax", "displayTaxCategory", "displayTaxCategorySuperscripts", "displayZeroAmountRecurringServicesAndBundles", "groupBy", "itemizeItemsInEachGroup", "itemizeServicesAndBundles", "name", "nonBillableLaborLabel", "numberFormat", "pageLayout", "pageNumberFormat", "paymentTerms", "rateCostExpression", "showGridHeader", "showVerticalGridLines", "sortBy", "timeFormat"],
   "invoices": ["id", "batchID", "comments", "companyID", "createDateTime", "creatorResourceID", "dueDate", "fromDate", "invoiceDateTime", "invoiceEditorTemplateID", "invoiceNumber", "invoiceTotal", "isVoided", "orderNumber", "paidDate", "paymentTerm", "taxGroup", "taxRegionName", "toDate", "totalTaxValue", "voidedByResourceID", "voidedDate", "webServiceDate"],
   "notification_history": ["id", "companyID", "entityNumber", "entityTitle", "initiatingContactID", "initiatingResourceID", "isActive", "isDeleted", "isTemplateJob", "notificationHistoryTypeID", "notificationSentTime", "opportunityID", "projectID", "quoteID", "recipientDisplayName", "recipientEmailAddress", "taskID", "templateName", "ticketID", "timeEntryID"],
   "opportunities": ["id", "advancedField1", "advancedField2", "advancedField3", "advancedField4", "advancedField5", "amount", "assessmentScore", "barriers", "closedDate", "companyID", "contactID", "cost", "createDate", "creatorResourceID", "description", "helpNeeded", "impersonatorCreatorResourceID", "lastActivity", "leadSource", "lossReason", "lossReasonDetail", "lostDate", "market", "monthlyCost", "monthlyRevenue", "nextStep", "onetimeCost", "onetimeRevenue", "opportunityCategoryID", "organizationalLevelAssociationID", "ownerResourceID", "primaryCompetitor", "probability", "productID", "projectedCloseDate", "promisedFulfillmentDate", "promotionName", "quarterlyCost", "quarterlyRevenue", "rating", "relationshipAssessmentScore", "revenueSpread", "revenueSpreadUnit", "salesOrderID", "salesProcessPercentComplete", "semiannualCost", "semiannualRevenue", "stage", "startDate", "status", "technicalAssessmentScore", "throughDate", "title", "totalAmountMonths", "useQuoteTotals", "winReason", "winReasonDetail", "yearlyCost", "yearlyRevenue", "userDefinedFields"],
   "opportunity_attachments": ["id", "attachDate", "attachedByContactID", "attachedByResourceID", "attachmentType", "contentType", "creatorType", "fileSize", "fullPath", "impersonatorCreatorResourceID", "opportunityID", "parentAttachmentID", "parentID", "publish", "title", "data", "parentType", "soapParentPropertyId", "isTaskAttachment"],
   "opportunity_categories": ["id", "displayColorRGB", "isActive", "isGlobalDefault", "name", "nickname"],
+  "organizational_level1s": ["id", "description", "isActive", "name"],
+  "organizational_level2s": ["id", "description", "isActive", "name"],
+  "organizational_level_associations": ["id", "isActive", "organizationalLevel1ID", "organizationalLevel2ID"],
   "phases": ["id", "createDate", "creatorResourceID", "description", "dueDate", "estimatedHours", "externalID", "isScheduled", "lastActivityDateTime", "parentPhaseID", "phaseNumber", "projectID", "startDate", "title", "soapParentPropertyId"],
   "product_vendors": ["id", "isActive", "isDefault", "productID", "vendorCost", "vendorID", "vendorPartNumber", "soapParentPropertyId"],
   "products": ["id", "billingType", "chargeBillingCodeID", "createdByResourceID", "createdTime", "defaultVendorID", "description", "doesNotRequireProcurement", "externalProductID", "impersonatorCreatorResourceID", "internalProductID", "isActive", "isEligibleForRma", "isSerialized", "link", "manufacturerName", "manufacturerProductName", "markupRate", "msrp", "name", "periodType", "priceCostMethod", "productBillingCodeID", "productCategory", "sku", "unitCost", "unitPrice", "vendorProductNumber", "defaultInstalledProductCategoryID", "userDefinedFields"],
@@ -16792,6 +17642,7 @@ var MODEL_FIELD_SETS = {
   "resource_time_off_balances": ["id", "resourceID", "floatingHolidayAnnualAllowance", "floatingHolidayBalance", "floatingHolidayPlanned", "floatingHolidayUsed", "floatingHolidayWaitingApproval", "personalTimeAnnualAllowance", "personalTimeBalance", "personalTimePlanned", "personalTimeUsed", "personalTimeWaitingApproval", "sickTimeAnnualAllowance", "sickTimeBalance", "sickTimePlanned", "sickTimeUsed", "sickTimeWaitingApproval", "vacationTimeAnnualAllowance", "vacationTimeBalance", "vacationTimePlanned", "vacationTimeUsed", "vacationTimeWaitingApproval", "year", "soapParentPropertyId"],
   "resources": ["id", "accountingReferenceID", "dateFormat", "defaultServiceDeskRoleID", "email", "email2", "email3", "emailTypeCode", "emailTypeCode2", "emailTypeCode3", "firstName", "gender", "greeting", "hireDate", "homePhone", "initials", "internalCost", "isActive", "lastName", "licenseType", "locationID", "middleName", "mobilePhone", "numberFormat", "officeExtension", "officePhone", "payrollIdentifier", "payrollType", "resourceType", "suffix", "surveyResourceRating", "timeFormat", "title", "travelAvailabilityPct", "userName", "userType"],
   "roles": ["id", "description", "hourlyFactor", "hourlyRate", "isActive", "isExcludedFromNewContracts", "isSystemRole", "name", "quoteItemDefaultTaxCategoryId", "roleType"],
+  "sales_orders": ["id", "additionalBillToAddressInformation", "additionalShipToAddressInformation", "billingAddress1", "billingAddress2", "billToCity", "billToCountryID", "billToPostalCode", "billToState", "companyID", "contactID", "impersonatorCreatorResourceID", "opportunityID", "organizationalLevelAssociationID", "ownerResourceID", "promisedFulfillmentDate", "salesOrderDate", "shipToAddress1", "shipToAddress2", "shipToCity", "shipToCountryID", "shipToPostalCode", "shipToState", "status", "title", "soapParentPropertyId", "userDefinedFields"],
   "service_call_task_resources": ["id", "resourceID", "serviceCallTaskID", "soapParentPropertyId"],
   "service_call_tasks": ["id", "serviceCallID", "taskID", "soapParentPropertyId"],
   "service_call_ticket_resources": ["id", "resourceID", "serviceCallTicketID", "soapParentPropertyId"],
@@ -16809,6 +17660,7 @@ var MODEL_FIELD_SETS = {
   "tags": ["id", "createDateTime", "isActive", "isExcludedFromAutomaticTagging", "isSystem", "label", "lastModifiedDateTime", "tagGroupID"],
   "task_secondary_resources": ["id", "resourceID", "roleID", "taskID", "soapParentPropertyId"],
   "tasks": ["id", "assignedResourceID", "assignedResourceRoleID", "billingCodeID", "canClientPortalUserCompleteTask", "companyLocationID", "completedByResourceID", "completedByType", "completedDateTime", "createDateTime", "creatorResourceID", "creatorType", "departmentID", "description", "endDateTime", "estimatedHours", "externalID", "hoursToBeScheduled", "isTaskBillable", "isVisibleInClientPortal", "lastActivityDateTime", "lastActivityPersonType", "lastActivityResourceID", "phaseID", "priority", "priorityLabel", "projectID", "purchaseOrderNumber", "remainingHours", "startDateTime", "status", "taskCategoryID", "taskNumber", "taskType", "title", "soapParentPropertyId", "userDefinedFields"],
+  "tax_regions": ["id", "isActive", "name"],
   "ticket_additional_configuration_items": ["id", "configurationItemID", "ticketID", "soapParentPropertyId"],
   "ticket_additional_contacts": ["id", "contactID", "ticketID", "soapParentPropertyId"],
   "ticket_attachments": ["id", "attachDate", "attachedByContactID", "attachedByResourceID", "attachmentType", "contentType", "creatorType", "fileSize", "fullPath", "impersonatorCreatorResourceID", "opportunityID", "parentAttachmentID", "parentID", "publish", "ticketID", "ticketNoteID", "timeEntryID", "title", "data", "parentType", "soapParentPropertyId", "isTaskAttachment"],
@@ -16830,6 +17682,7 @@ var MODEL_FIELD_SETS = {
 };
 var MODEL_DATE_FIELDS = {
   "appointments": ["createDateTime", "endDateTime", "startDateTime", "updateDateTime"],
+  "billing_item_approval_levels": ["approvalDateTime"],
   "billing_items": ["itemDate", "postedDate", "postedOnTime", "webServiceDate"],
   "companies": ["createDate", "lastActivityDate", "lastTrackedModifiedDateTime"],
   "company_notes": ["completedDateTime", "createDateTime", "endDateTime", "lastModifiedDate", "startDateTime"],
@@ -16848,6 +17701,7 @@ var MODEL_DATE_FIELDS = {
   "contract_service_units": ["approveAndPostDate", "endDate", "startDate"],
   "contract_ticket_purchases": ["datePurchased", "endDate", "startDate"],
   "contracts": ["endDate", "lastModifiedDateTime", "startDate"],
+  "currencies": ["lastModifiedDateTime"],
   "expense_item_attachments": ["attachDate"],
   "expense_items": ["expenseDate"],
   "expense_reports": ["approvedDate", "submitDate", "weekEnding"],
@@ -16868,6 +17722,7 @@ var MODEL_DATE_FIELDS = {
   "quote_templates": ["createDate", "lastActivityDate"],
   "quotes": ["approvalStatusChangedDate", "createDate", "effectiveDate", "expirationDate", "extApprovalResponseDate", "lastActivityDate", "lastPublishedDateTime"],
   "resources": ["hireDate"],
+  "sales_orders": ["promisedFulfillmentDate", "salesOrderDate"],
   "service_calls": ["canceledDateTime", "createDateTime", "endDateTime", "lastModifiedDateTime", "startDateTime"],
   "services": ["createDate", "lastModifiedDate"],
   "subscription_periods": ["periodDate", "postedDate"],
@@ -19315,6 +20170,8 @@ export {
   MarkerUnsafeIdError,
   RecoveryTruncatedError,
   MoveRefusedError,
+  READ_CACHE_MAX_ENTRIES,
+  ReadCache,
   ZONE_CATALOG,
   ZONES,
   DEFAULT_ZONE,
@@ -19360,6 +20217,7 @@ export {
   buildTenantKey,
   cooldownDurationMs,
   resolveCredentials,
+  buildReadCache,
   resolveConfig,
   IDEMPOTENT_METHODS,
   isRecord2 as isRecord,
@@ -19427,6 +20285,9 @@ export {
   validateQueryFieldNames,
   EXPAND_RESOURCE_NAMES_MAX_IDS,
   expandResourceNames,
+  ENTITY_TYPE_TO_RESOURCE,
+  resourceForEntityType,
+  isEnumerableResource,
   WORKFLOW_RESOURCES,
   MAX_FIELD_CATALOG_WIRE,
   FIELD_CATALOG_HONESTY_NOTE,