@tenonhq/dovetail-servicenow 0.0.50 → 0.0.52

package/README.md

@@ -736,60 +736,102 @@ admin, and `sys_index_column` does not exist at all (HTTP 400 `Invalid table`),
 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
+bracketed `column_names` cell (`"[phone]"`, `"[a;b]"` - semicolon-separated when composite) **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`.
+duplicate-insert test proves enforcement. An empty result for a table that does not exist
+means the table name is wrong - every physical table has a `PRIMARY`.
+
+**Table-per-hierarchy children list their storage root's indexes.** `v_db_index` lists
+indexes by *physical* table, and a table stored in an ancestor's physical table (anything
+extending `task`, for example) has no rows under its own name. When the table exists but
+has no rows, its `super_class` chain is walked to the first ancestor that has them, and
+that root's indexes are listed - with `storageTable` and the note naming the root.
+`index-create` and `add-index` **refuse** such a child on the live path, naming the root,
+rather than build on it or report a false "NOT created".
 
 ### 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.
+> **An index IS captured in an update set.** The platform's build job writes a
+> `sys_update_xml` row (`type=Indexes`, name `sys_index_<table>_<col>_<col>…`) into the
+> session user's **current** update set - the Database Indexes dialog says so itself, and
+> it was read back live on tenonworkstudio 2026-10-08. `--update-set` is therefore
+> **required** on the live path: the verb pins that set as current first and reads the
+> capture row back from it afterwards. The physical index is still built per instance;
+> committing the set elsewhere rebuilds it there.
 
 ```bash
-# Dry-run (the DEFAULT) - sends nothing and reads nothing
+# Dry-run (the DEFAULT) - sends nothing and reads nothing; no update set needed
 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
