node-autotask 0.40.0 → 0.42.0

package/dist/{chunk-VDVBXXJW.js → chunk-AETFO6BO.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-Y6YJYKBZ.js";
+} from "./chunk-WP33PQVM.js";
 import {
   wrapUntrusted
 } from "./chunk-5VHSLJMR.js";
@@ -486,7 +486,7 @@ function suggestedActionForStatus(status) {
     case 429:
       return "Back off and retry; honour Retry-After.";
     default:
-      return status >= 500 ? "Retry with backoff; the server error is transient." : void 0;
+      return status >= 500 ? "The SDK already retried per its policy. A repeated 500 on one entity while others work usually means the API user lacks permission on that entity \u2014 ask the Autotask admin to grant it; otherwise retry once more at most." : void 0;
   }
 }
 function errorFromStatus(status, body, url, operation, redactPersonalData = true, credential) {
@@ -586,6 +586,40 @@ var MoveRefusedError = class extends AutotaskError {
   }
 };
 
+// src/errors/scopeRequired.ts
+var UNSCOPED_WALK_THRESHOLD = 500;
+var ScopeRequiredError = class extends AutotaskConfigError {
+  /** True when the call was refused locally: the walk was never issued. */
+  notSent = true;
+  /** The refusal is a caller-input problem (fix the filter; do not retry). */
+  callerInput = true;
+  /**
+   * @param operation The operation the refusal is about (e.g.
+   *   `billing_items.query` — the op the caller's filter must scope).
+   * @param details   `{ threshold }` + the pre-flight `count` when the
+   *   guard spent one (the aggregate's pre-request refusal has no count).
+   * @param reason    The per-surface refusal clause (default
+   *   `'no-id-scope'` — the query guard; the aggregate surface passes
+   *   `'empty-filter'`, its fold refusing on an EMPTY filter).
+   */
+  constructor(operation, details, reason = "no-id-scope") {
+    const countClause = details.count !== void 0 ? `${details.count} rows match ` : "The unscoped walk ";
+    const reasonClause = reason === "empty-filter" ? `has no filter (over ${details.threshold}) \u2014 the fold would walk the whole tenant table \u2014 ` : `with no id scope in the filter (over ${details.threshold}) \u2014 `;
+    super(
+      `${countClause}${reasonClause}"${operation}" was not issued`,
+      {
+        code: "SCOPE_REQUIRED",
+        category: "validation",
+        operation,
+        retryable: false,
+        suggestedAction: "Filter on an id field with op eq or in (companyID, contractID, ticketID, resourceID, or the entity id \u2014 time entries: ticketID), or use a count / group / sum for totals, or pass acknowledgeUnscoped: true to walk it anyway.",
+        details: { threshold: details.threshold, ...details.count !== void 0 ? { count: details.count } : {} }
+      }
+    );
+    this.name = "ScopeRequiredError";
+  }
+};
+
 // src/cache.ts
 var READ_CACHE_MAX_ENTRIES = 4096;
 var REFERENCE_TTL_MS = 36e5;
@@ -1300,6 +1334,15 @@ function resolveConfig(config) {
   const caches = resolveCaches(config);
   const update = { putFallback: config.update?.putFallback === true };
   const reResolveZoneOn401 = config.reResolveZoneOn401 === true;
+  let labels = false;
+  if (config.labels !== void 0) {
+    if (typeof config.labels !== "boolean") {
+      throw new AutotaskConfigError(
+        "labels must be a boolean (true adds the *Name/*Label row siblings to the read surfaces, false returns raw ids)"
+      );
+    }
+    labels = config.labels;
+  }
   const logger = config.logger ?? NoopLogger;
   if (credentials.baseUrl.startsWith("http:")) {
     const host = new URL(credentials.baseUrl).host;
@@ -1315,6 +1358,7 @@ function resolveConfig(config) {
     userName: credentials.userName,
     secret: credentials.secret,
     impersonationResourceId: credentials.impersonationResourceId,
+    labels,
     ...limits,
     logger,
     rateLimit,
@@ -1557,7 +1601,7 @@ function normalizeInCondition(cond, path) {
       `Operator "${cond.op}" at ${path} has an empty value list \u2014 pass an array or a comma-separated string with at least one value (e.g. "1,2,3")`
     );
   }
-  const value = cond.udf === true ? tokens : tokens.map((t) => String(Number(t)) === t ? Number(t) : t);
+  const value = cond.udf === true ? tokens : tokens.map((t) => /^(0|[1-9]\d*)$/.test(t) && Number.isSafeInteger(Number(t)) ? Number(t) : t);
   return { ...cond, value };
 }
 function refusedFilterShape(filter) {
@@ -16808,469 +16852,129 @@ async function toArray(iter) {
   return out;
 }
 
-// src/field-presets.ts
-var FIELD_PRESETS = {
-  /**
-   * The billing-item join read (the issue's example): the FK + measure
-   * columns that join a billing item to its company / ticket / project /
-   * time entry / contract service / contract / billing code / expense item,
-   * plus the date and the amount fields. All 14 names verified against the
-   * vendored-spec billing_items model (the non-authoritative guard); LIVE
-   * existence is asserted by the live-smoke preset check (the AC test).
-   */
-  billing_join: {
-    resource: "billing_items",
-    fields: [
-      "companyID",
-      "ticketID",
-      "projectID",
-      "timeEntryID",
-      "contractServiceID",
-      "contractID",
-      "billingCodeID",
-      "expenseItemID",
-      "itemDate",
-      "quantity",
-      "rate",
-      "extendedPrice",
-      "totalAmount",
-      "nonBillable"
-    ]
-  }
-};
-var FIELD_PRESET_NAMES = Object.keys(FIELD_PRESETS);
-function resolveFieldsPreset(name, resourceKey, explicitIncludeFields) {
-  if (explicitIncludeFields !== void 0 && explicitIncludeFields !== null && explicitIncludeFields.length > 0) {
-    throw new AutotaskConfigError(
-      `fieldsPreset: "${name}" cannot be combined with an explicit includeFields \u2014 the bag is closed (pass ONE of the two: the preset name OR the field list)`
-    );
-  }
-  const preset = Object.hasOwn(FIELD_PRESETS, name) ? FIELD_PRESETS[name] : void 0;
-  if (preset === void 0) {
-    throw new AutotaskConfigError(
-      `fieldsPreset: unknown preset "${name}" \u2014 the preset list is closed (valid names: ${FIELD_PRESET_NAMES.join(", ")})`
-    );
-  }
-  if (preset.resource !== resourceKey) {
-    throw new AutotaskConfigError(
-      `fieldsPreset: "${name}" is a ${preset.resource} preset \u2014 it cannot be resolved on ${resourceKey} (the preset names its resource; the valid names are: ${FIELD_PRESET_NAMES.join(", ")})`
-    );
-  }
-  return [...preset.fields];
-}
+// src/operations/types.ts
+var WORKFLOW_RESOURCES = [
+  "companies",
+  "tickets",
+  "contacts",
+  "configuration_items",
+  "projects"
+];
 
-// src/resources/base/helpers.ts
-function describeResponseShape(body) {
-  if (body === null) return "null";
-  if (Array.isArray(body)) return `array(len=${body.length})`;
-  if (typeof body !== "object") return typeof body;
-  const rec = body;
-  const keys = Object.keys(rec).sort();
-  const typeOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
-  const parts = keys.slice(0, 16).map((k) => `${k}:${typeOf(rec[k])}`);
-  const more = keys.length > 16 ? `, +${keys.length - 16} more` : "";
-  return `{ ${parts.join(", ")}${more} }`;
-}
-function defaultMarkerToken(data) {
-  for (const field of ["name", "title"]) {
-    const v = data[field];
-    if (typeof v === "string" && v.trim() !== "") return v.trim();
-  }
-  return null;
-}
-var CONTEXT_ABSENT_MARKER = "#context-absent";
-function contextAbsentKey(path) {
-  return path + "\0context-absent";
-}
-function noteCharsTruncationMarker(charsRemoved) {
-  return `\u2026 [+${charsRemoved} chars truncated]`;
-}
-function truncateNoteChars(items, cap, fields) {
-  let truncated = 0;
-  const out = items.map((item) => {
-    if (!isRecord2(item)) return item;
-    let changed = false;
-    const copy = { ...item };
-    for (const field of fields) {
-      const v = copy[field];
-      if (typeof v === "string" && v.length > cap) {
-        const end = cap > 0 && (v.charCodeAt(cap - 1) & 64512) === 55296 ? cap - 1 : cap;
-        copy[field] = v.slice(0, end) + noteCharsTruncationMarker(v.length - end);
-        truncated += 1;
-        changed = true;
-      }
-    }
-    return changed ? copy : item;
-  });
-  return [out, truncated];
-}
-function blindEmptyReason(stamp) {
+// src/operations/fieldCatalog.ts
+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 MIN_FIELD_CATALOG_MAX_BYTES = 4096;
+var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels", "compact", "maxBytes"];
+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 : "";
   return {
-    surface: stamp.surface,
-    kind: "blind-surface",
-    note: stamp.note,
-    authority: stamp.authority,
-    remedy: "the note is the remedy \u2014 the authority op answers for a record"
+    name,
+    ...typeof r.label === "string" && r.label !== "" ? { label: r.label } : {},
+    type,
+    isRequired: r.isRequired === true,
+    isReadOnly: r.isReadOnly === 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,
+    ...values !== void 0 ? { picklistValues: values } : {}
   };
 }
-function attachUpdateTargetMissReason(err, key) {
-  const pinned = EMPTY_REASON_STAMPS[key]?.update;
-  if (pinned === void 0) return;
-  err.details = { ...err.details ?? {}, emptyReason: pinned };
-}
-function buildDryRunResult(spec, policy = { redactPersonalData: true }) {
-  if (spec.operation === "") {
-    throw new AutotaskConfigError("dry-run: the operation name is required");
-  }
-  const wouldApply = spec.checks.every((check) => check.ok);
-  const resource = spec.operation.split(".")[0] ?? spec.operation;
-  const diffPart = spec.diff !== void 0 ? {
-    diff: spec.diff.map((entry) => {
-      if (entry.to === void 0) return entry;
-      const to = isRedactedFieldName(entry.field, policy) ? REDACTED : redactResponseBody(entry.to, policy);
-      return { ...entry, to };
-    })
-  } : {};
-  const dataPart = spec.data !== void 0 ? { data: redactResponseBody(spec.data, policy) } : {};
+function compactFieldRow(f, udf, keepValues) {
   return {
-    operation: spec.operation,
-    wouldApply,
-    target: { resource, ids: spec.ids },
-    request: { method: spec.method, path: spec.path },
-    ...diffPart,
-    checks: spec.checks,
-    impact: spec.impact,
-    simulated: true,
-    warnings: spec.warnings ?? [],
-    ...dataPart,
-    ...spec.emptyReason !== void 0 ? { emptyReason: spec.emptyReason } : {}
+    name: f.name,
+    type: f.type,
+    isPickList: f.isPickList,
+    isReference: f.referenceEntityType !== "",
+    udf,
+    ...keepValues && f.picklistValues !== void 0 ? { picklistValues: f.picklistValues } : {}
   };
 }
-function computeFieldDiff(current, data) {
-  const out = [];
-  for (const [field, to] of Object.entries(data)) {
-    if (field === "id" || to === void 0) continue;
-    const from = current[field];
-    if (from !== void 0 && JSON.stringify(from) === JSON.stringify(to)) continue;
-    out.push({ field, from: from === void 0 ? null : from, to });
+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;
+}
+function applyFieldsFilter(projected, filter, row) {
+  const kept = filter === void 0 ? projected : projected.filter((f) => filter.includes(f.name));
+  if (filter !== void 0) {
+    const present = new Set(projected.map((f) => f.name));
+    row.unmatchedFields = filter.filter((n) => !present.has(n));
+    row.projected = true;
   }
-  return out;
+  row.fields = kept;
+  row.required = kept.filter((f) => f.isRequired).map((f) => f.name);
+  row.readOnly = kept.filter((f) => f.isReadOnly).map((f) => f.name);
+  row.queryable = kept.filter((f) => f.isQueryable).map((f) => f.name);
+  row.picklistFields = kept.filter((f) => f.isPickList).map((f) => f.name);
 }
-function mergePartialBody(current, data) {
-  const merged = { ...current };
-  for (const [key, value] of Object.entries(data)) {
-    if (value === void 0) continue;
-    merged[key] = value;
+function capabilitySets() {
+  const fieldOps = /* @__PURE__ */ new Map();
+  const udfCapable = /* @__PURE__ */ new Set();
+  const resources = /* @__PURE__ */ new Set();
+  for (const rec of CAPABILITIES) {
+    if (rec.resource === "operations") continue;
+    resources.add(rec.resource);
+    if (rec.operation === "getFieldInfo") fieldOps.set(rec.resource, rec);
+    if (rec.udfCapable) udfCapable.add(rec.resource);
   }
-  return merged;
+  return { fieldOps, udfCapable, resources };
 }
-function normalizeUdfInput(value) {
-  if (Array.isArray(value)) {
-    return value.map((entry) => {
-      if (!isRecord2(entry) || typeof entry.name !== "string" || entry.name === "") {
-        throw new AutotaskConfigError("userDefinedFields array entries must be { name, value } objects");
+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 } : {}
+        });
       }
-      return { name: entry.name, value: entry.value };
-    });
-  }
-  if (isRecord2(value)) {
-    return Object.entries(value).map(([name, entryValue]) => ({ name, value: entryValue }));
+      derivedIndex.set(rec.resource, rows);
+    }
   }
-  throw new AutotaskConfigError("userDefinedFields must be an array of { name, value } entries or a name-to-value map");
+  return derivedIndex.get(resource) ?? [];
 }
-function blindStampFor(stamp, filter) {
-  if (stamp === void 0) return void 0;
-  if (stamp.kind !== "unfiltered-blind") return stamp;
-  const conditions = normalizedConditions(filter);
-  return conditions === void 0 || conditions.length === 0 ? stamp : void 0;
+function apiEntityFor(rec) {
+  const m = /^GET \/V1\.0\/([^/]+)\/entityInformation\/fields$/.exec(rec.endpoint ?? "");
+  if (m === null) {
+    throw new AutotaskConfigError(
+      `fieldCatalog: the plan's getFieldInfo endpoint for "${rec.resource}" has no /V1.0/<Entity>/entityInformation/fields shape (${rec.endpoint}) \u2014 plan defect`,
+      { operation: "operations.fieldCatalog" }
+    );
+  }
+  return m[1];
 }
-function decodeFileData(body) {
-  if (isRecord2(body)) {
-    const data = body.data;
-    if (typeof data === "string") return Buffer.from(data, "base64");
-    if (Array.isArray(data) && data.every((b) => typeof b === "number")) {
-      return Buffer.from(data);
-    }
-  }
-  if (typeof body === "string") return Buffer.from(body, "base64");
-  throw new AutotaskError(
-    "Expected the file envelope FileQueryResultModel { data } (or a base64 string); got a different shape",
-    { code: "INVALID_RESPONSE", category: "server" }
-  );
-}
-var DEPLURAL_EXCEPTIONS = {
-  tag_aliase: "tag_alias"
-};
-function entityNameFromPath(resourcePath) {
-  const segment = resourcePath.slice(resourcePath.lastIndexOf("/") + 1);
-  const snake = segment.replace(/([A-Z])/g, (_m, c, i) => (i > 0 ? `_` : "") + c.toLowerCase()).replace(/_{2,}/g, "_");
-  if (snake.endsWith("ies")) return `${snake.slice(0, -3)}y`;
-  if (snake.endsWith("s")) {
-    const stripped = snake.slice(0, -1);
-    return DEPLURAL_EXCEPTIONS[stripped] ?? stripped;
-  }
-  return snake;
-}
-
-// src/operations/expandResourceNames.ts
-var EXPAND_RESOURCE_NAMES_MAX_IDS = 500;
-function composeName(record) {
-  const parts = [];
-  for (const field of ["firstName", "middleName", "lastName"]) {
-    const value = record[field];
-    if (typeof value === "string" && value.trim() !== "") parts.push(value.trim());
-  }
-  return parts.length > 0 ? parts.join(" ") : null;
-}
-async function expandResourceNames(client, ids2, opts = {}) {
-  if (opts.maxIds !== void 0 && (!Number.isInteger(opts.maxIds) || opts.maxIds < 1)) {
-    throw new AutotaskConfigError(`expandResourceNames: maxIds must be an integer >= 1 (got ${String(opts.maxIds)})`);
-  }
-  const cap = Math.min(EXPAND_RESOURCE_NAMES_MAX_IDS, opts.maxIds ?? EXPAND_RESOURCE_NAMES_MAX_IDS);
-  if (!Array.isArray(ids2) || ids2.length === 0) {
-    throw new AutotaskConfigError(
-      "expandResourceNames: ids must be a non-empty array of vendor numeric resource ids (a zero-id call is a shape error, not a no-op)",
-      { suggestedAction: "Pass at least one vendor numeric resource id \u2014 safe integer, or the canonical integer string for ids above 2^53." }
-    );
-  }
-  if (ids2.length > cap) {
-    throw new AutotaskConfigError(
-      `expandResourceNames: ${ids2.length} ids over the ${cap}-id cap (EXPAND_RESOURCE_NAMES_MAX_IDS = ${EXPAND_RESOURCE_NAMES_MAX_IDS}; maxIds may lower, never raise) \u2014 zero ids were fetched (pre-request)`,
-      { suggestedAction: `Split the call into groups of <= ${cap} ids.` }
-    );
-  }
-  const problems = [];
-  const canonical = [];
-  for (let i = 0; i < ids2.length; i += 1) {
-    const at = `ids[${i}]`;
-    const raw = ids2[i];
-    try {
-      canonical[i] = parseIdentifier(raw, at);
-    } catch {
-      if (typeof raw === "string") {
-        problems.push(`${at}: "${raw}" is not a vendor numeric resource id \u2014 non-numeric string identifiers are operations.resolveAny territory (the resource's findBy* helpers)`);
-      } else if (typeof raw === "number") {
-        problems.push(`${at}: ${raw} is not a non-negative safe integer (a JS number this large is already corrupted \u2014 pass the canonical integer string form)`);
-      } else {
-        problems.push(`${at}: required \u2014 the vendor numeric resource id (safe integer, or the canonical integer string for ids above 2^53)`);
-      }
-    }
-  }
-  if (problems.length > 0) {
-    throw new AutotaskConfigError(`expandResourceNames: ${problems.length} problem(s) found pre-request (zero wire was issued)
-- ` + problems.join("\n- "), {
-      suggestedAction: "Fix every id above and call again \u2014 the ids are vendor NUMERIC resource ids only (name-to-id resolution is operations.resolveAny territory)."
-    });
-  }
-  const unique = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const id of canonical) {
-    const k = String(id);
-    if (!seen.has(k)) {
-      seen.add(k);
-      unique.push(id);
-    }
-  }
-  const holder = client.resources;
-  const cache = client.http.readCache;
-  const fresh = opts.fresh === true;
-  const byId = /* @__PURE__ */ new Map();
-  for (const id of unique) {
-    const k = String(id);
-    const absentKey = contextAbsentKey(`/V1.0/Resources/${k}`);
-    if (cache !== void 0 && !fresh && cache.get(absentKey) !== void 0) {
-      byId.set(k, { name: null, blind: true });
-      continue;
-    }
-    const epoch = cache?.epoch ?? 0;
-    try {
-      const record = await holder.get(id, { fresh });
-      cache?.delete(absentKey);
-      byId.set(k, { name: composeName(record), blind: false });
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        cache?.set(absentKey, CONTEXT_ABSENT_MARKER, epoch);
-        byId.set(k, { name: null, blind: true });
-        continue;
-      }
-      if (isAutotaskError(err) && err.code !== "ABORTED") {
-        const e = { code: err.code, message: err.message };
-        if (err.httpStatus !== void 0) e.httpStatus = err.httpStatus;
-        byId.set(k, { name: null, blind: false, error: e });
-        continue;
-      }
-      throw err;
-    }
-  }
-  const results = [];
-  for (const id of canonical) {
-    const out = byId.get(String(id));
-    results.push({ id, name: out.name, blind: out.blind, ...out.error !== void 0 ? { error: out.error } : {} });
-  }
-  const resolved = results.filter((r) => r.name !== null).length;
-  const blind = results.filter((r) => r.blind === true).length;
-  const failed = results.filter((r) => r.error !== void 0).length;
-  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",
-  "tickets",
-  "contacts",
-  "configuration_items",
-  "projects"
-];
-
-// src/operations/fieldCatalog.ts
-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 MIN_FIELD_CATALOG_MAX_BYTES = 4096;
-var FIELD_CATALOG_OPT_KEYS = ["resources", "include", "fresh", "fields", "labels", "compact", "maxBytes"];
-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,
-    // 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,
-    targetResource,
-    targetEnumerable: isEnumerableResource(targetResource),
-    ...values !== void 0 ? { picklistValues: values } : {}
-  };
-}
-function compactFieldRow(f, udf, keepValues) {
-  return {
-    name: f.name,
-    type: f.type,
-    isPickList: f.isPickList,
-    isReference: f.referenceEntityType !== "",
-    udf,
-    ...keepValues && f.picklistValues !== void 0 ? { picklistValues: f.picklistValues } : {}
-  };
-}
-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;
-}
-function applyFieldsFilter(projected, filter, row) {
-  const kept = filter === void 0 ? projected : projected.filter((f) => filter.includes(f.name));
-  if (filter !== void 0) {
-    const present = new Set(projected.map((f) => f.name));
-    row.unmatchedFields = filter.filter((n) => !present.has(n));
-    row.projected = true;
-  }
-  row.fields = kept;
-  row.required = kept.filter((f) => f.isRequired).map((f) => f.name);
-  row.readOnly = kept.filter((f) => f.isReadOnly).map((f) => f.name);
-  row.queryable = kept.filter((f) => f.isQueryable).map((f) => f.name);
-  row.picklistFields = kept.filter((f) => f.isPickList).map((f) => f.name);
-}
-function capabilitySets() {
-  const fieldOps = /* @__PURE__ */ new Map();
-  const udfCapable = /* @__PURE__ */ new Set();
-  const resources = /* @__PURE__ */ new Set();
-  for (const rec of CAPABILITIES) {
-    if (rec.resource === "operations") continue;
-    resources.add(rec.resource);
-    if (rec.operation === "getFieldInfo") fieldOps.set(rec.resource, rec);
-    if (rec.udfCapable) udfCapable.add(rec.resource);
-  }
-  return { fieldOps, udfCapable, 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) {
-    throw new AutotaskConfigError(
-      `fieldCatalog: the plan's getFieldInfo endpoint for "${rec.resource}" has no /V1.0/<Entity>/entityInformation/fields shape (${rec.endpoint}) \u2014 plan defect`,
-      { operation: "operations.fieldCatalog" }
-    );
-  }
-  return m[1];
-}
-function validateCatalogOptsShape(opts) {
-  if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new AutotaskConfigError(
-      "fieldCatalog: opts must be an object { resources?: string[], include?: (info|fields|udf)[], fresh?: boolean, fields?: string[], labels?: boolean, compact?: boolean, maxBytes?: number }"
-    );
-  }
-  for (const key of Object.keys(opts ?? {})) {
-    if (!FIELD_CATALOG_OPT_KEYS.includes(key)) {
-      throw new AutotaskConfigError(
-        `fieldCatalog: unknown opts key "${key}" \u2014 the bag is closed: ${FIELD_CATALOG_OPT_KEYS.join(", ")}`,
-        { suggestedAction: "Drop the unknown key (autotask_describe(operations.fieldCatalog) shows the exact bag)." }
-      );
+function validateCatalogOptsShape(opts) {
+  if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
+    throw new AutotaskConfigError(
+      "fieldCatalog: opts must be an object { resources?: string[], include?: (info|fields|udf)[], fresh?: boolean, fields?: string[], labels?: boolean, compact?: boolean, maxBytes?: number }"
+    );
+  }
+  for (const key of Object.keys(opts ?? {})) {
+    if (!FIELD_CATALOG_OPT_KEYS.includes(key)) {
+      throw new AutotaskConfigError(
+        `fieldCatalog: unknown opts key "${key}" \u2014 the bag is closed: ${FIELD_CATALOG_OPT_KEYS.join(", ")}`,
+        { suggestedAction: "Drop the unknown key (autotask_describe(operations.fieldCatalog) shows the exact bag)." }
+      );
     }
   }
 }
@@ -17361,7 +17065,8 @@ function resolveSizeOpts(opts) {
       `fieldCatalog: opts.maxBytes must be an integer >= ${MIN_FIELD_CATALOG_MAX_BYTES} (got ${String(maxBytes)})`
     );
   }
