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

package/package.json

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

package/src/commands/flows.js

@@ -21,7 +21,7 @@ const FLOW_COMMANDS = [
   { name: 'publish [identifier]', description: 'Publish (activate) a flow, or a custom action with --action' },
   { name: 'test [identifier]', description: 'Execute a record-triggered flow against one record' },
   { name: 'create', description: 'Create a draft flow: guided in a terminal, JSON manifest in scripts' },
-  { name: 'update [identifier]', description: 'Update a draft flow (alias: edit)' },
+  { name: 'update [identifier]', description: 'Update a draft, or a published flow whose definition reports write access (alias: edit)' },
   { name: 'doctor', description: 'Check whether this instance can publish flows at all' },
   { name: 'delete [identifier]', description: 'Delete a flow (not implemented: use the Flow Designer UI)' },
 ];
@@ -341,15 +341,19 @@ 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 a Draft, or to a published/active flow whose ProcessFlow definition reports security.can_write=true: record_create_or_update trigger table/condition and existing action inputs. Published flows are edited as their working definition; the published snapshot and runtime pointers must stay unchanged, and the command fails loudly if they do not. Flows without write access are refused before any lock or content write, naming the permission. Use --preview for before/after values without writes. 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();
             const dataFile = argv.dataFile ?? argv['data-file'];
-            const identifier = await pickFlow(argv, app, !hasDefinitionData(argv) ? 'active=false^status=draft' : '');
+            // No lifecycle filter: published flows are editable when their own
+            // definition reports write access, and a non-writable target is
+            // refused with a permission message rather than a lifecycle label.
+            const identifier = await pickFlow(argv, app);
             if (identifier === undefined) return;
             argv = { ...argv, identifier };
             let manifest;
@@ -360,13 +364,19 @@ 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 flow ${identifier}; unspecified components and inputs are preserved. A published flow is edited as its working definition: the published snapshot must stay unchanged.`);
             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`,
-              breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the updated draft flow' }],
+            const diff = result.changes.map(change => `${change.component}${change.order ? ` ${change.order}` : ''}.${change.input}: ${JSON.stringify(change.before)} -> ${JSON.stringify(change.after)}`).join('\n');
+            const state = `${result.flow.status}${result.flow.active ? ', active' : ''}`;
+            const preservation = result.lifecycle?.published && !result.preview
+              ? `; published snapshot ${result.runtime_preservation?.before?.published_definition?.snapshot_id ?? ''} unchanged`
+              : '';
+            return app.ok({ ...result, _formatted: diff }, {
+              summary: `${result.preview ? 'Preview for' : 'Updated'} flow "${result.flow.name}" (${result.flow.id}) in state ${state}${preservation} without activation`,
+              breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the updated flow' }],
             });
           }),
         })

package/src/flow-create.js

@@ -1,4 +1,6 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { flowSafeEditRequest, withFlowSafeEdit } from './flow-safe-edit.js';
 import { assertSafeExactMatch } from './helpers.js';
 import { createVerifiedFlowVersion } from './flow-versioning.js';
 import {
@@ -19,6 +21,20 @@ const FLOW_ENDPOINT = '/api/now/processflow/flow';
 const GRAPHQL_ENDPOINT = '/api/now/graphql';
 const PROTECTED_FLOW_ID = 'c215135293bf03d087b0f14fdd03d652';
 const PROTECTED_FLOW_NAME = 'jace-test-flow';
+// Design-time revisions this CLI itself creates. Published version rows must be
+// unchanged by an edit, but every save necessarily adds one Autosave row.
+const AUTOSAVE_VERSION_TYPE = 'Autosave';
+const FLOW_RECORD_FIELDS = 'sys_id,name,sys_scope,scope,active,status,type,sys_updated_on,master_snapshot,latest_snapshot,version_record,version';
+
+// Everything this partial-update contract still cannot do, whatever the
+// lifecycle state. Published edits reuse the same component rules.
+const DEFERRED_LIFECYCLE = ['publish/activation', 'Flow Logic', 'subflows', 'flow variables', 'error handling'];
+
+function supportedLifecycle(published) {
+  return published
+    ? ['draft', 'autosave', 'published working-definition edit']
+    : ['draft', 'autosave'];
+}
 
 function isSysId(value) {
   return typeof value === 'string' && /^[0-9a-f]{32}$/i.test(value);
@@ -493,6 +509,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,21 +580,127 @@ 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: FLOW_RECORD_FIELDS }));
+}
+
+// A flow is editable either as an inactive Draft (working definition only) or as
+// a published/active flow whose definition reports write access. `draft` is the
+// only state that skips the provider write-permission check: a published flow is
+// not inherently unwritable, and the decision belongs to the provider.
+export function flowLifecycleState(flow) {
+  const active = stringValue(flow.active).toLowerCase() === 'true';
+  const status = stringValue(flow.status).toLowerCase();
+  return { active, status: status || 'unknown', draft: !active && status === 'draft' };
+}
+
+function describeState(lifecycle) {
+  const parts = [lifecycle.active ? 'active' : 'inactive'];
+  if (lifecycle.status && lifecycle.status !== 'unknown') parts.push(`status=${lifecycle.status}`);
+  return parts.join(', ');
 }
 
