@jacebenson/jsn 4.3.8 → 4.3.9-dev.62

package/src/flow-create.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { withFlowSafeEdit } from './flow-safe-edit.js';
 import { assertSafeExactMatch } from './helpers.js';
 import { createVerifiedFlowVersion } from './flow-versioning.js';
 import {
@@ -493,6 +495,15 @@ function wrappedValue(value) {
   return { schemaless: false, schemalessValue: '', value };
 }
 
+function maskInputValue(input) {
+  const copy = clone(input);
+  for (const field of ['value', 'displayValue']) {
+    if (copy[field] && typeof copy[field] === 'object' && Object.hasOwn(copy[field], 'value')) copy[field].value = null;
+    else if (Object.hasOwn(copy, field)) copy[field] = null;
+  }
+  return copy;
+}
+
 function buildActionUpdate(existing, requested, index) {
   const existingInputs = new Set(inputList(existing).map(input => stringValue(input?.name)));
   for (const name of Object.keys(requested.inputs)) {
@@ -555,7 +566,7 @@ function readFlowRecord(sdk, identifier) {
   if (!exactIdentifier) throw new Error('Flow identifier must be an exact sys_id or name');
   assertSafeExactMatch(exactIdentifier);
   const query = isSysId(exactIdentifier) ? `sys_id=${exactIdentifier}` : `name=${exactIdentifier}`;
-  return sdk.list('sys_hub_flow', new URLSearchParams({ sysparm_query: query, sysparm_limit: '2', sysparm_display_value: 'all', sysparm_fields: 'sys_id,name,scope,active,status,type' }));
+  return sdk.list('sys_hub_flow', new URLSearchParams({ sysparm_query: query, sysparm_limit: '2', sysparm_display_value: 'all', sysparm_fields: 'sys_id,name,sys_scope,scope,active,status,type,sys_updated_on' }));
 }
 
 async function resolveDraftFlow(sdk, identifier) {
@@ -565,11 +576,12 @@ async function resolveDraftFlow(sdk, identifier) {
   const flowId = idValue(flow.sys_id);
   const flowName = stringValue(flow.name);
   if (flowId === PROTECTED_FLOW_ID || flowName === PROTECTED_FLOW_NAME) throw new Error(`Protected flow ${PROTECTED_FLOW_NAME} cannot be updated`);
-  if (String(flow.active?.value ?? flow.active ?? '').toLowerCase() === 'true' || String(flow.status?.value ?? flow.status ?? '').toLowerCase() !== 'draft') throw new Error(`Flow ${flowId} is not an inactive Draft; refusing update`);
+  if (String(flow.active?.value ?? flow.active ?? '').toLowerCase() !== 'false' || String(flow.status?.value ?? flow.status ?? '').toLowerCase() !== 'draft') throw new Error(`Flow ${flowId} is not an inactive Draft; refusing update. Published checkout is not verified by this CLI. Use Flow Designer to check out and edit published flows; save, publish and execution are separate operations.`);
   return { flow, flowId, flowName };
 }
 
 function updatedTrigger(flow, manifest, descriptor) {
+  if (findArray(flow, 'triggerInstances').length !== 1) throw new Error('Saved flow must have exactly one trigger for trigger updates');
   const existing = clone(findArray(flow, 'triggerInstances')[0]);
   if (!existing) throw new Error('Saved flow has no trigger instance');
   const existingMetadata = parseMaybeJson(existing.metadata, null);
@@ -595,14 +607,23 @@ function updatedTrigger(flow, manifest, descriptor) {
   }
   const id = findId(existing, ['sysId', 'sys_id', 'id', 'triggerId']);
   if (!id) throw new Error('Saved record trigger has no usable identity');
-  const update = { id, inputs };
+  const changed = inputs.filter(input => manifest.trigger[input.name] !== undefined);
+  const update = { id, inputs: changed.map(input => ({
+    ...(input.id ? { id: input.id } : {}),
+    name: input.name,
+    displayField: input.displayField,
+    scriptActive: input.scriptActive,
+    ...(input.parameter ? { parameter: flowDesignParameter(input.parameter) } : {}),
+    value: input.value,
+    displayValue: input.displayValue,
+  })) };
   if (manifest.trigger.condition !== undefined) {
     // The instance re-derives predicate metadata from the condition input; see
     // DEFAULT_TRIGGER_METADATA. The read-back check below still proves the
     // derived predicate matches what was asked for.
     update.metadata = DEFAULT_TRIGGER_METADATA;
   } else if (Object.prototype.hasOwnProperty.call(existing, 'metadata')) {
-    update.metadata = existing.metadata;
+    update.metadata = typeof existing.metadata === 'string' ? existing.metadata : JSON.stringify(existing.metadata);
   }
   return { update, currentTable: table };
 }
@@ -771,16 +792,26 @@ export async function updateFlowFromManifest(sdk, instance, identifier, inputMan
   const manifest = validateFlowUpdateManifest(inputManifest);
   const target = await resolveDraftFlow(sdk, identifier);
   const flowId = target.flowId;
-  const scope = stringValue(manifest.scope ?? target.flow.scope);
+  const targetScope = stringValue(target.flow.sys_scope) || stringValue(target.flow.scope);
+  const scope = manifest.scope ?? targetScope;
   const readUpdateSet = options.readUpdateSet || (async () => null);
   if (!scope) throw new Error(`Flow ${flowId} has no transaction scope`);
-  if (manifest.scope !== undefined && stringValue(target.flow.scope) && manifest.scope !== stringValue(target.flow.scope)) throw new Error(`Flow ${flowId} scope does not match the update manifest`);
-  const beforeDefinition = await readProcessFlow(sdk, instance, flowId, scope);
+  if (manifest.scope !== undefined && targetScope && manifest.scope !== targetScope) throw new Error(`Flow ${flowId} scope does not match the update manifest`);
+  let beforeDefinition = await readProcessFlow(sdk, instance, flowId, scope);
+  // A legacy ProcessFlow read can expose the preceding version's timestamp
+  // immediately after Autosave. Never substitute the newer Table timestamp into
+  // an older definition: reread the whole document, then let safeEdit check it.
+  const recordUpdated = stringValue(target.flow.sys_updated_on);
+  if (recordUpdated && beforeDefinition.updated !== recordUpdated) {
+    beforeDefinition = await readProcessFlow(sdk, instance, flowId, scope);
+    if (beforeDefinition.updated !== recordUpdated) throw new Error(`Flow ${flowId} definition is stale relative to its record; no edit session or content mutation attempted`);
+  }
   const snapshots = [];
   const triggerUpdates = [];
   const actionUpdates = [];
   const changedActionInputs = new Map();
   const actionTargets = new Map();
+  const changes = [];
   let triggerUpdate;
   if (manifest.trigger !== undefined) {
     const currentTrigger = findArray(beforeDefinition, 'triggerInstances')[0];
@@ -790,6 +821,9 @@ export async function updateFlowFromManifest(sdk, instance, identifier, inputMan
       : await readTableDescriptor(sdk, manifest.trigger.table ?? currentTable);
     triggerUpdate = updatedTrigger(beforeDefinition, manifest, descriptor).update;
     triggerUpdates.push(triggerUpdate);
+    for (const input of ['table', 'condition']) {
+      if (manifest.trigger[input] !== undefined) changes.push({ component: 'trigger', input, before: inputRawValue(inputList(currentTrigger).find(field => field.name === input)), after: manifest.trigger[input] });
+    }
   }
   const existingActions = findExistingActions(beforeDefinition);
   for (const [index, requested] of (manifest.actions || []).entries()) {
@@ -797,78 +831,110 @@ export async function updateFlowFromManifest(sdk, instance, identifier, inputMan
     const update = buildActionUpdate(existing, requested, index);
     actionUpdates.push(update);
     const uiId = stringValue(existing.uiUniqueIdentifier || existing.ui_unique_identifier);
+    if (actionTargets.has(uiId)) throw new Error(`Duplicate action update for order ${requested.order}; combine input changes in one action entry`);
     actionTargets.set(uiId, existing);
     changedActionInputs.set(uiId, new Set(Object.keys(requested.inputs)));
+    for (const [input, after] of Object.entries(requested.inputs)) changes.push({ component: 'action', order: requested.order, type: requested.type, input, before: inputRawValue(inputList(existing).find(field => field.name === input)), after });
   }
   if (triggerUpdates.length === 0 && actionUpdates.length === 0) throw new Error(`Flow ${flowId} update has no supported changes`);
-
-  try {
-    const patchResponse = await mutationContext('trigger_and_actions_update', readUpdateSet, snapshots, () => sdk.request(`${instance}${GRAPHQL_ENDPOINT}`, {
-      method: 'POST',
-      body: JSON.stringify({ query: buildFlowUpdateMutation({ flowId, triggerUpdates, actionUpdates }), variables: {} }),
-    }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
-    assertGraphQLSuccess(patchResponse, 'Flow trigger/action update');
-    const processflow = await readProcessFlow(sdk, instance, flowId, scope);
-    const readbackTrigger = findArray(processflow, 'triggerInstances')[0];
-    if (triggerUpdate) {
-      if (!readbackTrigger || findId(readbackTrigger, ['sysId', 'sys_id', 'id', 'triggerId']) !== triggerUpdate.id) throw new Error(`Flow ${flowId} trigger update was not readable after mutation`);
-      const beforeTrigger = findArray(beforeDefinition, 'triggerInstances')[0];
-      const preserveBefore = { ...beforeTrigger, inputs: undefined, metadata: undefined };
-      const preserveAfter = { ...readbackTrigger, inputs: undefined, metadata: undefined };
-      if (JSON.stringify(preserveBefore) !== JSON.stringify(preserveAfter)) throw new Error(`Flow ${flowId} trigger readback changed fields omitted by the manifest`);
-      const readbackInputs = inputList(readbackTrigger);
-      const beforeInputs = inputList(beforeTrigger);
-      if (readbackInputs.length !== beforeInputs.length) throw new Error(`Flow ${flowId} trigger input count changed during update`);
-      const requestedInputs = new Set();
-      if (manifest.trigger.table !== undefined) requestedInputs.add('table');
-      if (manifest.trigger.condition !== undefined) requestedInputs.add('condition');
-      for (const beforeInput of beforeInputs) {
-        const afterInput = readbackInputs.find(input => input.name === beforeInput.name);
-        if (!afterInput) throw new Error(`Flow ${flowId} trigger lost input ${beforeInput.name} during update`);
-        if (!requestedInputs.has(beforeInput.name) && JSON.stringify(beforeInput) !== JSON.stringify(afterInput)) throw new Error(`Flow ${flowId} trigger changed omitted input ${beforeInput.name}`);
+  if (options.preview) return { preview: true, flow: { id: flowId, name: target.flowName, status: 'draft', active: false }, changes, lifecycle: { published: false, executed: false } };
+
+  return withFlowSafeEdit(sdk, instance, flowId, beforeDefinition.updated, async () => {
+    let completedStage = 'validated';
+    try {
+      const patchResponse = await mutationContext('trigger_and_actions_update', readUpdateSet, snapshots, () => sdk.request(`${instance}${GRAPHQL_ENDPOINT}`, {
+        method: 'POST',
+        body: JSON.stringify({ query: buildFlowUpdateMutation({ flowId, triggerUpdates, actionUpdates }), variables: {} }),
+      }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
+      assertGraphQLSuccess(patchResponse, 'Flow trigger/action update');
+      completedStage = 'patch_acknowledged';
+      const processflow = await readProcessFlow(sdk, instance, flowId, scope);
+      // Only requested values may differ. Preserve array order and opaque fields.
+      for (const field of ['flowVariables', 'flowLogicInstances', 'subFlowInstances', 'flowInputs', 'flowOutputs', 'inputs', 'outputs', 'stages']) {
+        if (!isDeepStrictEqual(beforeDefinition[field], processflow[field])) throw new Error(`Flow ${flowId} changed omitted ${field}; preservation failed`);
       }
-      if (manifest.trigger.table !== undefined && inputRawValue(readbackInputs.find(input => input.name === 'table')) !== manifest.trigger.table) throw new Error(`Flow ${flowId} trigger table readback did not match the requested value`);
-      if (manifest.trigger.condition !== undefined) {
-        if (inputRawValue(readbackInputs.find(input => input.name === 'condition')) !== manifest.trigger.condition) throw new Error(`Flow ${flowId} trigger condition readback did not match the requested value`);
-        assertPredicateMetadataMatches(readbackTrigger.metadata, manifest.trigger.condition, `Flow ${flowId} trigger`);
-        const beforeMetadata = stripPredicates(parseMaybeJson(beforeTrigger.metadata, {}));
-        const afterMetadata = stripPredicates(parseMaybeJson(readbackTrigger.metadata, {}));
-        if (JSON.stringify(beforeMetadata) !== JSON.stringify(afterMetadata)) throw new Error(`Flow ${flowId} trigger metadata changed fields omitted by the manifest`);
-      } else if (JSON.stringify(parseMaybeJson(beforeTrigger.metadata, {})) !== JSON.stringify(parseMaybeJson(readbackTrigger.metadata, {}))) {
-        throw new Error(`Flow ${flowId} trigger metadata changed when the condition was omitted`);
+      if (!triggerUpdate && !isDeepStrictEqual(beforeDefinition.triggerInstances, processflow.triggerInstances)) throw new Error(`Flow ${flowId} changed omitted triggerInstances`);
+      const maskActions = definition => findExistingActions(definition).map(action => {
+        const copy = clone(action);
+        const changed = changedActionInputs.get(stringValue(action.uiUniqueIdentifier || action.ui_unique_identifier));
+        for (const [index, input] of inputList(copy).entries()) if (changed?.has(input.name)) inputList(copy)[index] = maskInputValue(input);
+        return copy;
+      });
+      if (!isDeepStrictEqual(maskActions(beforeDefinition), maskActions(processflow))) throw new Error(`Flow ${flowId} changed omitted action fields; preservation failed`);
+      const readbackTrigger = findArray(processflow, 'triggerInstances')[0];
+      if (triggerUpdate) {
+        if (!readbackTrigger || findId(readbackTrigger, ['sysId', 'sys_id', 'id', 'triggerId']) !== triggerUpdate.id) throw new Error(`Flow ${flowId} trigger update was not readable after mutation`);
+        const beforeTrigger = findArray(beforeDefinition, 'triggerInstances')[0];
+        const preserveBefore = { ...beforeTrigger, inputs: undefined, metadata: undefined };
+        const preserveAfter = { ...readbackTrigger, inputs: undefined, metadata: undefined };
+        if (JSON.stringify(preserveBefore) !== JSON.stringify(preserveAfter)) throw new Error(`Flow ${flowId} trigger readback changed fields omitted by the manifest`);
+        const readbackInputs = inputList(readbackTrigger);
+        const beforeInputs = inputList(beforeTrigger);
+        if (readbackInputs.length !== beforeInputs.length) throw new Error(`Flow ${flowId} trigger input count changed during update`);
+        const requestedInputs = new Set();
+        if (manifest.trigger.table !== undefined) requestedInputs.add('table');
+        if (manifest.trigger.condition !== undefined) requestedInputs.add('condition');
+        const maskTriggerInputs = inputs => inputs.map(input => {
+          if (!requestedInputs.has(input.name)) return input;
+          const copy = maskInputValue(input);
+          delete copy.displayField;
+          // Live table saves materialize only this absent display label as ''.
+          // Do not collapse named values, defaults or arbitrary empty fields.
+          if (copy.parameter?.type_label === '') delete copy.parameter.type_label;
+          return copy;
+        });
+        if (!isDeepStrictEqual(maskTriggerInputs(beforeInputs), maskTriggerInputs(readbackInputs))) throw new Error(`Flow ${flowId} trigger input preservation failed`);
+        for (const beforeInput of beforeInputs) {
+          const afterInput = readbackInputs.find(input => input.name === beforeInput.name);
+          if (!afterInput) throw new Error(`Flow ${flowId} trigger lost input ${beforeInput.name} during update`);
+          if (!requestedInputs.has(beforeInput.name) && JSON.stringify(beforeInput) !== JSON.stringify(afterInput)) throw new Error(`Flow ${flowId} trigger changed omitted input ${beforeInput.name}`);
+        }
+        if (manifest.trigger.table !== undefined && inputRawValue(readbackInputs.find(input => input.name === 'table')) !== manifest.trigger.table) throw new Error(`Flow ${flowId} trigger table readback did not match the requested value`);
+        if (manifest.trigger.condition !== undefined) {
+          if (inputRawValue(readbackInputs.find(input => input.name === 'condition')) !== manifest.trigger.condition) throw new Error(`Flow ${flowId} trigger condition readback did not match the requested value`);
+          assertPredicateMetadataMatches(readbackTrigger.metadata, manifest.trigger.condition, `Flow ${flowId} trigger`);
+          const beforeMetadata = stripPredicates(parseMaybeJson(beforeTrigger.metadata, {}));
+          const afterMetadata = stripPredicates(parseMaybeJson(readbackTrigger.metadata, {}));
+          if (JSON.stringify(beforeMetadata) !== JSON.stringify(afterMetadata)) throw new Error(`Flow ${flowId} trigger metadata changed fields omitted by the manifest`);
+        } else if (JSON.stringify(parseMaybeJson(beforeTrigger.metadata, {})) !== JSON.stringify(parseMaybeJson(readbackTrigger.metadata, {}))) {
+          throw new Error(`Flow ${flowId} trigger metadata changed when the condition was omitted`);
+        }
       }
-    }
-    const readbackActions = findExistingActions(processflow);
-    for (const update of actionUpdates) {
-      const uiId = stringValue(update.uiUniqueIdentifier);
-      const readback = readbackActions.find(action => stringValue(action.uiUniqueIdentifier || action.ui_unique_identifier) === uiId);
-      if (!readback) throw new Error(`Flow ${flowId} Action ${uiId} was not readable after mutation`);
-      const before = actionTargets.get(uiId);
-      const changed = changedActionInputs.get(uiId) || new Set();
-      for (const input of inputList(before)) {
-        const afterInput = inputList(readback).find(candidate => candidate.name === input.name);
-        if (!afterInput) throw new Error(`Flow ${flowId} Action ${uiId} lost input ${input.name} during update`);
-        if (!changed.has(input.name) && JSON.stringify(input) !== JSON.stringify(afterInput)) throw new Error(`Flow ${flowId} Action ${uiId} changed omitted input ${input.name}`);
-        if (changed.has(input.name) && inputRawValue(afterInput) !== inputRawValue(update.inputs.find(candidate => candidate.name === input.name))) throw new Error(`Flow ${flowId} Action ${uiId} input ${input.name} did not match the requested value`);
+      const readbackActions = findExistingActions(processflow);
+      for (const update of actionUpdates) {
+        const uiId = stringValue(update.uiUniqueIdentifier);
+        const readback = readbackActions.find(action => stringValue(action.uiUniqueIdentifier || action.ui_unique_identifier) === uiId);
+        if (!readback) throw new Error(`Flow ${flowId} Action ${uiId} was not readable after mutation`);
+        const before = actionTargets.get(uiId);
+        const changed = changedActionInputs.get(uiId) || new Set();
+        for (const input of inputList(before)) {
+          const afterInput = inputList(readback).find(candidate => candidate.name === input.name);
+          if (!afterInput) throw new Error(`Flow ${flowId} Action ${uiId} lost input ${input.name} during update`);
+          if (!changed.has(input.name) && JSON.stringify(input) !== JSON.stringify(afterInput)) throw new Error(`Flow ${flowId} Action ${uiId} changed omitted input ${input.name}`);
+          if (changed.has(input.name) && inputRawValue(afterInput) !== inputRawValue(update.inputs.find(candidate => candidate.name === input.name))) throw new Error(`Flow ${flowId} Action ${uiId} input ${input.name} did not match the requested value`);
+        }
       }
+      completedStage = 'definition_verified';
+      const { version } = await mutationContext('autosave_version', readUpdateSet, snapshots, () => createVerifiedFlowVersion(sdk, {
+        instance, flowId, scope, type: 'Autosave', annotation: 'JSN flow update',
+      }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
+      completedStage = 'autosave_verified';
+      const selectedUpdateSet = await readUpdateSet();
+      const updateSetCapture = await readUpdateSetCapture(sdk, selectedUpdateSet, flowId);
+      return {
+        flow: { id: flowId, name: target.flowName, status: 'draft', active: false },
+        changes,
+        processflow,
+        definition_readback: { available: true, status: 'read_back', flow_id: flowId },
+        version,
+        update_set_capture: updateSetCapture,
+        update_set_mutations: snapshots,
+        lifecycle: { published: false, supported: ['draft', 'autosave'], deferred: ['publish/activation', 'Flow Logic', 'subflows', 'flow variables', 'error handling'] },
+      };
+    } catch (error) {
+      throw new Error(`Flow ${flowId} update incomplete; last completed stage: ${completedStage}. Changes may already be persisted; inspect this exact flow before retrying. No rollback, publish or execution attempted. ${error.message}; reconciliation: ${JSON.stringify(snapshots)}`, { cause: error });
     }
-    const { version } = await mutationContext('autosave_version', readUpdateSet, snapshots, () => createVerifiedFlowVersion(sdk, {
-      instance, flowId, scope, type: 'Autosave', annotation: 'JSN flow update',
-    }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
-    const selectedUpdateSet = await readUpdateSet();
-    const updateSetCapture = await readUpdateSetCapture(sdk, selectedUpdateSet, flowId);
-    return {
-      flow: { id: flowId, name: target.flowName, status: 'draft', active: false },
-      processflow,
-      definition_readback: { available: true, status: 'read_back', flow_id: flowId },
-      version,
-      update_set_capture: updateSetCapture,
-      update_set_mutations: snapshots,
-      lifecycle: { published: false, supported: ['draft', 'autosave'], deferred: ['publish/activation', 'Flow Logic', 'subflows', 'flow variables', 'error handling'] },
-    };
-  } catch (error) {
-    throw new Error(`Flow ${flowId} update incomplete: ${error.message}; reconciliation: ${JSON.stringify(snapshots)}`, { cause: error });
-  }
+  });
 }
 
 export async function readCurrentUpdateSet(sdk) {

package/src/flow-designer-interactive.js

@@ -370,7 +370,7 @@ export async function savedFlowDefinition(app, identifier) {
   const { resolveRecord, unwrapSysId } = await import('./resolve-record.js');
   const record = await resolveRecord(app.sdk, { table: 'sys_hub_flow', identifier, matchField: 'name', resource: 'flow' });
   const id = unwrapSysId(record);
-  const scope = rawField(record.scope);
+  const scope = rawField(record.sys_scope) || rawField(record.scope);
   if (!scope) throw errUsage('Saved flow has no raw transaction scope');
   return { record, definition: await readProcessFlow(app.sdk, app.getEffectiveInstance(), id, scope) };
 }
@@ -396,7 +396,7 @@ export async function guidedFlowEdit(argv, app) {
     const actionType = rawField(action.actionTypeSysId || action.action_type_sys_id || action.actionType?.sys_id || action.actionType?.sysId);
     let inputSchema = { ...field, type: field.type || field.parameter?.type };
     if (!inputSchema.type) {
-      const { schema } = await readActionDefinition(app.sdk, app.getEffectiveInstance(), actionType, rawField(record.scope), { requireTypes: true });
+      const { schema } = await readActionDefinition(app.sdk, app.getEffectiveInstance(), actionType, rawField(record.sys_scope) || rawField(record.scope), { requireTypes: true });
       inputSchema = schema.find(candidate => candidate.name === field.name);
       if (!inputSchema) throw errUsage(`Saved action input ${field.name} is absent from its provider schema`);
     }

package/src/flow-publish.js

@@ -80,9 +80,21 @@ export async function publishFlows(sdk, flowIDs = [], actionIDs = []) {
 /** Publish one flow through the ProcessFlow snapshot/version lifecycle. */
 export async function publishFlowLifecycle(sdk, instance, flowId) {
   const flowRecord = sdk.get ? await sdk.get('sys_hub_flow', flowId) : null;
-  const scope = str(flowRecord, 'scope');
-  if (!scope) throw new Error(`Flow ${flowId} has no transaction scope; refusing to publish`);
-  const definitionResponse = await sdk.request(`${instance}${PROCESSFLOW_PATH}/${encodeURIComponent(flowId)}?sysparm_transaction_scope=${encodeURIComponent(scope)}`, { method: 'GET' });
+  const flowPath = `${instance}${PROCESSFLOW_PATH}/${encodeURIComponent(flowId)}`;
+  // sys_hub_flow.scope is often omitted by the Table API for newly created
+  // flows. The ProcessFlow definition carries the application scope needed by
+  // its snapshot and version endpoints, so read it before constructing either.
+  let scope = str(flowRecord, 'scope');
+  let definitionResponse;
+  if (!scope) {
+    definitionResponse = await sdk.request(flowPath, { method: 'GET' });
+    const initialDefinition = definitionResponse?.result?.data ?? definitionResponse?.data?.result?.data ?? definitionResponse?.data ?? definitionResponse?.result ?? definitionResponse;
+    scope = str(initialDefinition, 'scope');
+    if (!scope) throw new Error(`Flow ${flowId} has no transaction scope; refusing to publish`);
+  }
+  if (!definitionResponse) {
+    definitionResponse = await sdk.request(`${flowPath}?sysparm_transaction_scope=${encodeURIComponent(scope)}`, { method: 'GET' });
+  }
   const definition = definitionResponse?.result?.data ?? definitionResponse?.data?.result?.data ?? definitionResponse?.data ?? definitionResponse?.result ?? definitionResponse;
   if (!definition || typeof definition !== 'object') throw new Error(`Flow definition could not be read for ${flowId}`);
   const definitionScope = str(definition, 'scope');

package/src/flow-safe-edit.js

@@ -0,0 +1,48 @@
+// Flow Designer's safeEdit lease is separate from publishing and artifact deletion.
+// The provider exposes a user-level lock, not an operation token: refuse even a
+// same-user existing lease so this CLI cannot release an open designer session.
+export async function flowSafeEditRequest(sdk, instance, flowId, operation, lastUpdated) {
+  const id = JSON.stringify(flowId);
+  const input = operation === 'upsert' ? `upsert:{flowId:${id} lastUpdated:${JSON.stringify(lastUpdated)}}` : `${operation}:${id}`;
+  const selection = operation === 'delete' ? 'deleteResult{deleteSuccess id}' : `status{canUserEdit currentEditor${operation === 'upsert' ? ' clientFlowStale' : ''}}`;
+  const query = `${operation === 'read' ? 'query' : 'mutation'} {global {snFlowDesigner {safeEdit(safeEditInput:{${input}}){${selection}}}}}`;
+  const response = await sdk.request(`${instance}/api/now/graphql`, { method: 'POST', body: JSON.stringify({ query, variables: {} }) });
+  if (response.errors?.length) throw new Error(`Flow safe edit ${operation}: ${response.errors.map(error => error.message).join('; ')}`);
+  const result = response.data?.global?.snFlowDesigner?.safeEdit;
+  if (!result) throw new Error(`Flow safe edit ${operation} returned no result`);
+  return result;
+}
+
+export async function withFlowSafeEdit(sdk, instance, flowId, lastUpdated, operation) {
+  if (typeof lastUpdated !== 'string' || !lastUpdated) throw new Error(`Flow ${flowId} has no authoritative updated timestamp; safe edit refused`);
+  const read = async () => {
+    const { status } = await flowSafeEditRequest(sdk, instance, flowId, 'read');
+    if (!status || typeof status.canUserEdit !== 'boolean' || !(status.currentEditor == null || typeof status.currentEditor === 'string')) throw new Error('Unreadable safe edit status');
+    return status;
+  };
+  const before = await read();
+  if (before.canUserEdit || before.currentEditor) throw new Error(`Flow ${flowId} already has an existing edit session/editor; close it in Flow Designer before retrying. No lock changed.`);
+  let status;
+  try {
+    ({ status } = await flowSafeEditRequest(sdk, instance, flowId, 'upsert', lastUpdated));
+  } catch (error) {
+    throw new Error(`Flow ${flowId} safe edit acquisition is uncertain: ${error.message}. No content write attempted; no release attempted because ownership is unconfirmed. Inspect the exact flow/session before retrying.`, { cause: error });
+  }
+  // A denied or ambiguous upsert is not proof we own a lease. Never delete it.
+  if (status?.canUserEdit !== true || status.currentEditor) throw new Error(`Flow ${flowId} safe edit acquisition denied or ambiguous${status?.clientFlowStale === true ? ' (client flow is stale)' : ' (another editor may own it)'}; no content write or release attempted`);
+  let result, failure;
+  try {
+    if (status.clientFlowStale !== false && status.clientFlowStale !== null) throw new Error(`Flow ${flowId} is stale or has unreadable freshness; reread before retrying`);
+    result = await operation();
+  } catch (error) { failure = error; }
+  try {
+    const { deleteResult } = await flowSafeEditRequest(sdk, instance, flowId, 'delete');
+    if (deleteResult?.deleteSuccess !== true || deleteResult.id !== flowId) throw new Error('provider did not confirm release');
+    const after = await read();
+    if (after.canUserEdit || after.currentEditor) throw new Error('release readback still reports an edit session');
+  } catch (error) {
+    throw new Error(`${failure ? `${failure.message}; ` : 'Content operation completed; '}Flow ${flowId} safe edit release failed: ${error.message}. Inspect the exact flow/session before retrying.`, { cause: error });
+  }
+  if (failure) throw failure;
+  return result;
+}

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.
+}