+  --table x_cadso_journey_instance --columns state,created_on \
+  --update-set <sys_id> --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>`.
+all (`sys_index` is API-level-ACL 403, `sys_index_column` does not exist). `index-create`
+instead replays the two GlideAjax calls the platform's own Database Indexes dialog makes
+on `xmlhttp.do` over a form-login session - taken from a HAR of the Studio dialog plus the
+`dialog_index_create` UI page's client script, both read live:
+
+1. `IndexCreatorErrorChecker` / `canCreate` - the dialog's pre-flight (`sysparm_table_name`,
+   `sysparm_field_names`, `sysparm_unique`, `sysparm_access_method`). A `canCreate:false`
+   verdict is returned verbatim with its `errorCode` and nothing is scheduled.
+2. `ScheduleCreator` / `createSchedule` - schedules the build (`sysparm_table`,
+   `sysparm_fields`, `sysparm_access_method` - default `btree`, exactly as the dialog's
+   client JS does - `sysparm_unique` `true|false`, empty `sysparm_email` = no
+   notification, empty `sysparm_schedule_name`).
+
+(The `index_creator_dialog` page's `sys_action=create_index` form is inert - the browser
+never submits it, and the UI page has no processing script. The earlier form-POST replay
+was a silent no-op for that reason.)
 
 - **Dry-run by default.** Without `--confirm` nothing is sent *and nothing is read*;
   `--dry-run` forces a plan even with `--confirm`.
+- **Target checks before anything else.** The table must exist; the update set must exist,
+  be `in progress`, and belong to the table's application scope - a set in another scope
+  is refused, because the capture row would land in the wrong scope.
 - **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).
+  these columns short-circuits to `already-exists` with no pin, no form session and no
+  write. Column **order** is part of an index's identity - `[a;b]` is not `[b;a]`.
+- **Table-per-hierarchy children are refused.** A table with no `v_db_index` rows of its
+  own whose ancestor has them is stored in that ancestor's physical table; the run stops
+  before any write and names the root (run against the root if that is what you want).
+- **Identity check (warns, never refuses).** The pin runs through the REST client (an API
+  key when one is configured) but the build is scheduled by the form session (always
+  `SN_USER`), and the build captures into the *form* user's current set. The REST caller's
+  own `sys_user` row is read first; when it is not the form-login user (or cannot be read)
+  the run still goes ahead and every result note carries an `IDENTITY WARNING`. The capture
+  read-back then reports where the row actually landed (`captured` / `captureFoundIn`).
+- **The pin is read back.** The set is pinned with Dovetail's own `changeUpdateSet` and
+  `currentUpdateSet` is read; a pin that did not take stops the run before the session
+  opens.
+- **`--name` is refused.** The dialog has no name input; ServiceNow names the index after
+  its leading column (live: `[sys_created_on;status;version_step;version]` → index
+  `sys_created_on`). The created index's *real* name is returned in `name`.
+- **The read-back is the proof.** After scheduling, the index is polled for in `v_db_index`
+  (default 10 checks, 3 s apart). If it never appears the status is `failed`: an accepted
+  schedule is not evidence an ALTER ran, and a unique index cannot build over duplicate
+  values (EMPTY counts). Then the capture row is looked for in the pinned set:
+  `captured:true` only when it was read back; an index that exists but was not captured
+  is `created:true, captured:false` with `update-set-capture` in `unverified` - and
+  exit code 2, because it will not travel. In that case the capture name is searched
+  across every set and the set(s) it actually landed in come back in `captureFoundIn`.
 - **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.
+**Requires a username+password identity that can form-log-in.** `xmlhttp.do` ignores
+Basic auth and API keys, so an API-key-only, SSO or MFA identity fails at the session with
+that diagnosis (TenonHQ/Dovetail#292).
 
-Exit codes: `0` created / already-exists / dry-run, `1` bad args, `2` failed.
+Exit codes: `0` created / already-exists / dry-run, `1` bad args, `2` failed - and `2`
+when the index was created but its capture row was not found in the pinned set.
 
 ### Set a field on a record
 
@@ -835,7 +877,8 @@ npx dove-sn create-record \
 switches the executing user's app scope + update set server-side, inserts, and
 restores both — so the record is owned by the right app and the insert is captured
 in the right update set. Like `set-field` it **refuses** schema tables and verifies
-via read-back. `--scope` and `--update-set` are required; `--if-absent
+via read-back. It also **refuses** `sys_update_set` — the op cannot set an update
+set's application, so create sets with `dove createUpdateSet` instead. `--scope` and `--update-set` are required; `--if-absent
 "<encoded-query>"` makes re-runs idempotent (the insert is skipped when the query
 already matches a row). Exit codes: `0` created / skipped-in-sync / dry-run, `1` bad
 args, `2` write landed unverified (or skipped with drift). To **update** an existing
@@ -892,14 +935,19 @@ npx dove-sn delete-record \
 `delete-record` wraps the core `deleteRecord` op. It is **dry-run by default** —
 nothing is deleted without `--apply` (`--dry-run` wins if both are given). `--sys-id`
 must be a 32-character lowercase hex id and `--table` a plain table name; both are
-validated before any network call. `--update-set` is **required** and sent with the
-delete, but **the capture is not pinned yet**: until
-[#297](https://github.com/TenonHQ/Dovetail/issues/297) ships server-side, the op ignores
-`update_set_sys_id` and captures the delete into the session's **current** update set —
-make that the set you want before `--apply`. Every result note repeats this caveat; the
-client keeps sending the field so it takes effect the moment the server honours it. Like its siblings it **refuses** schema tables (`sys_db_object` /
-`sys_dictionary`). Exit codes: `0` deleted / dry-run, `1` bad args or no such record,
-`2` the delete returned but the record is **still present** on read-back.
+validated before any network call. `--update-set` is **required**, must exist and be
+**in progress** (checked on the dry-run too). Until
+[#297](https://github.com/TenonHQ/Dovetail/issues/297) ships server-side the op ignores
+`update_set_sys_id` and captures the delete into the session's **current** update set, so
+the verb pins `--update-set` as current first (refusing, nothing deleted, if the pin does
+not read back) and then reads the DELETE row back from `sys_update_xml`. The result carries
+`captured`, `capturedInto` and `captureState` (`in-set` / `other-set` / `none` /
+`unverified`). Like its siblings it **refuses** schema tables (`sys_db_object` /
+`sys_dictionary`). A failed delete call never skips the read-back. Exit codes: `0` deleted
+and captured in the set, a table that writes no capture at all (`none`, with a note), or a
+dry-run; `1` bad args, no such record, or an unknown/closed update set; `2` the record is
+**still present** on read-back (including a server-refused delete), its state is unknown,
+the pin did not take, or the DELETE landed in a different set / could not be read back.
 
 All three verbs are exported for programmatic use:
 
@@ -917,6 +965,36 @@ var r = await setField({
 console.log(r.status, r.verified); // "applied" true
 ```
 
