node-autotask 0.32.0 → 0.34.0

package/dist/operations/index.cjs

@@ -43,29 +43,30 @@
 
 
 
-var _chunkIKPFR6K2cjs = require('../chunk-IKPFR6K2.cjs');
 
+var _chunkGDQ4QM7Qcjs = require('../chunk-GDQ4QM7Q.cjs');
 
-var _chunkDCTHO7CQcjs = require('../chunk-DCTHO7CQ.cjs');
+
+var _chunkFOOHJBPPcjs = require('../chunk-FOOHJBPP.cjs');
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
 function resourceFor(client, key) {
-  return client[_chunkIKPFR6K2cjs.camelKey.call(void 0, key)];
+  return client[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, key)];
 }
 async function searchAcrossResources(client, query, opts = {}) {
   const text = query.trim();
   if (text === "") {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("searchAcrossResources: query must be a non-empty string");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("searchAcrossResources: query must be a non-empty string");
   }
-  const keys = _nullishCoalesce(opts.resources, () => ( _chunkIKPFR6K2cjs.WORKFLOW_RESOURCES));
+  const keys = _nullishCoalesce(opts.resources, () => ( _chunkGDQ4QM7Qcjs.WORKFLOW_RESOURCES));
   if (keys.length === 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("searchAcrossResources: no resources requested");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("searchAcrossResources: no resources requested");
   }
-  const limit = _chunkIKPFR6K2cjs.clampPageSize.call(void 0, _nullishCoalesce(opts.limit, () => ( DEFAULT_LIMIT)));
+  const limit = _chunkGDQ4QM7Qcjs.clampPageSize.call(void 0, _nullishCoalesce(opts.limit, () => ( DEFAULT_LIMIT)));
   const totalLimit = opts.totalLimit;
   if (totalLimit !== void 0 && !(Number.isInteger(totalLimit) && totalLimit >= 1)) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("searchAcrossResources: totalLimit must be a positive integer");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("searchAcrossResources: totalLimit must be a positive integer");
   }
   const results = [];
   const skipped = [];
