@tenonhq/dovetail-servicenow 0.0.36 → 0.0.37

package/README.md

@@ -367,6 +367,56 @@ adds diagnostics (app-switch status, resolved column key, assigned sys_id) to th
 result note. Ground truth (the HAR dissection) lives in the CTO repo's create-table
 docs.
 
+### Add a unique index
+
+Create a **single-column UNIQUE index** on an existing table, then read it back.
+
+```bash
+# Dry-run (the DEFAULT) - prints the plan, writes nothing and reads nothing
+npx dove-sn add-index \
+  --table x_cadso_journey_instance --columns occurrence_key --unique \
+  --update-set <sys_id> --json
+
+# Send it
+npx dove-sn add-index \
+  --table x_cadso_journey_instance --columns occurrence_key --unique \
+  --update-set <sys_id> --confirm
+```
+
+The **only** headless lever for an index is `sys_dictionary.unique`. `sys_index` fails an
+API-LEVEL ACL (HTTP 403) for every identity - and an ACL that refuses `GET` refuses `POST` -
+while `sys_index_column` does not exist at all (HTTP 400 `Invalid table`). So `add-index`
+patches the column's dictionary row through the update-set-aware write path and lets the
+platform build the physical index off that flag.
+
+Three consequences, each reported rather than hidden:
+
+- **One column, unique only.** `unique` is a per-COLUMN flag, so a composite index has no
+  dictionary lever. A multi-column request is **refused**, never narrowed to its first
+  column - building a different index than the one asked for is the worst available
+  outcome. `--unique` is required for the same reason. Composite and plain indexes stay
+  platform-UI work.
+- **Duplicates abort the run BEFORE it writes.** A unique index cannot build over repeated
+  values, and ServiceNow fails that ALTER *silently* - leaving a dictionary row claiming
+  `unique=true` with no index behind it (which is exactly what
+  `x_cadso_core_metric_point.idempotency_key` looks like today). **EMPTY counts as a
+  value**: a freshly added column that is empty on every existing row is one collision per
+  row. Backfill first, index second. The scan is paged and capped, and a scan that hits
+  that cap **aborts the same way** - an UNPROVEN scan is treated exactly like a proven
+  collision, because writing on a column that was only read part-way is how this verb
+  would manufacture that trap on a table too big for anyone to have checked.
+- **Success is read back; uniqueness never is.** `status` is `created` only when a matching
+  row was read back from the `v_db_index` view; a flag with no index is `failed`.
+  `verified.indexPresent` is `null` - UNKNOWN, not `false` - when the view could not be
+  read, because a blind instrument is not evidence of absence. And `v_db_index` carries no
+  uniqueness field (every row reads `btree`, unique or not), so **`uniqueness-enforced` is
+  listed in `unverified` on every status, success included**: only a duplicate-insert test
+  proves enforcement.
+
+`--update-set` is required on the live path and is checked before a client is built or a
+single request goes out. Exit codes: `0` created / skipped / dry-run, `1` bad args, `2`
+failed (the lying-row case included).
+
 ### Set a field on a record
 
 Set scalar field value(s) on an **existing** data record, capture the change into
@@ -576,7 +626,9 @@ console.log(formatLayoutResult("form layout", result));
 `dove-sn mcp` runs a self-contained MCP stdio server exposing the tools to
 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`, the record-write verbs `set_field` (update scalar fields on an
+`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
 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

