@jacebenson/jsn 4.3.13-dev.100.1 → 4.3.13-dev.101.1

package/README.md

@@ -32,6 +32,46 @@ under npm's `dev` tag. Versions include the workflow run number and attempt
 The npm trusted publisher for `publish-dev.yml` must authorize the repository's
 `dev` GitHub environment, alongside the production publishing configuration.
 
+### Instance Scan
+
+`jsn scan` manages checks and suites and runs scans against an explicit target.
+Use `jsn scan --help` and each subcommand's `--help` to discover the options.
+
+```bash
+jsn scan checks list --profile dev
+jsn scan checks create --type table --data-file check.json --profile dev
+jsn scan checks activate <check-id> --profile dev
+jsn scan suites add-check <suite-id> --check <check-id> --profile dev
+jsn scan run --update-set "My change" --suite "My suite" --wait --profile dev
+jsn scan run --table sys_script_include --record <record-id> --profile dev
+jsn scan results <execution-id> --profile dev
+```
+
+Check types are `table`, `column`, `linter`, and `script`. Definitions are created
+inactive unless the payload explicitly sets `active: true`; activation never
+starts a scan. Both checks and suites support list/show/create/update/delete and
+activate/deactivate. Suites also support add-check/remove-check.
+
+Runs require an update set, scope, record plus table, or explicit `--full`.
+Instance-wide scans may traverse many tables even when a check's script only
+examines a few records. Starting and cancelling a scan require confirmation;
+use `--force` only after approving that operation. `--wait --timeout 120` bounds
+the wait, not the scan's lifetime. A timed-out wait keeps the execution id and
+does not cancel or resubmit the scan. Use `status`, `results`, or `cancel` next.
+
+Update-set scans examine current instance records, not the historical XML
+versions. Inactive records may be skipped. Script-only checks do not participate
+in record/update-set scans; use an explicitly instance-wide suite run to execute
+them. Execution success does not mean zero findings or complete test coverage:
+results report recorded check executions, finding counts, unreadable sources,
+and truncated lists separately. A result's rerun hint preserves the previous
+target combination and requires `--full` again for instance-wide scans.
+
+Every command returns next-step breadcrumbs in human and JSON output, retaining
+an explicitly selected profile or instance. `updatesets show` also offers a scan
+hint. Recommendation/generation of new checks is not part of this command;
+JSN contains no AI and does not infer missing business requirements.
+
 ### Supported versions
 
 Only the current release and the two preceding releases in each channel are

package/package.json

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

package/skills/servicenow/SKILL.md

@@ -24,7 +24,7 @@ For development:
 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.
+4. Offer to run relevant existing ATFs and instance scans, or create missing checks.
 5. Ask whether anything else belongs in the update set. If the user confirms
    it is finished, complete it with notes.
 

package/src/cli.js

@@ -72,6 +72,7 @@ import { logsCmd } from './commands/logs.js';
 import { scrapiCmd } from './commands/scrapi.js';
 import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
+import { scanCmd } from './commands/scan.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { historyCmd } from './commands/history.js';
 import { perfCmd } from './commands/perf.js';
@@ -421,6 +422,7 @@ export function buildCLI() {
     .command(codesearchCmd(wrap))
     // DEVELOPER
     .command(atfCmd(wrap))
+    .command(scanCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))

package/src/commands/scan.js

