@tenonhq/dovetail-servicenow 0.0.27 → 0.0.28

package/README.md

@@ -201,8 +201,62 @@ npx dove-sn edit-action --sys-id <action_type_sys_id> --scope <scope_sys_id> \
   --patch-script "grabHashData::grabRecipients"                                   # dry-run (diff)
 npx dove-sn edit-action --sys-id <id> --scope <scope> --set-script ./script.js \
   --merge-outputs ./output-var.json --apply --update-set <id>                     # persist + publish
+
+# Edit it STRUCTURALLY — several steps' scripts, step-level IO, pill wiring — in one publish
+npx dove-sn edit-action --sys-id <id> --scope <scope> --from-json ops.json             # dry-run
+npx dove-sn edit-action --sys-id <id> --scope <scope> --from-json ops.json \
+  --apply --update-set <id>                                                            # publish + verify
+```
+
+### Editing an action type's steps (`--from-json`)
+
+The flag form above patches the one auto-detected script. When you need to touch
+more than one step — or the step's own inputs and outputs — pass an ops file:
+
+```json
+{
+  "patchStepScripts": [
+    { "step": "Parse Response", "scriptFile": "./parse-response.js" },
+    { "step": "Handle Error", "patchScript": { "find": "gs.error", "replace": "gs.warn" } }
+  ],
+  "addStepOutputs": [
+    { "step": "Parse Response", "name": "isRetryable", "label": "Is Retryable", "type": "boolean" }
+  ],
+  "addStepInputs": [
+    {
+      "step": "Handle Error",
+      "name": "isRetryable",
+      "type": "boolean",
+      "pillFrom": { "step": "Parse Response", "output": "isRetryable" }
+    }
+  ]
+}
 ```
 
+- **`step`** is a step's `cid` **or** its label — an unknown ref fails with the list of steps that do exist.
+- **`scriptFile`** is sugar for `setScript`, resolved **relative to the ops file**, so scripts can live beside it.
+- **`addStepInputs[].pillFrom`** wires the input to another step's output. You never write the pill
+  yourself — the correct format is `{{step[<source_cid>].<output>}}`, and getting it wrong does not
+  fail the publish, it compiles a dead reference that reads `undefined` at runtime.
+- Ops are **order-independent**: an input may pill from an output added in the same call. Everything
+  lands in a **single** `/snapshot` POST.
+- Adding IO is **idempotent** — a name that is already present is skipped with a warning, not duplicated.
+
+Two behaviours worth knowing before you rely on this:
+
+**It refuses to guess an entry shape.** A new `extended_inputs` / `extended_outputs` entry is built by
+mirroring an existing sibling entry on the same step, because those entries carry more keys than the
+four you supply and some are wrapped as `{value: x}` inconsistently. If the step has *no* existing
+entry in that list, there is nothing to mirror and the command **errors out** rather than hand-author
+an object that would corrupt the action. Author one entry in the Designer first, then re-run.
+
+**It verifies the publish.** A `201` from `/snapshot` means the snapshot compiled — not that your edit
+landed as intended. With `--apply`, the steps are read back from the instance and compared against what
+was sent: script **content** (hashed, so a same-length-but-different script can't pass) and each IO
+entry's **name, type and value** — so an entry that landed with a mis-wired pill is caught, not just a
+missing one. A mismatch prints the diff and exits **2**. When every op was a no-op, there is nothing to
+read back and the round-trip is skipped.
+
 `copy-flow` calls the Designer's own `POST /processflow/flow/{id}/copy` — a
 complete, faithful clone created as an **inactive draft**. (Don't publish +
 activate a copy of a triggered production flow unless you intend it to fire.)
@@ -427,7 +481,9 @@ Claude Code and agents: `create_view`, `set_list_layout`, `set_form_layout`,
 existing record) and `create_record` (insert one record) — both update-set-captured
 and read-back-verified — `host_assets` (deploy a built dist/), plus the Flow Designer
 tools `flow_view` (read a flow/subflow's step graph), `action_view` (read an action
-type's model), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
+type's model), `action_edit` (structurally edit a published action type — per-step
+scripts, step-level inputs/outputs, data-pill wiring — dry-run by default, and the
+publish is read back and verified), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
 (copy a flow as an inactive draft), `flow_create` (create a NEW flow from scratch +
 publish, grafting a template), `flow_test` (validate or run a flow), and
 `flow_edit` (patch a flow), plus `invoke_rest` (invoke an arbitrary authenticated

package/dist/cli.js

@@ -666,17 +666,54 @@ async function runEditFlow(flags) {
  * dove-sn edit-action:
  *   --sys-id <sys_id>                  Required. sys_hub_action_type_definition sys_id.
  *   --scope <sys_id>                   Required. sysparm_transaction_scope (app scope sys_id).
- *   --patch-script "<find>::<replace>" Optional. Find/replace in the script step value.
- *   --set-script <path>                Optional. Replace the script step value from a file.
+ *   --from-json <path>                 Optional. JSON EditActionTypeOps — the full surface, incl.
+ *                                      per-step ops: patchStepScripts / addStepOutputs / addStepInputs.
+ *   --patch-script "<find>::<replace>" Optional. Find/replace in the auto-detected script step value.
+ *   --set-script <path>                Optional. Replace the auto-detected script step value from a file.
  *   --merge-outputs <path>             Optional. JSON file: an output-variable object/array to merge by name.
  *   --script-input <name>              Optional. Input name holding the script (default: auto-detect).
  *   --update-set <sys_id>              Optional. Capture the republish into this update set.
  *   --apply                            Optional. Republish (POST /snapshot). Omit for dry-run.
  *   --json                             Optional. Emit the structured EditActionTypeResult.
  *
- * Edits a published Custom Action Type's script and/or output variables and
- * republishes through the snapshot POST. Dry-run (read-only) by default; --apply writes.
+ * Edits a published Custom Action Type and republishes through the snapshot POST.
+ * Dry-run (read-only) by default; --apply writes.
+ *
+ * The flag form handles the single-script case. For anything structural — patching
+ * several steps' scripts, adding a step-level output, adding a step-level input
+ * pill-wired to another step's output — use --from-json:
+ *
+ *   {
+ *     "patchStepScripts": [{ "step": "Parse Response", "scriptFile": "./parse.js" }],
+ *     "addStepOutputs":   [{ "step": "Parse Response", "name": "isRetryable", "type": "boolean" }],
+ *     "addStepInputs":    [{ "step": "Handle Error", "name": "isRetryable", "type": "boolean",
+ *                            "pillFrom": { "step": "Parse Response", "output": "isRetryable" } }]
+ *   }
+ *
+ * `step` is a step cid or label. `scriptFile` is sugar for `setScript` and is
+ * resolved RELATIVE TO THE OPS FILE, so an ops file can sit next to its scripts.
  */
+/** Resolve `scriptFile` sugar in patchStepScripts, relative to the ops file's own dir. */
+function resolveScriptFiles(ops, opsPath) {
+    var stepScripts = ops.patchStepScripts;
+    if (!Array.isArray(stepScripts)) {
+        return;
+    }
+    var opsDir = path.dirname(path.resolve(opsPath));
+    for (var i = 0; i < stepScripts.length; i += 1) {
+        var op = stepScripts[i];
+        if (!op || typeof op !== "object" || typeof op.scriptFile !== "string") {
+            continue;
+        }
+        if (typeof op.setScript === "string") {
+            throw new Error("edit-action: step '" +
+                String(op.step) +
+                "' sets both scriptFile and setScript — pick one.");
+        }
+        op.setScript = fs.readFileSync(path.resolve(opsDir, op.scriptFile), "utf8");
+        delete op.scriptFile;
+    }
+}
 async function runEditAction(flags) {
     var sysId = flags["sys-id"] || flags.sysId;
     var scope = flags.scope || flags.scopeSysId;
@@ -685,6 +722,14 @@ async function runEditAction(flags) {
         return 1;
     }
     var ops = {};
+    if (flags["from-json"]) {
+        ops = JSON.parse(fs.readFileSync(flags["from-json"], "utf8"));
+        if (!ops || typeof ops !== "object" || Array.isArray(ops)) {
+            process.stderr.write("edit-action: --from-json must contain an EditActionTypeOps object\n");
+            return 1;
+        }
+        resolveScriptFiles(ops, flags["from-json"]);
+    }
     if (flags["patch-script"]) {
         var parts = String(flags["patch-script"]).split("::");
         if (parts.length !== 2) {
@@ -730,6 +775,51 @@ async function runEditAction(flags) {
     for (var wi = 0; wi < result.warnings.length; wi += 1) {
         process.stdout.write("  ! " + result.warnings[wi] + "\n");
     }
+    // Per-step before/after — the dry-run's whole job is to make this inspectable.
+    if (result.stepsBefore && result.stepsAfter) {
+        process.stdout.write("\n--- steps (before -> after) ---\n");
+        for (var si = 0; si < result.stepsAfter.length; si += 1) {
+            var after = result.stepsAfter[si];
+            var before = result.stepsBefore[si];
+            var io = function (label, list) {
+                if (list.length === 0) {
+                    return "";
+                }
+                var rendered = list
+                    .map(function (e) {
+                    return e.name + (e.value ? "=" + e.value : "");
+                })
+                    .join(", ");
+                return "\n      " + label + ": " + rendered;
+            };
+            process.stdout.write("  " +
+                after.label +
+                " (" +
+                after.cid +
+                ")\n" +
+                "      script: " +
+                String(before ? before.scriptChars : "?") +
+                " -> " +
+                String(after.scriptChars) +
+                " chars" +
+                io("in ", after.extendedInputs) +
+                io("out", after.extendedOutputs) +
+                "\n");
+        }
+    }
+    if (result.verified) {
+        process.stdout.write("\n--- verify (read back from the instance) ---\n");
+        process.stdout.write("  " + (result.verified.ok ? "OK" : "FAILED") + "\n");
+        for (var vi = 0; vi < result.verified.notes.length; vi += 1) {
+            process.stdout.write("  " +
+                (result.verified.ok ? "+ " : "! ") +
+                result.verified.notes[vi] +
+                "\n");
+        }
+        if (!result.verified.ok) {
+            return 2;
+        }
+    }
     if (result.status === "preview" &&
         result.scriptAfter !== undefined &&
         result.scriptAfter !== result.scriptBefore) {
@@ -801,6 +891,12 @@ function printHelp() {
         "                      [--update-set <sys_id>] [--max-bytes <n>] [--allow-oversize] [--dry-run] [--json])\n" +
         "  test-flow          Validate (default) or run a flow/subflow\n" +
         "                     (--sys-id <sys_id> [--execute --confirm] [--inputs <json>] [--json])\n" +
+        "  edit-action        Patch a published Custom Action Type and republish (snapshot)\n" +
+        "                     (--sys-id <sys_id> --scope <sys_id>\n" +
+        "                      --from-json <ops.json>  ops: patchStepScripts / addStepOutputs / addStepInputs\n" +
+        "                                              (per-step scripts + step IO + data-pill wiring)\n" +
+        '                      | --patch-script "<find>::<replace>" | --set-script <path> | --merge-outputs <path>\n' +
+        "                      [--script-input <name>] [--update-set <sys_id>] [--apply] [--json])\n" +
         "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
         "                     (--sys-id <sys_id> --from-json <ops.json> [--apply] [--update-set <sys_id>] [--scope <sys_id>] [--json])\n" +
         "  mcp                Run the MCP stdio server (--smoke lists tools and exits)\n" +

package/dist/flowDesigner/editActionType.d.ts

@@ -23,6 +23,7 @@
  * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
  */
 import type { ServiceNowClient } from "../client";
+import type { AddStepInputOp, AddStepOutputOp, PatchStepScriptOp, StepSummary, VerifyStepsResult } from "./stepOps";
 export interface EditActionTypeOps {
     /** Replace every occurrence of `find` with `replace` inside the script step value. */
     patchScript?: {
@@ -31,6 +32,25 @@ export interface EditActionTypeOps {
     };
     /** Replace the script step value outright (wins over patchScript). */
     setScript?: string;
+    /**
+     * Per-step script edits, addressing each step by `cid` or `label`. Use this
+     * instead of patchScript/setScript when the action has more than one scripted
+     * step, or when you need to target a specific one rather than the auto-detected
+     * first match.
+     */
+    patchStepScripts?: Array<PatchStepScriptOp>;
+    /**
+     * Step-level outputs (`extended_outputs`) to add — the values one step exposes
+     * to the steps after it. Idempotent: an output whose name is already present is
+     * skipped, not duplicated.
+     */
+    addStepOutputs?: Array<AddStepOutputOp>;
+    /**
+     * Step-level inputs (`extended_inputs`) to add, each wired by data pill to
+     * another step's output via `pillFrom: { step, output }`. Outputs added in the
+     * same call are visible to these — it all lands in one snapshot.
+     */
+    addStepInputs?: Array<AddStepInputOp>;
     /**
      * Output-variable definition objects to merge into `model.outputs`, matched by
      * `name` (replaced in place, else appended). Supply the modeled output JSON —
@@ -63,6 +83,15 @@ export interface EditActionTypeResult {
     scriptBefore?: string;
     scriptAfter?: string;
     outputsMerged: Array<string>;
+    /** Per-step scripts + step-level IO, as read (before) and as sent (after). */
+    stepsBefore?: Array<StepSummary>;
+    stepsAfter?: Array<StepSummary>;
+    /**
+     * Post-publish read-back of /step_instances for the steps we touched. A 201 from
+     * /snapshot means "compiled", not "your edit landed" — only set when applied and
+     * step ops were supplied.
+     */
+    verified?: VerifyStepsResult;
     /** HTTP status of the snapshot POST (201 on success); only set when applied. */
     httpStatus?: number;
     snapshotSysId?: string;

package/dist/flowDesigner/editActionType.js

@@ -25,6 +25,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.editActionType = editActionType;
+const stepOps_1 = require("./stepOps");
 function actionTypePath(sysId, scopeSysId, suffix) {
     return "/api/now/processflow/action/action_types/" + encodeURIComponent(sysId)
         + suffix
@@ -70,12 +71,21 @@ async function editActionType(params) {
     if (!scopeSysId) {
         throw new Error("editActionType: scopeSysId is required (sysparm_transaction_scope).");
     }
-    if (!ops.patchScript && !ops.setScript && !(ops.mergeOutputs && ops.mergeOutputs.length > 0)) {
-        throw new Error("editActionType: no ops — supply patchScript, setScript, and/or mergeOutputs.");
+    var stepOpsSupplied = (0, stepOps_1.hasStepOps)(ops);
+    if (!ops.patchScript && !ops.setScript && !(ops.mergeOutputs && ops.mergeOutputs.length > 0) && !stepOpsSupplied) {
+        throw new Error("editActionType: no ops — supply patchScript, setScript, mergeOutputs, "
+            + "patchStepScripts, addStepOutputs, and/or addStepInputs.");
+    }
+    if (stepOpsSupplied && (ops.patchScript || ops.setScript)) {
+        throw new Error("editActionType: patchScript/setScript (auto-detected single script) cannot be combined with "
+            + "patchStepScripts (explicit per-step). Use patchStepScripts for all script edits.");
     }
     var changes = [];
     var warnings = [];
     var outputsMerged = [];
+    var stepsBefore;
+    var stepsAfter;
+    var touchedCids = [];
     // 1. GET the model (outputs[], steps:null).
     var model = unwrap(await client.now.get(actionTypePath(sysId, scopeSysId, "")));
     if (!model || typeof model !== "object") {
@@ -87,6 +97,20 @@ async function editActionType(params) {
     if (steps.length === 0) {
         throw new Error("editActionType: /step_instances returned no steps for action type " + sysId);
     }
+    // 2b. Per-step ops — scripts, step-level IO, pill wiring. Pure; see stepOps.ts.
+    if (stepOpsSupplied) {
+        stepsBefore = (0, stepOps_1.summarizeSteps)(steps);
+        var applied = (0, stepOps_1.applyStepOps)(steps, {
+            patchStepScripts: ops.patchStepScripts,
+            addStepOutputs: ops.addStepOutputs,
+            addStepInputs: ops.addStepInputs
+        });
+        steps = applied.steps;
+        stepsAfter = (0, stepOps_1.summarizeSteps)(steps);
+        touchedCids = applied.touchedCids;
+        changes = changes.concat(applied.changes);
+        warnings = warnings.concat(applied.warnings);
+    }
     // 3. Patch the script step input.
     var scriptBefore;
     var scriptAfter;
@@ -164,7 +188,9 @@ async function editActionType(params) {
             warnings: warnings,
             scriptBefore: scriptBefore,
             scriptAfter: scriptAfter,
-            outputsMerged: outputsMerged
+            outputsMerged: outputsMerged,
+            stepsBefore: stepsBefore,
+            stepsAfter: stepsAfter
         };
     }
     // 6. Apply: optionally pin the update set, then POST /snapshot (compiles the
@@ -183,6 +209,27 @@ async function editActionType(params) {
             snapshotSysId = snap;
         }
     }
+    // 7. Verify — a 201 says the snapshot compiled, not that the edit landed as
+    //    intended. Read the steps back and compare against what we sent.
+    var verified;
+    if (stepOpsSupplied && touchedCids.length === 0) {
+        // Every op was a no-op (already present / nothing to patch) — there is nothing
+        // to read back, so don't spend a round-trip proving we changed nothing.
+        verified = { ok: true, notes: ["no step changed — nothing to verify"] };
+    }
+    else if (stepOpsSupplied && stepsAfter) {
+        var freshResp = unwrap(await client.now.get(actionTypePath(sysId, scopeSysId, "/step_instances")));
+        var freshSteps = freshResp && Array.isArray(freshResp.steps) ? freshResp.steps : [];
+        if (freshSteps.length === 0) {
+            verified = { ok: false, notes: ["read-back returned no steps — could not verify the publish"] };
+        }
+        else {
+            verified = (0, stepOps_1.verifySteps)(stepsAfter, (0, stepOps_1.summarizeSteps)(freshSteps), touchedCids);
+        }
+        if (!verified.ok) {
+            warnings.push("VERIFY FAILED — the snapshot compiled but the read-back does not match what was sent");
+        }
+    }
     return {
         status: "published",
         changes: changes,
@@ -190,6 +237,9 @@ async function editActionType(params) {
         scriptBefore: scriptBefore,
         scriptAfter: scriptAfter,
         outputsMerged: outputsMerged,
+        stepsBefore: stepsBefore,
+        stepsAfter: stepsAfter,
+        verified: verified,
         httpStatus: 201,
         snapshotSysId: snapshotSysId
     };

package/dist/flowDesigner/index.d.ts

@@ -18,6 +18,8 @@ export { publishActionType } from "./publishActionType";
 export type { PublishActionTypeParams, PublishActionTypeResult } from "./publishActionType";
 export { editActionType } from "./editActionType";
 export type { EditActionTypeParams, EditActionTypeResult, EditActionTypeOps } from "./editActionType";
+export { applyStepOps, verifySteps, summarizeSteps, formatStepPill, findStep, hasStepOps } from "./stepOps";
+export type { StepOps, StepRecord, StepSummary, StepIoSummary, PatchStepScriptOp, AddStepOutputOp, AddStepInputOp, ApplyStepOpsResult, VerifyStepsResult } from "./stepOps";
 export { readFlow } from "./readFlow";
 export type { ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable } from "./readFlow";
 export { readActionType } from "./readActionType";

package/dist/flowDesigner/index.js

@@ -6,7 +6,7 @@
  * functions land in Phase 1.C/D.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.hasStepOps = exports.findStep = exports.formatStepPill = exports.summarizeSteps = exports.verifySteps = exports.applyStepOps = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
 var listTemplates_1 = require("./listTemplates");
 Object.defineProperty(exports, "listTemplates", { enumerable: true, get: function () { return listTemplates_1.listTemplates; } });
 var verifyArtifact_1 = require("./verifyArtifact");
@@ -21,6 +21,13 @@ var publishActionType_1 = require("./publishActionType");
 Object.defineProperty(exports, "publishActionType", { enumerable: true, get: function () { return publishActionType_1.publishActionType; } });
 var editActionType_1 = require("./editActionType");
 Object.defineProperty(exports, "editActionType", { enumerable: true, get: function () { return editActionType_1.editActionType; } });
+var stepOps_1 = require("./stepOps");
+Object.defineProperty(exports, "applyStepOps", { enumerable: true, get: function () { return stepOps_1.applyStepOps; } });
+Object.defineProperty(exports, "verifySteps", { enumerable: true, get: function () { return stepOps_1.verifySteps; } });
+Object.defineProperty(exports, "summarizeSteps", { enumerable: true, get: function () { return stepOps_1.summarizeSteps; } });
+Object.defineProperty(exports, "formatStepPill", { enumerable: true, get: function () { return stepOps_1.formatStepPill; } });
+Object.defineProperty(exports, "findStep", { enumerable: true, get: function () { return stepOps_1.findStep; } });
+Object.defineProperty(exports, "hasStepOps", { enumerable: true, get: function () { return stepOps_1.hasStepOps; } });
 var readFlow_1 = require("./readFlow");
 Object.defineProperty(exports, "readFlow", { enumerable: true, get: function () { return readFlow_1.readFlow; } });
 var readActionType_1 = require("./readActionType");

package/dist/flowDesigner/stepOps.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Step-graph operations for a Custom Action Type — the pure half of `editActionType`.
+ *
+ * Everything here operates on the `steps` array returned by
+ * `GET /api/now/processflow/action/action_types/{id}/step_instances`. No client,
+ * no network: the step graph goes in, a patched copy comes out, and the caller
+ * grafts it onto the model and POSTs `/snapshot`.
+ *
+ * Two facts about that payload were established against a live instance and are
+ * enforced here, because getting either wrong corrupts the action type in a way
+ * the publish POST happily accepts:
+ *
+ * 1. STEP-TO-STEP DATA PILL FORMAT — `{{step[<source_cid>].<output_name>}}`.
+ *    NOT `{{<cid>.<name>}}`, which is what the flow-variable pill syntax suggests.
+ *    A wrong pill does not fail the publish; it compiles a snapshot with a dead
+ *    reference, and the action silently reads `undefined` at runtime.
+ *
+ * 2. NEW IO ENTRIES MUST MIRROR AN EXISTING SIBLING — an `extended_inputs` /
+ *    `extended_outputs` entry carries more keys than the four you care about, and
+ *    some are wrapped as `{value: x}` while others are bare, inconsistently by key.
+ *    So a new entry is a deep copy of an existing entry from the SAME list with
+ *    only our keys overwritten, preserving each key's wrapped-vs-bare shape.
+ *    When the list is empty there is no shape to mirror and we refuse rather than
+ *    guess — a clear error beats a corrupted action type.
+ *
+ * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
+ */
+/** A step's field value: either bare, or wrapped by the Designer as `{ value: x }`. */
+export type StepScalar = string | number | boolean | null;
+/** One entry in a step's `inputs` / `extended_inputs` / `extended_outputs` list. */
+export interface IoEntry {
+    [key: string]: unknown;
+}
+/** One step from `/step_instances`. */
+export interface StepRecord {
+    [key: string]: unknown;
+}
+export interface PatchStepScriptOp {
+    /** Step to patch — its `cid`, or its `label`/`name`. */
+    step: string;
+    /** Replace the script outright (wins over patchScript). */
+    setScript?: string;
+    /** Replace every occurrence of `find` with `replace` inside the script. */
+    patchScript?: {
+        find: string;
+        replace: string;
+    };
+    /** Input name holding the script. Default: auto-detect (`script`, else by signature). */
+    scriptInputName?: string;
+}
+export interface AddStepOutputOp {
+    /** Step to add the output to — its `cid`, or its `label`/`name`. */
+    step: string;
+    name: string;
+    label?: string;
+    /** ServiceNow variable type. Default: "boolean". */
+    type?: string;
+}
+export interface AddStepInputOp {
+    /** Step to add the input to — its `cid`, or its `label`/`name`. */
+    step: string;
+    name: string;
+    label?: string;
+    /** ServiceNow variable type. Default: "boolean". */
+    type?: string;
+    /** Wire the input's value to another step's output via a data pill. */
+    pillFrom: {
+        step: string;
+        output: string;
+    };
+}
+export interface StepOps {
+    patchStepScripts?: Array<PatchStepScriptOp>;
+    addStepOutputs?: Array<AddStepOutputOp>;
+    addStepInputs?: Array<AddStepInputOp>;
+}
+export interface StepIoSummary {
+    name: string;
+    type: string;
+    value: string;
+}
+export interface StepSummary {
+    label: string;
+    cid: string;
+    /** For display. NOT sufficient to verify a script — two different scripts can share a length. */
+    scriptChars: number | null;
+    /** Content hash of the script — what the verify pass actually compares. */
+    scriptHash: string | null;
+    extendedInputs: Array<StepIoSummary>;
+    extendedOutputs: Array<StepIoSummary>;
+}
+export interface ApplyStepOpsResult {
+    /** A patched deep copy — the input graph is never mutated. */
+    steps: Array<StepRecord>;
+    changes: Array<string>;
+    warnings: Array<string>;
+    /** cids of the steps an op actually changed — what the verify pass re-reads. */
+    touchedCids: Array<string>;
+}
+export interface VerifyStepsResult {
+    ok: boolean;
+    notes: Array<string>;
+}
+/** Unwrap the Designer's `{ value: x }` envelope; pass anything else through. */
+export declare function unwrapValue(v: unknown): unknown;
+/** Coerce an unwrapped field to a string ("" for null/undefined/objects). */
+export declare function readString(v: unknown): string;
+/** A step's addressable identity: its `cid` and its human label. */
+export declare function stepIdentity(step: StepRecord): {
+    cid: string;
+    label: string;
+};
+/** Find a step by `cid` or by `label`/`name`. Throws listing what IS there. */
+export declare function findStep(steps: Array<StepRecord>, ref: string): StepRecord;
+/** Locate the input holding a step's script — by name, else by script signature. */
+export declare function findScriptInput(step: StepRecord, inputName?: string): IoEntry | null;
+/** Format a step-to-step data pill. THE format — see the header note. */
+export declare function formatStepPill(sourceCid: string, outputName: string): string;
+/**
+ * FNV-1a over the script text. The verify pass compares content, not length —
+ * two different scripts of the same length must not pass as equal.
+ */
+export declare function hashScript(script: string): string;
+/** A compact, loggable view of a step's scripts and step-level IO. */
+export declare function summarizeSteps(steps: Array<StepRecord>): Array<StepSummary>;
+/**
+ * Apply per-step ops to a DEEP COPY of the step graph.
+ *
+ * Outputs are added before inputs, so an input may pill from an output created in
+ * the same call — everything lands in one `/snapshot` POST.
+ */
+export declare function applyStepOps(steps: Array<StepRecord>, ops: StepOps): ApplyStepOpsResult;
+/**
+ * Compare what we published against what the instance now reports, for the steps
+ * we touched. A 201 from `/snapshot` means "snapshot compiled", NOT "your edit
+ * landed the way you meant it" — so read the steps back and prove it.
+ */
+export declare function verifySteps(expected: Array<StepSummary>, actual: Array<StepSummary>, touchedCids: Array<string>): VerifyStepsResult;
+/** True when `ops` carries at least one per-step op. */
+export declare function hasStepOps(ops: StepOps): boolean;