@lexq/cli 0.3.1 → 1.0.0

package/dist/index.js

@@ -72,6 +72,7 @@ var survivesDoubleRoundTrip = (literal) => isSafeNumber(literal);
 var parseNumber = (value) => survivesDoubleRoundTrip(value) ? parseFloat(value) : new LosslessNumber(value);
 var parseJson = (text) => losslessParse(text, void 0, parseNumber);
 var stringifyJson = (value, space) => losslessStringify(value, void 0, space);
+var isLosslessNumber = (value) => value instanceof LosslessNumber;
 
 // src/lib/api-client.ts
 var ApiError = class extends Error {
@@ -1338,7 +1339,7 @@ ${data.length} unregistered`);
       process.exit(1);
     }
   });
-  facts.command("create").description("Create a new fact definition").option("--key <key>", "Fact key (letters, numbers, underscores)").option("--name <n>", "Display name").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--description <desc>", "Description").option("--required", "Mark as required", false).option("--pii", "Mark as PII \u2014 value is masked on every read surface", false).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+  facts.command("create").description("Create a new fact definition").option("--key <key>", "Fact key (letters, numbers, underscores)").option("--name <n>", "Display name").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--description <desc>", "Description").option("--required", "Mark as required", false).option("--pii", "Mark as PII \u2014 value is masked on every read surface", false).option("--allowed-values <csv>", "Comma-separated list of accepted values").option("--min <number>", "Lower bound, inclusive (numeric types only)").option("--max <number>", "Upper bound, inclusive (numeric types only)").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent6`
 
@@ -1354,9 +1355,21 @@ ${data.length} unregistered`);
               "isRequired": false
             }'
 
+          $ lexq facts create --key riskScore --name "Risk Score" --type NUMBER --min 0 --max 100
+          $ lexq facts create --key tier --name "Tier" --type STRING \
+              --allowed-values "GOLD, SILVER, BRONZE"
+
         Value Types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
         Key Format:  starts with a letter, then letters, numbers, and underscores.
                      Casing is yours to choose (e.g., paymentAmount, payment_amount)
+
+        Value Domain: --allowed-values, --min, and --max say which values the fact accepts.
+                      A rule can then only compare against those values, and the console turns
+                      the rule editor into a dropdown instead of a free text box.
+                      STRING types take --allowed-values. NUMBER types take all three.
+                      BOOLEAN takes none — it has only two values to begin with.
+                      For list types the constraint applies to each element.
+                      Leave them out for no constraint, which is how facts behaved before.
       `
   ).action(async (opts) => {
     try {
@@ -1375,14 +1388,25 @@ ${data.length} unregistered`);
       process.exit(1);
     }
   });
-  facts.command("update").description("Update a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--name <n>", "Display name").option("--description <desc>", "Description").option("--required", "Mark as required").option("--no-required", "Mark as not required").option("--pii", "Mark as PII (enables masking)").option("--no-pii", "Unmark as PII (disables masking \u2014 value becomes visible)").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+  facts.command("update").description("Update a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--name <n>", "Display name").option("--description <desc>", "Description").option("--required", "Mark as required").option("--no-required", "Mark as not required").option("--pii", "Mark as PII (enables masking)").option("--no-pii", "Unmark as PII (disables masking \u2014 value becomes visible)").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--allowed-values <csv>", "Comma-separated list of accepted values").option("--min <number>", "Lower bound, inclusive (numeric types only)").option("--max <number>", "Upper bound, inclusive (numeric types only)").option("--clear-value-domain", "Remove the value constraint entirely").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent6`
 
-        System facts cannot be modified. Only display name, description, and required flag can be changed.
+        System facts accept name, description, and the PII flag only.
 
-        Example:
+        Examples:
           $ lexq facts update --id <factId> --name "Updated Name" --required
+          $ lexq facts update --id <factId> --min 0 --max 100
+          $ lexq facts update --id <factId> --clear-value-domain
+
+        Only the flags you pass are changed. Leaving out --allowed-values, --min, and --max
+        leaves the constraint alone; --clear-value-domain removes it.
+
+        Narrowing a constraint does not rewrite rules that already reference this fact. They keep
+        working, and the next time one is saved it is judged against the new constraint.
+
+        Pass --type when the accepted values are numbers and you are not also naming the type,
+        so "10" is sent as a number rather than a string. --json settles it either way.
       `
   ).action(async (opts) => {
     try {
@@ -1496,16 +1520,66 @@ function buildCreateBody2(opts) {
     isPii: opts.pii === true
   };
   if (opts.description) body.description = opts.description;
+  const domain = buildValueDomain(opts, opts.type);
+  if (domain) body.valueDomain = domain;
   return body;
 }
 function buildUpdateBody2(opts) {
   const body = {};
   if (opts.name) body.name = opts.name;
   if (opts.description !== void 0) body.description = opts.description;
+  if (opts.type) body.type = opts.type;
   if (typeof opts.required === "boolean") body.isRequired = opts.required;
   if (typeof opts.isPii === "boolean") body.isPii = opts.isPii;
+  if (opts.clearValueDomain === true) {
+    if (hasDomainFlag(opts)) {
+      throw new Error(
+        "--clear-value-domain cannot be combined with --allowed-values, --min, or --max."
+      );
+    }
+    body.valueDomain = {};
+    return body;
+  }
+  const domain = buildValueDomain(opts, opts.type);
+  if (domain) body.valueDomain = domain;
   return body;
 }
+function hasDomainFlag(opts) {
+  return opts.allowedValues !== void 0 || opts.min !== void 0 || opts.max !== void 0;
+}
+function parseNumericLiteral(text, flag) {
+  let parsed;
+  try {
+    parsed = parseJson(text);
+  } catch {
+    throw new Error(`${flag} must be a number, got: ${text}`);
+  }
+  if (typeof parsed !== "number" && !isLosslessNumber(parsed)) {
+    throw new Error(`${flag} must be a number, got: ${text}`);
+  }
+  return parsed;
+}
+function asDomainValue(text, numeric) {
+  if (numeric === true) return parseNumericLiteral(text, "--allowed-values");
+  if (numeric === false) return text;
+  try {
+    const parsed = parseJson(text);
+    return typeof parsed === "number" || isLosslessNumber(parsed) ? parsed : text;
+  } catch {
+    return text;
+  }
+}
+function buildValueDomain(opts, type) {
+  if (!hasDomainFlag(opts)) return void 0;
+  const numeric = type === void 0 ? void 0 : type === "NUMBER" || type === "LIST_NUMBER";
+  const domain = {};
+  if (opts.allowedValues !== void 0) {
+    domain.allowedValues = opts.allowedValues.split(",").map((part) => part.trim()).filter((part) => part.length > 0).map((part) => asDomainValue(part, numeric));
+  }
+  if (opts.min !== void 0) domain.min = parseNumericLiteral(opts.min, "--min");
+  if (opts.max !== void 0) domain.max = parseNumericLiteral(opts.max, "--max");
+  return domain;
+}
 
 // src/commands/deploy.ts
 import "commander";
@@ -3421,6 +3495,7 @@ function registerStatusTools(server, callApi) {
     "lexq_whoami",
     {
       title: "Who Am I",
+      annotations: { readOnlyHint: true },
       description: "Show current authentication info (tenant ID, user ID, role).",
       inputSchema: z.object({})
     },
@@ -3435,6 +3510,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_list",
     {
       title: "List Policy Groups",
+      annotations: { readOnlyHint: true },
       description: "List all policy groups (tenant-wide, priority ASC).",
       inputSchema: z2.object({})
     },
@@ -3444,6 +3520,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_get",
     {
       title: "Get Policy Group",
+      annotations: { readOnlyHint: true },
       description: "Get a single policy group by ID.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -3455,6 +3532,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_create",
     {
       title: "Create Policy Group",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Create a new policy group. Requires name. Priority is auto-assigned (appended last, tenant-wide); use lexq_groups_reorder to change order. Optionally set conflict resolution, activation group, and description. Policy groups that share an activationGroup form a cluster and must share the same activationMode / activationStrategy / executionLimit; executionLimit is how many of those groups run, not how many rules.",
       inputSchema: z2.object({
         name: z2.string().describe("Group name (unique among non-ARCHIVED)"),
@@ -3485,6 +3563,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_update",
     {
       title: "Update Policy Group",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
@@ -3507,6 +3586,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_delete",
     {
       title: "Delete Policy Group",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Archive a policy group. Only non-live groups can be deleted. This is irreversible.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -3518,6 +3598,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_reorder",
     {
       title: "Reorder Policy Groups",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Reorder policy groups by priority. Priority is tenant-wide and flat (1...N continuous); array index 0 = priority 1 (highest precedence). activationGroup is not affected \u2014 this only changes priority.",
       inputSchema: z2.object({
         groupIds: z2.array(z2.string().uuid()).describe("Group IDs in desired priority order (index 0 = priority 1)")
@@ -3535,6 +3616,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_start",
     {
       title: "Start A/B Test",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate. The split is computed from context.trafficKey on each execution request; requests that omit it never reach the challenger and the test stays at 0%.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
@@ -3548,6 +3630,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_stop",
     {
       title: "Stop A/B Test",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Stop a running A/B test. All traffic is restored to the control (current) version.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -3559,6 +3642,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_adjust",
     {
       title: "Adjust A/B Test",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Adjust traffic rate of a running A/B test.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
@@ -3576,6 +3660,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_list",
     {
       title: "List Policy Versions",
+      annotations: { readOnlyHint: true },
       description: "List all versions of a policy group.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3591,6 +3676,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_get",
     {
       title: "Get Policy Version",
+      annotations: { readOnlyHint: true },
       description: "Get a single version by ID, including its rules and fact requirements.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3603,6 +3689,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_create",
     {
       title: "Create Policy Version",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3617,6 +3704,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_update",
     {
       title: "Update Policy Version",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Update a DRAFT version. Only DRAFT versions can be modified. Only provided fields are changed.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3632,6 +3720,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_delete",
     {
       title: "Delete Policy Version",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Delete a DRAFT version. Only DRAFT versions can be deleted.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3644,6 +3733,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_clone",
     {
       title: "Clone Policy Version",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Clone an existing version to create a new DRAFT. Useful when the source version is already published.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -3666,6 +3756,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_list",
     {
       title: "List Rules",
+      annotations: { readOnlyHint: true },
       description: "List all rules in a version (priority ASC). Returns summary with conditionSummary and actionSummary.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3678,6 +3769,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_get",
     {
       title: "Get Rule Detail",
+      annotations: { readOnlyHint: true },
       description: "Get full rule detail including condition tree and action definitions.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3691,6 +3783,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_create",
     {
       title: "Create Rule",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: dedent15`
         Create a rule in a DRAFT version. Requires name, condition tree, and actions array. priority is auto-assigned (appended last); use lexq_rules_reorder to change order.
 
@@ -3769,6 +3862,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_update",
     {
       title: "Update Rule",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Update an existing rule in a DRAFT version. Only provided fields are changed.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3790,6 +3884,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_delete",
     {
       title: "Delete Rule",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Delete a rule from a DRAFT version.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3810,6 +3905,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_reorder",
     {
       title: "Reorder Rules",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Reorder rules by specifying rule IDs in desired order. Priorities are assigned 1...N (1-based, continuous); array index 0 = priority 1 (highest precedence).",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3831,6 +3927,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_toggle",
     {
       title: "Toggle Rule",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Enable or disable a rule without deleting it.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -3858,6 +3955,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_list",
     {
       title: "List Fact Definitions",
+      annotations: { readOnlyHint: true },
       description: "List all fact definitions (input variable schema). Shows key, type, required, and PII status. Always check this before creating rules.",
       inputSchema: z5.object({
         page: z5.number().int().min(0).default(0).describe("Page number"),
@@ -3875,6 +3973,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_create",
     {
       title: "Create Fact Definition",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Register a new input variable. Key starts with a letter, then letters, numbers, and underscores (e.g. paymentAmount). Casing is not enforced. Types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER.",
       inputSchema: z5.object({
         key: z5.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
@@ -3884,6 +3983,15 @@ function registerFactTools(server, callApi) {
         isRequired: z5.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
         isPii: z5.boolean().default(false).describe(
           "Mark as PII \u2014 masked on every read surface, revealable only in the console (audited)"
+        ),
+        valueDomain: z5.object({
+          allowedValues: z5.array(z5.union([z5.string(), z5.number()])).optional().describe(
+            "Accepted values. For list types the constraint applies to each element, not to the list as a whole."
+          ),
+          min: z5.number().optional().describe("Lower bound, inclusive. Numeric types only."),
+          max: z5.number().optional().describe("Upper bound, inclusive. Numeric types only.")
+        }).optional().describe(
+          "Which values this fact accepts. Omit for no constraint. STRING and LIST_STRING take allowedValues only; NUMBER and LIST_NUMBER take all three; BOOLEAN takes none. Declaring it lets the rule editor offer a dropdown and rejects a rule literal that could never match."
         )
       })
     },
@@ -3893,6 +4001,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Only the fields you send are changed. System facts accept name, description, and PII only.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID"),
@@ -3902,7 +4011,16 @@ function registerFactTools(server, callApi) {
           "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
         ),
         isRequired: z5.boolean().optional().describe("Required flag"),
-        isPii: z5.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)")
+        isPii: z5.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)"),
+        valueDomain: z5.object({
+          allowedValues: z5.array(z5.union([z5.string(), z5.number()])).optional().describe(
+            "Accepted values. For list types the constraint applies to each element, not to the list as a whole."
+          ),
+          min: z5.number().optional().describe("Lower bound, inclusive. Numeric types only."),
+          max: z5.number().optional().describe("Upper bound, inclusive. Numeric types only.")
+        }).optional().describe(
+          "Which values this fact accepts. Three states: omit the field to leave the constraint alone, send {} to remove it, or send a populated object to replace it. Narrowing it does not rewrite rules that already reference this fact \u2014 they keep working, and the next save is judged against the new constraint."
+        )
       })
     },
     async ({ factId, ...body }) => callApi("PUT", `schema/facts/${factId}`, { body })
@@ -3911,6 +4029,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Remove the references first.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID")
@@ -3922,6 +4041,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_action_metadata",
     {
       title: "Get Action Runtime Fact Metadata",
+      annotations: { readOnlyHint: true },
       description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. Facts are supplied as input or written by a prior action in the same rule; only SET_FACT creates a fact from nothing. Static data, safe to cache in-session.",
       inputSchema: z5.object({})
     },
@@ -3931,6 +4051,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_unregistered",
     {
       title: "List Unregistered Facts",
+      annotations: { readOnlyHint: true },
       description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy, INV-4). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
@@ -3943,6 +4064,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_export",
     {
       title: "Export Fact Catalog",
+      annotations: { readOnlyHint: true },
       description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
       inputSchema: z5.object({
         format: z5.enum(EXPORT_FORMATS).default("csv").describe("Export format"),
@@ -3962,6 +4084,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_publish",
     {
       title: "Publish Version",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -3975,6 +4098,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -3990,6 +4114,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_rollback",
     {
       title: "Rollback Deployment",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Rollback to the previous deployed version. Only available if there is a previous version.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -4004,6 +4129,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_undeploy",
     {
       title: "Undeploy",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Remove the live version from traffic. The version stays ACTIVE but no longer serves requests.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -4018,6 +4144,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_schedule",
     {
       title: "Schedule Deployment",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -4033,6 +4160,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_unschedule",
     {
       title: "Cancel Scheduled Deployment",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID")
@@ -4044,6 +4172,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_schedules",
     {
       title: "List Scheduled Deployments",
+      annotations: { readOnlyHint: true },
       description: "List scheduled deployments across all groups (all statuses: PENDING, EXECUTED, CANCELED, FAILED), newest first.",
       inputSchema: z6.object({
         page: z6.number().int().min(0).default(0).describe("Page number"),
@@ -4056,6 +4185,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_history",
     {
       title: "Deployment History",
+      annotations: { readOnlyHint: true },
       description: "List deployment history across all groups.",
       inputSchema: z6.object({
         page: z6.number().int().min(0).default(0).describe("Page number"),
@@ -4079,6 +4209,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_detail",
     {
       title: "Deployment Detail",
+      annotations: { readOnlyHint: true },
       description: "Get detailed info about a specific deployment including snapshot hash and integrity check.",
       inputSchema: z6.object({
         deploymentId: z6.string().uuid().describe("Deployment ID")
@@ -4090,6 +4221,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_overview",
     {
       title: "Deployment Overview",
+      annotations: { readOnlyHint: true },
       description: "Show current deployment status of all groups \u2014 which version is live, last deployment type, and deployer.",
       inputSchema: z6.object({})
     },
@@ -4099,6 +4231,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_deployable",
     {
       title: "List Deployable Versions",
+      annotations: { readOnlyHint: true },
       description: "List ACTIVE (published) versions that can be deployed for a group. Use this to find which versions are available before calling deploy live.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID")
@@ -4110,6 +4243,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_diff",
     {
       title: "Deployment Diff",
+      annotations: { readOnlyHint: true },
       description: "Compare rule snapshots between two versions. Shows added, removed, and modified rules. Useful for reviewing changes before deploying a new version.",
       inputSchema: z6.object({
         baseVersionId: z6.string().uuid().describe("Base version ID (typically the current live)"),
@@ -4130,6 +4264,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run",
     {
       title: "Dry Run",
+      annotations: { readOnlyHint: true },
       description: dedent16`
         Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
         
@@ -4159,6 +4294,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run_compare",
     {
       title: "Dry Run Compare",
+      annotations: { readOnlyHint: true },
       description: dedent16`
         Compare dry run results between two versions using the same input facts. Useful for validating changes.
         
@@ -4183,6 +4319,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_requirements",
     {
       title: "Analyze Requirements",
+      annotations: { readOnlyHint: true },
       description: "Analyze which input facts a version requires. Returns required keys, types, and an example request body.",
       inputSchema: z7.object({
         groupId: z7.string().uuid().describe("Policy group ID"),
@@ -4195,6 +4332,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_start",
     {
       title: "Start Simulation",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: dedent16`
         Start an Impact Simulation against historical, uploaded, or inline data.
 
@@ -4236,6 +4374,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_status",
     {
       title: "Simulation Status",
+      annotations: { readOnlyHint: true },
       description: "Get simulation status and results. Poll until status is COMPLETED or FAILED.",
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID")
@@ -4247,6 +4386,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_list",
     {
       title: "List Simulations",
+      annotations: { readOnlyHint: true },
       description: "List simulation history with optional filters.",
       inputSchema: z7.object({
         page: z7.number().int().min(0).default(0).describe("Page number"),
@@ -4268,6 +4408,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_cancel",
     {
       title: "Cancel Simulation",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Cancel a running or pending simulation.",
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID")
@@ -4279,6 +4420,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_export",
     {
       title: "Export Simulation",
+      annotations: { readOnlyHint: true },
       description: "Export simulation results as JSON or CSV. Returns the raw data.",
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID"),
@@ -4293,6 +4435,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dataset_upload",
     {
       title: "Upload Dataset",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: dedent16`
         Upload inline CSV or JSON content as a simulation dataset.
         The content is uploaded to S3 and a path is returned in the "path" field.
@@ -4336,6 +4479,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dataset_template",
     {
       title: "Download Dataset Template",
+      annotations: { readOnlyHint: true },
       description: "Generate a sample CSV or JSON template based on the required facts of a version. Use this to understand the expected data format before uploading a dataset.",
       inputSchema: z7.object({
         groupId: z7.string().uuid().describe("Policy group ID"),
@@ -4365,6 +4509,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_overview",
     {
       title: "Group Latency Profile",
+      annotations: { readOnlyHint: true },
       description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 6, p95 n \u2265 60, p99 n \u2265 300 \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a deterministic ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
@@ -4384,6 +4529,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_rule",
     {
       title: "Rule Latency Detail",
+      annotations: { readOnlyHint: true },
       description: `Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (${LATENCY_WINDOW_MILLIS / 1e3}s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 n \u2265 6, p95 n \u2265 60, p99 n \u2265 300). ` + RELATIVE_THRESHOLD,
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
@@ -4408,6 +4554,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_decision",
     {
       title: "Replay a Decision",
+      annotations: { readOnlyHint: true },
       description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
       inputSchema: z9.object({
         traceId: z9.string().describe("Trace ID of the past execution to replay"),
@@ -4420,6 +4567,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_start",
     {
       title: "Start Window Replay (Blast Radius)",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Submit an async job that replays a date window of past executions against a candidate version and measures the blast radius (how many decisions change). Billed per replayed record (REPLAY metric); VIEWER role cannot submit. Poll with lexq_replay_status.",
       inputSchema: z9.object({
         candidateVersionId: z9.string().uuid().describe("Version to re-evaluate against"),
@@ -4436,6 +4584,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_status",
     {
       title: "Get Replay Job Status",
+      annotations: { readOnlyHint: true },
       description: "Poll a window replay job. RUNNING shows progress 0\u2013100; COMPLETED fills summary and changedSamples; FAILED carries errorMessage. capped=true means the window exceeded the sample cap and only part was replayed.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID from lexq_replay_start")
@@ -4447,6 +4596,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_list",
     {
       title: "List Replay Jobs",
+      annotations: { readOnlyHint: true },
       description: "List window replay job history (reverse-chronological). Lightweight items \u2014 use lexq_replay_status for summary and changed samples.",
       inputSchema: z9.object({
         page: z9.number().int().min(0).default(0).describe("Page number"),
@@ -4459,6 +4609,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_cancel",
     {
       title: "Cancel Replay Job",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Cooperatively cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID")
@@ -4470,6 +4621,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_export",
     {
       title: "Export Replay Result",
+      annotations: { readOnlyHint: true },
       description: "Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID"),
@@ -4487,6 +4639,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_list",
     {
       title: "List Execution History",
+      annotations: { readOnlyHint: true },
       description: "List policy execution history. Shows trace ID, group, version, status, match result, and latency.",
       inputSchema: z10.object({
         page: z10.number().int().min(0).default(0).describe("Page number"),
@@ -4514,6 +4667,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_get",
     {
       title: "Get Execution Detail",
+      annotations: { readOnlyHint: true },
       description: "Get full execution detail including inputFacts, mutatedFacts, generatedVariables, executionTraces, and decisionTraces.",
       inputSchema: z10.object({
         traceId: z10.string().describe("Trace ID from execution history")
@@ -4525,6 +4679,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_stats",
     {
       title: "Execution Statistics",
+      annotations: { readOnlyHint: true },
       description: "Get execution KPIs: total executions, success/failure counts, success rate, and average latency.",
       inputSchema: z10.object({
         groupId: z10.string().uuid().optional().describe("Filter by policy group"),
@@ -4549,6 +4704,7 @@ function registerProvenanceTools(server, callApi) {
     "lexq_provenance_get",
     {
       title: "Get Decision Provenance",
+      annotations: { readOnlyHint: true },
       description: "Get the lineage of a single decision: what was decided, deterministic why per rule, input facts (PII facts are masked as \u2022\u2022\u2022\u2022\u2022\u2022 with maskedKeys listing them \u2014 values are revealable only in the console, audited), the authored/published/deployed responsibility chain, and the rule snapshot fingerprint.",
       inputSchema: z11.object({
         traceId: z11.string().describe("Trace ID of the execution")
@@ -4560,6 +4716,7 @@ function registerProvenanceTools(server, callApi) {
     "lexq_pii_reveals_list",
     {
       title: "List PII Reveal Audits",
+      annotations: { readOnlyHint: true },
       description: "List the PII reveal audit ledger \u2014 who revealed which fact of which trace, and when. Metadata only; revealed values are never stored or returned. Use for monthly access-log inspection and SIEM collection.",
       inputSchema: z11.object({
         page: z11.number().int().min(0).default(0).describe("Page number"),
@@ -4590,6 +4747,7 @@ function registerLogTools(server, callApi) {
     "lexq_logs_list",
     {
       title: "List Failure Logs",
+      annotations: { readOnlyHint: true },
       description: "List system failure logs from background tasks (platform event webhooks, scheduled deployments).",
       inputSchema: z12.object({
         page: z12.number().int().min(0).default(0).describe("Page number"),
@@ -4615,6 +4773,7 @@ function registerLogTools(server, callApi) {
     "lexq_logs_get",
     {
       title: "Get Failure Log",
+      annotations: { readOnlyHint: true },
       description: "Get failure log detail by ID.",
       inputSchema: z12.object({
         logId: z12.string().uuid().describe("Failure log ID")
@@ -4626,6 +4785,7 @@ function registerLogTools(server, callApi) {
     "lexq_logs_action",
     {
       title: "Process Failure Log",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Process a single failure log: RESOLVE (mark as manually fixed) or IGNORE (skip intentionally).",
       inputSchema: z12.object({
         logId: z12.string().uuid().describe("Failure log ID"),
@@ -4640,6 +4800,7 @@ function registerLogTools(server, callApi) {
     "lexq_logs_bulk_action",
     {
       title: "Bulk Process Failure Logs",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Process multiple failure logs at once. Provide an array of log IDs and the action.",
       inputSchema: z12.object({
         logIds: z12.array(z12.string().uuid()).describe("Array of failure log IDs"),
@@ -4659,6 +4820,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_list",
     {
       title: "List Webhook Subscriptions",
+      annotations: { readOnlyHint: true },
       description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications (publish, deploy, rollback, undeploy).",
       inputSchema: z13.object({
         page: z13.number().int().min(0).default(0).describe("Page number"),
@@ -4674,6 +4836,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_get",
     {
       title: "Get Webhook Subscription",
+      annotations: { readOnlyHint: true },
       description: "Get webhook subscription detail by ID.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -4685,6 +4848,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_save",
     {
       title: "Save Webhook Subscription",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: 'Create or update a webhook subscription. Omit id to create, provide id to update. Events: VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).',
       inputSchema: z13.object({
         id: z13.string().uuid().optional().describe("Subscription ID (omit to create, provide to update)"),
@@ -4702,6 +4866,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_delete",
     {
       title: "Delete Webhook Subscription",
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: "Delete a webhook subscription by ID.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -4713,6 +4878,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_test",
     {
       title: "Test Webhook Subscription",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Send a test event to verify webhook connectivity. Returns the HTTP status code and success/failure message.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -4729,6 +4895,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_list",
     {
       title: "List Domain Templates",
+      annotations: { readOnlyHint: true },
       description: "List all domain templates. A domain template is a curated, industry-specific starter pack of fact definitions and sample rules (e.g. ECOMMERCE). Each entry reports its key, status (ACTIVE or COMING_SOON), and a summary of what it provisions. Call this before preview or apply to discover which templates can currently be applied.",
       inputSchema: z14.object({})
     },
@@ -4738,6 +4905,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_preview",
     {
       title: "Preview Domain Template",
+      annotations: { readOnlyHint: true },
       description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers, the sample rules it creates, and an apply plan. This is a read-only dry run \u2014 nothing is created. Only ACTIVE templates can be previewed.",
       inputSchema: z14.object({
         template: z14.string().describe(
@@ -4751,6 +4919,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_apply",
     {
       title: "Apply Domain Template",
+      annotations: { readOnlyHint: false, destructiveHint: false },
       description: "Apply a domain template to the current tenant. Creates the template's fact definitions and a new policy group pre-populated with its sample rules as a DRAFT version. Existing facts are skipped \u2014 apply is additive and never overwrites existing schema. Run lexq_domain_templates_preview first to review what will be created. Only ACTIVE templates can be applied.",
       inputSchema: z14.object({
         template: z14.string().describe("Domain template key to apply (e.g. ECOMMERCE)."),