@jacebenson/jsn 4.3.8-dev.47 → 4.3.8-dev.49

package/README.md

@@ -44,6 +44,96 @@ private files and offers a foreground console, not native service registration.
 See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
 lifecycle commands and the untested Windows host phases. Docker remains available.
 
+## Customization reports
+
+```sh
+jsn customizations capture --label before-upgrade --customer-scope x_acme_app
+jsn customizations list
+jsn customizations show <run_id>
+jsn customizations compare <baseline_id> <new_id> --json
+jsn customizations show <run_id> --get data.coverage
+```
+
+Capture data access uses Table API GET requests only. Captures never run
+background scripts or create, update or delete instance records. Standard
+authentication still applies, including OAuth refresh, local refreshed-credential
+storage and session/GCK bootstrap, which can make authentication POST requests.
+Expired credentials without a usable refresh token require login. Reports are private local JSON files in
+`$JSN_DATA_HOME/customizations`, defaulting to `~/.jsn/customizations`. List,
+show and compare work offline. Interactive terminals offer local report pickers;
+pass explicit IDs with JSON, pipes or `--get`.
+
+The bounded inventory joins visible `sys_metadata`, `sys_scope` and
+`sys_upgrade_history_log` records. `ootb_modifications` contains artifacts
+with historical skipped-upgrade evidence, not a verified current OOTB diff.
+Because the broad `sys_metadata` read is an arbitrary `sys_id`-ordered slice
+(994 of 621972 rows on a large instance), it is reported as a **bounded sample,
+not an inventory**: it only ever describes the rows the page budget reached.
+The skipped-upgrade artifacts are inventoried separately and completely for the
+observed history: after the filtered upgrade-history read, every observed
+`sys_update_name` is resolved with chunked GET-only
+`sys_update_nameIN<chunk of names>` lookups on `sys_metadata`, so an artifact
+with skipped-upgrade evidence appears in `ootb_modifications` even when it falls
+far outside the sample. `coverage.upgrade_evidence` reports the skipped rows
+observed, the distinct update names, how many resolved by direct lookup, the
+unresolved name list and any failed lookup chunks.
+`customer_app_artifacts` contains only scopes explicitly declared with repeatable
+`--customer-scope` values or sys_ids. The instance verifies the scope identity,
+not its ownership. Installed/vendor scopes are never automatically called
+customer-built. Other visible artifacts remain `unclassified`, and both those
+categories cover only what the bounded sample read.
+
+Each item reports identity, scope, evidence, unknown risk with rationale and a
+review recommendation. Historical OOTB findings include the known skipped-upgrade
+impact and explicit unknown baseline, runtime impact and dependencies. No
+reversion is performed or recommended as safe without further investigation.
+
+Defaults are 100 records per page and 10 pages per source. Adjust `--page-size`
+and `--max-pages` within the documented limits. Source coverage compares the rows
+fetched with the Stats API count for the same query and reports both. A page
+shorter than the requested size never implies exhaustion; `exhausted` is reported
+only when the fetched rows account for the available total, and an unavailable
+count is reported as unknown rather than implied completeness. Other statuses
+distinguish missing fields, unstable pagination and read failures. Both the count
+and the rows reflect visible ACL-filtered records, so hidden rows cannot be ruled
+out and reports remain `incomplete`. An empty category does not prove that no
+customizations exist. A 2xx table body without a `result` array is treated as an
+unavailable source, never as an empty table.
+
+Comparisons show newly observed, no-longer-observed and changed metadata/evidence.
+They ignore local capture IDs, labels, timestamps and enumeration order.
+They do not prove record creation/deletion or detect source-body changes without
+captured metadata changes. Changed entries render the concrete before/after field
+values, and additions/removals list the artifact's name, table, scope, category
+and evidence basis. When either report has an unavailable or empty source, the
+comparison status is `unreliable` and those differences are labelled as missing
+coverage instead of mass creation or deletion. Compare only reports from the same
+instance.
+
+Provider contract: [ServiceNow Customizations Unchanged](https://www.servicenow.com/docs/r/xanadu/platform-administration/customizations-unchanged-related-list.html)
+explains that the `Skipped` disposition preserves customizations. Other skip
+reasons are not treated as equivalent evidence. This command cannot establish a
+trusted baseline from that history alone.
+
+The verified provider join is `sys_upgrade_history_log.file_name` to
+`sys_metadata.sys_update_name`, not the log's nonexistent `name` field. Capture
+uses raw values from `sysparm_display_value=all`: disposition `4` or `104`
+means Skipped or Skipped (second pass). Resolution `reviewed_reverted` excludes
+that history row; a present empty resolution is distinct from a missing field.
+The upgrade-history read is filtered server-side to those dispositions so a
+bounded capture spends its pages on preserved-customization evidence instead of
+arbitrary history rows, and `unmatched_upgrade_records` counts only that filtered
+population, not all upgrade history. The filtered history is the unit of the
+inventory claim: every observed `file_name` is then resolved against visible
+`sys_metadata` with chunked GET-only `sys_update_nameIN<chunk>` lookups, so
+skipped artifacts are inventoried from the history instead of from the arbitrary
+`sys_id`-ordered metadata sample. `unmatched_upgrade_records` and
+`coverage.upgrade_evidence.unresolved_update_names` describe only names no
+visible metadata row matched; a failed lookup chunk is reported rather than
+treated as an absent artifact.
+These values were checked against the PDI dictionary, choices and actual joined
+rows. Display labels are not used for classification.
+
 ## Quick Start
 
 ```bash
@@ -344,6 +434,8 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **Automation** — `flows`, `actions`, `rules`, `scrapi`, `updatesets`, `eval`, `rest`
 
+**Upgrade review** — [`skipped-updates`](docs/skipped-updates.md) discovers existing unresolved skips, reviews current/base field changes and known dependencies, and processes only explicitly selected actions after an exact batch preview and one confirmation.
+
 **Access** — `acls`, `roles`, `scopes`, `properties`, `privileges`
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.8-dev.47",
+  "version": "4.3.8-dev.49",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/skills/servicenow/SKILL.md

@@ -73,6 +73,42 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 
+### Customization evidence
+
+```sh
+jsn customizations capture --label review --customer-scope x_acme_app --json
+jsn customizations list --json
+jsn customizations show <run_id> --get data.categories
+jsn customizations compare <baseline_id> <new_id> --json
+```
+
+Capture performs bounded GET-only table reads and saves local reports. It never
+evals or creates, updates or deletes instance records. Standard authentication
+may refresh OAuth tokens, store refreshed credentials locally and bootstrap a
+session/GCK using authentication POSTs. List/show/compare are offline.
+Declare customer ownership with repeatable `--customer-scope` values or sys_ids;
+never infer customer ownership from a non-global scope. The declaration is
+caller evidence, not independent publisher verification. OOTB findings reflect
+historical upgrade skips, not a current verified baseline deviation. The upgrade
+history is read server-side for the skip dispositions and every observed skipped
+`file_name` is resolved against `sys_metadata` by chunked
+`sys_update_nameIN<chunk>` lookups, so the OOTB inventory covers the observed
+skipped artifacts; the broad `sys_metadata` read is an arbitrary `sys_id`-ordered
+slice and is reported as a bounded sample, not an inventory, describing only the
+unclassified and declared-customer categories. Unresolved skipped names and
+failed lookup chunks stay explicit rather than becoming absent artifacts, and a
+resolved artifact can lack a scope name when its scope record was outside the
+bounded `sys_scope` read. Missing
+ACL access, pagination limits and unmatched evidence remain explicit. All
+reports are incomplete; no findings is not proof of no customizations.
+Comparisons cover captured metadata/evidence, not source payloads. Removals mean
+no longer observed, not proven deletion. Reversion impact and dependencies
+remain unknown until separately investigated. Never recommend automatic reversion.
+
+Upgrade history joins `file_name` to metadata `sys_update_name`. Raw disposition
+`4` or `104` is skipped-customization evidence; resolution `reviewed_reverted`
+excludes that history row. Use raw values, not display labels or other skip reasons.
+
 ### Complete an update set
 
 ```bash

package/src/cli.js

@@ -9,6 +9,7 @@ import { App } from './app.js';
 import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
+import { skippedUpdatesCmd } from './commands/skipped-updates.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
 import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
@@ -70,6 +71,7 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { customizationsCmd } from './commands/customizations.js';
 import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
@@ -405,7 +407,9 @@ export function buildCLI() {
     // DEVELOPER
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
+    .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
+    .command(customizationsCmd(wrap))
     .command(midserversCmd(wrap))
     .command(diffCmd(wrap))
     .command(graphqlCmd(wrap))

package/src/commands/customizations.js

@@ -0,0 +1,70 @@
+import { declareCapabilities } from '../capabilities.js';
+import { errUsageHint, errUsage } from '../errors.js';
+import { canUsePicker } from '../helpers.js';
+import { paginatedSearch } from '../paginated-search.js';
+import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
+
+// Only capture needs an instance. Saved reports never need network access.
+declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
+const listHint = { action: 'list', cmd: 'jsn customizations list', description: 'Browse saved customization captures' };
+const showHint = id => ({ action: 'show', cmd: `jsn customizations show ${id}`, description: 'Review this saved capture' });
+const compareHint = id => ({ action: 'compare', cmd: `jsn customizations compare ${id} OTHER_RUN_ID`, description: 'Compare captured metadata and evidence' });
+function requireReport(id) {
+  const report = getReport(id);
+  if (!report) throw errUsageHint(`Unknown customization report: ${id}`, 'Run `jsn customizations list` to find saved captures.');
+  return report;
+}
+async function pickReport(app, argv, exclude = null, message = 'Select a customization capture') {
+  if (!canUsePicker(app, argv)) throw errUsageHint('A report ID is required when prompts are unavailable.', 'Run `jsn customizations list`, then pass the run ID explicitly.');
+  const runs = listReports({ limit: 1000 }).filter(run => run.run_id !== exclude);
+  if (!runs.length) throw errUsage('No saved customization captures available');
+  const picked = await paginatedSearch({ message, totalCount: runs.length, pageSize: 10, source: async (term = '') => runs.filter(run => `${run.run_id} ${run.label} ${run.instance}`.toLowerCase().includes(term.toLowerCase())).map(run => ({ name: `${run.run_id} ${run.label || '(unlabeled)'} ${run.instance}`, value: run })) });
+  return picked?.value ? requireReport(picked.value.run_id) : null;
+}
+function show(app, report) {
+  app.ok({ ...report, _formatted: formatReport(report) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+}
+export function customizationsCmd(wrap) {
+  return {
+    command: 'customizations [subcommand]',
+    describe: 'Capture and compare read-only customization evidence locally',
+    builder: y => y
+      .command({ command: 'capture', describe: 'Capture bounded read-only metadata and historical upgrade evidence',
+        builder: b => b.option('label', { type: 'string', describe: 'Label for this capture' })
+          .option('customer-scope', { type: 'string', array: true, default: [], describe: 'Declared customer-owned scope value or sys_id, repeatable; ownership is not inferred' })
+          .option('page-size', { type: 'number', default: 100, describe: 'Records per table page, 1..1000' })
+          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' }),
+        handler: wrap(async (argv, app) => {
+          app.requireInstance();
+          if (!Number.isInteger(argv.pageSize) || argv.pageSize < 1 || argv.pageSize > 1000 || !Number.isInteger(argv.maxPages) || argv.maxPages < 1 || argv.maxPages > 100) throw errUsage('page-size must be 1..1000 and max-pages 1..100');
+          const customerScopes = Array.isArray(argv.customerScope) ? argv.customerScope : argv.customerScope ? [argv.customerScope] : [];
+          const report = await captureReport({ sdk: app.sdk, instance: app.getEffectiveInstance(), profile: app.session?.profileName || '', label: argv.label || '', customerScopes, pageSize: argv.pageSize, maxPages: argv.maxPages });
+          show(app, report);
+        }),
+      })
+      .command({ command: 'list', aliases: ['ls'], describe: 'List saved local captures',
+        builder: b => b.option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Maximum captures to list' }),
+        handler: wrap(async (argv, app) => {
+          if (canUsePicker(app, argv)) { const report = await pickReport(app, argv); if (report) show(app, report); return; }
+          const runs = listReports({ limit: argv.limit });
+          app.ok({ runs, count: runs.length, _formatted: formatReportList(runs) }, { summary: `${runs.length} customization capture(s)`, breadcrumbs: [listHint, ...(runs[0] ? [showHint(runs[0].run_id)] : [])] });
+        }),
+      })
+      .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', handler: wrap(async (argv, app) => {
+        const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
+        if (report) show(app, report);
+      }) })
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
+        if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
+        if (argv.baseline && argv.baseline === argv.new) throw errUsage('Compare requires two different report IDs');
+        const baseline = argv.baseline ? requireReport(argv.baseline) : await pickReport(app, argv, null, 'Select the baseline capture');
+        if (!baseline) return;
+        const newer = argv.new ? requireReport(argv.new) : await pickReport(app, argv, baseline.run_id, 'Select the new capture');
+        if (!newer) return;
+        if (baseline.instance !== newer.instance) throw errUsage('Customization reports must describe the same instance');
+        const result = compareReports(baseline, newer);
+        app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
+      }) }),
+    handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
+  };
+}