-  return { compact: opts?.compact === true, maxBytes };
+  const compact = opts?.compact ?? (opts?.fields === void 0 && opts?.labels !== true);
+  return { compact, maxBytes };
 }
 var jsonBytes = (v) => Buffer.byteLength(JSON.stringify(v), "utf8");
 var TRIM_KINDS = ["udf", "fields", "picklistFields", "queryable", "readOnly", "required"];
@@ -17552,15 +17257,592 @@ async function fieldCatalog(client, opts) {
   return result;
 }
 
-// src/field-sets.ts
-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"],
-  "checklist_library_checklist_items": ["id", "checklistLibraryID", "isImportant", "itemName", "knowledgebaseArticleID", "position", "soapParentPropertyId"],
+// src/resources/base/helpers.ts
+function describeResponseShape(body) {
+  if (body === null) return "null";
+  if (Array.isArray(body)) return `array(len=${body.length})`;
+  if (typeof body !== "object") return typeof body;
+  const rec = body;
+  const keys = Object.keys(rec).sort();
+  const typeOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+  const parts = keys.slice(0, 16).map((k) => `${k}:${typeOf(rec[k])}`);
+  const more = keys.length > 16 ? `, +${keys.length - 16} more` : "";
+  return `{ ${parts.join(", ")}${more} }`;
+}
+function defaultMarkerToken(data) {
+  for (const field of ["name", "title"]) {
+    const v = data[field];
+    if (typeof v === "string" && v.trim() !== "") return v.trim();
+  }
+  return null;
+}
+var CONTEXT_ABSENT_MARKER = "#context-absent";
+function contextAbsentKey(path) {
+  return path + "\0context-absent";
+}
+function noteCharsTruncationMarker(charsRemoved) {
+  return `\u2026 [+${charsRemoved} chars truncated]`;
+}
+function truncateNoteChars(items, cap, fields) {
+  let truncated = 0;
+  const out = items.map((item) => {
+    if (!isRecord2(item)) return item;
+    let changed = false;
+    const copy = { ...item };
+    for (const field of fields) {
+      const v = copy[field];
+      if (typeof v === "string" && v.length > cap) {
+        const end = cap > 0 && (v.charCodeAt(cap - 1) & 64512) === 55296 ? cap - 1 : cap;
+        copy[field] = v.slice(0, end) + noteCharsTruncationMarker(v.length - end);
+        truncated += 1;
+        changed = true;
+      }
+    }
+    return changed ? copy : item;
+  });
+  return [out, truncated];
+}
+function blindEmptyReason(stamp) {
+  return {
+    surface: stamp.surface,
+    kind: "blind-surface",
+    note: stamp.note,
+    authority: stamp.authority,
+    remedy: "the note is the remedy \u2014 the authority op answers for a record"
+  };
+}
+function attachUpdateTargetMissReason(err, key) {
+  const pinned = EMPTY_REASON_STAMPS[key]?.update;
+  if (pinned === void 0) return;
+  err.details = { ...err.details ?? {}, emptyReason: pinned };
+}
+function buildDryRunResult(spec, policy = { redactPersonalData: true }) {
+  if (spec.operation === "") {
+    throw new AutotaskConfigError("dry-run: the operation name is required");
+  }
+  const wouldApply = spec.checks.every((check) => check.ok);
+  const resource = spec.operation.split(".")[0] ?? spec.operation;
+  const diffPart = spec.diff !== void 0 ? {
+    diff: spec.diff.map((entry) => {
+      if (entry.to === void 0) return entry;
+      const to = isRedactedFieldName(entry.field, policy) ? REDACTED : redactResponseBody(entry.to, policy);
+      return { ...entry, to };
+    })
+  } : {};
+  const dataPart = spec.data !== void 0 ? { data: redactResponseBody(spec.data, policy) } : {};
+  return {
+    operation: spec.operation,
+    wouldApply,
+    target: { resource, ids: spec.ids },
+    request: { method: spec.method, path: spec.path },
+    ...diffPart,
+    checks: spec.checks,
+    impact: spec.impact,
+    simulated: true,
+    warnings: spec.warnings ?? [],
+    ...dataPart,
+    ...spec.emptyReason !== void 0 ? { emptyReason: spec.emptyReason } : {}
+  };
+}
+function computeFieldDiff(current, data) {
+  const out = [];
+  for (const [field, to] of Object.entries(data)) {
+    if (field === "id" || to === void 0) continue;
+    const from = current[field];
+    if (from !== void 0 && JSON.stringify(from) === JSON.stringify(to)) continue;
+    out.push({ field, from: from === void 0 ? null : from, to });
+  }
+  return out;
+}
+function mergePartialBody(current, data) {
+  const merged = { ...current };
+  for (const [key, value] of Object.entries(data)) {
+    if (value === void 0) continue;
+    merged[key] = value;
+  }
+  return merged;
+}
+function normalizeUdfInput(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => {
+      if (!isRecord2(entry) || typeof entry.name !== "string" || entry.name === "") {
+        throw new AutotaskConfigError("userDefinedFields array entries must be { name, value } objects");
+      }
+      return { name: entry.name, value: entry.value };
+    });
+  }
+  if (isRecord2(value)) {
+    return Object.entries(value).map(([name, entryValue]) => ({ name, value: entryValue }));
+  }
+  throw new AutotaskConfigError("userDefinedFields must be an array of { name, value } entries or a name-to-value map");
+}
+function blindStampFor(stamp, filter) {
+  if (stamp === void 0) return void 0;
+  if (stamp.kind !== "unfiltered-blind") return stamp;
+  const conditions = normalizedConditions(filter);
+  return conditions === void 0 || conditions.length === 0 ? stamp : void 0;
+}
+function decodeFileData(body) {
+  if (isRecord2(body)) {
+    const data = body.data;
+    if (typeof data === "string") return Buffer.from(data, "base64");
+    if (Array.isArray(data) && data.every((b) => typeof b === "number")) {
+      return Buffer.from(data);
+    }
+  }
+  if (typeof body === "string") return Buffer.from(body, "base64");
+  throw new AutotaskError(
+    "Expected the file envelope FileQueryResultModel { data } (or a base64 string); got a different shape",
+    { code: "INVALID_RESPONSE", category: "server" }
+  );
+}
+var DEPLURAL_EXCEPTIONS = {
+  tag_aliase: "tag_alias"
+};
+function entityNameFromPath(resourcePath) {
+  const segment = resourcePath.slice(resourcePath.lastIndexOf("/") + 1);
+  const snake = segment.replace(/([A-Z])/g, (_m, c, i) => (i > 0 ? `_` : "") + c.toLowerCase()).replace(/_{2,}/g, "_");
+  if (snake.endsWith("ies")) return `${snake.slice(0, -3)}y`;
+  if (snake.endsWith("s")) {
+    const stripped = snake.slice(0, -1);
+    return DEPLURAL_EXCEPTIONS[stripped] ?? stripped;
+  }
+  return snake;
+}
+
+// src/operations/expandResourceNames.ts
+var EXPAND_RESOURCE_NAMES_MAX_IDS = 500;
+function composeName(record) {
+  const parts = [];
+  for (const field of ["firstName", "middleName", "lastName"]) {
+    const value = record[field];
+    if (typeof value === "string" && value.trim() !== "") parts.push(value.trim());
+  }
+  return parts.length > 0 ? parts.join(" ") : null;
+}
+async function expandResourceNames(client, ids2, opts = {}) {
+  if (opts.maxIds !== void 0 && (!Number.isInteger(opts.maxIds) || opts.maxIds < 1)) {
+    throw new AutotaskConfigError(`expandResourceNames: maxIds must be an integer >= 1 (got ${String(opts.maxIds)})`);
+  }
+  const cap = Math.min(EXPAND_RESOURCE_NAMES_MAX_IDS, opts.maxIds ?? EXPAND_RESOURCE_NAMES_MAX_IDS);
+  if (!Array.isArray(ids2) || ids2.length === 0) {
+    throw new AutotaskConfigError(
+      "expandResourceNames: ids must be a non-empty array of vendor numeric resource ids (a zero-id call is a shape error, not a no-op)",
+      { suggestedAction: "Pass at least one vendor numeric resource id \u2014 safe integer, or the canonical integer string for ids above 2^53." }
+    );
+  }
+  if (ids2.length > cap) {
+    throw new AutotaskConfigError(
+      `expandResourceNames: ${ids2.length} ids over the ${cap}-id cap (EXPAND_RESOURCE_NAMES_MAX_IDS = ${EXPAND_RESOURCE_NAMES_MAX_IDS}; maxIds may lower, never raise) \u2014 zero ids were fetched (pre-request)`,
+      { suggestedAction: `Split the call into groups of <= ${cap} ids.` }
+    );
+  }
+  const problems = [];
+  const canonical = [];
+  for (let i = 0; i < ids2.length; i += 1) {
+    const at = `ids[${i}]`;
+    const raw = ids2[i];
+    try {
+      canonical[i] = parseIdentifier(raw, at);
+    } catch {
+      if (typeof raw === "string") {
+        problems.push(`${at}: "${raw}" is not a vendor numeric resource id \u2014 non-numeric string identifiers are operations.resolveAny territory (the resource's findBy* helpers)`);
+      } else if (typeof raw === "number") {
+        problems.push(`${at}: ${raw} is not a non-negative safe integer (a JS number this large is already corrupted \u2014 pass the canonical integer string form)`);
+      } else {
+        problems.push(`${at}: required \u2014 the vendor numeric resource id (safe integer, or the canonical integer string for ids above 2^53)`);
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new AutotaskConfigError(`expandResourceNames: ${problems.length} problem(s) found pre-request (zero wire was issued)
+- ` + problems.join("\n- "), {
+      suggestedAction: "Fix every id above and call again \u2014 the ids are vendor NUMERIC resource ids only (name-to-id resolution is operations.resolveAny territory)."
+    });
+  }
+  const unique = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of canonical) {
+    const k = String(id);
+    if (!seen.has(k)) {
+      seen.add(k);
+      unique.push(id);
+    }
+  }
+  const holder = client.resources;
+  const cache = client.http.readCache;
+  const fresh = opts.fresh === true;
+  const byId = /* @__PURE__ */ new Map();
+  for (const id of unique) {
+    const k = String(id);
+    const absentKey = contextAbsentKey(`/V1.0/Resources/${k}`);
+    if (cache !== void 0 && !fresh && cache.get(absentKey) !== void 0) {
+      byId.set(k, { name: null, blind: true });
+      continue;
+    }
+    const epoch = cache?.epoch ?? 0;
+    try {
+      const record = await holder.get(id, { fresh });
+      cache?.delete(absentKey);
+      byId.set(k, { name: composeName(record), blind: false });
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        cache?.set(absentKey, CONTEXT_ABSENT_MARKER, epoch);
+        byId.set(k, { name: null, blind: true });
+        continue;
+      }
+      if (isAutotaskError(err) && err.code !== "ABORTED") {
+        const e = { code: err.code, message: err.message };
+        if (err.httpStatus !== void 0) e.httpStatus = err.httpStatus;
+        byId.set(k, { name: null, blind: false, error: e });
+        continue;
+      }
+      throw err;
+    }
+  }
+  const results = [];
+  for (const id of canonical) {
+    const out = byId.get(String(id));
+    results.push({ id, name: out.name, blind: out.blind, ...out.error !== void 0 ? { error: out.error } : {} });
+  }
+  const resolved = results.filter((r) => r.name !== null).length;
+  const blind = results.filter((r) => r.blind === true).length;
+  const failed = results.filter((r) => r.error !== void 0).length;
+  return { results, resolved, blind, failed };
+}
+
+// src/operations/lineOfBusinessChain.ts
+function vendorId(value) {
+  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 1 ? value : void 0;
+  if (typeof value === "string" && /^[0-9]+$/.test(value.trim())) {
+    const n = Number(value.trim());
+    return Number.isSafeInteger(n) && n >= 1 ? n : void 0;
+  }
+  return void 0;
+}
+async function resolveLineOfBusinessChain(http, associationId, options) {
+  const operation = options.operation ?? "compositeNames";
+  const degrade = options.onError === "degrade";
+  const get = (path) => {
+    const res = http.request({ method: "GET", path, operation }).then((body) => {
+      const b = body;
+      if (b === null || !("item" in b) || b.item === null || b.item === void 0) return null;
+      return b.item;
+    });
+    if (!degrade) {
+      return res.catch((e) => {
+        if (e instanceof NotFoundError) return null;
+        throw e;
+      });
+    }
+    return res.catch((e) => {
+      if (e instanceof NotFoundError || isAutotaskError(e) && e.code !== "ABORTED") return null;
+      throw e;
+    });
+  };
+  let remaining = options.budget;
+  if (remaining < 1) {
+    return {
+      lineOfBusiness: { association: null, organizationalLevel2: null, organizationalLevel1: null, markers: { association: "capped", organizationalLevel2: "capped", organizationalLevel1: "capped" } },
+      used: 0,
+      truncated: true
+    };
+  }
+  remaining -= 1;
+  const association = await get(`/V1.0/OrganizationalLevelAssociations/${associationId}`);
+  const associationMarker = association === null ? "unresolved" : "ok";
+  if (association === null) {
+    return {
+      lineOfBusiness: { association: null, organizationalLevel2: null, organizationalLevel1: null, markers: { association: associationMarker, organizationalLevel2: "missing", organizationalLevel1: "missing" } },
+      used: 1,
+      truncated: false
+    };
+  }
+  const l2Id = vendorId(association.organizationalLevel2ID);
+  const l1Id = vendorId(association.organizationalLevel1ID);
+  let l2Marker = l2Id !== void 0 ? "unresolved" : "missing";
+  let l1Marker = l1Id !== void 0 ? "unresolved" : "missing";
+  const need = (l2Id !== void 0 ? 1 : 0) + (l1Id !== void 0 ? 1 : 0);
+  let l2 = null;
+  let l1 = null;
+  let used = 1;
+  let truncated = false;
+  if (need > 0 && remaining < need) {
+    truncated = true;
+    if (l2Id !== void 0) l2Marker = "capped";
+    if (l1Id !== void 0) l1Marker = "capped";
+  } else {
+    used += need;
+    const [r2, r1] = await Promise.all([
+      l2Id !== void 0 ? get(`/V1.0/OrganizationalLevel2s/${l2Id}`) : Promise.resolve(null),
+      l1Id !== void 0 ? get(`/V1.0/OrganizationalLevel1s/${l1Id}`) : Promise.resolve(null)
+    ]);
+    l2 = r2;
+    l1 = r1;
+    if (l2Id !== void 0) l2Marker = l2 === null ? "unresolved" : "ok";
+    if (l1Id !== void 0) l1Marker = l1 === null ? "unresolved" : "ok";
+  }
+  return {
+    lineOfBusiness: { association, organizationalLevel2: l2, organizationalLevel1: l1, markers: { association: associationMarker, organizationalLevel2: l2Marker, organizationalLevel1: l1Marker } },
+    used,
+    truncated
+  };
+}
+
+// src/operations/compositeNames.ts
+var PICKLIST_VALUE_NOT_SERVED_NOTE = "The picklist is served to this API user, but this record's value is not in it (an inactive or unexposed value) \u2014 the label cannot be resolved and is null; refreshing the field catalog will not surface it. (A picklist the vendor does not expose at all is reported with the field-catalog honesty note instead.)";
+var DEFAULT_MAX_NAME_READS = 20;
+var TICKET_LABEL_FIELDS = ["status", "priority", "ticketType", "issueType", "subIssueType", "source", "queueID"];
+function isVendorId(value) {
+  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0;
+  if (typeof value === "string") return /^\d+$/.test(value);
+  return false;
+}
+var zeroIsRecord = (table) => table === "company";
+function createNamePlan(labelFields = [], labelResource) {
+  const resourceIds = [];
+  const resSeen = /* @__PURE__ */ new Set();
+  const recordFks = [];
+  const fkSeen = /* @__PURE__ */ new Set();
+  let lineOfBusinessId;
+  let lineOfBusinessSource;
+  let lineOfBusinessContractId;
+  return {
+    plan: () => ({
+      resourceIds,
+      recordFks,
+      labelFields,
+      ...labelResource !== void 0 ? { labelResource } : {},
+      ...lineOfBusinessId !== void 0 ? { lineOfBusinessId } : {},
+      ...lineOfBusinessSource !== void 0 ? { lineOfBusinessSource } : {},
+      ...lineOfBusinessContractId !== void 0 ? { lineOfBusinessContractId } : {}
+    }),
+    addResource: (value) => {
+      if (!isVendorId(value) || Number(value) === 0) return;
+      const k = String(value);
+      if (!resSeen.has(k)) {
+        resSeen.add(k);
+        resourceIds.push(value);
+      }
+    },
+    addFk: (table, value) => {
+      if (!isVendorId(value) || Number(value) === 0 && !zeroIsRecord(table)) return;
+      const k = `${table}:${String(value)}`;
+      if (!fkSeen.has(k)) {
+        fkSeen.add(k);
+        recordFks.push({ table, id: value });
+      }
+    },
+    addLineOfBusinessFromContract: (value) => {
+      if (!isVendorId(value)) return;
+      lineOfBusinessContractId = value;
+    },
+    addLineOfBusiness: (value, origin) => {
+      if (!isVendorId(value)) return;
+      lineOfBusinessId = value;
+      if (origin !== void 0) {
+        lineOfBusinessSource = origin.source;
+        if (origin.contractId !== void 0) lineOfBusinessContractId = origin.contractId;
+      }
+    }
+  };
+}
+function addNameSibling(row, field, resolve) {
+  const value = row[field];
+  if (value === void 0) return;
+  row[`${field}Name`] = isVendorId(value) ? resolve(value) : null;
+}
+function addLabelSibling(row, field, names) {
+  const value = row[field];
+  if (value === void 0) return;
+  row[`${field}Label`] = names.labelFor(field, value);
+}
+var FK_TABLE_PATH = {
+  role: "/V1.0/Roles",
+  billingCode: "/V1.0/BillingCodes",
+  contract: "/V1.0/Contracts",
+  company: "/V1.0/Companies",
+  ticket: "/V1.0/Tickets"
+};
+var FK_NAME_FIELD = {
+  role: "name",
+  billingCode: "name",
+  contract: "contractName",
+  company: "companyName",
+  ticket: "ticketNumber"
+};
+function fkName(record, table) {
+  if (table === "ticket") {
+    const parts = [record["ticketNumber"], record["title"]].filter((v) => typeof v === "string" && v.trim() !== "").map((v) => v.trim());
+    return parts.length > 0 ? parts.join(" ") : null;
+  }
+  const value = record[FK_NAME_FIELD[table]];
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function faultRow(err) {
+  const e = err;
+  return e.httpStatus !== void 0 ? { code: e.code, message: e.message, httpStatus: e.httpStatus } : { code: e.code, message: e.message };
+}
+async function resolveCompositeNames(http, plan, opts = {}) {
+  if (opts.maxNameReads !== void 0 && (!Number.isInteger(opts.maxNameReads) || opts.maxNameReads < 1)) {
+    throw new AutotaskConfigError(`composite names: maxNameReads must be an integer >= 1 (got ${String(opts.maxNameReads)})`);
+  }
+  const budget = Math.min(DEFAULT_MAX_NAME_READS, opts.maxNameReads ?? DEFAULT_MAX_NAME_READS);
+  const client = http.client;
+  if (client === void 0) {
+    throw new AutotaskConfigError("composite names: the transport is not wired to an AutotaskClient (the composite must run through the client)");
+  }
+  const readCache = http.readCache;
+  const section = { truncated: false, rows: {}, reasons: {} };
+  let remaining = budget;
+  let contractLobPointer;
+  let contractLobUnread;
+  const coldResource = [];
+  for (const id of plan.resourceIds) {
+    const path = `/V1.0/Resources/${id}`;
+    if (readCache !== void 0 && (readCache.peek(path).hit || readCache.peek(contextAbsentKey(path)).hit)) continue;
+    coldResource.push(id);
+  }
+  const withinBudget = coldResource.slice(0, remaining);
+  const overBudgetResource = coldResource.slice(remaining);
+  remaining -= withinBudget.length;
+  for (const id of overBudgetResource) {
+    section.rows[`resource:${id}`] = { name: null, blind: false };
+    section.truncated = true;
+  }
+  const overSet = new Set(overBudgetResource.map((id) => String(id)));
+  const opIds = plan.resourceIds.filter((id) => !overSet.has(String(id)));
+  if (opIds.length > 0) {
+    let pass = opIds;
+    if (pass.length > 500) {
+      for (const id of pass.slice(500)) {
+        section.rows[`resource:${id}`] = { name: null, blind: false };
+        section.truncated = true;
+      }
+      pass = pass.slice(0, 500);
+    }
+    const res = await expandResourceNames(client, pass);
+    for (const r of res.results) {
+      const row = { name: r.name, blind: r.blind };
+      if (r.error !== void 0) row.error = faultRow(r.error);
+      section.rows[`resource:${r.id}`] = row;
+    }
+  }
+  const holders = {
+    role: client.roles,
+    billingCode: client.billingCodes,
+    contract: client.contracts,
+    company: client.companies,
+    ticket: client.tickets
+  };
+  for (const fk of plan.recordFks) {
+    const key = `${fk.table}:${fk.id}`;
+    const cold = readCache === void 0 || readCache.get(`${FK_TABLE_PATH[fk.table]}/${fk.id}`) === void 0;
+    if (cold) {
+      if (remaining < 1) {
+        section.rows[key] = { name: null, blind: false };
+        section.truncated = true;
+        if (fk.table === "contract" && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
+          contractLobUnread = "capped";
+        }
+        continue;
+      }
+      remaining -= 1;
+    }
+    try {
+      const record = await holders[fk.table].get(fk.id);
+      if (fk.table === "contract" && plan.lineOfBusinessId === void 0 && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
+        contractLobPointer = vendorId(record["organizationalLevelAssociationID"]);
+      }
+      section.rows[key] = { name: fkName(record, fk.table), blind: false };
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        section.rows[key] = { name: null, blind: true };
+      } else if (isAutotaskError(err) && err.code !== "ABORTED") {
+        section.rows[key] = { name: null, blind: false, error: faultRow(err) };
+        if (fk.table === "contract" && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
+          contractLobUnread = "unresolved";
+        }
+      } else {
+        throw err;
+      }
+    }
+  }
+  const picklists = {};
+  if (plan.labelFields.length > 0) {
+    try {
+      const labelResource = plan.labelResource ?? "tickets";
+      const catalog = await fieldCatalog(client, { resources: [labelResource], labels: true, fields: [...plan.labelFields] });
+      const row = catalog.rows.find((r) => r.resource === labelResource);
+      if (row !== void 0 && row.error === null && row.fields !== void 0) {
+        for (const f of plan.labelFields) {
+          const frow = row.fields.find((x) => x.name === f);
+          picklists[f] = frow?.picklistValues;
+        }
+      }
+    } catch (err) {
+      if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
+    }
+  }
+  let lineOfBusiness2 = null;
+  const lobId = plan.lineOfBusinessId ?? contractLobPointer;
+  if (lobId !== void 0) {
+    const chain = await resolveLineOfBusinessChain(http, lobId, { budget: remaining, onError: "degrade" });
+    remaining -= chain.used;
+    if (chain.truncated) section.truncated = true;
+    const fromContract = plan.lineOfBusinessId === void 0;
+    lineOfBusiness2 = {
+      ...chain.lineOfBusiness,
+      ...fromContract ? { source: "contract", contractId: plan.lineOfBusinessContractId } : plan.lineOfBusinessSource !== void 0 ? { source: plan.lineOfBusinessSource } : {},
+      ...!fromContract && plan.lineOfBusinessContractId !== void 0 ? { contractId: plan.lineOfBusinessContractId } : {}
+    };
+  } else if (contractLobUnread !== void 0 && plan.lineOfBusinessContractId !== void 0) {
+    lineOfBusiness2 = {
+      source: "contract",
+      contractId: plan.lineOfBusinessContractId,
+      association: null,
+      organizationalLevel2: null,
+      organizationalLevel1: null,
+      markers: { association: contractLobUnread, organizationalLevel2: "missing", organizationalLevel1: "missing" }
+    };
+  }
+  return {
+    section,
+    lineOfBusiness: lineOfBusiness2,
+    resourceName: (id) => section.rows[`resource:${id}`]?.name ?? null,
+    recordName: (table, id) => section.rows[`${table}:${id}`]?.name ?? null,
+    labelFor: (field, value) => {
+      if (value === null || value === void 0) return null;
+      const values = picklists[field];
+      if (values === void 0) {
+        section.reasons[field] = FIELD_CATALOG_HONESTY_NOTE;
+        return null;
+      }
+      const hit = values.find((v) => String(v.value) === String(value));
+      if (hit === void 0) {
+        if (String(value) !== "0") section.reasons[field] = PICKLIST_VALUE_NOT_SERVED_NOTE;
+        return null;
+      }
+      return typeof hit.label === "string" ? hit.label : null;
+    }
+  };
+}
+
+// src/resources/base/types.ts
+var BOUNDED_QUERY_DEFAULT_LIMIT = 500;
+var BOUNDED_QUERY_MAX_LIMIT = 2500;
+var LATEST_MAX_COUNT_PROBES = 64;
+var MARKER_RECOVERY_LIMIT = 5;
+
+// src/field-sets.ts
+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"],
+  "checklist_library_checklist_items": ["id", "checklistLibraryID", "isImportant", "itemName", "knowledgebaseArticleID", "position", "soapParentPropertyId"],
   "classification_icons": ["id", "description", "isActive", "isSystem", "name", "relativeUrl"],
   "companies": ["id", "additionalAddressInformation", "address1", "address2", "alternatePhone1", "alternatePhone2", "apiVendorID", "assetValue", "billToCompanyLocationID", "billToAdditionalAddressInformation", "billingAddress1", "billingAddress2", "billToAddressToUse", "billToAttention", "billToCity", "billToCountryID", "billToState", "billToZipCode", "city", "classification", "companyCategoryID", "companyName", "companyNumber", "companyType", "competitorID", "countryID", "createDate", "createdByResourceID", "currencyID", "fax", "impersonatorCreatorResourceID", "invoiceEmailMessageID", "invoiceMethod", "invoiceNonContractItemsToParentCompany", "invoiceTemplateID", "isActive", "isClientPortalActive", "isEnabledForComanaged", "isSample", "isTaskFireActive", "isTaxExempt", "lastActivityDate", "lastTrackedModifiedDateTime", "marketSegmentID", "ownerResourceID", "parentCompanyID", "phone", "postalCode", "purchaseOrderTemplateID", "quoteEmailMessageID", "quoteTemplateID", "sicCode", "state", "stockMarket", "stockSymbol", "surveyCompanyRating", "taxID", "taxRegionID", "territoryID", "webAddress", "userDefinedFields"],
   "company_alerts": ["id", "alertText", "alertTypeID", "companyID", "soapParentPropertyId"],
