@jacebenson/jsn 4.3.12 → 4.3.13-dev.100.1

package/src/resolve-record.js

@@ -9,7 +9,7 @@
 // resolve → mutate → report.
 
 import { assertSafeExactMatch, isHexString } from './helpers.js';
-import { errNotFound } from './errors.js';
+import { errNotFound, errUsage, AppError, CodeAmbiguous } from './errors.js';
 
 /**
  * True when the identifier looks like a ServiceNow sys_id (32 hex chars).
@@ -25,40 +25,60 @@ export function isSysId(identifier) {
  */
 export function unwrapSysId(record) {
   const sysId = record?.sys_id;
-  if (sysId && typeof sysId === 'object') return sysId.value || sysId.display_value || '';
+  if (sysId && typeof sysId === 'object') return sysId.value || '';
   return sysId || '';
 }
 
 /**
- * Resolve a single record by human identifier.
- *
- * @param {object} sdk — SDK handle (uses sdk.list)
- * @param {object} opts
- * @param {string} opts.table — ServiceNow table
- * @param {string} opts.identifier — sys_id (32 hex) or value of matchField
- * @param {string} opts.matchField — field to match non-sys_id identifiers on
- *   (e.g. 'number', 'name', 'user_name')
- * @param {string} [opts.resource] — label for the not-found error
- *   (e.g. 'User' → "User not found: <id>"); defaults to matchField
- * @param {string[]} [opts.fields] — restrict sysparm_fields when set
- * @returns {Promise<object>} the record (display values requested)
- * @throws {AppError} code not_found when no record matches
+ * Exact lookups precede partial sys_id lookup. Configured human identifiers keep
+ * their legacy precedence; identifierField explicitly disambiguates collisions.
+ * Each query requests at most two rows so no operation silently picks a match.
  */
-export async function resolveRecord(sdk, { table, identifier, matchField, resource, fields }) {
+export async function resolveRecord(sdk, { table, identifier, matchField = 'sys_id', identifierField,
+  resource, fields, displayValue = 'all', partial = true }) {
   assertSafeExactMatch(identifier);
-  const queryField = isSysId(identifier) ? 'sys_id' : matchField;
-  const params = new URLSearchParams();
-  params.set('sysparm_query', `${queryField}=${identifier}`);
-  params.set('sysparm_limit', '1');
-  params.set('sysparm_display_value', 'all');
-  if (fields && fields.length > 0) {
-    params.set('sysparm_fields', fields.join(','));
+  if (typeof identifier !== 'string' || !identifier.trim()) throw errUsage('An identifier is required.');
+  for (const value of [table, identifierField || matchField]) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value || '')) throw errUsage('Invalid table or identifier field name.');
   }
-  const records = await sdk.list(table, params);
-  if (records.length === 0) {
-    throw errNotFound(resource || matchField, identifier);
+  const explicit = identifierField !== undefined;
+  const firstField = identifierField || (isSysId(identifier) ? 'sys_id' : matchField);
+  const attempts = [];
+  async function lookup(field, operator, mode) {
+    const params = new URLSearchParams({
+      sysparm_query: `${field}${operator}${identifier}`,
+      sysparm_limit: '2', sysparm_display_value: displayValue,
+    });
+    if (fields?.length) params.set('sysparm_fields', [...new Set(['sys_id', ...fields])].join(','));
+    const records = await sdk.list(table, params);
+    const resolution = { table, field, mode, matches: Math.min(records.length, 2),
+      ...(records.length >= 2 ? { at_least: true } : {}) };
+    attempts.push(resolution);
+    if (records.length > 1) {
+      const error = new AppError(CodeAmbiguous, `Multiple ${resource || 'records'} found matching ${mode} ${field}: ${identifier}`,
+        'Use a longer/full sys_id or select the exact human field with --identifier-field <field>.');
+      error.resolution = { ...resolution, attempts };
+      throw error;
+    }
+    return records[0];
   }
-  return records[0];
+  let record = await lookup(firstField, '=', 'exact');
+  if (record) return record;
+  if (!explicit && firstField !== 'sys_id') {
+    record = await lookup('sys_id', '=', 'exact');
+    if (record) return record;
+  }
+  // An explicitly selected human field must never fall back to another field.
+  if (partial && (!explicit || firstField === 'sys_id')) {
+    record = await lookup('sys_id', 'STARTSWITH', 'prefix');
+    if (record) return record;
+    record = await lookup('sys_id', 'ENDSWITH', 'suffix');
+    if (record) return record;
+  }
+  const error = errNotFound(resource || matchField, identifier);
+  error.hint = 'No accessible record matched. Check the table/ACLs, supply a full or longer sys_id, or use --identifier-field <field> for an exact human identifier.';
+  error.resolution = { ...attempts.at(-1), attempts };
+  throw error;
 }
 
 /**
@@ -67,5 +87,7 @@ export async function resolveRecord(sdk, { table, identifier, matchField, resour
  */
 export async function resolveSysId(sdk, opts) {
   const record = await resolveRecord(sdk, { fields: ['sys_id'], ...opts });
-  return unwrapSysId(record);
+  const id = unwrapSysId(record);
+  if (!id) throw errUsage('The matched record has no readable sys_id; check field ACLs before retrying.');
+  return id;
 }