package/src/commands/skipped-updates.js

@@ -0,0 +1,102 @@
+import { checkbox, select, confirm } from '@inquirer/prompts';
+import { canUsePicker, interactiveList, getStringField } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+import { errUsage } from '../errors.js';
+import { discoverSkippedUpdates, reviewSkippedUpdate, prepareSkippedBatch, processSkippedBatch, raw, SKIP_TABLE } from '../skipped-updates.js';
+
+const label = row => `${raw(row.sys_id)}  ${getStringField(row, 'target_name') || getStringField(row, 'file_name')}`;
+const selectionOptions = y => y
+  .option('ids', { type: 'string', describe: 'Comma-separated literal finding sys_ids, maximum 100' })
+  .option('action', { type: 'string', choices: ['retain', 'revert'], describe: 'Explicit selected action, never inferred from recommendations' });
+
+export function renderSkippedPreview(preview) {
+  const lines = [`Instance: ${preview.instance}`, `Exact selected batch: ${preview.count} finding(s)`];
+  for (const item of preview.selected) {
+    lines.push(`\n${item.sys_id}: ${item.artifact.update_name}`, `Action: ${item.action}`, item.operation,
+      `Recommendation only: ${item.impact.recommendation.action}. ${item.impact.recommendation.basis}`,
+      `State: disposition=${item.finding.disposition}, resolution=${item.finding.resolution_status}`,
+      `Evidence: base version ${item.impact.evidence.baseline_version || 'unknown'}, source ${item.impact.evidence.baseline_source_table || 'unknown'}/${item.impact.evidence.baseline_source || 'unknown'}`,
+      `Finding: ${preview.instance}/${SKIP_TABLE}.do?sys_id=${item.sys_id}`,
+      item.impact.direct_behavior.summary);
+    for (const change of item.impact.changes) lines.push(`  ${change.field}: ${JSON.stringify(change.current)} -> ${JSON.stringify(change.base)}`, `  ${change.effect}`);
+    for (const dep of item.impact.known_dependencies) lines.push(`  Known dependency: ${dep.table}.${dep.field} / ${dep.sys_id}`);
+    for (const gap of item.impact.unknown) lines.push(`  Unknown: ${gap}`);
+  }
+  lines.push(`\nConfirmation token: ${preview.confirmation_token}`, 'No writes have been performed.');
+  return lines.join('\n');
+}
+
+export function skippedUpdatesCmd(wrap, ui = {}) {
+  declareCapabilities('skipped-updates', { mutationSubcommands: ['process'] });
+  const prompts = { checkbox, select, confirm, canUsePicker, interactiveList, ...ui };
+  async function showReview(app, id) {
+    const review = await reviewSkippedUpdate(app.sdk, id);
+    const display = { instance: app.getEffectiveInstance(), selected: [{ ...review, action: 'none', operation: 'Read-only review.' }], count: 1, confirmation_token: 'not applicable' };
+    app.ok({ ...review, _formatted: renderSkippedPreview(display) }, { summary: 'Skipped update review; deeper effects remain unknown' });
+  }
+  async function selection(argv, app, guided) {
+    let ids = typeof argv.ids === 'string' ? argv.ids.split(',') : undefined;
+    let action = argv.action;
+    if (!ids && guided) {
+      const page = await discoverSkippedUpdates(app.sdk, { limit: 100, offset: 0 });
+      if (!page.count) throw errUsage('No unresolved skipped findings were returned.');
+      ids = await prompts.checkbox({ message: `Select findings from this page${page.has_more ? ' (more exist; use list --offset for others)' : ''}`,
+        choices: page.findings.map(row => ({ name: label(row), value: raw(row.sys_id) })), required: true });
+    }
+    if (!ids?.length) throw errUsage('Provide --ids with the exact selected finding sys_ids.');
+    if (!action && guided) action = await prompts.select({ message: 'Choose the action for these findings',
+      choices: [{ name: 'Retain customization, mark reviewed and retained', value: 'retain' },
+        { name: 'Return to base system, discard customization', value: 'revert' }] });
+    return { ids, action, instance: app.getEffectiveInstance() };
+  }
+  return { command: 'skipped-updates', describe: 'Review and process existing unresolved skipped updates across all upgrade history',
+    builder: y => y
+      .command({ command: 'list', describe: 'Discover unresolved skips instance-wide, independent of new upgrades',
+        builder: y => y.option('limit', { type: 'number', default: 100, describe: 'Page size, maximum 500' })
+          .option('offset', { type: 'number', default: 0, describe: 'Page offset' }),
+        handler: wrap(async (argv, app) => {
+          app.requireInstance();
+          if (prompts.canUsePicker(app, argv)) {
+            const selected = await prompts.interactiveList({ app, table: SKIP_TABLE, singular: 'skipped update',
+              columns: ['target_name', 'file_name', 'disposition', 'resolution_status'], labelField: 'target_name',
+              query: 'dispositionIN4,104,9,10,11^resolution_statusIN,not_reviewed', formatLabel: label });
+            if (selected === undefined) return;
+            if (selected) { await showReview(app, raw(selected.sys_id)); return; }
+          }
+          const page = await discoverSkippedUpdates(app.sdk, argv);
+          app.ok(page, { summary: `${page.count} unresolved finding(s) fetched${page.has_more ? '; more available' : ''}. Instance-wide total is not measured.` });
+        }) })
+      .command({ command: 'review <sys-id>', describe: 'Review artifact evidence, field changes and bounded known dependencies',
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          await showReview(app, argv['sys-id']);
+        }) })
+      .command({ command: 'preview', describe: 'Read-only exact batch preview and confirmation token', builder: selectionOptions,
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          const options = await selection(argv, app, prompts.canUsePicker(app, argv));
+          const preview = await prepareSkippedBatch(app.sdk, options);
+          app.ok({ ...preview, _formatted: renderSkippedPreview(preview) }, { summary: 'Read-only batch preview; review before confirming' });
+        }) })
+      .command({ command: 'process', describe: 'Apply selected action after ONE explicit confirmation of the exact preview',
+        builder: y => selectionOptions(y).option('confirm', { type: 'string', describe: 'Confirmation token from a previously reviewed exact preview; required in automation' }),
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          try {
+            const guided = prompts.canUsePicker(app, argv);
+            const options = await selection(argv, app, guided);
+            const result = await processSkippedBatch({ sdk: app.sdk, ...options,
+              readOnly: app.session?.readOnly === true, confirmationToken: argv.confirm,
+              onPreview: guided ? async preview => app.ok({ ...preview, _formatted: renderSkippedPreview(preview) }, { summary: 'Review exact batch before confirmation' }) : undefined,
+              confirm: guided && !argv.confirm ? async () => prompts.confirm({ message: 'Apply exactly this selected batch?', default: false }) : undefined });
+            app.ok({ ...result, _formatted: result.cancelled ? 'Cancelled. No writes performed.'
+              : result.results.map(row => `${row.sys_id} ${row.action}: ${row.success ? 'verified success' : `FAILED (${row.effect})`}`).join('\n') },
+            { summary: `${result.success_count} succeeded; ${result.failure_count} failed${result.partial ? '; partial batch' : ''}` });
+            if (result.failure_count) process.exitCode = 1;
+          } catch (err) {
+            if (err.name === 'ExitPromptError' || err.name === 'AbortPromptError') {
+              app.ok({ cancelled: true, writes_performed: false }, { summary: 'Cancelled. No writes performed.' }); return;
+            }
+            throw err;
+          }
+        }) })
+      .demandCommand(1, 'Choose list, review, preview or process'),
+  };
+}