+### Register UI component events (sync-ux-events)
+
+UI Builder can only map an event a component dispatches when it exists as a
+`sys_ux_event` record **and** is listed in the component macroponent's
+`dispatched_events`. A component deploy does not reliably create either, so
+`sync-ux-events` reads the component's `now-ui.json` and reconciles every
+`components.<tag>.actions[]` entry against the instance.
+
+```bash
+# Dry-run (the default) — per action: ok / create / link / drift / ambiguous, plus orphans
+npx dove-sn sync-ux-events --file path/to/now-ui.json
+
+# Apply — creates the missing events and appends them to dispatched_events
+npx dove-sn sync-ux-events --file path/to/now-ui.json \
+  --component cadso-journey-builder --update-set <sys_id> --apply
+```
+
+The macroponent is the `sys_ux_macroponent` (category `component`) whose
+`root_component` is the `sys_ux_lib_component` with that tag; events are created in
+the macroponent's scope via the scope-aware `createRecord` op and the list edit goes
+through `pushWithUpdateSet`, both captured into `--update-set`. The write is
+**append-only** — existing `dispatched_events` entries are never dropped or reordered —
+and is re-read to verify. Label/description **drift** and **orphans** (linked but no
+longer declared) are reported, never changed; an event name carried by several records
+is **ambiguous** and never written. Event names and tags are charset-validated before
+they reach a query. Re-runs are no-ops. Exit codes: `0` in sync / dry-run / applied and
+verified; `1` bad args or unreadable file; `2` an unresolved or ambiguous
+component/event, or a write that did not verify. MCP: `sync_ux_events` (dry-run unless
+`confirm:true`).
+
 ### Invoke an arbitrary REST operation
 
 Invoke any authenticated ServiceNow REST operation — an application's own
@@ -1167,15 +1245,15 @@ read back from the `v_db_index` view - uniqueness enforcement is always reported
 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
+replaying the Database Indexes dialog's own processor calls; dry-run by default, idempotent,
+pinned to a required update set, read back from `v_db_index` and the capture row read back
+from `sys_update_xml`), the record-write verbs `set_field` (update scalar fields on an
 existing record), `create_record` (insert one record) and `delete_record` (delete one
 record — dry-run by default, `confirm:true` to apply, `updateSetSysId` required, the
 record read back before AND after so success is only reported once it is confirmed
 gone) — all read-back-verified; `set_field` / `create_record` are captured in the