@@ -17743,12 +18025,6 @@ var MODEL_DATE_FIELDS = {
   "time_off_requests": ["approvedDateTime", "createDateTime", "endTime", "lastModifiedDateTime", "requestDate", "startTime"]
 };
 
-// src/resources/base/types.ts
-var BOUNDED_QUERY_DEFAULT_LIMIT = 500;
-var BOUNDED_QUERY_MAX_LIMIT = 2500;
-var LATEST_MAX_COUNT_PROBES = 64;
-var MARKER_RECOVERY_LIMIT = 5;
-
 // src/resources/special/_shared/bounded-part.ts
 async function boundedPart(http, path, conditions, limit, operation, includeFields) {
   const body = { MaxRecords: limit, filter: conditions };
@@ -17781,6 +18057,10 @@ function relationsFor(resourceKey) {
   const fields = MODEL_FIELD_SETS[resourceKey] ?? [];
   return Object.keys(RELATION_TARGETS).filter((rel) => fields.includes(`${rel}ID`));
 }
+function selfPrefixes(resourceKey) {
+  const rels = Object.keys(RELATION_TARGETS).filter((rel) => RELATION_TARGETS[rel].resource === resourceKey);
+  return [resourceKey, ...rels];
+}
 var isRelationLeaf = (c) => isRecord2(c) && c.op !== "and" && c.op !== "or" && typeof c.field === "string" && c.field.includes(".");
 function hasRelationConditions(conditions) {
   if (conditions === void 0) return false;
@@ -17800,6 +18080,10 @@ function validateRelationLeaves(resourceKey, conditions, op) {
           suggestedAction: valid.length > 0 ? `Use ${valid.map((r) => `${r}.<${RELATION_TARGETS[r].resource} field>`).join(" or ")} (one hop; field names from operations.fieldCatalog).` : `${resourceKey} has no relation filters; filter on its own fields.`
         });
       };
+      if (selfPrefixes(resourceKey).includes(rel)) {
+        if (rest.length > 0 || !sub) fail("is not <resource>.<field> (multi-hop relations are not supported)");
+        continue;
+      }
       if (c.udf === true) fail("cannot be a UDF condition");
       if (rest.length > 0 || !sub) fail("is not <relation>.<field> (multi-hop relations are not supported)");
       if (!valid.includes(rel)) fail(`names an unknown relation for ${resourceKey} (valid: ${valid.join(", ") || "none"})`);
@@ -17833,7 +18117,12 @@ async function rewriteRelationFilters(http, resourceKey, conditions, op) {
     const byRel = /* @__PURE__ */ new Map();
     for (const c of list) {
       if (isRelationLeaf(c)) {
-        const rel = c.field.split(".")[0];
+        const parts = c.field.split(".");
+        if (parts.length === 2 && selfPrefixes(resourceKey).includes(parts[0])) {
+          out.push({ ...c, field: parts[1] });
+          continue;
+        }
+        const rel = parts[0];
         if (mode === "and") {
           byRel.set(rel, [...byRel.get(rel) ?? [], c]);
           continue;
@@ -17851,20 +18140,128 @@ async function rewriteRelationFilters(http, resourceKey, conditions, op) {
         out.push({ ...c, items });
         continue;
       }
-      out.push(c);
+      out.push(c);
+    }
+    for (const [rel, leaves] of byRel) {
+      const ids2 = await parentIds(rel, leaves);
+      if (ids2.length === 0) return NEVER;
+      out.push({ field: `${rel}ID`, op: "in", value: ids2 });
+    }
+    return out.length === 0 && mode === "or" ? NEVER : out;
+  };
+  const rewritten = await rewrite(conds, "and");
+  if (rewritten === NEVER) {
+    return { never: true, note: `no parent record matched the relation conditions \u2014 0 ${resourceKey} rows (the ${resourceKey} query was not issued)` };
+  }
+  return { never: false, conditions: rewritten };
+}
+
+// src/operations/rowLabels.ts
+var ROW_FK_TABLES = {
+  companyID: "company",
+  contractID: "contract",
+  ticketID: "ticket",
+  roleID: "role",
+  billingCodeID: "billingCode"
+};
+var isResourceFkField = (field) => field === "resourceID" || field.endsWith("ResourceID");
+var LABEL_NAME_MAX_CHARS = 200;
+function untrustedName(name) {
+  if (name === null) return null;
+  const [[capped]] = truncateNoteChars([{ v: name }], LABEL_NAME_MAX_CHARS, ["v"]);
+  return wrapUntrusted(capped.v) ?? capped.v;
+}
+function readNamesOpt(client, value, where) {
+  if (value === void 0) return client?.config?.labels ?? false;
+  if (typeof value !== "boolean") {
+    throw new AutotaskConfigError(`${where}: names must be a boolean (got ${typeof value}) \u2014 true adds label siblings, false returns raw ids only, absent uses the client's labels option (off by default)`);
+  }
+  return value;
+}
+async function labelRows(client, resourceKey, rows) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const row of rows) for (const k of Object.keys(row)) keys.add(k);
+  if (keys.size === 0) return { rows: [...rows] };
+  let picklistFields = [];
+  const modelFields = MODEL_FIELD_SETS[resourceKey] ?? [];
+  const candidates = [...keys].filter((f) => f !== "id" && modelFields.includes(f) && ROW_FK_TABLES[f] === void 0 && !isResourceFkField(f));
+  if (candidates.length > 0) {
+    try {
+      const catalog = await fieldCatalog(client, { resources: [resourceKey], labels: true });
+      const row = catalog.rows.find((r) => r.resource === resourceKey);
+      if (row !== void 0 && row.error === null && row.fields !== void 0) {
+        picklistFields = row.fields.filter((f) => f.isPickList).map((f) => f.name).filter((f) => candidates.includes(f));
+      }
+    } catch (err) {
+      if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
     }
-    for (const [rel, leaves] of byRel) {
-      const ids2 = await parentIds(rel, leaves);
-      if (ids2.length === 0) return NEVER;
-      out.push({ field: `${rel}ID`, op: "in", value: ids2 });
+  }
+  const labelled = (field) => picklistFields.includes(field) || ROW_FK_TABLES[field] !== void 0 || isResourceFkField(field);
+  if (![...keys].some(labelled)) return { rows: [...rows] };
+  const builder = createNamePlan(picklistFields, resourceKey);
+  for (const row of rows) {
+    for (const [field, value] of Object.entries(row)) {
+      const table = ROW_FK_TABLES[field];
+      if ((value === 0 || value === "0") && table !== "company") continue;
+      if (table !== void 0) builder.addFk(table, value);
+      else if (isResourceFkField(field)) builder.addResource(value);
     }
-    return out.length === 0 && mode === "or" ? NEVER : out;
-  };
-  const rewritten = await rewrite(conds, "and");
-  if (rewritten === NEVER) {
-    return { never: true, note: `no parent record matched the relation conditions \u2014 0 ${resourceKey} rows (the ${resourceKey} query was not issued)` };
   }
-  return { never: false, conditions: rewritten };
+  const plan = builder.plan();
+  const names = plan.resourceIds.length === 0 && plan.recordFks.length === 0 && picklistFields.length === 0 ? void 0 : await resolveCompositeNames(client.http, plan);
+  const out = rows.map((row) => {
+    const r = { ...row };
+    for (const [field, value] of Object.entries(row)) {
+      const has2 = value !== null && value !== void 0 && names !== void 0;
+      if (picklistFields.includes(field)) r[`${field}Label`] = has2 ? names.labelFor(field, value) : null;
+      const table = ROW_FK_TABLES[field];
+      const set = has2 && (table === "company" || value !== 0 && value !== "0");
+      if (table !== void 0) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.recordName(table, value)) : null;
+      else if (isResourceFkField(field)) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.resourceName(value)) : null;
+    }
+    return r;
+  });
+  const capHit = names?.section.truncated === true;
+  const unresolved = Object.keys(names?.section.reasons ?? {});
+  if (capHit === false && unresolved.length === 0) return { rows: out };
+  const parts = [];
+  if (capHit) parts.push(`ids left unlabelled (their *Name is null): the per-call cap of ${DEFAULT_MAX_NAME_READS} uncached name reads was hit \u2014 names already read are cached, so repeating or narrowing the call labels more`);
+  if (unresolved.length > 0) parts.push(`picklist label(s) unavailable for ${unresolved.join(", ")} (see reasons)`);
+  return { rows: out, names: { note: parts.join("; "), ...Object.keys(names.section.reasons).length > 0 ? { reasons: names.section.reasons } : {} } };
+}
+async function labelFetchResults(client, result) {
+  const byResource = /* @__PURE__ */ new Map();
+  result.results.forEach((r, i) => {
+    if (r.found && r.value !== null) byResource.set(r.resource, [...byResource.get(r.resource) ?? [], i]);
+  });
+  const results = [...result.results];
+  const notes = [];
+  const reasons = {};
+  for (const [resource, indices] of byResource) {
+    const labelled = await labelRows(client, resource, indices.map((i) => results[i].value));
+    indices.forEach((idx, j) => {
+      results[idx] = { ...results[idx], value: labelled.rows[j] };
+    });
+    if (labelled.names !== void 0) {
+      notes.push(labelled.names.note);
+      for (const [field, why] of Object.entries(labelled.names.reasons ?? {})) reasons[field] = why;
+    }
+  }
+  if (notes.length === 0) return { ...result, results };
+  return { ...result, results, names: { note: notes.join("; "), ...Object.keys(reasons).length > 0 ? { reasons } : {} } };
+}
+
+// src/operations/walkBag.ts
+function validateWalkBag(walk, prefix, details) {
+  if (walk === void 0) return void 0;
+  const wr = typeof walk === "object" && walk !== null && !Array.isArray(walk) ? walk.maxRows : void 0;
+  if (!Number.isInteger(wr) || wr < 1) {
+    throw new AutotaskConfigError(
+      `${prefix} walk.maxRows must be a positive integer (got ${String(wr)}) \u2014 it is the walk's TOTAL row cap (the bounding cap = min(limit, walk.maxRows))`,
+      details
+    );
+  }
+  return wr;
 }
 
 // src/resources/base/query.ts