-async function resolveDraftFlow(sdk, identifier) {
+async function resolveFlowForUpdate(sdk, identifier) {
   const rows = await readFlowRecord(sdk, identifier);
   if (rows.length !== 1) throw new Error(rows.length === 0 ? `Flow not found: ${identifier}` : `Flow identifier is ambiguous: ${identifier}; exact target ID or unique name is required`);
   const flow = rows[0];
   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`);
-  return { flow, flowId, flowName };
+  return { flow, flowId, flowName, lifecycle: flowLifecycleState(flow) };
+}
+
+// The ProcessFlow definition is the write contract for a published flow. A
+// missing or false can_write means the provider will reject the content patch
+// with "Insufficient access level for operation [write]", so refuse before any
+// edit session exists and say which permission is missing.
+function assertDefinitionWritable(flowId, scope, lifecycle, definition) {
+  if (lifecycle.draft) return;
+  const security = definition?.security;
+  const canWrite = security && typeof security === 'object' ? security.can_write : undefined;
+  if (canWrite === true) return;
+  const reported = canWrite === false ? 'security.can_write=false' : 'no security.can_write';
+  throw new Error(`Flow ${flowId} is ${describeState(lifecycle)} and its ProcessFlow definition reports ${reported}, so the provider would reject a content write with "Insufficient access level for operation [write]". This is a flow content-permission problem, not a published-flow limitation: no edit session, content write or Autosave was attempted. Use an account/scope with write access to the flow's application (${scope}) or edit the flow in Flow Designer as a user who can write it. Published snapshots were not touched.`);
+}
+
+function digestDefinition(definition) {
+  return createHash('sha256').update(JSON.stringify(definition)).digest('hex');
+}
+
+// Runtime state of a published flow: the parent pointers that decide whether it
+// runs, the frozen published definition read through its master snapshot id, and
+// the version rows that a publish created. Autosave rows are excluded because
+// every accepted edit adds exactly one design-time revision.
+async function readFlowRuntime(sdk, instance, flowId, { scope, snapshotId }) {
+  const records = await sdk.list('sys_hub_flow', new URLSearchParams({
+    sysparm_query: `sys_id=${flowId}`,
+    sysparm_limit: '1',
+    sysparm_display_value: 'all',
+    sysparm_fields: FLOW_RECORD_FIELDS,
+  }));
+  if (records.length !== 1) throw new Error(`Flow ${flowId} runtime read returned ${records.length} records; cannot verify published state`);
+  const record = records[0];
+  const pointers = {
+    active: stringValue(record.active),
+    status: stringValue(record.status),
+    master_snapshot: stringValue(record.master_snapshot),
+    latest_snapshot: stringValue(record.latest_snapshot),
+    version_record: stringValue(record.version_record),
+  };
+  let publishedDefinition;
+  if (snapshotId) {
+    const response = await sdk.request(`${instance}${FLOW_ENDPOINT}/${encodeURIComponent(snapshotId)}?sysparm_transaction_scope=${encodeURIComponent(scope)}`, { method: 'GET' });
+    const definition = findFlowData(response);
+    if (!definition || typeof definition !== 'object') throw new Error(`Published snapshot ${snapshotId} for flow ${flowId} was unreadable; refusing to compare published runtime state`);
+    publishedDefinition = { snapshot_id: snapshotId, digest: digestDefinition(definition) };
+  } else {
+    publishedDefinition = { snapshot_id: '', digest: '' };
+  }
+  const versionRows = await sdk.list('sys_hub_flow_version', new URLSearchParams({
+    sysparm_query: `flow=${flowId}^ORDERBYDESCsys_updated_on`,
+    sysparm_limit: '50',
+    sysparm_display_value: 'all',
+    sysparm_fields: 'sys_id,flow,type,sys_created_on',
+  }));
+  const versionRowsStable = versionRows
+    .map(row => ({ sys_id: stringValue(row.sys_id), type: stringValue(row.type), created: stringValue(row.sys_created_on) }))
+    .filter(row => row.type !== AUTOSAVE_VERSION_TYPE)
+    .sort((left, right) => left.sys_id.localeCompare(right.sys_id));
+  return { record: pointers, published_definition: publishedDefinition, version_rows: versionRowsStable };
+}
+
+// Published runtime must not move. Two parent fields do move by platform design
+// when a published flow is saved: the record's status becomes a draft working
+// copy and version_record points at the new Autosave. Those are accepted only in
+// that exact shape (and reported), because the runtime gates are `active`, the
+// frozen snapshot pointers and the published definition itself.
+function runtimeDifferences(before, after, { autosaveVersionId, newVersionType } = {}) {
+  const differences = [];
+  const checkout = [];
+  for (const field of ['active', 'master_snapshot', 'latest_snapshot']) {
+    if (before.record[field] !== after.record[field]) differences.push({ field, before: before.record[field], after: after.record[field] });
+  }
+  if (before.record.status !== after.record.status) {
+    const publishedToDraft = before.record.status === 'published' && after.record.status === 'draft';
+    const entry = { field: 'status', before: before.record.status, after: after.record.status };
+    if (publishedToDraft) checkout.push({ ...entry, reason: 'platform checkout: the published flow now has a draft working copy; the published snapshot still runs' });
+    else differences.push(entry);
+  }
+  if (before.record.version_record !== after.record.version_record) {
+    const entry = { field: 'version_record', before: before.record.version_record, after: after.record.version_record };
+    if (autosaveVersionId && after.record.version_record === autosaveVersionId) checkout.push({ ...entry, reason: `pointer moved to this command's ${newVersionType || 'Autosave'} version` });
+    else differences.push(entry);
+  }
+  if (before.published_definition.digest !== after.published_definition.digest) {
+    differences.push({ field: 'published_definition', before: before.published_definition, after: after.published_definition });
+  }
+  if (JSON.stringify(before.version_rows) !== JSON.stringify(after.version_rows)) {
+    differences.push({ field: 'published_version_rows', before: before.version_rows, after: after.version_rows });
+  }
+  return { differences, design_time_changes: checkout };
 }
 
 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 +726,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 };
 }