-update set you pass, while `delete_record` captures into the session's current set
-until [#297](https://github.com/TenonHQ/Dovetail/issues/297) ships — `host_assets` (deploy a built
+update set you pass, while `delete_record` pins the set as current and reads the DELETE
+capture back (`captureState`) until [#297](https://github.com/TenonHQ/Dovetail/issues/297) ships — `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), `action_edit` (structurally edit a published action type — per-step

package/dist/cli.js

@@ -86,6 +86,7 @@ const deleteRecord_1 = require("./deleteRecord");
 const invokeRest_1 = require("./invokeRest");
 const publishApp_1 = require("./publishApp");
 const hostAssets_1 = require("./hostAssets");
+const uxEvents_1 = require("./uxEvents");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
     // `dove-sn --help` has no verb: a leading flag means an empty command and the
@@ -1572,7 +1573,14 @@ async function runIndexList(flags) {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
         return 0;
     }
-    process.stdout.write(result.table + " — " + result.indexes.length + " index(es)\n");
+    process.stdout.write(result.table +
+        " — " +
+        result.indexes.length +
+        " index(es)" +
+        (result.storageTable && result.storageTable !== result.table
+            ? " (stored in " + result.storageTable + "'s physical table — these are its indexes)"
+            : "") +
+        "\n");
     for (var i = 0; i < result.indexes.length; i += 1) {
         var idx = result.indexes[i];
         process.stdout.write("  " +
@@ -1588,16 +1596,19 @@ async function runIndexList(flags) {
 }
 /**
  * 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]
+ *   --table x_cadso_core_u_smoke --columns a,b --update-set <sys_id> [--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.
+ * --dry-run forces a plan even with it. --update-set is REQUIRED on the live path:
+ * the build job captures the index definition (sys_update_xml type=Indexes) into the
+ * user's CURRENT update set, so the verb pins that set first and reads the capture
+ * row back from it afterwards.
  *
  * 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").
+ * includes "scheduled but no index was read back") — and 2 when the index was read
+ * back but its capture row was NOT found in the pinned set.
  */
 async function runIndexCreate(flags) {
     var columns = splitList(flags.columns || "");
@@ -1605,10 +1616,12 @@ async function runIndexCreate(flags) {
         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");
+    // DRY-RUN BY DEFAULT: --confirm is what sends; --dry-run forces a plan even with it.
+    var indexDryRun = flags["dry-run"] === "true" || flags.confirm !== "true";
+    if (!indexDryRun && !flags["update-set"]) {
+        process.stderr.write("index-create: --update-set is required on the live path — the index " +
+            "definition is captured into the user's CURRENT update set, so it must be " +
+            "pinned first (only a dry-run works without one)\n");
         return 1;
     }
     var params = {
@@ -1623,8 +1636,8 @@ async function runIndexCreate(flags) {
         params.name = flags.name;
     if (flags["access-method"])
         params.accessMethod = flags["access-method"];
-    if (flags["form-path"])
-        params.formPath = flags["form-path"];
+    if (flags["update-set"])
+        params.updateSetSysId = flags["update-set"];
     if (flags.debug === "true")
         params.debug = true;
     // A non-integer poll setting would make the bounded wait unbounded (or zero).
@@ -1663,6 +1676,12 @@ async function runIndexCreate(flags) {
             (result.name ? " -> " + result.name : "") +
             (result.instance ? " on " + result.instance : "") +
             (result.verified ? " — verified" : "") +
+            (result.updateSet
+                ? " [update set " +
+                    (result.updateSet.name || result.updateSet.sysId) +
+                    (result.captured ? " — captured" : " — capture NOT verified") +
+                    "]"
+                : "") +
             "\n" +
             result.note +
             "\nUNVERIFIED: " +
@@ -1671,6 +1690,10 @@ async function runIndexCreate(flags) {
     }
     if (result.status === "failed")
         return 2;
+    // An index that exists but whose definition was not captured will not travel —
+    // surface that as a non-zero exit, the same way an unread-back index is.
+    if (result.status === "created" && !result.captured)
+        return 2;
     return 0;
 }
 /** Parse a CLI boolean flag. Bare `--mandatory` means true; `--mandatory false` means
@@ -1991,18 +2014,76 @@ async function runCreateRecord(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn sync-ux-events:
+ *   --file <path/to/now-ui.json>
+ *   [--component <tag>]
+ *   [--update-set <sys_id>]                      (required with --apply)
+ *   [--apply] [--dry-run] [--json]
+ * DRY-RUN BY DEFAULT. Exit codes: 0 in sync / dry-run / applied+verified, 1 bad args or
+ * unreadable file, 2 unresolved/ambiguous component or event, or an unverified write.
+ */
+async function runSyncUxEvents(flags, bare) {
+    var bareErr = bareStringFlagError("sync-ux-events", bare);
+    if (bareErr) {
+        process.stderr.write(bareErr);
+        return 1;
+    }
+    var file = flags.file;
+    if (!file) {
+        process.stderr.write("sync-ux-events: --file <now-ui.json> is required\n");
+        return 1;
+    }
+    var apply = flags.apply === "true" && flags["dry-run"] !== "true";
+    var nowUi;
+    try {
+        nowUi = JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
+    }
+    catch (err) {
+        process.stderr.write("sync-ux-events: cannot read " + file + ": " + (err instanceof Error ? err.message : String(err)) + "\n");
+        return 1;
+    }
+    var result;
+    try {
+        result = await (0, uxEvents_1.syncUxEvents)({
+            client: (0, client_1.createClient)({}),
+            nowUi: nowUi,
+            component: flags.component,
+            updateSetSysId: flags["update-set"],
+            apply: apply,
+        });
+    }
+    catch (err) {
+        var message = err instanceof Error ? err.message : String(err);
+        if (message.indexOf("ux-events: ") === 0)
+            message = message.slice("ux-events: ".length);
+        process.stderr.write("sync-ux-events: " + message + "\n");
+        return 1;
+    }
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write((0, uxEvents_1.formatUxEventSync)(result) + "\n");
+    }
+    return result.ok ? 0 : 2;
+}
 /**
  * dove-sn delete-record:
  *   --table x_cadso_core_metric_point_type
  *   --sys-id <32-hex sys_id>                     (the record to delete)
- *   --update-set <sys_id>                        (required — the delete is captured here, never the
- *                                                 session default; server honours it once #297 ships)
+ *   --update-set <sys_id>                        (required — must exist and be in progress; pinned as
+ *                                                 the session's current set before the delete, and the
+ *                                                 DELETE capture row is read back from sys_update_xml)
  *   [--apply]                                    (DRY-RUN BY DEFAULT — nothing is deleted without it)
  *   [--dry-run] [--json]                         (--dry-run wins over --apply)
  * Reads the record BEFORE (a missing record is an error, not a no-op delete) and AFTER
  * (success is only reported once the record is confirmed gone).
- * Exit codes: 0 deleted/dry-run, 1 bad args or missing record, 2 delete returned but the
- * record is STILL PRESENT on read-back.
+ * Exit codes: 0 deleted (and captured in the requested set) / dry-run, 1 bad args, missing
+ * record or unknown/closed update set, 2 the record is STILL PRESENT on read-back (including a
+ * delete the server refused with an error), its state is unknown, the update-set pin did not
+ * take (nothing deleted), or it was deleted but the DELETE capture landed in a different set or
+ * could not be read back. A table with no update-set capture at all exits 0 with a note.
  */
 async function runDeleteRecord(flags) {
     var table = flags.table;
@@ -2048,7 +2129,15 @@ async function runDeleteRecord(flags) {
             result.sysId +
             " → update set " +
             result.updateSetSysId +
+            (result.updateSetName ? " (" + result.updateSetName + ")" : "") +
             (result.verified ? " — verified gone" : "") +
+            (result.status === "deleted"
+                ? (result.captureState === "in-set"
+                    ? ", capture verified"
+                    : result.captureState === "none"
+                        ? ", no update-set capture (table not recorded?)"
+                        : ", NOT captured in that set")
+                : "") +
             "\n" +
             result.note +
             "\n");
@@ -2058,6 +2147,12 @@ async function runDeleteRecord(flags) {
     }
     if (result.status === "failed")
         return 2;
+    // Gone but the DELETE landed in ANOTHER set (the requested set would promote without it),
+    // or the capture could not be read back: neither may read as success to a script. A table
+    // that is not recorded in update sets at all ("none") is a plain data delete — exit 0, and
+    // the note says the delete will not travel.
+    if (result.status === "deleted" && (result.captureState === "other-set" || result.captureState === "unverified"))
+        return 2;
     return 0;
 }
 /**
@@ -2689,6 +2784,9 @@ async function dispatch(parsed) {
     if (parsed.command === "create-record") {
         return await runCreateRecord(parsed.flags);
     }
+    if (parsed.command === "sync-ux-events") {
+        return await runSyncUxEvents(parsed.flags, parsed.bare);
+    }
     if (parsed.command === "delete-record") {
         return await runDeleteRecord(parsed.flags);
     }

package/dist/cliUsage.js

@@ -332,14 +332,15 @@ exports.VERB_USAGE = {
         ],
     },
     "index-create": {
-        summary: "Create a DATABASE index (composite and non-unique included) by replaying the platform index-creator form, then read it back",
+        summary: "Create a DATABASE index (composite and non-unique included) by replaying the platform Database Indexes dialog's processor calls, pinned to an update set, then read it back",
         required: [
             { flag: "table", value: "<name>" },
             { flag: "columns", value: "<a[,b,...]>", note: "Comma-separated column elements, in index order." },
+            { flag: "update-set", value: "<sys_id>", note: "Required on the live path; the index definition is captured into it. Must be in the table's application scope." },
         ],
         optional: [
             { flag: "unique" },
-            { flag: "access-method", value: "<m>", note: "Platform access method (default: the form's default)." },
+            { flag: "access-method", value: "<m>", note: "Platform access method (default: btree, as the dialog does)." },
             CONFIRM_FLAG,
             FORCE_DRY_RUN_FLAG,
             { flag: "poll-attempts", value: "<n>", note: "Positive integer." },
@@ -349,11 +350,12 @@ exports.VERB_USAGE = {
         ],
         gate: "confirm",
         gateNote: "Nothing is sent OR read without --confirm.",
-        example: "dove-sn index-create --table x_cadso_journey_instance --columns state,created_on --confirm",
+        example: "dove-sn index-create --table x_cadso_journey_instance --columns state,created_on --update-set <sys_id> --confirm",
         notes: [
-            "A DATABASE INDEX IS PHYSICAL AND PER-INSTANCE: not captured in an update set, does not travel with a promotion — re-run it against every environment. --update-set is therefore REFUSED.",
-            "Idempotent: an index over exactly those columns returns already-exists with no write. --name is refused (the form has no name input; the real name is returned).",
-            "Needs a username+password identity that can form-log-in.",
+            "An index IS captured in an update set: the build job writes a sys_update_xml row (type=Indexes) into the user's CURRENT set, so --update-set is pinned first and the capture row is read back from it. The physical index is still built per instance; committing the set elsewhere rebuilds it.",
+            "Replays the dialog's own xmlhttp.do calls: IndexCreatorErrorChecker.canCreate (pre-flight) then ScheduleCreator.createSchedule. Idempotent: an index over exactly those columns returns already-exists with no write. --name is refused (the dialog has no name input; the real name is returned).",
+            "Needs a username+password identity that can form-log-in (xmlhttp.do ignores Basic auth / API keys).",
+            "Exit 2 when the index was scheduled but never read back from v_db_index, and when it was read back but its capture row was not found in the pinned set.",
         ],
     },
     "set-field": {
@@ -406,7 +408,7 @@ exports.VERB_USAGE = {
             {
                 flag: "update-set",
                 value: "<sys_id>",
-                note: "Sent with the delete; see the #297 note below for where the capture lands today.",
+                note: "Must exist and be in progress (checked on the dry-run too); pinned as current before the delete.",
             },
         ],
         optional: [
@@ -418,10 +420,36 @@ exports.VERB_USAGE = {
         gateNote: "The dry-run prints the record snapshot that would be deleted.",
         example: "dove-sn delete-record --table x_cadso_core_metric_point_type --sys-id <32-hex sys_id> --update-set <sys_id> --apply",
         notes: [
-            "Reads the record BEFORE (a missing record is an error, never a no-op delete) and AFTER (exit 2 if it is still present).",
-            "Until TenonHQ/Dovetail#297 ships server-side the delete op IGNORES --update-set and captures into the session's current update set — make that the set you want before --apply.",
+            "Reads the record BEFORE (a missing record is an error, never a no-op delete) and AFTER (exit 2 if it is still present — including when the server refused the delete with an error).",
+            "Until TenonHQ/Dovetail#297 ships server-side the delete op IGNORES --update-set and captures into the session's current update set — so the verb pins --update-set as current first (refusing, nothing deleted, if the pin does not read back) and reads the DELETE row back from sys_update_xml: exit 2 when it landed in a different set or the read-back failed. A table that writes no update-set capture at all exits 0 with a note (captureState \"none\") — that delete will not travel.",
         ],
     },
+    "sync-ux-events": {
+        summary: "Register a UI component's now-ui.json actions as sys_ux_event records on its macroponent",
+        required: [
+            { flag: "file", value: "<now-ui.json>", note: "Path to the component's now-ui.json; every component with `actions` is synced." },
+        ],
+        optional: [
+            { flag: "component", value: "<tag>", note: "Limit to one component tag, e.g. cadso-journey-builder." },
+            {
+                flag: "update-set",
+                value: "<sys_id>",
+                note: "Required with --apply — the event creates and the macroponent edit are captured here.",
+            },
+            { flag: "apply", note: "Write (without it the run is a dry-run)." },
+            { flag: "dry-run", note: "Force a dry-run even with --apply." },
+            JSON_FLAG,
+        ],
+        gate: "apply",
+        gateNote: "The dry-run prints each action as ok / create / link / drift / ambiguous, plus orphans.",
+        example: "dove-sn sync-ux-events --file path/to/now-ui.json --component cadso-journey-builder --update-set <sys_id> --apply",
+        notes: [
+            "Macroponent = sys_ux_macroponent whose root_component is the sys_ux_lib_component with that tag (category component). Events are created in the macroponent's scope.",
+            "Append-only: missing events are created and their sys_ids appended to dispatched_events; existing entries are never dropped or reordered. Label/description drift and orphaned (linked but undeclared) events are reported, never changed.",
+            "Exit codes: 0 in sync / dry-run / applied and verified, 1 bad args or unreadable file, 2 unresolved or ambiguous component/event, or a write that did not verify.",
+        ],
+        stringFlags: ["file", "component", "update-set"],
+    },
     "host-assets": {
         summary: "Deploy a built dist/ to ServiceNow (carrier sys_ui_script + attachment + m2m)",
         required: [

package/dist/createRecord.d.ts

@@ -9,7 +9,8 @@
  * The INSERT counterpart to `set-field`.
  *
  * NOT for schema tables (sys_db_object / sys_dictionary) — that's
- * create-table / add-column. To UPDATE an existing record, use `set-field`.
+ * create-table / add-column. NOT for sys_update_set — that's
+ * `dove createUpdateSet`. To UPDATE an existing record, use `set-field`.
  */
 import type { ServiceNowClient } from "./client";
 import type { RecordWriteResult } from "./setField";

package/dist/createRecord.js

@@ -10,7 +10,8 @@
  * The INSERT counterpart to `set-field`.
  *
  * NOT for schema tables (sys_db_object / sys_dictionary) — that's
- * create-table / add-column. To UPDATE an existing record, use `set-field`.
+ * create-table / add-column. NOT for sys_update_set — that's
+ * `dove createUpdateSet`. To UPDATE an existing record, use `set-field`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRecord = createRecord;
@@ -19,6 +20,11 @@ const setField_1 = require("./setField");
 // Same guard as set-field: schema tables are never written as data — routed to
 // the dedicated schema verbs instead so we never orphan or corrupt metadata.
 var REFUSED_TABLES = ["sys_db_object", "sys_dictionary"];
+// The generic createRecord op never sets `application`, so an update set
+// inserted through it lands in the session app while the read-back (name only)
+// still reports success. Update sets go through the scope-correct
+// createUpdateSet op instead.
+var UPDATE_SET_TABLE = "sys_update_set";
 async function createRecord(params) {
     var client = params.client || (0, client_1.createClient)({});
     var table = params.table;
@@ -29,6 +35,11 @@ async function createRecord(params) {
         throw new Error("create-record: refusing to write " + table + " as data — it is a schema table. "
             + "Use add-column / create-table for schema changes.");
     }
+    if (table === UPDATE_SET_TABLE) {
+        throw new Error("create-record: refusing to create a sys_update_set record — the generic createRecord op "
+            + "does not set its application, so the set would land in the session app. "
+            + "Use `dove createUpdateSet --name <name> --scope <scope>` instead.");
+    }
     var fieldNames = params.fields ? Object.keys(params.fields) : [];
     if (fieldNames.length === 0) {
         throw new Error("create-record: at least one field (--fields key=value) is required.");