@@ -96,7 +97,7 @@ async function searchAcrossResources(client, query, opts = {}) {
 
 // src/operations/resolveAny.ts
 function resourceFor2(client, key) {
-  return client[_chunkIKPFR6K2cjs.camelKey.call(void 0, key)];
+  return client[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, key)];
 }
 var FAULT_CATEGORIES = /* @__PURE__ */ new Set(["auth", "rate_limit", "server", "network", "timeout", "policy"]);
 function missCost(identifier) {
@@ -105,13 +106,13 @@ function missCost(identifier) {
 }
 async function resolveAny(client, identifier, opts = {}) {
   if (typeof identifier === "number") {
-    _chunkIKPFR6K2cjs.parseIdentifier.call(void 0, identifier, "identifier");
+    _chunkGDQ4QM7Qcjs.parseIdentifier.call(void 0, identifier, "identifier");
   } else if (identifier.trim() === "") {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("resolveAny: identifier must be non-empty");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("resolveAny: identifier must be non-empty");
   }
-  const keys = _nullishCoalesce(opts.resources, () => ( _chunkIKPFR6K2cjs.WORKFLOW_RESOURCES));
+  const keys = _nullishCoalesce(opts.resources, () => ( _chunkGDQ4QM7Qcjs.WORKFLOW_RESOURCES));
   if (keys.length === 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("resolveAny: no resources requested");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("resolveAny: no resources requested");
   }
   const results = [];
   for (const key of keys) {
@@ -141,9 +142,9 @@ async function resolveAny(client, identifier, opts = {}) {
     } catch (err) {
       let code;
       let candidates = [];
-      if (err instanceof _chunkIKPFR6K2cjs.AutotaskConfigError) {
+      if (err instanceof _chunkGDQ4QM7Qcjs.AutotaskConfigError) {
         code = "CONFIG_ERROR";
-      } else if (_chunkIKPFR6K2cjs.isAutotaskError.call(void 0, err)) {
+      } else if (_chunkGDQ4QM7Qcjs.isAutotaskError.call(void 0, err)) {
         if (FAULT_CATEGORIES.has(err.category)) throw err;
         code = err.code;
         if (code === "RESOLUTION_AMBIGUOUS" && err.resourceIds !== void 0) {
@@ -170,7 +171,7 @@ async function resolveAny(client, identifier, opts = {}) {
 // src/operations/aggregate.ts
 var AGGREGATE_TOP_MAX = 100;
 var AGGREGATE_DEFAULT_TOP = 25;
-var AGGREGATE_DEFAULT_LIMIT = _chunkIKPFR6K2cjs.BOUNDED_QUERY_MAX_LIMIT;
+var AGGREGATE_DEFAULT_LIMIT = _chunkGDQ4QM7Qcjs.BOUNDED_QUERY_MAX_LIMIT;
 var AGGREGATE_DATE_BUCKETS = ["month", "week", "year"];
 var DATE_ONLY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 var DATETIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:?\d{2})?$/;
@@ -227,7 +228,7 @@ function dateBucketLabel(value, bucket) {
 }
 var QUERY_RESOURCE_KEYS = (() => {
   const s = /* @__PURE__ */ new Set();
-  for (const rec of _chunkDCTHO7CQcjs.CAPABILITIES) if (rec.operation === "query") s.add(rec.resource);
+  for (const rec of _chunkFOOHJBPPcjs.CAPABILITIES) if (rec.operation === "query") s.add(rec.resource);
   return s;
 })();
 var AGGREGATE_OPT_KEYS = ["groupBy", "sum", "top", "limit"];
@@ -263,15 +264,15 @@ function parseFilterConditions(filter, problems) {
     return [];
   }
   try {
-    return _chunkIKPFR6K2cjs.buildFilter.call(void 0, conds).filter;
+    return _chunkGDQ4QM7Qcjs.buildFilter.call(void 0, conds).filter;
   } catch (err) {
-    problems.push(err instanceof _chunkIKPFR6K2cjs.AutotaskConfigError ? err.message : `filter must be the query-bag filter (13 operators; caps 500 OR-conditions / 1 UDF / 8000 chars); ${String(err)}`);
+    problems.push(err instanceof _chunkGDQ4QM7Qcjs.AutotaskConfigError ? err.message : `filter must be the query-bag filter (13 operators; caps 500 OR-conditions / 1 UDF / 8000 chars); ${String(err)}`);
     return [];
   }
 }
 function checkOptsBag(opts, problems) {
   if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `aggregate: opts must be the options object (got ${Array.isArray(opts) ? "an array" : typeof opts})`,
       { operation: "operations.aggregate" }
     );
@@ -351,7 +352,7 @@ function parseTopAndLimit(opts, problems) {
     if (!Number.isInteger(opts.limit)) {
       problems.push(`limit must be an integer (got ${String(opts.limit)})`);
     } else {
-      limit = Math.min(Math.max(opts.limit, 1), _chunkIKPFR6K2cjs.BOUNDED_QUERY_MAX_LIMIT);
+      limit = Math.min(Math.max(opts.limit, 1), _chunkGDQ4QM7Qcjs.BOUNDED_QUERY_MAX_LIMIT);
     }
   }
   return { top, limit };
@@ -363,14 +364,14 @@ function validateAggregate(operation, filter, opts) {
   checkOptsBag(opts, problems);
   const oracles = {
     resourceKey,
-    fieldSets: resourceKey !== void 0 ? _chunkIKPFR6K2cjs.MODEL_FIELD_SETS[resourceKey] : void 0,
-    dateSets: resourceKey !== void 0 ? _chunkIKPFR6K2cjs.MODEL_DATE_FIELDS[resourceKey] : void 0
+    fieldSets: resourceKey !== void 0 ? _chunkGDQ4QM7Qcjs.MODEL_FIELD_SETS[resourceKey] : void 0,
+    dateSets: resourceKey !== void 0 ? _chunkGDQ4QM7Qcjs.MODEL_DATE_FIELDS[resourceKey] : void 0
   };
   const groupBy = parseGroupBy(opts, oracles, problems);
   const sum = checkSumFields("sum", opts.sum, oracles, problems);
   const { top, limit } = parseTopAndLimit(opts, problems);
   if (problems.length > 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `aggregate: ${problems.length} problem(s) found pre-request (zero wire was issued)
 - ` + problems.join("\n- "),
       { operation: "operations.aggregate" }
@@ -404,9 +405,9 @@ function foldGroups(items, v) {
 }
 async function aggregate(client, operation, filter, opts = {}) {
   const v = validateAggregate(operation, filter, opts);
-  const holder = client[_chunkIKPFR6K2cjs.camelKey.call(void 0, v.resourceKey)];
+  const holder = client[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, v.resourceKey)];
   if (holder === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(`aggregate: the client exposes no accessor for resource "${v.resourceKey}"`, {
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(`aggregate: the client exposes no accessor for resource "${v.resourceKey}"`, {
       operation: "operations.aggregate",
       suggestedAction: "Rebuild the client from the SDK build that ships this registry (the resource set is pinned by the plan)."
     });
@@ -440,20 +441,20 @@ async function aggregate(client, operation, filter, opts = {}) {
 async function relationshipMap(client, resourceKey) {
   void client;
   if (typeof resourceKey !== "string" || resourceKey.trim() === "") {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `relationshipMap: resourceKey must be a non-empty plan resource key string (e.g. 'tickets'; got ${typeof resourceKey === "string" ? "a blank string" : typeof resourceKey})`,
       { suggestedAction: "Pass the exact plan resource key (snake_case) from autotask_catalog \u2014 e.g. tickets, companies, configuration_items, ticket_notes." }
     );
   }
   const key = resourceKey.trim();
-  const entry = _chunkIKPFR6K2cjs.RELATIONSHIP_MAP[key];
+  const entry = _chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP[key];
   if (entry === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskError)(
-      `relationshipMap: unknown resource "${key}" \u2014 the plan has ${Object.keys(_chunkIKPFR6K2cjs.RELATIONSHIP_MAP).length} resources`,
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskError)(
+      `relationshipMap: unknown resource "${key}" \u2014 the plan has ${Object.keys(_chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP).length} resources`,
       {
         code: "RESOURCE_UNKNOWN",
         category: "validation",
-        suggestedAction: `Pass the exact plan resource key (snake_case) from autotask_catalog (e.g. tickets, companies, configuration_items). Zone facts served are ${_chunkIKPFR6K2cjs.RELATIONSHIP_ZONE.label} (${_chunkIKPFR6K2cjs.RELATIONSHIP_ZONE.zone})-verified.`
+        suggestedAction: `Pass the exact plan resource key (snake_case) from autotask_catalog (e.g. tickets, companies, configuration_items). Zone facts served are ${_chunkGDQ4QM7Qcjs.RELATIONSHIP_ZONE.label} (${_chunkGDQ4QM7Qcjs.RELATIONSHIP_ZONE.zone})-verified.`
       }
     );
   }
@@ -470,24 +471,24 @@ var BLIND_SURFACE_KINDS = [
 async function blindSurfaces(client, opts) {
   void client;
   if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("blindSurfaces: opts must be an object { resource?: string, kind?: BlindSurfaceKind }");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("blindSurfaces: opts must be an object { resource?: string, kind?: BlindSurfaceKind }");
   }
-  const inv = _chunkIKPFR6K2cjs.BLIND_SURFACE_INVENTORY;
+  const inv = _chunkGDQ4QM7Qcjs.BLIND_SURFACE_INVENTORY;
   if (inv === null) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("blindSurfaces: the reachability inventory is absent from the generated artifact \u2014 re-run the build");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("blindSurfaces: the reachability inventory is absent from the generated artifact \u2014 re-run the build");
   }
   let surfaces = inv.surfaces;
   if (_optionalChain([opts, 'optionalAccess', _ => _.resource]) !== void 0) {
     const key = typeof opts.resource === "string" ? opts.resource.trim() : "";
     if (key === "") {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
         "blindSurfaces: opts.resource must be a non-empty plan resource key string (e.g. 'tickets')",
         { suggestedAction: "Pass the exact plan resource key (snake_case) from autotask_catalog \u2014 e.g. tickets, companies, configuration_items." }
       );
     }
     if (!inv.surfaces.some((row) => row.resource === key)) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskError)(
-        `blindSurfaces: unknown resource "${key}" \u2014 the plan has ${Object.keys(_chunkIKPFR6K2cjs.RELATIONSHIP_MAP).length} resources`,
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskError)(
+        `blindSurfaces: unknown resource "${key}" \u2014 the plan has ${Object.keys(_chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP).length} resources`,
         {
           code: "RESOURCE_UNKNOWN",
           category: "validation",
@@ -499,7 +500,7 @@ async function blindSurfaces(client, opts) {
   }
   if (_optionalChain([opts, 'optionalAccess', _2 => _2.kind]) !== void 0) {
     if (!BLIND_SURFACE_KINDS.includes(opts.kind)) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
         `blindSurfaces: unknown kind "${String(opts.kind)}" \u2014 the valid classes are: ${BLIND_SURFACE_KINDS.join(", ")}`,
         { suggestedAction: `Filter with one of: ${BLIND_SURFACE_KINDS.join(", ")} (or omit kind for the full 116-surface inventory).` }
       );
@@ -512,51 +513,51 @@ async function blindSurfaces(client, opts) {
 // src/operations/probeReachability.ts
 async function probeReachability(client, opts) {
   if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("probeReachability: opts must be an object { resources?: string[], limit?: 1|2, maxWireCalls?: number, confirmProbe?: true }");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("probeReachability: opts must be an object { resources?: string[], limit?: 1|2, maxWireCalls?: number, confirmProbe?: true }");
   }
-  const defs = _chunkIKPFR6K2cjs.REACHABILITY_PROBE_DEFAULTS;
+  const defs = _chunkGDQ4QM7Qcjs.REACHABILITY_PROBE_DEFAULTS;
   if (_optionalChain([opts, 'optionalAccess', _3 => _3.confirmProbe]) !== true) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       "probeReachability: confirmProbe: true is required \u2014 the op deliberately fans out read wire across the tenant (one bounded query per surface); pass confirmProbe: true to run it",
       { suggestedAction: `Re-call with { confirmProbe: true } (plus resources/limit/maxWireCalls as needed). For the ZERO-wire pinned inventory use operations.blindSurfaces.` }
     );
   }
   const limit = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _4 => _4.limit]), () => ( defs.limitDefault));
   if (!Number.isInteger(limit) || limit < 1 || limit > defs.limitMax) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `probeReachability: limit must be an integer 1..${defs.limitMax} (got ${String(limit)}) \u2014 the rows-per-surface bound for the discovery read`
     );
   }
   const cap = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _5 => _5.maxWireCalls]), () => ( defs.defaultCap));
   if (!Number.isInteger(cap) || cap < 1) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(`probeReachability: maxWireCalls must be a positive integer (got ${String(cap)})`);
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(`probeReachability: maxWireCalls must be a positive integer (got ${String(cap)})`);
   }
   if (cap > defs.hardCap) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `probeReachability: maxWireCalls ${cap} exceeds the hard wire cap of ${defs.hardCap} \u2014 the sweep is refused above it (never capped silently)`,
       { suggestedAction: `Pass maxWireCalls \u2264 ${defs.hardCap} and a resources set no larger than the cap (the refused set is never truncated).` }
     );
   }
