@jacebenson/jsn 4.3.9-dev.61 → 4.3.9-dev.62

package/package.json

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

package/src/commands/flows.js

@@ -341,10 +341,11 @@ export function flowsCmd(wrap) {
         .command({
           command: 'update [identifier]',
           aliases: ['edit'],
-          describe: 'Safely update an inactive Draft flow from a partial JSON manifest. Use `jsn flows schemas` for live trigger inputs and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned; omitted values are preserved.',
+          describe: 'Save partial edits to an inactive Draft: record_create_or_update trigger table/condition and existing action inputs. Use --preview for before/after values without writes. Published checkout, Flow Logic, variables, catalog-trigger edits and stage placement require Flow Designer. Never publishes or executes. Use `jsn flows schemas` and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for live schemas; omitted values are preserved.',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the update manifest from a JSON file' })
+            .option('preview', { type: 'boolean', default: false, describe: 'Validate and show exact before/after input values without saving or versioning' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
@@ -360,12 +361,14 @@ export function flowsCmd(wrap) {
             } catch (error) {
               throw new Error(`Invalid flow update manifest JSON: ${error.message}`, { cause: error });
             }
-            await confirmDesignerMutation(argv, app, `Update draft flow ${identifier}; unspecified components and inputs are preserved`);
+            if (!argv.preview) await confirmDesignerMutation(argv, app, `Update draft flow ${identifier}; unspecified components and inputs are preserved`);
             const result = await updateFlowFromManifest(app.sdk, app.getEffectiveInstance(), argv.identifier, manifest, {
+              preview: argv.preview,
               readUpdateSet: () => readCurrentUpdateSet(app.sdk),
             });
-            return app.ok(result, {
-              summary: `Updated draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
+            const diff = result.changes.map(change => `${change.component}${change.order ? ` ${change.order}` : ''}.${change.input}: ${JSON.stringify(change.before)} -> ${JSON.stringify(change.after)}`).join('\n');
+            return app.ok({ ...result, _formatted: diff }, {
+              summary: `${result.preview ? 'Preview for' : 'Updated'} draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
               breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the updated draft flow' }],
             });
           }),

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