package/src/sdk-batch.js

@@ -0,0 +1,130 @@
+// Optional, read-only ServiceNow Batch REST transport. No ordinary SDK call is
+// routed here implicitly; writes are deliberately outside this initial contract.
+import { randomUUID } from 'node:crypto';
+import { AppError, errAPI, errUsage } from './errors.js';
+
+const UNSUPPORTED = new Set([404, 405, 501]);
+function malformed(message) { return new AppError('malformed_response', `Invalid Batch API response: ${message}`); }
+function errorData(error) {
+  return { code: error.code || 'network_error', message: error.message, ...(error.status ? { status: error.status } : {}) };
+}
+function normalizeRequests(sdk, requests) {
+  if (!Array.isArray(requests)) throw errUsage('Batch requests must be an array.');
+  const ids = new Set();
+  return requests.map((item, index) => {
+    if (!item || typeof item !== 'object') throw errUsage('Each batch request must be an object.');
+    const id = item.id == null ? String(index + 1) : String(item.id);
+    if (!id || ids.has(id)) throw errUsage('Batch request IDs must be nonempty and unique.');
+    ids.add(id);
+    if (String(item.method || 'GET').toUpperCase() !== 'GET' || item.body !== undefined) {
+      throw errUsage('SDK batch supports GET reads only; send writes through ordinary SDK methods with their existing safety and history contracts.');
+    }
+    if (typeof item.url !== 'string' || !item.url.trim()) throw errUsage('Each batch request needs a same-instance API URL.');
+    let url;
+    try { url = new URL(item.url, `${sdk.baseURL}/`); } catch { throw errUsage('Invalid batch API URL.'); }
+    if (url.origin !== new URL(sdk.baseURL).origin || url.username || url.password || url.hash
+      || !url.pathname.startsWith('/api/') || /\/batch\/?$/.test(url.pathname)) {
+      throw errUsage('Batch URLs must target a same-instance API endpoint; nested batches, credentials, and fragments are unsupported.');
+    }
+    const headers = new Headers(item.headers || {});
+    for (const name of headers.keys()) {
+      if (/^(authorization|cookie|x-usertoken|host|proxy-authorization)$/i.test(name)) throw errUsage('Batch subrequests cannot override authentication headers.');
+    }
+    if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+    if (sdk.domain) headers.set('X-Now-Domain', sdk.domain);
+    return { id, method: 'GET', url: url.pathname + url.search, headers: [...headers].map(([name, value]) => ({ name, value })), exclude_response_headers: true };
+  });
+}
+function decodeBody(body) {
+  if (body == null || body === '') return null;
+  if (typeof body !== 'string') throw malformed('item body must be base64 text');
+  const encoded = body.replace(/\s/g, '');
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw malformed('item body is not valid base64');
+  const text = Buffer.from(encoded, 'base64').toString('utf8');
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+function parseBatch(response, requests, batchId) {
+  // ServiceNow's endpoint returns these arrays directly, not in a Table API
+  // result wrapper. Missing/duplicated correlations are never inferred by order.
+  if (!response || response.batch_request_id !== batchId || !Array.isArray(response.serviced_requests) || !Array.isArray(response.unserviced_requests)) {
+    throw malformed('expected matching batch_request_id and serviced/unserviced arrays');
+  }
+  const expected = new Set(requests.map(item => item.id));
+  const mapped = new Map();
+  for (const id of response.unserviced_requests) {
+    if (typeof id !== 'string' || !expected.has(id) || mapped.has(id)) throw malformed('unknown or duplicate unserviced ID');
+    mapped.set(id, { id, ok: false, serviced: false, status: null, data: null,
+      error: { code: 'batch_unserviced', message: 'The batch processing limit left this request unserviced; it was not retried.' } });
+  }
+  for (const item of response.serviced_requests) {
+    if (!item || !expected.has(item.id) || mapped.has(item.id)) throw malformed('unknown or duplicate serviced ID');
+    const status = item.status_code;
+    if (!Number.isInteger(status) || status < 100 || status > 599) throw malformed('invalid item HTTP status');
+    const ok = status >= 200 && status < 300;
+    let data;
+    try { data = decodeBody(item.body); } catch (error) {
+      mapped.set(item.id, { id: item.id, ok: false, serviced: true, status, data: null, error: errorData(error) });
+      continue;
+    }
+    const error = ok ? null : errorData(errAPI(status, typeof data === 'string' ? data : JSON.stringify(data || { error: item.error_message || item.status_text || 'Request failed' })));
+    mapped.set(item.id, { id: item.id, ok, serviced: true, status, data, error });
+  }
+  return requests.map(({ id }) => mapped.get(id) || { id, ok: false, serviced: null, status: null, data: null,
+    error: { code: 'batch_missing_response', message: 'No correlated response was returned; execution is unknown and was not retried.' } });
+}
+async function individual(sdk, request, timeout) {
+  try {
+    return await sdk._withAuthenticatedRequest(`${sdk.baseURL}${request.url}`, {
+      method: 'GET', headers: Object.fromEntries(request.headers.map(({ name, value }) => [name, value])),
+    }, { timeout, normalizeErrors: true }, async response => {
+      const text = await response.text();
+      let data = text || null;
+      if (text) { try { data = JSON.parse(text); } catch { /* Non-JSON REST reads remain text. */ } }
+      return { id: request.id, ok: response.ok, serviced: true, status: response.status, data,
+        error: response.ok ? null : errorData(errAPI(response.status, text)) };
+    });
+  } catch (error) {
+    return { id: request.id, ok: false, serviced: null, status: error.status || null, data: null, error: errorData(error) };
+  }
+}
+
+/**
+ * @param {SDKClient} sdk authenticated SDK instance
+ * @param {Array<{id?: string, method?: 'GET', url: string, headers?: object}>} requests
+ * @param {{fallback?: boolean, chunkSize?: number, timeout?: number}} options
+ */
+export async function batchRead(sdk, requests, { fallback = true, chunkSize = 50, timeout = sdk.timeout } = {}) {
+  if (typeof fallback !== 'boolean') throw errUsage('Batch fallback must be a boolean.');
+  const normalized = normalizeRequests(sdk, requests);
+  if (!Number.isInteger(chunkSize) || chunkSize < 1 || chunkSize > 1000) throw errUsage('Batch chunkSize must be an integer from 1 to 1000.');
+  const results = [], transports = new Set();
+  for (let offset = 0; offset < normalized.length; offset += chunkSize) {
+    const chunk = normalized.slice(offset, offset + chunkSize);
+    let useIndividual = fallback && sdk._batchUnsupported === true;
+    if (!useIndividual) {
+      const batchId = randomUUID();
+      try {
+        const response = await sdk.request(`${sdk.baseURL}/api/now/v1/batch`, {
+          method: 'POST', timeout, touchLastSeen: false,
+          body: JSON.stringify({ batch_request_id: batchId, rest_requests: chunk }),
+        });
+        results.push(...parseBatch(response, chunk, batchId));
+        transports.add('batch');
+      } catch (error) {
+        // Only explicit endpoint absence permits fallback. ACL/auth, rate limits,
+        // malformed responses and uncertain transport failures must not replay.
+        if (!fallback || !UNSUPPORTED.has(error.status)) throw error;
+        sdk._batchUnsupported = true;
+        useIndividual = true;
+      }
+    }
+    if (useIndividual) {
+      transports.add('individual');
+      for (const request of chunk) results.push(await individual(sdk, request, timeout));
+    }
+  }
+  const successful = results.filter(item => item.ok).length;
+  return { transport: transports.size > 1 ? 'mixed' : [...transports][0] || 'none',
+    results, counts: { total: results.length, successful, failed: results.length - successful } };
+}

package/src/sdk.js

@@ -1,7 +1,8 @@
 // ServiceNow REST API client
 
+import { batchRead } from './sdk-batch.js';
 import { gunzipSync } from 'node:zlib';
-import { errAuth, errAPI, errNetwork } from './errors.js';
+import { AppError, CodeAPI, CodeAuth, errAuth, errAPI, errNetwork, errUsage } from './errors.js';
 import { getStringField } from './helpers.js';
 import { getAction, getStepTypes, createAction, updateAction, testAction } from './processflow-actions.js';
 import { readSkippedBaseline, revertSkippedUpdate } from './skipped-update-provider.js';
@@ -47,6 +48,8 @@ export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
+    this.recovery = opts.recovery;
+    this.onMutation = opts.onMutation;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
     this.domain = opts.domain || '';
     this.oauthCookies = null;
@@ -58,7 +61,13 @@ export class SDKClient {
     if (!this.authProvider) {
       throw errAuth('No authentication configured');
     }
-    const creds = await this.authProvider.getCredentials();
+    let creds;
+    try {
+      creds = await this.authProvider.getCredentials();
+    } catch (error) {
+      if (error.code === CodeAuth && this.recovery?.credentialError) throw this.recovery.credentialError(error);
+      throw error;
+    }
     if (!creds) {
       throw errAuth('No valid credentials');
     }
@@ -97,26 +106,85 @@ export class SDKClient {
 
   // Keep the timeout alive through body consumption for text/JSON requests.
   // Raw-response callers retain their existing timeout boundary at headers.
-  async _withAuthenticatedRequest(endpoint, opts, {
+  async _withAuthenticatedRequest(endpoint, opts, settings, consume = (response) => response) {
+    const url = new URL(endpoint);
+    const match = url.pathname.match(/^\/api\/now\/table\/([^/]+)(?:\/([^/]+))?\/?$/);
+    const operation = { POST: 'create', PUT: 'update', PATCH: 'update', DELETE: 'delete' }[(opts.method || 'GET').toUpperCase()];
+    const event = match && operation && this.onMutation ? {
+      table: decodeURIComponent(match[1]), sys_id: match[2] ? decodeURIComponent(match[2]) : null, operation,
+    } : null;
+    let result;
+    try {
+      result = await this._performAuthenticatedRequest(endpoint, opts, settings, async response => {
+        if (event) event.http_status = response.status;
+        const value = await consume(response);
+        if (event && value instanceof Response && response.ok && operation === 'create') {
+          try { event.sys_id = (await response.clone().json())?.result?.sys_id || null; } catch { /* ID remains unknown. */ }
+        }
+        return value;
+      });
+    } catch (error) {
+      if (event) await this._reportMutation({ ...event, outcome: error.status >= 400 && error.status < 500 && error.status !== 408
+        ? 'failed' : 'unknown', http_status: error.status || null });
+      throw error;
+    }
+    if (event) {
+      let body = result;
+      if (typeof body === 'string') { try { body = JSON.parse(body); } catch { body = null; } }
+      const id = body?.result?.sys_id;
+      if (typeof id === 'string') event.sys_id = id;
+      else if (typeof id?.value === 'string') event.sys_id = id.value;
+      await this._reportMutation({ ...event, outcome: event.http_status >= 400
+        ? (event.http_status < 500 && event.http_status !== 408 ? 'failed' : 'unknown')
+        : (event.sys_id ? 'succeeded' : 'unknown') });
+    }
+    return result;
+  }
+
+  async _reportMutation(event) {
+    // History failures must never change the outcome of a completed remote write.
+    try { await this.onMutation(event); } catch { /* App callback reports local storage failures. */ }
+  }
+
+  async _performAuthenticatedRequest(endpoint, opts, {
     timeout = this.timeout, prepare, skipOAuthSession = false, normalizeErrors = false,
   }, consume = (response) => response) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-      const req = new Request(endpoint, { ...opts, signal: controller.signal });
-      if (prepare) prepare(req);
-      await this._setAuth(req, { skipOAuthSession });
-      return await consume(await fetch(req));
-    } catch (err) {
-      if (normalizeErrors) {
-        if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
-        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
-          throw errNetwork(err);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      let rejection;
+      try {
+        const req = new Request(endpoint, { ...opts, signal: controller.signal });
+        if (prepare) prepare(req);
+        await this._setAuth(req, { skipOAuthSession });
+        const response = await fetch(req);
+        if (!skipOAuthSession && response.status === 401 && this.recovery) {
+          // Only a definitive HTTP rejection permits replay, including POST.
+          // Do not consume/echo the provider's potentially sensitive body.
+          rejection = { status: response.status, method: req.method, url: req.url };
+          await response.body?.cancel();
+        } else {
+          return await consume(response);
+        }
+      } catch (err) {
+        if (normalizeErrors) {
+          if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
+          if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+            throw errNetwork(err);
+          }
         }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
+      // Browser renewal has its own existing hard timeout. Never leave a
+      // request timeout running while waiting for the human to authenticate.
+      if (attempt === 0 && await this.recovery.recover(rejection)) {
+        this.oauthCookies = null;
+        this.sessionUserToken = '';
+        continue;
+      }
+      throw this.recovery.error || errAPI(401, '');
     }
   }
 
@@ -174,6 +242,11 @@ export class SDKClient {
     });
   }
 
+  // Explicit opt-in; ordinary SDK methods remain unbatched.
+  async batch(requests, options = {}) {
+    return batchRead(this, requests, options);
+  }
+
   async getSkippedUpdateBaseline(sysID) {
     return readSkippedBaseline(this, sysID);
   }
@@ -695,6 +768,72 @@ export class SDKClient {
     });
   }
 
