@tenonhq/dovetail-servicenow 0.0.44 → 0.0.46

package/README.md

@@ -652,6 +652,73 @@ Three consequences, each reported rather than hidden:
 single request goes out. Exit codes: `0` created / skipped / dry-run, `1` bad args, `2`
 failed (the lying-row case included).
 
+### List a table's indexes
+
+```bash
+npx dove-sn index-list --table x_cadso_automate_message_batch_recipient --json
+```
+
+Read-only: no form session, no writes. **`v_db_index` is the index read surface** - and
+the only one. `sys_index` fails an API-LEVEL ACL (HTTP 403) for every identity including
+admin, and `sys_index_column` does not exist at all (HTTP 400 `Invalid table`), so there
+is no two-table index model to join and nothing to cross-check against.
+
+Each row comes back as `{ name, columns, type, rawColumns }`. `columns` is the view's
+bracketed `column_names` cell (`"[phone]"`, `"[a,b]"`) **parsed** into a list - never
+substring-matched, because `"[owner_id]"` contains `"owner"`. `type` is `access_method`.
+
+**Uniqueness is not readable.** `v_db_index` has no uniqueness field, so a unique index
+and an ordinary one are indistinguishable in it: `unique` is left **absent** rather than
+guessed, and `uniqueness-enforced` is reported in `unverified` on every result. Only a
+duplicate-insert test proves enforcement. An empty result more likely means the table name
+is wrong than that the table is unindexed - every physical table has a `PRIMARY`.
+
+### Create an index (composite and non-unique included)
+
+> **A DATABASE INDEX IS A PHYSICAL, PER-INSTANCE CHANGE. IT IS NOT CAPTURED IN AN UPDATE
+> SET AND DOES NOT TRAVEL WITH A PROMOTION.** Re-run `index-create` against every
+> environment that needs the index (dev, test, uat, staging, prod). There is deliberately
+> no `--update-set` - passing one is an error, not a silent no-op.
+
+```bash
+# Dry-run (the DEFAULT) - sends nothing and reads nothing
+npx dove-sn index-create --table x_cadso_journey_instance --columns state,created_on
+
+# Send it
+npx dove-sn index-create \
+  --table x_cadso_journey_instance --columns state,created_on --confirm --json
+```
+
+This is what `add-index` cannot do. `sys_dictionary.unique` - the only record-shaped lever
+- is **per-column and unique-only**, so composite and plain indexes have no record path at
+all. `index-create` instead replays the platform's own index-creator form
+(`sys_action=create_index`, `sysparm_index_table`, `sysparm_fields`,
+`sysparm_unique_index_SKIP`) over a form-login session. That contract is lifted from the
+instance's shipped `index_creator_information` UI macro, not from a guess, and the POST
+target is taken from the rendered page's own `<form action>`.
+
+- **Dry-run by default.** Without `--confirm` nothing is sent *and nothing is read*;
+  `--dry-run` forces a plan even with `--confirm`.
+- **Idempotent.** On the live path `v_db_index` is read first, and an index over *exactly*
+  these columns short-circuits to `already-exists` with no form session and no write.
+  Column **order** is part of an index's identity - `[a,b]` is not `[b,a]`.
+- **`--name` is refused.** The platform's form has no name input; ServiceNow names the
+  index itself. Reporting a name the instance does not carry would be a lie, so the
+  created index's *real* name is returned in `name` instead.
+- **The read-back is the proof.** After the POST the index is polled for in `v_db_index`
+  (default 10 checks, 3 s apart - a build on a populated table is asynchronous). If it
+  never appears the status is `failed`: a form processor returning a page is not evidence
+  an ALTER ran, and a unique index cannot build over duplicate values (EMPTY counts).
+- **Uniqueness is still never claimed.** `uniqueness-enforced` stays in `unverified` on
+  every status.
+
+**Requires a username+password identity that can form-log-in.** An instance on
+API-key-only auth, SSO or MFA rejects the form login however valid the API key is; the
+verb fails at the session with that diagnosis rather than a mystery 302, and no `.do`
+replay (including `create-table`'s) can work in that state.
+
+Exit codes: `0` created / already-exists / dry-run, `1` bad args, `2` failed.
+
 ### Set a field on a record
 
 Set scalar field value(s) on an **existing** data record, capture the change into
@@ -954,7 +1021,12 @@ Claude Code and agents: `create_view`, `set_list_layout`, `set_form_layout`,
 `set_related_lists`, `add_choices_to_field`, the schema verbs `create_table` /
 `add_column` / `add_index` (a single-column unique index via `sys_dictionary.unique`,
 read back from the `v_db_index` view - uniqueness enforcement is always reported
-unverified), the record-write verbs `set_field` (update scalar fields on an
+unverified) / `index_list` (read-only: a table's database indexes from `v_db_index`,
+the only index read surface - `sys_index` is API-level-ACL 403 and `sys_index_column`
+does not exist) / `index_create` (create an index, composite and non-unique included, by
+replaying the platform index-creator form; dry-run by default, idempotent, read back from
+`v_db_index` - and **not** captured in an update set, because a database index is a
+physical per-instance change), the record-write verbs `set_field` (update scalar fields on an
 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

package/dist/cli.js

@@ -1300,6 +1300,25 @@ function printHelp() {
         "                     is treated exactly like a proven collision. Success is\n" +
         "                     read back from v_db_index; that view has no uniqueness field, so\n" +
         "                     ENFORCEMENT is always reported unverified.\n" +
+        "  index-list         List a table's DATABASE INDEXES from the v_db_index view (read-only)\n" +
+        "                     (--table <name> [--json])\n" +
+        "                     sys_index is API-level-ACL 403 and sys_index_column does not\n" +
+        "                     exist, so v_db_index is the only index read surface. It has no\n" +
+        "                     uniqueness field, so WHICH indexes are unique is always\n" +
+        "                     reported unverified.\n" +
+        "  index-create       Create a DATABASE INDEX (composite and non-unique included) by\n" +
+        "                     replaying the platform index-creator form, then read it back\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is sent or read without --confirm\n" +
+        "                     (--table <name> --columns <a[,b,...]> [--unique]\n" +
+        "                      [--access-method <m>] [--confirm] [--dry-run]\n" +
+        "                      [--poll-attempts <n>] [--poll-interval-ms <n>] [--debug] [--json])\n" +
+        "                     A DATABASE INDEX IS PHYSICAL AND PER-INSTANCE: it is NOT captured\n" +
+        "                     in an update set and does NOT travel with a promotion — re-run it\n" +
+        "                     against every environment. There is no --update-set for that\n" +
+        "                     reason. Idempotent: an index over exactly those columns already\n" +
+        "                     present returns already-exists with no write. --name is REFUSED —\n" +
+        "                     the platform's form has no name input; the real name is returned.\n" +
+        "                     Needs a username+password identity that can form-log-in.\n" +
         "  set-column         Update an EXISTING column's SCHEMA (label/mandatory/default/read-only/max-length),\n" +
         "                     into an update set, then verify against the instance\n" +
         "                     (--table <t> --column <c> --update-set <sys_id>\n" +
@@ -1662,6 +1681,130 @@ async function runAddIndex(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn index-list:
+ *   --table x_cadso_automate_message_batch_recipient [--json]
+ *
+ * Read-only. Lists the table's database indexes from the v_db_index view — the only
+ * index read surface an instance exposes (sys_index is API-level-ACL 403,
+ * sys_index_column does not exist).
+ *
+ * Exit codes: 0 read, 1 bad args.
+ */
+async function runIndexList(flags) {
+    if (!flags.table) {
+        process.stderr.write("index-list: --table <name> is required\n");
+        return 1;
+    }
+    var result = await (0, table_1.listIndexes)({
+        client: (0, client_1.createClient)({}),
+        table: flags.table,
+    });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write(result.table + " — " + result.indexes.length + " index(es)\n");
+    for (var i = 0; i < result.indexes.length; i += 1) {
+        var idx = result.indexes[i];
+        process.stdout.write("  " +
+            (idx.name || "(unnamed)") +
+            "  [" +
+            idx.columns.join(", ") +
+            "]  " +
+            (idx.type || "(no access_method)") +
+            "\n");
+    }
+    process.stdout.write(result.note + "\nUNVERIFIED: " + result.unverified.join(", ") + "\n");
+    return 0;
+}
+/**
+ * dove-sn index-create:
+ *   --table x_cadso_core_u_smoke --columns a,b [--unique] [--access-method <m>]
+ *   [--confirm] [--dry-run] [--poll-attempts <n>] [--poll-interval-ms <n>]
+ *   [--debug] [--json]
+ *
+ * DRY-RUN BY DEFAULT — nothing is sent (and nothing is even READ) without --confirm;
+ * --dry-run forces a plan even with it. There is deliberately NO --update-set: a
+ * database index is physical and is not captured in one.
+ *
+ * Exit codes: 0 created / already-exists / dry-run, 1 bad args, 2 failed (which
+ * includes "the form was posted but no index was read back").
+ */
+async function runIndexCreate(flags) {
+    var columns = splitList(flags.columns || "");
+    if (!flags.table || columns.length === 0) {
+        process.stderr.write("index-create: --table <name> and --columns <a[,b,...]> are required\n");
+        return 1;
+    }
+    if (flags["update-set"]) {
+        process.stderr.write("index-create: --update-set is not accepted. A database index is a PHYSICAL, " +
+            "PER-INSTANCE change — it is NOT captured in an update set and does not " +
+            "travel with a promotion. Run index-create against each environment.\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        table: flags.table,
+        columns: columns,
+        unique: flags.unique === "true",
+        confirm: flags.confirm === "true",
+        dryRun: flags["dry-run"] === "true",
+    };
+    if (flags.name !== undefined)
+        params.name = flags.name;
+    if (flags["access-method"])
+        params.accessMethod = flags["access-method"];
+    if (flags["form-path"])
+        params.formPath = flags["form-path"];
+    if (flags.debug === "true")
+        params.debug = true;
+    // A non-integer poll setting would make the bounded wait unbounded (or zero).
+    // Reject it here with a named message instead of letting NaN reach the loop.
+    var numeric = [
+        ["poll-attempts", "pollAttempts"],
+        ["poll-interval-ms", "pollIntervalMs"],
+    ];
+    for (var n = 0; n < numeric.length; n += 1) {
+        var raw = flags[numeric[n][0]];
+        if (raw === undefined)
+            continue;
+        var value = Number(raw);
+        if (!Number.isInteger(value) || value <= 0) {
+            process.stderr.write("index-create: --" +
+                numeric[n][0] +
+                " must be a positive integer (got '" +
+                raw +
+                "')\n");
+            return 1;
+        }
+        params[numeric[n][1]] = value;
+    }
+    var result = await (0, table_1.createIndex)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write("[" +
+            result.status +
+            "] " +
+            result.table +
+            " [" +
+            result.columns.join(", ") +
+            "]" +
+            (result.name ? " -> " + result.name : "") +
+            (result.instance ? " on " + result.instance : "") +
+            (result.verified ? " — verified" : "") +
+            "\n" +
+            result.note +
+            "\nUNVERIFIED: " +
+            result.unverified.join(", ") +
+            "\n");
+    }
+    if (result.status === "failed")
+        return 2;
+    return 0;
+}
 /** Parse a CLI boolean flag. Bare `--mandatory` means true; `--mandatory false` means
  *  false. Anything else is rejected rather than quietly coerced to `true`. */
 function parseBoolFlag(name, raw, verb = "set-column") {
@@ -2544,6 +2687,12 @@ async function main() {
     if (parsed.command === "add-index") {
         return await runAddIndex(parsed.flags);
     }
+    if (parsed.command === "index-list") {
+        return await runIndexList(parsed.flags);
+    }
+    if (parsed.command === "index-create") {
+        return await runIndexCreate(parsed.flags);
+    }
     if (parsed.command === "set-column") {
         return await runSetColumn(parsed.flags, parsed.bare);
     }

package/dist/flowDesigner/cloneActionType.d.ts

@@ -14,6 +14,21 @@
  *        ├─ sys_hub_step_ext_input   (model_id → step)
  *        └─ sys_hub_step_ext_output  (model_id → step)
  *
+ * Plus two stores the action's IO depends on that are NOT FK children
+ * (verified live on tenonworkstudio 2026-09-30):
+ *
+ *   sys_element_mapping   output → step-output wiring, one row per mapped output
+ *                         (incl. __action_status__ / __dont_treat_as_error__):
+ *                         id = action sys_id, table = var__m_sys_hub_action_output_<action>,
+ *                         field = output element, value = the pill. Without these a
+ *                         clone publishes with every output unmapped (runs, returns empty).
+ *   sys_documentation     IO labels: name = var__m_sys_hub_action_{input,output}_<action>,
+ *                         element, label, language. Without these Flow Designer shows the
+ *                         element name as the label.
+ *
+ * Action IO rows are var_dictionary rows whose `name` IS their var__m table, so
+ * the clone retargets `name` onto the new action's var__m table too.
+ *
  * Publish reuses the proven snapshot path (publishActionType): the SOURCE
  * action's step graph is read from /step_instances, each step's `action` and
  * `sys_id` are remapped onto the clone (old→new sys_id map), optional StepOps
@@ -77,6 +92,12 @@ export interface CloneActionTypePlan {
     sourceScopeSysId: string;
     /** Old → new sys_id for every cloned step instance. */
     stepIdMap: Record<string, string>;
+    /**
+     * The sys_documentation (label) ops inside `ops`. They are UPSERTED after the
+     * graph is written (the dictionary insert may already have created the row),
+     * not run through executeWritePlan.
+     */
+    labelOpIds: Array<string>;
 }
 export interface CloneActionTypeStepReport {
     /** Step summary of the cloned graph before stepOps. */
@@ -99,6 +120,10 @@ export interface CloneActionTypeResult {
     verify?: VerifyStepsResult;
     steps?: CloneActionTypeStepReport;
 }
+/** var_dictionary table name for a model's variables: var__m_<table>_<model sys_id>. */
+export declare function varTableName(table: string, modelSysId: string): string;
+/** The encoded query for an action's output → step-output mappings. */
+export declare function outputMappingQuery(actionSysId: string): string;
 /** Slug for internal_name: lowercase, runs of non-alphanumerics → "_", trimmed of "_". */
 export declare function slugInternalName(name: string): string;
 /**
@@ -117,3 +142,18 @@ export declare function resolveScope(client: ServiceNowClient, ref: string): Pro
  */
 export declare function remapClonedSteps(steps: Array<StepRecord>, newParentSysId: string, stepIdMap: Record<string, string>, idMap: Record<string, string>): Array<StepRecord>;
 export declare function cloneActionType(opts: CloneActionTypeParams): Promise<CloneActionTypeResult>;
+/**
+ * Set `name` on a cloned var_dictionary row (action IO / step ext IO) to the
+ * clone's var__m table — but only when it named the SOURCE model's var__m table
+ * exactly; anything else is left as it was.
+ */
+export declare function retargetVarName(fields: Record<string, unknown>, table: string, oldModelSysId: string, newModelSysId: string): void;
+/**
+ * Compare the source action's output mappings with the clone's, by `field`.
+ * A source field absent on the clone fails; a differing value is noted but does
+ * not fail (publish may legitimately normalise a pill).
+ */
+export declare function verifyOutputMappings(sourceRows: Array<Record<string, unknown>>, cloneRows: Array<Record<string, unknown>>): {
+    ok: boolean;
+    notes: Array<string>;
+};

package/dist/flowDesigner/cloneActionType.js

@@ -15,6 +15,21 @@
  *        ├─ sys_hub_step_ext_input   (model_id → step)
  *        └─ sys_hub_step_ext_output  (model_id → step)
  *
+ * Plus two stores the action's IO depends on that are NOT FK children
+ * (verified live on tenonworkstudio 2026-09-30):
+ *
+ *   sys_element_mapping   output → step-output wiring, one row per mapped output
+ *                         (incl. __action_status__ / __dont_treat_as_error__):
+ *                         id = action sys_id, table = var__m_sys_hub_action_output_<action>,
+ *                         field = output element, value = the pill. Without these a
+ *                         clone publishes with every output unmapped (runs, returns empty).
+ *   sys_documentation     IO labels: name = var__m_sys_hub_action_{input,output}_<action>,
+ *                         element, label, language. Without these Flow Designer shows the
+ *                         element name as the label.
+ *
+ * Action IO rows are var_dictionary rows whose `name` IS their var__m table, so
+ * the clone retargets `name` onto the new action's var__m table too.
+ *
  * Publish reuses the proven snapshot path (publishActionType): the SOURCE
  * action's step graph is read from /step_instances, each step's `action` and
  * `sys_id` are remapped onto the clone (old→new sys_id map), optional StepOps
@@ -32,10 +47,14 @@
  * docs/servicenow-flow-designer-headless-authoring.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.varTableName = varTableName;
+exports.outputMappingQuery = outputMappingQuery;
 exports.slugInternalName = slugInternalName;
 exports.resolveScope = resolveScope;
 exports.remapClonedSteps = remapClonedSteps;
 exports.cloneActionType = cloneActionType;
+exports.retargetVarName = retargetVarName;
+exports.verifyOutputMappings = verifyOutputMappings;
 const shape_1 = require("./shape");
 const writeOrder_1 = require("./writeOrder");
 const actionTypeApi_1 = require("./actionTypeApi");
@@ -47,6 +66,16 @@ var OUTPUT_TABLE = "sys_hub_action_output";
 var STEP_TABLE = "sys_hub_step_instance";
 var EXT_INPUT_TABLE = "sys_hub_step_ext_input";
 var EXT_OUTPUT_TABLE = "sys_hub_step_ext_output";
+var MAPPING_TABLE = "sys_element_mapping";
+var LABEL_TABLE = "sys_documentation";
+/** var_dictionary table name for a model's variables: var__m_<table>_<model sys_id>. */
+function varTableName(table, modelSysId) {
+    return "var__m_" + table + "_" + modelSysId;
+}
+/** The encoded query for an action's output → step-output mappings. */
+function outputMappingQuery(actionSysId) {
+    return "id=" + actionSysId + "^tableSTARTSWITH" + "var__m_" + OUTPUT_TABLE + "_";
+}
 /** Rows per child query. A full page means the read may be truncated — refuse rather than half-clone. */
 var CHILD_LIMIT = 1000;
 /**
@@ -307,6 +336,10 @@ async function cloneActionType(opts) {
             scope: scope.name,
         },
     ];
+    // element → plan op id, per IO table, so label/mapping ops can depend on their row.
+    var ioOpByElement = {};
+    ioOpByElement[INPUT_TABLE] = {};
+    ioOpByElement[OUTPUT_TABLE] = {};
     var pushModelChildren = function (table, prefix, rows) {
         for (var r = 0; r < rows.length; r++) {
             var src = flattenRow(rows[r]);
@@ -314,6 +347,11 @@ async function cloneActionType(opts) {
             idMap[String(src.sys_id || "")] = childSysId;
             var fields = cloneFields(src, scope.sysId, childSysId);
             fields.model_id = newParentSysId;
+            retargetVarName(fields, table, opts.sourceSysId, newParentSysId);
+            var element = String(src.element || "");
+            if (element) {
+                ioOpByElement[table][element] = prefix + ":" + r;
+            }
             ops.push({
                 id: prefix + ":" + r,
                 logicalName: table + ":" + String(src.element || src.name || src.sys_id),
@@ -356,6 +394,7 @@ async function cloneActionType(opts) {
                 idMap[String(srcExt.sys_id || "")] = newExtSysId;
                 var extFields = cloneFields(srcExt, scope.sysId, newExtSysId);
                 extFields.model_id = newStepSysId;
+                retargetVarName(extFields, extSpecs[x].table, oldStepSysId, newStepSysId);
                 ops.push({
                     id: stepOpId + ":" + extSpecs[x].prefix + ":" + e,
                     logicalName: extSpecs[x].table + ":" + String(srcExt.element || srcExt.name || srcExt.sys_id),
@@ -367,13 +406,78 @@ async function cloneActionType(opts) {
             }
         }
     }
+    // 3b. Output → step-output wiring (sys_element_mapping). Step cids survive the
+    // clone, so field and value (the pill) carry over unchanged.
+    var newOutputVarTable = varTableName(OUTPUT_TABLE, newParentSysId);
+    var sourceMappings = await queryChildren(client, MAPPING_TABLE, outputMappingQuery(opts.sourceSysId));
+    for (var mi = 0; mi < sourceMappings.length; mi++) {
+        var srcMap = flattenRow(sourceMappings[mi]);
+        var mapField = String(srcMap.field || "");
+        var mapFields = cloneFields(srcMap, scope.sysId, (0, shape_1.generateSysId)());
+        mapFields.id = newParentSysId;
+        mapFields.table = newOutputVarTable;
+        // After the parent and its outputs (the matching output first), so a mapping never precedes the row it wires.
+        var mapDeps = ["parent"];
+        if (mapField && Object.prototype.hasOwnProperty.call(ioOpByElement[OUTPUT_TABLE], mapField)) {
+            mapDeps.push(ioOpByElement[OUTPUT_TABLE][mapField]);
+        }
+        var outputOpIds = Object.keys(ioOpByElement[OUTPUT_TABLE]).map(function (el) { return ioOpByElement[OUTPUT_TABLE][el]; });
+        for (var oi = 0; oi < outputOpIds.length; oi++) {
+            if (mapDeps.indexOf(outputOpIds[oi]) === -1) {
+                mapDeps.push(outputOpIds[oi]);
+            }
+        }
+        ops.push({
+            id: "mapping:" + mi,
+            logicalName: MAPPING_TABLE + ":" + (mapField || String(srcMap.sys_id || mi)),
+            table: MAPPING_TABLE,
+            fields: mapFields,
+            dependsOn: mapDeps,
+            scope: scope.name,
+        });
+    }
+    // 3c. IO labels (sys_documentation keyed on the var__m table), retargeted.
+    var labelOps = [];
+    var labelSpecs = [
+        { table: INPUT_TABLE, prefix: "label:input" },
+        { table: OUTPUT_TABLE, prefix: "label:output" },
+    ];
+    for (var li = 0; li < labelSpecs.length; li++) {
+        var spec = labelSpecs[li];
+        var srcVarTable = varTableName(spec.table, opts.sourceSysId);
+        var newVarTable = varTableName(spec.table, newParentSysId);
+        var labelRows = await queryChildren(client, LABEL_TABLE, "name=" + srcVarTable);
+        for (var lr = 0; lr < labelRows.length; lr++) {
+            var srcLabel = flattenRow(labelRows[lr]);
+            var labelElement = String(srcLabel.element || "");
+            if (!labelElement) {
+                continue;
+            }
+            var labelFields = cloneFields(srcLabel, scope.sysId, (0, shape_1.generateSysId)());
+            labelFields.name = newVarTable;
+            var labelDeps = ["parent"];
+            if (Object.prototype.hasOwnProperty.call(ioOpByElement[spec.table], labelElement)) {
+                labelDeps.push(ioOpByElement[spec.table][labelElement]);
+            }
+            labelOps.push({
+                id: spec.prefix + ":" + lr,
+                logicalName: LABEL_TABLE + ":" + newVarTable + "." + labelElement,
+                table: LABEL_TABLE,
+                fields: labelFields,
+                dependsOn: labelDeps,
+                scope: scope.name,
+            });
+        }
+    }
+    var allOps = ops.concat(labelOps);
     var plan = {
-        ops: ops,
-        counts: countByTable(ops),
-        total: ops.length,
+        ops: allOps,
+        counts: countByTable(allOps),
+        total: allOps.length,
         scope: scope,
         sourceScopeSysId: sourceScopeSysId,
         stepIdMap: stepIdMap,
+        labelOpIds: labelOps.map(function (o) { return o.id; }),
     };
     // 4. The publishable step graph: the SOURCE's /step_instances, remapped.
     var sourceSteps = await (0, actionTypeApi_1.fetchActionSteps)(client, opts.sourceSysId, sourceScopeSysId);
@@ -412,6 +516,11 @@ async function cloneActionType(opts) {
     // 5. Write the graph, pinned to the update set.
     var updateSetSysId = opts.updateSetSysId;
     var written = await (0, writeOrder_1.executeWritePlan)(client, ops, updateSetSysId);
+    // Labels last: the IO dictionary inserts above may already have created a
+    // sys_documentation row for the new var__m table, so upsert rather than duplicate.
+    for (var lw = 0; lw < labelOps.length; lw++) {
+        written.push(await upsertLabel(client, labelOps[lw], updateSetSysId));
+    }
     var result = {
         sysId: newParentSysId,
         internalName: internalName,
@@ -440,16 +549,129 @@ async function cloneActionType(opts) {
     }
     // 7. Verify — a 201 means "compiled", not "landed as sent". Read the clone's steps back.
     var fresh = await (0, actionTypeApi_1.fetchActionSteps)(client, newParentSysId, scope.sysId);
+    var verify;
     if (fresh.length === 0) {
-        result.verify = { ok: false, notes: ["read-back returned no steps — could not verify the publish"] };
+        verify = { ok: false, notes: ["read-back returned no steps — could not verify the publish"] };
     }
     else {
         var expected = stepReport.after;
-        result.verify = (0, stepOps_1.verifySteps)(expected, (0, stepOps_1.summarizeSteps)(fresh), allCids(finalSteps));
+        verify = (0, stepOps_1.verifySteps)(expected, (0, stepOps_1.summarizeSteps)(fresh), allCids(finalSteps));
         if (fresh.length !== finalSteps.length) {
-            result.verify.ok = false;
-            result.verify.notes.push("step count on the instance is " + fresh.length + ", expected " + finalSteps.length);
+            verify.ok = false;
+            verify.notes.push("step count on the instance is " + fresh.length + ", expected " + finalSteps.length);
         }
     }
+    // Output mappings: every source mapping must exist on the clone, or its outputs come back empty.
+    var cloneMappings = await queryChildren(client, MAPPING_TABLE, outputMappingQuery(newParentSysId));
+    var mappingCheck = verifyOutputMappings(sourceMappings, cloneMappings);
+    if (!mappingCheck.ok) {
+        verify.ok = false;
+    }
+    for (var vn = 0; vn < mappingCheck.notes.length; vn++) {
+        verify.notes.push(mappingCheck.notes[vn]);
+    }
+    result.verify = verify;
     return result;
 }
+/**
+ * Set `name` on a cloned var_dictionary row (action IO / step ext IO) to the
+ * clone's var__m table — but only when it named the SOURCE model's var__m table
+ * exactly; anything else is left as it was.
+ */
+function retargetVarName(fields, table, oldModelSysId, newModelSysId) {
+    if (!Object.prototype.hasOwnProperty.call(fields, "name")) {
+        return;
+    }
+    if (String(fields.name) === varTableName(table, oldModelSysId)) {
+        fields.name = varTableName(table, newModelSysId);
+    }
+}
+/**
+ * Compare the source action's output mappings with the clone's, by `field`.
+ * A source field absent on the clone fails; a differing value is noted but does
+ * not fail (publish may legitimately normalise a pill).
+ */
+function verifyOutputMappings(sourceRows, cloneRows) {
+    var cloneByField = {};
+    for (var c = 0; c < cloneRows.length; c++) {
+        var cr = flattenRow(cloneRows[c]);
+        var cf = String(cr.field || "");
+        if (cf) {
+            cloneByField[cf] = String(cr.value === undefined || cr.value === null ? "" : cr.value);
+        }
+    }
+    var missing = [];
+    var notes = [];
+    for (var s = 0; s < sourceRows.length; s++) {
+        var sr = flattenRow(sourceRows[s]);
+        var sf = String(sr.field || "");
+        if (!sf) {
+            continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(cloneByField, sf)) {
+            missing.push(sf);
+            continue;
+        }
+        var sv = String(sr.value === undefined || sr.value === null ? "" : sr.value);
+        if (cloneByField[sf] !== sv) {
+            notes.push("output mapping '" + sf + "' differs on the clone: '" + cloneByField[sf] + "' (source '" + sv + "')");
+        }
+    }
+    if (missing.length > 0) {
+        notes.unshift(missing.length + " output mapping(s) missing on the clone (" + MAPPING_TABLE + "): " + missing.join(", "));
+    }
+    else if (sourceRows.length > 0) {
+        notes.unshift("all " + sourceRows.length + " output mapping(s) present on the clone");
+    }
+    return { ok: missing.length === 0, notes: notes };
+}
+/**
+ * Write one cloned sys_documentation row: update the existing (name, element,
+ * language) row on the target if the platform already made one, else create it.
+ */
+async function upsertLabel(client, op, updateSetSysId) {
+    var f = op.fields;
+    var keyParts = [String(f.name), String(f.element || ""), String(f.language || "")];
+    for (var k = 0; k < keyParts.length; k++) {
+        if (/[\^\r\n]/.test(keyParts[k])) {
+            throw new Error("cloneActionType: label key " + JSON.stringify(keyParts[k]) + " contains '^' or a line break.");
+        }
+    }
+    var query = "name=" + keyParts[0] + "^element=" + keyParts[1];
+    if (keyParts[2] !== "") {
+        query += "^language=" + keyParts[2];
+    }
+    try {
+        var hits = await client.table.query(LABEL_TABLE, query, { limit: 1, fields: ["sys_id"] });
+        var existingSysId = hits.length > 0 ? String(flattenRow(hits[0]).sys_id || "") : "";
+        if (RX_SYS_ID.test(existingSysId)) {
+            var update = Object.assign({}, f);
+            delete update.sys_id;
+            await client.claude.pushWithUpdateSet({
+                update_set_sys_id: updateSetSysId,
+                table: LABEL_TABLE,
+                record_sys_id: existingSysId,
+                fields: update,
+            });
+            return { id: op.id, logicalName: op.logicalName, table: op.table, sysId: existingSysId, action: "updated" };
+        }
+        var created = await client.claude.createRecord({
+            table: op.table,
+            fields: f,
+            scope: op.scope,
+            update_set_sys_id: updateSetSysId,
+            sys_id: String(f.sys_id),
+        });
+        return {
+            id: op.id,
+            logicalName: op.logicalName,
+            table: op.table,
+            sysId: created.sys_id ? String(created.sys_id) : String(f.sys_id),
+            action: "created",
+        };
+    }
+    catch (err) {
+        var msg = err instanceof Error ? err.message : String(err);
+        throw new Error("cloneActionType: label write failed at op '" + op.id + "' (" + op.table + "): " + msg);
+    }
+}

package/dist/flowDesigner/writeOrder.d.ts

@@ -36,8 +36,12 @@ export interface WriteOpResult {
     logicalName: string;
     table: string;
     sysId: string;
-    /** Currently always "created" — claude.createRecord doesn't distinguish. */
-    action: "created";
+    /**
+     * executeWritePlan always reports "created" — claude.createRecord doesn't
+     * distinguish. "updated" is reported by callers that upsert (cloneActionType's
+     * label rows, which the platform may already have created on the dictionary insert).
+     */
+    action: "created" | "updated";
 }
 export declare class WriteOrderError extends Error {
     readonly cycleIds?: Array<string> | undefined;

package/dist/index.d.ts

@@ -21,8 +21,8 @@ export { sincPlugin } from "./plugin";
 export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, resolveScope, slugInternalName, fetchActionSteps, findStepInput, triggerPublication, publishActionType, editActionType, defineActionType, planActionDefinition, validateDefineSpec, applyStepOps, verifySteps, summarizeSteps, formatStepPill, readFlow, readActionType, publishFlow, copyFlow, createFlow, buildPublishModel, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError, } from "./flowDesigner";
 export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, CloneActionTypePlan, CloneActionTypeStepReport, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, EditActionTypeParams, EditActionTypeResult, EditActionTypeOps, DefineActionSpec, DefineActionInputSpec, DefineActionOutputSpec, DefineStepSpec, DefineStepVarSpec, DefineStepOutputSpec, DefineStepValue, DefineActionTypeParams, DefineActionTypeResult, DefineActionDiff, DefineActionPlan, PlanActionDefinitionParams, ActionView, StepView, StepOps, StepRecord, StepSummary, StepIoSummary, PatchStepScriptOp, SetStepInputOp, AddStepOutputOp, AddStepInputOp, ApplyStepOpsResult, VerifyStepsResult, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, CreateFlowParams, CreateFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult, } from "./flowDesigner";
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, RemoveChoicesParams, RemoveChoicesResult, ChoiceRemovalResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams, ChunkRole, ChunkInfo, ChunkResult, PrunedResult, HostAssetsParams, HostAssetsResult, } from "./types";
-export { createTable, projectTableGraph, buildColumnXml, normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, TYPE_MAP, DEFAULT_SUPER_CLASS, DEFAULT_SAVE_ACTION, addColumn, deriveElement, addIndex, parseIndexColumns, indexMatchesColumns, setColumn, resolveAttributes, toStoredValue, setTable, resolveTableAttributes, } from "./table";
-export type { CreateTableParams, CreateTableResult, AddColumnParams, AddColumnResult, AddIndexParams, AddIndexResult, AddIndexVerification, SetColumnParams, SetColumnResult, ColumnAttributes, AttributeChange, SetTableParams, SetTableResult, TableAttributes, TableGraph, NormalizedColumn, ColumnSpec, AccessFlags, OverlaySpec, } from "./table";
+export { createTable, projectTableGraph, buildColumnXml, normalizeColumns, resolveType, applyTableSaveOverlay, defaultAccessFlags, TYPE_MAP, DEFAULT_SUPER_CLASS, DEFAULT_SAVE_ACTION, addColumn, deriveElement, addIndex, parseIndexColumns, indexMatchesColumns, listIndexes, createIndex, validateCreateIndex, DEFAULT_INDEX_FORM_PATH, NOT_IN_UPDATE_SET, setColumn, resolveAttributes, toStoredValue, setTable, resolveTableAttributes, } from "./table";
+export type { CreateTableParams, CreateTableResult, AddColumnParams, AddColumnResult, AddIndexParams, AddIndexResult, AddIndexVerification, ListIndexesParams, ListIndexesResult, TableIndex, CreateIndexParams, CreateIndexResult, SetColumnParams, SetColumnResult, ColumnAttributes, AttributeChange, SetTableParams, SetTableResult, TableAttributes, TableGraph, NormalizedColumn, ColumnSpec, AccessFlags, OverlaySpec, } from "./table";
 export { setField } from "./setField";
 export { createRecord } from "./createRecord";
 export type { RecordWriteResult, SetFieldParams, SetFieldResult, } from "./setField";