-  const inv = _chunkIKPFR6K2cjs.BLIND_SURFACE_INVENTORY;
+  const inv = _chunkGDQ4QM7Qcjs.BLIND_SURFACE_INVENTORY;
   if (inv === null) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("probeReachability: the reachability inventory is absent from the generated artifact \u2014 re-run the build");
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("probeReachability: the reachability inventory is absent from the generated artifact \u2014 re-run the build");
   }
   let targets;
   if (_optionalChain([opts, 'optionalAccess', _6 => _6.resources]) === void 0) {
     targets = [...defs.defaultTargets];
   } else {
     if (!Array.isArray(opts.resources) || opts.resources.length === 0) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("probeReachability: opts.resources must be a non-empty string[] of plan resource keys (or omit it for the default non-data-full set)");
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("probeReachability: opts.resources must be a non-empty string[] of plan resource keys (or omit it for the default non-data-full set)");
     }
     const seen = /* @__PURE__ */ new Set();
     for (const r of opts.resources) {
       if (typeof r !== "string" || r.trim() === "") {
-        throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(`probeReachability: opts.resources must contain non-empty plan resource key strings (got ${typeof r === "string" && r.trim() === "" ? "a blank string" : typeof r})`);
+        throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(`probeReachability: opts.resources must contain non-empty plan resource key strings (got ${typeof r === "string" && r.trim() === "" ? "a blank string" : typeof r})`);
       }
       const key = r.trim();
       if (!inv.surfaces.some((row) => row.resource === key)) {
         const surfaceCount = new Set(inv.surfaces.map((s) => s.resource)).size;
-        throw new (0, _chunkIKPFR6K2cjs.AutotaskError)(
+        throw new (0, _chunkGDQ4QM7Qcjs.AutotaskError)(
           `probeReachability: unknown resource "${key}" \u2014 the inventory has ${surfaceCount} surfaces`,
           {
             code: "RESOURCE_UNKNOWN",
@@ -570,7 +571,7 @@ async function probeReachability(client, opts) {
     targets = [...seen];
   }
   if (targets.length > cap) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `probeReachability: ${targets.length} requested surface(s) exceed the wire cap of ${cap} \u2014 the sweep is refused above its cap (never truncated)`,
       { suggestedAction: `Raise maxWireCalls (\u2264 ${defs.hardCap}) to cover the set, or pass a smaller resources list.` }
     );
@@ -580,7 +581,7 @@ async function probeReachability(client, opts) {
   for (const resource of targets.sort()) {
     const row = byResource.get(resource);
     if (row === void 0) continue;
-    const holder = client[_chunkIKPFR6K2cjs.camelKey.call(void 0, resource)];
+    const holder = client[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, resource)];
     const probeFn = _optionalChain([holder, 'optionalAccess', _7 => _7.queryBounded]);
     if (typeof probeFn !== "function") {
       results.push({
@@ -599,7 +600,7 @@ async function probeReachability(client, opts) {
         probe: { ok: true, wire: 1, error: null }
       });
     } catch (err) {
-      const code = _chunkIKPFR6K2cjs.isAutotaskError.call(void 0, err) ? err.code : "NETWORK_ERROR";
+      const code = _chunkGDQ4QM7Qcjs.isAutotaskError.call(void 0, err) ? err.code : "NETWORK_ERROR";
       const message = err instanceof Error ? err.message : String(err);
       results.push({
         ...row,
@@ -612,20 +613,6 @@ async function probeReachability(client, opts) {
   return { results, wireUsed, cap, truncated: false };
 }
 
-// src/operations/requiredFields.ts
-function effectiveRequiredFields(record, zoneFacts) {
-  const prefix = _optionalChain([zoneFacts, 'optionalAccess', _9 => _9.createGuidance, 'optionalAccess', _10 => _10.liveProvenPrefix]);
-  if (Array.isArray(prefix) && prefix.length > 0) {
-    return { fields: [...prefix], from: "live-proven" };
-  }
-  const zoneSet = _optionalChain([zoneFacts, 'optionalAccess', _11 => _11.createRequiredSet]);
-  if (Array.isArray(zoneSet) && zoneSet.length > 0) {
-    return { fields: [...zoneSet], from: "zone" };
-  }
-  const spec = _optionalChain([record, 'optionalAccess', _12 => _12.requiredFields]);
-  return { fields: Array.isArray(spec) ? [...spec] : [], from: "spec" };
-}
-
 // src/operations/createGuidance.ts
 var CREATE_BLOCKER_KINDS = [
   "ok",
@@ -641,30 +628,30 @@ var CREATE_BLOCKER_KINDS = [
 async function createGuidance(client, opts) {
   void client;
   if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       "createGuidance: opts must be an object { resources?: string[], kind?: CreateBlockerKind }"
     );
   }
-  let servedRows = _chunkIKPFR6K2cjs.CREATE_GUIDANCE.rows.map((row) => ({
+  let servedRows = _chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.rows.map((row) => ({
     ...row,
     // Issue #219 N4: one precedence rule, stated on every row (live-proven >
     // zone > spec). The spec set is not available here (it is a LIVE read) —
     // the helper is handed the plan's two shapes and names the source.
-    requiredFields: effectiveRequiredFields(void 0, _nullishCoalesce(_optionalChain([_chunkIKPFR6K2cjs.RELATIONSHIP_MAP, 'access', _13 => _13[row.resource], 'optionalAccess', _14 => _14.zoneFacts]), () => ( null)))
+    requiredFields: _chunkGDQ4QM7Qcjs.effectiveRequiredFields.call(void 0, void 0, _nullishCoalesce(_optionalChain([_chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP, 'access', _9 => _9[row.resource], 'optionalAccess', _10 => _10.zoneFacts]), () => ( null)))
   }));
-  if (_optionalChain([opts, 'optionalAccess', _15 => _15.resources]) !== void 0) {
+  if (_optionalChain([opts, 'optionalAccess', _11 => _11.resources]) !== void 0) {
     if (!Array.isArray(opts.resources) || opts.resources.length === 0) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("createGuidance: opts.resources must be a non-empty string[] of plan resource keys");
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("createGuidance: opts.resources must be a non-empty string[] of plan resource keys");
     }
     const wanted = /* @__PURE__ */ new Set();
     for (const r of opts.resources) {
       if (typeof r !== "string" || r.trim() === "") {
-        throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)("createGuidance: opts.resources must contain non-empty plan resource key strings");
+        throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)("createGuidance: opts.resources must contain non-empty plan resource key strings");
       }
       const key = r.trim();
-      if (!_chunkIKPFR6K2cjs.CREATE_GUIDANCE.rows.some((row) => row.resource === key)) {
-        throw new (0, _chunkIKPFR6K2cjs.AutotaskError)(
-          `createGuidance: unknown resource "${key}" \u2014 the catalog has ${_chunkIKPFR6K2cjs.CREATE_GUIDANCE.rows.length} create entities`,
+      if (!_chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.rows.some((row) => row.resource === key)) {
+        throw new (0, _chunkGDQ4QM7Qcjs.AutotaskError)(
+          `createGuidance: unknown resource "${key}" \u2014 the catalog has ${_chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.rows.length} create entities`,
           {
             code: "RESOURCE_UNKNOWN",
             category: "validation",
@@ -676,20 +663,20 @@ async function createGuidance(client, opts) {
     }
     servedRows = servedRows.filter((row) => wanted.has(row.resource));
   }
-  if (_optionalChain([opts, 'optionalAccess', _16 => _16.kind]) !== void 0) {
+  if (_optionalChain([opts, 'optionalAccess', _12 => _12.kind]) !== void 0) {
     if (!CREATE_BLOCKER_KINDS.includes(opts.kind)) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
         `createGuidance: unknown kind "${String(opts.kind)}" \u2014 the valid kinds are: ${CREATE_BLOCKER_KINDS.join(", ")}`
       );
     }
-    servedRows = servedRows.filter((row) => _optionalChain([row, 'access', _17 => _17.blocker, 'optionalAccess', _18 => _18.kind]) === opts.kind);
+    servedRows = servedRows.filter((row) => _optionalChain([row, 'access', _13 => _13.blocker, 'optionalAccess', _14 => _14.kind]) === opts.kind);
   }
   return {
-    zone: _chunkIKPFR6K2cjs.CREATE_GUIDANCE.zone,
-    label: _chunkIKPFR6K2cjs.CREATE_GUIDANCE.label,
-    verifiedAt: _chunkIKPFR6K2cjs.CREATE_GUIDANCE.verifiedAt,
+    zone: _chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.zone,
+    label: _chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.label,
+    verifiedAt: _chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.verifiedAt,
     rows: servedRows,
-    counts: _chunkIKPFR6K2cjs.CREATE_GUIDANCE.counts
+    counts: _chunkGDQ4QM7Qcjs.CREATE_GUIDANCE.counts
   };
 }
 
@@ -698,7 +685,7 @@ var RECOVERY_CONFIRM = "operations.recovery";
 var RECOVERY_DEFAULT_LIMIT = 25;
 var RECOVERY_MAX_LIMIT = 100;
 function configError(message, operation, suggestedAction) {
-  throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(message, { operation, suggestedAction });
+  throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(message, { operation, suggestedAction });
 }
 function parseMatchId(record) {
   const raw = record.id;
@@ -714,7 +701,7 @@ function parseMatchId(record) {
   return { id: null, unsafe: true };
 }
 function validateRecoveryInput(input, operation) {
-  if (!_chunkIKPFR6K2cjs.isRecord.call(void 0, input)) {
+  if (!_chunkGDQ4QM7Qcjs.isRecord.call(void 0, input)) {
     configError(
       `recovery: input must be an object { resource, marker, ... } (got ${typeof input})`,
       operation,
@@ -748,10 +735,10 @@ function validateRecoveryInput(input, operation) {
   return { resource, marker, action };
 }
 function resolveRecoveryTarget(client, resource, operation) {
-  const entry = _chunkIKPFR6K2cjs.RELATIONSHIP_MAP[resource];
+  const entry = _chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP[resource];
   if (entry === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskError)(
-      `recovery: unknown resource "${resource}" \u2014 the plan has ${Object.keys(_chunkIKPFR6K2cjs.RELATIONSHIP_MAP).length} resources`,
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskError)(
+      `recovery: unknown resource "${resource}" \u2014 the plan has ${Object.keys(_chunkGDQ4QM7Qcjs.RELATIONSHIP_MAP).length} resources`,
       {
         code: "RESOURCE_UNKNOWN",
         category: "validation",
@@ -760,7 +747,7 @@ function resolveRecoveryTarget(client, resource, operation) {
       }
     );
   }
-  const holder = client[_chunkIKPFR6K2cjs.camelKey.call(void 0, resource)];
+  const holder = client[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, resource)];
   if (!holder || typeof holder.queryBounded !== "function") {
     configError(
       `recovery: ${resource} exposes no bounded query surface \u2014 the marker search cannot run`,
@@ -771,7 +758,7 @@ function resolveRecoveryTarget(client, resource, operation) {
   return { entry, holder };
 }
 function resolveMarkerField(input, resource, operation) {
-  const field = input.field !== void 0 ? String(input.field) : _chunkIKPFR6K2cjs.MARKER_FIELDS[resource];
+  const field = input.field !== void 0 ? String(input.field) : _chunkGDQ4QM7Qcjs.MARKER_FIELDS[resource];
   if (typeof field !== "string" || field.trim() === "") {
     configError(
       `recovery: ${resource} has no plan markerField and no input.field was passed \u2014 the marker search needs a name-like field to filter on`,
@@ -810,7 +797,7 @@ function resolveExtraFilter(input, operation) {
     );
   }
   for (const c of input.filter) {
-    if (!_chunkIKPFR6K2cjs.isRecord.call(void 0, c) || typeof c.op !== "string" || c.op === "and" || c.op === "or") {
+    if (!_chunkGDQ4QM7Qcjs.isRecord.call(void 0, c) || typeof c.op !== "string" || c.op === "and" || c.op === "or") {
       configError(
         "recovery: input.filter accepts only plain leaf conditions ({ field, op, value }) \u2014 no grouping",
         operation,
@@ -835,7 +822,7 @@ function resolveLimit(input, operation) {
 async function applyRecoveryDeletes(holder, matches, parentId, resource, operation) {
   const deleteMethod = holder.delete;
   if (deleteMethod === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.DeleteBoundaryError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.DeleteBoundaryError)(
       `recovery: ${resource} has no delete method on the client \u2014 the boundary is marked available in the plan but the typed delete surface is missing`,
       {
         operation,
@@ -864,14 +851,14 @@ async function applyRecoveryDeletes(holder, matches, parentId, resource, operati
           verify = "still-present";
         }
       } catch (err) {
-        if (err instanceof _chunkIKPFR6K2cjs.NotFoundError) verify = "not-found";
+        if (err instanceof _chunkGDQ4QM7Qcjs.NotFoundError) verify = "not-found";
         else {
           verify = "error";
-          code = _chunkIKPFR6K2cjs.isAutotaskError.call(void 0, err) ? err.code : "SERVER_ERROR";
+          code = _chunkGDQ4QM7Qcjs.isAutotaskError.call(void 0, err) ? err.code : "SERVER_ERROR";
         }
       }
     } catch (err) {
-      code = _chunkIKPFR6K2cjs.isAutotaskError.call(void 0, err) ? err.code : "SERVER_ERROR";
+      code = _chunkGDQ4QM7Qcjs.isAutotaskError.call(void 0, err) ? err.code : "SERVER_ERROR";
     }
     deleted.push({ id, verified: verify === "not-found", code });
   }
@@ -899,7 +886,7 @@ async function recovery(client, input, opts = {}) {
   const parentId = resolveParentId(input, entry, resource, operation);
   const extra = resolveExtraFilter(input, operation);
   const limit = resolveLimit(input, operation);
-  const boundaryNote = _chunkIKPFR6K2cjs.DELETE_BOUNDARY_NOTES[resource];
+  const boundaryNote = _chunkGDQ4QM7Qcjs.DELETE_BOUNDARY_NOTES[resource];
   const boundary = {
     available: boundaryNote === void 0,
     reason: _nullishCoalesce(boundaryNote, () => ( null)),
@@ -911,7 +898,7 @@ async function recovery(client, input, opts = {}) {
   };
   const isDelete = action === "delete";
   if (isDelete && boundaryNote !== void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.DeleteBoundaryError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.DeleteBoundaryError)(
       `recovery: the vendor defines no DELETE for ${resource} \u2014 the delete cannot be issued through the API (zero wire was issued)`,
       {
         operation,
@@ -920,10 +907,10 @@ async function recovery(client, input, opts = {}) {
       }
     );
   }
-  const dryRun = _optionalChain([opts, 'optionalAccess', _19 => _19.dryRun]) !== false;
-  const confirm = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _20 => _20.confirm]), () => ( input.confirm));
+  const dryRun = _optionalChain([opts, 'optionalAccess', _15 => _15.dryRun]) !== false;
+  const confirm = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _16 => _16.confirm]), () => ( input.confirm));
   if (isDelete && !dryRun && confirm !== RECOVERY_CONFIRM) {
-    throw new (0, _chunkIKPFR6K2cjs.ConfirmationRequiredError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.ConfirmationRequiredError)(
       `recovery: action 'delete' apply is destructive and requires its confirmation flag: pass confirm: "${RECOVERY_CONFIRM}"`,
       {
         operation: RECOVERY_CONFIRM,
@@ -939,7 +926,7 @@ async function recovery(client, input, opts = {}) {
   const query = await holder.queryBounded({ filter: conditions, limit });
   if (query.hasMore) {
     const wire = isDelete ? "DELETE wire" : "mutating wire";
-    throw new (0, _chunkIKPFR6K2cjs.RecoveryTruncatedError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.RecoveryTruncatedError)(
       `recovery: the marker search on ${resource} TRIPPED its match cap (${limit}) \u2014 more matches exist than were returned (zero ${wire} was issued)`,
       {
         operation,
@@ -968,7 +955,7 @@ async function recovery(client, input, opts = {}) {
     return { ...base, simulated: true, dryRun: true };
   }
   if (unsafeId) {
-    throw new (0, _chunkIKPFR6K2cjs.MarkerUnsafeIdError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.MarkerUnsafeIdError)(
       `recovery: ${unsafeIds.length} of ${matches.length} match(es) on ${resource} have ids beyond Number.MAX_SAFE_INTEGER \u2014 they CANNOT be addressed through the SDK's typed delete surface (zero DELETE wire was issued)`,
       {
         operation,
@@ -986,7 +973,7 @@ function needsConfirmation(record) {
   return record.effect === "destructive" || (_nullishCoalesce(record.flags, () => ( []))).includes("requiresApproval");
 }
 function refuse(message, operation, suggestedAction) {
-  throw new (0, _chunkIKPFR6K2cjs.ConfirmationRequiredError)(message, { operation, suggestedAction });
+  throw new (0, _chunkGDQ4QM7Qcjs.ConfirmationRequiredError)(message, { operation, suggestedAction });
 }
 var MODE_BY_EFFECT = {
   read: "read",
@@ -1032,7 +1019,7 @@ function looseTypeOk(type, value) {
     case "string[]":
       return Array.isArray(value) && value.every((v) => typeof v === "string");
     case "object":
-      return _chunkIKPFR6K2cjs.isRecord.call(void 0, value);
+      return _chunkGDQ4QM7Qcjs.isRecord.call(void 0, value);
     default:
       return true;
   }
@@ -1046,12 +1033,12 @@ function declaredArgList(record) {
 function resolveDispatchArgs(record, argsIn) {
   const operation = record.id;
   const bad = (message) => {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(`invoke: "${operation}" ${message}`, { operation });
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(`invoke: "${operation}" ${message}`, { operation });
   };
   if (argsIn === void 0 || argsIn === null) return [];
   if (Array.isArray(argsIn)) return argsIn;
   const byName = argsIn;
-  if (!_chunkIKPFR6K2cjs.isRecord.call(void 0, byName) || ![Object.prototype, null].includes(Object.getPrototypeOf(byName))) {
+  if (!_chunkGDQ4QM7Qcjs.isRecord.call(void 0, byName) || ![Object.prototype, null].includes(Object.getPrototypeOf(byName))) {
     return bad(`args must be a positional array or a plain object of named inputs (declared: ${declaredArgList(record)})`);
   }
   const schema = _nullishCoalesce(record.inputSchema, () => ( {}));
@@ -1072,7 +1059,7 @@ function validateDispatchArgs(record, argsIn) {
     const bagName = names.find((n) => schema[n].properties);
     const surplus = args[names.length];
     const bagHint = bagName && surplus !== null && typeof surplus === "object" && !Array.isArray(surplus) ? ` \u2014 options go inside the single ${bagName} object` : "";
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: "${operation}" declares ${names.length} positional arg(s) (${declaredArgList(record)}) but ${args.length} were passed \u2014 extra args are refused${bagHint}`,
       {
         operation,
@@ -1082,7 +1069,7 @@ function validateDispatchArgs(record, argsIn) {
   }
   const required = names.filter((n) => schema[n].required);
   if (args.length < required.length) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: "${operation}" requires ${required.length} positional arg(s) (${required.map((n) => `${n}: ${schema[n].type}`).join(", ")}) but only ${args.length} were passed \u2014 declared args: ${declaredArgList(record)}`,
       { operation }
     );
@@ -1093,7 +1080,7 @@ function validateDispatchArgs(record, argsIn) {
     const name = names[i];
     const spec = schema[name];
     if (!looseTypeOk(spec.type, value)) {
-      throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
         `invoke: "${operation}" arg ${i + 1} is declared ${name}: ${spec.type} \u2014 the value has the wrong type (pass a ${spec.type} value)`,
         { operation }
       );
@@ -1101,17 +1088,17 @@ function validateDispatchArgs(record, argsIn) {
   }
 }
 function foldFlattenedOpts(record, toolArgs) {
-  if (!_chunkIKPFR6K2cjs.isRecord.call(void 0, toolArgs)) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(`invoke: "${record.id}" tool args must be a plain object of named inputs`, { operation: record.id });
+  if (!_chunkGDQ4QM7Qcjs.isRecord.call(void 0, toolArgs)) {
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(`invoke: "${record.id}" tool args must be a plain object of named inputs`, { operation: record.id });
   }
-  const bagKeys = (_nullishCoalesce(_optionalChain([record, 'access', _21 => _21.inputSchema, 'optionalAccess', _22 => _22.opts, 'optionalAccess', _23 => _23.properties]), () => ( []))).map((p) => p.name);
+  const bagKeys = (_nullishCoalesce(_optionalChain([record, 'access', _17 => _17.inputSchema, 'optionalAccess', _18 => _18.opts, 'optionalAccess', _19 => _19.properties]), () => ( []))).map((p) => p.name);
   const flat = Object.keys(toolArgs).filter((k) => bagKeys.includes(k) && toolArgs[k] !== void 0 && toolArgs[k] !== null);
   const folded = { ...toolArgs };
   for (const k of bagKeys) delete folded[k];
   if (folded.opts === null) delete folded.opts;
   if (flat.length === 0) return folded;
   if (folded.opts !== void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: "${record.id}" was given both opts and flattened option(s) ${flat.map((k) => `"${k}"`).join(", ")} \u2014 pass one form`,
       { operation: record.id }
     );
@@ -1172,12 +1159,12 @@ function validateParamsBag(record, args) {
   if (record.inputSchemaStrict !== true) return;
   const valid = PARAMS_BAG_KEYS[record.operation];
   if (valid === void 0) return;
-  const bag = _optionalChain([args, 'optionalAccess', _24 => _24[0]]);
-  if (bag === void 0 || bag === null || !_chunkIKPFR6K2cjs.isRecord.call(void 0, bag)) return;
+  const bag = _optionalChain([args, 'optionalAccess', _20 => _20[0]]);
+  if (bag === void 0 || bag === null || !_chunkGDQ4QM7Qcjs.isRecord.call(void 0, bag)) return;
   const unknown = Object.keys(bag).filter((k) => !valid.includes(k));
   if (unknown.length === 0) return;
   const suggestions = unknown.map((k) => [k, suggestForKey(k, valid)]).filter((pair) => pair[1] !== null).map(([k, s]) => `"${k}" \u2192 "${s}"`);
-  throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+  throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
     `invoke: "${record.id}" params bag has unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 the bag is closed (valid keys: ${valid.join(", ")})`,
     {
       operation: record.id,
@@ -1185,17 +1172,36 @@ function validateParamsBag(record, args) {
     }
   );
 }
-var INVOKE_OPTION_KEYS = ["dryRun", "confirm", "lastModifiedDate", "maxRetries", "mode"];
+function validateGetBag(record, args) {
+  if (record.kind !== "primitive" || record.operation !== "get") return;
+  const at = Object.keys(_nullishCoalesce(record.inputSchema, () => ( {}))).indexOf("opts");
+  const bag = at < 0 ? void 0 : _optionalChain([args, 'optionalAccess', _21 => _21[at]]);
+  if (bag === void 0 || bag === null || !_chunkGDQ4QM7Qcjs.isRecord.call(void 0, bag)) return;
+  const unknown = Object.keys(bag).filter((k) => k !== "fresh");
+  if (unknown.length > 0) {
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
+      `invoke: "${record.id}" opts bag has unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 the bag is closed (valid keys: fresh)`,
+      { operation: record.id, suggestedAction: "Pass only { fresh?: boolean }." }
+    );
+  }
+  if (bag.fresh !== void 0 && typeof bag.fresh !== "boolean") {
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
+      `invoke: fresh must be a boolean (got ${typeof bag.fresh}) \u2014 "${record.id}" was not issued`,
+      { operation: record.id, suggestedAction: "Pass fresh: true (bypass the read cache) or omit it." }
+    );
+  }
+}
+var INVOKE_OPTION_KEYS = ["dryRun", "confirm", "lastModifiedDate", "maxRetries", "fresh", "mode"];
 function validateInvokeOptions(opts, operation) {
   if (opts === void 0 || opts === null) return;
   const unknown = Object.keys(opts).filter((k) => !INVOKE_OPTION_KEYS.includes(k));
   if (unknown.length === 0) return;
-  const suggestions = unknown.map((k) => [k, suggestForKey(k, ["dryRun", "confirm", "lastModifiedDate", "maxRetries"])]).filter((pair) => pair[1] !== null).map(([k, s]) => `"${k}" \u2192 "${s}"`);
-  throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
-    `invoke: "${operation}" has unknown option key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 the options set is closed (valid: dryRun, confirm, lastModifiedDate, maxRetries; "mode" is internal to the mode wrappers)`,
+  const suggestions = unknown.map((k) => [k, suggestForKey(k, ["dryRun", "confirm", "lastModifiedDate", "maxRetries", "fresh"])]).filter((pair) => pair[1] !== null).map(([k, s]) => `"${k}" \u2192 "${s}"`);
+  throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
+    `invoke: "${operation}" has unknown option key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 the options set is closed (valid: dryRun, confirm, lastModifiedDate, maxRetries, fresh; "mode" is internal to the mode wrappers)`,
     {
       operation,
-      suggestedAction: suggestions.length > 0 ? `Fix the option name (${suggestions.join(", ")}).` : `Pass only dryRun / confirm / lastModifiedDate / maxRetries.`
+      suggestedAction: suggestions.length > 0 ? `Fix the option name (${suggestions.join(", ")}).` : `Pass only dryRun / confirm / lastModifiedDate / maxRetries / fresh.`
     }
   );
 }
@@ -1204,7 +1210,7 @@ function unknownKeysRefusal(raw, validKeys, subject, operation) {
   const unknown = Object.keys(raw).filter((k) => !validKeys.includes(k));
   if (unknown.length === 0) return null;
   const suggestions = unknown.map((k) => [k, suggestForKey(k, [...validKeys])]).filter((pair) => pair[1] !== null).map(([k, s]) => `"${k}" \u2192 "${s}"`);
-  return new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+  return new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
     `unknown ${subject} ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 the ${subject} set is closed (valid keys: ${validKeys.join(", ")})`,
     {
       ...operation !== void 0 ? { operation } : {},
@@ -1214,7 +1220,7 @@ function unknownKeysRefusal(raw, validKeys, subject, operation) {
 }
 
 // src/operations/invoke/registry.ts
-var RECORDS = _chunkDCTHO7CQcjs.CAPABILITIES;
+var RECORDS = _chunkFOOHJBPPcjs.CAPABILITIES;
 var byId = new Map(RECORDS.map((r) => [r.id, r]));
 
 // src/operations/invoke/dispatch.ts
@@ -1233,7 +1239,7 @@ function bufferResult(buf) {
 function resolveRecord(operation) {
   const record = byId.get(operation);
   if (record === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: unknown operation "${operation}" \u2014 it is not in the capability registry`,
       { operation, suggestedAction: "List the registry (the ./capabilities subpath) for the exact operation key." }
     );
@@ -1244,16 +1250,30 @@ function governPreRequest(record, operation, opts) {
   validateInvokeOptions(opts, operation);
   const mode = opts.mode;
   if (mode !== void 0 && MODE_BY_EFFECT[record.effect] !== mode) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(crossModeRefusal(operation, record.effect, mode), { operation });
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(crossModeRefusal(operation, record.effect, mode), { operation });
   }
   if (opts.dryRun !== void 0 && typeof opts.dryRun !== "boolean") {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: dryRun must be a boolean (got ${typeof opts.dryRun}) \u2014 "${operation}" was not issued`,
       { operation, suggestedAction: "Pass dryRun: true (simulate) or dryRun: false (apply) as a real boolean." }
     );
   }
+  if (opts.fresh !== void 0) {
+    if (typeof opts.fresh !== "boolean") {
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
+        `invoke: fresh must be a boolean (got ${typeof opts.fresh}) \u2014 "${operation}" was not issued`,
+        { operation, suggestedAction: "Pass fresh: true (bypass the read cache) or omit it." }
+      );
+    }
+    if (record.effect !== "read" || record.kind !== "primitive" || record.operation !== "get" || !("opts" in (_nullishCoalesce(record.inputSchema, () => ( {}))))) {
+      throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
+        `invoke: fresh applies only to a single-record "<resource>.get" read \u2014 "${operation}" was not issued`,
+        { operation, suggestedAction: "Drop the fresh option (only <resource>.get consults the read cache per call)." }
+      );
+    }
+  }
   if (record.effect === "read" && opts.dryRun === true) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: "${operation}" is a read \u2014 dryRun is not applicable (reads issue their request as-is)`,
       { operation }
     );
@@ -1270,7 +1290,7 @@ function operationsHolder(client) {
   return {
     resolveAny: (identifier, opts) => resolveAny(client, identifier, opts),
     searchAcrossResources: (query, opts) => searchAcrossResources(client, query, opts),
-    fetchMany: (items, opts) => _chunkIKPFR6K2cjs.fetchMany.call(void 0, client, items, opts),
+    fetchMany: (items, opts) => _chunkGDQ4QM7Qcjs.fetchMany.call(void 0, client, items, opts),
     // Issue #62: the generic aggregate + the cheap count — the
     // groupBy/sum-absent mode is ONE vendor /query/count (the S12-C blind
     // sentinel rides through); the group/sum modes walk the named
@@ -1280,12 +1300,12 @@ function operationsHolder(client) {
     // Issue #59 PR-B: the bulk fetch by ids — query-first chunked `id in`
     // reads + the per-id `get` fallback (blind-surface-safe; per-item
     // typed outcomes reuse the fetchMany shapes).
-    fetchByIds: (items, opts) => _chunkIKPFR6K2cjs.fetchByIds.call(void 0, client, items, opts),
+    fetchByIds: (items, opts) => _chunkGDQ4QM7Qcjs.fetchByIds.call(void 0, client, items, opts),
     // Issue #65: opt-in resource name expansion — per-id resources.get
     // reads ONLY (never an id-in query — the resources table can be blind
     // to count/query while per-id reads work); blind-marked rows for ids
     // the API user cannot resolve; the name cache (default-on).
-    expandResourceNames: (ids, opts) => _chunkIKPFR6K2cjs.expandResourceNames.call(void 0, client, ids, opts),
+    expandResourceNames: (ids, opts) => _chunkGDQ4QM7Qcjs.expandResourceNames.call(void 0, client, ids, opts),
     relationshipMap: (resourceKey) => relationshipMap(client, resourceKey),
     // Issue #11: the served blind-surface inventory (zero wire) + the
     // bounded caller-opted reachability sweep (read-only, confirmProbe-
@@ -1295,12 +1315,12 @@ function operationsHolder(client) {
     // Issue #12: the served zone-fact create-guidance catalog (zero wire).
     createGuidance: (opts) => createGuidance(client, opts),
     // Issue #202: ExecuteCommand deep links — pure, zero wire.
-    uiLink: (input) => _chunkIKPFR6K2cjs.uiLink.call(void 0, client, input),
+    uiLink: (input) => _chunkGDQ4QM7Qcjs.uiLink.call(void 0, client, input),
     // Issue #31: the opt-in live field-metadata channel — N bounded
     // entityInformation GETs (the op's own cap refuses over-cap fan-outs
     // pre-request; per-resource failures are recorded on the row and
     // never abort the call).
-    fieldCatalog: (opts) => _chunkIKPFR6K2cjs.fieldCatalog.call(void 0, client, opts),
+    fieldCatalog: (opts) => _chunkGDQ4QM7Qcjs.fieldCatalog.call(void 0, client, opts),
     // Issue #9: the one-call recovery/cleanup op — effect write in the
     // registry (the governor's dry-run-first applies to it); the op's own
     // confirm gate makes the destructive action deliberate (the governor
@@ -1310,15 +1330,15 @@ function operationsHolder(client) {
 }
 function resolveHolder(client, record, operation) {
   const clientBag = client;
-  let holder = clientBag[_chunkIKPFR6K2cjs.camelKey.call(void 0, record.resource)];
+  let holder = clientBag[_chunkGDQ4QM7Qcjs.camelKey.call(void 0, record.resource)];
   if (typeof holder === "function") {
-    holder = _nullishCoalesce(clientBag[`${_chunkIKPFR6K2cjs.camelKey.call(void 0, record.resource)}Resource`], () => ( holder));
+    holder = _nullishCoalesce(clientBag[`${_chunkGDQ4QM7Qcjs.camelKey.call(void 0, record.resource)}Resource`], () => ( holder));
   }
   if (holder === void 0 && record.resource === "operations") {
     holder = operationsHolder(client);
   }
   if (holder === void 0) {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: the client exposes no accessor for resource "${record.resource}"`,
       { operation }
     );
@@ -1362,20 +1382,27 @@ function buildCallArgs(record, args, mutationOpts, isWrite) {
   }
   return callArgs;
 }
+function appendFresh(record, callArgs) {
+  const at = Object.keys(_nullishCoalesce(record.inputSchema, () => ( {}))).indexOf("opts");
+  while (callArgs.length < at) callArgs.push(void 0);
+  callArgs[at] = { fresh: true };
+  return callArgs;
+}
 async function invokeMode(client, operation, argsIn = [], opts = {}) {
   const record = resolveRecord(operation);
   governPreRequest(record, operation, opts);
   const args = resolveDispatchArgs(record, argsIn);
   validateDispatchArgs(record, args);
   validateParamsBag(record, args);
+  validateGetBag(record, args);
   const boundedQuery = record.kind === "primitive" && record.operation === "query";
   const countedQuery = record.kind === "primitive" && record.operation === "count";
   const holder = resolveHolder(client, record, operation);
-  if (boundedQuery || countedQuery) await _chunkIKPFR6K2cjs.validateQueryFieldNames.call(void 0, record, holder, args);
+  if (boundedQuery || countedQuery) await _chunkGDQ4QM7Qcjs.validateQueryFieldNames.call(void 0, record, holder, args);
   const methodName = boundedQuery ? "queryBounded" : record.operation;
   const method = holder[methodName];
   if (typeof method !== "function") {
-    throw new (0, _chunkIKPFR6K2cjs.AutotaskConfigError)(
+    throw new (0, _chunkGDQ4QM7Qcjs.AutotaskConfigError)(
       `invoke: "${record.resource}.${methodName}" is not a callable method on the client`,
       { operation }
     );
@@ -1383,6 +1410,7 @@ async function invokeMode(client, operation, argsIn = [], opts = {}) {
   const isWrite = record.effect !== "read";
   const mutationOpts = buildMutationOpts(opts, isWrite);
   const callArgs = buildCallArgs(record, args, mutationOpts, isWrite);
+  if (opts.fresh === true) appendFresh(record, callArgs);
   const result = await method.apply(holder, callArgs);
   return Buffer.isBuffer(result) ? bufferResult(result) : result;
 }
@@ -1452,4 +1480,4 @@ async function invokeDelete(client, operation, args = [], opts = {}) {
 
 
 
-exports.AGGREGATE_DATE_BUCKETS = AGGREGATE_DATE_BUCKETS; exports.AGGREGATE_DEFAULT_LIMIT = AGGREGATE_DEFAULT_LIMIT; exports.AGGREGATE_DEFAULT_TOP = AGGREGATE_DEFAULT_TOP; exports.AGGREGATE_TOP_MAX = AGGREGATE_TOP_MAX; exports.BLIND_SURFACE_KINDS = BLIND_SURFACE_KINDS; exports.CREATE_BLOCKER_KINDS = CREATE_BLOCKER_KINDS; exports.ENTITY_TYPE_TO_RESOURCE = _chunkIKPFR6K2cjs.ENTITY_TYPE_TO_RESOURCE; exports.EXPAND_RESOURCE_NAMES_MAX_IDS = _chunkIKPFR6K2cjs.EXPAND_RESOURCE_NAMES_MAX_IDS; exports.FETCH_BY_IDS_CHUNK_SIZE = _chunkIKPFR6K2cjs.FETCH_BY_IDS_CHUNK_SIZE; exports.FETCH_BY_IDS_MAX_ITEMS = _chunkIKPFR6K2cjs.FETCH_BY_IDS_MAX_ITEMS; exports.FETCH_MANY_MAX_ITEMS = _chunkIKPFR6K2cjs.FETCH_MANY_MAX_ITEMS; exports.FIELD_CACHE_KINDS = _chunkIKPFR6K2cjs.FIELD_CACHE_KINDS; exports.FIELD_CATALOG_HONESTY_NOTE = _chunkIKPFR6K2cjs.FIELD_CATALOG_HONESTY_NOTE; exports.INVOKE_OPTION_KEYS = INVOKE_OPTION_KEYS; exports.MAX_FIELD_CATALOG_WIRE = _chunkIKPFR6K2cjs.MAX_FIELD_CATALOG_WIRE; exports.PARAMS_BAG_KEYS = PARAMS_BAG_KEYS; exports.PICKLIST_VALUE_NOT_SERVED_NOTE = _chunkIKPFR6K2cjs.PICKLIST_VALUE_NOT_SERVED_NOTE; exports.RECOVERY_CONFIRM = RECOVERY_CONFIRM; exports.RECOVERY_DEFAULT_LIMIT = RECOVERY_DEFAULT_LIMIT; exports.RECOVERY_MAX_LIMIT = RECOVERY_MAX_LIMIT; exports.UI_LINK_ENTITIES = _chunkIKPFR6K2cjs.UI_LINK_ENTITIES; exports.WORKFLOW_RESOURCES = _chunkIKPFR6K2cjs.WORKFLOW_RESOURCES; exports.aggregate = aggregate; exports.blindSurfaces = blindSurfaces; exports.buildUiLink = _chunkIKPFR6K2cjs.buildUiLink; exports.createGuidance = createGuidance; exports.dateBucketLabel = dateBucketLabel; exports.effectiveRequiredFields = effectiveRequiredFields; exports.expandResourceNames = _chunkIKPFR6K2cjs.expandResourceNames; exports.fetchByIds = _chunkIKPFR6K2cjs.fetchByIds; exports.fetchMany = _chunkIKPFR6K2cjs.fetchMany; exports.fieldCatalog = _chunkIKPFR6K2cjs.fieldCatalog; exports.foldFlattenedOpts = foldFlattenedOpts; exports.invoke = invoke; exports.invokeDelete = invokeDelete; exports.invokeRead = invokeRead; exports.invokeWrite = invokeWrite; exports.isEnumerableResource = _chunkIKPFR6K2cjs.isEnumerableResource; exports.needsConfirmation = needsConfirmation; exports.probeReachability = probeReachability; exports.recovery = recovery; exports.relationshipMap = relationshipMap; exports.resolveAny = resolveAny; exports.resourceForEntityType = _chunkIKPFR6K2cjs.resourceForEntityType; exports.searchAcrossResources = searchAcrossResources; exports.uiLink = _chunkIKPFR6K2cjs.uiLink; exports.unknownKeysRefusal = unknownKeysRefusal; exports.validateDispatchArgs = validateDispatchArgs; exports.validateFetchManyItems = _chunkIKPFR6K2cjs.validateFetchManyItems; exports.validateInvokeOptions = validateInvokeOptions; exports.validateParamsBag = validateParamsBag;
+exports.AGGREGATE_DATE_BUCKETS = AGGREGATE_DATE_BUCKETS; exports.AGGREGATE_DEFAULT_LIMIT = AGGREGATE_DEFAULT_LIMIT; exports.AGGREGATE_DEFAULT_TOP = AGGREGATE_DEFAULT_TOP; exports.AGGREGATE_TOP_MAX = AGGREGATE_TOP_MAX; exports.BLIND_SURFACE_KINDS = BLIND_SURFACE_KINDS; exports.CREATE_BLOCKER_KINDS = CREATE_BLOCKER_KINDS; exports.ENTITY_TYPE_TO_RESOURCE = _chunkGDQ4QM7Qcjs.ENTITY_TYPE_TO_RESOURCE; exports.EXPAND_RESOURCE_NAMES_MAX_IDS = _chunkGDQ4QM7Qcjs.EXPAND_RESOURCE_NAMES_MAX_IDS; exports.FETCH_BY_IDS_CHUNK_SIZE = _chunkGDQ4QM7Qcjs.FETCH_BY_IDS_CHUNK_SIZE; exports.FETCH_BY_IDS_MAX_ITEMS = _chunkGDQ4QM7Qcjs.FETCH_BY_IDS_MAX_ITEMS; exports.FETCH_MANY_MAX_ITEMS = _chunkGDQ4QM7Qcjs.FETCH_MANY_MAX_ITEMS; exports.FIELD_CACHE_KINDS = _chunkGDQ4QM7Qcjs.FIELD_CACHE_KINDS; exports.FIELD_CATALOG_HONESTY_NOTE = _chunkGDQ4QM7Qcjs.FIELD_CATALOG_HONESTY_NOTE; exports.INVOKE_OPTION_KEYS = INVOKE_OPTION_KEYS; exports.MAX_FIELD_CATALOG_WIRE = _chunkGDQ4QM7Qcjs.MAX_FIELD_CATALOG_WIRE; exports.PARAMS_BAG_KEYS = PARAMS_BAG_KEYS; exports.PICKLIST_VALUE_NOT_SERVED_NOTE = _chunkGDQ4QM7Qcjs.PICKLIST_VALUE_NOT_SERVED_NOTE; exports.RECOVERY_CONFIRM = RECOVERY_CONFIRM; exports.RECOVERY_DEFAULT_LIMIT = RECOVERY_DEFAULT_LIMIT; exports.RECOVERY_MAX_LIMIT = RECOVERY_MAX_LIMIT; exports.UI_LINK_ENTITIES = _chunkGDQ4QM7Qcjs.UI_LINK_ENTITIES; exports.WORKFLOW_RESOURCES = _chunkGDQ4QM7Qcjs.WORKFLOW_RESOURCES; exports.aggregate = aggregate; exports.blindSurfaces = blindSurfaces; exports.buildUiLink = _chunkGDQ4QM7Qcjs.buildUiLink; exports.createGuidance = createGuidance; exports.dateBucketLabel = dateBucketLabel; exports.effectiveRequiredFields = _chunkGDQ4QM7Qcjs.effectiveRequiredFields; exports.expandResourceNames = _chunkGDQ4QM7Qcjs.expandResourceNames; exports.fetchByIds = _chunkGDQ4QM7Qcjs.fetchByIds; exports.fetchMany = _chunkGDQ4QM7Qcjs.fetchMany; exports.fieldCatalog = _chunkGDQ4QM7Qcjs.fieldCatalog; exports.foldFlattenedOpts = foldFlattenedOpts; exports.invoke = invoke; exports.invokeDelete = invokeDelete; exports.invokeRead = invokeRead; exports.invokeWrite = invokeWrite; exports.isEnumerableResource = _chunkGDQ4QM7Qcjs.isEnumerableResource; exports.needsConfirmation = needsConfirmation; exports.probeReachability = probeReachability; exports.recovery = recovery; exports.relationshipMap = relationshipMap; exports.resolveAny = resolveAny; exports.resourceForEntityType = _chunkGDQ4QM7Qcjs.resourceForEntityType; exports.searchAcrossResources = searchAcrossResources; exports.uiLink = _chunkGDQ4QM7Qcjs.uiLink; exports.unknownKeysRefusal = unknownKeysRefusal; exports.validateDispatchArgs = validateDispatchArgs; exports.validateFetchManyItems = _chunkGDQ4QM7Qcjs.validateFetchManyItems; exports.validateInvokeOptions = validateInvokeOptions; exports.validateParamsBag = validateParamsBag;