package/src/customizations.js

@@ -0,0 +1,463 @@
+// Read-only metadata inventory. Upgrade skips are historical evidence, not a
+// current baseline diff. Scope ownership must be declared, never inferred.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { getVersion } from './commands/version.js';
+
+// Raw provider choices: 4 = Skipped, 104 = Skipped (second pass). Other skip
+// dispositions do not establish a preserved customization, so the upgrade
+// history read is filtered server-side and a bounded budget spends its pages
+// on preserved-customization evidence instead of arbitrary history rows.
+export const SKIP_DISPOSITIONS = ['4', '104'];
+const SKIP_QUERY = `dispositionIN${SKIP_DISPOSITIONS.join(',')}`;
+const SOURCES = {
+  sys_scope: { fields: 'sys_id,name,scope,sys_class_name', query: 'ORDERBYsys_id', countQuery: '', kind: 'inventory read' },
+  sys_metadata: { fields: 'sys_id,sys_name,sys_class_name,sys_scope,sys_update_name,sys_updated_on', query: 'ORDERBYsys_id', countQuery: '', kind: 'bounded sample' },
+  sys_upgrade_history_log: { fields: 'sys_id,file_name,disposition,resolution_status,sys_updated_on', query: `${SKIP_QUERY}^ORDERBYsys_id`, countQuery: SKIP_QUERY, kind: 'inventory read' },
+};
+// The broad sys_metadata read is an arbitrary sys_id-ordered slice of a table
+// that can hold hundreds of thousands of rows, so it can only ever be a bounded
+// sample of the instance. Skipped-upgrade artifacts are therefore resolved
+// directly by the update names the filtered history read observed, so every
+// skipped artifact visible on the instance reaches the inventory.
+export const RESOLUTION_SOURCE = 'sys_metadata_name_resolution';
+export const RESOLUTION_CHUNK_SIZE = 25;
+const RESOLUTION_MAX_PAGES = 3;
+const value = v => v && typeof v === 'object' ? v.value ?? '' : v ?? '';
+const text = v => String(value(v));
+
+// How many rows are available for the same query? The Stats API count is the
+// only evidence that lets a capture claim completeness; without it coverage
+// must stay unknown rather than implied by a page that happened to end.
+async function availableCount(sdk, table, countQuery, fetched) {
+  if (typeof sdk.aggregateCount !== 'function') return null;
+  let count;
+  try {
+    count = await sdk.aggregateCount(table, countQuery);
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(count) || count < 0) return null;
+  // A zero count with rows in hand means the count is unusable, not that the
+  // table is empty.
+  if (count === 0 && fetched > 0) return null;
+  return Math.floor(count);
+}
+
+// A per-query count with no zero/short-page guessing: a count of 0 for a name
+// chunk means no visible row matched that chunk, which is real evidence.
+async function statsCount(sdk, table, query) {
+  if (typeof sdk.aggregateCount !== 'function') return null;
+  try {
+    const count = await sdk.aggregateCount(table, query);
+    return Number.isFinite(count) && count >= 0 ? Math.floor(count) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readSource(sdk, table, { fields, query, countQuery, kind }, pageSize, maxPages) {
+  const rows = [];
+  const seen = new Set();
+  const coverage = {
+    status: 'limited', fetched: 0, available: null, pages: 0, duplicate_rows: 0, missing_identity: 0,
+    query, ...(kind ? { kind } : {}), reason: 'Page limit reached; remaining records unknown.',
+  };
+  // The strict seam rejects a 2xx body without a result array, so a malformed
+  // envelope becomes an unavailable source instead of an empty inventory.
+  const listFn = typeof sdk.listStrict === 'function' ? sdk.listStrict.bind(sdk) : sdk.list.bind(sdk);
+  let failure = '';
+  try {
+    for (let page = 0; page < maxPages; page++) {
+      const batch = await listFn(table, {
+        sysparm_fields: fields, sysparm_query: query,
+        sysparm_display_value: 'all', sysparm_exclude_reference_link: 'true',
+        sysparm_limit: String(pageSize), sysparm_offset: String(page * pageSize),
+      }, { readOnly: true });
+      coverage.pages++;
+      if (!Array.isArray(batch)) throw new Error('Invalid table response');
+      for (const row of batch) {
+        const id = text(row.sys_id);
+        if (!id) { coverage.missing_identity++; continue; }
+        if (seen.has(id)) { coverage.duplicate_rows++; continue; }
+        seen.add(id);
+        rows.push(row);
+        const required = table === 'sys_metadata' ? ['sys_class_name', 'sys_scope', 'sys_update_name'] : table === 'sys_scope' ? ['scope'] : ['file_name', 'disposition', 'resolution_status'];
+        if (required.some(field => !Object.hasOwn(row, field))) coverage.missing_identity++;
+      }
+      coverage.fetched = rows.length;
+      // A short page is not exhaustion: ServiceNow returns short offset pages
+      // on large tables. Keep reading within the page budget.
+      if (batch.length === 0) break;
+    }
+  } catch (error) {
+    failure = String(error?.message || error);
+  }
+  if (failure) {
+    coverage.status = /401|403|permission|forbidden|access denied/i.test(failure) ? 'permission_denied' : 'unavailable';
+    coverage.reason = 'Table read failed; partial results retained. Authentication, ACLs, table availability or network access may limit coverage.';
+    return { rows, coverage };
+  }
+  coverage.available = await availableCount(sdk, table, countQuery, rows.length);
+  const duplicateNote = coverage.duplicate_rows
+    ? ` Pagination returned ${coverage.duplicate_rows} repeated identit${coverage.duplicate_rows === 1 ? 'y' : 'ies'}; offset paging on large tables can overlap or skip.`
+    : '';
+  if (coverage.missing_identity) {
+    coverage.status = 'missing_fields';
+    coverage.reason = 'Some records omitted identity or classification fields; field ACLs or malformed responses may hide evidence.';
+  } else if (coverage.available !== null && coverage.fetched >= coverage.available) {
+    coverage.status = 'exhausted';
+    coverage.reason = `Read all ${coverage.available} rows the Stats API reports for this query. Both the count and the rows reflect visible ACL-filtered records.`;
+  } else if (coverage.available !== null) {
+    coverage.status = 'limited';
+    coverage.reason = `Read ${coverage.fetched} of ${coverage.available} rows the Stats API reports for this query; ${coverage.available - coverage.fetched} row(s) were not read within the page budget.`;
+  } else if (coverage.duplicate_rows) {
+    coverage.status = 'unstable';
+    coverage.reason = 'Repeated identities across pages; pagination may be ignored or records changed during capture. The Stats API count for this query was unavailable, so completeness is unknown.';
+  } else {
+    coverage.status = 'limited';
+    coverage.reason = 'The Stats API count for this query was unavailable, so visible-result completeness cannot be claimed.';
+  }
+  coverage.reason += duplicateNote;
+  return { rows, coverage };
+}
+
+// Resolve observed skipped-upgrade update names against visible sys_metadata
+// with chunked GET-only `sys_update_nameIN<chunk>` queries. The broad sample
+// cannot be relied on for this: it is an arbitrary sys_id-ordered slice, so an
+// inventory claim needs the artifacts the history read actually named.
+// Read failures are reported per chunk instead of being hidden behind the
+// sample, and completeness stays anchored to the Stats API count for the exact
+// name queries used, never to a page that happened to end.
+async function resolveUpdateNames(sdk, names) {
+  const requested = [...new Set(names)].sort();
+  const rows = [];
+  const seen = new Set();
+  const resolved = new Set();
+  const coverage = {
+    kind: 'targeted name resolution', status: 'limited', fetched: 0, available: null, pages: 0, chunks: 0,
+    query: 'sys_update_nameIN<observed skipped update names>', requested_names: requested.length,
+    resolved_names: 0, unresolved_names: 0, failed_chunks: 0, reason: '',
+  };
+  if (!requested.length) {
+    coverage.query = '';
+    coverage.reason = 'No skipped upgrade rows were observed, so no update names required resolution.';
+    return { rows, resolved, coverage };
+  }
+  const listFn = typeof sdk.listStrict === 'function' ? sdk.listStrict.bind(sdk) : sdk.list.bind(sdk);
+  const failures = [];
+  let countSum = 0;
+  let countKnown = true;
+  for (let start = 0; start < requested.length; start += RESOLUTION_CHUNK_SIZE) {
+    const chunk = requested.slice(start, start + RESOLUTION_CHUNK_SIZE);
+    const limit = Math.max(chunk.length, 1);
+    const query = `sys_update_nameIN${chunk.join(',')}`;
+    coverage.chunks++;
+    try {
+      for (let page = 0; page < RESOLUTION_MAX_PAGES; page++) {
+        const batch = await listFn('sys_metadata', {
+          sysparm_fields: SOURCES.sys_metadata.fields, sysparm_query: `${query}^ORDERBYsys_id`,
+          sysparm_display_value: 'all', sysparm_exclude_reference_link: 'true',
+          sysparm_limit: String(limit), sysparm_offset: String(page * limit),
+        }, { readOnly: true });
+        coverage.pages++;
+        if (!Array.isArray(batch)) throw new Error('Invalid table response');
+        for (const row of batch) {
+          const updateName = text(row.sys_update_name);
+          if (updateName && chunk.includes(updateName)) resolved.add(updateName);
+          const id = text(row.sys_id);
+          if (!id || seen.has(id)) continue;
+          seen.add(id);
+          rows.push(row);
+        }
+        coverage.fetched = rows.length;
+        if (batch.length === 0) break;
+      }
+    } catch (error) {
+      failures.push(String(error?.message || error));
+    }
+    const counted = await statsCount(sdk, 'sys_metadata', query);
+    if (counted === null) countKnown = false;
+    else countSum += counted;
+  }
+  coverage.available = countKnown ? countSum : null;
+  coverage.resolved_names = resolved.size;
+  coverage.unresolved_names = requested.length - resolved.size;
+  if (failures.length) {
+    coverage.status = failures.some(message => /401|403|permission|forbidden|access denied/i.test(message)) ? 'permission_denied' : 'unavailable';
+    coverage.failed_chunks = failures.length;
+    coverage.reason = `${failures.length} of ${coverage.chunks} update-name lookup chunk(s) failed; rows resolved by the remaining chunks were retained, but some observed skipped artifacts may be missing from this inventory. ACL visibility or a read error may limit this source.`;
+  } else if (coverage.available !== null && coverage.fetched >= coverage.available) {
+    coverage.status = 'exhausted';
+    coverage.reason = `Resolved ${coverage.resolved_names} of ${requested.length} observed skipped update names in ${coverage.chunks} chunk(s) and read all ${coverage.available} row(s) the Stats API reports for those name queries.`;
+  } else if (coverage.available !== null) {
+    coverage.status = 'limited';
+    coverage.reason = `Resolved ${coverage.resolved_names} of ${requested.length} observed skipped update names and read ${coverage.fetched} of ${coverage.available} row(s) the Stats API reports for those name queries; the per-chunk page budget was reached.`;
+  } else {
+    coverage.status = 'limited';
+    coverage.reason = `Resolved ${coverage.resolved_names} of ${requested.length} observed skipped update names; the Stats API count for those name queries was unavailable, so lookup completeness cannot be claimed.`;
+  }
+  return { rows, resolved, coverage };
+}
+
+export const CUSTOMIZATION_SCHEMA_VERSION = 1;
+export function getCustomizationsDir() {
+  return path.join(process.env.JSN_DATA_HOME || path.join(os.homedir(), '.jsn'), 'customizations');
+}
+
+function reportFile(id, dir) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(String(id))) throw new Error('Invalid customization report ID');
+  return path.join(dir, `${id}.json`);
+}
+function validateReport(report) {
+  if (report?.capture_schema_version !== CUSTOMIZATION_SCHEMA_VERSION || !report.instance || !report.categories || !report.coverage) throw new Error('Unsupported or invalid customization report schema');
+  for (const category of ['ootb_modifications', 'customer_app_artifacts', 'unclassified']) {
+    if (!Array.isArray(report.categories[category])) throw new Error('Invalid customization report categories');
+  }
+  return report;
+}
+
+export async function captureReport({ sdk, instance, profile = '', label = '', customerScopes = [], pageSize = 100, maxPages = 10, dir = getCustomizationsDir() }) {
+  if (!instance) throw new Error('An authenticated instance is required for customization capture');
+  const start_time = new Date().toISOString();
+  const capture = await captureCustomizations({ sdk, customerScopes, pageSize, maxPages });
+  const report = { run_id: crypto.randomUUID(), instance, profile, label, start_time, finish_time: new Date().toISOString(), jsn_version: getVersion(), capture_schema_version: CUSTOMIZATION_SCHEMA_VERSION, command_options: { customerScopes, pageSize, maxPages }, ...capture };
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(reportFile(report.run_id, dir), JSON.stringify(report, null, 2), { mode: 0o600, flag: 'wx' });
+  return report;
+}
+
+export function getReport(id, { dir = getCustomizationsDir() } = {}) {
+  try { return validateReport(JSON.parse(fs.readFileSync(reportFile(id, dir), 'utf8'))); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export function listReports({ limit = 50, dir = getCustomizationsDir() } = {}) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => name.endsWith('.json')).map(name => {
+    const report = getReport(name.slice(0, -5), { dir });
+    return { run_id: report.run_id, instance: report.instance, profile: report.profile, label: report.label, start_time: report.start_time, status: report.status };
+  }).sort((a, b) => b.start_time.localeCompare(a.start_time) || a.run_id.localeCompare(b.run_id)).slice(0, Math.max(1, Math.min(1000, Number(limit) || 50)));
+}
+
+// Object key order and evidence enumeration order are not artifact changes.
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+function inventory(report) {
+  return new Map(Object.entries(report.categories).flatMap(([category, items]) => items.map(item => [`${item.identity.table}:${item.identity.sys_id}`, { category, ...item }])));
+}
+
+// Sources that cannot be read are not empty sources. A comparison built on top
+// of one must say so instead of presenting missing coverage as real removals.
+function impairedSources(coverage) {
+  const sources = coverage?.sources || {};
+  return Object.entries(sources).filter(([, source]) => {
+    if (source.status === 'unavailable' || source.status === 'permission_denied') return true;
+    return source.fetched === 0 && source.available === null;
+  }).map(([table, source]) => `${table} (${source.status})`);
+}
+
+export function compareReports(baseline, newer) {
+  validateReport(baseline); validateReport(newer);
+  if (baseline.instance !== newer.instance) throw new Error('Customization reports must describe the same instance');
+  const a = inventory(baseline), b = inventory(newer);
+  const additions = [], removals = [], changes = [];
+  for (const id of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+    if (!a.has(id)) additions.push({ id, availability: 'not_observed_in_baseline', item: b.get(id) });
+    else if (!b.has(id)) removals.push({ id, availability: 'not_observed_in_new', item: a.get(id) });
+    else if (JSON.stringify(canonical(a.get(id))) !== JSON.stringify(canonical(b.get(id)))) changes.push({ id, baseline: a.get(id), new: b.get(id) });
+  }
+  const impaired = { baseline: impairedSources(baseline.coverage), new: impairedSources(newer.coverage) };
+  const unreliable = impaired.baseline.length > 0 || impaired.new.length > 0;
+  const unknowns = ['Additions/removals mean newly observed/no longer observed, not proven creation/deletion. ACLs, limits and concurrent changes can affect visibility.', 'Only captured metadata and evidence are compared, not full artifact content or OOTB baselines.', 'Ownership declarations, scope visibility and evidence coverage can cause category changes without an artifact change.'];
+  if (unreliable) unknowns.push(`Unavailable or empty sources make observed additions/removals unreliable: baseline [${impaired.baseline.join(', ') || 'none'}], new [${impaired.new.join(', ') || 'none'}]. They may reflect missing coverage rather than a real change and must not be read as mass creation or deletion.`);
+  return { baseline_run_id: baseline.run_id, new_run_id: newer.run_id, instance: baseline.instance, status: unreliable ? 'unreliable' : 'incomplete', additions, removals, changes,
+    impaired_sources: impaired,
+    coverage: { baseline: baseline.coverage, new: newer.coverage },
+    unknowns };
+}
+
+export function formatReport(report) {
+  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE'];
+  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
+  for (const limitation of report.coverage.limitations) lines.push(`Unknown: ${limitation}`);
+  if (report.coverage.unmatched_customer_scopes.length) lines.push(`Unmatched customer declarations: ${report.coverage.unmatched_customer_scopes.join(', ')}`);
+  const upgrade = report.coverage.upgrade_evidence;
+  if (upgrade) {
+    lines.push(`Observed skipped upgrade rows: ${upgrade.skipped_rows_observed}; distinct update names: ${upgrade.update_names_observed}; resolved by direct name lookup: ${upgrade.resolved_by_lookup}; unresolved: ${upgrade.unresolved_update_names.length}${upgrade.lookup_failures ? `; failed lookup chunks: ${upgrade.lookup_failures}` : ''}`);
+    if (upgrade.unresolved_update_names.length) lines.push(`Unresolved skipped update names (not visible in sys_metadata): ${upgrade.unresolved_update_names.slice(0, 20).join(', ')}${upgrade.unresolved_update_names.length > 20 ? `, ... and ${upgrade.unresolved_update_names.length - 20} more` : ''}`);
+  }
+  lines.push(`Unmatched upgrade history records: ${report.coverage.unmatched_upgrade_records}`);
+  for (const [category, items] of Object.entries(report.categories)) {
+    lines.push('', `${category.toUpperCase()} (${items.length})`);
+    for (const item of items) {
+      lines.push(`${item.identity.table}:${item.identity.sys_id} ${item.identity.name}`, `  Scope: ${item.scope.scope || item.scope.sys_id || 'unknown'}`, `  Risk: ${item.risk.rating}. ${item.risk.rationale}`);
+      for (const evidence of item.evidence) lines.push(`  Evidence: ${evidence.source}:${evidence.sys_id}. ${evidence.basis}`);
+      if (item.reversion) {
+        for (const impact of item.reversion.known_impact) lines.push(`  Known impact: ${impact}`);
+        lines.push(`  Known dependencies: ${item.reversion.known_dependencies.join(', ') || 'not established'}`);
+        for (const unknown of item.reversion.unknowns) lines.push(`  Reversion unknown: ${unknown}`);
+      }
+      for (const unknown of item.unknowns) lines.push(`  Unknown: ${unknown}`);
+      lines.push(`  Recommendation: ${item.recommendation}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+export function formatReportList(runs) {
+  return ['RUN ID  STATUS  LABEL  INSTANCE', ...runs.map(run => `${run.run_id}  ${run.status}  ${run.label || '(unlabeled)'}  ${run.instance}`), ...(runs.length ? [] : ['(no customization captures)'])].join('\n') + '\n';
+}
+
+// Flatten a captured item into comparable leaf fields so a comparison can show
+// what actually changed instead of only asserting that something did.
+function flattenFields(source, prefix = '', out = {}) {
+  const current = prefix || 'value';
+  if (source === null || source === undefined) { out[current] = ''; return out; }
+  if (Array.isArray(source)) {
+    if (!source.length) { out[current] = '(none)'; return out; }
+    source.forEach((entry, index) => flattenFields(entry, `${prefix}[${index}]`, out));
+    return out;
+  }
+  if (typeof source === 'object') {
+    const keys = Object.keys(source).sort();
+    if (!keys.length) { out[current] = '(none)'; return out; }
+    for (const key of keys) flattenFields(source[key], prefix ? `${prefix}.${key}` : key, out);
+    return out;
+  }
+  out[current] = String(source);
+  return out;
+}
+function fieldChanges(before, after) {
+  const a = flattenFields(canonical(before));
+  const b = flattenFields(canonical(after));
+  return [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()
+    .filter(field => a[field] !== b[field])
+    .map(field => ({ field, before: Object.hasOwn(a, field) ? a[field] : '(absent)', after: Object.hasOwn(b, field) ? b[field] : '(absent)' }));
+}
+function describeComparedItem(item) {
+  const identity = item?.identity || {};
+  const scope = item?.scope || {};
+  return [
+    `Artifact: ${identity.table || 'unknown'}:${identity.sys_id || 'unknown'} "${identity.name || identity.update_name || 'unnamed'}"`,
+    `Category: ${item?.category || 'unknown'}`,
+    `Scope: ${scope.scope || scope.sys_id || 'unknown'}${scope.name ? ` (${scope.name})` : ''}`,
+    `Evidence: ${(item?.evidence || []).map(evidence => `${evidence.source}:${evidence.sys_id}`).join(', ') || 'none captured'}`,
+    `Risk: ${item?.risk?.rating || 'unknown'}`,
+    `Recommendation: ${item?.recommendation || 'not recorded'}`,
+  ];
+}
+
+export function formatReportComparison(result) {
+  const lines = [`Customization comparison: ${result.status}`, `Baseline: ${result.baseline_run_id}`, `New: ${result.new_run_id}`, ...result.unknowns];
+  const impaired = result.impaired_sources || { baseline: [], new: [] };
+  if (impaired.baseline.length) lines.push(`Unreliable baseline sources: ${impaired.baseline.join(', ')}`);
+  if (impaired.new.length) lines.push(`Unreliable new sources: ${impaired.new.join(', ')}`);
+  for (const kind of ['additions', 'removals', 'changes']) {
+    lines.push('', `${kind.toUpperCase()} (${result[kind].length})`);
+    for (const entry of result[kind]) {
+      if (kind === 'changes') {
+        lines.push(`${entry.id}: ${entry.availability || 'captured metadata/evidence changed'}`);
+        const fields = fieldChanges(entry.baseline, entry.new);
+        for (const field of fields) lines.push(`  ${field.field}: "${field.before}" -> "${field.after}"`);
+        if (!fields.length) lines.push('  No compared field differs; evidence ordering or another unrendered value changed.');
+      } else {
+        lines.push(`${entry.id}: ${entry.availability}`);
+        for (const detail of describeComparedItem(entry.item)) lines.push(`  ${detail}`);
+      }
+    }
+  }
+  for (const side of ['baseline', 'new']) for (const [table, source] of Object.entries(result.coverage[side].sources)) lines.push(`${side} ${table}${source.kind ? ` [${source.kind}]` : ''}: ${source.status}, ${source.fetched} fetched of ${source.available === null || source.available === undefined ? 'unknown' : source.available} available. ${source.reason}`);
+  return lines.join('\n') + '\n';
+}
+
+export async function captureCustomizations({ sdk, customerScopes = [], pageSize = 100, maxPages = 10 }) {
+  if (!sdk) throw new Error('An authenticated SDK is required');
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 1000 || !Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100) throw new Error('pageSize must be 1..1000 and maxPages 1..100');
+  const sources = {};
+  const data = {};
+  for (const [table, source] of Object.entries(SOURCES)) {
+    const result = await readSource(sdk, table, source, pageSize, maxPages);
+    sources[table] = result.coverage;
+    data[table] = result.rows;
+  }
+  // The broad sys_metadata read is a bounded sample, so the artifacts the
+  // filtered history read actually named are looked up directly. The source is
+  // only registered when there is something to resolve, so a report with no
+  // skipped rows has no phantom empty source.
+  const observedNames = data.sys_upgrade_history_log.map(row => text(row.file_name)).filter(Boolean);
+  const resolution = await resolveUpdateNames(sdk, observedNames);
+  if (observedNames.length) {
+    sources[RESOLUTION_SOURCE] = resolution.coverage;
+    const sampled = new Set(data.sys_metadata.map(row => text(row.sys_id)));
+    data.sys_metadata = [...data.sys_metadata, ...resolution.rows.filter(row => !sampled.has(text(row.sys_id)))];
+  }
+  const scopes = new Map(data.sys_scope.map(row => [text(row.sys_id), row]));
+  const declared = new Set(customerScopes);
+  const logs = new Map();
+  for (const row of data.sys_upgrade_history_log) {
+    const name = text(row.file_name);
+    if (!logs.has(name)) logs.set(name, []);
+    logs.get(name).push(row);
+  }
+  const categories = { ootb_modifications: [], customer_app_artifacts: [], unclassified: [] };
+  for (const row of data.sys_metadata) {
+    const scopeId = text(row.sys_scope);
+    const scope = scopes.get(scopeId);
+    const scopeName = text(scope?.scope);
+    const identity = { sys_id: text(row.sys_id), table: text(row.sys_class_name) || 'unknown', name: text(row.sys_name) || text(row.sys_update_name) || text(row.sys_id), update_name: text(row.sys_update_name) };
+    const evidence = [{ source: 'sys_metadata', sys_id: identity.sys_id, basis: 'Visible application metadata record', updated_on: text(row.sys_updated_on) }];
+    const item = {
+      identity, scope: { sys_id: scopeId || null, name: text(scope?.name) || null, scope: scopeName || null }, evidence,
+      risk: { rating: 'unknown', rationale: 'No trusted current OOTB baseline, runtime usage or dependency analysis was captured.' },
+      recommendation: 'Review ownership, current configuration and tests before changing this artifact.',
+      unknowns: ['Current content and behavioral differences were not captured.', 'Metadata timestamps can change without a behavioral change.'],
+    };
+    const history = (logs.get(identity.update_name) || []).sort((a, b) => text(b.sys_updated_on).localeCompare(text(a.sys_updated_on)) || text(a.sys_id).localeCompare(text(b.sys_id)));
+    // Raw provider choices: 4 = Skipped, 104 = Skipped (second pass).
+    // The read is already filtered server-side; this check stays because a
+    // server filter is never trusted to be a classification.
+    const skipped = history.filter(log => Object.hasOwn(log, 'resolution_status') && SKIP_DISPOSITIONS.includes(text(log.disposition)) && text(log.resolution_status) !== 'reviewed_reverted');
+    // A declaration is caller evidence, not platform/vendor provenance. Keep it
+    // separate from OOTB findings and record the uncertainty explicitly.
+    if (scope && scopeId !== 'global' && scopeName !== 'global' && (declared.has(scopeName) || declared.has(scopeId))) {
+      evidence.push({ source: 'capture_options', sys_id: scopeId, basis: 'Customer ownership declared by caller; scope identity verified in sys_scope.' });
+      item.unknowns.push('Publisher/customer ownership is not independently verified.');
+      item.recommendation = 'Maintain as a declared customer application artifact; review with its owner, not as an OOTB deviation.';
+      categories.customer_app_artifacts.push(item);
+    } else if (identity.update_name && skipped.length) {
+      for (const log of skipped) evidence.push({ source: 'sys_upgrade_history_log', sys_id: text(log.sys_id), basis: 'Upgrade disposition skipped preserves a customization of a vendor-delivered artifact.', disposition: text(log.disposition), resolution_status: text(log.resolution_status) || null });
+      item.unknowns.push('Historical upgrade skips do not prove the customization still differs from OOTB. Later reversion or merge may have occurred.');
+      item.reversion = {
+        known_impact: ['The recorded upgrade did not overwrite the customization.'],
+        known_dependencies: [],
+        unknowns: ['Current OOTB baseline and exact changes are unavailable.', 'Runtime impact and dependencies of reverting have not been established. An empty dependency list does not mean none exist.'],
+      };
+      item.recommendation = 'Retain pending review. Compare the current artifact with a trusted baseline, inspect callers and regression-test in non-production before any reversion.';
+      categories.ootb_modifications.push(item);
+    } else {
+      item.unknowns.push('Origin is unclassified. A non-global scope or an update timestamp is not proof of customer ownership or an OOTB modification.');
+      categories.unclassified.push(item);
+    }
+  }
+  const visibleNames = new Set(data.sys_metadata.map(row => text(row.sys_update_name)).filter(Boolean));
+  const unresolvedNames = [...new Set(observedNames)].filter(name => !visibleNames.has(name)).sort();
+  return {
+    status: 'incomplete', categories,
+    coverage: { complete: false, sources,
+      upgrade_evidence: {
+        skipped_rows_observed: data.sys_upgrade_history_log.length,
+        update_names_observed: new Set(observedNames).size,
+        resolved_by_lookup: observedNames.length ? resolution.coverage.resolved_names : 0,
+        unresolved_update_names: unresolvedNames,
+        lookup_failures: observedNames.length ? resolution.coverage.failed_chunks : 0,
+      },
+      unmatched_upgrade_records: data.sys_upgrade_history_log.filter(row => !visibleNames.has(text(row.file_name))).length,
+      unmatched_customer_scopes: customerScopes.filter(id => !data.sys_scope.some(row => text(row.sys_id) === id || text(row.scope) === id)),
+      limitations: ['Inventory covers visible sys_metadata and upgrade history only, not every customization mechanism.', `Upgrade history is read server-side for raw dispositions ${SKIP_DISPOSITIONS.join(' and ')} only; unmatched upgrade counts describe that filtered population, not all upgrade history.`, 'Coverage compares rows fetched with the Stats API count for the same query; a short page never implies exhaustion and an unavailable count leaves completeness unknown.', `The broad sys_metadata source is a bounded sample of an arbitrary sys_id-ordered slice, not an inventory, so unclassified and declared-customer categories only describe sampled artifacts. Skipped-upgrade artifacts are separate: they are resolved by the update names the filtered history read observed (${RESOLUTION_SOURCE}).`, 'Name resolution only looks up artifacts with skipped-upgrade evidence, so customizations with no upgrade-skip history are not discovered by it.', 'A resolved artifact can show a scope sys_id without a scope name when that scope record was outside the bounded sys_scope read.', 'Row/field ACL filtering and concurrent changes cannot be ruled out.', 'No current baseline, source payloads or dependency graph captured. Comparisons detect captured metadata/evidence changes only.', 'OOTB category means historical skipped-upgrade evidence, not a verified current deviation. Customer scopes are caller declarations.'],
+    },
+  };
+}

package/src/impact-analysis.js

@@ -0,0 +1,67 @@
+// Reusable, provider-independent impact analysis. No CLI, prompts or writes.
+const raw = value => String(value?.value ?? value ?? '');
+const BOOKKEEPING_FIELDS = new Set(['sys_id', 'sys_created_on', 'sys_created_by', 'sys_updated_on',
+  'sys_updated_by', 'sys_mod_count', 'sys_recorded_at', 'sys_update_name']);
+export const isImpactField = field => !BOOKKEEPING_FIELDS.has(field);
+const decode = value => value.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+
+// Deliberately accepts only the observed flat record_update payload shape.
+// Unknown XML constructs are evidence gaps, never silently discarded changes.
+export function baselineFields(payload, artifact) {
+  if (!payload || /<!DOCTYPE|<!ENTITY/i.test(payload)) return null;
+  const table = artifact.table;
+  if (!/^[a-z][a-z0-9_]*$/.test(table || '')) return null;
+  const outer = payload.replace(/^\s*<\?xml[^?]*\?>\s*/, '').trim();
+  const match = outer.match(/^<record_update\s+table="([a-z0-9_]+)">\s*<([a-z0-9_]+)\s+action="INSERT_OR_UPDATE">([\s\S]*)<\/\2>\s*<\/record_update>$/);
+  if (!match || match[1] !== table || match[2] !== table) return null;
+  const fields = {};
+  let rest = match[3];
+  while (rest.trim()) {
+    const field = rest.match(/^\s*<([a-z0-9_]+)(?:\s+[^<>]*?)?(?:\s*\/>|>([\s\S]*?)<\/\1>)/);
+    if (!field || Object.hasOwn(fields, field[1])) return null;
+    let value = field[2] ?? '';
+    if (value.startsWith('<![CDATA[') && value.endsWith(']]>')) value = value.slice(9, -3);
+    else {
+      if (/[<>]/.test(value) || /&(?!lt;|gt;|quot;|apos;|amp;)/.test(value)) return null;
+      value = decode(value);
+    }
+    fields[field[1]] = value;
+    rest = rest.slice(field[0].length);
+  }
+  if (fields.sys_id !== artifact.sys_id) return null;
+  return fields;
+}
+
+export function analyzeImpact({ artifact, current, baseline, dependencies = [], unknown = [] }) {
+  const fields = baselineFields(baseline?.payload, artifact);
+  const gaps = [...unknown, 'Dynamic script references, transitive dependencies and runtime outcomes are unknown; no execution testing was performed.'];
+  const changes = [];
+  if (!fields) gaps.push('The exact base payload is unavailable or its XML shape/identity is unsupported.');
+  if (!current) gaps.push('The current artifact is unavailable.');
+  if (fields && current) {
+    for (const field of Object.keys(fields).sort()) {
+      if (!isImpactField(field)) continue;
+      if (!Object.hasOwn(current, field)) {
+        gaps.push(`Current field ${field} was not returned; its revert impact is unknown.`);
+        continue;
+      }
+      if (raw(current[field]) !== fields[field]) {
+        changes.push({ field, current: raw(current[field]), base: fields[field],
+          effect: field === 'script' ? 'Replace the executable script with the base script; runtime behavior is unverified.'
+            : field === 'active' ? `Set activation to ${fields[field]}; execution eligibility changes.`
+              : `Replace ${field} with the base value; behavior beyond this field change is unknown.` });
+      }
+    }
+    gaps.push('Fields absent from the base payload and provider-generated normalization are unknown.');
+  }
+  return { artifact, evidence: { baseline_version: baseline?.sys_id || null,
+    baseline_source: baseline?.source || null, baseline_source_table: baseline?.source_table || null },
+  direct_behavior: { status: fields && current ? 'field_comparison' : 'unknown',
+    summary: fields && current ? `${changes.length} observed field change(s) on return to base; this is not a runtime simulation.` : 'Unknown without both current artifact and a supported exact base payload.' },
+  changes, known_dependencies: dependencies, unknown: gaps,
+  recommendation: { action: 'retain', basis: changes.length
+    ? 'Preserve the customization pending validation of the observed changes and unknown dependencies.'
+    : 'Preserve the customization until the unknown runtime and dependency effects are validated.',
+  automatic: false } };
+}

package/src/sdk.js

@@ -4,6 +4,7 @@ import { gunzipSync } from 'node:zlib';
 import { errAuth, errAPI, errNetwork } 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';
 
 const DEFAULT_TIMEOUT = 30000;
 
@@ -94,7 +95,8 @@ export class SDKClient {
   }
 
   async request(endpoint, opts = {}) {
-    const { timeout = this.timeout, touchLastSeen = true, ...requestOptions } = opts;
+    const { timeout = this.timeout, readOnly = false, touchLastSeen, ...requestOptions } = opts;
+    if (readOnly && (requestOptions.method || 'GET').toUpperCase() !== 'GET') throw new Error('Read-only SDK requests require GET');
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
 
@@ -110,6 +112,8 @@ export class SDKClient {
       if (this.domain) {
         req.headers.set('X-Now-Domain', this.domain);
       }
+      // readOnly guards the data request, not standard authentication bootstrap.
+      // OAuth refresh and session/GCK negotiation are not instance-record writes.
       await this._setAuth(req);
 
       const resp = await fetch(req);
@@ -125,7 +129,10 @@ export class SDKClient {
 
       // Stamp last_seen on successful API call
       try {
-        if (touchLastSeen && this.authProvider && typeof this.authProvider.touchLastSeen === 'function') {
+        // readOnly suppresses the credential last-seen write unconditionally: a
+        // caller passing touchLastSeen cannot override it (GLOSSARY contract).
+        const shouldTouch = readOnly ? false : (touchLastSeen ?? true);
+        if (shouldTouch && this.authProvider && typeof this.authProvider.touchLastSeen === 'function') {
           this.authProvider.touchLastSeen(this.baseURL);
         }
       } catch { /* non-fatal */ }
@@ -197,6 +204,14 @@ export class SDKClient {
     }
   }
 
+  async getSkippedUpdateBaseline(sysID) {
+    return readSkippedBaseline(this, sysID);
+  }
+
+  async revertSkippedUpdate(sysID, modCount) {
+    return revertSkippedUpdate(this, sysID, modCount);
+  }
+
   async list(table, params = {}, opts = {}) {
     const query = new URLSearchParams(params).toString();
     const endpoint = `${this.baseURL}/api/now/table/${table}${query ? '?' + query : ''}`;
@@ -204,6 +219,22 @@ export class SDKClient {
     return result?.result || [];
   }
 
+  // Strict Table API seam. `list` stays best-effort for legacy callers, but a
+  // 2xx response without a result array is a malformed envelope, not an empty
+  // table. Capture paths use this so an unexpected body becomes an unavailable
+  // source instead of a complete-looking empty inventory.
+  async listStrict(table, params = {}, opts = {}) {
+    const query = new URLSearchParams(params).toString();
+    const endpoint = `${this.baseURL}/api/now/table/${table}${query ? '?' + query : ''}`;
+    const response = await this.request(endpoint, { method: 'GET', ...opts });
+    if (!response || typeof response !== 'object' || !Array.isArray(response.result)) {
+      const error = new Error(`Malformed table response for ${table}: expected a JSON envelope with a result array`);
+      error.code = 'malformed_response';
+      throw error;
+    }
+    return response.result;
+  }
+
   async get(table, sysID) {
     const endpoint = `${this.baseURL}/api/now/table/${table}/${sysID}`;
     const result = await this.request(endpoint, { method: 'GET' });

package/src/skipped-update-provider.js

@@ -0,0 +1,45 @@
+import { errUsage } from './errors.js';
+
+function validateId(id) {
+  if (!/^[0-9a-fA-F]{32}$/.test(id || '')) throw errUsage('A literal 32-hex skipped finding sys_id is required.');
+}
+
+// Contract observed in RevertUpdateVersionAjax.revertToBaseSystem, PDI Australia.
+// Keep read and write separate. No Table API state update can implement revert.
+export async function readSkippedBaseline(sdk, id) {
+  validateId(id);
+  const output = await sdk.executeScript(`(function() {
+    var record = new GlideRecordSecure('sys_upgrade_history_log');
+    if (!record.get('${id}') || !record.canRead()) throw new Error('Finding unavailable');
+    var name = record.getValue('file_name');
+    var storeAppID = GlideappUpdateVersion.getStoreAppID(record);
+    var baseline = storeAppID != null
+      ? GlideappUpdateVersion.getVersion(name, storeAppID, 'sys_store_app', null)
+      : GlideappUpdateVersion.getVersion(name, record.upgrade_history, 'sys_upgrade_history', null);
+    if (!baseline || !baseline.isValidRecord()) throw new Error('No base system version found');
+    gs.print('JSN_SKIPPED_BASE:' + JSON.stringify({sys_id: baseline.getUniqueValue(),
+      payload: baseline.getValue('payload'), source: baseline.getValue('source'),
+      source_table: baseline.getValue('source_table')}));
+  })();`, 'global');
+  const match = output.match(/JSN_SKIPPED_BASE:(\{[^\r\n]*\})/);
+  if (!match) throw errUsage('Base version inspection returned no verifiable result.');
+  try { return JSON.parse(match[1]); } catch { throw errUsage('Base version inspection returned invalid JSON.'); }
+}
+
+export async function revertSkippedUpdate(sdk, id, modCount) {
+  validateId(id);
+  if (!/^\d+$/.test(modCount || '')) throw errUsage('Finding update count is required for safe revert.');
+  const output = await sdk.executeScript(`(function() {
+    if (!gs.hasRole('admin')) throw new Error('Admin role required');
+    var record = new GlideRecordSecure('sys_upgrade_history_log');
+    if (!record.get('${id}') || !record.canWrite()) throw new Error('Finding unavailable or not writable');
+    if (record.getValue('disposition') !== '4' ||
+        ['', 'not_reviewed'].indexOf(record.getValue('resolution_status') || '') < 0 ||
+        record.getValue('sys_mod_count') !== '${modCount}') throw new Error('Finding changed or is not eligible');
+    new RevertUpdateVersionAjax().revertToBaseSystem('${id}');
+    gs.print('JSN_SKIPPED_REVERT:dispatched');
+  })();`, 'global');
+  if (!output.includes('JSN_SKIPPED_REVERT:dispatched')) throw errUsage('Revert dispatch outcome is unknown; inspect the finding before retrying.');
+  // The processor returns no success boolean. Caller must verify disposition and
+  // resolution by GET; dispatch alone must never be reported as success.
+}

package/src/skipped-updates.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { errUsage, errNotFound, AppError } from './errors.js';
+import { analyzeImpact, baselineFields, isImpactField } from './impact-analysis.js';
+
+export const SKIP_TABLE = 'sys_upgrade_history_log';
+const SKIPPED = ['4', '104', '9', '10', '11'];
+export const raw = value => String(value?.value ?? value ?? '');
+export const unresolved = record => Boolean(record && Object.hasOwn(record, 'disposition')
+  && Object.hasOwn(record, 'resolution_status') && SKIPPED.includes(raw(record.disposition))
+  && ['', 'not_reviewed'].includes(raw(record.resolution_status)));
+const FIELDS = 'sys_id,file_name,target_name,disposition,resolution_status,upgrade_history,reason,changed,sys_mod_count,sys_updated_on';
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const validId = id => /^[0-9a-fA-F]{32}$/.test(id || '');
+
+function validateSelection(ids, action) {
+  if (!Array.isArray(ids) || !ids.length || ids.length > 100 || ids.some(id => !validId(id))) {
+    throw errUsage('Select between 1 and 100 literal finding sys_ids.');
+  }
+  if (new Set(ids.map(id => id.toLowerCase())).size !== ids.length) throw errUsage('Duplicate finding sys_ids are not allowed.');
+  if (!['retain', 'revert'].includes(action)) throw errUsage('Select an explicit action: retain or revert. Recommendations are never actions.');
+}
+
+export async function reviewSkippedUpdate(sdk, id) {
+  if (!validId(id)) throw errUsage('A literal 32-hex finding sys_id is required.');
+  const finding = await sdk.get(SKIP_TABLE, id);
+  if (!finding) throw errNotFound('Skipped finding', id);
+  if (raw(finding.sys_id).toLowerCase() !== id.toLowerCase()) throw errUsage('Provider finding identity does not match selection.');
+  const fileName = raw(finding.file_name);
+  const match = fileName.match(/^([a-z][a-z0-9_]*)_([0-9a-fA-F]{32})$/);
+  const artifact = { update_name: fileName, name: raw(finding.target_name),
+    table: match?.[1] || null, sys_id: match?.[2] || null };
+  let current = null;
+  let baseline = null;
+  const unknown = [];
+  if (match) {
+    try { current = await sdk.get(artifact.table, artifact.sys_id); }
+    catch { unknown.push('Current artifact could not be read; access or availability is unknown.'); }
+  } else unknown.push('Artifact identity cannot be decoded from the provider update name.');
+  try { baseline = await sdk.getSkippedUpdateBaseline(id); }
+  catch { unknown.push('Base inspection is unavailable. Background-script access and version API availability are required.'); }
+  const dependencies = [];
+  if (match) {
+    try {
+      const refs = await sdk.list('sys_dictionary', new URLSearchParams({
+        sysparm_query: `reference=${artifact.table}^elementISNOTEMPTY^ORDERBYname^ORDERBYelement`,
+        sysparm_fields: 'name,element', sysparm_limit: '21', sysparm_display_value: 'false',
+      }));
+      if (refs.length > 20) unknown.push('Incoming reference discovery is truncated to 20 dictionary fields.');
+      for (const ref of refs.slice(0, 20)) {
+        const table = raw(ref.name), field = raw(ref.element);
+        if (!/^[a-z][a-z0-9_]*$/.test(table) || !/^[a-z][a-z0-9_]*$/.test(field)) continue;
+        try {
+          const rows = await sdk.list(table, new URLSearchParams({ sysparm_query: `${field}=${artifact.sys_id}^ORDERBYsys_id`,
+            sysparm_fields: 'sys_id', sysparm_limit: '11', sysparm_display_value: 'false' }));
+          for (const row of rows.slice(0, 10)) dependencies.push({ table, field, sys_id: raw(row.sys_id), relation: 'incoming_reference' });
+          if (rows.length > 10) unknown.push(`Incoming references from ${table}.${field} are truncated to 10 records.`);
+        } catch { unknown.push(`Incoming references from ${table}.${field} could not be read.`); }
+      }
+    } catch { unknown.push('Dictionary-backed incoming dependency discovery is unavailable.'); }
+  }
+  const impact = analyzeImpact({ artifact, current, baseline, dependencies, unknown });
+  const fields = baselineFields(baseline?.payload, artifact);
+  const fingerprint = digest({ finding, current, baseline });
+  return { sys_id: raw(finding.sys_id), artifact, finding: Object.fromEntries(FIELDS.split(',').map(key => [key, raw(finding[key])])),
+    impact, fingerprint, eligible: unresolved(finding),
+    // The provider's revert writes a NEW base version record whose payload is a
+    // copy of the version that was read here, so revert readback compares base
+    // CONTENT (this digest) instead of the previewed version sys_id.
+    baseline_payload_digest: typeof baseline?.payload === 'string' && baseline.payload
+      ? digest(baseline.payload) : null,
+    revert_supported: raw(finding.disposition) === '4' && validId(baseline?.sys_id)
+      && Boolean(current && raw(current.sys_id) === artifact.sys_id && fields
+        && Object.keys(fields).every(field => !isImpactField(field) || Object.hasOwn(current, field))) };
+}
+
+export async function prepareSkippedBatch(sdk, { ids, action, instance = '' }) {
+  validateSelection(ids, action);
+  const selected = [];
+  for (const id of ids) {
+    const review = await reviewSkippedUpdate(sdk, id);
+    if (!review.eligible) throw errUsage(`Finding ${id} is no longer unresolved and skipped.`);
+    if (action === 'revert' && !review.revert_supported) throw errUsage(`Revert is unsupported for ${id}: requires disposition 4, readable artifact and exact base version.`);
+    selected.push({ ...review, action, operation: action === 'retain'
+      ? 'Set resolution_status=reviewed_retained only; leave artifact unchanged.'
+      : 'Call RevertUpdateVersionAjax.revertToBaseSystem; replace customization with provider-selected base version.' });
+  }
+  if (action === 'revert') {
+    const includes = await sdk.list('sys_script_include', new URLSearchParams({
+      sysparm_query: 'name=RevertUpdateVersionAjax', sysparm_fields: 'script', sysparm_limit: '2', sysparm_display_value: 'false' }));
+    if (includes.length !== 1 || !/revertToBaseSystem\s*:\s*function\s*\(\s*sys_id\s*\)/.test(raw(includes[0].script))
+        || !raw(includes[0].script).includes('GlideappUpdateVersion.getVersion')) {
+      throw errUsage('Provider revert lifecycle contract is unavailable; no writes performed.');
+    }
+  }
+  const preview = { instance, selected, count: selected.length };
+  return { ...preview, confirmation_token: digest(preview), writes_performed: false };
+}
+
+
+export async function processSkippedBatch({ sdk, ids, action, instance = '', readOnly = false,
+  confirmationToken, confirm, onPreview }) {
+  if (readOnly) throw new AppError('read_only', 'Read-only profiles cannot process findings.');
+  const preview = await prepareSkippedBatch(sdk, { ids, action, instance });
+  // Preview precedes the sole confirmation. Never honor force or a profile's
+  // skip_confirmations here; this batch always requires explicit consent.
+  if (onPreview) await onPreview(preview);
+  if (confirmationToken) {
+    if (confirmationToken !== preview.confirmation_token) throw errUsage('Preview changed or confirmation token does not match. Review a new preview before confirming.');
+  } else if (confirm) {
+    if (!await confirm(preview)) return { preview, cancelled: true, results: [], success_count: 0, failure_count: 0, partial: false, writes_performed: false };
+  } else {
+    throw new AppError('confirmation_required', 'Review the exact batch preview before processing.',
+      `Run jsn skipped-updates preview --ids ${ids.join(',')} --action ${action}; review its exact selection, then process that selection with --confirm <preview-token>.`);
+  }
+  const results = [];
+  for (const selected of preview.selected) {
+    let attempted = false;
+    try {
+      const latest = await reviewSkippedUpdate(sdk, selected.sys_id);
+      if (!latest.eligible || latest.fingerprint !== selected.fingerprint) throw errUsage('Finding, artifact or base version changed after preview; no write attempted.');
+      attempted = true;
+      if (action === 'retain') await sdk.update(SKIP_TABLE, selected.sys_id, { resolution_status: 'reviewed_retained' });
+      else await sdk.revertSkippedUpdate(selected.sys_id, selected.finding.sys_mod_count);
+      const persisted = await sdk.get(SKIP_TABLE, selected.sys_id);
+      const expected = action === 'retain' ? 'reviewed_retained' : 'reviewed_reverted';
+      if (!persisted || raw(persisted.sys_id) !== selected.sys_id || raw(persisted.resolution_status) !== expected
+          || raw(persisted.disposition) !== (action === 'revert' ? '5' : selected.finding.disposition)) {
+        throw errUsage('Provider state readback did not verify the selected action.');
+      }
+      if (action === 'revert') {
+        const artifact = await sdk.get(selected.artifact.table, selected.artifact.sys_id);
+        const baseline = await sdk.getSkippedUpdateBaseline(selected.sys_id);
+        const fields = baselineFields(baseline?.payload, selected.artifact);
+        // RevertToBaseSystem reverts to the previewed base version and leaves a new
+        // base version record behind, so the sys_id legitimately changes. What must
+        // still match is the base CONTENT we previewed and the artifact now at base.
+        if (!artifact || raw(artifact.sys_id) !== selected.artifact.sys_id || !fields
+            || !validId(baseline?.sys_id) || typeof baseline?.payload !== 'string'
+            || digest(baseline.payload) !== selected.baseline_payload_digest
+            || Object.entries(fields).some(([field, value]) => isImpactField(field)
+              && (!Object.hasOwn(artifact, field) || raw(artifact[field]) !== value))) {
+          throw errUsage('Artifact readback did not verify the previewed base content on the reverted artifact.');
+        }
+        results.push({ sys_id: selected.sys_id, action, success: true, write_attempted: true,
+          resolution_status: raw(persisted.resolution_status), disposition: raw(persisted.disposition),
+          base_version: raw(baseline.sys_id), verified: true });
+        continue;
+      }
+      results.push({ sys_id: selected.sys_id, action, success: true, write_attempted: true,
+        resolution_status: raw(persisted.resolution_status), disposition: raw(persisted.disposition), verified: true });
+    } catch (err) {
+      results.push({ sys_id: selected.sys_id, action, success: false, write_attempted: attempted,
+        effect: attempted ? 'unknown' : 'unchanged', code: err.code || 'provider_error',
+        message: attempted ? 'Selected action or its readback failed; inspect this finding before retrying.' : err.message });
+    }
+  }
+  const successCount = results.filter(result => result.success).length;
+  return { preview, results, cancelled: false, success_count: successCount,
+    failure_count: results.length - successCount, partial: successCount > 0 && successCount < results.length,
+    writes_performed: results.some(result => result.write_attempted) };
+}
+
+export async function discoverSkippedUpdates(sdk, { limit = 100, offset = 0 } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500 || !Number.isInteger(offset) || offset < 0) {
+    throw errUsage('Use a limit between 1 and 500 and a nonnegative integer offset.');
+  }
+  const params = new URLSearchParams({
+    sysparm_query: 'dispositionIN4,104,9,10,11^resolution_statusIN,not_reviewed^ORDERBYsys_id',
+    sysparm_fields: FIELDS, sysparm_display_value: 'all',
+    sysparm_limit: String(limit + 1), sysparm_offset: String(offset),
+  });
+  const rows = await sdk.list(SKIP_TABLE, params);
+  // Recheck locally: an instance can ignore a query field the caller cannot read.
+  if (rows.some(row => !unresolved(row))) throw errUsage('Provider returned a finding outside the unresolved skipped state.');
+  return { findings: rows.slice(0, limit), count: Math.min(rows.length, limit),
+    limit, offset, has_more: rows.length > limit, total: null };
+}