@@ -769,18 +909,42 @@ export async function createFlowFromManifest(sdk, instance, inputManifest, optio
 
 export async function updateFlowFromManifest(sdk, instance, identifier, inputManifest, options = {}) {
   const manifest = validateFlowUpdateManifest(inputManifest);
-  const target = await resolveDraftFlow(sdk, identifier);
+  const target = await resolveFlowForUpdate(sdk, identifier);
   const flowId = target.flowId;
-  const scope = stringValue(manifest.scope ?? target.flow.scope);
+  const lifecycle = target.lifecycle;
+  const published = !lifecycle.draft;
+  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`);
+  const snapshotId = stringValue(target.flow.master_snapshot);
+  // A published/active target is judged by the provider, not by its lifecycle
+  // label: read the definition and require security.can_write before any lock.
+  const definitionRead = async () => {
+    const definition = await readProcessFlow(sdk, instance, flowId, scope);
+    assertDefinitionWritable(flowId, scope, lifecycle, definition);
+    return definition;
+  };
+  let beforeDefinition = await definitionRead();
+  // 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) {
+    // A publish moves the record, not the definition, so a published flow may
+    // legitimately report an older definition timestamp. The definition's own
+    // `updated` is what safeEdit checks; only a draft must match its record.
+    beforeDefinition = await definitionRead();
+    if (!published && beforeDefinition.updated !== recordUpdated) throw new Error(`Flow ${flowId} definition is stale relative to its record; no edit session or content mutation attempted`);
+  }
+  if (published && !snapshotId) throw new Error(`Flow ${flowId} is ${describeState(lifecycle)} but has no master_snapshot; refusing to edit without a published-definition baseline`);
   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 +954,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 +964,166 @@ 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: lifecycle.status, active: lifecycle.active },
+    changes,
+    lifecycle: {
+      published,
+      active: lifecycle.active,
+      executed: false,
+      writable: true,
+      lock_acquired: false,
+      supported: supportedLifecycle(published),
+      deferred: DEFERRED_LIFECYCLE,
+    },
+  };
+  // Baseline the published runtime after the definition read (a legacy read can
+  // materialize a version row) and before the edit session exists.
+  const runtimeBefore = published ? await readFlowRuntime(sdk, instance, flowId, { scope, snapshotId }) : null;
+  const outcome = await 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';
+      let runtime;
+      if (published) {
+        runtime = { before: runtimeBefore, after: await readFlowRuntime(sdk, instance, flowId, { scope, snapshotId }) };
+        const comparison = runtimeDifferences(runtime.before, runtime.after, {
+          autosaveVersionId: stringValue(version?.sys_id || version?.sysId),
+          newVersionType: stringValue(version?.type) || AUTOSAVE_VERSION_TYPE,
+        });
+        if (comparison.differences.length) {
+          throw new Error(`Flow ${flowId} was edited but its published runtime state changed: ${JSON.stringify(comparison.differences)}. The edit may have altered runtime. Do not republish, retry, unpublish or deactivate; inspect published snapshot ${snapshotId}, the version rows and the active/status pointers in Flow Designer. No rollback, publish or execution was attempted.`);
+        }
+        runtime.verified = true;
+        runtime.design_time_changes = comparison.design_time_changes;
+        completedStage = 'runtime_verified';
+      }
+      const selectedUpdateSet = await readUpdateSet();
+      const updateSetCapture = await readUpdateSetCapture(sdk, selectedUpdateSet, flowId);
+      // Report what the record says after the save, not the pre-edit label: a
+      // published flow that now has a draft working copy must not look published
+      // in the result. `active` and the snapshot pointers are the runtime gates.
+      const finalRecord = runtime?.after?.record;
+      return {
+        flow: {
+          id: flowId,
+          name: target.flowName,
+          status: finalRecord?.status || lifecycle.status,
+          active: finalRecord ? finalRecord.active === 'true' : lifecycle.active,
+        },
+        changes,
+        processflow,
+        definition_readback: { available: true, status: 'read_back', flow_id: flowId },
+        version,
+        ...(runtime ? { runtime_preservation: runtime } : {}),
+        update_set_capture: updateSetCapture,
+        update_set_mutations: snapshots,
+        lifecycle: {
+          published,
+          active: lifecycle.active,
+          executed: false,
+          runtime_preserved: published ? true : undefined,
+          supported: supportedLifecycle(published),
+          deferred: DEFERRED_LIFECYCLE,
+        },
+      };
+    } 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 });
+  });
+  if (published) {
+    // The lease is user-level, so its absence is part of the delivered result.
+    const { status } = await flowSafeEditRequest(sdk, instance, flowId, 'read');
+    if (!status || status.canUserEdit || status.currentEditor) {
+      throw new Error(`Flow ${flowId} update saved (Autosave ${stringValue(outcome.version?.sys_id)}) but its safe edit lease is still present: ${JSON.stringify(status ?? null)}. Inspect and close the Flow Designer session before further edits. No rollback or unpublish attempted.`);
+    }
+    outcome.lifecycle = { ...outcome.lifecycle, safe_edit_lease: 'absent' };
+    outcome.runtime_preservation = { ...outcome.runtime_preservation, safe_edit_lease: 'absent' };
   }
+  return outcome;
 }
 
 export async function readCurrentUpdateSet(sdk) {

package/src/flow-designer-interactive.js

@@ -370,16 +370,21 @@ 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) };
 }
 export async function guidedFlowEdit(argv, app) {
   if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the flow update manifest in noninteractive mode');
   const { record, definition } = await savedFlowDefinition(app, argv.identifier);
-  if (rawField(record.active) === true || rawField(record.active) === 'true' || rawField(record.status) !== 'draft') throw errUsage('Guided flow edit requires an inactive Draft');
+  // Published/active targets are judged by the provider, exactly as the scripted
+  // path does: an inactive Draft needs no write check, anything else must report
+  // security.can_write=true or the save would be rejected after this wizard.
+  const active = rawField(record.active) === true || rawField(record.active) === 'true';
+  const draft = !active && rawField(record.status) === 'draft';
+  if (!draft && definition?.security?.can_write !== true) throw errUsage(`Guided flow edit needs the flow's ProcessFlow definition to report security.can_write=true; ${argv.identifier} does not, so the provider would reject the save. Edit it in Flow Designer as a user who can write this flow.`);
   const manifest = {};
-  const choice = await prompts(app).select({ message: 'Edit supported draft flow fields', choices: [
+  const choice = await prompts(app).select({ message: 'Edit supported flow fields', choices: [
     { name: 'Record trigger condition', value: 'trigger' }, { name: 'Existing action input values', value: 'actions' },
   ] });
   if (choice === 'trigger') {
@@ -396,7 +401,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;
+}