+  /** Load through the native XML upload processor, then verify the exact envelope. */
+  async importUpdateSet(xml, inspection, filename = 'update-set.xml') {
+    const { sys_id: id, remote_sys_id: sourceID } = inspection;
+    const params = new URLSearchParams({
+      sysparm_query: `sys_id=${id}^ORremote_sys_id=${sourceID}`,
+      sysparm_fields: 'sys_id,name,state', sysparm_limit: '2', sysparm_display_value: 'false',
+    });
+    if ((await this.list('sys_remote_update_set', params)).length) {
+      throw errUsage('This retrieved update set already exists on the target; refusing to overwrite it. Inspect it before retrying.');
+    }
+    // Native INSERT_OR_UPDATE must not move/overwrite a member belonging to another set.
+    for (let offset = 0; offset < inspection.members.length; offset += 50) {
+      const ids = inspection.members.slice(offset, offset + 50).map(member => member.sys_id).join(',');
+      const existing = await this.list('sys_update_xml', new URLSearchParams({
+        sysparm_query: `sys_idIN${ids}`, sysparm_fields: 'sys_id', sysparm_limit: '1',
+      }));
+      if (existing.length) throw errUsage('An XML member already exists on the target; refusing to overwrite or move existing updates.');
+    }
+    const cookies = await this._warmSession();
+    const formURL = `${this.baseURL}/upload.do?sysparm_target=sys_remote_update_set`;
+    const html = await this.rawRequest(formURL, { method: 'GET', headers: cookies ? { Cookie: cookies } : {} });
+    const csrf = html.match(/name=["']sysparm_ck["'][^>]*value=["']([^"']+)["']/i)?.[1];
+    if (!csrf || !/action=["']\/sys_upload\.do["']/i.test(html) || !/name=["']attachFile["']/i.test(html)) {
+      throw errUsage('The native XML upload form is unavailable; no XML was uploaded. Check admin access and session authentication.');
+    }
+    const form = new FormData();
+    form.set('sysparm_ck', csrf);
+    form.set('sysparm_target', 'sys_remote_update_set');
+    form.set('sysparm_upload_prefix', '');
+    form.set('sysparm_referring_url', 'sys_remote_update_set_list.do');
+    form.set('attachFile', new Blob([xml], { type: 'application/xml' }), filename);
+    let outcome = 'unknown';
+    try {
+      await this.rawRequest(`${this.baseURL}/sys_upload.do`, { method: 'POST', body: form,
+        headers: { ...(cookies ? { Cookie: cookies } : {}), 'X-UserToken': csrf, Referer: formURL },
+      });
+      const records = await this.list('sys_remote_update_set', params);
+      if (records.length !== 1) throw new Error('Could not identify exactly one uploaded retrieved update set');
+      const record = records[0];
+      const importedID = getStringField(record, 'sys_id');
+      const state = getStringField(record, 'state');
+      if (state !== 'loaded' || getStringField(record, 'name') !== inspection.name) throw new Error('Uploaded update set name/state did not match the loaded export');
+      const members = [];
+      for (let offset = 0; ; offset += 500) {
+        const page = await this.list('sys_update_xml', new URLSearchParams({
+          sysparm_query: `remote_update_set=${importedID}^ORDERBYsys_id`, sysparm_limit: '500',
+          sysparm_offset: String(offset), sysparm_display_value: 'false', sysparm_fields: 'sys_id,name,action',
+        }));
+        members.push(...page);
+        if (members.length > inspection.count) throw new Error('Uploaded update set contains unexpected extra members');
+        if (page.length < 500) break;
+      }
+      const actual = new Map(members.map(member => [getStringField(member, 'sys_id'), member]));
+      if (actual.size !== inspection.count || inspection.members.some(expected => {
+        const member = actual.get(expected.sys_id);
+        return !member || getStringField(member, 'name') !== expected.name || getStringField(member, 'action') !== expected.action;
+      })) throw new Error('Uploaded update set members did not match the XML export');
+      outcome = 'succeeded';
+      return { sys_id: importedID, state, count: members.length, link: `${this.baseURL}/sys_remote_update_set.do?sys_id=${importedID}` };
+    } catch (error) {
+      throw new AppError(CodeAPI, `XML import could not be verified: ${error.message}. It may have partially loaded; inspect Retrieved Update Sets before retrying. No automatic retry was attempted.`, 'Inspect Retrieved Update Sets before retrying.', 0, error);
+    } finally {
+      if (this.onMutation) await this._reportMutation({ table: 'sys_remote_update_set', sys_id: id, operation: 'create', outcome });
+    }
+  }
+
   /**
    * Execute a background script on the ServiceNow instance via sys.scripts.do.
    * Uses a 3-step session-establishment flow compatible with OAuth tokens:

package/src/update-set-xml.js

@@ -0,0 +1,89 @@
+// Parse the export envelope without evaluating its payload or resolving entities.
+import { SaxesParser } from 'saxes';
+import { errUsage } from './errors.js';
+
+export const MAX_UPDATE_SET_BYTES = 50 * 1024 * 1024;
+const ID = /^[a-f0-9]{32}$/i;
+
+export function updateSetFilename(name) {
+  const stem = String(name).normalize('NFKC').replace(/[^a-z0-9._-]+/gi, '-').replace(/^[.-]+|[.-]+$/g, '').slice(0, 180);
+  return `${stem || 'update-set'}.xml`;
+}
+
+export function inspectUpdateSetXML(xml) {
+  if (Buffer.byteLength(xml, 'utf8') > MAX_UPDATE_SET_BYTES) throw errUsage('Update set XML exceeds the 50 MiB limit');
+  const parser = new SaxesParser();
+  const stack = [], sets = [], updates = [];
+  let record;
+  parser.on('doctype', () => { throw errUsage('DOCTYPE and external entities are not allowed in update set XML'); });
+  parser.on('opentag', tag => {
+    stack.push(tag.name);
+    if (stack.length === 1 && tag.name !== 'unload') throw errUsage('Expected an update set export with an <unload> root');
+    if (stack.length === 2) {
+      if (!['sys_remote_update_set', 'sys_update_xml'].includes(tag.name) || tag.attributes.action !== 'INSERT_OR_UPDATE') {
+        throw errUsage('Only INSERT_OR_UPDATE sys_remote_update_set and sys_update_xml envelope records may be imported');
+      }
+      record = {};
+    }
+    if (stack.length === 3) {
+      if (Object.hasOwn(record, tag.name)) throw errUsage(`Duplicate XML field: ${tag.name}`);
+      record[tag.name] = '';
+    }
+    if (stack.length > 3) throw errUsage('Update payloads must be XML text or CDATA, not nested envelope elements');
+  });
+  const text = value => { if (stack.length === 3) record[stack[2]] += value; };
+  parser.on('text', text); parser.on('cdata', text);
+  parser.on('closetag', () => {
+    if (stack.length === 2) (stack[1] === 'sys_remote_update_set' ? sets : updates).push(record);
+    stack.pop();
+  });
+  try { parser.write(xml).close(); } catch (error) { throw errUsage(`Invalid update set XML: ${error.message}`); }
+  if (sets.length !== 1) throw errUsage('Import exactly one retrieved update set per XML file');
+  const set = sets[0];
+  if (!ID.test(set.sys_id || '') || !ID.test(set.remote_sys_id || '') || !set.name?.trim()) {
+    throw errUsage('Update set requires a name, sys_id, and remote_sys_id');
+  }
+  if (set.sys_class_name && set.sys_class_name !== 'sys_remote_update_set') throw errUsage('Invalid retrieved update set class');
+  if (set.state !== 'loaded' || set.update_set?.trim()) throw errUsage('Expected a loaded, uncommitted retrieved update set export');
+  const seen = new Set();
+  const summary = new Map(), payloadOperations = new Map();
+  for (const update of updates) {
+    if (!ID.test(update.sys_id || '') || seen.has(update.sys_id.toLowerCase()) || update.remote_update_set !== set.sys_id
+      || update.update_set?.trim() || !update.name || !update.payload?.trim()
+      || !['INSERT_OR_UPDATE', 'DELETE'].includes(update.action)) {
+      throw errUsage('Invalid, duplicate, or unrelated update XML member');
+    }
+    if (update.sys_class_name && update.sys_class_name !== 'sys_update_xml') throw errUsage('Invalid update XML class');
+    seen.add(update.sys_id.toLowerCase());
+    // Payload XML stays inert; parse it solely to describe the affected table.
+    const payload = new SaxesParser(); let table = '', depth = 0, primary = '';
+    payload.on('doctype', () => { throw errUsage('DOCTYPE is not allowed in update payloads'); });
+    payload.on('opentag', tag => {
+      depth++;
+      if (depth === 1 && tag.name !== 'record_update') throw errUsage('Expected a record_update payload');
+      if (depth === 1) table = tag.attributes.table || '';
+      if (depth === 2) {
+        if (!primary) {
+          primary = tag.name;
+          if (table && table !== primary) throw errUsage('Payload table does not match its primary record');
+          table = primary;
+          if (tag.attributes.action && tag.attributes.action !== update.action) throw errUsage('Payload action does not match the update member action');
+        }
+        const action = tag.attributes.action || 'platform_default';
+        if (!['INSERT_OR_UPDATE', 'INSERT', 'UPDATE', 'DELETE', 'delete_multiple', 'platform_default'].includes(action)) throw errUsage('Unsupported payload record action');
+        const key = `${tag.name}:${action}`;
+        const operation = payloadOperations.get(key) || { table: tag.name, action, count: 0 };
+        operation.count++; payloadOperations.set(key, operation);
+      }
+    });
+    payload.on('closetag', () => { depth--; });
+    try { payload.write(update.payload).close(); } catch (error) { throw errUsage(`Invalid update payload: ${error.message}`); }
+    if (!primary || !/^[a-z][a-z0-9_]*$/i.test(table)) throw errUsage(`Missing or invalid payload table for ${update.name}`);
+    const key = `${table}:${update.action}`;
+    const row = summary.get(key) || { table, action: update.action, count: 0 };
+    row.count++; summary.set(key, row);
+  }
+  return { name: set.name, sys_id: set.sys_id, remote_sys_id: set.remote_sys_id,
+    state: set.state, count: updates.length, summary: [...summary.values()], payload_operations: [...payloadOperations.values()],
+    members: updates.map(update => ({ sys_id: update.sys_id, name: update.name, target_name: update.target_name || '', action: update.action })) };
+}