@jacebenson/jsn 4.3.13-dev.88.1 → 4.3.13-dev.90.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.88.1",
+  "version": "4.3.13-dev.90.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "@inquirer/prompts": "^7.5.1",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.5.0",
+    "saxes": "^6.0.0",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/skills/servicenow/SKILL.md

@@ -1,154 +1,33 @@
 ---
 name: servicenow
-description: |
-  Interact with ServiceNow instances via the jsn CLI. Use when working with ServiceNow
-  development, administration, or data exploration. Handles tables, records, business rules,
-  flows, script includes, ACLs, update sets, and more. Triggered by ServiceNow URLs
-  (service-now.com, servicenow.com) or when the user mentions ServiceNow, jsn, servicenow,
-  or related terms like tables, records, business rules, flows, script includes, ACLs,
-  update sets, or encoded queries.
+description: Use the jsn CLI for ServiceNow development, administration, and data exploration.
 license: MIT
-compatibility: |
-  Requires jsn CLI (github.com/jacebenson/jsn). Install via:
-  npm install -g @jacebenson/jsn
-  Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
 metadata:
   author: jacebenson
-  version: "4.3.12"
+  version: "4.3.13"
   repository: https://github.com/jacebenson/jsn
 ---
 
-# Jace's ServiceNow CLI (jsn)
+# ServiceNow with JSN
 
-Explore and manage ServiceNow instances. Interactive paginated pickers with server-side search on all list commands.
+Discover commands with `jsn --help`, `jsn discover "search words"`, and
+`jsn <command> --help`.
 
-## Discovery
+- Verify the intended instance and select it explicitly with `--profile <name>`.
+- Prefer purpose-built or records commands over `eval`. Explain the need and get
+  approval before using eval; avoid bypassing ServiceNow protections.
+- Honor delete confirmations. Get approval for destructive work and Global +
+  Default mutations; use `--force` only for the approved operation.
 
-```bash
-jsn --help                # All commands grouped by domain
-jsn <command> --help      # Flags, subcommands, and examples
-```
+For development:
 
-## Interactive Picker
+1. Choose or create the application scope and update set.
+2. Do the work, keeping related changes together.
+3. Verify the results on the instance and report where changes were captured.
+4. Offer to create ATFs and instance scans to verify the outcomes.
+5. Ask whether anything else belongs in the update set. If the user confirms
+   it is finished, complete it with notes.
 
