@jacebenson/jsn 4.3.7-dev.38 → 4.3.7-dev.40

package/package.json

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

package/src/commands/flows.js

@@ -6,6 +6,7 @@ import { inspectFlow } from '../flow-inspection.js';
 import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '../flow-publish.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.js';
+import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES } from '../flow-triggers.js';
 import { testFlow } from '../flow-test.js';
 import { errUsage } from '../errors.js';
 import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guidedFlowTestRecord, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
@@ -32,6 +33,18 @@ function flowInspectionAdapter(app) {
   };
 }
 
+// The picker is driven by the instance's own trigger definitions, but this CLI
+// can only create the families it has verified. State both plainly so a created
+// flow never surprises the operator with a trigger that was not really set.
+function triggerGuidance(trigger) {
+  return {
+    supported_families: [...SUPPORTED_TRIGGER_TYPES].sort(),
+    excluded_families: [...EXCLUDED_TRIGGER_TYPES.entries()].map(([type, reason]) => ({ type, reason })).sort((a, b) => a.type.localeCompare(b.type)),
+    created_trigger: trigger ? { id: trigger.id, type: trigger.type, name: trigger.name, triggerDefinitionId: trigger.triggerDefinitionId } : null,
+    note: 'The trigger picker lists only families this CLI can create and verify. Families the picker omits are reported in excluded_families.',
+  };
+}
+
 declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'edit', 'delete', 'publish', 'test'] });
 
 function renderChecks(checks) {
@@ -281,10 +294,11 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Guide draft flow creation in a terminal, or use a schema-driven JSON manifest',
+          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
-            .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' }),
+            .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' })
+            .option('scope', { type: 'string', describe: 'Transaction scope sys_id or global for the guided picker' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             const dataFile = argv.dataFile ?? argv['data-file'];
@@ -299,8 +313,8 @@ export function flowsCmd(wrap) {
             const result = await createFlowFromManifest(app.sdk, app.getEffectiveInstance(), manifest, {
               readUpdateSet: () => readCurrentUpdateSet(app.sdk),
             });
-            app.ok(result, {
-              summary: `Created draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
+            app.ok({ ...result, trigger_guidance: triggerGuidance(result.trigger) }, {
+              summary: `Created draft flow "${result.flow.name}" (${result.flow.id}) with trigger ${result.trigger?.type ?? 'unknown'} (${result.trigger?.id ?? 'no trigger id'}) without activation`,
               breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the draft flow' }],
             });
           }),

package/src/flow-create.js

@@ -1,10 +1,20 @@
 import { randomUUID } from 'node:crypto';
 import { assertSafeExactMatch } from './helpers.js';
 import { createVerifiedFlowVersion } from './flow-versioning.js';
+import {
+  SUPPORTED_TRIGGER_TYPES,
+  TRIGGER_DEFINITION_TABLE,
+  buildTriggerInputs,
+  buildTriggerInstance,
+  conditionInputFor,
+  readTableDescriptor,
+  readTriggerInputDefinitions,
+  tableInputFor,
+  flowDesignParameter,
+} from './flow-triggers.js';
 
 const FLOW_ENDPOINT = '/api/now/processflow/flow';
 const GRAPHQL_ENDPOINT = '/api/now/graphql';
-const TABLE_DESCRIPTOR_ENDPOINT = '/api/now/processflow/trigger/record/table';
 const PROTECTED_FLOW_ID = 'c215135293bf03d087b0f14fdd03d652';
 const PROTECTED_FLOW_NAME = 'jace-test-flow';
 
@@ -132,12 +142,15 @@ export function validateFlowManifest(manifest) {
   if (manifest.variables !== undefined || manifest.flowVariables !== undefined) throw new Error('Flow-variable lifecycle is unsupported in this creation slice');
   if (manifest.errorHandling !== undefined) throw new Error('Error handling is unsupported in this creation slice');
   const trigger = manifest.trigger;
-  if (!trigger || trigger.type !== 'record_create_or_update') throw new Error('Only trigger.type=record_create_or_update is supported');
-  if (!String(trigger.table || '').trim()) throw new Error('Record trigger requires table');
+  if (!trigger || typeof trigger !== 'object' || Array.isArray(trigger)) throw new Error('Flow manifest requires a trigger object');
+  for (const key of Object.keys(trigger)) if (!['type', 'table', 'condition', 'inputs'].includes(key)) throw new Error(`Flow manifest trigger field "${key}" is unsupported`);
+  if (!SUPPORTED_TRIGGER_TYPES.has(String(trigger.type))) throw new Error(`Unsupported trigger.type "${trigger.type}"; supported families are ${[...SUPPORTED_TRIGGER_TYPES].join(', ')}`);
+  if (trigger.table !== undefined && !String(trigger.table).trim()) throw new Error('Trigger table must not be empty');
   if (trigger.condition !== undefined && typeof trigger.condition !== 'string') throw new Error('Record trigger condition must be a string');
   if (trigger.condition && !/^[A-Za-z_][A-Za-z0-9_.]*(?:STARTSWITH|ENDSWITH|LIKE|NOT LIKE|=|!=|IN|ISEMPTY|ISNOTEMPTY)[^,^]*$/.test(trigger.condition)) {
     throw new Error('Record trigger condition uses an unsupported encoded-query condition subset');
   }
+  if (trigger.inputs !== undefined && (!trigger.inputs || typeof trigger.inputs !== 'object' || Array.isArray(trigger.inputs))) throw new Error('Trigger inputs must be an object');
   if (!Array.isArray(manifest.actions)) throw new Error('Flow manifest requires an actions array');
   for (const [index, action] of manifest.actions.entries()) {
     if (!action || typeof action !== 'object' || !String(action.type || '').trim()) throw new Error(`Action ${index + 1} requires type`);
@@ -165,8 +178,12 @@ export function buildFlowProperties(manifest) {
 }
 
 export function buildFlowPatchMutation({ flowId, trigger, actions }) {
-  const triggerUpdate = {
-    id: trigger.id,
+  const triggerInsert = {
+    flowSysId: trigger.flowSysId,
+    name: trigger.name,
+    type: trigger.type,
+    triggerType: trigger.triggerType,
+    triggerDefinitionId: trigger.triggerDefinitionId,
     metadata: trigger.metadata,
     inputs: trigger.inputs,
   };
@@ -182,8 +199,10 @@ export function buildFlowPatchMutation({ flowId, trigger, actions }) {
     metadata: action.metadata,
     inputs: action.inputs,
   }));
-  const patch = `flowPatch: {flowId: ${gqlString(flowId)}, triggerInstances: {update: [${gqlInputObject(triggerUpdate)}]}, actions: {insert: [${actionInsert.map(gqlInputObject).join(', ')}]}}`;
-  return `mutation { global { snFlowDesigner { flow(${patch}) { triggerInstances { inserts { sysId uiUniqueIdentifier } updates { sysId uiUniqueIdentifier } } actions { inserts { sysId uiUniqueIdentifier } updates { sysId uiUniqueIdentifier } } } } } }`;
+  const patch = `flowPatch: {flowId: ${gqlString(flowId)}, triggerInstances: {insert: [${gqlInputObject(triggerInsert)}]}, actions: {insert: [${actionInsert.map(gqlInputObject).join(', ')}]}}`;
+  // `triggerInstances.updates` is a leaf [String] on this schema; only `inserts`
+  // carries identities, and only for triggers does `inserts` lack a uiUniqueIdentifier.
+  return `mutation { global { snFlowDesigner { flow(${patch}) { triggerInstances { inserts { sysId } updates } actions { inserts { sysId uiUniqueIdentifier } } } } } }`;
 }
 
 export function buildFlowUpdateMutation({ flowId, triggerUpdates = [], actionUpdates = [] }) {
@@ -230,21 +249,35 @@ export async function readActionDefinition(sdk, instance, actionTypeId, scope, {
   return { definition, schema };
 }
 
-function buildTypedInputs(action, schema) {
+export function buildTypedInputs(action, schema) {
   const supplied = action.inputs || {};
-  const allowed = new Set(schema.map(field => field.name));
+  const allowed = new Set(schema.map(field => field?.name).filter(Boolean));
   for (const key of Object.keys(supplied)) if (!allowed.has(key)) throw new Error(`Unsupported input "${key}" for action ${action.type}`);
   return schema.map(field => {
-    if (!field || typeof field !== 'object' || !field.id || !field.parameter || typeof field.parameter !== 'object') {
+    // The instance's own definition is the contract: identity is required,
+    // everything else is echoed back untouched. Demanding a key the provider
+    // omits breaks real actions.
+    if (!field || typeof field !== 'object' || !field.id || !field.name) {
       throw new Error(`Action ${action.type} returned an incomplete input schema; refusing to invent input metadata for "${field?.name || 'unknown'}"`);
     }
+    if (field.parameter !== undefined && (typeof field.parameter !== 'object' || field.parameter === null || Array.isArray(field.parameter))) {
+      throw new Error(`Action ${action.type} input "${field.name}" has a malformed parameter block; refusing to change it`);
+    }
     const suppliedValue = Object.prototype.hasOwnProperty.call(supplied, field.name) ? supplied[field.name] : field.default;
     if ((suppliedValue === undefined || suppliedValue === null) && (field.mandatory === true || field.required === true)) throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
     const value = suppliedValue ?? null;
     const displayValue = field.displayValue ?? field.display_value ?? value;
+    // global_snFlowDesigner_ActionInstanceValue accepts ONLY these keys. The
+    // ProcessFlow action definition hands back the whole UI schema on the input
+    // object (uiDisplayTypeLabel, choices, type_label, …) and spreading it makes
+    // the mutation fail validation, so the schema is carried inside `parameter`.
     return {
-      ...field,
+      id: field.id,
       name: field.name,
+      children: Array.isArray(field.children) ? field.children : [],
+      displayField: stringValue(field.displayField || field.display_field || ''),
+      scriptActive: false,
+      parameter: flowDesignParameter(field),
       value: { schemaless: false, schemalessValue: '', value },
       displayValue: { schemaless: false, schemalessValue: '', value: displayValue },
     };
@@ -258,51 +291,15 @@ function parseSimpleCondition(condition) {
   return { field: match[1], operator: match[2], term: match[3] };
 }
 
-export async function readTableDescriptor(sdk, instance, scope, table, override) {
-  if (override) return override(table);
-  const endpoint = `${instance}${TABLE_DESCRIPTOR_ENDPOINT}?table=${encodeURIComponent(table)}&sysparm_transaction_scope=${encodeURIComponent(scope)}`;
-  const response = await sdk.request(endpoint, { method: 'GET' });
-  const descriptor = response?.result ?? response?.data?.result ?? response?.data ?? response;
-  if (!descriptor || typeof descriptor !== 'object') throw new Error(`ProcessFlow table descriptor was unavailable for ${table}`);
-  const label = stringValue(descriptor.label || descriptor.displayValue || descriptor.display_value || descriptor.name);
-  const displayField = stringValue(descriptor.displayField || descriptor.display_field || descriptor.displayColumn || descriptor.display_column);
-  if (!label || !displayField) throw new Error(`ProcessFlow table descriptor for ${table} lacks label/display field`);
-  return { ...descriptor, label, displayField };
-}
-
-function buildPredicateMetadata(condition, descriptor) {
-  const predicate = parseSimpleCondition(condition);
-  if (!predicate) return { predicates: [], order_by: [], group_by: [], has_rlq_conditions: false };
-  const field = descriptor.fields?.find(item => stringValue(item.name || item.element || item.field) === predicate.field)
-    || descriptor.schema?.find(item => stringValue(item.name || item.element || item.field) === predicate.field);
-  if (!field) throw new Error(`Record trigger condition field "${predicate.field}" is absent from the table descriptor`);
-  const fieldLabel = stringValue(field.label || field.column_label || predicate.field);
-  const operatorLabel = stringValue(field?.operators?.[predicate.operator] || predicate.operator);
-  const comparison = {
-    field_type: stringValue(field?.field_type || field?.type || 'string'),
-    operator: predicate.operator,
-    term_label: predicate.term,
-    or_query: false,
-    field_label: fieldLabel,
-    column_type: stringValue(field?.column_type || 'element'),
-    term: predicate.term,
-    display_value: '',
-    new_query: false,
-    goto_query: false,
-    is_pre_evaluated: false,
-    rlqc_query: false,
-    operator_label: operatorLabel,
-    value: predicate.term,
-    field: predicate.field,
-    type: 'comparison',
-  };
-  return {
-    predicates: [{ compound_type: 'or', subpredicates: [{ compound_type: 'and', subpredicates: [{ compound_type: 'and', subpredicates: [comparison], type: 'compound' }], type: 'compound' }], type: 'compound' }],
-    order_by: [],
-    group_by: [],
-    has_rlq_conditions: false,
-  };
-}
+// Trigger predicate metadata is DERIVED BY THE INSTANCE, not by this CLI: the
+// snFlowDesigner patch parses the `condition` input into
+// `metadata.query_parse.predicates` itself (verified live on insert and on
+// update — the returned field_label/operator_label/field_type match Flow
+// Designer's own output). Sending `{}` and verifying the derived predicate by
+// read-back is therefore both simpler and more faithful than rebuilding the
+// predicate tree from a table descriptor, and it removes the dependency on the
+// ProcessFlow table-descriptor route, which returns 400 on this instance.
+const DEFAULT_TRIGGER_METADATA = '{}';
 
 function predicateMetadataMatches(metadata, condition) {
   const expected = parseSimpleCondition(condition);
@@ -311,10 +308,15 @@ function predicateMetadataMatches(metadata, condition) {
   const comparisons = [];
   walk(parsed, object => {
     if (stringValue(object.type).toLowerCase() !== 'comparison') return;
+    // The instance stores the parsed predicate with `term` holding the WHOLE
+    // encoded condition and `value` holding the extracted term, so the term
+    // comparison must prefer `value` (e.g. for
+    // "short_descriptionSTARTSWITHjacetest": term = the full string,
+    // value = "jacetest").
     comparisons.push({
       field: stringValue(object.field),
       operator: stringValue(object.operator),
-      term: stringValue(object.term ?? object.value),
+      term: stringValue(object.value ?? object.term),
     });
   });
   return comparisons.some(comparison => comparison.field === expected.field
@@ -326,18 +328,39 @@ function assertPredicateMetadataMatches(metadata, condition, label) {
   if (!predicateMetadataMatches(metadata, condition)) throw new Error(`${label} predicate metadata did not match the requested field, operator, and term`);
 }
 
+// The instance stores predicate metadata as {query_parse: {predicates: [...]}},
+// so dropping only a top-level `predicates` key is not enough to compare the
+// parts of the metadata a manifest did not ask to change.
+function stripPredicates(value) {
+  if (Array.isArray(value)) return value.map(stripPredicates);
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'predicates') continue;
+    out[key] = stripPredicates(item);
+  }
+  return out;
+}
+
 function actionTypeIdOf(action) {
   return idValue(action?.actionTypeSysId || action?.action_type_sys_id || action?.actionType?.sys_id || action?.actionType?.sysId);
 }
 
-function verifyCreatedFlowReadback({ flowId, processflow, trigger, manifest, actionInstances, inserted }) {
+function verifyCreatedFlowReadback({ flowId, processflow, trigger, insertedTrigger, manifest, actionInstances, inserted }) {
   const returnedFlowId = stringValue(processflow.flowId || processflow.flow_id || processflow.sysId || processflow.sys_id);
   if (returnedFlowId && returnedFlowId !== flowId) throw new Error(`ProcessFlow read-back returned a different flow ID (${returnedFlowId})`);
 
   const triggers = findArray(processflow, 'triggerInstances');
   if (triggers.length !== 1) throw new Error(`ProcessFlow read-back returned ${triggers.length} trigger instances; expected one`);
   const savedTrigger = triggers[0];
-  if (findId(savedTrigger, ['sysId', 'sys_id', 'id', 'triggerId']) !== trigger.id) throw new Error('Created trigger identity was not preserved in ProcessFlow read-back');
+  const savedTriggerId = findId(savedTrigger, ['sysId', 'sys_id', 'id', 'triggerId']);
+  const insertedTriggerId = findId(insertedTrigger || {}, ['sysId', 'sys_id', 'id']);
+  if (!insertedTriggerId) throw new Error('Flow trigger insert did not return a trigger identity');
+  if (savedTriggerId !== insertedTriggerId) throw new Error('Created trigger identity was not preserved in ProcessFlow read-back');
+  if (stringValue(savedTrigger.triggerDefinitionId || savedTrigger.trigger_definition_id) !== trigger.triggerDefinitionId) {
+    throw new Error(`Created trigger definition did not match the requested ${trigger.triggerDefinitionId}`);
+  }
+  if (stringValue(savedTrigger.type) !== trigger.type) throw new Error(`Created trigger type did not match the requested ${trigger.type}`);
   const savedTriggerInputs = inputList(savedTrigger);
   for (const expected of trigger.inputs) {
     const actual = savedTriggerInputs.find(input => input.name === expected.name);
@@ -368,23 +391,70 @@ function verifyCreatedFlowReadback({ flowId, processflow, trigger, manifest, act
   }
 }
 
-function makeTriggerPatch(flow, manifest, descriptor) {
-  const trigger = findArray(flow, 'triggerInstances')[0];
-  if (!trigger) throw new Error('Created flow did not return its default record trigger instance');
-  const id = findId(trigger, ['sysId', 'sys_id', 'id', 'triggerId']);
-  if (!id) throw new Error('Created flow trigger has no usable identity');
-  const metadata = buildPredicateMetadata(manifest.trigger.condition || '', descriptor);
-  const wrapped = value => ({ schemaless: false, schemalessValue: '', value });
+export async function resolveTriggerDefinition(sdk, type) {
+  if (!SUPPORTED_TRIGGER_TYPES.has(String(type))) throw new Error(`Unsupported trigger.type "${type}"`);
+  const rows = await sdk.list(TRIGGER_DEFINITION_TABLE, new URLSearchParams({
+    sysparm_query: `type=${type}^active=true`,
+    sysparm_limit: '5',
+    sysparm_display_value: 'all',
+    sysparm_fields: 'sys_id,name,type,active,category',
+  }));
+  if (rows.length !== 1) throw new Error(rows.length === 0
+    ? `Trigger definition not found or inactive: ${type}`
+    : `Trigger definition is ambiguous: ${type}`);
+  const row = rows[0];
   return {
-    id,
-    metadata: JSON.stringify(metadata),
-    inputs: [
-      { name: 'table', displayField: descriptor.displayField, displayValue: wrapped(descriptor.label), value: wrapped(manifest.trigger.table) },
-      { name: 'condition', displayField: manifest.trigger.condition || '', displayValue: wrapped(manifest.trigger.condition || ''), value: wrapped(manifest.trigger.condition || '') },
-    ],
+    sysId: idValue(row.sys_id || row.sysId),
+    name: stringValue(row.name),
+    type: stringValue(row.type),
+    // The definition's category display name is what the trigger instance stores
+    // as triggerType ("Record", "Scheduled", "Application"). The raw value is the
+    // category sys_id, so take the display value when the API returned one.
+    triggerType: categoryDisplay(row.category),
   };
 }
 
+function categoryDisplay(value) {
+  if (value && typeof value === 'object') return stringValue(value.display_value ?? value.value);
+  return stringValue(value);
+}
+
+/**
+ * Build the triggerInstances.insert payload from the definition's own declared
+ * inputs. `manifest.trigger.table` / `.condition` are shortcuts onto whichever
+ * declared input carries them; everything else goes through `trigger.inputs`.
+ */
+export async function buildCreateTrigger(sdk, flowId, manifest, definition, options = {}) {
+  const declared = await readTriggerInputDefinitions(sdk, definition.sysId);
+  if (!declared.length && options.requireInputs === true) throw new Error(`Trigger definition ${definition.type} declares no inputs`);
+  const tableInput = tableInputFor(declared);
+  const conditionInput = conditionInputFor(declared);
+  const supplied = { ...(manifest.trigger.inputs || {}) };
+
+  if (manifest.trigger.table !== undefined) {
+    if (!tableInput) throw new Error(`Trigger ${definition.type} does not declare a table input`);
+    supplied[tableInput.name] = manifest.trigger.table;
+  }
+  if (manifest.trigger.condition !== undefined) {
+    if (!conditionInput) throw new Error(`Trigger ${definition.type} does not declare a condition input`);
+    supplied[conditionInput.name] = manifest.trigger.condition;
+  }
+  let descriptor = null;
+  if (tableInput && supplied[tableInput.name]) {
+    descriptor = options.readTableDescriptor
+      ? await options.readTableDescriptor(supplied[tableInput.name])
+      : await readTableDescriptor(sdk, supplied[tableInput.name]);
+  }
+
+  return buildTriggerInstance({
+    flowId,
+    definition,
+    triggerType: definition.triggerType,
+    metadata: DEFAULT_TRIGGER_METADATA,
+    inputs: buildTriggerInputs(declared, supplied, descriptor),
+  });
+}
+
 function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
@@ -505,9 +575,10 @@ function updatedTrigger(flow, manifest, descriptor) {
   if (!id) throw new Error('Saved record trigger has no usable identity');
   const update = { id, inputs };
   if (manifest.trigger.condition !== undefined) {
-    const generated = buildPredicateMetadata(condition, descriptor);
-    const metadata = { ...generated, ...(existingMetadata || {}), predicates: generated.predicates };
-    update.metadata = JSON.stringify(metadata);
+    // 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;
   }
@@ -522,6 +593,14 @@ function insertedActions(response) {
   return found;
 }
 
+function insertedTriggers(response) {
+  let found = [];
+  walk(response, object => {
+    if (!found.length && object.triggerInstances?.inserts) found = object.triggerInstances.inserts;
+  });
+  return found;
+}
+
 async function reconcileAmbiguousCreate(sdk, manifest) {
   const params = new URLSearchParams({ sysparm_query: `name=${manifest.name}`, sysparm_limit: '2', sysparm_display_value: 'all', sysparm_fields: 'sys_id,name,active,status,scope' });
   const records = await sdk.list('sys_hub_flow', params);
@@ -603,9 +682,12 @@ export async function createFlowFromManifest(sdk, instance, inputManifest, optio
       parentSnapshot.capture_before = unavailableCapture('flow ID was not known before parent creation');
       await addPostMutationCapture(parentSnapshot, sdk, readUpdateSet, flowId);
     }
-    const initialDefinition = await readProcessFlow(sdk, instance, flowId, scope);
-    const tableDescriptor = await readTableDescriptor(sdk, instance, scope, manifest.trigger.table, options.readTableDescriptor);
-    const trigger = makeTriggerPatch(initialDefinition, manifest, tableDescriptor);
+    // A newly POSTed ProcessFlow has NO trigger (verified live: triggerInstances
+    // comes back empty), so the trigger is inserted by the same snFlowDesigner
+    // patch as the actions. There is nothing to read back from the parent apart
+    // from the flow identity.
+    const definition = await resolveTriggerDefinition(sdk, manifest.trigger.type);
+    const trigger = await buildCreateTrigger(sdk, flowId, manifest, definition, options);
 
     const actionInstances = [];
     for (const [index, action] of manifest.actions.entries()) {
@@ -630,11 +712,13 @@ export async function createFlowFromManifest(sdk, instance, inputManifest, optio
       body: JSON.stringify({ query: buildFlowPatchMutation({ flowId, trigger, actions: actionInstances }), variables: {} }),
     }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
     assertGraphQLSuccess(patchResponse, 'Flow trigger/action patch');
+    const insertedTrigger = insertedTriggers(patchResponse)[0];
+    if (!insertedTrigger) throw new Error('Flow trigger insert returned no trigger identity');
     const inserted = insertedActions(patchResponse);
     if (inserted.length !== actionInstances.length) throw new Error(`Flow action patch returned ${inserted.length} inserted action identities; expected ${actionInstances.length}`);
 
     const processflow = await readProcessFlow(sdk, instance, flowId, scope);
-    verifyCreatedFlowReadback({ flowId, processflow, trigger, manifest, actionInstances, inserted });
+    verifyCreatedFlowReadback({ flowId, processflow, trigger, insertedTrigger, manifest, actionInstances, inserted });
     const { version } = await mutationContext('autosave_version', readUpdateSet, snapshots, () => createVerifiedFlowVersion(sdk, {
       instance, flowId, scope, type: 'Autosave', annotation: 'JSN flow create',
     }), updateSet => readUpdateSetCapture(sdk, updateSet, flowId));
@@ -644,7 +728,7 @@ export async function createFlowFromManifest(sdk, instance, inputManifest, optio
     const triggerReadback = findArray(processflow, 'triggerInstances')[0] || {};
     return {
       flow: { id: flowId, name: manifest.name, status: 'draft', active: false },
-      trigger: { ...triggerReadback, id: findId(triggerReadback, ['sysId', 'sys_id', 'id']) || trigger.id },
+      trigger: { ...triggerReadback, id: findId(triggerReadback, ['sysId', 'sys_id', 'id']) || findId(insertedTrigger, ['sysId', 'sys_id', 'id']) },
       actions: inserted,
       processflow,
       definition_readback: { available: true, status: 'read_back', flow_id: flowId },
@@ -654,7 +738,10 @@ export async function createFlowFromManifest(sdk, instance, inputManifest, optio
       lifecycle: { published: false, supported: ['draft', 'autosave'], deferred: ['publish/activation', 'Flow Logic', 'subflows', 'flow variables', 'error handling'] },
     };
   } catch (error) {
-    throw new Error(`Flow ${flowId} creation incomplete: ${error.message}; reconciliation: ${JSON.stringify(snapshots)}`, { cause: error });
+    // Creation is two-stage: the parent POST leaves a real draft behind when the
+    // trigger/action patch fails. Name that orphan explicitly instead of leaving
+    // the caller to hunt for it.
+    throw new Error(`Flow ${flowId} creation incomplete and left orphan draft flow ${flowId} (delete it in Flow Designer): ${error.message}; reconciliation: ${JSON.stringify(snapshots)}`, { cause: error });
   }
 }
 
@@ -676,7 +763,9 @@ export async function updateFlowFromManifest(sdk, instance, identifier, inputMan
   if (manifest.trigger !== undefined) {
     const currentTrigger = findArray(beforeDefinition, 'triggerInstances')[0];
     const currentTable = inputRawValue(inputList(currentTrigger).find(input => input.name === 'table'));
-    const descriptor = await readTableDescriptor(sdk, instance, scope, manifest.trigger.table ?? currentTable, options.readTableDescriptor);
+    const descriptor = options.readTableDescriptor
+      ? await options.readTableDescriptor(manifest.trigger.table ?? currentTable)
+      : await readTableDescriptor(sdk, manifest.trigger.table ?? currentTable);
     triggerUpdate = updatedTrigger(beforeDefinition, manifest, descriptor).update;
     triggerUpdates.push(triggerUpdate);
   }
@@ -720,10 +809,8 @@ export async function updateFlowFromManifest(sdk, instance, identifier, inputMan
       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 = parseMaybeJson(beforeTrigger.metadata, {});
-        const afterMetadata = parseMaybeJson(readbackTrigger.metadata, {});
-        delete beforeMetadata.predicates;
-        delete afterMetadata.predicates;
+        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`);

package/src/flow-designer-interactive.js

@@ -7,7 +7,18 @@ import { FormatAuto } from './output.js';
 import { errUsage, errConfirmationRequired } from './errors.js';
 import { getCurrentUser, getCurrentApplication } from './context.js';
 import { validateDefinition, validateScope, ACTION_TABLE } from './processflow-actions.js';
-import { validateFlowManifest, validateFlowUpdateManifest, readProcessFlow, readActionDefinition, readTableDescriptor } from './flow-create.js';
+import { validateFlowManifest, validateFlowUpdateManifest, readProcessFlow, readActionDefinition } from './flow-create.js';
+import {
+  NUMERIC_TRIGGER_TYPES,
+  PROMPTABLE_TRIGGER_TYPES,
+  conditionInputFor,
+  readTableDescriptor,
+  readTriggerCatalog,
+  readTriggerInputDefinitions,
+  selectableTriggers,
+  tableInputFor,
+  triggerChoiceLabel,
+} from './flow-triggers.js';
 import { deriveRecordTrigger } from './flow-test.js';
 import { getActiveProfile } from './config.js';
 
@@ -253,27 +264,106 @@ async function tableName(argv, app) {
   if (!name) throw errUsage('Selected trigger table has no raw name');
   return name;
 }
+
+// Prompt for one declared trigger input. Choice lists are not exposed by
+// sys_hub_trigger_input on this instance, and every supported family declares
+// its choice/boolean inputs as optional with a default, so those keep the
+// instance default instead of inventing options.
+async function promptTriggerInput(app, input) {
+  if (!input?.name || !input.type) throw errUsage('Provider returned an incomplete named, typed trigger input');
+  if (input.type === 'choice') {
+    if (input.mandatory) throw errUsage(`Trigger input ${input.name} is a mandatory choice whose options this instance does not expose; supply it through --data-file`);
+    return null;
+  }
+  if (input.type === 'boolean') return null;
+  if (!PROMPTABLE_TRIGGER_TYPES.has(input.type)) {
+    throw errUsage(`Trigger input ${input.name} has unsupported type ${input.type}; use --data-file to preserve its complete schema and value`);
+  }
+  const p = prompts(app);
+  const message = `Trigger input: ${input.label || input.name} [${input.type}]`;
+  const fallback = input.defaultValue === '' || input.defaultValue === undefined ? '' : String(input.defaultValue);
+  if (NUMERIC_TRIGGER_TYPES.has(input.type)) {
+    const answer = await p.input({ message, default: scalarDefault(fallback), validate: value => {
+      if (value === '' && input.mandatory) return 'A value is required';
+      if (value === '') return true;
+      return Number.isFinite(Number(value)) ? true : 'Enter a number';
+    } });
+    return answer === '' ? '' : Number(answer);
+  }
+  return p.input({ message, default: scalarDefault(fallback), validate: value => (input.mandatory && value === '' ? 'A value is required' : true) });
+}
+
 export async function guidedFlowCreate(argv, app) {
   if (!interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the flow manifest in noninteractive mode');
-  const manifest = { name: await prompts(app).input({ message: 'Flow name', validate: required }),
-    description: await prompts(app).input({ message: 'Description' }), scope: await designerScope(argv, app),
-    trigger: { type: 'record_create_or_update', table: await tableName(argv, app),
-      condition: await prompts(app).input({ message: 'Trigger condition (single supported encoded predicate, or empty)' }) }, actions: [] };
+  const name = await prompts(app).input({ message: 'Flow name', validate: required });
+  const description = await prompts(app).input({ message: 'Description' });
+  const scope = await designerScope(argv, app);
+  const manifest = { name, description, scope, trigger: { type: '' }, actions: [] };
+
+  // Category first, then the triggers that category actually contains, both
+  // read from the instance (sys_hub_trigger_category + the definition's own
+  // `category` reference). Definitions this CLI cannot create are never offered.
+  const catalog = await readTriggerCatalog(app.sdk);
+  const pickable = catalog.categories.filter(category => selectableTriggers(category).length);
+  if (!pickable.length) {
+    throw errUsage('No supported trigger categories are available on this instance; use --data-file to supply the manifest directly');
+  }
+  const chosenCategory = await prompts(app).select({
+    message: 'Select a trigger category',
+    choices: pickable.map(category => ({ name: `${category.name} (${selectableTriggers(category).length})`, value: category })),
+  });
+  const triggers = selectableTriggers(chosenCategory);
+  const definition = await prompts(app).select({
+    message: `Select a ${chosenCategory.name} trigger`,
+    choices: triggers.map(trigger => ({ name: triggerChoiceLabel(trigger), value: trigger })),
+  });
+  manifest.trigger.type = definition.type;
+
+  const declared = await readTriggerInputDefinitions(app.sdk, definition.sysId);
+  const tableInput = tableInputFor(declared);
+  if (tableInput) {
+    manifest.trigger.table = await tableName(argv, app);
+  }
+  const conditionInput = conditionInputFor(declared);
+  if (conditionInput) {
+    manifest.trigger.condition = await prompts(app).input({ message: 'Trigger condition (single supported encoded predicate, or empty)' });
+  }
+  const optional = declared.filter(input => !tableInput || input.name !== tableInput.name)
+    .filter(input => !conditionInput || input.name !== conditionInput.name);
+  if (optional.some(input => input.mandatory)) {
+    manifest.trigger.inputs = {};
+    for (const input of optional.filter(candidate => candidate.mandatory)) {
+      const value = await promptTriggerInput(app, input);
+      if (value !== null) manifest.trigger.inputs[input.name] = value;
+    }
+  }
+  if (optional.some(input => !input.mandatory && input.type !== 'choice' && input.type !== 'boolean')
+    && await prompts(app).confirm({ message: 'Change optional trigger inputs (otherwise the instance defaults are used)?', default: false })) {
+    manifest.trigger.inputs = manifest.trigger.inputs || {};
+    for (const input of optional.filter(candidate => !candidate.mandatory)) {
+      if (input.type === 'choice' || input.type === 'boolean') continue;
+      if (!await prompts(app).confirm({ message: `Change ${input.label || input.name} [${input.type}]?`, default: false })) continue;
+      const value = await promptTriggerInput(app, input);
+      if (value !== null) manifest.trigger.inputs[input.name] = value;
+    }
+  }
+  if (manifest.trigger.inputs && !Object.keys(manifest.trigger.inputs).length) delete manifest.trigger.inputs;
+
   while (await prompts(app).confirm({ message: 'Add a published action?', default: true })) {
     const id = await pickDesignerRecord(argv, app, ACTION_TABLE, 'published action', 'active=true^published=true');
     if (id === undefined) throw CANCEL;
     const { schema } = await readActionDefinition(app.sdk, app.getEffectiveInstance(), id, manifest.scope, { requireTypes: true });
     const inputs = {};
     for (const field of schema) {
-      if (!field.id || !field.parameter || typeof field.parameter !== 'object' || Array.isArray(field.parameter)) {
-        throw errUsage(`Published action input ${field.name} lacks provider id/parameter metadata; no flow was allocated`);
+      if (!field.id || !field.name) {
+        throw errUsage(`Published action input ${field.name || 'unknown'} lacks the provider identity needed to bind a value; no flow was allocated`);
       }
       inputs[field.name] = await promptSchemaValue(app, field, field.default, 'Action input: ');
     }
     manifest.actions.push({ type: id, inputs });
   }
   validateFlowManifest(manifest);
-  await confirmDesignerSave(app, `Create inactive draft flow '${manifest.name}' with ${manifest.actions.length} action(s)? No publish or execution.`);
+  await confirmDesignerSave(app, `Create inactive draft flow '${manifest.name}' with trigger ${definition.name} and ${manifest.actions.length} action(s)? No publish or execution.`);
   return manifest;
 }
 export async function savedFlowDefinition(app, identifier) {
@@ -319,9 +409,9 @@ export async function guidedFlowEdit(argv, app) {
 export async function guidedFlowTestRecord(argv, app) {
   if (argv.record !== undefined) return argv.record;
   if (!interactiveDesigner(argv, app)) throw errUsage('Provide --record <sys_id> in noninteractive mode');
-  const { record, definition } = await savedFlowDefinition(app, argv.identifier);
+  const { definition } = await savedFlowDefinition(app, argv.identifier);
   const { table } = deriveRecordTrigger(definition);
-  const descriptor = await readTableDescriptor(app.sdk, app.getEffectiveInstance(), rawField(record.scope), table);
+  const descriptor = await readTableDescriptor(app.sdk, table);
   const { identifier: _identifier, ...pickerArgs } = argv;
   return pickDesignerRecord(pickerArgs, app, table, `test record in ${table}`, '', descriptor.displayField);
 }

package/src/flow-triggers.js

@@ -0,0 +1,395 @@
+// Trigger contract for Flow Designer creation.
+//
+// Flow Designer does NOT give a newly POSTed ProcessFlow a default trigger, so
+// the trigger instance must be INSERTED through the same snFlowDesigner
+// GraphQL `flowPatch` that inserts actions. Everything the insert needs is read
+// from the instance's own schema tables — no trigger input is hardcoded:
+//
+//   sys_hub_trigger_definition      one row per trigger ("Created", "Daily", …)
+//   sys_hub_trigger_category        the picker's first level
+//   sys_hub_trigger_input           the inputs a definition declares. The owning
+//                                   definition is carried by `name`, which is
+//                                   `var__m_sys_hub_trigger_input_<definitionId>`;
+//                                   the `model` reference is EMPTY on this
+//                                   instance for most definitions, and a
+//                                   `trigger_definition=` query is silently
+//                                   ignored, so `name` is the only reliable
+//                                   relation.
+//   sys_db_object / sys_dictionary  the record trigger's Table label and display
+//                                   column (the ProcessFlow
+//                                   /trigger/record/table descriptor endpoint
+//                                   does not exist: HTTP 400 "Requested URI does
+//                                   not represent any resource").
+//
+// `internal_type` on sys_hub_trigger_input holds the parameter's real type
+// ("glide_time", "table_name", "conditions", …) as its raw value; its display
+// value is the human label ("Time", "Table Name", …).
+
+export const TRIGGER_DEFINITION_TABLE = 'sys_hub_trigger_definition';
+export const TRIGGER_CATEGORY_TABLE = 'sys_hub_trigger_category';
+export const TRIGGER_INPUT_TABLE = 'sys_hub_trigger_input';
+
+export const TRIGGER_INPUT_NAME_PREFIX = 'var__m_sys_hub_trigger_input_';
+
+// Families this CLI can actually create, each verified against a live instance
+// with a disposable draft flow (see the PR body for the probe sys_ids). The
+// picker intersects this set with the instance's own active definitions, so an
+// unimplemented family can never be offered.
+export const SUPPORTED_TRIGGER_TYPES = new Set([
+  'record_create',
+  'record_update',
+  'record_create_or_update',
+  'daily',
+  'weekly',
+  'monthly',
+  'repeat',
+  'run_once',
+  'email',
+  'knowledge_management',
+  'service_catalog',
+  'sla_task',
+  'remote_table_query',
+]);
+
+// Definitions that exist on the instance but are deliberately not offered, with
+// the reason. Kept explicit so the picker can explain the omission instead of
+// silently hiding a family.
+export const EXCLUDED_TRIGGER_TYPES = new Map([
+  ['analytics', 'the Proactive Analytics trigger definition is inactive on this instance'],
+  ['rest', 'the Trigger Rest definition has no resolvable trigger category'],
+]);
+
+// Families whose declared inputs name a table. The manifest's `table` shortcut
+// maps onto whichever of these the chosen definition declares.
+const TABLE_INPUT_NAMES = ['table', 'u_table', 'target_table'];
+// Same idea for the encoded-query condition.
+const CONDITION_INPUT_NAMES = ['condition', 'email_conditions', 'business_calendar_condition'];
+
+// Trigger input types this CLI can prompt for. Anything else must be supplied
+// through --data-file so its complete schema and value are preserved.
+export const PROMPTABLE_TRIGGER_TYPES = new Set([
+  'string', 'table_name', 'field_name', 'conditions', 'choice', 'reference',
+  'glide_time', 'glide_date_time', 'glide_duration', 'glide_list',
+  'integer', 'decimal', 'float', 'boolean', 'day_of_week', 'month_of_year',
+  'script', 'html', 'url', 'email', 'document_id', 'date', 'datetime',
+]);
+
+export const NUMERIC_TRIGGER_TYPES = new Set(['integer', 'decimal', 'float']);
+
+function rawValue(value) {
+  if (value && typeof value === 'object') return value.value ?? value.sys_id ?? value.name ?? '';
+  return value == null ? '' : value;
+}
+
+function displayValue(value) {
+  if (value && typeof value === 'object') return value.display_value ?? value.value ?? '';
+  return value == null ? '' : value;
+}
+
+function text(value) {
+  const result = rawValue(value);
+  return result == null ? '' : String(result);
+}
+
+export function isSysId(value) {
+  return typeof value === 'string' && /^[0-9a-f]{32}$/i.test(value);
+}
+
+function boolValue(value) {
+  return String(rawValue(value)).toLowerCase() === 'true';
+}
+
+function numeric(value, fallback = 0) {
+  const parsed = Number(rawValue(value));
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/**
+ * The category tree the picker shows, built from the instance's own
+ * sys_hub_trigger_category rows and the category reference each active
+ * definition carries.
+ *
+ * Definitions whose category does not resolve to a readable category record
+ * are returned separately in `ungrouped` — they are never selectable, but the
+ * caller can report them.
+ */
+export async function readTriggerCatalog(sdk) {
+  const [definitions, categories] = await Promise.all([
+    sdk.list(TRIGGER_DEFINITION_TABLE, new URLSearchParams({
+      sysparm_query: 'active=true^ORDERBYname',
+      sysparm_limit: '200',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'sys_id,name,type,active,category,description',
+    })),
+    sdk.list(TRIGGER_CATEGORY_TABLE, new URLSearchParams({
+      sysparm_limit: '200',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'sys_id,name',
+    })),
+  ]);
+
+  const categoryNames = new Map(categories.map(row => [text(row.sys_id), displayValue(row.name) || text(row.name)]));
+  const grouped = new Map();
+  const ungrouped = [];
+
+  for (const row of definitions) {
+    const categoryId = text(row.category);
+    const categoryName = categoryNames.get(categoryId) || '';
+    const definition = {
+      sysId: text(row.sys_id),
+      type: text(row.type),
+      name: displayValue(row.name) || text(row.name),
+      description: displayValue(row.description) || '',
+      supported: SUPPORTED_TRIGGER_TYPES.has(text(row.type)),
+      excludedReason: EXCLUDED_TRIGGER_TYPES.get(text(row.type)) || (SUPPORTED_TRIGGER_TYPES.has(text(row.type)) ? '' : 'this CLI has no verified creation contract for this trigger'),
+    };
+    if (!categoryId || !categoryName) {
+      ungrouped.push(definition);
+      continue;
+    }
+    if (!grouped.has(categoryId)) grouped.set(categoryId, { id: categoryId, name: categoryName, triggers: [] });
+    grouped.get(categoryId).triggers.push(definition);
+  }
+
+  const categoriesOut = [...grouped.values()]
+    .map(category => ({ ...category, triggers: category.triggers.sort((a, b) => a.name.localeCompare(b.name)) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return { categories: categoriesOut, ungrouped };
+}
+
+/** The pickable definitions for one category, in the shape the picker needs. */
+export function selectableTriggers(category) {
+  return (category?.triggers || []).filter(trigger => trigger.supported);
+}
+
+// Definition descriptions are authored HTML; strip it and keep the first
+// sentence so a picker row stays readable.
+export function triggerChoiceLabel(trigger) {
+  const text = String(trigger?.description || '')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!text) return trigger?.name || '';
+  const sentence = text.split(/\.\s/)[0];
+  return `${trigger.name} — ${sentence.length > 90 ? `${sentence.slice(0, 87)}…` : sentence}`;
+}
+
+/**
+ * The inputs a trigger definition declares, straight from
+ * sys_hub_trigger_input. Answers "what must I supply for this family?" from the
+ * instance rather than from a hand-written table.
+ */
+export async function readTriggerInputDefinitions(sdk, definitionId) {
+  if (!isSysId(definitionId)) throw new Error(`Trigger definition id must be an exact sys_id, got "${definitionId}"`);
+  const rows = await sdk.list(TRIGGER_INPUT_TABLE, new URLSearchParams({
+    sysparm_query: `name=${TRIGGER_INPUT_NAME_PREFIX}${definitionId}^ORDERBYorder`,
+    sysparm_limit: '200',
+    sysparm_display_value: 'all',
+    sysparm_fields: 'sys_id,element,label,column_label,internal_type,mandatory,order,max_length,default_value,attributes,choice,reference,use_dependent_field,dependent_on_field,read_only,hint',
+  }));
+  return rows
+    .map(normalizeTriggerInput)
+    .filter(input => input.name);
+}
+
+function normalizeTriggerInput(row) {
+  const parameter = {
+    id: text(row.sys_id),
+    label: displayValue(row.label) || displayValue(row.column_label) || text(row.element),
+    name: text(row.element),
+    type: text(row.internal_type),
+    hint: displayValue(row.hint) || '',
+    order: numeric(row.order),
+    extended: false,
+    mandatory: boolValue(row.mandatory),
+    readonly: boolValue(row.read_only),
+    maxsize: numeric(row.max_length),
+    children: [],
+    reference: text(row.reference) ? displayValue(row.reference) : '',
+    reference_display: '',
+    ref_qual: '',
+    choiceOption: text(row.choice),
+    table: '',
+    columnName: '',
+    defaultValue: rawValue(row.default_value) ?? '',
+    use_dependent: boolValue(row.use_dependent_field),
+    dependent_on: text(row.dependent_on_field),
+    show_ref_finder: false,
+    local: false,
+    // On INPUT the GraphQL type is String; the read path renders it as an object.
+    attributes: text(row.attributes),
+  };
+  return {
+    id: parameter.id,
+    name: parameter.name,
+    label: parameter.label,
+    type: parameter.type,
+    mandatory: parameter.mandatory,
+    order: parameter.order,
+    defaultValue: parameter.defaultValue === '' ? '' : String(parameter.defaultValue),
+    reference: parameter.reference,
+    parameter,
+  };
+}
+
+/**
+ * The record trigger's table metadata. The documented ProcessFlow descriptor
+ * route (/api/now/processflow/trigger/record/table) does not exist on this
+ * instance, so the label comes from sys_db_object and the display column from
+ * the nearest sys_dictionary `display=true` element walking up the
+ * super_class chain (a child table such as `ticket` inherits `number` from
+ * `task`).
+ */
+export async function readTableDescriptor(sdk, table) {
+  const name = String(table || '').trim();
+  if (!name) throw new Error('Record trigger requires a table name');
+  const rows = await sdk.list('sys_db_object', new URLSearchParams({
+    sysparm_query: `name=${name}`,
+    sysparm_limit: '2',
+    sysparm_display_value: 'all',
+    sysparm_fields: 'name,label,super_class',
+  }));
+  if (rows.length !== 1) throw new Error(rows.length === 0 ? `Table not found: ${name}` : `Table name is ambiguous: ${name}`);
+  const label = displayValue(rows[0].label) || text(rows[0].label);
+  if (!label) throw new Error(`Table ${name} has no label`);
+  return { table: name, label, displayField: await readDisplayField(sdk, name, text(rows[0].super_class)) };
+}
+
+async function readDisplayField(sdk, table, superId) {
+  let current = table;
+  let parentId = superId;
+  for (let depth = 0; depth < 16 && current; depth += 1) {
+    const field = await sdk.list('sys_dictionary', new URLSearchParams({
+      sysparm_query: `name=${current}^display=true`,
+      sysparm_limit: '5',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'element',
+    }));
+    const element = field.map(row => text(row.element)).find(Boolean);
+    if (element) return element;
+    if (!parentId) return '';
+    const parent = await sdk.list('sys_db_object', new URLSearchParams({
+      sysparm_query: `sys_id=${parentId}`,
+      sysparm_limit: '2',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'name,super_class',
+    }));
+    if (parent.length !== 1) return '';
+    current = text(parent[0].name);
+    parentId = text(parent[0].super_class);
+  }
+  return '';
+}
+
+/** The declared input a manifest shortcut (`table`, `condition`) should drive. */
+export function tableInputFor(declared) {
+  return declared.find(input => TABLE_INPUT_NAMES.includes(input.name)) || null;
+}
+
+export function conditionInputFor(declared) {
+  return declared.find(input => CONDITION_INPUT_NAMES.includes(input.name)) || null;
+}
+
+function wrapped(value) {
+  const scalar = value === '' || value === null || value === undefined ? '' : String(value);
+  return { schemaless: false, schemalessValue: '', value: scalar };
+}
+
+function declaredDefault(input) {
+  return input.defaultValue === '' || input.defaultValue === undefined ? '' : input.defaultValue;
+}
+
+/**
+ * Turn a definition's declared inputs plus the caller's values into the exact
+ * `inputs` array the snFlowDesigner insert expects.
+ *
+ * Every declared input is written, using the instance's own default when the
+ * caller supplies nothing, because Flow Designer stores the full input set
+ * (a real record trigger carries run_on_extended / run_flow_in /
+ * run_when_setting / … alongside table and condition).
+ */
+export function buildTriggerInputs(declared, supplied = {}, tableDescriptor = null) {
+  const byName = new Map(declared.map(input => [input.name, input]));
+  for (const name of Object.keys(supplied)) {
+    if (!byName.has(name)) throw new Error(`Trigger input "${name}" is not declared by this trigger definition`);
+  }
+  for (const input of declared) {
+    const value = Object.prototype.hasOwnProperty.call(supplied, input.name) ? supplied[input.name] : declaredDefault(input);
+    const resolved = value === '' || value === null || value === undefined ? '' : String(value);
+    if (resolved === '' && input.mandatory) throw new Error(`Trigger input "${input.name}" (${input.label || input.type}) is required`);
+    const tableValue = tableDescriptor && TABLE_INPUT_NAMES.includes(input.name);
+    const renderedValue = tableValue ? tableDescriptor.table : resolved;
+    const renderedDisplay = tableValue ? tableDescriptor.label : resolved;
+    if (!input.parameter?.id) throw new Error(`Trigger input "${input.name}" is missing its provider identity; refusing to invent one`);
+    byName.get(input.name).value = renderedValue;
+    byName.get(input.name).displayValue = renderedDisplay;
+    byName.get(input.name).displayField = tableValue ? tableDescriptor.displayField || '' : '';
+  }
+  return declared.map(input => ({
+    name: input.name,
+    value: wrapped(input.value),
+    displayValue: wrapped(input.displayValue),
+    displayField: input.displayField || '',
+    scriptActive: false,
+    label: input.parameter.label,
+    internalType: input.parameter.type,
+    fromTemplate: false,
+    order: input.parameter.order,
+    valueSysId: '',
+    mandatory: input.parameter.mandatory === true,
+    parameter: input.parameter,
+  }));
+}
+
+/** The triggerInstances.insert payload for the snFlowDesigner flow patch. */
+export function buildTriggerInstance({ flowId, definition, triggerType = '', inputs, metadata = '{}' }) {
+  if (!flowId) throw new Error('Trigger insert requires the created flow id');
+  if (!definition?.sysId || !definition?.type) throw new Error('Trigger insert requires a resolved trigger definition');
+  return {
+    flowSysId: flowId,
+    name: definition.name,
+    type: definition.type,
+    triggerType: triggerType || '',
+    triggerDefinitionId: definition.sysId,
+    metadata,
+    inputs,
+  };
+}
+
+// The snFlowDesigner GraphQL input types take `attributes` as a String
+// ("key=value,key=value") even though the ProcessFlow read path renders it as an
+// object. Sending the object fails validation: "not a valid 'String'".
+export function attributesToString(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('Provider attributes must be a string or a flat object');
+  return Object.entries(value).map(([key, item]) => `${key}=${item}`).join(',');
+}
+
+// Accepted `parameter` keys on global_snFlowDesigner_FlowDesignParameter.
+// GraphQL introspection is disabled on this instance, so this list was
+// established empirically by probing each candidate field against the live
+// schema (unknown keys answer "contains a field not in
+// 'global_snFlowDesigner_FlowDesignParameter'"). Anything the ProcessFlow
+// action definition returns that is NOT in this list — notably the synthetic
+// `default` this CLI adds, plus `scriptActive`/`value`/`displayValue` — must be
+// carried elsewhere or dropped, or the mutation fails validation.
+const FLOW_DESIGN_PARAMETER_FIELDS = [
+  'id', 'label', 'name', 'type', 'type_label', 'hint', 'order', 'extended',
+  'mandatory', 'readonly', 'maxsize', 'children', 'data_structure', 'reference',
+  'reference_display', 'ref_qual', 'choiceOption', 'table', 'columnName',
+  'defaultValue', 'defaultDisplayValue', 'use_dependent', 'dependent_on',
+  'show_ref_finder', 'local', 'attributes', 'sys_class_name', 'choices',
+  'defaultChoices', 'uiDisplayType', 'uiDisplayTypeLabel', 'placeholder',
+  'comments', 'internal_link', 'dynamic', 'searchField',
+];
+
+/** A provider schema entry narrowed to the GraphQL parameter input type. */
+export function flowDesignParameter(entry) {
+  const out = {};
+  for (const key of FLOW_DESIGN_PARAMETER_FIELDS) if (entry?.[key] !== undefined) out[key] = entry[key];
+  out.attributes = attributesToString(entry?.attributes);
+  return out;
+}