@@ -977,6 +977,20 @@ function printHelp() {
         "                      [--name <element>] [--max-length <n>] [--reference <table>]\n" +
         "                      [--mandatory] [--default <v>] [--scope <s>] [--dry-run] [--json])\n" +
         "                     --update-set is REQUIRED on the live path (not for --dry-run).\n" +
+        "  add-index          Create a single-column UNIQUE index (sys_dictionary.unique), then verify\n" +
+        "                     DRY-RUN BY DEFAULT — nothing is written without --confirm\n" +
+        "                     (--table <name|sys_id> --columns <column> --unique --update-set <sys_id>\n" +
+        "                      [--confirm] [--scope <s>] [--dry-run] [--debug] [--json])\n" +
+        "                     ONE column only: unique is a per-COLUMN dictionary flag, so a\n" +
+        "                     composite index is REFUSED, not narrowed — that stays UI work,\n" +
+        "                     as does a plain (non-unique) index. The run ABORTS before writing\n" +
+        "                     when the column holds duplicate values (EMPTY counts): a unique\n" +
+        "                     index cannot build over them and the platform fails that ALTER\n" +
+        "                     SILENTLY, leaving unique=true with no index behind it. It aborts\n" +
+        "                     the same way when that scan hits its row cap — an UNPROVEN scan\n" +
+        "                     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" +
         "  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" +
@@ -1222,6 +1236,82 @@ async function runAddColumn(flags) {
         return 2;
     return 0;
 }
+/**
+ * dove-sn add-index:
+ *   --table x_cadso_journey_instance --columns occurrence_key --unique
+ *   --update-set <sys_id> [--confirm] [--scope x_cadso_journey] [--debug] [--json]
+ *
+ * DRY-RUN BY DEFAULT — nothing is written without --confirm (--dry-run forces a
+ * dry-run even with it). --update-set is required on the live path and is checked
+ * here, before a client is built or a single request goes out.
+ *
+ * Exit codes: 0 created / skipped / dry-run, 1 bad args, 2 failed (which includes
+ * "the dictionary flag is set but no index was read back" — the lying-row case).
+ */
+async function runAddIndex(flags) {
+    var table = flags.table;
+    var columns = (flags.columns || "")
+        .split(",")
+        .map(function (c) {
+        return c.trim();
+    })
+        .filter(function (c) {
+        return c.length > 0;
+    });
+    if (!table || columns.length === 0) {
+        process.stderr.write("add-index: --table and --columns <column> are required " +
+            "(--unique too, and --update-set unless this is a dry-run)\n");
+        return 1;
+    }
+    // The only headless lever is sys_dictionary.unique. Refuse a non-unique request by
+    // name instead of building something else and calling it done.
+    if (flags.unique !== "true") {
+        process.stderr.write("add-index: --unique is required — the only headless lever is " +
+            "sys_dictionary.unique, which has no equivalent for a plain (non-unique) " +
+            "index. Create that one in the platform UI.\n");
+        return 1;
+    }
+    // DRY-RUN BY DEFAULT: --confirm is what sends; --dry-run forces a plan even with it.
+    var dryRun = flags["dry-run"] === "true" || flags.confirm !== "true";
+    if (!dryRun && !flags["update-set"]) {
+        process.stderr.write("add-index: --update-set is required on the live path (only a dry-run works without one)\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        table: table,
+        columns: columns,
+        unique: true,
+        dryRun: dryRun,
+    };
+    if (flags.scope)
+        params.scope = flags.scope;
+    if (flags["update-set"])
+        params.updateSetSysId = flags["update-set"];
+    if (flags.debug === "true")
+        params.debug = true;
+    var result = await (0, table_1.addIndex)(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.indexName ? " -> " + result.indexName : "") +
+            "\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") {
@@ -1851,6 +1941,9 @@ async function main() {
     if (parsed.command === "add-column") {
         return await runAddColumn(parsed.flags);
     }
+    if (parsed.command === "add-index") {
+        return await runAddIndex(parsed.flags);
+    }
     if (parsed.command === "set-column") {
         return await runSetColumn(parsed.flags, parsed.bare);
     }

package/dist/index.d.ts

@@ -21,8 +21,8 @@ export { sincPlugin } from "./plugin";
 export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, editActionType, 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, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, EditActionTypeParams, EditActionTypeResult, EditActionTypeOps, StepOps, StepRecord, StepSummary, StepIoSummary, PatchStepScriptOp, 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, setColumn, resolveAttributes, toStoredValue, setTable, resolveTableAttributes, } from "./table";
-export type { CreateTableParams, CreateTableResult, AddColumnParams, AddColumnResult, 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, 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 { setField } from "./setField";
 export { createRecord } from "./createRecord";
 export type { RecordWriteResult, SetFieldParams, SetFieldResult, } from "./setField";

package/dist/index.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeColumns = exports.buildColumnXml = exports.projectTableGraph = exports.createTable = exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.formatStepPill = exports.summarizeSteps = exports.verifySteps = exports.applyStepOps = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatRemoveChoicesResult = exports.formatAddChoicesResult = exports.formatHostAssetsResult = exports.classifyChunks = exports.hostAssets = exports.ChoiceWriteError = exports.removeChoicesFromField = exports.addChoicesToField = exports.resolveConfigFromEnvFile = exports.createClientFromEnvFile = exports.assertWriteAllowed = exports.evaluateWriteGate = exports.isCiEnvironment = exports.resolveExecutionContext = exports.createClient = void 0;
-exports.PUBLISH_POLL_DELAYS_MS = exports.DEFAULT_PUBLISH_TIMEOUT_MS = exports.parseCicdProgress = exports.parseCicdPublishResponse = exports.harvestProgressResults = exports.flattenSteps = exports.classifyProgress = exports.parseProgressTree = exports.parseXmlAnswer = exports.buildStartFields = exports.publishApp = exports.INVOKE_REST_METHODS = exports.invokeRest = exports.createRecord = exports.setField = exports.resolveTableAttributes = exports.setTable = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.deriveElement = exports.addColumn = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.TYPE_MAP = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = void 0;
+exports.PUBLISH_POLL_DELAYS_MS = exports.DEFAULT_PUBLISH_TIMEOUT_MS = exports.parseCicdProgress = exports.parseCicdPublishResponse = exports.harvestProgressResults = exports.flattenSteps = exports.classifyProgress = exports.parseProgressTree = exports.parseXmlAnswer = exports.buildStartFields = exports.publishApp = exports.INVOKE_REST_METHODS = exports.invokeRest = exports.createRecord = exports.setField = exports.resolveTableAttributes = exports.setTable = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.indexMatchesColumns = exports.parseIndexColumns = exports.addIndex = exports.deriveElement = exports.addColumn = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.TYPE_MAP = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var executionContext_1 = require("./executionContext");
@@ -80,6 +80,9 @@ Object.defineProperty(exports, "DEFAULT_SUPER_CLASS", { enumerable: true, get: f
 Object.defineProperty(exports, "DEFAULT_SAVE_ACTION", { enumerable: true, get: function () { return table_1.DEFAULT_SAVE_ACTION; } });
 Object.defineProperty(exports, "addColumn", { enumerable: true, get: function () { return table_1.addColumn; } });
 Object.defineProperty(exports, "deriveElement", { enumerable: true, get: function () { return table_1.deriveElement; } });
+Object.defineProperty(exports, "addIndex", { enumerable: true, get: function () { return table_1.addIndex; } });
+Object.defineProperty(exports, "parseIndexColumns", { enumerable: true, get: function () { return table_1.parseIndexColumns; } });
+Object.defineProperty(exports, "indexMatchesColumns", { enumerable: true, get: function () { return table_1.indexMatchesColumns; } });
 Object.defineProperty(exports, "setColumn", { enumerable: true, get: function () { return table_1.setColumn; } });
 Object.defineProperty(exports, "resolveAttributes", { enumerable: true, get: function () { return table_1.resolveAttributes; } });
 Object.defineProperty(exports, "toStoredValue", { enumerable: true, get: function () { return table_1.toStoredValue; } });

package/dist/mcp/registry.d.ts

@@ -10,7 +10,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ToolAnnotations } from "@tenonhq/dovetail-mcp-kit";
 import type { ServiceNowClient } from "../client";
-export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "remove_choices_from_field", "flow_view", "action_view", "action_edit", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit", "create_table", "add_column", "set_column", "set_table", "set_field", "create_record", "host_assets", "invoke_rest", "app_publish"];
+export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "remove_choices_from_field", "flow_view", "action_view", "action_edit", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit", "create_table", "add_column", "add_index", "set_column", "set_table", "set_field", "create_record", "host_assets", "invoke_rest", "app_publish"];
 export type ToolName = (typeof TOOL_NAMES)[number];
 export interface RegistryDeps {
     /** Optional client injection for tests; defaults to createClient({}). */

package/dist/mcp/registry.js

@@ -50,6 +50,7 @@ exports.TOOL_NAMES = [
     "flow_edit",
     "create_table",
     "add_column",
+    "add_index",
     "set_column",
     "set_table",
     "set_field",
@@ -373,6 +374,65 @@ function buildDescriptors(deps = {}) {
                 });
             },
         },
+        {
+            name: "add_index",
+            annotations: dovetail_mcp_kit_1.WRITE_OVERWRITE,
+            description: "Create a single-column UNIQUE index on an EXISTING ServiceNow table, headless. The " +
+                "ONLY headless lever is sys_dictionary.unique — sys_index fails an API-LEVEL ACL (403) " +
+                "for every identity and sys_index_column does not exist — so this patches the column's " +
+                "dictionary row through the update-set-aware write path and lets the platform build the " +
+                "physical index off that flag, then READS IT BACK from the v_db_index view. columns is a " +
+                "list but exactly one entry is supported: unique is a PER-COLUMN flag, so a composite " +
+                "request is REFUSED rather than silently narrowed to a different index than the one asked " +
+                "for, and unique:false is refused too (there is no dictionary lever for a plain index) — " +
+                "both stay platform-UI work. Before writing, the column's values are scanned and the run " +
+                "ABORTS on duplicates, EMPTY included: a unique index cannot build over them, and the " +
+                "platform fails that ALTER SILENTLY, leaving a dictionary row claiming unique=true with no " +
+                "index behind it (the x_cadso_core_metric_point.idempotency_key trap). That scan is paged " +
+                "and capped, and a scan that hits the cap ABORTS TOO — an UNPROVEN scan is treated exactly " +
+                "like a proven collision, because writing on a partly-read column is how this verb would " +
+                "manufacture that trap on a table too big to have been checked. status is 'created' " +
+                "only when a matching v_db_index row was read back; a flag with no index is 'failed', and " +
+                "verified.indexPresent is null (UNKNOWN) when the view could not be read — never false, " +
+                "because a blind instrument is not evidence of absence. 'uniqueness-enforced' is ALWAYS " +
+                "reported in unverified: v_db_index carries no uniqueness field, so enforcement is provable " +
+                "only by a duplicate-insert test. updateSetSysId is required on the live path; dryRun:true " +
+                "returns the plan with no reads and no writes.",
+            shape: schemas_1.addIndexSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.addIndexSchema.parse(args);
+                // The schema leaves updateSetSysId optional (dry-run doesn't need one), so
+                // enforce the live-path requirement HERE — a tool-level error before any
+                // work beats a failure surfacing from deep inside addIndex. Same pattern as
+                // add_column.
+                if (p.dryRun !== true &&
+                    (!p.updateSetSysId || !p.updateSetSysId.trim())) {
+                    throw new Error("add_index: updateSetSysId is required on the live path so the " +
+                        "sys_dictionary change is captured in a known update set — " +
+                        "set dryRun:true to plan without one.");
+                }
+                // `unique` is boolean at the boundary (unvalidated JSON arrives here), but only
+                // true is buildable — refuse it by name rather than let a caller believe a plain
+                // index was created.
+                var unique = p.unique;
+                if (unique !== true) {
+                    throw new Error("add_index: only a unique index can be created headlessly — the sole " +
+                        "lever is sys_dictionary.unique, which has no equivalent for a plain " +
+                        "(non-unique) index. Pass unique:true, or create that index in the " +
+                        "platform UI.");
+                }
+                return (0, table_1.addIndex)({
+                    client: client(),
+                    table: p.table,
+                    columns: p.columns,
+                    unique: unique,
+                    scope: p.scope,
+                    updateSetSysId: p.updateSetSysId,
+                    dryRun: p.dryRun,
+                    debug: p.debug,
+                });
+            },
+        },
         {
             name: "set_column",
             annotations: dovetail_mcp_kit_1.WRITE_OVERWRITE,

package/dist/mcp/schemas.d.ts

@@ -849,6 +849,31 @@ export declare var addColumnSchema: z.ZodObject<{
     scope?: string | undefined;
     updateSetSysId?: string | undefined;
 }>;
+export declare var addIndexSchema: z.ZodObject<{
+    table: z.ZodString;
+    columns: z.ZodArray<z.ZodString, "many">;
+    unique: z.ZodBoolean;
+    scope: z.ZodOptional<z.ZodString>;
+    updateSetSysId: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    columns: string[];
+    table: string;
+    unique: boolean;
+    dryRun?: boolean | undefined;
+    debug?: boolean | undefined;
+    scope?: string | undefined;
+    updateSetSysId?: string | undefined;
+}, {
+    columns: string[];
+    table: string;
+    unique: boolean;
+    dryRun?: boolean | undefined;
+    debug?: boolean | undefined;
+    scope?: string | undefined;
+    updateSetSysId?: string | undefined;
+}>;
 export declare var columnAttributesSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     mandatory: z.ZodOptional<z.ZodBoolean>;

package/dist/mcp/schemas.js

@@ -4,7 +4,7 @@
  * own file so registry.ts stays focused on wiring.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.invokeRestSchema = exports.publishAppSchema = exports.createRecordSchema = exports.setFieldSchema = exports.setTableSchema = exports.tableAttributesSchema = exports.setColumnSchema = exports.columnAttributesSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.editActionSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.removeChoicesFromFieldSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
+exports.invokeRestSchema = exports.publishAppSchema = exports.createRecordSchema = exports.setFieldSchema = exports.setTableSchema = exports.tableAttributesSchema = exports.setColumnSchema = exports.columnAttributesSchema = exports.addIndexSchema = exports.addColumnSchema = exports.createTableSchema = exports.columnSpecSchema = exports.hostAssetsSchema = exports.editFlowSchema = exports.editActionSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.removeChoicesFromFieldSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
 const zod_1 = require("zod");
 exports.createViewSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
@@ -221,6 +221,23 @@ exports.addColumnSchema = zod_1.z.object({
     dryRun: zod_1.z.boolean().optional(),
     debug: zod_1.z.boolean().optional(),
 });
+// add-index keeps a column LIST because an index is conceptually multi-column, but the
+// only headless lever (sys_dictionary.unique) is per-COLUMN — so addIndex REFUSES a list
+// longer than one rather than silently building a different index than the one asked for.
+// `unique` is a plain boolean here for the same reason `internalType` is accepted by
+// set-column: a caller who asks for a non-unique index earns the explanation of why it is
+// impossible instead of a schema error that reads like a typo. updateSetSysId is optional
+// because dryRun needs none; the live-path requirement is enforced at the tool boundary
+// (registry.ts), matching add_column.
+exports.addIndexSchema = zod_1.z.object({
+    table: zod_1.z.string().min(1),
+    columns: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    unique: zod_1.z.boolean(),
+    scope: zod_1.z.string().optional(),
+    updateSetSysId: zod_1.z.string().min(1).optional(),
+    dryRun: zod_1.z.boolean().optional(),
+    debug: zod_1.z.boolean().optional(),
+});
 // set-column takes a CLOSED attribute set, not an open field map: an unbounded write to
 // sys_dictionary lets a caller silently corrupt the schema. internalType and element are
 // listed but are NOT settable — ServiceNow honours neither on an existing column, and

package/dist/table/addIndex.d.ts

@@ -0,0 +1,130 @@
+/**
+ * addIndex — create a single-column UNIQUE index on an EXISTING ServiceNow table,
+ * headless, and then read the result back.
+ *
+ * THE ONLY HEADLESS LEVER IS `sys_dictionary.unique`. There is no writable index
+ * table: `sys_index` fails an API-LEVEL ACL (HTTP 403) for every identity — an ACL
+ * that refuses GET refuses POST — and `sys_index_column` does not exist (HTTP 400
+ * "Invalid table"). So this verb patches the column's dictionary row through the
+ * scope-aware `pushWithUpdateSet` op (update set + scope switched server-side,
+ * exactly as `addColumn` does for max_length) and lets the platform build the
+ * physical index off that flag.
+ *
+ * Consequences, each of which the contract encodes rather than hides:
+ *
+ * 1. PER-COLUMN ONLY. `unique` is a column flag, so a composite index has no
+ *    dictionary lever at all. A multi-column request is REFUSED, never narrowed to
+ *    its first column — quietly building a different index than the one asked for is
+ *    the worst available outcome. Composite / non-unique indexes stay UI work.
+ *
+ * 2. THE FLAG IS NOT SELF-VERIFYING. `x_cadso_core_metric_point.idempotency_key`
+ *    reads `unique=true` in the dictionary with NO index on the table — a lying row.
+ *    So the write is never the proof: after the patch the dictionary row is re-read
+ *    BY sys_id and the index is looked for in the `v_db_index` VIEW (`table_name`,
+ *    `column_names` as a bracketed list like "[occurrence_key]", `index_name`,
+ *    `access_method`). A flag with no index is a FAILURE, not a success with a note.
+ *
+ * 3. UNIQUENESS ENFORCEMENT IS UNREADABLE. `v_db_index` carries no uniqueness field
+ *    — every row reads `access_method: btree`, unique or not — and the same view also
+ *    shows the ordinary reference indexes ServiceNow builds on its own. Presence of
+ *    an index over the right column is therefore NECESSARY BUT NOT SUFFICIENT, and
+ *    "uniqueness-enforced" is reported in `unverified` on EVERY status, success
+ *    included. Only a duplicate-insert test can prove enforcement.
+ *
+ * 4. A UNIQUE INDEX CANNOT BUILD OVER DUPLICATE VALUES, and the platform fails that
+ *    ALTER quietly — leaving exactly the lying row above. So the live path scans the
+ *    column first and ABORTS BEFORE WRITING when values repeat. EMPTY counts as a
+ *    value: a newly added column that is empty on all 498 existing rows is 498
+ *    collisions, which is the single most likely way this verb would be used wrong.
+ *    AN UNPROVEN SCAN IS TREATED EXACTLY LIKE A PROVEN COLLISION. The scan is paged
+ *    and capped (SCAN_MAX_PAGES x SCAN_PAGE_SIZE rows); if it hits that cap the run
+ *    ABORTS TOO. Writing on a scan that only got part-way would risk manufacturing
+ *    the very lying row above — on a table too big to have been checked — and there
+ *    is no headless way back from it, because writing "true" over "true" fires no
+ *    ALTER. "Not proven clean" is not "clean".
+ *
+ * `verified.indexPresent` is deliberately three-valued: `true` (a matching row was
+ * read back), `false` (the view WAS read and holds no such row) and `null` (the view
+ * could not be read, or was never read). Collapsing `null` into `false` would report
+ * "the index is absent" when the truth is "the instrument is blind".
+ *
+ * `set-column` cannot do this: its WRITABLE allowlist is closed (label, mandatory,
+ * default, read_only, max_length) and deliberately excludes `unique`, which has a
+ * physical side effect and a verification burden the others do not.
+ *
+ * ES6 only, no optional chaining, no `any`.
+ */
+import type { ServiceNowClient } from "../client";
+export interface AddIndexParams {
+    /** REST client for table/scope resolution, the dictionary patch, and the read-back. */
+    client: ServiceNowClient;
+    /** Existing table — its name ("x_cadso_journey_instance") OR its sys_db_object sys_id. */
+    table: string;
+    /** The column list. Exactly one entry today; more is REFUSED, never narrowed. */
+    columns: Array<string>;
+    /** Must be true — there is no dictionary lever for a plain (non-unique) index. */
+    unique: true;
+    /** Scope name or sys_scope sys_id. Must match the table's own scope. */
+    scope?: string;
+    /** Update set to capture the dictionary patch into. REQUIRED on the live path. */
+    updateSetSysId?: string;
+    /** Plan only — no reads, no writes. */
+    dryRun?: boolean;
+    /** Add diagnostic detail to the result note. */
+    debug?: boolean;
+}
+/** What was actually READ BACK. `null` means "not read", never "absent". */
+export interface AddIndexVerification {
+    /** sys_dictionary.unique re-read after the patch. null when the re-read failed. */
+    dictionaryUnique: boolean | null;
+    /** A v_db_index row over exactly these columns. null when the view was not read. */
+    indexPresent: boolean | null;
+    /** The matching row's `column_names`, verbatim (e.g. "[occurrence_key]"); "" when none. */
+    indexColumns: string;
+}
+export interface AddIndexResult {
+    status: "created" | "dry-run" | "failed" | "skipped";
+    /** The table's name (resolved on the live path; echoes the input on dry-run). */
+    table: string;
+    /** The requested column list, normalized. */
+    columns: Array<string>;
+    /** index_name as reported by v_db_index; "" when no matching index was read back. */
+    indexName: string;
+    verified: AddIndexVerification;
+    /** Always includes "uniqueness-enforced". Never empty. */
+    unverified: Array<string>;
+    /** Update set the patch was captured into ("" on dry-run without one). */
+    updateSetSysId: string;
+    note: string;
+}
+/** One repeated value and how many ROWS carry it. */
+export interface DuplicateValue {
+    value: string;
+    rows: number;
+}
+export interface DuplicateScan {
+    duplicates: Array<DuplicateValue>;
+    /** Rows actually read. */
+    scanned: number;
+    /**
+     * True when the scan hit its page cap — "no duplicates seen" is then not "none exist",
+     * so the live path REFUSES to write on it rather than downgrading it to a caveat.
+     */
+    incomplete: boolean;
+}
+/**
+ * Read the column's values across the table and count repeats. EMPTY is counted as a
+ * value, not skipped: ServiceNow stores an unset string as "", and "" collides with ""
+ * — the 498-rows-with-a-new-empty-column trap. Pages by a sys_id keyset because
+ * `client.table.query` exposes no sysparm_offset.
+ */
+export declare function scanForDuplicates(client: ServiceNowClient, table: string, column: string): Promise<DuplicateScan>;
+/** Parse a v_db_index `column_names` cell ("[a]", "[a,b]") into its column list. */
+export declare function parseIndexColumns(raw: string): Array<string>;
+/**
+ * Does this row's column list match the requested one EXACTLY? Parsed, never
+ * substring-matched: "[occurrence_key_extra]" contains "occurrence_key", and an
+ * indexOf test would green-light an index over the wrong column.
+ */
+export declare function indexMatchesColumns(raw: string, columns: Array<string>): boolean;
+export declare function addIndex(params: AddIndexParams): Promise<AddIndexResult>;

package/dist/table/addIndex.js

@@ -0,0 +1,588 @@
+"use strict";
+/**
+ * addIndex — create a single-column UNIQUE index on an EXISTING ServiceNow table,
+ * headless, and then read the result back.
+ *
+ * THE ONLY HEADLESS LEVER IS `sys_dictionary.unique`. There is no writable index
+ * table: `sys_index` fails an API-LEVEL ACL (HTTP 403) for every identity — an ACL
+ * that refuses GET refuses POST — and `sys_index_column` does not exist (HTTP 400
+ * "Invalid table"). So this verb patches the column's dictionary row through the
+ * scope-aware `pushWithUpdateSet` op (update set + scope switched server-side,
+ * exactly as `addColumn` does for max_length) and lets the platform build the
+ * physical index off that flag.
+ *
+ * Consequences, each of which the contract encodes rather than hides:
+ *
+ * 1. PER-COLUMN ONLY. `unique` is a column flag, so a composite index has no
+ *    dictionary lever at all. A multi-column request is REFUSED, never narrowed to
+ *    its first column — quietly building a different index than the one asked for is
+ *    the worst available outcome. Composite / non-unique indexes stay UI work.
+ *
+ * 2. THE FLAG IS NOT SELF-VERIFYING. `x_cadso_core_metric_point.idempotency_key`
+ *    reads `unique=true` in the dictionary with NO index on the table — a lying row.
+ *    So the write is never the proof: after the patch the dictionary row is re-read
+ *    BY sys_id and the index is looked for in the `v_db_index` VIEW (`table_name`,
+ *    `column_names` as a bracketed list like "[occurrence_key]", `index_name`,
+ *    `access_method`). A flag with no index is a FAILURE, not a success with a note.
+ *
+ * 3. UNIQUENESS ENFORCEMENT IS UNREADABLE. `v_db_index` carries no uniqueness field
+ *    — every row reads `access_method: btree`, unique or not — and the same view also
+ *    shows the ordinary reference indexes ServiceNow builds on its own. Presence of
+ *    an index over the right column is therefore NECESSARY BUT NOT SUFFICIENT, and
+ *    "uniqueness-enforced" is reported in `unverified` on EVERY status, success
+ *    included. Only a duplicate-insert test can prove enforcement.
+ *
+ * 4. A UNIQUE INDEX CANNOT BUILD OVER DUPLICATE VALUES, and the platform fails that
+ *    ALTER quietly — leaving exactly the lying row above. So the live path scans the
+ *    column first and ABORTS BEFORE WRITING when values repeat. EMPTY counts as a
+ *    value: a newly added column that is empty on all 498 existing rows is 498
+ *    collisions, which is the single most likely way this verb would be used wrong.
+ *    AN UNPROVEN SCAN IS TREATED EXACTLY LIKE A PROVEN COLLISION. The scan is paged
+ *    and capped (SCAN_MAX_PAGES x SCAN_PAGE_SIZE rows); if it hits that cap the run
+ *    ABORTS TOO. Writing on a scan that only got part-way would risk manufacturing
+ *    the very lying row above — on a table too big to have been checked — and there
+ *    is no headless way back from it, because writing "true" over "true" fires no
+ *    ALTER. "Not proven clean" is not "clean".
+ *
+ * `verified.indexPresent` is deliberately three-valued: `true` (a matching row was
+ * read back), `false` (the view WAS read and holds no such row) and `null` (the view
+ * could not be read, or was never read). Collapsing `null` into `false` would report
+ * "the index is absent" when the truth is "the instrument is blind".
+ *
+ * `set-column` cannot do this: its WRITABLE allowlist is closed (label, mandatory,
+ * default, read_only, max_length) and deliberately excludes `unique`, which has a
+ * physical side effect and a verification burden the others do not.
+ *
+ * ES6 only, no optional chaining, no `any`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanForDuplicates = scanForDuplicates;
+exports.parseIndexColumns = parseIndexColumns;
+exports.indexMatchesColumns = indexMatchesColumns;
+exports.addIndex = addIndex;
+const setField_1 = require("../setField");
+const choices_1 = require("../choices");
+var SYS_ID = /^[0-9a-f]{32}$/i;
+/** A dictionary element is a plain identifier. Anything else is rejected before it
+ *  reaches an encoded query or a sysparm_fields list. */
+var COLUMN_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** ServiceNow caps a Table API page at 1000 rows, and there is no sysparm_offset on
+ *  the client — the duplicate scan pages by a sys_id keyset instead. */
+var SCAN_PAGE_SIZE = 1000;
+var SCAN_MAX_PAGES = 10;
+var INDEX_ROW_LIMIT = 500;
+var SAMPLE_VALUE_MAX = 80;
+var MAX_DUPLICATE_SAMPLES = 5;
+/** Never provable from a read — see header note 3. Present on every status. */
+var UNIQUENESS_UNVERIFIABLE = "uniqueness-enforced";
+/** Set when v_db_index was not read at all (dry-run) or could not be read (403). */
+var INDEX_PRESENCE_UNVERIFIED = "index-presence";
+function errorMessage(e) {
+    if (e instanceof Error && e.message)
+        return e.message;
+    if (typeof e === "string" && e)
+        return e;
+    return String(e);
+}
+function isTrue(value) {
+    var v = value.toLowerCase();
+    return v === "true" || v === "1";
+}
+/** Validate every input BEFORE any network call, and return the single column name. */
+function validate(params) {
+    if (!params || typeof params !== "object")
+        throw new Error("add-index: params object required.");
+    if (!params.client)
+        throw new Error("add-index: client is required.");
+    if (typeof params.table !== "string" || !params.table.trim())
+        throw new Error("add-index: table is required.");
+    var columns = params.columns;
+    var count = Array.isArray(columns) ? columns.length : 0;
+    if (!Array.isArray(columns) || count !== 1) {
+        throw new Error("add-index: exactly one column is required (got " +
+            count +
+            "). sys_dictionary.unique is a PER-COLUMN flag, so there is no headless lever " +
+            "for a composite index — and taking the first column would build a DIFFERENT " +
+            "index than the one asked for. Create a composite index in the platform UI.");
+    }
+    var raw = columns[0];
+    if (typeof raw !== "string" || !raw.trim())
+        throw new Error("add-index: column must be a non-empty string.");
+    var column = raw.trim();
+    if (!COLUMN_NAME.test(column)) {
+        throw new Error("add-index: column '" +
+            column +
+            "' is not a valid column name — letters, digits and underscores only, " +
+            "starting with a letter.");
+    }
+    if (params.unique !== true) {
+        throw new Error("add-index: only a unique index can be created headlessly. The sole lever is " +
+            "sys_dictionary.unique, which has no equivalent for a plain (non-unique) index " +
+            "— pass unique:true, or create that index in the platform UI.");
+    }
+    if (params.dryRun !== true &&
+        (!params.updateSetSysId || !String(params.updateSetSysId).trim())) {
+        throw new Error("add-index: updateSetSysId is required on the live path so the sys_dictionary " +
+            "change is captured in a known update set (dry-run does not need one).");
+    }
+    return column;
+}
+/** Resolve the table by name or sys_id; returns its name, sys_id, and sys_scope sys_id. */
+async function resolveTable(client, table) {
+    var query = SYS_ID.test(table)
+        ? "sys_id=" + (0, choices_1.encodeQueryValue)(table)
+        : "name=" + (0, choices_1.encodeQueryValue)(table);
+    var rows = await client.table.query("sys_db_object", query, { limit: 1, fields: ["sys_id", "name", "sys_scope"] });
+    if (rows.length === 0) {
+        throw new Error("add-index: table '" + table + "' not found in sys_db_object.");
+    }
+    return {
+        name: (0, setField_1.fieldToString)(rows[0].name) || table,
+        sysId: (0, setField_1.fieldToString)(rows[0].sys_id),
+        scopeSysId: (0, setField_1.fieldToString)(rows[0].sys_scope),
+    };
+}
+/** Resolve a sys_scope sys_id to its scope NAME (e.g. "x_cadso_journey"). */
+async function resolveScopeName(client, scopeSysId) {
+    if (!scopeSysId)
+        return "";
+    var rows = await client.table.query("sys_scope", "sys_id=" + (0, choices_1.encodeQueryValue)(scopeSysId), { limit: 1, fields: ["scope"] });
+    return rows.length > 0 ? (0, setField_1.fieldToString)(rows[0].scope) : "";
+}
+/**
+ * Read the column's values across the table and count repeats. EMPTY is counted as a
+ * value, not skipped: ServiceNow stores an unset string as "", and "" collides with ""
+ * — the 498-rows-with-a-new-empty-column trap. Pages by a sys_id keyset because
+ * `client.table.query` exposes no sysparm_offset.
+ */
+async function scanForDuplicates(client, table, column) {
+    var counts = new Map();
+    var cursor = "";
+    var scanned = 0;
+    var incomplete = false;
+    for (var page = 0; page < SCAN_MAX_PAGES; page += 1) {
+        var query = (cursor ? "sys_id>" + (0, choices_1.encodeQueryValue)(cursor) + "^" : "") +
+            "ORDERBYsys_id";
+        var rows = await client.table.query(table, query, {
+            limit: SCAN_PAGE_SIZE,
+            fields: ["sys_id", column],
+        });
+        if (!Array.isArray(rows) || rows.length === 0)
+            break;
+        var moved = false;
+        for (var i = 0; i < rows.length; i += 1) {
+            var row = rows[i] && typeof rows[i] === "object" ? rows[i] : {};
+            var value = (0, setField_1.fieldToString)(row[column]);
+            var seen = counts.get(value);
+            counts.set(value, (seen === undefined ? 0 : seen) + 1);
+            var sysId = (0, setField_1.fieldToString)(row.sys_id);
+            if (sysId && sysId !== cursor) {
+                cursor = sysId;
+                moved = true;
+            }
+        }
+        scanned += rows.length;
+        if (rows.length < SCAN_PAGE_SIZE)
+            break;
+        // A full page that did not advance the cursor would re-read itself forever.
+        if (!moved || page === SCAN_MAX_PAGES - 1) {
+            incomplete = true;
+            break;
+        }
+    }
+    var duplicates = [];
+    counts.forEach(function (rowCount, value) {
+        if (rowCount > 1)
+            duplicates.push({ value: value, rows: rowCount });
+    });
+    duplicates.sort(function (a, b) {
+        return b.rows - a.rows;
+    });
+    return { duplicates: duplicates, scanned: scanned, incomplete: incomplete };
+}
+function sampleValue(value) {
+    if (value === "")
+        return "(empty)";
+    if (value.length <= SAMPLE_VALUE_MAX)
+        return "'" + value + "'";
+    return "'" + value.slice(0, SAMPLE_VALUE_MAX) + "' (truncated)";
+}
+function describeDuplicates(scan) {
+    var collidingRows = 0;
+    scan.duplicates.forEach(function (d) {
+        collidingRows += d.rows;
+    });
+    var shown = scan.duplicates.slice(0, MAX_DUPLICATE_SAMPLES).map(function (d) {
+        return sampleValue(d.value) + " (" + d.rows + " rows)";
+    });
+    return (scan.duplicates.length +
+        " duplicated value(s) across " +
+        collidingRows +
+        " rows, of " +
+        scan.scanned +
+        " scanned: " +
+        shown.join(", ") +
+        (scan.duplicates.length > shown.length ? ", ..." : ""));
+}
+/** Parse a v_db_index `column_names` cell ("[a]", "[a,b]") into its column list. */
+function parseIndexColumns(raw) {
+    var text = String(raw === undefined || raw === null ? "" : raw).trim();
+    if (text.length > 1 &&
+        text.charAt(0) === "[" &&
+        text.charAt(text.length - 1) === "]") {
+        text = text.slice(1, text.length - 1);
+    }
+    if (!text)
+        return [];
+    return text
+        .split(",")
+        .map(function (part) {
+        return part.trim();
+    })
+        .filter(function (part) {
+        return part.length > 0;
+    });
+}
+/**
+ * Does this row's column list match the requested one EXACTLY? Parsed, never
+ * substring-matched: "[occurrence_key_extra]" contains "occurrence_key", and an
+ * indexOf test would green-light an index over the wrong column.
+ */
+function indexMatchesColumns(raw, columns) {
+    var parsed = parseIndexColumns(raw);
+    if (parsed.length !== columns.length)
+        return false;
+    for (var i = 0; i < parsed.length; i += 1) {
+        if (parsed[i].toLowerCase() !== String(columns[i]).toLowerCase()) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Read the index back from `v_db_index`. `sys_index` is never touched: it is
+ * API-level-ACL 403 to every identity, so reading it would turn a blind instrument
+ * into a hard failure of the whole verb.
+ */
+async function readIndexBack(client, table, columns) {
+    var rows;
+    try {
+        rows = await client.table.query("v_db_index", "table_name=" + (0, choices_1.encodeQueryValue)(table), {
+            limit: INDEX_ROW_LIMIT,
+            fields: ["table_name", "index_name", "column_names", "access_method"],
+        });
+    }
+    catch (e) {
+        return {
+            readable: false,
+            error: errorMessage(e),
+            present: false,
+            indexName: "",
+            indexColumns: "",
+            others: [],
+        };
+    }
+    var others = [];
+    var match;
+    var safeRows = Array.isArray(rows) ? rows : [];
+    for (var i = 0; i < safeRows.length; i += 1) {
+        var row = safeRows[i] && typeof safeRows[i] === "object" ? safeRows[i] : {};
+        if ((0, setField_1.fieldToString)(row.table_name) !== table)
+            continue;
+        var cols = (0, setField_1.fieldToString)(row.column_names);
+        if (!match && indexMatchesColumns(cols, columns)) {
+            match = row;
+        }
+        else {
+            others.push((0, setField_1.fieldToString)(row.index_name) + " over " + cols);
+        }
+    }
+    return {
+        readable: true,
+        error: "",
+        present: Boolean(match),
+        indexName: match ? (0, setField_1.fieldToString)(match.index_name) : "",
+        indexColumns: match ? (0, setField_1.fieldToString)(match.column_names) : "",
+        others: others,
+    };
+}
+function finish(state, status, note) {
+    return {
+        status: status,
+        table: state.table,
+        columns: state.columns.slice(),
+        indexName: state.indexName,
+        verified: {
+            dictionaryUnique: state.dictionaryUnique,
+            indexPresent: state.indexPresent,
+            indexColumns: state.indexColumns,
+        },
+        unverified: [UNIQUENESS_UNVERIFIABLE].concat(state.extraUnverified),
+        updateSetSysId: state.updateSetSysId,
+        note: note,
+    };
+}
+/** The read-back verdict, shared by the "we wrote" and "already set" paths. */
+function verdict(state, readBack, wrote, table, column, extraNote) {
+    var target = table + "." + column;
+    var caveat = " NOT VERIFIED: that the index actually REJECTS duplicates — v_db_index carries no " +
+        "uniqueness field (every row reads btree, unique or not), so enforcement is provable " +
+        "only by a duplicate-insert test.";
+    if (!readBack.readable) {
+        state.indexPresent = null;
+        state.extraUnverified.push(INDEX_PRESENCE_UNVERIFIED);
+        return finish(state, "failed", (wrote
+            ? "sys_dictionary.unique=true was written for " + target + ", but "
+            : target + " already reads unique=true in sys_dictionary, but ") +
+            "v_db_index could not be read — index presence is UNKNOWN, which is NOT the " +
+            "same as absent: " +
+            readBack.error +
+            ". Re-run the read-back with an identity that can read v_db_index before " +
+            "treating this index as built." +
+            caveat +
+            extraNote);
+    }
+    state.indexPresent = readBack.present;
+    state.indexName = readBack.indexName;
+    state.indexColumns = readBack.indexColumns;
+    if (!readBack.present) {
+        return finish(state, "failed", (wrote
+            ? "sys_dictionary.unique=true was written for " +
+                target +
+                ", but the index is "
+            : target +
+                " already reads unique=true in sys_dictionary, but the index is ") +
+            "NOT OBSERVED in v_db_index" +
+            (readBack.others.length > 0
+                ? " (the table's other indexes: " + readBack.others.join("; ") + ")"
+                : " (the view reports no index at all for this table)") +
+            ". This is the lying-row case — a dictionary flag with no physical index " +
+            "behind it, which enforces nothing. " +
+            (wrote
+                ? "The most likely cause is duplicate values the ALTER could not build over."
+                : "Writing 'true' over 'true' fires no ALTER, so nothing was written and " +
+                    "add-index cannot repair this: clear the duplicates and rebuild the index " +
+                    "in the platform UI.") +
+            caveat +
+            extraNote);
+    }
+    return finish(state, wrote ? "created" : "skipped", (wrote
+        ? "Set sys_dictionary.unique=true on " +
+            target +
+            " and READ BACK a matching index in v_db_index: "
+        : target +
+            " already reads unique=true in sys_dictionary and v_db_index already holds a " +
+            "matching index — nothing was written: ") +
+        (readBack.indexName || "(unnamed)") +
+        " over " +
+        readBack.indexColumns +
+        "." +
+        caveat +
+        extraNote);
+}
+async function addIndex(params) {
+    var column = validate(params);
+    var client = params.client;
+    if (params.dryRun) {
+        return {
+            status: "dry-run",
+            table: params.table,
+            columns: [column],
+            indexName: "",
+            verified: {
+                dictionaryUnique: false,
+                indexPresent: null,
+                indexColumns: "",
+            },
+            unverified: [UNIQUENESS_UNVERIFIABLE, INDEX_PRESENCE_UNVERIFIED],
+            updateSetSysId: params.updateSetSysId ? params.updateSetSysId : "",
+            note: "dry-run: nothing written and nothing read. Would set sys_dictionary.unique=true " +
+                "on '" +
+                params.table +
+                "." +
+                column +
+                "' — the only headless lever for an index — captured into update set " +
+                (params.updateSetSysId ? params.updateSetSysId : "(none provided)") +
+                ", then re-read the dictionary row and look for an index over [" +
+                column +
+                "] in v_db_index. A dry-run does NOT check that the column exists, that its " +
+                "values are free of duplicates (a unique index cannot build over them, empty " +
+                "values included), or that an index is already there — the live path does all " +
+                "three before it writes.",
+        };
+    }
+    // ---- LIVE PATH ------------------------------------------------------------
+    var updateSetSysId = String(params.updateSetSysId).trim();
+    var resolved = await resolveTable(client, params.table);
+    var scopeName = await resolveScopeName(client, resolved.scopeSysId);
+    if (!scopeName) {
+        throw new Error("add-index: could not resolve the scope name for table '" +
+            resolved.name +
+            "' (sys_scope " +
+            (resolved.scopeSysId || "(none)") +
+            ") — needed to confirm the column is written in its own scope.");
+    }
+    // A column lives in its table's scope; an explicit override must match it.
+    if (params.scope && params.scope.trim()) {
+        var override = params.scope.trim();
+        if (override !== scopeName && override !== resolved.scopeSysId) {
+            throw new Error("add-index: --scope '" +
+                override +
+                "' does not match table '" +
+                resolved.name +
+                "' scope '" +
+                scopeName +
+                "' — an index lives in its table's scope. Omit --scope or set it to '" +
+                scopeName +
+                "'.");
+        }
+    }
+    var state = {
+        table: resolved.name,
+        columns: [column],
+        updateSetSysId: updateSetSysId,
+        dictionaryUnique: false,
+        indexPresent: null,
+        indexColumns: "",
+        indexName: "",
+        extraUnverified: [],
+    };
+    var dictRows = await client.table.query("sys_dictionary", "name=" +
+        (0, choices_1.encodeQueryValue)(resolved.name) +
+        "^element=" +
+        (0, choices_1.encodeQueryValue)(column), {
+        limit: 1,
+        fields: ["sys_id", "name", "element", "internal_type", "unique"],
+    });
+    if (dictRows.length === 0) {
+        return finish(state, "failed", "column '" +
+            column +
+            "' does not exist on " +
+            resolved.name +
+            " — no sys_dictionary row for name=" +
+            resolved.name +
+            "^element=" +
+            column +
+            ". Nothing was written. Add the column first (dove-sn add-column), backfill it, " +
+            "then index it.");
+    }
+    var dictSysId = (0, setField_1.fieldToString)(dictRows[0].sys_id);
+    var internalType = (0, setField_1.fieldToString)(dictRows[0].internal_type);
+    if (!dictSysId) {
+        // The patch targets the dictionary row BY sys_id. Without one there is nothing to
+        // aim at, and sending an empty record_sys_id would write blind.
+        return finish(state, "failed", "the sys_dictionary row for " +
+            resolved.name +
+            "." +
+            column +
+            " came back without a sys_id, so there is no row to patch. Nothing was " +
+            "written — check the column (and the caller's read access to sys_dictionary) " +
+            "on the instance.");
+    }
+    var alreadyUnique = isTrue((0, setField_1.fieldToString)(dictRows[0].unique));
+    state.dictionaryUnique = alreadyUnique;
+    var debugNote = params.debug
+        ? " [debug: dictionarySysId=" +
+            dictSysId +
+            " internalType=" +
+            (internalType || "(none)") +
+            " scope=" +
+            scopeName +
+            " tableSysId=" +
+            resolved.sysId +
+            "]"
+        : "";
+    // Already flagged: writing "true" over "true" fires no ALTER, so there is nothing
+    // this verb can do — go straight to the read-back and report what is actually there.
+    if (alreadyUnique) {
+        var existing = await readIndexBack(client, resolved.name, [column]);
+        return verdict(state, existing, false, resolved.name, column, debugNote);
+    }
+    // A unique index cannot build over duplicates, and the failed ALTER is SILENT —
+    // it leaves the dictionary claiming unique=true with no index behind it. Check first.
+    var scan = await scanForDuplicates(client, resolved.name, column);
+    if (scan.duplicates.length > 0) {
+        return finish(state, "failed", "Refusing to write: a unique index cannot build over duplicate values, and " +
+            resolved.name +
+            "." +
+            column +
+            " holds them — the platform would fail the ALTER silently and leave " +
+            "sys_dictionary claiming unique=true with NO index behind it (the " +
+            "x_cadso_core_metric_point.idempotency_key trap). " +
+            describeDuplicates(scan) +
+            ". An EMPTY value counts: every empty row collides with every other empty row. " +
+            "Nothing was written — backfill or clear those rows, then re-run." +
+            debugNote);
+    }
+    // The scan is capped. A capped scan proves NOTHING about the rows it never read, and
+    // writing on "no duplicates in the part I saw" is how this verb would manufacture the
+    // lying row it exists to prevent — on a table too big for anyone to have checked, with
+    // no headless way back (writing "true" over "true" fires no ALTER). So an unproven scan
+    // aborts exactly like a proven collision does.
+    if (scan.incomplete) {
+        return finish(state, "failed", "Refusing to write: the duplicate scan could not read the whole column. It " +
+            "stopped after " +
+            scan.scanned +
+            " rows of " +
+            resolved.name +
+            "." +
+            column +
+            ", so freedom from duplicates is UNPROVEN beyond that depth — and a unique " +
+            "index that meets a collision fails its ALTER SILENTLY, leaving sys_dictionary " +
+            "claiming unique=true with NO index behind it (the " +
+            "x_cadso_core_metric_point.idempotency_key trap) and no headless way back, " +
+            "because writing 'true' over 'true' fires no ALTER. Nothing was written — " +
+            "prove the column is duplicate-free by another route (EMPTY counts as a value) " +
+            "and build this index in the platform UI." +
+            debugNote);
+    }
+    try {
+        await client.claude.pushWithUpdateSet({
+            update_set_sys_id: updateSetSysId,
+            table: "sys_dictionary",
+            record_sys_id: dictSysId,
+            fields: { unique: "true" },
+        });
+    }
+    catch (e) {
+        return finish(state, "failed", "The sys_dictionary patch FAILED, so nothing changed: " +
+            errorMessage(e) +
+            ". " +
+            resolved.name +
+            "." +
+            column +
+            " still read unique=false before the attempt; no index was created and no " +
+            "update-set entry was captured." +
+            debugNote);
+    }
+    // Read the flag back BY sys_id — the write returning 200 is not evidence the row
+    // changed, and it is certainly not evidence an index was built.
+    try {
+        var after = await client.table.query("sys_dictionary", "sys_id=" + (0, choices_1.encodeQueryValue)(dictSysId), { limit: 1, fields: ["sys_id", "element", "internal_type", "unique"] });
+        state.dictionaryUnique =
+            after.length > 0 ? isTrue((0, setField_1.fieldToString)(after[0].unique)) : false;
+    }
+    catch (e) {
+        state.dictionaryUnique = null;
+        return finish(state, "failed", "The sys_dictionary patch was accepted for " +
+            resolved.name +
+            "." +
+            column +
+            ", but re-reading the row failed, so nothing about this run is verified: " +
+            errorMessage(e) +
+            ". Check the column on the instance before relying on it." +
+            debugNote);
+    }
+    if (state.dictionaryUnique !== true) {
+        return finish(state, "failed", "The sys_dictionary patch was accepted for " +
+            resolved.name +
+            "." +
+            column +
+            ", but the row still does NOT read unique=true on read-back — the flag did not " +
+            "stick, so no index was built. Check the column (and the update set) on the " +
+            "instance." +
+            debugNote);
+    }
+    var readBack = await readIndexBack(client, resolved.name, [column]);
+    return verdict(state, readBack, true, resolved.name, column, " Captured into update set " + updateSetSysId + "." + debugNote);
+}

package/dist/table/index.d.ts

@@ -13,6 +13,8 @@ export { resolveFormAuth, openFormSession, setCurrentApplication, getRecordForm,
 export type { FormAuth, FormSession, HarvestedForm, PostResult, } from "./formSession";
 export { addColumn, deriveElement } from "./addColumn";
 export type { AddColumnParams, AddColumnResult } from "./addColumn";
+export { addIndex, scanForDuplicates, parseIndexColumns, indexMatchesColumns, } from "./addIndex";
+export type { AddIndexParams, AddIndexResult, AddIndexVerification, DuplicateScan, DuplicateValue, } from "./addIndex";
 export { setColumn, resolveAttributes, toStoredValue, findTruncationRisk, } from "./setColumn";
 export type { SetColumnParams, SetColumnResult, ColumnAttributes, AttributeChange, TruncationRisk, } from "./setColumn";
 export { OVERRIDABLE, LABEL_LANGUAGE, explainMaxLengthNotOverridable, resolveTableScope, findOverrideRow, findLabelRow, effectiveValue, diffInherited, applyInheritedWrites, overrideUpdateName, labelUpdateName, } from "./overrideColumn";

package/dist/table/index.js

@@ -5,7 +5,7 @@
  * live-validation caveat.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveTableAttributes = exports.setTable = exports.labelUpdateName = exports.overrideUpdateName = exports.applyInheritedWrites = exports.diffInherited = exports.effectiveValue = exports.findLabelRow = exports.findOverrideRow = exports.resolveTableScope = exports.explainMaxLengthNotOverridable = exports.LABEL_LANGUAGE = exports.OVERRIDABLE = exports.findTruncationRisk = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.deriveElement = exports.addColumn = exports.decodeHtmlEntities = exports.scrapeCk = exports.postForm = exports.parseFormInputs = exports.getNewRecordForm = exports.getRecordForm = exports.setCurrentApplication = exports.openFormSession = exports.resolveFormAuth = exports.TYPE_MAP = exports.listEditKey = exports.showInMenuKey = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.xmlEscape = exports.buildColumnXml = exports.DEFAULT_COLUMNS_REL_ID = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.parseSysIdFromLocation = exports.projectTableGraph = exports.createTable = void 0;
+exports.resolveTableAttributes = exports.setTable = exports.labelUpdateName = exports.overrideUpdateName = exports.applyInheritedWrites = exports.diffInherited = exports.effectiveValue = exports.findLabelRow = exports.findOverrideRow = exports.resolveTableScope = exports.explainMaxLengthNotOverridable = exports.LABEL_LANGUAGE = exports.OVERRIDABLE = exports.findTruncationRisk = exports.toStoredValue = exports.resolveAttributes = exports.setColumn = exports.indexMatchesColumns = exports.parseIndexColumns = exports.scanForDuplicates = exports.addIndex = exports.deriveElement = exports.addColumn = exports.decodeHtmlEntities = exports.scrapeCk = exports.postForm = exports.parseFormInputs = exports.getNewRecordForm = exports.getRecordForm = exports.setCurrentApplication = exports.openFormSession = exports.resolveFormAuth = exports.TYPE_MAP = exports.listEditKey = exports.showInMenuKey = exports.defaultAccessFlags = exports.applyTableSaveOverlay = exports.resolveType = exports.normalizeColumns = exports.xmlEscape = exports.buildColumnXml = exports.DEFAULT_COLUMNS_REL_ID = exports.DEFAULT_SAVE_ACTION = exports.DEFAULT_SUPER_CLASS = exports.parseSysIdFromLocation = exports.projectTableGraph = exports.createTable = void 0;
 var createTable_1 = require("./createTable");
 Object.defineProperty(exports, "createTable", { enumerable: true, get: function () { return createTable_1.createTable; } });
 Object.defineProperty(exports, "projectTableGraph", { enumerable: true, get: function () { return createTable_1.projectTableGraph; } });
@@ -37,6 +37,11 @@ Object.defineProperty(exports, "decodeHtmlEntities", { enumerable: true, get: fu
 var addColumn_1 = require("./addColumn");
 Object.defineProperty(exports, "addColumn", { enumerable: true, get: function () { return addColumn_1.addColumn; } });
 Object.defineProperty(exports, "deriveElement", { enumerable: true, get: function () { return addColumn_1.deriveElement; } });
+var addIndex_1 = require("./addIndex");
+Object.defineProperty(exports, "addIndex", { enumerable: true, get: function () { return addIndex_1.addIndex; } });
+Object.defineProperty(exports, "scanForDuplicates", { enumerable: true, get: function () { return addIndex_1.scanForDuplicates; } });
+Object.defineProperty(exports, "parseIndexColumns", { enumerable: true, get: function () { return addIndex_1.parseIndexColumns; } });
+Object.defineProperty(exports, "indexMatchesColumns", { enumerable: true, get: function () { return addIndex_1.indexMatchesColumns; } });
 var setColumn_1 = require("./setColumn");
 Object.defineProperty(exports, "setColumn", { enumerable: true, get: function () { return setColumn_1.setColumn; } });
 Object.defineProperty(exports, "resolveAttributes", { enumerable: true, get: function () { return setColumn_1.resolveAttributes; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "engines": {
     "node": ">=22"
   },