-All `list` subcommands use a paginated interactive picker in TTY mode:
-- Arrow through items (10 per page)
-- Type to search (server-side LIKE query)
-- Scroll past last loaded item to load next page
-- Enter to select, Esc to cancel
-- Falls back to table output with `--json`
-
-## Agent Rules
-
-1. **Output modes** — `--json` when parsing data; text when presenting to humans
-2. **Use sys_id for updates** — All update/delete operations require sys_id
-3. **Verify the intended instance** — Use `--profile <name>` for explicit targeting; never assume the default is right. `jsn auth switch <name>` changes the default.
-4. **Eval safety** — Prefer purpose-built or `records` commands. Never use `eval` to bypass a blocked business rule, ACL, or other ServiceNow protection. If eval is genuinely needed, explain why and obtain explicit user approval.
-5. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
-
-## Command Hierarchy
-
-Pick the most specific tool for the job. **Never default to eval** — it's the last resort:
-
-1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn catalogitems`, etc.
-2. **`jsn records --table <name>`** — generic CRUD on any table
-3. **`jsn docs search <query>`** — offline ServiceNow documentation search (no instance needed)
-4. **`jsn rest`** — raw Table API escape hatch
-5. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
-6. **Ask the human** — if none of the above work
-
-## Key Commands
-
-| Domain | Commands |
-|--------|---------|
-| **Core** | `incidents`, `changes`, `requests`, `tasks` |
-| **Catalog** | `catalogitems list/show/create` — items with variables and flow info |
-| **Automation** | `flows`, `actions`, `rules`, `triggers`, `scheduledjobs` |
-| **Access** | `acls`, `b4rules`, `roles`, `groups`, `users` |
-| **UX** | `forms` (section/element layout), `lists`, `clientscripts`, `uipolicies` |
-| **Data** | `tables`, `columns`, `includes`, `logs`, `properties`, `records` |
-| **Config** | `setup`, `auth`, `updatesets`, `scopes` |
-| **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
-| **Developer** | `eval`, `rest`, `skill`, `version` |
-
-### Customization evidence
-
-Use `jsn customizations --help` to discover bounded read-only capture and offline
-review/comparison. For example:
-
-```sh
-jsn customizations capture --label review --customer-scope x_acme_app --json
-jsn customizations show <run_id> --json
-```
-
-Read the CLI's interpretation, coverage and per-artifact triage before drawing
-conclusions. Verify ownership and current behavior before proposing changes;
-never recommend automatic reversion.
-
-### Complete an update set
-
-Before development changes, identify the intended application scope and update
-set. Keep related changes together, use the appropriate update-set or application
-deployment mechanism, and report where changes were captured. Not all changes
-are update-set tracked. Only complete a set when the human explicitly asks,
-including sets you created; completing the current set returns selection to Default.
-
-```bash
-jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
-```
-
-`complete [name]` defaults to the current set when the name is omitted. Explicit
-names must be unique. Supply nonempty `--notes` in automation; real newlines
-separate bullets. A human terminal opens a notes editor when `--notes` is absent.
-Existing Description text is preserved and appended after confirmation. Use
-`--force` only after approval, or the profile's `skip_confirmations` policy.
-Notes apply only to the selected set. ServiceNow's normal batch rules can complete
-child sets when the parent completes; their descriptions are not replaced.
-Both selected-set Description and state are read back before success. On
-verification failure, inspect the set before retrying.
-
-### Table and raw REST discovery
-
-Use `jsn records list --help`, `jsn records get --help`, and `jsn rest --help`
-for syntax and examples. REST is blocked on read-only connections, including GET.
-
-### `jsn docs` — offline documentation search
-
-No ServiceNow instance required. Searches the full ServiceNow docs locally with FTS5 + semantic hybrid search.
-
-```bash
-# First run: download docs and build the index (~45k files, ~3-5 min)
-jsn docs sync
-
-# Check state
-jsn docs status
-
-# Search (keyword + semantic hybrid)
-jsn docs search "GlideRecord query" --limit 5 --json
-
-# Filter by bundle
-jsn docs search "REST API" --bundle it-service-management --json
-
-# Start the web UI
-jsn docs serve
-
-```
-
-**Re-running `jsn docs sync`** does a smart incremental refresh — pulls latest docs and only rebuilds changed files (seconds, not minutes).
-
-## Troubleshooting Field Behavior
-
-Check order (priority):
-
-1. **Before-query business rules** — `sys_script` with `when=before`, `action=query`
-   ```bash
-   jsn b4rules list --query "collection=sys_user"
-   ```
-2. **ACLs** — `jsn acls list --query "name=incident"`
-3. **Dictionary overrides** — `jsn records list --table sys_dictionary --query "name=incident^element=caller_id"`
-4. **Client scripts** / **UI policies** — form-level field behavior
-
-## Configuration
-
-Use `jsn setup` for interactive configuration. `jsn setup --help` lists the
-scriptable `jsn auth` equivalents and secure authentication input options.
+For incoming update sets: import the XML, preview the set, and resolve preview
+errors with the human where needed. Once the preview is clear, commit the set
+and verify the results.

package/src/capabilities.js

@@ -134,3 +134,8 @@ export function mutationPaths(caps = collectCapabilities()) {
 export function _resetCapabilities() {
   REGISTRY.clear();
 }
+
+/** Declared local-only previews bypass instance access, including context headers. */
+export function isLocalPreview(argv, caps = collectCapabilities()) {
+  return argv.dryRun === true && caps.get(argv._?.[0])?.localPreviewSubcommands?.includes(argv._?.[1]) === true;
+}

package/src/cli.js

@@ -10,7 +10,7 @@ import { resolveSession, applySession } from './session.js';
 import { renderHelp, renderTips } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { skippedUpdatesCmd } from './commands/skipped-updates.js';
-import { noInstanceCommands, dailyCheckSkipCommands, contextHeaderSkipCommands } from './capabilities.js';
+import { isLocalPreview, noInstanceCommands, dailyCheckSkipCommands, contextHeaderSkipCommands } from './capabilities.js';
 import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
 
@@ -258,6 +258,7 @@ export function buildCLI() {
     .middleware(async (argv) => {
       // Session (incl. --instance/--profile overrides) was already applied
       // by the middleware above — nothing to re-apply here.
+      if (isLocalPreview(argv)) return;
       const cmd = (argv._[0] || '').toString();
       // Daily-check + context-header skip-list is derived from command
       // capability declarations (skipDailyChecks: true).

package/src/commands/updatesets.js

@@ -1,17 +1,20 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { inspectUpdateSetXML, updateSetFilename, MAX_UPDATE_SET_BYTES } from '../update-set-xml.js';
 import { editor, confirm } from '../prompts.js';
 import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack, quoteShellArg } from '../helpers.js';
 import { getActiveProfile } from '../config.js';
 import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
-import { errAPI, errUsage, errConfirmationRequired } from '../errors.js';
+import { AppError, CodeConfirmationRequired, errAPI, errUsage, errConfirmationRequired } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveScope } from './scopes.js';
 import { unwrapSysId } from '../resolve-record.js';
 
 declareCapabilities('updatesets', {
-  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
-  mutationContextExemptSubcommands: ['create', 'set'],
+  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent', 'import', 'reopen'],
+  mutationContextExemptSubcommands: ['create', 'set', 'import', 'reopen'],
+  localPreviewSubcommands: ['import'],
 });
 
 /**
@@ -382,7 +385,7 @@ export async function formatUpdateSetDetail(app, record) {
   });
   hints.push({
     action: 'export',
-    cmd: `jsn updatesets export "${name}" --out ${name.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.xml`,
+    cmd: `jsn updatesets export "${name}" --out ${quoteShellArg(updateSetFilename(name))}`,
     description: 'Export this update set to XML',
   });
   if (!isClosed) {
@@ -478,11 +481,14 @@ export function updateSetsCmd(wrap) {
         })
         .command({
           command: 'export <name>',
-          describe: 'Export an update set to XML (raw XML to stdout, or --out file)',
+          describe: 'Export XML without changing state; auto-name a file in a terminal, preserve piped stdout',
           builder: (y) => y
             .positional('name', { describe: 'Update set name', type: 'string' })
-            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' }),
+            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' })
+            .option('out-dir', { type: 'string', describe: 'Write an automatically named XML file in this directory' })
+            .option('stdout', { type: 'boolean', describe: 'Write raw XML to stdout, including in a terminal' }),
           handler: wrap(async (argv, app) => {
+            if ([Boolean(argv.out), Boolean(argv.outDir), Boolean(argv.stdout)].filter(Boolean).length > 1) throw errUsage('Choose one of --out, --out-dir, or --stdout');
             app.requireInstance();
             const record = await resolveUpdateSetByName(app, argv.name);
             const sysID = getStringField(record, 'sys_id');
@@ -504,14 +510,16 @@ export function updateSetsCmd(wrap) {
             }
 
             const bytes = Buffer.byteLength(xml, 'utf-8');
-            if (argv.out) {
-              await fs.promises.writeFile(argv.out, xml);
+            const out = argv.out || (argv.outDir || (process.stdout.isTTY && !argv.stdout && !argv.json && argv.format !== 'json')
+              ? path.join(argv.outDir || '.', updateSetFilename(getStringField(record, 'name'))) : null);
+            if (out) {
+              await fs.promises.writeFile(out, xml, { flag: 'wx' });
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
-                out: argv.out,
+                out,
                 bytes,
-              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${argv.out}` });
+              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${out}` });
               return;
             }
 
@@ -519,7 +527,7 @@ export function updateSetsCmd(wrap) {
             // (`jsn updatesets export "X" > set.xml`). Only wrap in the JSON
             // envelope when the user explicitly asks for it — auto format
             // detection must NOT hijack the payload for piped consumers.
-            if (argv.json || argv.format === 'json') {
+            if (!argv.stdout && (argv.json || argv.format === 'json')) {
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
@@ -531,6 +539,47 @@ export function updateSetsCmd(wrap) {
             process.stdout.write(xml + (xml.endsWith('\n') ? '' : '\n'));
           }),
         })
+        .command({
+          command: 'import <file>',
+          describe: 'Load XML as a retrieved update set; never preview, commit, or select it automatically',
+          builder: y => y
+            .positional('file', { type: 'string', describe: 'Update set XML export' })
+            .option('dry-run', { type: 'boolean', describe: 'Inspect locally without any instance requests' })
+            .option('yes', { type: 'boolean', describe: 'Confirm loading the displayed XML into the selected target' }),
+          handler: wrap(async (argv, app) => {
+            const stat = await fs.promises.stat(argv.file);
+            if (!stat.isFile() || stat.size > MAX_UPDATE_SET_BYTES) throw errUsage('Expected an XML file no larger than 50 MiB');
+            const xml = await fs.promises.readFile(argv.file, 'utf8');
+            const inspection = inspectUpdateSetXML(xml);
+            const { members, ...summary } = inspection;
+            if (argv.dryRun) return app.ok({ ...summary, members, dry_run: true }, { summary: `XML: ${inspection.name}; ${inspection.count} updates (local inspection only)` });
+            app.requireInstance();
+            const question = `Load "${inspection.name}" (${inspection.count} updates) into ${app.getEffectiveInstance()} as a retrieved update set? This does not commit its changes.`;
+            if (!argv.yes) {
+              if (!canPrompt() || argv.json || argv.get || (argv.format && argv.format !== FormatAuto)) {
+                throw new AppError(CodeConfirmationRequired, `${question} — confirmation required. Pass --yes after approving this target.`,
+                  `Rerun: ${buildRerunCommand(argv, { rerun: ['updatesets', 'import', argv.file, '--yes'] })}`);
+              }
+              if (!await confirm({ message: question, default: false })) return;
+            }
+            const result = await app.sdk.importUpdateSet(xml, inspection, path.basename(argv.file));
+            app.ok({ ...summary, ...result, committed: false }, { summary: `Loaded retrieved update set "${inspection.name}" (${result.count} updates); not committed` });
+          }),
+        })
+        .command({
+          command: 'reopen <name>',
+          describe: 'Explicitly return a complete or ignored local update set to in progress; does not select it',
+          handler: wrap(async (argv, app) => {
+            const target = await resolveCompletionTarget(app, argv.name);
+            const record = await fetchUpdateSetById(app, target.sys_id);
+            const state = String(record?.state?.value ?? record?.state ?? '').toLowerCase();
+            if (!['complete', 'ignore'].includes(state)) throw errUsage(`Cannot reopen an update set in state "${state}"; expected complete or ignore`);
+            await app.sdk.update('sys_update_set', target.sys_id, { state: 'in progress' });
+            const mismatches = await verifyWriteBack(app, 'sys_update_set', target.sys_id, { state: 'in progress' });
+            if (mismatches.length) throw errAPI(200, 'Reopen could not be verified; inspect the update set before retrying');
+            app.ok({ update_set: target.name, sys_id: target.sys_id, state: 'in progress' }, { summary: `Reopened update set: ${target.name}` });
+          }),
+        })
         .command({
           command: 'set [name]',
           describe: 'Set the current update set (interactive picker with scope when run bare)',
@@ -738,6 +787,8 @@ export function updateSetsCmd(wrap) {
         console.log('  list           List update sets (shows scope)');
         console.log('  show <name>    Show an update set (type counts + risky items)');
         console.log('  export <name>  Export an update set to XML (stdout or --out)');
+        console.log('  import <file>  Load retrieved XML (--dry-run inspects locally; --yes confirms)');
+        console.log('  reopen <name>  Explicitly return a closed set to in progress');
         console.log('  set  [name]    Set the current update set (picker when run bare)');
         console.log('  create         Create a new update set (auto-sets as current)');
         console.log('  complete [name] Complete a named or current set with --notes (editor when omitted)');

package/src/mutations.js

@@ -8,7 +8,7 @@
 // create` (read-only bypass), and listed `restmethods`, a command that was
 // never registered. Derived data can't drift that way.
 
-import { mutationPaths } from './capabilities.js';
+import { mutationPaths, isLocalPreview } from './capabilities.js';
 
 /**
  * Back-compat export: the derived mutation path list, refreshed by
@@ -42,6 +42,7 @@ function currentPaths(paths) {
  * @returns {boolean}
  */
 export function isMutationCommand(argv, paths) {
+  if (isLocalPreview(argv)) return false;
   const cmd = argv._ || [];
   for (const pattern of currentPaths(paths)) {
     if (pattern.length > cmd.length) continue;

package/src/sdk.js

@@ -2,7 +2,7 @@
 
 import { batchRead } from './sdk-batch.js';
 import { gunzipSync } from 'node:zlib';
-import { CodeAuth, 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';
@@ -768,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 })) };
+}