@@ -17968,19 +18365,19 @@ var QueryBase = class {
   /**
    * Stream items across pages (the resource `query` surface — the MCP
    * server's `output_path` walk). Issue #281: relation filters resolve first
-   * (as queryBounded), and each page's rows carry the default label siblings
-   * (issue #276, the same `labelRows`) unless `names: false`. Labelling runs
-   * per page, so the cold name-read cap (20) applies per page; a capped id
-   * gets a null `*Name` (an iterator has no result envelope for the `names`
-   * summary). A resource built without a client (bare `HttpClient`) yields
-   * raw rows.
+   * (as queryBounded). Label siblings are opt-in (issue #287): the per-call
+   * `names` key is the explicit override, absent = the client's `labels`
+   * option (off by default). When on, labelling runs per page, so the cold
+   * name-read cap (20) applies per page; a capped id gets a null `*Name`
+   * (an iterator has no result envelope for the `names` summary). A
+   * resource built without a client (bare `HttpClient`) yields raw rows.
    */
   async *queryItems(params) {
     const { names, ...rest } = params ?? {};
-    const label = readNamesOpt(names, `${this.config.key}.query`);
+    const client = this.http.client;
+    const label = readNamesOpt(client, names, `${this.config.key}.query`);
     const walk = await this.relationWalkParams(rest, `${this.config.key}.query`);
     if (walk === void 0) return;
-    const client = this.http.client;
     if (!label || client === void 0) {
       yield* paginateItems(this.pageFetcher(walk), { pageSize: this.walkPageSize(walk) });
       return;
@@ -18049,8 +18446,7 @@ var QueryBase = class {
         `queryBounded: noteChars must be an integer >= 1 (got ${String(noteChars)}) \u2014 it is the per-field char cap on the untrusted-class free-text fields (absent = the raw, untruncated result)`
       );
     }
-    let walkParams = params?.fieldsPreset !== void 0 ? { ...params, includeFields: resolveFieldsPreset(params.fieldsPreset, this.config.key, params.includeFields) } : params ?? {};
-    const latest = walkParams.latest;
+    const latest = params?.latest;
     if (latest !== void 0) {
       if (!Number.isInteger(latest) || latest < 1 || latest > BOUNDED_QUERY_MAX_LIMIT) {
         throw new AutotaskConfigError(
@@ -18063,15 +18459,27 @@ var QueryBase = class {
         );
       }
     }
+    const walk = params?.walk;
+    const maxRows = validateWalkBag(walk, "queryBounded:");
+    if (walk !== void 0 && latest !== void 0) {
+      throw new AutotaskConfigError(
+        "queryBounded: walk.maxRows is not combinable with latest \u2014 the count-anchored mechanism has its own walk window"
+      );
+    }
+    const cap = maxRows !== void 0 ? Math.min(limit, maxRows) : limit;
+    let walkParams = params ?? {};
     const relation = await rewriteRelationFilters(this.http, this.config.key, normalizedConditions(walkParams.filter), `${this.config.key}.query`);
     if (relation?.never === true) return { items: [], fetched: 0, hasMore: false, pagesWalked: 0, relationNote: relation.note };
     if (relation !== void 0) walkParams = { ...walkParams, filter: relation.conditions };
     if (latest !== void 0) {
       return this.applyNoteChars(await this.latestWalk(walkParams, Math.max(limit, latest), latest), noteChars);
     }
-    const { items, pages, guard, sliced, cursor } = await this.walkBounded(walkParams, limit);
-    const hasMore = (items.length >= limit || guard) && (sliced > 0 || cursor !== null);
+    const { items, pages, guard, sliced, cursor } = await this.walkBounded(walkParams, cap, limit);
+    const hasMore = (items.length >= cap || guard) && (sliced > 0 || cursor !== null);
     const result = { items, fetched: items.length, hasMore, pagesWalked: pages };
+    if (maxRows !== void 0) {
+      result.truncated = items.length >= maxRows && (sliced > 0 || cursor !== null || guard);
+    }
     this.stampEmptyQueryResult(result, params);
     return this.applyNoteChars(result, noteChars);
   }
@@ -18102,13 +18510,13 @@ var QueryBase = class {
    *  SOFT stop (never a throw). ONE per-walk closure (walks never share
    *  state).
    * @internal */
-  async walkBounded(p, limit) {
+  async walkBounded(p, limit, pageSizeBase) {
     const state = { cursor: null };
     const items = [];
     let pages = 0;
     let sliced = 0;
     let guard = false;
-    const pageSize = Math.min(MAX_PAGE_SIZE, limit);
+    const pageSize = Math.min(MAX_PAGE_SIZE, pageSizeBase ?? limit);
     for (; ; ) {
       if (pages >= MAX_PAGES) {
         guard = true;
@@ -18724,1333 +19132,884 @@ var MetaBase = class extends QueryBase {
    *   `searchFields`, capped by the client caps (`maxScanRecords` /
    *   `maxScanPages`). A hit is cost `client-scan`; a completed scan with no
    *   match → null; a cap-tripped scan THROWS RESOLUTION_TRUNCATED — never a
-   *   silent null.
-   * - bare value on an id-only resource → AutotaskConfigError (CONFIG_ERROR).
-   */
-  async resolveDetailed(identifier) {
-    let numeric = null;
-    if (isIdentifierCandidate(identifier)) {
-      numeric = parseIdentifier(identifier, "id");
-    }
-    if (numeric !== null) {
-      const record = await this.fetchRecordRaw(this.resourcePath, numeric);
-      return { value: record, resolutionCost: "direct", scanned: 0, scanTruncated: false };
-    }
-    if (typeof identifier !== "string" || identifier.trim() === "") {
-      throw new AutotaskConfigError("resolve: identifier must be a numeric id or a non-empty value");
-    }
-    const value = identifier.trim();
-    const fields = this.config.searchFields ?? [];
-    if (fields.length === 0) {
-      throw new AutotaskConfigError(
-        `resolve: ${this.config.key} has no primary text field (ids only)`
-      );
-    }
-    const leaf = fields.map((field) => ({ field, op: "eq", value }));
-    const root = leaf.length === 1 ? leaf[0] : { op: "or", items: leaf };
-    const items = await this.queryPage1([root], 2);
-    if (items.length === 1) {
-      return { value: items[0], resolutionCost: "server-filter", scanned: 0, scanTruncated: false };
-    }
-    if (items.length >= 2) {
-      const ids2 = items.map((m) => m.id).filter((id) => typeof id === "number");
-      throw new ResolutionError(
-        `resolve: "${value}" is ambiguous on ${this.config.key} (matched ${items.length} records)`,
-        {
-          code: "RESOLUTION_AMBIGUOUS",
-          resourceIds: ids2,
-          details: { idRefs: ids2.map((cid) => ({ entity: this.entityName, id: cid })) },
-          // issue #59 PR-B: the miss-channel pointer (the generic floor names
-          // the resource's own search op — reachable only where searchFields
-          // is non-empty, so the named op always exists here).
-          suggestedAction: `Narrow the identifier to the full exact value, or run ${this.config.key}.search (contains match) for candidate records to disambiguate.`
-        }
-      );
-    }
-    if (!this.resolutionCaps.scanOnMiss) {
-      return { value: null, resolutionCost: "server-filter", scanned: 0, scanTruncated: false, triedFields: fields };
-    }
-    const scan = await this.scanForExactMatch(value, fields);
-    if (scan.found !== null) {
-      return {
-        value: scan.found,
-        resolutionCost: "client-scan",
-        scanned: scan.scanned,
-        scanTruncated: false
-      };
-    }
-    if (scan.truncated) {
-      throw new ResolutionError(
-        `resolve: "${value}" is unverified on ${this.config.key} \u2014 the bounded client scan read ${scan.scanned} records (cap) without completing; a complete non-match cannot be proven`,
-        {
-          code: "RESOLUTION_TRUNCATED",
-          // issue #59 PR-B: the pointer channel on the unverified-miss outcome
-          // (the contains-candidates channel is the resource's search op).
-          suggestedAction: `Retry with a more specific identifier, or narrow the search to fewer records (contains candidates: ${this.config.key}.search).`
-        }
-      );
-    }
-    return { value: null, resolutionCost: "client-scan", scanned: scan.scanned, scanTruncated: false, triedFields: fields };
-  }
-  /**
-   * Issue #78: `resolve` with the miss explained. A hit is `{ record, resolutionCost }`
-   * (unchanged). A miss is never a bare `null`: `miss` carries the fields and operator
-   * tried, the blind-surface stamp when the surface is blind, and the next steps.
-   * Thrown outcomes (not found by id, ambiguous, truncated) are unchanged.
-   */
-  async resolveWithDetail(identifier) {
-    const r = await this.resolveDetailed(identifier);
-    if (r.value !== null) return { record: r.value, resolutionCost: r.resolutionCost };
-    return { record: null, resolutionCost: r.resolutionCost, miss: this.missDetail("eq", r.triedFields ?? this.config.searchFields ?? []) };
-  }
-  /**
-   * Issue #78: `search` with an empty result explained (a bare `[]` reads as complete on a
-   * blind surface). Hits are `{ items }` (unchanged); an empty result adds `miss`.
-   */
-  async searchWithDetail(query, opts = {}) {
-    const items = await this.searchBase(query, opts);
-    if (items.length > 0) return { items };
-    return { items, miss: this.missDetail("contains", this.config.searchFields ?? []) };
-  }
-  /** The shared miss explanation for `resolveWithDetail` / `searchWithDetail`. @internal */
-  missDetail(operator, fields) {
-    const key = this.config.key;
-    const probe = fields.map((field) => ({ field, op: operator, value: "" }));
-    const blind = blindStampFor(BLIND_SURFACE_STAMPS[key]?.query, probe);
-    const next = [];
-    if (blind !== void 0) {
-      next.push(`This surface is blind to records the API user does not own, so a miss is not proof of absence: ${blind.authority} returns the record when the id is known.`);
-    }
-    next.push(
-      operator === "eq" ? `Matching is exact on ${fields.join(", ")} (other identifier forms were not tried); ${key}.search finds contains candidates.` : `Matching is a contains match on ${fields.join(", ")}; try a shorter or different fragment, or ${key}.resolve with the full exact value.`
-    );
-    return { tried: { fields: [...fields], operator }, ...blind !== void 0 ? { blindSurface: blind } : {}, next };
-  }
-  /** The plain value projection of `resolveDetailed` (the `resolve` floor). */
-  async resolveBase(identifier) {
-    return (await this.resolveDetailed(identifier)).value;
-  }
-  /** The items of one page of the resource's own `/query`. */
-  async queryPage1(conditions, maxRecords) {
-    const body = {
-      filter: buildFilter(conditions).filter,
-      MaxRecords: maxRecords
-    };
-    const res = await this.http.request({
-      method: "POST",
-      idempotent: true,
-      path: `${this.resourcePath}/query`,
-      body,
-      operation: `${this.config.key}.resolve`
-    });
-    return unwrapItems(res, `${this.config.key}.resolve`).items;
-  }
-  /**
-   * The bounded client-scan fallback (section 19.2): an unfiltered walk of
-   * the resource's own query endpoint, exact match on `fields`, bounded by
-   * BOTH client caps (records AND pages). `truncated` is true when the caps
-   * were hit before the walk completed (a complete non-match is unproven).
-   */
-  async scanForExactMatch(value, fields) {
-    const caps = this.resolutionCaps;
-    const pageSize = Math.max(1, Math.floor(caps.maxScanRecords / caps.maxScanPages));
-    const state = { cursor: null };
-    let scanned = 0;
-    let pages = 0;
-    let found = null;
-    let exhausted = false;
-    for (; ; ) {
-      const page = await this.fetchPage({ maxRecords: pageSize }, pages + 1, pageSize, state);
-      pages += 1;
-      for (const item of page.items) {
-        scanned += 1;
-        const rec = item;
-        if (fields.some((field) => rec[field] === value)) {
-          found = item;
-          break;
-        }
-      }
-      if (found !== null) break;
-      if (!page.hasMore) {
-        exhausted = true;
-        break;
-      }
-      if (pages >= caps.maxScanPages || scanned >= caps.maxScanRecords) break;
-    }
-    return { found, scanned, truncated: found === null && !exhausted };
-  }
-  /**
-   * `findBy<field>` helpers: exact (`eq`) filter on one vendor field, bounded
-   *  to 2 records — 0 → null, 1 → the record, ≥2 → ResolutionError with the
-   *  candidate ids.
-   */
-  async findByField(field, value) {
-    if (value.trim() === "") throw new AutotaskConfigError(`findBy${field}: empty value`);
-    const matches = await this.queryEntity(
-      `${this.resourcePath}/query`,
-      [{ field, op: "eq", value: value.trim() }],
-      { maxRecords: 2 }
-    );
-    if (matches.length === 0) return null;
-    if (matches.length > 1) {
-      const ids2 = matches.map((m) => m.id).filter((id) => typeof id === "number");
-      throw new ResolutionError(
-        `findBy${field}: "${value}" is ambiguous on ${this.config.key} (matched ${matches.length} records)`,
-        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids2, details: { idRefs: ids2.map((cid) => ({ entity: this.entityName, id: cid })) } }
-      );
-    }
-    return matches[0];
-  }
-  /**
-   * `search` — the bounded contains surface (no vendor free-text search):
-   * `contains` on every `searchFields` field (OR-grouped), `MaxRecords` =
-   * `limit` (default 25, clamped to 1..500). Empty query → AutotaskConfigError.
+   *   silent null.
+   * - bare value on an id-only resource → AutotaskConfigError (CONFIG_ERROR).
    */
-  async searchBase(query, opts = {}) {
-    const text = query.trim();
-    if (text === "") throw new AutotaskConfigError("search: empty query");
+  async resolveDetailed(identifier) {
+    let numeric = null;
+    if (isIdentifierCandidate(identifier)) {
+      numeric = parseIdentifier(identifier, "id");
+    }
+    if (numeric !== null) {
+      const record = await this.fetchRecordRaw(this.resourcePath, numeric);
+      return { value: record, resolutionCost: "direct", scanned: 0, scanTruncated: false };
+    }
+    if (typeof identifier !== "string" || identifier.trim() === "") {
+      throw new AutotaskConfigError("resolve: identifier must be a numeric id or a non-empty value");
+    }
+    const value = identifier.trim();
     const fields = this.config.searchFields ?? [];
     if (fields.length === 0) {
-      throw new AutotaskConfigError(`search: ${this.config.key} has no searchable field`);
+      throw new AutotaskConfigError(
+        `resolve: ${this.config.key} has no primary text field (ids only)`
+      );
     }
-    const limit = opts.limit === void 0 ? 25 : clampPageSize(opts.limit);
-    const leaf = fields.map((field) => ({ field, op: "contains", value: text }));
+    const leaf = fields.map((field) => ({ field, op: "eq", value }));
     const root = leaf.length === 1 ? leaf[0] : { op: "or", items: leaf };
-    for (const key of Object.keys(opts)) {
-      if (key !== "limit" && key !== "companyID" && key !== "includeFields") {
-        throw new AutotaskConfigError(`search: unknown opts key "${key}" \u2014 the bag is closed: limit, companyID, includeFields`);
-      }
+    const items = await this.queryPage1([root], 2);
+    if (items.length === 1) {
+      return { value: items[0], resolutionCost: "server-filter", scanned: 0, scanTruncated: false };
     }
-    if (opts.companyID !== void 0 && !isIdentifierCandidate(opts.companyID)) {
-      throw new AutotaskConfigError(`search: companyID must be a positive integer id (got ${String(opts.companyID)})`);
+    if (items.length >= 2) {
+      const ids2 = items.map((m) => m.id).filter((id) => typeof id === "number");
+      throw new ResolutionError(
+        `resolve: "${value}" is ambiguous on ${this.config.key} (matched ${items.length} records)`,
+        {
+          code: "RESOLUTION_AMBIGUOUS",
+          resourceIds: ids2,
+          details: { idRefs: ids2.map((cid) => ({ entity: this.entityName, id: cid })) },
+          // issue #59 PR-B: the miss-channel pointer (the generic floor names
+          // the resource's own search op — reachable only where searchFields
+          // is non-empty, so the named op always exists here).
+          suggestedAction: `Narrow the identifier to the full exact value, or run ${this.config.key}.search (contains match) for candidate records to disambiguate.`
+        }
+      );
     }
-    if (opts.includeFields !== void 0 && (!Array.isArray(opts.includeFields) || opts.includeFields.length === 0 || opts.includeFields.some((f) => typeof f !== "string" || f === ""))) {
-      throw new AutotaskConfigError("search: includeFields must be a non-empty array of field names");
+    if (!this.resolutionCaps.scanOnMiss) {
+      return { value: null, resolutionCost: "server-filter", scanned: 0, scanTruncated: false, triedFields: fields };
     }
-    const companyID = opts.companyID === void 0 ? void 0 : Number(opts.companyID);
-    const includeFields = opts.includeFields === void 0 ? void 0 : opts.includeFields.includes("id") ? opts.includeFields : ["id", ...opts.includeFields];
-    const conditions = companyID === void 0 ? [root] : [{ field: "companyID", op: "eq", value: companyID }, root];
-    const rows = await this.queryEntity(`${this.resourcePath}/query`, conditions, {
-      maxRecords: limit,
-      ...includeFields !== void 0 ? { includeFields } : {}
-    });
-    if (includeFields === void 0 || includeFields.includes("userDefinedFields")) return rows;
-    return rows.map((row) => {
-      const r = row;
-      if (!Array.isArray(r.userDefinedFields) || r.userDefinedFields.length > 0) return row;
-      const rest = { ...r };
-      delete rest.userDefinedFields;
-      return rest;
-    });
-  }
-};
-function isEmpty(value) {
-  if (value === null || value === void 0) return true;
-  if (Array.isArray(value)) return value.length === 0;
-  return typeof value === "object" && Object.keys(value).length === 0;
-}
-
-// src/resources/base/mutations.ts
-var MutationBase = class extends MetaBase {
-  // ------------------------------------------------------------------
-  // Mutations
-  // ------------------------------------------------------------------
-  /** Normalise a mutation body: `id` OR `itemId` → `id`; UDF map → UDF array (UDF-capable only). */
-  normalizeMutationBody(data) {
-    const body = { ...data };
-    if (body.itemId !== void 0 && body.id === void 0) {
-      body.id = body.itemId;
-      delete body.itemId;
+    const scan = await this.scanForExactMatch(value, fields);
+    if (scan.found !== null) {
+      return {
+        value: scan.found,
+        resolutionCost: "client-scan",
+        scanned: scan.scanned,
+        scanTruncated: false
+      };
     }
-    if (this.config.udfCapable && body.userDefinedFields !== void 0) {
-      body.userDefinedFields = normalizeUdfInput(body.userDefinedFields);
+    if (scan.truncated) {
+      throw new ResolutionError(
+        `resolve: "${value}" is unverified on ${this.config.key} \u2014 the bounded client scan read ${scan.scanned} records (cap) without completing; a complete non-match cannot be proven`,
+        {
+          code: "RESOLUTION_TRUNCATED",
+          // issue #59 PR-B: the pointer channel on the unverified-miss outcome
+          // (the contains-candidates channel is the resource's search op).
+          suggestedAction: `Retry with a more specific identifier, or narrow the search to fewer records (contains candidates: ${this.config.key}.search).`
+        }
+      );
     }
-    return body;
-  }
-  /** `POST /V1.0/<E>` → `{ id }` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
-  async createGlobal(data, opts = {}) {
-    const body = this.normalizeMutationBody(data);
-    const res = await this.http.request({
-      method: "POST",
-      path: this.resourcePath,
-      body,
-      operation: `${this.config.key}.create`,
-      maxRetries: opts.maxRetries
-    });
-    return this.unwrapCreateOperation(res, body, opts);
+    return { value: null, resolutionCost: "client-scan", scanned: scan.scanned, scanTruncated: false, triedFields: fields };
   }
   /**
-   * Issue #13: the create-response envelope unwrap with the bounded marker
-   * recovery. The fast path is the plain `unwrapOperation` (a well-formed
-   * envelope costs ZERO extra requests and returns the byte-identical
-   * `{ id }` result). Only a typed `INVALID_RESPONSE` (a 2xx body that is
-   * not the specced envelope / `{ id }` / `{ itemId }` alternative) with a
-   * plan-pinned marker field AND `recoverIdFromMarker !== false` runs the
-   * fallback — and it can only run on the APPLY path: a dry run returns the
-   * pinned envelope BEFORE the mutating request, so the fallback never sees
-   * a dry-run response (skipped entirely by construction).
-   * @internal
+   * Issue #78: `resolve` with the miss explained. A hit is `{ record, resolutionCost }`
+   * (unchanged). A miss is never a bare `null`: `miss` carries the fields and operator
+   * tried, the blind-surface stamp when the surface is blind, and the next steps.
+   * Thrown outcomes (not found by id, ambiguous, truncated) are unchanged.
    */
-  async unwrapCreateOperation(body, wireBody, opts) {
-    const operation = `${this.config.key}.create`;
-    try {
-      return unwrapOperation(body, operation);
-    } catch (err) {
-      if (!isAutotaskError(err) || err.code !== "INVALID_RESPONSE") throw err;
-      const pin = RESPONSE_DRIFT_MARKERS[this.config.key];
-      if (pin === void 0 || opts.recoverIdFromMarker === false) throw err;
-      return this.recoverCreatedIdByMarker(err, body, wireBody, opts, pin);
-    }
+  async resolveWithDetail(identifier) {
+    const r = await this.resolveDetailed(identifier);
+    if (r.value !== null) return { record: r.value, resolutionCost: r.resolutionCost };
+    return { record: null, resolutionCost: r.resolutionCost, miss: this.missDetail("eq", r.triedFields ?? this.config.searchFields ?? []) };
   }
   /**
-   * Issue #13: the ONE bounded marker read on the resource's own query
-   * surface (`POST <collection>/query`, MaxRecords 5 — a read: idempotent,
-   * zero mutating wire; the fallback never issues anything else). Outcomes:
-   * exactly ONE numeric match → the normal success result stamped
-   * `idFrom: 'marker-recovery'` + the `shapeDrift` note; zero matches, more
-   * than one, or a cap-tripped search (a full 5 + a next cursor) → the
-   * existing `INVALID_RESPONSE` with the drift detail + the failed search
-   * (candidate ids listed — never a guessed id).
-   * @internal
+   * Issue #78: `search` with an empty result explained (a bare `[]` reads as complete on a
+   * blind surface). Hits are `{ items }` (unchanged); an empty result adds `miss`.
    */
-  async recoverCreatedIdByMarker(err, body, wireBody, opts, pin) {
-    const operation = `${this.config.key}.create`;
-    const markerField = typeof opts.markerField === "string" && opts.markerField.trim() !== "" ? opts.markerField.trim() : pin.markerField;
-    const markerToken = typeof opts.markerToken === "string" && opts.markerToken.trim() !== "" ? opts.markerToken.trim() : defaultMarkerToken(wireBody);
-    if (markerToken === null) throw err;
-    const observedShape = describeResponseShape(body);
-    const res = await this.http.request({
-      method: "POST",
-      idempotent: true,
-      path: `${this.resourcePath}/query`,
-      body: { MaxRecords: MARKER_RECOVERY_LIMIT, filter: [{ field: markerField, op: "contains", value: markerToken }] },
-      operation: `${operation}.marker-recovery`
-    });
-    const { items, pageDetails } = unwrapItems(res, operation);
-    const truncated = items.length >= MARKER_RECOVERY_LIMIT && pageDetails.nextPageUrl != null;
-    const drift = {
-      observedShape,
-      speccedEnvelope: "OperationResultModel",
-      markerField,
-      markerToken,
-      matches: items.length,
-      truncated,
-      note: pin.note
-    };
-    const numericIds = items.map((row) => {
-      const id = row.id;
-      if (typeof id === "number" && Number.isInteger(id) && id >= 0) return id;
-      if (typeof id === "string" && /^\d+$/.test(id.trim())) {
-        const parsed = Number.parseInt(id.trim(), 10);
-        return Number.isSafeInteger(parsed) ? parsed : id.trim();
-      }
-      return null;
-    });
-    if (items.length === 1 && !truncated && numericIds[0] !== null) {
-      const id = numericIds[0];
-      const shapeDrift = {
-        observedShape,
-        speccedEnvelope: "OperationResultModel",
-        note: `The create answered 2xx with a body that is not the specced OperationResultModel (observed: ${observedShape}); the id was recovered by ONE bounded marker read (${markerField} contains the caller's marker, limit ${MARKER_RECOVERY_LIMIT}) \u2014 exactly one numeric match.`
-      };
-      return { id, idFrom: "marker-recovery", shapeDrift };
+  async searchWithDetail(query, opts = {}) {
+    const items = await this.searchBase(query, opts);
+    if (items.length > 0) return { items };
+    return { items, miss: this.missDetail("contains", this.config.searchFields ?? []) };
+  }
+  /** The shared miss explanation for `resolveWithDetail` / `searchWithDetail`. @internal */
+  missDetail(operator, fields) {
+    const key = this.config.key;
+    const probe = fields.map((field) => ({ field, op: operator, value: "" }));
+    const blind = blindStampFor(BLIND_SURFACE_STAMPS[key]?.query, probe);
+    const next = [];
+    if (blind !== void 0) {
+      next.push(`This surface is blind to records the API user does not own, so a miss is not proof of absence: ${blind.authority} returns the record when the id is known.`);
     }
-    const candidateIds = numericIds.map((n, i) => n ?? String(items[i].id ?? "unknown"));
-    const outcome = items.length === 0 ? "found 0 matches" : truncated ? `found ${items.length} matches at the limit ${MARKER_RECOVERY_LIMIT} cap (truncated \u2014 more may exist)` : `found ${items.length} matches`;
-    err.details = { ...err.details, responseDrift: { ...drift, candidateIds } };
-    err.suggestedAction = `The create answered 2xx with a body that is not the specced OperationResultModel (observed shape: ${observedShape}); the bounded marker recovery (${markerField} contains the caller's marker, limit ${MARKER_RECOVERY_LIMIT}) ${outcome} \u2014 ` + (items.length === 0 ? "the record may exist with an unfindable marker; report the vendor response-shape drift and locate the record in the UI." : "refusing to guess an id \u2014 disambiguate with an exact-field query (or the UI) and recover the id before retrying.");
-    throw err;
+    next.push(
+      operator === "eq" ? `Matching is exact on ${fields.join(", ")} (other identifier forms were not tried); ${key}.search finds contains candidates.` : `Matching is a contains match on ${fields.join(", ")}; try a shorter or different fragment, or ${key}.resolve with the full exact value.`
+    );
+    return { tried: { fields: [...fields], operator }, ...blind !== void 0 ? { blindSurface: blind } : {}, next };
+  }
+  /** The plain value projection of `resolveDetailed` (the `resolve` floor). */
+  async resolveBase(identifier) {
+    return (await this.resolveDetailed(identifier)).value;
+  }
+  /** The items of one page of the resource's own `/query`. */
+  async queryPage1(conditions, maxRecords) {
+    const body = {
+      filter: buildFilter(conditions).filter,
+      MaxRecords: maxRecords
+    };
+    const res = await this.http.request({
+      method: "POST",
+      idempotent: true,
+      path: `${this.resourcePath}/query`,
+      body,
+      operation: `${this.config.key}.resolve`
+    });
+    return unwrapItems(res, `${this.config.key}.resolve`).items;
   }
-  /** `PUT /V1.0/<E>/{id}` (the vendor tolerates PATCH at the same path) → `{ id }`.
-   *  For collection-only-writable resources (`collectionUpdate`, D1) the
-   *  vendor spec defines no put/patch on the item path (it is GET-only; the
-   *  item-path PUT 405s), so the confirmed update hits the COLLECTION
-   *  `PUT /V1.0/<E>` with the record id merged into the mutation body — the
-   *  vendor keys the record by the id in the body (the same convention the
-   *  parent-scoped `updateScopedRaw` PATCH uses).
-   *
-   *  V2 partial-update merge: the vendor's collection PUT validates the FULL
-   *  model (a partial body 500s 'Missing Required Field'), so a
-   *  collectionUpdate update MERGES the caller's partial body into the
-   *  record's current full model before the PUT: ONE fresh GET serves both
-   *  the merge source and the stale-object guard's read (a `lastModifiedDate`
-   *  mismatch throws STALE_OBJECT before the PUT; the guard semantics are
-   *  unchanged — it is a no-op where the model lacks the field or the caller
-   *  supplied no token). `opts.raw === true` sends the caller body as-is
-   *  instead (the pre-merge wire; the guard keeps its own verification read
-   *  when a token is supplied).
-   *
-   *  Issue #34: with `update.putFallback: true` (OFF by default), a TYPED
-   *  404 on the pinned route retries ONCE as `PUT /{Entity}/{id}` where the
-   *  gate holds — never a collectionUpdate route (the spec defines no
-   *  item-path update there), never a `raw: true` update, never a non-404
-   *  fault; the retry body runs the same fresh-read merge (see
-   *  `putFallbackMergedBody`), so the fallback is never a null-clearing
-   *  partial. A declined gate (a collectionUpdate route 404s, or the retry
-   *  itself 404s) throws the self-explaining typed error (the route tried,
-   *  the status, the opt-in; `details.putFallback`). */
   /**
-   * Issue #34 gate: the fallback may fire only while `update.putFallback`
-   * is ON and the pinned update route answered a TYPED 404 (a transport
-   * `NotFoundError` with `httpStatus: 404`) — never a 400/405/422/5xx, and
-   * never a 2xx shape fault (those keep today's typed error byte-identical).
-   * @internal
+   * The bounded client-scan fallback (section 19.2): an unfiltered walk of
+   * the resource's own query endpoint, exact match on `fields`, bounded by
+   * BOTH client caps (records AND pages). `truncated` is true when the caps
+   * were hit before the walk completed (a complete non-match is unproven).
    */
-  putFallbackEligible(err) {
-    return this.http.update.putFallback === true && err instanceof NotFoundError && err.httpStatus === 404;
+  async scanForExactMatch(value, fields) {
+    const caps = this.resolutionCaps;
+    const pageSize = Math.max(1, Math.floor(caps.maxScanRecords / caps.maxScanPages));
+    const state = { cursor: null };
+    let scanned = 0;
+    let pages = 0;
+    let found = null;
+    let exhausted = false;
+    for (; ; ) {
+      const page = await this.fetchPage({ maxRecords: pageSize }, pages + 1, pageSize, state);
+      pages += 1;
+      for (const item of page.items) {
+        scanned += 1;
+        const rec = item;
+        if (fields.some((field) => rec[field] === value)) {
+          found = item;
+          break;
+        }
+      }
+      if (found !== null) break;
+      if (!page.hasMore) {
+        exhausted = true;
+        break;
+      }
+      if (pages >= caps.maxScanPages || scanned >= caps.maxScanRecords) break;
+    }
+    return { found, scanned, truncated: found === null && !exhausted };
   }
   /**
-   * Issue #34: the fallback retry body — the caller's (normalised) fields
-   * merged onto a FRESH unredacted read of the current record (the same
-   * merge the collection-update path performs; the read is the live record,
-   * never cached). A target miss on the merge read surfaces with the pinned
-   * update-target reason (the issue-#14 convention) — the recovery has
-   * nothing to merge onto, and no retry is issued.
-   * @internal
+   * `findBy<field>` helpers: exact (`eq`) filter on one vendor field, bounded
+   *  to 2 records — 0 → null, 1 → the record, ≥2 → ResolutionError with the
+   *  candidate ids.
    */
-  async putFallbackMergedBody(read, callerBody, id) {
-    let current;
-    try {
-      current = await read();
-    } catch (err) {
-      if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
-      throw err;
+  async findByField(field, value) {
+    if (value.trim() === "") throw new AutotaskConfigError(`findBy${field}: empty value`);
+    const matches = await this.queryEntity(
+      `${this.resourcePath}/query`,
+      [{ field, op: "eq", value: value.trim() }],
+      { maxRecords: 2 }
+    );
+    if (matches.length === 0) return null;
+    if (matches.length > 1) {
+      const ids2 = matches.map((m) => m.id).filter((id) => typeof id === "number");
+      throw new ResolutionError(
+        `findBy${field}: "${value}" is ambiguous on ${this.config.key} (matched ${matches.length} records)`,
+        { code: "RESOLUTION_AMBIGUOUS", resourceIds: ids2, details: { idRefs: ids2.map((cid) => ({ entity: this.entityName, id: cid })) } }
+      );
     }
-    const merged = mergePartialBody(current, callerBody);
-    merged.id = id;
-    return merged;
+    return matches[0];
   }
   /**
-   * Issue #34: the self-explaining typed error a DECLINED gate throws. The
-   * original transport error keeps its identity (class / code / httpStatus);
-   * the message names the route tried, the status and the opt-in, and the
-   * structured detail rides under `details.putFallback`
-   * (`{ route, status, retried, optIn }`).
-   * @internal
+   * `search` — the bounded contains surface (no vendor free-text search):
+   * `contains` on every `searchFields` field (OR-grouped), `MaxRecords` =
+   * `limit` (default 25, clamped to 1..500). Empty query → AutotaskConfigError.
    */
-  putFallbackDeclined(err, route, retried) {
-    err.message = `${route} answered 404 on the pinned update route; ` + (retried ? `the update.putFallback retry ${route} also answered 404 \u2014 the zone drops the item route as well, so no further recovery is possible` : `the opt-in update.putFallback declines to retry this route (collectionUpdate resources have no spec-defined item-path update; raw updates send exactly what they were told) \u2014 no fallback was issued`);
-    err.details = { ...err.details ?? {}, putFallback: { route, status: 404, retried, optIn: "update.putFallback" } };
-    err.suggestedAction = retried ? "The zone answers 404 for both the pinned update route and the item route \u2014 verify the zone route registration for this entity before retrying." : "The zone drops the pinned update route and the spec defines no item-path update for this resource \u2014 verify the zone route registration, or issue the update against the collection route raw.";
-    return err;
-  }
-  async updateGlobal(id, data, opts = {}) {
-    const numeric = parseIdentifier(id, "id");
-    const operation = `${this.config.key}.update`;
-    let body = this.normalizeMutationBody(data);
-    const collectionUpdate = this.config.collectionUpdate === true;
-    if (collectionUpdate) {
-      if (opts.raw !== true) {
-        let current;
-        try {
-          current = await this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries });
-        } catch (err) {
-          if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
-          throw err;
-        }
-        this.staleObjectCheck(current, opts, operation);
-        body = mergePartialBody(current, body);
-      } else {
-        await this.guardStaleBeforeMutation(numeric, opts, operation);
-      }
-      body.id = numeric;
+  async searchBase(query, opts = {}) {
+    const text = query.trim();
+    if (text === "") throw new AutotaskConfigError("search: empty query");
+    const fields = this.config.searchFields ?? [];
+    if (fields.length === 0) {
+      throw new AutotaskConfigError(`search: ${this.config.key} has no searchable field`);
     }
-    const route = collectionUpdate ? `PUT ${this.resourcePath}` : `PUT ${this.resourcePath}/${numeric}`;
-    let res;
-    try {
-      res = await this.http.request({
-        method: "PUT",
-        path: collectionUpdate ? this.resourcePath : `${this.resourcePath}/${numeric}`,
-        body,
-        operation,
-        maxRetries: opts.maxRetries
-      });
-    } catch (err) {
-      if (!this.putFallbackEligible(err)) throw err;
-      if (collectionUpdate) {
-        throw this.putFallbackDeclined(err, route, false);
-      }
-      const merged = await this.putFallbackMergedBody(
-        () => this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries }),
-        body,
-        numeric
-      );
-      let retry;
-      try {
-        retry = await this.http.request({
-          method: "PUT",
-          path: `${this.resourcePath}/${numeric}`,
-          body: merged,
-          operation,
-          maxRetries: opts.maxRetries
-        });
-      } catch (rerr) {
-        if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, route, true);
-        throw rerr;
+    const limit = opts.limit === void 0 ? 25 : clampPageSize(opts.limit);
+    const leaf = fields.map((field) => ({ field, op: "contains", value: text }));
+    const root = leaf.length === 1 ? leaf[0] : { op: "or", items: leaf };
+    for (const key of Object.keys(opts)) {
+      if (key !== "limit" && key !== "companyID" && key !== "includeFields") {
+        throw new AutotaskConfigError(`search: unknown opts key "${key}" \u2014 the bag is closed: limit, companyID, includeFields`);
       }
-      return unwrapOperation(retry, operation);
     }
-    return unwrapOperation(res, operation);
-  }
-  /** `DELETE /V1.0/<E>/{id}` → `{ id }` (OperationResultModel). A blank 2xx
-   *  (204 / empty body) is a valid vendor delete answer — synthesize the
-   *  result from the path id (issue #25: the transport returns undefined
-   *  for it; a non-blank wrong shape still throws via unwrapOperation). */
-  async deleteGlobal(id, opts = {}) {
-    const numeric = parseIdentifier(id, "id");
-    const res = await this.http.request({
-      method: "DELETE",
-      path: `${this.resourcePath}/${numeric}`,
-      operation: `${this.config.key}.delete`,
-      maxRetries: opts.maxRetries
+    if (opts.companyID !== void 0 && !isIdentifierCandidate(opts.companyID)) {
+      throw new AutotaskConfigError(`search: companyID must be a positive integer id (got ${String(opts.companyID)})`);
+    }
+    if (opts.includeFields !== void 0 && (!Array.isArray(opts.includeFields) || opts.includeFields.length === 0 || opts.includeFields.some((f) => typeof f !== "string" || f === ""))) {
+      throw new AutotaskConfigError("search: includeFields must be a non-empty array of field names");
+    }
+    const companyID = opts.companyID === void 0 ? void 0 : Number(opts.companyID);
+    const includeFields = opts.includeFields === void 0 ? void 0 : opts.includeFields.includes("id") ? opts.includeFields : ["id", ...opts.includeFields];
+    const conditions = companyID === void 0 ? [root] : [{ field: "companyID", op: "eq", value: companyID }, root];
+    const rows = await this.queryEntity(`${this.resourcePath}/query`, conditions, {
+      maxRecords: limit,
+      ...includeFields !== void 0 ? { includeFields } : {}
     });
-    return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
-  }
-  /** Parent-scoped create: `POST .../{parentId}/<Child>` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
-  async createScopedRaw(parentId, data, opts = {}) {
-    const body = this.normalizeMutationBody(data);
-    const res = await this.http.request({
-      method: "POST",
-      path: this.scopedCollectionPath(parentId),
-      body,
-      operation: `${this.config.key}.create`,
-      maxRetries: opts.maxRetries
+    if (includeFields === void 0 || includeFields.includes("userDefinedFields")) return rows;
+    return rows.map((row) => {
+      const r = row;
+      if (!Array.isArray(r.userDefinedFields) || r.userDefinedFields.length > 0) return row;
+      const rest = { ...r };
+      delete rest.userDefinedFields;
+      return rest;
     });
-    return this.unwrapCreateOperation(res, body, opts);
   }
-  /** Parent-scoped update: `PATCH .../{parentId}/<Child>` — the COLLECTION.
-   *  Swagger documents put+patch on the scoped collection and has NO put/patch on
-   *  the item path anywhere in the spec; the node strips the id from the path and
-   *  PATCHes the collection, and the vendor keys the record by the id in the body. */
-  async updateScopedRaw(parentId, id, data, opts = {}) {
-    const numeric = parseIdentifier(id, "id");
-    const body = this.normalizeMutationBody(data);
-    body.id = numeric;
-    const path = this.scopedCollectionPath(parentId);
-    const operation = `${this.config.key}.update`;
-    let res;
-    try {
-      res = await this.http.request({
-        method: "PATCH",
-        path,
-        body,
-        operation,
-        maxRetries: opts.maxRetries
-      });
-    } catch (err) {
-      if (!this.putFallbackEligible(err)) throw err;
-      const merged = await this.putFallbackMergedBody(
-        () => this.getScopedUnredacted(parentId, numeric, { maxRetries: opts.maxRetries }),
-        body,
-        numeric
-      );
-      let retry;
-      try {
-        retry = await this.http.request({
-          method: "PUT",
-          path: `${path}/${numeric}`,
-          body: merged,
-          operation,
-          maxRetries: opts.maxRetries
-        });
-      } catch (rerr) {
-        if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, `PUT ${path}/${numeric}`, true);
-        throw rerr;
-      }
-      return unwrapOperation(retry, operation);
+  /**
+   * Issue #287 (D7): the bounded CONTAINS fallback of `resolveAny`'s
+   * `match: 'auto'` — the resource's own contains surface (`searchBase`),
+   * bounded by the resource's scan RECORD cap (the same cap that bounds the
+   * `scanOnMiss` client scan — default 500 records; the walk's page clamp
+   * keeps the fetch within the bounded-query page budget). Returns the
+   * matching items (0..cap): the caller folds 1-hit / many / none. Zero wire
+   * on an id-only resource (no primary text field → the empty set, so the
+   * caller reports the miss unchanged).
+   */
+  async resolveContainsMatches(value) {
+    const fields = this.config.searchFields ?? [];
+    if (fields.length === 0) return [];
+    const limit = Math.min(this.resolutionCaps.maxScanRecords, 500);
+    return this.searchBase(value, { limit });
+  }
+};
+function isEmpty(value) {
+  if (value === null || value === void 0) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  return typeof value === "object" && Object.keys(value).length === 0;
+}
+
+// src/resources/base/mutations.ts
+var MutationBase = class extends MetaBase {
+  // ------------------------------------------------------------------
+  // Mutations
+  // ------------------------------------------------------------------
+  /** Normalise a mutation body: `id` OR `itemId` → `id`; UDF map → UDF array (UDF-capable only). */
+  normalizeMutationBody(data) {
+    const body = { ...data };
+    if (body.itemId !== void 0 && body.id === void 0) {
+      body.id = body.itemId;
+      delete body.itemId;
     }
-    return unwrapOperation(res, operation);
+    if (this.config.udfCapable && body.userDefinedFields !== void 0) {
+      body.userDefinedFields = normalizeUdfInput(body.userDefinedFields);
+    }
+    return body;
   }
-  /** Parent-scoped delete: `DELETE .../{parentId}/<Child>/{id}` → `{ id }`
-   *  (a blank 2xx synthesizes `{ id }` from the path id — issue #25). */
-  async deleteScopedRaw(parentId, id, opts = {}) {
-    const numeric = parseIdentifier(id, "id");
+  /** `POST /V1.0/<E>` → `{ id }` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
+  async createGlobal(data, opts = {}) {
+    const body = this.normalizeMutationBody(data);
     const res = await this.http.request({
-      method: "DELETE",
-      path: this.scopedItemPath(parentId, id),
-      operation: `${this.config.key}.delete`,
+      method: "POST",
+      path: this.resourcePath,
+      body,
+      operation: `${this.config.key}.create`,
       maxRetries: opts.maxRetries
     });
-    return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
+    return this.unwrapCreateOperation(res, body, opts);
   }
   /**
-   * Attachment delete: the vendor returns the deleted attachment MODEL, not
-   * OperationResultModel (G1 envelope.md) — pass it through typed.
+   * Issue #13: the create-response envelope unwrap with the bounded marker
+   * recovery. The fast path is the plain `unwrapOperation` (a well-formed
+   * envelope costs ZERO extra requests and returns the byte-identical
+   * `{ id }` result). Only a typed `INVALID_RESPONSE` (a 2xx body that is
+   * not the specced envelope / `{ id }` / `{ itemId }` alternative) with a
+   * plan-pinned marker field AND `recoverIdFromMarker !== false` runs the
+   * fallback — and it can only run on the APPLY path: a dry run returns the
+   * pinned envelope BEFORE the mutating request, so the fallback never sees
+   * a dry-run response (skipped entirely by construction).
+   * @internal
    */
-  async deleteScopedModel(parentId, id, opts = {}) {
-    const numeric = parseIdentifier(id, "id");
-    const res = await this.http.request({
-      method: "DELETE",
-      path: this.scopedItemPath(parentId, id),
-      operation: `${this.config.key}.delete`,
-      maxRetries: opts.maxRetries
-    });
-    if (res === void 0) return {};
-    if (!isRecord2(res)) {
-      throw new AutotaskError(
-        `Expected the deleted attachment model for ID ${numeric}; got a different shape`,
-        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric], details: { idRefs: [{ entity: this.entityName, id: numeric }] } }
-      );
+  async unwrapCreateOperation(body, wireBody, opts) {
+    const operation = `${this.config.key}.create`;
+    try {
+      return unwrapOperation(body, operation);
+    } catch (err) {
+      if (!isAutotaskError(err) || err.code !== "INVALID_RESPONSE") throw err;
+      const pin = RESPONSE_DRIFT_MARKERS[this.config.key];
+      if (pin === void 0 || opts.recoverIdFromMarker === false) throw err;
+      return this.recoverCreatedIdByMarker(err, body, wireBody, opts, pin);
     }
-    return res;
   }
-  async createIfNotExists(dataOrParentId, dataOrOpts, opts = {}) {
-    const isObject = (v) => isRecord2(v) && !Array.isArray(v);
-    const scoped = this.config.parentScopedPath !== void 0;
-    let parentId;
-    let data;
-    let cinOpts;
-    if (scoped) {
-      const dataIsOptsBag = isObject(dataOrOpts) && ("dedupFields" in dataOrOpts || "dryRun" in dataOrOpts);
-      if (!isIdentifierCandidate(dataOrParentId) || !isObject(dataOrOpts) || dataIsOptsBag) {
-        throw new AutotaskConfigError(
-          `createIfNotExists for parent-scoped resource ${this.config.key} requires (parentId, data[, opts]) \u2014 the global collection has no create; a missing parentId would be a wrong-path request`
-        );
-      }
-      parentId = parseIdentifier(dataOrParentId, "parentId");
-      data = dataOrOpts;
-      cinOpts = opts;
-    } else {
-      if (!isObject(dataOrParentId)) {
-        throw new AutotaskConfigError(
-          `createIfNotExists for top-level resource ${this.config.key} takes (data[, opts]) \u2014 got a non-record first argument`
-        );
-      }
-      data = dataOrParentId;
-      cinOpts = isObject(dataOrOpts) ? dataOrOpts : {};
-    }
-    const record = isRecord2(data) ? data : {};
-    const dedupFields = (cinOpts.dedupFields ?? []).filter((field) => field in record);
-    let existing;
-    let existingId;
-    if (dedupFields.length > 0) {
-      const conditions = dedupFields.map((field) => ({
-        field,
-        op: "eq",
-        value: record[field]
-      }));
-      if (parentId !== void 0 && this.config.parentField !== void 0) {
-        conditions.unshift({ field: this.config.parentField, op: "eq", value: parentId });
-      }
-      const matches = await this.queryEntity(`${this.resourcePath}/query`, conditions, { maxRecords: 10 });
-      const first = matches[0];
-      if (first !== void 0) {
-        const firstId = first.id;
-        if (isIdentifierCandidate(firstId)) {
-          existing = first;
-          existingId = parseIdentifier(firstId, "id");
-        }
-      }
-    }
-    if (cinOpts.dryRun === true) {
-      const checks = [
-        { name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 }
-      ];
-      if (dedupFields.length > 0) {
-        checks.push({ name: "duplicate-detection", ok: existingId === void 0 });
+  /**
+   * Issue #13: the ONE bounded marker read on the resource's own query
+   * surface (`POST <collection>/query`, MaxRecords 5 — a read: idempotent,
+   * zero mutating wire; the fallback never issues anything else). Outcomes:
+   * exactly ONE numeric match → the normal success result stamped
+   * `idFrom: 'marker-recovery'` + the `shapeDrift` note; zero matches, more
+   * than one, or a cap-tripped search (a full 5 + a next cursor) → the
+   * existing `INVALID_RESPONSE` with the drift detail + the failed search
+   * (candidate ids listed — never a guessed id).
+   * @internal
+   */
+  async recoverCreatedIdByMarker(err, body, wireBody, opts, pin) {
+    const operation = `${this.config.key}.create`;
+    const markerField = typeof opts.markerField === "string" && opts.markerField.trim() !== "" ? opts.markerField.trim() : pin.markerField;
+    const markerToken = typeof opts.markerToken === "string" && opts.markerToken.trim() !== "" ? opts.markerToken.trim() : defaultMarkerToken(wireBody);
+    if (markerToken === null) throw err;
+    const observedShape = describeResponseShape(body);
+    const res = await this.http.request({
+      method: "POST",
+      idempotent: true,
+      path: `${this.resourcePath}/query`,
+      body: { MaxRecords: MARKER_RECOVERY_LIMIT, filter: [{ field: markerField, op: "contains", value: markerToken }] },
+      operation: `${operation}.marker-recovery`
+    });
+    const { items, pageDetails } = unwrapItems(res, operation);
+    const truncated = items.length >= MARKER_RECOVERY_LIMIT && pageDetails.nextPageUrl != null;
+    const drift = {
+      observedShape,
+      speccedEnvelope: "OperationResultModel",
+      markerField,
+      markerToken,
+      matches: items.length,
+      truncated,
+      note: pin.note
+    };
+    const numericIds = items.map((row) => {
+      const id = row.id;
+      if (typeof id === "number" && Number.isInteger(id) && id >= 0) return id;
+      if (typeof id === "string" && /^\d+$/.test(id.trim())) {
+        const parsed = Number.parseInt(id.trim(), 10);
+        return Number.isSafeInteger(parsed) ? parsed : id.trim();
       }
-      const warnings = existingId !== void 0 ? [`duplicate match on ${dedupFields.join(", ")} (id ${existingId}); the create would be skipped`] : [];
-      return buildDryRunResult({
-        operation: `${this.config.key}.createIfNotExists`,
-        method: "POST",
-        path: parentId !== void 0 ? this.scopedCollectionPath(parentId) : this.resourcePath,
-        ids: existingId !== void 0 ? [existingId] : [],
-        checks,
-        warnings,
-        impact: { affected: 1, scope: "single-record", reversible: true },
-        data
-      }, { redactPersonalData: this.http.redactPersonalData });
-    }
-    if (existing !== void 0 && existingId !== void 0) {
-      return { id: existingId, created: false, existing };
+      return null;
+    });
+    if (items.length === 1 && !truncated && numericIds[0] !== null) {
+      const id = numericIds[0];
+      const shapeDrift = {
+        observedShape,
+        speccedEnvelope: "OperationResultModel",
+        note: `The create answered 2xx with a body that is not the specced OperationResultModel (observed: ${observedShape}); the id was recovered by ONE bounded marker read (${markerField} contains the caller's marker, limit ${MARKER_RECOVERY_LIMIT}) \u2014 exactly one numeric match.`
+      };
+      return { id, idFrom: "marker-recovery", shapeDrift };
     }
-    const op = parentId !== void 0 ? await this.createScopedRaw(parentId, data) : await this.createGlobal(data);
-    return { id: op.id, created: true };
+    const candidateIds = numericIds.map((n, i) => n ?? String(items[i].id ?? "unknown"));
+    const outcome = items.length === 0 ? "found 0 matches" : truncated ? `found ${items.length} matches at the limit ${MARKER_RECOVERY_LIMIT} cap (truncated \u2014 more may exist)` : `found ${items.length} matches`;
+    err.details = { ...err.details, responseDrift: { ...drift, candidateIds } };
+    err.suggestedAction = `The create answered 2xx with a body that is not the specced OperationResultModel (observed shape: ${observedShape}); the bounded marker recovery (${markerField} contains the caller's marker, limit ${MARKER_RECOVERY_LIMIT}) ${outcome} \u2014 ` + (items.length === 0 ? "the record may exist with an unfindable marker; report the vendor response-shape drift and locate the record in the UI." : "refusing to guess an id \u2014 disambiguate with an exact-field query (or the UI) and recover the id before retrying.");
+    throw err;
   }
-  // ------------------------------------------------------------------
-  // Dry-run scaffolding + stale-object guard (mutation safety, section 19.3)
-  // ------------------------------------------------------------------
+  /** `PUT /V1.0/<E>/{id}` (the vendor tolerates PATCH at the same path) → `{ id }`.
+   *  For collection-only-writable resources (`collectionUpdate`, D1) the
+   *  vendor spec defines no put/patch on the item path (it is GET-only; the
+   *  item-path PUT 405s), so the confirmed update hits the COLLECTION
+   *  `PUT /V1.0/<E>` with the record id merged into the mutation body — the
+   *  vendor keys the record by the id in the body (the same convention the
+   *  parent-scoped `updateScopedRaw` PATCH uses).
+   *
+   *  V2 partial-update merge: the vendor's collection PUT validates the FULL
+   *  model (a partial body 500s 'Missing Required Field'), so a
+   *  collectionUpdate update MERGES the caller's partial body into the
+   *  record's current full model before the PUT: ONE fresh GET serves both
+   *  the merge source and the stale-object guard's read (a `lastModifiedDate`
+   *  mismatch throws STALE_OBJECT before the PUT; the guard semantics are
+   *  unchanged — it is a no-op where the model lacks the field or the caller
+   *  supplied no token). `opts.raw === true` sends the caller body as-is
+   *  instead (the pre-merge wire; the guard keeps its own verification read
+   *  when a token is supplied).
+   *
+   *  Issue #34: with `update.putFallback: true` (OFF by default), a TYPED
+   *  404 on the pinned route retries ONCE as `PUT /{Entity}/{id}` where the
+   *  gate holds — never a collectionUpdate route (the spec defines no
+   *  item-path update there), never a `raw: true` update, never a non-404
+   *  fault; the retry body runs the same fresh-read merge (see
+   *  `putFallbackMergedBody`), so the fallback is never a null-clearing
+   *  partial. A declined gate (a collectionUpdate route 404s, or the retry
+   *  itself 404s) throws the self-explaining typed error (the route tried,
+   *  the status, the opt-in; `details.putFallback`). */
   /**
-   * Stale-object guard (section 19.3): compare the plan's `staleCheck` field
-   * (vendor `lastModifiedDate`) against the caller-observed value. Mismatch
-   * throws `STALE_OBJECT`. Returns true when a comparison was actually made
-   * (the resource model carries the field AND the vendor answered it AND the
-   * caller supplied an expected value); false when the check is unavailable.
-   */
-  staleObjectCheck(current, opts, operation) {
-    const field = this.config.staleField;
-    const expected = opts.lastModifiedDate;
-    if (field === void 0 || expected === void 0) return false;
-    const actual = current[field];
-    if (typeof actual !== "string") return false;
-    if (actual !== expected) {
-      throw new StaleObjectError(
-        `stale object: ${this.config.key} ${field} changed since the caller read it (expected ${expected}, current ${actual})`,
-        {
-          code: "STALE_OBJECT",
-          operation,
-          suggestedAction: "Re-read the record and retry with the fresh lastModifiedDate."
-        }
-      );
-    }
-    return true;
+   * Issue #34 gate: the fallback may fire only while `update.putFallback`
+   * is ON and the pinned update route answered a TYPED 404 (a transport
+   * `NotFoundError` with `httpStatus: 404`) — never a 400/405/422/5xx, and
+   * never a 2xx shape fault (those keep today's typed error byte-identical).
+   * @internal
+   */
+  putFallbackEligible(err) {
+    return this.http.update.putFallback === true && err instanceof NotFoundError && err.httpStatus === 404;
   }
   /**
-   * Stale-object guard for a REAL mutation: the caller supplied an expected
-   * `lastModifiedDate` and the model carries the field → fetch the current
-   * record and compare before the mutating request (mismatch throws
-   * STALE_OBJECT; a vanished record propagates the vendor's NotFoundError).
+   * Issue #34: the fallback retry body — the caller's (normalised) fields
+   * merged onto a FRESH unredacted read of the current record (the same
+   * merge the collection-update path performs; the read is the live record,
+   * never cached). A target miss on the merge read surfaces with the pinned
+   * update-target reason (the issue-#14 convention) — the recovery has
+   * nothing to merge onto, and no retry is issued.
+   * @internal
    */
-  async guardStaleBeforeMutation(id, opts, operation, parentId) {
-    if (opts.lastModifiedDate === void 0 || this.config.staleField === void 0) return;
+  async putFallbackMergedBody(read, callerBody, id) {
     let current;
     try {
-      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
+      current = await read();
     } catch (err) {
       if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
       throw err;
     }
-    this.staleObjectCheck(current, opts, operation);
+    const merged = mergePartialBody(current, callerBody);
+    merged.id = id;
+    return merged;
   }
   /**
-   * `create` dry-run: input validation + parent verification (scoped
-   * resources) + the pinned envelope. NO request is issued (scoped parent
-   * verification is a read). Duplicate detection has no reliable lookup for
-   * a plain create (that is `createIfNotExists`), so it is not claimed.
+   * Issue #34: the self-explaining typed error a DECLINED gate throws. The
+   * original transport error keeps its identity (class / code / httpStatus);
+   * the message names the route tried, the status and the opt-in, and the
+   * structured detail rides under `details.putFallback`
+   * (`{ route, status, retried, optIn }`).
+   * @internal
    */
-  async runCreateDryRun(data, parentId) {
-    const checks = [];
-    const warnings = [];
-    checks.push({ name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 });
-    const deleteBoundaryNote = DELETE_BOUNDARY_NOTES[this.config.key];
-    if (deleteBoundaryNote !== void 0) {
-      checks.push({ name: "delete-boundary", ok: true });
-      warnings.push(deleteBoundaryNote);
-    }
-    let path = this.resourcePath;
-    if (parentId !== void 0) {
-      path = this.scopedCollectionPath(parentId);
-      const parentPath = this.config.parentPath;
-      if (parentPath === void 0) {
-        throw new AutotaskConfigError(
-          `dry-run: ${this.config.key} is parent-scoped but has no parentPath configured`
-        );
-      }
-      let parent = null;
-      if (isIdentifierCandidate(parentId)) {
+  putFallbackDeclined(err, route, retried) {
+    err.message = `${route} answered 404 on the pinned update route; ` + (retried ? `the update.putFallback retry ${route} also answered 404 \u2014 the zone drops the item route as well, so no further recovery is possible` : `the opt-in update.putFallback declines to retry this route (collectionUpdate resources have no spec-defined item-path update; raw updates send exactly what they were told) \u2014 no fallback was issued`);
+    err.details = { ...err.details ?? {}, putFallback: { route, status: 404, retried, optIn: "update.putFallback" } };
+    err.suggestedAction = retried ? "The zone answers 404 for both the pinned update route and the item route \u2014 verify the zone route registration for this entity before retrying." : "The zone drops the pinned update route and the spec defines no item-path update for this resource \u2014 verify the zone route registration, or issue the update against the collection route raw.";
+    return err;
+  }
+  async updateGlobal(id, data, opts = {}) {
+    const numeric = parseIdentifier(id, "id");
+    const operation = `${this.config.key}.update`;
+    let body = this.normalizeMutationBody(data);
+    const collectionUpdate = this.config.collectionUpdate === true;
+    if (collectionUpdate) {
+      if (opts.raw !== true) {
+        let current;
         try {
-          parent = await this.fetchRecordRaw(
-            parentPath,
-            parseIdentifier(parentId, "parentId"),
-            true
-          );
+          current = await this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries });
         } catch (err) {
-          if (!(err instanceof NotFoundError)) throw err;
+          if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
+          throw err;
         }
+        this.staleObjectCheck(current, opts, operation);
+        body = mergePartialBody(current, body);
+      } else {
+        await this.guardStaleBeforeMutation(numeric, opts, operation);
       }
-      checks.push({ name: "parent-exists", ok: parent !== null });
-      if (parent === null) {
-        warnings.push(`parent ${parentId} not found; the vendor would reject the create`);
-      }
-    }
-    if (isRecord2(data)) {
-      const eff = effectiveRequiredFields(void 0, RELATIONSHIP_MAP[this.config.key]?.zoneFacts ?? null);
-      const missing = eff.fields.filter((f) => f !== this.config.parentField && data[f] === void 0);
-      if (missing.length > 0) {
-        warnings.push(`required field(s) not in the data: ${missing.join(", ")} (${eff.from}); the vendor would likely reject the create`);
-      }
-    }
-    if (this.config.key === "companies") {
-      warnings.push('the vendor auto-creates a "Primary Address" location for a new company (rename it with company_locations.update; it cannot be deleted via the API)');
-    }
-    return buildDryRunResult({
-      operation: `${this.config.key}.create`,
-      method: "POST",
-      path,
-      ids: [],
-      checks,
-      impact: { affected: 1, scope: "single-record", reversible: true },
-      warnings,
-      data
-    }, { redactPersonalData: this.http.redactPersonalData });
-  }
-  /**
-   * `update` dry-run: input validation + current-record fetch (a missing
-   * record carries `warnings` and no `diff` — pinned), the stale-object
-   * check (mismatch throws STALE_OBJECT) and the best-effort `diff`. NO
-   * mutating request is issued.
-   */
-  async runUpdateDryRun(id, data, opts = {}, parentId) {
-    const operation = `${this.config.key}.update`;
-    const checks = [];
-    const warnings = [];
-    checks.push({ name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 });
-    const scopedUpdate = parentId !== void 0 && this.config.parentScopedPath !== void 0;
-    const collectionUpdate = scopedUpdate || this.config.collectionUpdate === true;
-    const path = scopedUpdate ? this.scopedCollectionPath(parentId) : collectionUpdate ? this.resourcePath : `${this.resourcePath}/${id}`;
-    const method = scopedUpdate ? "PATCH" : "PUT";
-    let current = null;
-    try {
-      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        const updateReason = EMPTY_REASON_STAMPS[this.config.key]?.update;
-        checks.push({
-          name: "current-record-exists",
-          ok: false,
-          ...updateReason !== void 0 ? { note: updateReason.note } : {}
-        });
-        warnings.push(`current record ${id} not fetchable; no diff`);
-        return buildDryRunResult({
-          operation,
-          method,
-          path,
-          ids: [id],
-          checks,
-          impact: { affected: 1, scope: "single-record", reversible: true },
-          warnings,
-          data,
-          ...updateReason !== void 0 ? { emptyReason: updateReason } : {}
-        }, { redactPersonalData: this.http.redactPersonalData });
-      }
-      throw err;
-    }
-    checks.push({ name: "current-record-exists", ok: true });
-    if (this.staleObjectCheck(current, opts, operation)) {
-      checks.push({ name: "stale-check", ok: true });
-    }
-    let envelopeData = data;
-    if (parentId === void 0 && this.config.collectionUpdate === true && opts.raw !== true) {
-      envelopeData = mergePartialBody(
-        current,
-        this.normalizeMutationBody(data)
-      );
-    }
-    return buildDryRunResult({
-      operation,
-      method,
-      path,
-      ids: [id],
-      checks,
-      diff: computeFieldDiff(current, data),
-      impact: { affected: 1, scope: "single-record", reversible: true },
-      warnings,
-      data: envelopeData
-    }, { redactPersonalData: this.http.redactPersonalData });
-  }
-  /**
-   * `delete` dry-run: current-record verification + the stale-object check +
-   * the pinned envelope (no diff — a delete has no before/after fields). NO
-   * mutating request is issued.
-   */
-  async runDeleteDryRun(id, opts = {}, parentId) {
-    const operation = `${this.config.key}.delete`;
-    const checks = [];
-    const warnings = [];
-    const path = parentId === void 0 ? `${this.resourcePath}/${id}` : this.scopedItemPath(parentId, id);
-    let current = null;
-    try {
-      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        checks.push({ name: "current-record-exists", ok: false });
-        warnings.push(`record ${id} not fetchable; the vendor would reject the delete`);
-        return buildDryRunResult({
-          operation,
-          method: "DELETE",
-          path,
-          ids: [id],
-          checks,
-          impact: { affected: 1, scope: "single-record", reversible: false },
-          warnings
-        }, { redactPersonalData: this.http.redactPersonalData });
-      }
-      throw err;
-    }
-    checks.push({ name: "current-record-exists", ok: true });
-    if (this.staleObjectCheck(current, opts, operation)) {
-      checks.push({ name: "stale-check", ok: true });
-    }
-    return buildDryRunResult({
-      operation,
-      method: "DELETE",
-      path,
-      ids: [id],
-      checks,
-      impact: { affected: 1, scope: "single-record", reversible: false },
-      warnings
-    }, { redactPersonalData: this.http.redactPersonalData });
-  }
-};
-
-// src/resources/base/BaseResource.ts
-var BaseResource = class extends MutationBase {
-};
-
-// src/operations/compositeNames.ts
-var PICKLIST_VALUE_NOT_SERVED_NOTE = "The picklist is served to this API user, but this record's value is not in it (an inactive or unexposed value) \u2014 the label cannot be resolved and is null; refreshing the field catalog will not surface it. (A picklist the vendor does not expose at all is reported with the field-catalog honesty note instead.)";
-var PICKLIST_CATALOG_UNAVAILABLE_NOTE = "The field-catalog read that serves picklist labels failed for this call, so this label is unavailable (null), not absent: the value may well have one. Retry the call once the catalog read succeeds (see names.catalogError).";
-var DEFAULT_MAX_NAME_READS = 20;
-var TICKET_LABEL_FIELDS = ["status", "priority", "ticketType", "issueType", "subIssueType", "source", "queueID"];
-function isVendorId(value) {
-  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0;
-  if (typeof value === "string") return /^\d+$/.test(value);
-  return false;
-}
-var zeroIsRecord = (table) => table === "company";
-function createNamePlan(labelFields = [], labelResource) {
-  const resourceIds = [];
-  const resSeen = /* @__PURE__ */ new Set();
-  const recordFks = [];
-  const fkSeen = /* @__PURE__ */ new Set();
-  let lineOfBusinessId;
-  let lineOfBusinessSource;
-  let lineOfBusinessContractId;
-  return {
-    plan: () => ({
-      resourceIds,
-      recordFks,
-      labelFields,
-      ...labelResource !== void 0 ? { labelResource } : {},
-      ...lineOfBusinessId !== void 0 ? { lineOfBusinessId } : {},
-      ...lineOfBusinessSource !== void 0 ? { lineOfBusinessSource } : {},
-      ...lineOfBusinessContractId !== void 0 ? { lineOfBusinessContractId } : {}
-    }),
-    addResource: (value) => {
-      if (!isVendorId(value) || Number(value) === 0) return;
-      const k = String(value);
-      if (!resSeen.has(k)) {
-        resSeen.add(k);
-        resourceIds.push(value);
-      }
-    },
-    addFk: (table, value) => {
-      if (!isVendorId(value) || Number(value) === 0 && !zeroIsRecord(table)) return;
-      const k = `${table}:${String(value)}`;
-      if (!fkSeen.has(k)) {
-        fkSeen.add(k);
-        recordFks.push({ table, id: value });
+      body.id = numeric;
+    }
+    const route = collectionUpdate ? `PUT ${this.resourcePath}` : `PUT ${this.resourcePath}/${numeric}`;
+    let res;
+    try {
+      res = await this.http.request({
+        method: "PUT",
+        path: collectionUpdate ? this.resourcePath : `${this.resourcePath}/${numeric}`,
+        body,
+        operation,
+        maxRetries: opts.maxRetries
+      });
+    } catch (err) {
+      if (!this.putFallbackEligible(err)) throw err;
+      if (collectionUpdate) {
+        throw this.putFallbackDeclined(err, route, false);
       }
-    },
-    addLineOfBusinessFromContract: (value) => {
-      if (!isVendorId(value)) return;
-      lineOfBusinessContractId = value;
-    },
-    addLineOfBusiness: (value, origin) => {
-      if (!isVendorId(value)) return;
-      lineOfBusinessId = value;
-      if (origin !== void 0) {
-        lineOfBusinessSource = origin.source;
-        if (origin.contractId !== void 0) lineOfBusinessContractId = origin.contractId;
+      const merged = await this.putFallbackMergedBody(
+        () => this.getGlobalUnredacted(numeric, { maxRetries: opts.maxRetries }),
+        body,
+        numeric
+      );
+      let retry;
+      try {
+        retry = await this.http.request({
+          method: "PUT",
+          path: `${this.resourcePath}/${numeric}`,
+          body: merged,
+          operation,
+          maxRetries: opts.maxRetries
+        });
+      } catch (rerr) {
+        if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, route, true);
+        throw rerr;
       }
+      return unwrapOperation(retry, operation);
     }
-  };
-}
-function addNameSibling(row, field, resolve) {
-  const value = row[field];
-  if (value === void 0) return;
-  row[`${field}Name`] = isVendorId(value) ? resolve(value) : null;
-}
-function addLabelSibling(row, field, names) {
-  const value = row[field];
-  if (value === void 0) return;
-  row[`${field}Label`] = names.labelFor(field, value);
-}
-var FK_TABLE_PATH = {
-  role: "/V1.0/Roles",
-  billingCode: "/V1.0/BillingCodes",
-  contract: "/V1.0/Contracts",
-  company: "/V1.0/Companies",
-  ticket: "/V1.0/Tickets"
-};
-var FK_NAME_FIELD = {
-  role: "name",
-  billingCode: "name",
-  contract: "contractName",
-  company: "companyName",
-  ticket: "ticketNumber"
-};
-function fkName(record, table) {
-  if (table === "ticket") {
-    const parts = [record["ticketNumber"], record["title"]].filter((v) => typeof v === "string" && v.trim() !== "").map((v) => v.trim());
-    return parts.length > 0 ? parts.join(" ") : null;
-  }
-  const value = record[FK_NAME_FIELD[table]];
-  return typeof value === "string" && value.trim() !== "" ? value : null;
-}
-function faultRow(err) {
-  const e = err;
-  return e.httpStatus !== void 0 ? { code: e.code, message: e.message, httpStatus: e.httpStatus } : { code: e.code, message: e.message };
-}
-function vendorId(value) {
-  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 1 ? value : void 0;
-  if (typeof value === "string" && /^[0-9]+$/.test(value.trim())) {
-    const n = Number(value.trim());
-    return Number.isSafeInteger(n) && n >= 1 ? n : void 0;
+    return unwrapOperation(res, operation);
   }
-  return void 0;
-}
-async function resolveLineOfBusinessChain(http, associationId, options) {
-  const operation = options.operation ?? "compositeNames";
-  const degrade = options.onError === "degrade";
-  const get = (path) => {
-    const res = http.request({ method: "GET", path, operation }).then((body) => {
-      const b = body;
-      if (b === null || !("item" in b) || b.item === null || b.item === void 0) return null;
-      return b.item;
-    });
-    if (!degrade) {
-      return res.catch((e) => {
-        if (e instanceof NotFoundError) return null;
-        throw e;
-      });
-    }
-    return res.catch((e) => {
-      if (e instanceof NotFoundError || isAutotaskError(e) && e.code !== "ABORTED") return null;
-      throw e;
+  /** `DELETE /V1.0/<E>/{id}` → `{ id }` (OperationResultModel). A blank 2xx
+   *  (204 / empty body) is a valid vendor delete answer — synthesize the
+   *  result from the path id (issue #25: the transport returns undefined
+   *  for it; a non-blank wrong shape still throws via unwrapOperation). */
+  async deleteGlobal(id, opts = {}) {
+    const numeric = parseIdentifier(id, "id");
+    const res = await this.http.request({
+      method: "DELETE",
+      path: `${this.resourcePath}/${numeric}`,
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
     });
-  };
-  let remaining = options.budget;
-  if (remaining < 1) {
-    return {
-      lineOfBusiness: { association: null, organizationalLevel2: null, organizationalLevel1: null, markers: { association: "capped", organizationalLevel2: "capped", organizationalLevel1: "capped" } },
-      used: 0,
-      truncated: true
-    };
-  }
-  remaining -= 1;
-  const association = await get(`/V1.0/OrganizationalLevelAssociations/${associationId}`);
-  const associationMarker = association === null ? "unresolved" : "ok";
-  if (association === null) {
-    return {
-      lineOfBusiness: { association: null, organizationalLevel2: null, organizationalLevel1: null, markers: { association: associationMarker, organizationalLevel2: "missing", organizationalLevel1: "missing" } },
-      used: 1,
-      truncated: false
-    };
-  }
-  const l2Id = vendorId(association.organizationalLevel2ID);
-  const l1Id = vendorId(association.organizationalLevel1ID);
-  let l2Marker = l2Id !== void 0 ? "unresolved" : "missing";
-  let l1Marker = l1Id !== void 0 ? "unresolved" : "missing";
-  const need = (l2Id !== void 0 ? 1 : 0) + (l1Id !== void 0 ? 1 : 0);
-  let l2 = null;
-  let l1 = null;
-  let used = 1;
-  let truncated = false;
-  if (need > 0 && remaining < need) {
-    truncated = true;
-    if (l2Id !== void 0) l2Marker = "capped";
-    if (l1Id !== void 0) l1Marker = "capped";
-  } else {
-    used += need;
-    const [r2, r1] = await Promise.all([
-      l2Id !== void 0 ? get(`/V1.0/OrganizationalLevel2s/${l2Id}`) : Promise.resolve(null),
-      l1Id !== void 0 ? get(`/V1.0/OrganizationalLevel1s/${l1Id}`) : Promise.resolve(null)
-    ]);
-    l2 = r2;
-    l1 = r1;
-    if (l2Id !== void 0) l2Marker = l2 === null ? "unresolved" : "ok";
-    if (l1Id !== void 0) l1Marker = l1 === null ? "unresolved" : "ok";
-  }
-  return {
-    lineOfBusiness: { association, organizationalLevel2: l2, organizationalLevel1: l1, markers: { association: associationMarker, organizationalLevel2: l2Marker, organizationalLevel1: l1Marker } },
-    used,
-    truncated
-  };
-}
-async function resolveCompositeNames(http, plan, opts = {}) {
-  if (opts.maxNameReads !== void 0 && (!Number.isInteger(opts.maxNameReads) || opts.maxNameReads < 1)) {
-    throw new AutotaskConfigError(`composite names: maxNameReads must be an integer >= 1 (got ${String(opts.maxNameReads)})`);
-  }
-  const budget = Math.min(DEFAULT_MAX_NAME_READS, opts.maxNameReads ?? DEFAULT_MAX_NAME_READS);
-  const client = http.client;
-  if (client === void 0) {
-    throw new AutotaskConfigError("composite names: the transport is not wired to an AutotaskClient (the composite must run through the client)");
-  }
-  const readCache = http.readCache;
-  const section = { truncated: false, rows: {}, reasons: {} };
-  let remaining = budget;
-  let contractLobPointer;
-  let contractLobUnread;
-  const coldResource = [];
-  for (const id of plan.resourceIds) {
-    const path = `/V1.0/Resources/${id}`;
-    if (readCache !== void 0 && (readCache.peek(path).hit || readCache.peek(contextAbsentKey(path)).hit)) continue;
-    coldResource.push(id);
+    return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
   }
-  const withinBudget = coldResource.slice(0, remaining);
-  const overBudgetResource = coldResource.slice(remaining);
-  remaining -= withinBudget.length;
-  for (const id of overBudgetResource) {
-    section.rows[`resource:${id}`] = { name: null, blind: false, capped: true };
-    section.truncated = true;
+  /** Parent-scoped create: `POST .../{parentId}/<Child>` (issue #13: a drifted 2xx runs the bounded marker recovery where the plan pins a marker field). */
+  async createScopedRaw(parentId, data, opts = {}) {
+    const body = this.normalizeMutationBody(data);
+    const res = await this.http.request({
+      method: "POST",
+      path: this.scopedCollectionPath(parentId),
+      body,
+      operation: `${this.config.key}.create`,
+      maxRetries: opts.maxRetries
+    });
+    return this.unwrapCreateOperation(res, body, opts);
   }
-  const overSet = new Set(overBudgetResource.map((id) => String(id)));
-  const opIds = plan.resourceIds.filter((id) => !overSet.has(String(id)));
-  if (opIds.length > 0) {
-    let pass = opIds;
-    if (pass.length > 500) {
-      for (const id of pass.slice(500)) {
-        section.rows[`resource:${id}`] = { name: null, blind: false, capped: true };
-        section.truncated = true;
+  /** Parent-scoped update: `PATCH .../{parentId}/<Child>` — the COLLECTION.
+   *  Swagger documents put+patch on the scoped collection and has NO put/patch on
+   *  the item path anywhere in the spec; the node strips the id from the path and
+   *  PATCHes the collection, and the vendor keys the record by the id in the body. */
+  async updateScopedRaw(parentId, id, data, opts = {}) {
+    const numeric = parseIdentifier(id, "id");
+    const body = this.normalizeMutationBody(data);
+    body.id = numeric;
+    const path = this.scopedCollectionPath(parentId);
+    const operation = `${this.config.key}.update`;
+    let res;
+    try {
+      res = await this.http.request({
+        method: "PATCH",
+        path,
+        body,
+        operation,
+        maxRetries: opts.maxRetries
+      });
+    } catch (err) {
+      if (!this.putFallbackEligible(err)) throw err;
+      const merged = await this.putFallbackMergedBody(
+        () => this.getScopedUnredacted(parentId, numeric, { maxRetries: opts.maxRetries }),
+        body,
+        numeric
+      );
+      let retry;
+      try {
+        retry = await this.http.request({
+          method: "PUT",
+          path: `${path}/${numeric}`,
+          body: merged,
+          operation,
+          maxRetries: opts.maxRetries
+        });
+      } catch (rerr) {
+        if (this.putFallbackEligible(rerr)) throw this.putFallbackDeclined(rerr, `PUT ${path}/${numeric}`, true);
+        throw rerr;
       }
-      pass = pass.slice(0, 500);
+      return unwrapOperation(retry, operation);
     }
-    const res = await expandResourceNames(client, pass);
-    for (const r of res.results) {
-      const row = { name: r.name, blind: r.blind, capped: false };
-      if (r.error !== void 0) row.error = faultRow(r.error);
-      section.rows[`resource:${r.id}`] = row;
+    return unwrapOperation(res, operation);
+  }
+  /** Parent-scoped delete: `DELETE .../{parentId}/<Child>/{id}` → `{ id }`
+   *  (a blank 2xx synthesizes `{ id }` from the path id — issue #25). */
+  async deleteScopedRaw(parentId, id, opts = {}) {
+    const numeric = parseIdentifier(id, "id");
+    const res = await this.http.request({
+      method: "DELETE",
+      path: this.scopedItemPath(parentId, id),
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
+    });
+    return res === void 0 ? { id: numeric } : unwrapOperation(res, `${this.config.key}.delete`);
+  }
+  /**
+   * Attachment delete: the vendor returns the deleted attachment MODEL, not
+   * OperationResultModel (G1 envelope.md) — pass it through typed.
+   */
+  async deleteScopedModel(parentId, id, opts = {}) {
+    const numeric = parseIdentifier(id, "id");
+    const res = await this.http.request({
+      method: "DELETE",
+      path: this.scopedItemPath(parentId, id),
+      operation: `${this.config.key}.delete`,
+      maxRetries: opts.maxRetries
+    });
+    if (res === void 0) return {};
+    if (!isRecord2(res)) {
+      throw new AutotaskError(
+        `Expected the deleted attachment model for ID ${numeric}; got a different shape`,
+        { code: "INVALID_RESPONSE", category: "server", resourceIds: [numeric], details: { idRefs: [{ entity: this.entityName, id: numeric }] } }
+      );
     }
+    return res;
   }
-  const holders = {
-    role: client.roles,
-    billingCode: client.billingCodes,
-    contract: client.contracts,
-    company: client.companies,
-    ticket: client.tickets
-  };
-  for (const fk of plan.recordFks) {
-    const key = `${fk.table}:${fk.id}`;
-    const cold = readCache === void 0 || readCache.get(`${FK_TABLE_PATH[fk.table]}/${fk.id}`) === void 0;
-    if (cold) {
-      if (remaining < 1) {
-        section.rows[key] = { name: null, blind: false, capped: true };
-        section.truncated = true;
-        if (fk.table === "contract" && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
-          contractLobUnread = "capped";
-        }
-        continue;
+  async createIfNotExists(dataOrParentId, dataOrOpts, opts = {}) {
+    const isObject = (v) => isRecord2(v) && !Array.isArray(v);
+    const scoped = this.config.parentScopedPath !== void 0;
+    let parentId;
+    let data;
+    let cinOpts;
+    if (scoped) {
+      const dataIsOptsBag = isObject(dataOrOpts) && ("dedupFields" in dataOrOpts || "dryRun" in dataOrOpts);
+      if (!isIdentifierCandidate(dataOrParentId) || !isObject(dataOrOpts) || dataIsOptsBag) {
+        throw new AutotaskConfigError(
+          `createIfNotExists for parent-scoped resource ${this.config.key} requires (parentId, data[, opts]) \u2014 the global collection has no create; a missing parentId would be a wrong-path request`
+        );
       }
-      remaining -= 1;
+      parentId = parseIdentifier(dataOrParentId, "parentId");
+      data = dataOrOpts;
+      cinOpts = opts;
+    } else {
+      if (!isObject(dataOrParentId)) {
+        throw new AutotaskConfigError(
+          `createIfNotExists for top-level resource ${this.config.key} takes (data[, opts]) \u2014 got a non-record first argument`
+        );
+      }
+      data = dataOrParentId;
+      cinOpts = isObject(dataOrOpts) ? dataOrOpts : {};
     }
-    try {
-      const record = await holders[fk.table].get(fk.id);
-      if (fk.table === "contract" && plan.lineOfBusinessId === void 0 && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
-        contractLobPointer = vendorId(record["organizationalLevelAssociationID"]);
+    const record = isRecord2(data) ? data : {};
+    const dedupFields = (cinOpts.dedupFields ?? []).filter((field) => field in record);
+    let existing;
+    let existingId;
+    if (dedupFields.length > 0) {
+      const conditions = dedupFields.map((field) => ({
+        field,
+        op: "eq",
+        value: record[field]
+      }));
+      if (parentId !== void 0 && this.config.parentField !== void 0) {
+        conditions.unshift({ field: this.config.parentField, op: "eq", value: parentId });
       }
-      section.rows[key] = { name: fkName(record, fk.table), blind: false, capped: false };
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        section.rows[key] = { name: null, blind: true, capped: false };
-      } else if (isAutotaskError(err) && err.code !== "ABORTED") {
-        section.rows[key] = { name: null, blind: false, capped: false, error: faultRow(err) };
-        if (fk.table === "contract" && plan.lineOfBusinessContractId !== void 0 && String(fk.id) === String(plan.lineOfBusinessContractId)) {
-          contractLobUnread = "unresolved";
+      const matches = await this.queryEntity(`${this.resourcePath}/query`, conditions, { maxRecords: 10 });
+      const first = matches[0];
+      if (first !== void 0) {
+        const firstId = first.id;
+        if (isIdentifierCandidate(firstId)) {
+          existing = first;
+          existingId = parseIdentifier(firstId, "id");
         }
-      } else {
-        throw err;
       }
     }
-  }
-  const picklists = {};
-  if (plan.labelFields.length > 0) {
-    let usable = true;
-    let failure;
-    try {
-      const labelResource = plan.labelResource ?? "tickets";
-      const catalog = await fieldCatalog(client, { resources: [labelResource], labels: true, fields: [...plan.labelFields] });
-      const row = catalog.rows.find((r) => r.resource === labelResource);
-      if (row === void 0 || row.error !== null || row.fields === void 0) {
-        usable = false;
-        failure = row?.error ?? { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${labelResource} row` };
-      } else {
-        for (const f of plan.labelFields) {
-          const frow = row.fields.find((x) => x.name === f);
-          picklists[f] = frow?.picklistValues;
-        }
+    if (cinOpts.dryRun === true) {
+      const checks = [
+        { name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 }
+      ];
+      if (dedupFields.length > 0) {
+        checks.push({ name: "duplicate-detection", ok: existingId === void 0 });
       }
-    } catch (err) {
-      if (isAutotaskError(err) && err.code !== "ABORTED") {
-        usable = false;
-        failure = { code: err.code, message: err.message };
-      } else throw err;
+      const warnings = existingId !== void 0 ? [`duplicate match on ${dedupFields.join(", ")} (id ${existingId}); the create would be skipped`] : [];
+      return buildDryRunResult({
+        operation: `${this.config.key}.createIfNotExists`,
+        method: "POST",
+        path: parentId !== void 0 ? this.scopedCollectionPath(parentId) : this.resourcePath,
+        ids: existingId !== void 0 ? [existingId] : [],
+        checks,
+        warnings,
+        impact: { affected: 1, scope: "single-record", reversible: true },
+        data
+      }, { redactPersonalData: this.http.redactPersonalData });
     }
-    if (!usable) {
-      section.catalogError = failure;
-      for (const f of plan.labelFields) section.reasons[f] = PICKLIST_CATALOG_UNAVAILABLE_NOTE;
+    if (existing !== void 0 && existingId !== void 0) {
+      return { id: existingId, created: false, existing };
     }
+    const op = parentId !== void 0 ? await this.createScopedRaw(parentId, data) : await this.createGlobal(data);
+    return { id: op.id, created: true };
   }
-  let lineOfBusiness2 = null;
-  const lobId = plan.lineOfBusinessId ?? contractLobPointer;
-  if (lobId !== void 0) {
-    const chain = await resolveLineOfBusinessChain(http, lobId, { budget: remaining, onError: "degrade" });
-    remaining -= chain.used;
-    if (chain.truncated) section.truncated = true;
-    const fromContract = plan.lineOfBusinessId === void 0;
-    lineOfBusiness2 = {
-      ...chain.lineOfBusiness,
-      ...fromContract ? { source: "contract", contractId: plan.lineOfBusinessContractId } : plan.lineOfBusinessSource !== void 0 ? { source: plan.lineOfBusinessSource } : {},
-      ...!fromContract && plan.lineOfBusinessContractId !== void 0 ? { contractId: plan.lineOfBusinessContractId } : {}
-    };
-  } else if (contractLobUnread !== void 0 && plan.lineOfBusinessContractId !== void 0) {
-    lineOfBusiness2 = {
-      source: "contract",
-      contractId: plan.lineOfBusinessContractId,
-      association: null,
-      organizationalLevel2: null,
-      organizationalLevel1: null,
-      markers: { association: contractLobUnread, organizationalLevel2: "missing", organizationalLevel1: "missing" }
-    };
+  // ------------------------------------------------------------------
+  // Dry-run scaffolding + stale-object guard (mutation safety, section 19.3)
+  // ------------------------------------------------------------------
+  /**
+   * Stale-object guard (section 19.3): compare the plan's `staleCheck` field
+   * (vendor `lastModifiedDate`) against the caller-observed value. Mismatch
+   * throws `STALE_OBJECT`. Returns true when a comparison was actually made
+   * (the resource model carries the field AND the vendor answered it AND the
+   * caller supplied an expected value); false when the check is unavailable.
+   */
+  staleObjectCheck(current, opts, operation) {
+    const field = this.config.staleField;
+    const expected = opts.lastModifiedDate;
+    if (field === void 0 || expected === void 0) return false;
+    const actual = current[field];
+    if (typeof actual !== "string") return false;
+    if (actual !== expected) {
+      throw new StaleObjectError(
+        `stale object: ${this.config.key} ${field} changed since the caller read it (expected ${expected}, current ${actual})`,
+        {
+          code: "STALE_OBJECT",
+          operation,
+          suggestedAction: "Re-read the record and retry with the fresh lastModifiedDate."
+        }
+      );
+    }
+    return true;
   }
-  return {
-    section,
-    lineOfBusiness: lineOfBusiness2,
-    resourceName: (id) => section.rows[`resource:${id}`]?.name ?? null,
-    recordName: (table, id) => section.rows[`${table}:${id}`]?.name ?? null,
-    labelFor: (field, value) => {
-      if (value === null || value === void 0) return null;
-      const values = picklists[field];
-      if (values === void 0) {
-        section.reasons[field] = section.catalogError !== void 0 ? PICKLIST_CATALOG_UNAVAILABLE_NOTE : FIELD_CATALOG_HONESTY_NOTE;
-        return null;
+  /**
+   * Stale-object guard for a REAL mutation: the caller supplied an expected
+   * `lastModifiedDate` and the model carries the field → fetch the current
+   * record and compare before the mutating request (mismatch throws
+   * STALE_OBJECT; a vanished record propagates the vendor's NotFoundError).
+   */
+  async guardStaleBeforeMutation(id, opts, operation, parentId) {
+    if (opts.lastModifiedDate === void 0 || this.config.staleField === void 0) return;
+    let current;
+    try {
+      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
+    } catch (err) {
+      if (err instanceof NotFoundError) attachUpdateTargetMissReason(err, this.config.key);
+      throw err;
+    }
+    this.staleObjectCheck(current, opts, operation);
+  }
+  /**
+   * `create` dry-run: input validation + parent verification (scoped
+   * resources) + the pinned envelope. NO request is issued (scoped parent
+   * verification is a read). Duplicate detection has no reliable lookup for
+   * a plain create (that is `createIfNotExists`), so it is not claimed.
+   */
+  async runCreateDryRun(data, parentId) {
+    const checks = [];
+    const warnings = [];
+    checks.push({ name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 });
+    const deleteBoundaryNote = DELETE_BOUNDARY_NOTES[this.config.key];
+    if (deleteBoundaryNote !== void 0) {
+      checks.push({ name: "delete-boundary", ok: true });
+      warnings.push(deleteBoundaryNote);
+    }
+    let path = this.resourcePath;
+    if (parentId !== void 0) {
+      path = this.scopedCollectionPath(parentId);
+      const parentPath = this.config.parentPath;
+      if (parentPath === void 0) {
+        throw new AutotaskConfigError(
+          `dry-run: ${this.config.key} is parent-scoped but has no parentPath configured`
+        );
+      }
+      let parent = null;
+      if (isIdentifierCandidate(parentId)) {
+        try {
+          parent = await this.fetchRecordRaw(
+            parentPath,
+            parseIdentifier(parentId, "parentId"),
+            true
+          );
+        } catch (err) {
+          if (!(err instanceof NotFoundError)) throw err;
+        }
       }
-      const hit = values.find((v) => String(v.value) === String(value));
-      if (hit === void 0) {
-        if (String(value) !== "0") section.reasons[field] = PICKLIST_VALUE_NOT_SERVED_NOTE;
-        return null;
+      checks.push({ name: "parent-exists", ok: parent !== null });
+      if (parent === null) {
+        warnings.push(`parent ${parentId} not found; the vendor would reject the create`);
       }
-      return typeof hit.label === "string" ? hit.label : null;
     }
-  };
-}
-var ROW_FK_TABLES = {
-  companyID: "company",
-  contractID: "contract",
-  ticketID: "ticket",
-  roleID: "role",
-  billingCodeID: "billingCode"
-};
-var isResourceFkField = (field) => field === "resourceID" || field.endsWith("ResourceID");
-var LABEL_NAME_MAX_CHARS = 200;
-function untrustedName(name) {
-  if (name === null) return null;
-  const [[capped]] = truncateNoteChars([{ v: name }], LABEL_NAME_MAX_CHARS, ["v"]);
-  return wrapUntrusted(capped.v) ?? capped.v;
-}
-var lastPicklists = /* @__PURE__ */ new WeakMap();
-function readNamesOpt(value, where) {
-  if (value === void 0) return true;
-  if (typeof value !== "boolean") {
-    throw new AutotaskConfigError(`${where}: names must be a boolean (got ${typeof value}) \u2014 true (default) adds label siblings, false returns raw ids only`);
-  }
-  return value;
-}
-async function labelRows(client, resourceKey, rows, resourceKeyedReasons = false) {
-  const keys = /* @__PURE__ */ new Set();
-  for (const row of rows) for (const k of Object.keys(row)) keys.add(k);
-  if (keys.size === 0) return { rows: [...rows] };
-  let picklistFields = [];
-  let unavailable = [];
-  let catalogError;
-  const modelFields = MODEL_FIELD_SETS[resourceKey] ?? [];
-  const candidates = [...keys].filter((f) => f !== "id" && modelFields.includes(f) && ROW_FK_TABLES[f] === void 0 && !isResourceFkField(f));
-  if (candidates.length > 0) try {
-    const catalog = await fieldCatalog(client, { resources: [resourceKey], labels: true });
-    const row = catalog.rows.find((r) => r.resource === resourceKey);
-    const known = lastPicklists.get(client) ?? /* @__PURE__ */ new Map();
-    lastPicklists.set(client, known);
-    if (row?.fields === void 0) {
-      const last = known.get(resourceKey);
-      unavailable = (last ?? []).filter((f) => candidates.includes(f));
-      if (last === void 0 || unavailable.length > 0) {
-        catalogError = row?.error ?? { code: "INVALID_RESPONSE", message: `fieldCatalog: no ${resourceKey} row` };
+    if (isRecord2(data)) {
+      const eff = effectiveRequiredFields(void 0, RELATIONSHIP_MAP[this.config.key]?.zoneFacts ?? null);
+      const missing = eff.fields.filter((f) => f !== this.config.parentField && data[f] === void 0);
+      if (missing.length > 0) {
+        warnings.push(`required field(s) not in the data: ${missing.join(", ")} (${eff.from}); the vendor would likely reject the create`);
       }
-    } else {
-      const all = row.fields.filter((f) => f.isPickList).map((f) => f.name);
-      known.set(resourceKey, all);
-      picklistFields = all.filter((f) => candidates.includes(f));
     }
-  } catch (err) {
-    if (!isAutotaskError(err) || err.code === "ABORTED") throw err;
-  }
-  const labelled = (field) => picklistFields.includes(field) || unavailable.includes(field) || ROW_FK_TABLES[field] !== void 0 || isResourceFkField(field);
-  if (catalogError === void 0 && ![...keys].some(labelled)) return { rows: [...rows] };
-  const builder = createNamePlan(picklistFields, resourceKey);
-  for (const row of rows) {
-    for (const [field, value] of Object.entries(row)) {
-      const table = ROW_FK_TABLES[field];
-      if ((value === 0 || value === "0") && !zeroIsRecord(table)) continue;
-      if (table !== void 0) builder.addFk(table, value);
-      else if (isResourceFkField(field)) builder.addResource(value);
+    if (this.config.key === "companies") {
+      warnings.push('the vendor auto-creates a "Primary Address" location for a new company (rename it with company_locations.update; it cannot be deleted via the API)');
     }
+    return buildDryRunResult({
+      operation: `${this.config.key}.create`,
+      method: "POST",
+      path,
+      ids: [],
+      checks,
+      impact: { affected: 1, scope: "single-record", reversible: true },
+      warnings,
+      data
+    }, { redactPersonalData: this.http.redactPersonalData });
   }
-  const plan = builder.plan();
-  const names = plan.resourceIds.length === 0 && plan.recordFks.length === 0 && picklistFields.length === 0 ? void 0 : await resolveCompositeNames(client.http, plan);
-  const secondReadFailed = names?.section.catalogError;
-  if (secondReadFailed !== void 0) {
-    catalogError ??= secondReadFailed;
-    unavailable = [.../* @__PURE__ */ new Set([...unavailable, ...picklistFields])];
-  }
-  const out = rows.map((row) => {
-    const r = { ...row };
-    for (const [field, value] of Object.entries(row)) {
-      const has2 = value !== null && value !== void 0 && names !== void 0;
-      if (picklistFields.includes(field)) r[`${field}Label`] = has2 ? names.labelFor(field, value) : null;
-      else if (unavailable.includes(field)) r[`${field}Label`] = null;
-      const table = ROW_FK_TABLES[field];
-      const set = has2 && (zeroIsRecord(table) || value !== 0 && value !== "0");
-      if (table !== void 0) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.recordName(table, value)) : null;
-      else if (isResourceFkField(field)) r[`${field}Name`] = set && isVendorId(value) ? untrustedName(names.resourceName(value)) : null;
+  /**
+   * `update` dry-run: input validation + current-record fetch (a missing
+   * record carries `warnings` and no `diff` — pinned), the stale-object
+   * check (mismatch throws STALE_OBJECT) and the best-effort `diff`. NO
+   * mutating request is issued.
+   */
+  async runUpdateDryRun(id, data, opts = {}, parentId) {
+    const operation = `${this.config.key}.update`;
+    const checks = [];
+    const warnings = [];
+    checks.push({ name: "input-validation", ok: isRecord2(data) && Object.keys(data).length > 0 });
+    const scopedUpdate = parentId !== void 0 && this.config.parentScopedPath !== void 0;
+    const collectionUpdate = scopedUpdate || this.config.collectionUpdate === true;
+    const path = scopedUpdate ? this.scopedCollectionPath(parentId) : collectionUpdate ? this.resourcePath : `${this.resourcePath}/${id}`;
+    const method = scopedUpdate ? "PATCH" : "PUT";
+    let current = null;
+    try {
+      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        const updateReason = EMPTY_REASON_STAMPS[this.config.key]?.update;
+        checks.push({
+          name: "current-record-exists",
+          ok: false,
+          ...updateReason !== void 0 ? { note: updateReason.note } : {}
+        });
+        warnings.push(`current record ${id} not fetchable; no diff`);
+        return buildDryRunResult({
+          operation,
+          method,
+          path,
+          ids: [id],
+          checks,
+          impact: { affected: 1, scope: "single-record", reversible: true },
+          warnings,
+          data,
+          ...updateReason !== void 0 ? { emptyReason: updateReason } : {}
+        }, { redactPersonalData: this.http.redactPersonalData });
+      }
+      throw err;
     }
-    if (r["assignedResourceIDName"] !== void 0) r["assignedResourceName"] = r["assignedResourceIDName"];
-    return r;
-  });
-  const capped = names === void 0 ? 0 : Object.values(names.section.rows).filter((row) => row.capped).length;
-  const unresolved = Object.keys(names?.section.reasons ?? {});
-  const reasons = { ...names?.section.reasons };
-  for (const f of unavailable) reasons[f] = PICKLIST_CATALOG_UNAVAILABLE_NOTE;
-  if (capped === 0 && unresolved.length === 0 && catalogError === void 0) return { rows: out };
-  const parts = [];
-  if (capped > 0) parts.push(`${capped} id(s) left unlabelled (their *Name is null): the per-call cap of ${DEFAULT_MAX_NAME_READS} uncached name reads was hit \u2014 names already read are cached, so repeating or narrowing the call labels more`);
-  if (unresolved.length > 0) parts.push(`picklist label(s) unavailable for ${unresolved.map((f) => resourceKeyedReasons ? `${resourceKey}.${f}` : f).join(", ")} (see reasons)`);
-  if (catalogError !== void 0) {
-    parts.push(
-      `the ${resourceKey} field catalog read failed (${catalogError.code}), so picklist labels are unavailable for this call, not absent: ` + (unavailable.length > 0 ? `the *Label is null for ${unavailable.join(", ")}` : "no *Label sibling was added (the picklist fields are unknown until a catalog read succeeds)") + " \u2014 retry the call to label them"
-    );
+    checks.push({ name: "current-record-exists", ok: true });
+    if (this.staleObjectCheck(current, opts, operation)) {
+      checks.push({ name: "stale-check", ok: true });
+    }
+    let envelopeData = data;
+    if (parentId === void 0 && this.config.collectionUpdate === true && opts.raw !== true) {
+      envelopeData = mergePartialBody(
+        current,
+        this.normalizeMutationBody(data)
+      );
+    }
+    return buildDryRunResult({
+      operation,
+      method,
+      path,
+      ids: [id],
+      checks,
+      diff: computeFieldDiff(current, data),
+      impact: { affected: 1, scope: "single-record", reversible: true },
+      warnings,
+      data: envelopeData
+    }, { redactPersonalData: this.http.redactPersonalData });
   }
-  return {
-    rows: out,
-    names: {
-      truncated: capped > 0,
-      capped,
-      note: parts.join("; "),
-      ...Object.keys(reasons).length > 0 ? { reasons } : {},
-      ...catalogError !== void 0 ? { catalogError } : {}
+  /**
+   * `delete` dry-run: current-record verification + the stale-object check +
+   * the pinned envelope (no diff — a delete has no before/after fields). NO
+   * mutating request is issued.
+   */
+  async runDeleteDryRun(id, opts = {}, parentId) {
+    const operation = `${this.config.key}.delete`;
+    const checks = [];
+    const warnings = [];
+    const path = parentId === void 0 ? `${this.resourcePath}/${id}` : this.scopedItemPath(parentId, id);
+    let current = null;
+    try {
+      current = parentId === void 0 ? await this.getGlobal(id, true) : this.config.attachmentGet ? await this.getScopedModel(parentId, id, true) : await this.getScopedRaw(parentId, id, true);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        checks.push({ name: "current-record-exists", ok: false });
+        warnings.push(`record ${id} not fetchable; the vendor would reject the delete`);
+        return buildDryRunResult({
+          operation,
+          method: "DELETE",
+          path,
+          ids: [id],
+          checks,
+          impact: { affected: 1, scope: "single-record", reversible: false },
+          warnings
+        }, { redactPersonalData: this.http.redactPersonalData });
+      }
+      throw err;
     }
-  };
-}
-async function labelFetchResults(client, result) {
-  const byResource = /* @__PURE__ */ new Map();
-  result.results.forEach((r, i) => {
-    if (r.found && r.value !== null) byResource.set(r.resource, [...byResource.get(r.resource) ?? [], i]);
-  });
-  const results = [...result.results];
-  const summaries = [];
-  const reasons = {};
-  const catalogErrors = {};
-  for (const [resource, indices] of byResource) {
-    const labelled = await labelRows(client, resource, indices.map((i) => results[i].value), true);
-    indices.forEach((idx, j) => {
-      results[idx] = { ...results[idx], value: labelled.rows[j] };
-    });
-    if (labelled.names !== void 0) {
-      summaries.push(labelled.names);
-      for (const [field, why] of Object.entries(labelled.names.reasons ?? {})) reasons[`${resource}.${field}`] = why;
-      if (labelled.names.catalogError !== void 0) catalogErrors[resource] = labelled.names.catalogError;
-    }
-  }
-  if (summaries.length === 0) return { ...result, results };
-  const catalogError = Object.values(catalogErrors)[0];
-  const names = {
-    truncated: summaries.some((s) => s.truncated),
-    capped: summaries.reduce((n, s) => n + s.capped, 0),
-    note: summaries.map((s) => s.note).join("; "),
-    ...Object.keys(reasons).length > 0 ? { reasons } : {},
-    ...catalogError !== void 0 ? { catalogError, catalogErrors } : {}
-  };
-  return { ...result, results, names };
-}
+    checks.push({ name: "current-record-exists", ok: true });
+    if (this.staleObjectCheck(current, opts, operation)) {
+      checks.push({ name: "stale-check", ok: true });
+    }
+    return buildDryRunResult({
+      operation,
+      method: "DELETE",
+      path,
+      ids: [id],
+      checks,
+      impact: { affected: 1, scope: "single-record", reversible: false },
+      warnings
+    }, { redactPersonalData: this.http.redactPersonalData });
+  }
+};
+
+// src/resources/base/BaseResource.ts
+var BaseResource = class extends MutationBase {
+};
 
 // src/resources/billing_codes.ts
 var BillingCodesResource = class extends BaseResource {
@@ -20954,7 +20913,7 @@ function formatUnknownNameList(names, cap = UNKNOWN_NAME_LIST_CAP) {
   const more = names.length > cap ? ` (and ${names.length - cap} more)` : "";
   return `${listed}${more}`;
 }
-function collectFilterFieldNames(conditions) {
+function collectFilterFieldNames(conditions, resourceKey) {
   const out = [];
   const walk = (conds) => {
     for (const cond of conds) {
@@ -20964,7 +20923,16 @@ function collectFilterFieldNames(conditions) {
         continue;
       }
       if (cond.udf === true) continue;
-      if (typeof cond.field === "string" && cond.field.length > 0 && !cond.field.includes(".")) out.push(cond.field);
+      if (typeof cond.field === "string" && cond.field.length > 0) {
+        if (!cond.field.includes(".")) {
+          out.push(cond.field);
+          continue;
+        }
+        if (resourceKey !== void 0) {
+          const parts = cond.field.split(".");
+          if (parts.length === 2 && selfPrefixes(resourceKey).includes(parts[0])) out.push(parts[1]);
+        }
+      }
     }
   };
   walk(conditions);
@@ -21027,10 +20995,17 @@ function unknownNamesRefusal(record, authority, known, unknownInclude, unknownFi
     message,
     {
       operation: record.id,
-      suggestedAction: `Use exact vendor field names (operations.fieldCatalog with resources: ["${record.resource}"] lists the live set for the entity); pass fieldCheck: false to disable this name check. The authority here was ${authority}.`
+      suggestedAction: unknownNamesSuggestedAction(record, authority, unknownFilter.length > 0)
     }
   );
 }
+function unknownNamesSuggestedAction(record, authority, filterUnknown) {
+  const vendor = `Use exact vendor field names (operations.fieldCatalog resources: ["${record.resource}"] lists the live set).`;
+  if (filterUnknown && record.udfCapable) {
+    return `${vendor} UDF names: filter with udf: true (max 1 per query); names + picklist ids via fieldCatalog resources: ["${record.resource}"], include: ["udf"], labels: true; fieldCheck: false = vendor names only (never UDF names). Authority: ${authority}.`;
+  }
+  return `${vendor} Pass fieldCheck: false to disable this name check. The authority here was ${authority}.`;
+}
 async function validateQueryFieldNames(record, holder, args) {
   const bag = args[0];
   if (!isRecord2(bag)) return;
@@ -21039,7 +21014,7 @@ async function validateQueryFieldNames(record, holder, args) {
   let filterNames;
   if (bag["filter"] !== void 0) {
     const conditions = normalizedConditions(bag["filter"]);
-    filterNames = collectFilterFieldNames(conditions ?? []);
+    filterNames = collectFilterFieldNames(conditions ?? [], record.resource);
   }
   if (fieldCheck === false) return;
   const found = await findUnknownFieldNames(record, holder, { includeFields: includeNames ?? [], filter: filterNames ?? [] });
@@ -21653,7 +21628,22 @@ async function readBillingPart(http, v, companyIds) {
     if (v.dateFrom !== void 0) billingConditions.push({ field: "itemDate", op: "gte", value: v.dateFrom });
     if (v.dateTo !== void 0) billingConditions.push({ field: "itemDate", op: "lte", value: v.dateTo });
   }
-  const billingFields = resolveFieldsPreset("billing_join", "billing_items");
+  const billingFields = [
+    "companyID",
+    "ticketID",
+    "projectID",
+    "timeEntryID",
+    "contractServiceID",
+    "contractID",
+    "billingCodeID",
+    "expenseItemID",
+    "itemDate",
+    "quantity",
+    "rate",
+    "extendedPrice",
+    "totalAmount",
+    "nonBillable"
+  ];
   const billingIncludeFields = [...billingFields, "id", ...v.includeNotes ? ["description"] : []];
   const billingRaw = await boundedPart(http, "/V1.0/BillingItems/query", billingConditions, v.limit, OP3, billingIncludeFields);
   let billingItems = billingRaw.items;
@@ -22038,7 +22028,7 @@ async function fetchMany(client, items, opts = {}) {
   if (opts.liveFields !== void 0 && typeof opts.liveFields !== "boolean") {
     throw new AutotaskConfigError(`fetchMany: liveFields must be a boolean (got ${typeof opts.liveFields})`);
   }
-  const labels = readNamesOpt(opts.names, "fetchMany");
+  const labels = readNamesOpt(client, opts.names, "fetchMany");
   const cap = Math.min(FETCH_MANY_MAX_ITEMS, opts.maxItems ?? FETCH_MANY_MAX_ITEMS);
   if (opts.liveFields === true) {
     validateFetchManyItems(items, cap, void 0, void 0, { fieldCheck: false });
@@ -22123,7 +22113,7 @@ async function fetchByIds(client, items, opts = {}) {
       throw new AutotaskConfigError(`fetchByIds: maxItems must be an integer >= 1 (got ${String(opts.maxItems)})`);
     }
   }
-  const labels = readNamesOpt(opts.names, "fetchByIds");
+  const labels = readNamesOpt(client, opts.names, "fetchByIds");
   const cap = Math.min(FETCH_BY_IDS_MAX_ITEMS, opts.maxItems ?? FETCH_BY_IDS_MAX_ITEMS);
   validateFetchManyItems(items, cap, "fetchByIds", `FETCH_BY_IDS_MAX_ITEMS = ${FETCH_BY_IDS_MAX_ITEMS}`);
   const groups = /* @__PURE__ */ new Map();
@@ -22729,7 +22719,7 @@ function appendWiresNote(wires, note) {
   wires.note = (wires.note ? wires.note + " | " : "") + note;
 }
 function makeFetchCtx(rawHttp, v, contractId, budget) {
-  const OP9 = PROFITABILITY_OP;
+  const OP8 = PROFITABILITY_OP;
   const id = parseIdentifier(contractId, "contractId");
   const idNum = typeof id === "number" ? id : Number(id);
   const wires = { issued: 0, requests: 0, budget };
@@ -22741,19 +22731,19 @@ function makeFetchCtx(rawHttp, v, contractId, budget) {
   } };
   const readPart = (path, conditions, fields) => {
     wires.issued += 1;
-    return degradable(() => boundedPart(http, path, conditions, v.limit, OP9, fields));
+    return degradable(() => boundedPart(http, path, conditions, v.limit, OP8, fields));
   };
   const truncatedMonths = {};
   const windowedPart = async (name, key, path, cond, fields, dateField) => {
     const first = await readPart(path, cond, fields);
     if (first.absent !== void 0 || !first.hasMore) return { part: stampPart(key, first, cond), rows: first.items };
-    const wp = await degradable(() => expandByMonth(http, path, cond, v.limit, OP9, fields, dateField, v.dateFrom, v.dateTo, wires));
+    const wp = await degradable(() => expandByMonth(http, path, cond, v.limit, OP8, fields, dateField, v.dateFrom, v.dateTo, wires));
     if (!("truncatedMonths" in wp)) return { part: stampPart(key, wp, cond), rows: [] };
     const { truncatedMonths: tm, ...part } = wp;
     truncatedMonths[name] = tm;
     return { part, rows: wp.items };
   };
-  return { v, OP: OP9, id, idNum, rawHttp, http, wires, windowOn, readPart, windowedPart, truncatedMonths };
+  return { v, OP: OP8, id, idNum, rawHttp, http, wires, windowOn, readPart, windowedPart, truncatedMonths };
 }
 
 // src/resources/special/contracts/profitability.stages.ts
@@ -24385,50 +24375,50 @@ async function queryTimeEntries(_resource, filter, limit, operation, http, curso
   const { items, pageDetails } = unwrapItems(res);
   return { items, hasMore: pageDetails.nextPageUrl != null, nextCursor: pageDetails.nextPageUrl ?? null };
 }
-function pagingOpts(opts, OP9) {
+function pagingOpts(opts, OP8) {
   if (opts?.countOnly !== void 0 && typeof opts.countOnly !== "boolean") {
-    throw new AutotaskConfigError(`${OP9}: countOnly must be a boolean`, { operation: OP9 });
+    throw new AutotaskConfigError(`${OP8}: countOnly must be a boolean`, { operation: OP8 });
   }
   const countOnly = opts?.countOnly === true;
   const cursor = opts?.cursor;
   if (cursor !== void 0 && (typeof cursor !== "string" || cursor.trim() === "")) {
-    throw new AutotaskConfigError(`${OP9}: cursor must be the non-empty nextCursor of a previous call`, { operation: OP9 });
+    throw new AutotaskConfigError(`${OP8}: cursor must be the non-empty nextCursor of a previous call`, { operation: OP8 });
   }
   if (cursor !== void 0 && cursor.length > CURSOR_MAX) {
-    throw new ResponseRejectedError(`${OP9}: refused the pagination cursor: ${cursor.length} chars is over the ${CURSOR_MAX}-char cap (a vendor nextPageUrl is far shorter)`);
+    throw new ResponseRejectedError(`${OP8}: refused the pagination cursor: ${cursor.length} chars is over the ${CURSOR_MAX}-char cap (a vendor nextPageUrl is far shorter)`);
   }
   if (cursor !== void 0 && countOnly) {
-    throw new AutotaskConfigError(`${OP9}: cursor does not apply with countOnly (countOnly reads every page itself)`, { operation: OP9 });
+    throw new AutotaskConfigError(`${OP8}: cursor does not apply with countOnly (countOnly reads every page itself)`, { operation: OP8 });
   }
   const budget = opts?.maxVendorCalls ?? COUNT_BUDGET_DEFAULT;
   if (!Number.isInteger(budget) || budget < 1 || budget > COUNT_BUDGET_MAX) {
-    throw new AutotaskConfigError(`${OP9}: maxVendorCalls must be an integer 1-${COUNT_BUDGET_MAX} (got ${String(opts?.maxVendorCalls)})`, { operation: OP9 });
+    throw new AutotaskConfigError(`${OP8}: maxVendorCalls must be an integer 1-${COUNT_BUDGET_MAX} (got ${String(opts?.maxVendorCalls)})`, { operation: OP8 });
   }
   return { ...cursor === void 0 ? {} : { cursor }, countOnly, budget };
 }
-function budgetExceeded(OP9, details, midWalk) {
+function budgetExceeded(OP8, details, midWalk) {
   const { estimate, budget, total } = details;
   const raise = midWalk ? budget < COUNT_BUDGET_MAX ? `, or pass a maxVendorCalls above ${budget} for headroom past the estimate` : "" : estimate <= COUNT_BUDGET_MAX ? ` or pass maxVendorCalls >= ${estimate}` : "";
   return new AutotaskError(
-    midWalk ? `${OP9}: countOnly stopped at the ${budget}-call budget mid-walk: the walk needed more calls than the ${estimate} estimated from the ${total}-entry count (more entries than counted, or an extra page such as an empty continuation page), so the next call, which may be the closing re-count, did not fit; no partial total is returned` : `${OP9}: countOnly needs an estimated ${estimate} vendor calls for ${total} entries (1 count + 1 per ${PAGE} entries + 1 join per 250 + 1 re-count), over the ${budget}-call budget; nothing was read past the count`,
-    { code: "BUDGET_EXCEEDED", category: "policy", operation: OP9, details, suggestedAction: `Narrow the dateWorked window (dateFrom/dateTo)${raise}.` }
+    midWalk ? `${OP8}: countOnly stopped at the ${budget}-call budget mid-walk: the walk needed more calls than the ${estimate} estimated from the ${total}-entry count (more entries than counted, or an extra page such as an empty continuation page), so the next call, which may be the closing re-count, did not fit; no partial total is returned` : `${OP8}: countOnly needs an estimated ${estimate} vendor calls for ${total} entries (1 count + 1 per ${PAGE} entries + 1 join per 250 + 1 re-count), over the ${budget}-call budget; nothing was read past the count`,
+    { code: "BUDGET_EXCEEDED", category: "policy", operation: OP8, details, suggestedAction: `Narrow the dateWorked window (dateFrom/dateTo)${raise}.` }
   );
 }
-async function countPostedState(http, filter, OP9, budget, window) {
+async function countPostedState(http, filter, OP8, budget, window) {
   let issued = 0;
   let estimate = 0;
   let counted = 0;
   const spend = () => {
-    if (issued >= budget) throw budgetExceeded(OP9, { estimate, budget, total: counted, issued }, true);
+    if (issued >= budget) throw budgetExceeded(OP8, { estimate, budget, total: counted, issued }, true);
     issued += 1;
   };
   spend();
   counted = unwrapQueryCount(
-    await http.request({ method: "POST", idempotent: true, path: "/V1.0/TimeEntries/query/count", body: { filter }, operation: OP9 }),
-    OP9
+    await http.request({ method: "POST", idempotent: true, path: "/V1.0/TimeEntries/query/count", body: { filter }, operation: OP8 }),
+    OP8
   );
   estimate = 1 + Math.max(1, Math.ceil(counted / PAGE)) + Math.ceil(counted / 250) + 1;
-  if (estimate > budget) throw budgetExceeded(OP9, { estimate, budget, total: counted, issued }, false);
+  if (estimate > budget) throw budgetExceeded(OP8, { estimate, budget, total: counted, issued }, false);
   const states = /* @__PURE__ */ new Map();
   let cursor = null;
   do {
@@ -24438,15 +24428,15 @@ async function countPostedState(http, filter, OP9, budget, window) {
       idempotent: true,
       path: cursor === null ? "/V1.0/TimeEntries/query" : entryCursorPath(http.baseUrl, cursor),
       body: { MaxRecords: PAGE, IncludeFields: ["id"], filter },
-      operation: OP9
+      operation: OP8
     });
     const page = unwrapItems(res);
-    const joined = await postedStateOf(http, page.items, OP9, spend);
+    const joined = await postedStateOf(http, page.items, OP8, spend);
     if (joined.incomplete) {
-      throw new AutotaskError(`${OP9}: countOnly refused: a billing-item join page was truncated (more than 500 billing items for 250 entries), so the posted split cannot be confirmed`, {
+      throw new AutotaskError(`${OP8}: countOnly refused: a billing-item join page was truncated (more than 500 billing items for 250 entries), so the posted split cannot be confirmed`, {
         code: "RESOLUTION_TRUNCATED",
         category: "resolution",
-        operation: OP9,
+        operation: OP8,
         details: { issued, budget },
         suggestedAction: "Narrow the dateWorked window, or page it with cursor (rows mode reports unconfirmed entries via hasMore)."
       });
@@ -24456,14 +24446,14 @@ async function countPostedState(http, filter, OP9, budget, window) {
   } while (cursor !== null);
   spend();
   const recounted = unwrapQueryCount(
-    await http.request({ method: "POST", idempotent: true, path: "/V1.0/TimeEntries/query/count", body: { filter }, operation: OP9 }),
-    OP9
+    await http.request({ method: "POST", idempotent: true, path: "/V1.0/TimeEntries/query/count", body: { filter }, operation: OP8 }),
+    OP8
   );
   if (states.size !== counted && states.size !== recounted) {
-    throw new AutotaskError(`${OP9}: countOnly read ${states.size} distinct entries but the window counted ${counted} before the walk and ${recounted} after it (a page repeated or dropped entries, or the window changed mid-walk); no total is returned. Retry the call`, {
+    throw new AutotaskError(`${OP8}: countOnly read ${states.size} distinct entries but the window counted ${counted} before the walk and ${recounted} after it (a page repeated or dropped entries, or the window changed mid-walk); no total is returned. Retry the call`, {
       code: "INVALID_RESPONSE",
       category: "server",
-      operation: OP9,
+      operation: OP8,
       details: { reason: "count_mismatch", streamed: states.size, counted, recounted, issued, budget },
       suggestedAction: "Retry the call; a window that changes during the walk can fail or pass depending on timing."
     });
@@ -24520,13 +24510,13 @@ async function postedStateQuery(_resource, mode, http, opts) {
   return { items, hasMore: read.hasMore || incomplete, window, nextCursor: read.nextCursor, unconfirmed, approvedCount, unapprovedCount: items.length - approvedCount };
 }
 async function postedWithin(_resource, from, to, http, opts, opLabel = "time_entries.postedWithin") {
-  const OP9 = opLabel;
-  const paging = pagingOpts(opts, OP9);
-  if (opts?.tz !== void 0) validateZone(opts.tz, OP9);
-  const fromB = customRangeDay(from, "from", void 0, OP9);
-  const toB = customRangeDay(to, "to", void 0, OP9);
+  const OP8 = opLabel;
+  const paging = pagingOpts(opts, OP8);
+  if (opts?.tz !== void 0) validateZone(opts.tz, OP8);
+  const fromB = customRangeDay(from, "from", void 0, OP8);
+  const toB = customRangeDay(to, "to", void 0, OP8);
   if (fromB.ms > toB.ms) {
-    throw new AutotaskConfigError(`${OP9}: from (${iso2(fromB.ms)}) must not be after to (${iso2(toB.ms)})`, { operation: OP9 });
+    throw new AutotaskConfigError(`${OP8}: from (${iso2(fromB.ms)}) must not be after to (${iso2(toB.ms)})`, { operation: OP8 });
   }
   const windowToMs = toB.ms + DAY_MS2 - 1;
   const filter = [
@@ -24536,9 +24526,9 @@ async function postedWithin(_resource, from, to, http, opts, opLabel = "time_ent
   if (opts?.ticketID !== void 0) filter.push({ field: "ticketID", op: "eq", value: opts.ticketID });
   if (opts?.resourceID !== void 0) filter.push({ field: "resourceID", op: "eq", value: opts.resourceID });
   const window = { from: iso2(fromB.ms), to: iso2(windowToMs) };
-  if (paging.countOnly) return countPostedState(http, filter, OP9, paging.budget, window);
-  const { items, hasMore, nextCursor } = await queryTimeEntries(_resource, filter, clampWindowLimit(opts?.limit), OP9, http, paging.cursor);
-  const { states, incomplete } = await postedStateOf(http, items, OP9);
+  if (paging.countOnly) return countPostedState(http, filter, OP8, paging.budget, window);
+  const { items, hasMore, nextCursor } = await queryTimeEntries(_resource, filter, clampWindowLimit(opts?.limit), OP8, http, paging.cursor);
+  const { states, incomplete } = await postedStateOf(http, items, OP8);
   let postedCount = 0;
   let unpostedCount = 0;
   for (const state of states.values()) {
@@ -25308,103 +25298,6 @@ async function approve(resource, id, opts = {}, http) {
   };
 }
 
-// src/resources/special/time_entries/recentTickets.ts
-var OP8 = "time_entries.recentTickets";
-var DAY_MS3 = 864e5;
-var TICKET_CHUNK = 100;
-var TICKET_FIELDS2 = ["id", "ticketNumber", "title", "status", "assignedResourceID", "companyID"];
-function positiveId2(value, name) {
-  const n = typeof value === "string" && /^\d+$/.test(value.trim()) ? Number(value) : value;
-  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 1) {
-    throw new AutotaskConfigError(`${OP8}: ${name} must be a positive integer id (got ${String(value)})`, { operation: OP8 });
-  }
-  return n;
-}
-async function recentTickets(_resource, from, to, http, opts) {
-  if (opts === void 0 || opts === null || typeof opts !== "object") {
-    throw new AutotaskConfigError(`${OP8}: opts { resourceID, companyID?, tz?, limit? } is required`, { operation: OP8 });
-  }
-  const resourceID = positiveId2(opts.resourceID, "resourceID");
-  const companyID = opts.companyID === void 0 ? void 0 : positiveId2(opts.companyID, "companyID");
-  if (opts.tz !== void 0) validateZone(opts.tz, OP8);
-  const fromB = customRangeDay(from, "from", void 0, OP8);
-  const toB = customRangeDay(to, "to", void 0, OP8);
-  if (fromB.ms > toB.ms) {
-    throw new AutotaskConfigError(`${OP8}: from (${isoUtc(fromB.ms)}) must not be after to (${isoUtc(toB.ms)})`, { operation: OP8 });
-  }
-  const windowToMs = toB.ms + DAY_MS3 - 1;
-  const { items: entries, hasMore } = await queryTimeEntries(
-    _resource,
-    [
-      { field: "dateWorked", op: "gte", value: isoUtc(fromB.ms) },
-      { field: "dateWorked", op: "lte", value: isoUtc(windowToMs) },
-      { field: "resourceID", op: "eq", value: resourceID }
-    ],
-    clampWindowLimit(opts.limit),
-    OP8,
-    http
-  );
-  const groups = /* @__PURE__ */ new Map();
-  let entriesWithoutTicket = 0;
-  for (const e of entries) {
-    if (typeof e.ticketID !== "number") {
-      entriesWithoutTicket += 1;
-      continue;
-    }
-    const g = groups.get(e.ticketID) ?? { entryCount: 0, totalHours: 0, lastWorked: "" };
-    g.entryCount += 1;
-    g.totalHours += e.hoursWorked ?? 0;
-    if ((e.dateWorked ?? "") > g.lastWorked) g.lastWorked = e.dateWorked ?? "";
-    groups.set(e.ticketID, g);
-  }
-  const ids2 = [...groups.keys()];
-  const tickets = /* @__PURE__ */ new Map();
-  for (let c = 0; c < ids2.length; c += TICKET_CHUNK) {
-    const chunk = ids2.slice(c, c + TICKET_CHUNK);
-    const filter = [{ field: "id", op: "in", value: chunk }];
-    const res = await http.request({
-      method: "POST",
-      idempotent: true,
-      path: "/V1.0/Tickets/query",
-      body: { MaxRecords: TICKET_CHUNK, filter, IncludeFields: TICKET_FIELDS2 },
-      operation: OP8
-    });
-    for (const t of unwrapItems(res, OP8).items) if (typeof t.id === "number") tickets.set(t.id, t);
-  }
-  const items = [];
-  const unresolvedTicketIDs = [];
-  let excludedTickets = 0;
-  for (const [ticketID, g] of groups) {
-    const t = tickets.get(ticketID);
-    if (t === void 0) unresolvedTicketIDs.push(ticketID);
-    if (companyID !== void 0 && t?.companyID !== companyID) {
-      if (t !== void 0) excludedTickets += 1;
-      continue;
-    }
-    items.push({
-      ticketID,
-      ...t?.ticketNumber !== void 0 ? { ticketNumber: t.ticketNumber } : {},
-      ...t?.title !== void 0 ? { title: t.title } : {},
-      ...t?.status !== void 0 ? { status: t.status } : {},
-      ...t?.assignedResourceID !== void 0 ? { assignedResourceID: t.assignedResourceID } : {},
-      ...t?.companyID !== void 0 ? { companyID: t.companyID } : {},
-      entryCount: g.entryCount,
-      totalHours: Math.round(g.totalHours * 100) / 100,
-      lastWorked: g.lastWorked
-    });
-  }
-  items.sort((a, b) => a.lastWorked < b.lastWorked ? 1 : a.lastWorked > b.lastWorked ? -1 : a.ticketID - b.ticketID);
-  return {
-    items,
-    entriesRead: entries.length,
-    entriesWithoutTicket,
-    unresolvedTicketIDs,
-    ...companyID !== void 0 ? { excludedTickets } : {},
-    window: { from: isoUtc(fromB.ms), to: isoUtc(windowToMs) },
-    truncated: hasMore
-  };
-}
-
 // src/resources/time_entries.ts
 var TimeEntriesResource = class extends BaseResource {
   constructor(http, pageSize) {
@@ -25536,11 +25429,6 @@ var TimeEntriesResource = class extends BaseResource {
   postedWithin(from, to, opts) {
     return postedWithin(this, from, to, this.http, opts);
   }
-  /** Node-parity special op (hand-written in src/resources/special/time_entries.ts).
-   * @deprecated Since 0.38.0, removed in the next minor. Use operations.aggregate(client, 'time_entries.query', [{ field: 'resourceID', op: 'eq', value: R }, { field: 'dateWorked', op: 'gte', value: FROM }, { field: 'dateWorked', op: 'lte', value: TO }], { groupBy: ['ticketID'], sum: ['hoursWorked'] }) — group keys carry ticketIDName; add { field: 'ticket.companyID', op: 'eq', value: C } to scope by company. */
-  recentTickets(from, to, opts) {
-    return recentTickets(this, from, to, this.http, opts);
-  }
   /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
   today(opts) {
     return windowQuery3(this, "today", this.http, opts);
@@ -25599,6 +25487,8 @@ export {
   MarkerUnsafeIdError,
   RecoveryTruncatedError,
   MoveRefusedError,
+  UNSCOPED_WALK_THRESHOLD,
+  ScopeRequiredError,
   READ_CACHE_MAX_ENTRIES,
   REFERENCE_TTL_MS,
   REFERENCE_ENTITIES,
@@ -25675,6 +25565,7 @@ export {
   unwrapOperation,
   passthrough,
   HttpClient,
+  BOUNDED_QUERY_DEFAULT_LIMIT,
   BOUNDED_QUERY_MAX_LIMIT,
   buildDryRunResult,
   mergePartialBody,
@@ -25686,31 +25577,25 @@ export {
   paginateItems,
   collectAll,
   toArray,
-  FIELD_PRESETS,
-  FIELD_PRESET_NAMES,
-  resolveFieldsPreset,
   MODEL_DATE_FIELDS,
-  EXPAND_RESOURCE_NAMES_MAX_IDS,
-  expandResourceNames,
-  ENTITY_TYPE_TO_RESOURCE,
-  resourceForEntityType,
-  isEnumerableResource,
   WORKFLOW_RESOURCES,
   MAX_FIELD_CATALOG_WIRE,
   FIELD_CATALOG_HONESTY_NOTE,
   MIN_FIELD_CATALOG_MAX_BYTES,
   fieldCatalog,
+  EXPAND_RESOURCE_NAMES_MAX_IDS,
+  expandResourceNames,
+  vendorId,
+  resolveLineOfBusinessChain,
   PICKLIST_VALUE_NOT_SERVED_NOTE,
-  PICKLIST_CATALOG_UNAVAILABLE_NOTE,
   TICKET_LABEL_FIELDS,
   createNamePlan,
   addNameSibling,
   addLabelSibling,
-  vendorId,
-  resolveLineOfBusinessChain,
   resolveCompositeNames,
   readNamesOpt,
   labelRows,
+  validateWalkBag,
   BaseResource,
   BillingCodesResource,
   BillingItemsResource,