@@ -0,0 +1,234 @@
+import { buildRecordPayload, confirmDelete, getStringField, quoteShellArg, verifyWriteBack } from '../helpers.js';
+import { createRecord, updateRecord, deleteRecord } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { getCurrentApplication, getCurrentUser } from '../context.js';
+import { declareCapabilities } from '../capabilities.js';
+import { errAPI, errUsage } from '../errors.js';
+import { CHECK_TABLES, active, raw, referenceId, boundedLimit, scanList, resolveScanRecord,
+  validateScanPayload, checkKind, prepareScan, startScan, scanStatus, scanResults, cancelScan } from '../scan.js';
+
+declareCapabilities('scan', { mutationSubcommands: [
+  ...['checks', 'suites'].flatMap(group => ['create', 'update', 'delete', 'activate', 'deactivate'].map(verb => `${group} ${verb}`)),
+  'suites add-check', 'suites remove-check', 'run', 'cancel',
+] });
+
+const hint = (action, cmd, description) => ({ action, cmd, description });
+function report(app, argv, data, options) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { ...options, breadcrumbs: options.breadcrumbs.map(item => ({ ...item, cmd: item.cmd + connection })) });
+}
+const rootHints = () => [hint('checks', 'jsn scan checks list', 'Browse available checks'),
+  hint('suites', 'jsn scan suites list', 'Browse suites'), hint('run', 'jsn scan run --help', 'Choose an explicit scan target')];
+const itemHints = (group, record) => {
+  const id = unwrapSysId(record);
+  return [hint('list', `jsn scan ${group} list`, `Browse ${group}`),
+    hint('show', `jsn scan ${group} show ${id}`, 'Inspect this definition'),
+    hint('update', `jsn scan ${group} update ${id} --data-file ${group === 'checks' ? 'check' : 'suite'}.json`, 'Update selected fields'),
+    hint(active(record) ? 'deactivate' : 'activate', `jsn scan ${group} ${active(record) ? 'deactivate' : 'activate'} ${id}`, 'Change eligibility without starting a scan'),
+    ...(group === 'suites' ? [hint('add-check', `jsn scan suites add-check ${id} --check '<check-id-or-name>'`, 'Add an existing check'),
+      hint('run', `jsn scan run --suite ${id} --update-set '<update-set>'`, 'Run against an explicit update set')] :
+      [hint('suites', 'jsn scan suites list', 'Choose a suite for this check')]),
+    hint('delete', `jsn scan ${group} delete ${id}`, 'Delete this definition after confirmation')];
+};
+
+function executionHints(data) {
+  const id = data.execution_id;
+  return [hint('status', `jsn scan status ${id}`, 'Read execution progress'),
+    hint('results', `jsn scan results ${id}`, 'Inspect findings and recorded check executions'),
+    ...(!data.terminal ? [hint('cancel', `jsn scan cancel ${id}`, 'Request cancellation')] : []),
+    ...(data.reusable_target ? [hint('rerun', `jsn scan run --previous ${id}${data.rerun_full ? ' --full' : ''}`, 'Rerun the previous target with current check definitions')] : []),
+    hint('checks', 'jsn scan checks list', 'Review available checks')];
+}
+
+const payloadOptions = y => y.option('data', { type: 'string', describe: 'JSON fields' })
+  .option('data-file', { type: 'string', describe: 'Read JSON fields from a file (recommended for scripts)' })
+  .option('data-stdin', { type: 'boolean', describe: 'Read JSON fields from stdin' })
+  .option('field', { alias: 'f', type: 'array', describe: 'Set field=value; repeatable' });
+const lookupOptions = y => y.positional('identifier', { type: 'string', describe: 'Unique name or sys_id' });
+
+async function guardScope(app, record) {
+  const scopeId = referenceId(record.sys_scope) || raw(record.sys_scope);
+  if (!scopeId) throw errUsage('The definition scope is unreadable; inspect permissions before changing it.');
+  const user = await getCurrentUser(app.sdk);
+  if (!user) throw errUsage('Could not verify the current scope.');
+  const scope = await getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true });
+  if (scope.appSysId !== scopeId && scope.scope !== scopeId) {
+    throw errUsage(`Select the definition scope before changing it: jsn scopes set ${quoteShellArg(scopeId)}`);
+  }
+}
+
+async function verify(app, table, id, data) {
+  if (!id) throw errAPI(200, 'The write returned no sys_id. Inspect the instance before retrying.');
+  const mismatches = await verifyWriteBack(app, table, id, data);
+  if (mismatches.length) throw errAPI(200, `Write-back verification failed for ${table}/${id}: ${mismatches.map(item => item.field).join(', ')}. The write may have succeeded partially; inspect before retrying.`);
+}
+
+function definitions(group, wrap) {
+  const suite = group === 'suites';
+  const baseTable = suite ? 'scan_check_suite' : 'scan_check';
+  const emit = (app, argv, record, summary) => report(app, argv, record, { summary, breadcrumbs: itemHints(group, record) });
+  return {
+    command: `${group} [subcommand]`,
+    describe: suite ? 'Manage scan suites and their check memberships' : 'Manage typed Instance Scan check definitions',
+    builder: y => {
+      y.command({ command: 'list', describe: `List ${group}`,
+        builder: p => {
+          p.option('query', { type: 'string', describe: 'Encoded query' })
+            .option('limit', { type: 'number', default: 50, describe: 'Maximum records (1–200)' })
+            .option('offset', { type: 'number', default: 0, describe: 'Pagination offset' });
+          return suite ? p : p.option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', describe: 'Filter by check type' });
+        }, handler: wrap(async (argv, app) => {
+          const table = suite ? baseTable : (argv.type ? CHECK_TABLES[argv.type] : baseTable);
+          const records = await scanList(app.sdk, table, { limit: argv.limit, offset: argv.offset, query: argv.query,
+            fields: ['sys_id', 'name', 'active', ...(suite ? ['description'] : ['sys_class_name', 'short_description'])] });
+          report(app, argv, { table, records, count: records.length, limit: argv.limit, offset: argv.offset,
+            more_available: records.length === argv.limit ? null : false }, {
+            summary: `${records.length} scan ${group}`, breadcrumbs: [
+              ...records.slice(0, 5).map(record => hint('show', `jsn scan ${group} show ${unwrapSysId(record)}`, `Inspect ${getStringField(record, 'name')}`)),
+              hint('create', `jsn scan ${group} create${suite ? '' : ' --type table'} --data-file ${suite ? 'suite' : 'check'}.json`, 'Create an inactive definition'),
+              ...(records.length === argv.limit ? [hint('next', `jsn scan ${group} list --offset ${argv.offset + argv.limit} --limit ${argv.limit}${argv.type ? ` --type ${argv.type}` : ''}${argv.query ? ` --query ${quoteShellArg(argv.query)}` : ''}`, 'Next page')] : []),
+            ],
+          });
+        }) });
+      y.command({ command: 'show <identifier>', describe: `Inspect a ${suite ? 'suite and its members' : 'check'}`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          if (suite) {
+            const members = await scanList(app.sdk, 'scan_check_suite_check', { limit: 200, query: `suite=${unwrapSysId(record)}^ORDERBYsys_id`, fields: ['sys_id', 'check'] });
+            record.members = members;
+            record.members_may_be_truncated = members.length === 200;
+          }
+          emit(app, argv, record, `Scan ${suite ? 'suite' : 'check'}: ${getStringField(record, 'name')}`);
+        }) });
+      y.command({ command: 'create', describe: `Create an inactive ${suite ? 'suite' : 'typed check'} unless active is explicitly supplied`,
+        builder: p => suite ? payloadOptions(p) : payloadOptions(p).option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', demandOption: true, describe: 'Check type' }),
+        handler: wrap(async (argv, app) => {
+          const data = validateScanPayload(argv.type, buildRecordPayload(argv), { create: true, suite });
+          const table = suite ? baseTable : CHECK_TABLES[argv.type];
+          const record = await createRecord(app.sdk, { table, data });
+          await verify(app, table, unwrapSysId(record), data);
+          emit(app, argv, record, `Created scan ${suite ? 'suite' : 'check'}`);
+        }) });
+      for (const operation of ['update', 'activate', 'deactivate']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation} a scan ${suite ? 'suite' : 'check'} without running it`,
+        builder: p => operation === 'update' ? payloadOptions(lookupOptions(p)) : lookupOptions(p),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const kind = suite ? null : checkKind(record);
+          const patch = operation === 'update' ? validateScanPayload(kind, buildRecordPayload(argv), { suite, current: record }) : { active: operation === 'activate' };
+          if (!suite && operation === 'activate') validateScanPayload(kind, {
+            name: raw(record.name), script: raw(record.script), ...(kind === 'table' ? { table: raw(record.table), advanced: raw(record.advanced) } : {}),
+            ...(kind === 'column' ? { column_type: raw(record.column_type) } : {}),
+          }, { create: true });
+          await guardScope(app, record);
+          const table = suite ? baseTable : CHECK_TABLES[kind];
+          const updated = await updateRecord(app.sdk, { table, record, data: patch });
+          await verify(app, table, unwrapSysId(record), patch);
+          emit(app, argv, updated, `Updated scan ${suite ? 'suite' : 'check'}`);
+        }),
+      });
+      y.command({ command: 'delete <identifier>', describe: `Delete a ${suite ? 'suite' : 'check'} definition after confirmation`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          await guardScope(app, record);
+          await confirmDelete(app, argv, `Delete scan ${suite ? 'suite' : 'check'} "${getStringField(record, 'name')}"?`);
+          const id = await deleteRecord(app.sdk, { table: suite ? baseTable : CHECK_TABLES[checkKind(record)], record });
+          report(app, argv, { sys_id: id, deleted: true }, { summary: 'Deleted scan definition', breadcrumbs: [hint('list', `jsn scan ${group} list`, 'Browse remaining definitions')] });
+        }) });
+      if (suite) for (const operation of ['add-check', 'remove-check']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation === 'add-check' ? 'Add a check to' : 'Remove a check from'} a suite`,
+        builder: p => lookupOptions(p).option('check', { type: 'string', demandOption: true, describe: 'Check name or sys_id' }),
+        handler: wrap(async (argv, app) => {
+          const suiteRecord = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const check = await resolveScanRecord(app.sdk, 'scan_check', argv.check);
+          await guardScope(app, suiteRecord);
+          const data = { suite: unwrapSysId(suiteRecord), check: unwrapSysId(check) };
+          const table = 'scan_check_suite_check';
+          const members = await scanList(app.sdk, table, { query: `suite=${data.suite}^check=${data.check}`, limit: 2 });
+          if (members.length > 1) throw errUsage('Duplicate suite memberships exist; inspect and reconcile them before changing membership.');
+          let changed = false;
+          if (operation === 'add-check' && !members.length) {
+            const member = await createRecord(app.sdk, { table, data });
+            await verify(app, table, unwrapSysId(member), data);
+            changed = true;
+          } else if (operation === 'remove-check' && members.length) {
+            await confirmDelete(app, argv, 'Remove this check from the suite? The check definition will be retained.');
+            await deleteRecord(app.sdk, { table, record: members[0] });
+            changed = true;
+          }
+          report(app, argv, { ...data, changed, member: operation === 'add-check' }, { summary: 'Suite membership reconciled', breadcrumbs: itemHints(group, suiteRecord) });
+        }),
+      });
+      return y;
+    },
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['list', 'show', 'create', 'update', 'delete', 'activate', 'deactivate', ...(suite ? ['add-check', 'remove-check'] : [])] }, {
+      summary: `Scan ${group}`, breadcrumbs: [hint('list', `jsn scan ${group} list`, `Browse ${group}`)],
+    })),
+  };
+}
+
+export function scanCmd(wrap) {
+  return {
+    command: 'scan [subcommand]', describe: 'Instance Scan checks, suites, explicit targets, progress and findings',
+    builder: y => y.command(definitions('checks', wrap)).command(definitions('suites', wrap))
+      .command({ command: 'run', describe: 'Start an explicit target scan (confirmation required; no implicit full scan)',
+        builder: p => p.option('update-set', { type: 'string', describe: 'Update set name or sys_id; scans current records' })
+          .option('scope', { type: 'string', describe: 'Application scope value or sys_id' })
+          .option('record', { type: 'string', describe: 'Record sys_id; requires --table' })
+          .option('table', { type: 'string', describe: 'Table for --record' })
+          .option('full', { type: 'boolean', describe: 'Explicitly allow an instance-wide scan' })
+          .option('previous', { type: 'string', describe: 'Rerun a previous execution target; full scans also require --full' })
+          .option('suite', { type: 'string', describe: 'Optional active suite name or sys_id' })
+          .option('wait', { type: 'boolean', default: false, describe: 'Wait for completion; timeout does not cancel the scan' })
+          .option('timeout', { type: 'number', default: 120, describe: 'Maximum wait in seconds (1–3600)' }),
+        handler: wrap(async (argv, app) => {
+          if (!Number.isFinite(argv.timeout) || argv.timeout < 1 || argv.timeout > 3600) throw errUsage('--timeout must be from 1 to 3600 seconds.');
+          const plan = await prepareScan(app.sdk, argv);
+          await confirmDelete(app, argv, `Start scan of ${plan.target.kind} ${plan.target.name || plan.target.sys_id || plan.target.execution_id || 'the full instance'}${plan.suite_id ? ` using suite ${plan.suite_id}` : ''}?`);
+          const scheduled = await startScan(app.sdk, plan);
+          let data = { ...scheduled, status: 'scheduled', terminal: false };
+          if (argv.wait) {
+            try {
+              const deadline = Date.now() + argv.timeout * 1000;
+              while (Date.now() < deadline) {
+                try {
+                  data = { ...scheduled, ...await scanStatus(app.sdk, scheduled.execution_id, { allowInitializing: true }) };
+                } catch (error) {
+                  if (error.code !== 'not_found' && error.status !== 404) throw error;
+                  // The processor can return before its execution tracker is visible.
+                  data = { ...scheduled, status: 'scheduled', terminal: false };
+                }
+                if (data.terminal) { data = { ...scheduled, ...await scanResults(app.sdk, scheduled.execution_id) }; break; }
+                await new Promise(resolve => setTimeout(resolve, Math.min(2000, Math.max(0, deadline - Date.now()))));
+              }
+              if (!data.terminal) data.wait_timed_out = true;
+            } catch (error) {
+              throw errAPI(error.status || 0, `Scan ${scheduled.execution_id} was scheduled, but progress could not be read: ${error.message}. Use jsn scan status ${scheduled.execution_id}; do not resubmit automatically.`);
+            }
+          }
+          const breadcrumbs = executionHints(data);
+          if (data.terminal && !data.reusable_target) breadcrumbs.push(hint('rerun', 'jsn scan run --help', 'Choose a target for another scan'));
+          report(app, argv, data, { summary: `Scan ${data.execution_id}: ${data.status}${data.wait_timed_out ? ' (still running; wait timed out)' : ''}`, breadcrumbs });
+        }) })
+      .command({ command: 'status <id>', describe: 'Read scan execution progress',
+        handler: wrap(async (argv, app) => {
+          const data = await scanStatus(app.sdk, argv.id);
+          report(app, argv, data, { summary: `Scan ${data.status}: ${data.message}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'results <id>', describe: 'Read findings and check execution coverage; unreadable data is not zero',
+        builder: p => p.option('limit', { type: 'number', default: 50, describe: 'Maximum findings/check rows (1–200); truncation is reported' }),
+        handler: wrap(async (argv, app) => {
+          const data = await scanResults(app.sdk, argv.id, boundedLimit(argv.limit));
+          report(app, argv, data, { summary: `Scan ${data.status}; ${data.findings_count ?? 'unknown'} findings; ${data.checks_executed ?? 'unknown'} recorded check executions${data.incomplete ? '; incomplete data' : ''}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'cancel <id>', describe: 'Request cancellation of this scan after confirmation',
+        handler: wrap(async (argv, app) => {
+          const status = await scanStatus(app.sdk, argv.id);
+          if (!status.terminal) await confirmDelete(app, argv, `Cancel scan ${argv.id}?`);
+          const data = status.terminal ? { ...status, cancellation_requested: false } : await cancelScan(app.sdk, argv.id);
+          report(app, argv, data, { summary: data.cancellation_requested ? `Cancellation requested: ${argv.id}` : 'Scan already finished; no cancellation sent', breadcrumbs: executionHints(data) });
+        }) }),
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['checks', 'suites', 'run', 'status', 'results', 'cancel'] }, { summary: 'Instance Scan', breadcrumbs: rootHints() })),
+  };
+}

package/src/commands/updatesets.js

@@ -365,6 +365,7 @@ export async function formatUpdateSetDetail(app, record) {
   const stateRaw = String(full.state?.value ?? full.state ?? '').toLowerCase();
   const isClosed = ['complete', 'committed'].includes(stateRaw);
   const hints = [];
+  hints.push({ action: 'scan', cmd: `jsn scan run --update-set ${sysID}${app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : ''}`, description: 'Offer an explicit scan of current records before completing or promoting this set' });
   if (isClosed) {
     hints.push({
       action: 'set',

package/src/help.js

@@ -132,6 +132,7 @@ const CONFIG_COMMANDS = [
 ];
 
 const DEVELOPER_COMMANDS = [
+  { name: 'scan', desc: 'Instance Scan checks, suites, explicit targets, progress and findings' },
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },

package/src/scan.js

@@ -0,0 +1,249 @@
+import { SaxesParser } from 'saxes';
+import { getRecord, recordListParams } from './records-engine.js';
+import { isSysId, unwrapSysId } from './resolve-record.js';
+import { errAPI, errNotFound, errUsage } from './errors.js';
+
+export const CHECK_TABLES = {
+  table: 'scan_table_check', column: 'scan_column_type_check',
+  linter: 'scan_linter_check', script: 'scan_script_only_check',
+};
+export const raw = value => value && typeof value === 'object' ? (value.value ?? '') : value;
+export const active = record => [true, 'true', '1', 1].includes(raw(record?.active));
+export const referenceId = value => {
+  const id = raw(value) || value?.link?.split('/').at(-1);
+  return isSysId(id) ? id : '';
+};
+
+export function requireId(value, label = 'execution') {
+  if (!isSysId(value)) throw errUsage(`Use a full 32-character sys_id for ${label}.`);
+  return value;
+}
+
+export function boundedLimit(value = 50) {
+  if (!Number.isInteger(value) || value < 1 || value > 200) throw errUsage('--limit must be an integer from 1 to 200.');
+  return value;
+}
+
+export async function scanList(sdk, table, { limit = 50, offset = 0, fields, query } = {}) {
+  boundedLimit(limit);
+  if (!Number.isInteger(offset) || offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+  const params = recordListParams({ limit, offset, fields, query, displayValue: 'false' });
+  return sdk.listStrict(table, params);
+}
+
+export async function resolveScanRecord(sdk, table, identifier, matchField = 'name') {
+  const record = await getRecord(sdk, { table, identifier, matchField, displayValues: 'raw', resource: table });
+  if (table !== 'scan_check') return record;
+  const subtype = String(raw(record.sys_class_name) || '');
+  if (!Object.values(CHECK_TABLES).includes(subtype)) return record;
+  const concrete = await sdk.get(subtype, unwrapSysId(record));
+  if (!concrete || unwrapSysId(concrete) !== unwrapSysId(record)) throw errUsage('The concrete check definition is unavailable; inspect its class and permissions before changing it.');
+  return { ...record, ...concrete };
+}
+
+const COMMON_FIELDS = ['name', 'description', 'short_description', 'active', 'category', 'priority',
+  'script', 'run_condition', 'finding_type', 'resolution_details', 'documentation_url', 'score_min', 'score_max', 'score_scale'];
+
+export function validateScanPayload(kind, input, { create = false, suite = false, current = {} } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw errUsage('The payload must be a JSON object.');
+  if (!suite && !CHECK_TABLES[kind]) throw errUsage('Choose --type table, column, linter, or script.');
+  const fields = suite ? ['name', 'description', 'active', 'private'] : [...COMMON_FIELDS,
+    ...(kind === 'table' ? ['table', 'conditions', 'advanced', 'use_manifest'] : []),
+    ...(kind === 'column' ? ['column_type'] : [])];
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field)) throw errUsage(`Unsupported ${suite ? 'suite' : kind + ' check'} field: ${field}`);
+  }
+  const data = { ...input };
+  for (const field of ['active', 'private', 'advanced', 'use_manifest']) {
+    if (data[field] === undefined) continue;
+    if (![true, false, 'true', 'false'].includes(data[field])) throw errUsage(`${field} must be true or false.`);
+    data[field] = data[field] === true || data[field] === 'true';
+  }
+  if ((create || data.name !== undefined) && (typeof data.name !== 'string' || !data.name.trim())) throw errUsage('A nonempty name is required.');
+  if (data.script !== undefined && typeof data.script !== 'string') throw errUsage('script must be a string.');
+  if (create && data.active === undefined) data.active = false;
+  if (data.table !== undefined && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(data.table)) throw errUsage('Invalid target table name.');
+  if (data.column_type !== undefined && !['script', 'xml', 'html'].includes(data.column_type)) throw errUsage('column_type must be script, xml, or html.');
+  if (!suite) {
+    const script = data.script ?? raw(current.script);
+    const advanced = data.advanced ?? active({ active: current.advanced });
+    if (create && kind === 'table' && !data.table) throw errUsage('Table checks require a table.');
+    if (create && kind === 'column' && !data.column_type) throw errUsage('Column checks require column_type.');
+    if ((create || Object.hasOwn(data, 'script') || Object.hasOwn(data, 'advanced'))
+      && (kind !== 'table' || advanced) && (typeof script !== 'string' || !script.trim())) {
+      throw errUsage('This check type requires a nonempty script.');
+    }
+  }
+  return data;
+}
+
+export function checkKind(record) {
+  const table = String(raw(record.sys_class_name) || '');
+  const kind = Object.keys(CHECK_TABLES).find(key => CHECK_TABLES[key] === table);
+  if (!kind) throw errUsage('Unknown or unreadable check class; inspect the check before changing it.');
+  return kind;
+}
+
+function decodeAjax(xml) {
+  let answer;
+  const parser = new SaxesParser();
+  parser.on('doctype', () => { throw errAPI(200, 'Unexpected document type in scan response.'); });
+  parser.on('opentag', node => { if (node.name === 'xml') answer = node.attributes.answer; });
+  try { parser.write(xml).close(); } catch { throw errAPI(200, 'Malformed scan processor XML response.'); }
+  if (typeof answer !== 'string') throw errAPI(200, 'Scan processor returned no answer; check endpoint access.');
+  return answer;
+}
+
+export async function scanAjax(sdk, method, parameters) {
+  const query = new URLSearchParams({ sysparm_processor: 'ScanAjaxProcessor', sysparm_name: method, ...parameters });
+  return decodeAjax(await sdk.rawRequest(`${sdk.baseURL}/xmlhttp.do?${query}`, { method: 'POST' }));
+}
+
+const TERMINAL = new Set(['successful', 'failed', 'cancelled']);
+const STATES = { '0': 'pending', '1': 'running', '2': 'successful', '3': 'failed', '4': 'cancelled',
+  pending: 'pending', running: 'running', successful: 'successful', failed: 'failed',
+  cancelled: 'cancelled', canceled: 'cancelled' };
+
+export async function scanStatus(sdk, id, { allowInitializing = false } = {}) {
+  requireId(id);
+  const tracker = await sdk.get('sys_execution_tracker', id);
+  if (!tracker) throw errNotFound('scan execution', id);
+  if (!raw(tracker.type) && allowInitializing) return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: null, message: 'Execution tracker is initializing', result_id: null };
+  if (raw(tracker.type) === 'sys.instance_scan.queue') return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: raw(tracker.percent_complete) ?? null, message: raw(tracker.message) || 'Scan is queued', result_id: null };
+  if (raw(tracker.type) !== 'instance_scan') throw errUsage('This execution tracker is not an Instance Scan.');
+  const state = STATES[String(raw(tracker.state)).toLowerCase()] || 'unknown';
+  let resultId = '';
+  if (raw(tracker.result)) {
+    try { resultId = referenceId(JSON.parse(raw(tracker.result)).result_id); } catch { /* reported as unavailable below */ }
+  }
+  return { execution_id: id, status: state, terminal: TERMINAL.has(state),
+    percent_complete: raw(tracker.percent_complete) ?? null,
+    message: raw(tracker.message) || '', result_id: resultId || null };
+}
+
+async function resolveSuite(sdk, identifier) {
+  const suite = await resolveScanRecord(sdk, 'scan_check_suite', identifier);
+  if (!active(suite)) throw errUsage('The selected suite is inactive or its active state is unreadable. Activate it explicitly first.');
+  return unwrapSysId(suite);
+}
+
+export async function prepareScan(sdk, argv) {
+  const previous = argv.previous;
+  const updateSet = argv.updateSet ?? argv['update-set'];
+  for (const value of [previous, updateSet, argv.scope, argv.record, argv.suite]) {
+    if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw errUsage('Scan target and suite identifiers must be nonempty strings.');
+  }
+  const selectors = [updateSet, argv.scope, argv.record, previous].filter(value => value !== undefined).length;
+  if (selectors + Number(Boolean(argv.full)) !== 1 && !(previous && argv.full && selectors === 1)) {
+    throw errUsage('Choose exactly one target: --update-set, --scope, --record with --table, --full, or --previous.');
+  }
+  if (Boolean(argv.table) !== Boolean(argv.record)) throw errUsage('--record and --table must be supplied together.');
+  if (previous && argv.suite) throw errUsage('--previous preserves its source suite; do not combine it with --suite.');
+  let target;
+  if (previous) {
+    const status = await scanStatus(sdk, previous);
+    if (!status.terminal || !status.result_id) throw errUsage('The previous scan must have finished and have a readable result.');
+    const result = await sdk.get('scan_result', status.result_id);
+    const comboId = referenceId(result?.combo);
+    if (!comboId) throw errUsage('The previous scan has no reusable target combination. Choose an explicit target.');
+    const combo = await sdk.get('scan_combo', comboId);
+    if (!combo) throw errUsage('The previous scan combination is unavailable.');
+    if (!raw(combo.targets) && !argv.full) throw errUsage('The previous scan was instance-wide. Repeat with --full to approve that breadth.');
+    target = { kind: 'previous', execution_id: previous, combo_id: comboId, full: !raw(combo.targets) };
+  } else if (updateSet !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_update_set', updateSet);
+    target = { kind: 'update_set', sys_id: unwrapSysId(record), name: raw(record.name),
+      note: 'Scans current instance records referenced by this update set, not historical XML versions. Script-only checks do not participate.' };
+  } else if (argv.scope !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_scope', argv.scope, 'scope');
+    target = { kind: 'scope', sys_id: unwrapSysId(record), name: raw(record.scope) };
+  } else if (argv.record !== undefined) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(argv.table)) throw errUsage('Invalid target table.');
+    const record = await resolveScanRecord(sdk, argv.table, argv.record, 'sys_id');
+    target = { kind: 'record', table: argv.table, sys_id: unwrapSysId(record),
+      inactive: raw(record.active) === false || raw(record.active) === 'false',
+      note: 'Inactive target records may be skipped by the scan engine. Script-only checks do not participate.' };
+  } else target = { kind: 'full', note: 'Instance-wide scans can traverse many tables and take substantially longer.' };
+  if (!target.sys_id && !['full', 'previous'].includes(target.kind)) throw errUsage('The target has no readable sys_id.');
+  const suiteId = argv.suite ? await resolveSuite(sdk, argv.suite) : null;
+  return { target, suite_id: suiteId };
+}
+
+export async function startScan(sdk, plan) {
+  const { target, suite_id: suite } = plan;
+  let response;
+  if (suite && ['update_set', 'scope'].includes(target.kind)) {
+    const kind = target.kind === 'scope' ? 'scoped_apps' : 'update_sets';
+    const field = target.kind === 'scope' ? 'app_scope_sys_ids' : 'update_set_sys_ids';
+    const data = await sdk.request(`${sdk.baseURL}/api/sn_cicd/instance_scan/suite_scan/${requireId(suite, 'suite')}/${kind}`, {
+      method: 'POST', body: JSON.stringify({ [field]: [target.sys_id] }),
+    });
+    response = data?.result;
+    if (response?.error || !['0', '1', '2'].includes(String(response?.status))) throw errAPI(200, 'Scan dispatch was rejected by the provider.');
+    const executionId = response?.links?.progress?.id;
+    if (!isSysId(executionId)) throw errAPI(200, 'Scan dispatch returned no valid execution id. Inspect existing scans before retrying.');
+    return { execution_id: executionId, via: 'sn_cicd', ...plan };
+  }
+  let method, parameters;
+  if (target.kind === 'previous') { method = 'executeScanFromCombo'; parameters = { sysparm_combo_id: target.combo_id }; }
+  else if (suite && target.kind === 'full') { method = 'executeSuiteScan'; parameters = { sysparm_sys_id: suite }; }
+  else if (suite) {
+    method = 'executeSuiteScanWithTargets'; parameters = { sysparm_suite_sys_id: suite,
+      sysparm_target_table: target.table, sysparm_target_sys_ids: JSON.stringify([target.sys_id]) };
+  } else if (target.kind === 'update_set') { method = 'executeUpdateSetScan'; parameters = { sysparm_sys_id: target.sys_id }; }
+  else if (target.kind === 'scope') { method = 'executeAppScan'; parameters = { sysparm_scope_id: target.sys_id }; }
+  else if (target.kind === 'record') { method = 'executePointScan'; parameters = { sysparm_sys_id: target.sys_id, sysparm_table_name: target.table }; }
+  else { method = 'executeFullScan'; parameters = {}; }
+  try { response = JSON.parse(await scanAjax(sdk, method, parameters)); }
+  catch (error) { if (error.code) throw error; throw errAPI(200, 'Malformed scan dispatch answer. Inspect existing scans before retrying.'); }
+  if (response.status !== 0 || !isSysId(response.progressId)) throw errAPI(200, 'Scan dispatch failed or returned no valid execution id. Inspect existing scans before retrying.');
+  return { execution_id: response.progressId, via: 'ScanAjaxProcessor', ...plan };
+}
+
+export async function scanResults(sdk, id, limit = 50) {
+  boundedLimit(limit);
+  const status = await scanStatus(sdk, id);
+  const data = { ...status, checks_executed: null, findings_count: null, checks: [], findings: [],
+    incomplete: !status.terminal, unavailable: [], truncated: {}, rerun_full: false, reusable_target: false };
+  if (!status.result_id) { data.unavailable.push('scan_result'); data.incomplete = true; return data; }
+  let result;
+  try {
+    result = await sdk.get('scan_result', status.result_id);
+    if (!result) throw new Error('Result unavailable');
+    data.scan_number = raw(result.number);
+    const value = raw(result.finding_count);
+    const count = Number(value);
+    if ((typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value))) && Number.isInteger(count) && count >= 0) data.findings_count = count;
+    else { data.unavailable.push('scan_result.finding_count'); data.incomplete = true; }
+  } catch { data.unavailable.push('scan_result'); data.incomplete = true; }
+  for (const [key, table, fields] of [
+    ['checks', 'scan_check_execution', ['check', 'message', 'execution_time']],
+    ['findings', 'scan_finding', ['check', 'source_table', 'source', 'finding_details', 'count']],
+  ]) {
+    try {
+      const rows = await sdk.listStrict(table, recordListParams({ limit: limit + 1,
+        query: `result=${status.result_id}^ORDERBYsys_id`, fields, displayValue: 'all' }));
+      data[key] = rows.slice(0, limit);
+      data.truncated[key] = rows.length > limit;
+      if (key === 'checks' && !data.truncated[key] && status.terminal) data.checks_executed = rows.length;
+    } catch { data.unavailable.push(table); data.incomplete = true; }
+  }
+  const comboId = referenceId(result?.combo);
+  if (comboId) {
+    try { const combo = await sdk.get('scan_combo', comboId); if (combo) { data.reusable_target = true; data.rerun_full = !raw(combo.targets); } }
+    catch { /* Optional rerun hint is omitted when target metadata is inaccessible. */ }
+  }
+  data.coverage_note = 'Execution success does not prove functional correctness or complete coverage. Zero findings may mean records or checks were skipped.';
+  return data;
+}
+
+export async function cancelScan(sdk, id) {
+  const status = await scanStatus(sdk, id);
+  if (status.terminal) return { ...status, cancellation_requested: false };
+  const answer = await scanAjax(sdk, 'cancelScan', { sysparm_progress_id: id });
+  const after = await scanStatus(sdk, id);
+  if (after.status !== 'cancelled' && !/cancelled successfully/i.test(answer)) throw errAPI(200, 'Cancellation was not confirmed. Check the execution status before retrying.');
+  return { ...after, cancellation_requested: true };
+}