@hotmeshio/long-tail 0.16.2 → 0.17.0

package/build/services/user/crud.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPropertyValidationError = exports.UserPropertyConflictError = void 0;
 exports.attachRoles = attachRoles;
 exports.createUser = createUser;
 exports.getUser = getUser;
@@ -10,11 +11,15 @@ exports.getUserByExternalId = getUserByExternalId;
 exports.getUserByEmail = getUserByEmail;
 exports.getUserByMetadataValue = getUserByMetadataValue;
 exports.updateUser = updateUser;
+exports.getIdentityPropertyKeys = getIdentityPropertyKeys;
+exports.patchUserProperties = patchUserProperties;
 exports.deleteUser = deleteUser;
 exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scan_code_1 = require("../scan-code");
+const scan_code_2 = require("../../types/scan-code");
 const scope_1 = require("./scope");
 // ─── Private helpers (exported for internal use by auth.ts) ──────────────────
 async function attachRoles(user) {
@@ -143,6 +148,109 @@ async function updateUser(id, input) {
         return null;
     return attachRoles(rows[0]);
 }
+/** A property write that would create an ambiguous identity binding. */
+class UserPropertyConflictError extends Error {
+    constructor(key) {
+        super(`"${key}" value is already bound to another active user`);
+        this.status = 409;
+        this.name = 'UserPropertyConflictError';
+    }
+}
+exports.UserPropertyConflictError = UserPropertyConflictError;
+/** A malformed property patch — rejected before any write. */
+class UserPropertyValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.status = 400;
+        this.name = 'UserPropertyValidationError';
+    }
+}
+exports.UserPropertyValidationError = UserPropertyValidationError;
+/**
+ * The lt_users.metadata keys the platform itself resolves identities against:
+ * every enabled identity scan scheme's target_facet (e.g. badge_id). Writes
+ * to these keys carry a uniqueness guard; the dashboard marks them as system
+ * properties.
+ */
+async function getIdentityPropertyKeys() {
+    const schemes = await (0, scan_code_1.listScanSchemes)();
+    return [...new Set(schemes
+            .filter((s) => s.enabled && s.kind === scan_code_2.SCAN_SCHEME_KINDS.IDENTITY)
+            .map((s) => s.target_facet))];
+}
+/**
+ * Atomic per-key patch of the user's properties dictionary (lt_users.metadata).
+ * One statement — never read-merge-write: concurrent patches of different
+ * keys both land, a rename never opens a key-absent window, and deleting is
+ * explicit (`remove`) — an absent key means keep. Precedence on collision:
+ * set > rename > existing. Values are raw JSON, so numbers/booleans/objects
+ * round-trip typed.
+ *
+ * Identity-binding keys (getIdentityPropertyKeys) additionally assert, in the
+ * same statement, that no OTHER active user carries the value — the
+ * write-side counterpart of getUserByMetadataValue's ambiguity throw.
+ * A tripped guard raises UserPropertyConflictError (409).
+ */
+async function patchUserProperties(id, ops) {
+    const set = ops.set ?? {};
+    const remove = ops.remove ?? [];
+    const rename = ops.rename ?? {};
+    const setKeys = Object.keys(set);
+    const renameEntries = Object.entries(rename);
+    if (setKeys.length === 0 && remove.length === 0 && renameEntries.length === 0) {
+        throw new UserPropertyValidationError('A property patch requires at least one set, remove, or rename');
+    }
+    for (const key of [...setKeys, ...remove, ...renameEntries.flat()]) {
+        if (typeof key !== 'string' || key.trim().length === 0) {
+            throw new UserPropertyValidationError('Property keys must be non-empty strings');
+        }
+    }
+    for (const key of setKeys) {
+        if (remove.includes(key)) {
+            throw new UserPropertyValidationError(`"${key}" cannot be both set and removed in one patch`);
+        }
+    }
+    for (const [prev, next] of renameEntries) {
+        if (prev === next) {
+            throw new UserPropertyValidationError(`Renaming "${prev}" to itself is not a change`);
+        }
+    }
+    const renameTargets = renameEntries.map(([, next]) => next);
+    if (new Set(renameTargets).size !== renameTargets.length) {
+        throw new UserPropertyValidationError('Two properties cannot be renamed to the same key');
+    }
+    // Identity bindings resolve people — their values must be scalar and, for
+    // ACTIVE users, unique. The guard rides the same statement.
+    const identityKeys = await getIdentityPropertyKeys();
+    const guard = {};
+    for (const key of identityKeys) {
+        if (key in set) {
+            const value = set[key];
+            if (typeof value !== 'string' && typeof value !== 'number') {
+                throw new UserPropertyValidationError(`"${key}" is an identity binding — its value must be a string or number`);
+            }
+            guard[key] = String(value);
+        }
+    }
+    const removeAll = [...new Set([...remove, ...renameEntries.map(([prev]) => prev)])];
+    const renamePairs = renameEntries.map(([prev, next]) => ({ prev, next }));
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.PATCH_USER_PROPERTIES, [
+        id,
+        removeAll,
+        JSON.stringify(renamePairs),
+        JSON.stringify(set),
+        JSON.stringify(guard),
+    ]);
+    if (rows[0])
+        return attachRoles(rows[0]);
+    const exists = await pool.query(sql_1.VERIFY_USER_BY_ID, [id]);
+    if (!exists.rows[0])
+        return null;
+    // The user exists, so the identity guard is what blocked the write. Name
+    // the first guarded key for the caller; the row was not touched.
+    throw new UserPropertyConflictError(Object.keys(guard)[0] ?? 'identity binding');
+}
 async function deleteUser(id) {
     const pool = (0, db_1.getPool)();
     const { rowCount } = await pool.query(sql_1.DELETE_USER_BY_ID, [id]);

package/build/services/user/index.d.ts

@@ -1,5 +1,5 @@
-export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
-export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, deleteUser, listUsers, } from './crud';
+export { CreateUserInput, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
+export { createUser, getUser, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, grantRoleIfAbsent, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -10,6 +10,10 @@ Object.defineProperty(exports, "getUserByExternalId", { enumerable: true, get: f
 Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: function () { return crud_1.getUserByEmail; } });
 Object.defineProperty(exports, "getUserByMetadataValue", { enumerable: true, get: function () { return crud_1.getUserByMetadataValue; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
+Object.defineProperty(exports, "patchUserProperties", { enumerable: true, get: function () { return crud_1.patchUserProperties; } });
+Object.defineProperty(exports, "getIdentityPropertyKeys", { enumerable: true, get: function () { return crud_1.getIdentityPropertyKeys; } });
+Object.defineProperty(exports, "UserPropertyConflictError", { enumerable: true, get: function () { return crud_1.UserPropertyConflictError; } });
+Object.defineProperty(exports, "UserPropertyValidationError", { enumerable: true, get: function () { return crud_1.UserPropertyValidationError; } });
 Object.defineProperty(exports, "deleteUser", { enumerable: true, get: function () { return crud_1.deleteUser; } });
 Object.defineProperty(exports, "listUsers", { enumerable: true, get: function () { return crud_1.listUsers; } });
 var roles_1 = require("./roles");

package/build/services/user/sql.d.ts

@@ -28,6 +28,22 @@ export declare const GET_USER_BY_ID = "SELECT * FROM lt_users WHERE id = $1";
 export declare const GET_USERS_BY_METADATA_VALUE = "SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2";
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
+/**
+ * Atomic per-key patch of the user's properties dictionary — ONE statement,
+ * never read-merge-write. Composition (later wins on key collision):
+ *
+ *   base minus ($2: removed keys ∪ rename old-names)
+ *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
+ *      the source key is absent)
+ *   || sets ($4: typed JSON values)
+ *
+ * $5 is the identity-binding guard: {key: value} pairs that must not already
+ * belong to ANOTHER active user (the write-side counterpart of the
+ * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
+ * back means the user is missing OR the guard tripped — the caller
+ * distinguishes with VERIFY_USER_BY_ID.
+ */
+export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";

package/build/services/user/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 /** Fetch roles for a single user, ordered by creation time. granted_by_persona
@@ -50,6 +50,38 @@ exports.GET_USER_BY_ID = 'SELECT * FROM lt_users WHERE id = $1';
 exports.GET_USERS_BY_METADATA_VALUE = `SELECT * FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2`;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
+/**
+ * Atomic per-key patch of the user's properties dictionary — ONE statement,
+ * never read-merge-write. Composition (later wins on key collision):
+ *
+ *   base minus ($2: removed keys ∪ rename old-names)
+ *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
+ *      the source key is absent)
+ *   || sets ($4: typed JSON values)
+ *
+ * $5 is the identity-binding guard: {key: value} pairs that must not already
+ * belong to ANOTHER active user (the write-side counterpart of the
+ * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
+ * back means the user is missing OR the guard tripped — the caller
+ * distinguishes with VERIFY_USER_BY_ID.
+ */
+exports.PATCH_USER_PROPERTIES = `
+  UPDATE lt_users SET metadata = (
+    (COALESCE(metadata, '{}'::jsonb) - $2::text[])
+    || COALESCE((
+      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)
+      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)
+      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev
+    ), '{}'::jsonb)
+    || $4::jsonb
+  )
+  WHERE id = $1
+    AND NOT EXISTS (
+      SELECT 1
+      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)
+      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v
+    )
+  RETURNING *`;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
           r.role, r.type AS role_type, r.read_scope, r.write_scope

package/build/services/user/types.d.ts

@@ -24,5 +24,16 @@ export interface UpdateUserInput {
     display_name?: string;
     password?: string;
     status?: LTUserStatus;
+    /** Wholesale REPLACE of the properties dictionary — for per-key edits use patchUserProperties. */
     metadata?: Record<string, any>;
 }
+/**
+ * One atomic patch of the user's properties dictionary. Deleting is explicit
+ * (`remove`) — a key absent from the patch is kept. `rename` preserves the
+ * value. Precedence on collision: set > rename > existing.
+ */
+export interface UserPropertyOps {
+    set?: Record<string, unknown>;
+    remove?: string[];
+    rename?: Record<string, string>;
+}

package/build/shared/form-validation/field-validator.d.ts

@@ -8,13 +8,15 @@ interface ChecklistItem {
     required?: boolean;
 }
 /**
- * Resolve a checklist widget's item definitions from its `x-lt-source`
- * "domain.path" against the escalation context. Paths may embed
- * `{{domain.path}}` interpolation segments (cascading sources). Missing
- * domain/path, an unresolved segment, or a non-array value yields an empty
- * list.
+ * Resolve a checklist widget's item definitions from its `x-lt-source` —
+ * a "domain.path" or an ORDERED array of paths — against the escalation
+ * context. With an array, the first entry that resolves to a non-empty item
+ * list wins, so lookup-backed and envelope-embedded rows render the same
+ * shared schema interchangeably. Paths may embed `{{domain.path}}`
+ * interpolation segments (cascading sources); an entry that cannot resolve
+ * falls through to the next. Nothing resolvable yields an empty list.
  */
-export declare function resolveChecklistItems(sourcePath: unknown, ctx: Record<string, unknown> | undefined): ChecklistItem[];
+export declare function resolveChecklistItems(source: unknown, ctx: Record<string, unknown> | undefined): ChecklistItem[];
 export declare const X_LT_DEFAULT_CHECKED = "x-lt-default-checked";
 /**
  * The checklist's first-load default (`x-lt-default-checked`): every resolved

package/build/shared/form-validation/field-validator.js

@@ -10,24 +10,32 @@ exports.validateField = validateField;
 const x_lt_options_1 = require("./x-lt-options");
 const ctx_path_1 = require("./ctx-path");
 /**
- * Resolve a checklist widget's item definitions from its `x-lt-source`
- * "domain.path" against the escalation context. Paths may embed
- * `{{domain.path}}` interpolation segments (cascading sources). Missing
- * domain/path, an unresolved segment, or a non-array value yields an empty
- * list.
+ * Resolve a checklist widget's item definitions from its `x-lt-source` —
+ * a "domain.path" or an ORDERED array of paths — against the escalation
+ * context. With an array, the first entry that resolves to a non-empty item
+ * list wins, so lookup-backed and envelope-embedded rows render the same
+ * shared schema interchangeably. Paths may embed `{{domain.path}}`
+ * interpolation segments (cascading sources); an entry that cannot resolve
+ * falls through to the next. Nothing resolvable yields an empty list.
  */
-function resolveChecklistItems(sourcePath, ctx) {
-    if (typeof sourcePath !== 'string' || !ctx)
+function resolveChecklistItems(source, ctx) {
+    const paths = (typeof source === 'string' ? [source] : Array.isArray(source) ? source : [])
+        .filter((p) => typeof p === 'string' && p.length > 0);
+    if (paths.length === 0 || !ctx)
         return [];
-    let concrete = sourcePath;
-    if ((0, ctx_path_1.hasInterpolation)(sourcePath)) {
-        const resolved = (0, ctx_path_1.interpolatePath)(sourcePath, ctx);
-        if (resolved === null)
-            return [];
-        concrete = resolved;
+    for (const sourcePath of paths) {
+        let concrete = sourcePath;
+        if ((0, ctx_path_1.hasInterpolation)(sourcePath)) {
+            const resolved = (0, ctx_path_1.interpolatePath)(sourcePath, ctx);
+            if (resolved === null)
+                continue;
+            concrete = resolved;
+        }
+        const cur = (0, ctx_path_1.resolveCtxPath)(concrete, ctx);
+        if (Array.isArray(cur) && cur.length > 0)
+            return cur;
     }
-    const cur = (0, ctx_path_1.resolveCtxPath)(concrete, ctx);
-    return Array.isArray(cur) ? cur : [];
+    return [];
 }
 exports.X_LT_DEFAULT_CHECKED = 'x-lt-default-checked';
 /**

package/build/shared/form-validation/x-lt-options.js

@@ -10,10 +10,18 @@ exports.resolveFieldOptions = resolveFieldOptions;
  * offer a different legal set per escalation (e.g. `[1..N]` where N rides the
  * envelope, or a versioned knowledge lookup under the `lookup` domain).
  *
- *   x-lt-options   "domain.path" — e.g. "envelope.left_quantity_options"
- *                  paths may embed {{domain.path}} interpolation segments —
+ *   x-lt-options   "domain.path" or an ORDERED array of paths — e.g.
+ *                  "envelope.left_quantity_options" or
+ *                  ["lookup.reasons.items", "envelope.reject_reason_items"].
+ *                  With an array, the first entry that resolves to options
+ *                  wins, so lookup-backed and envelope-embedded rows render
+ *                  the same shared schema interchangeably (a parked row
+ *                  falls through to the envelope it already carries).
+ *                  Paths may embed {{domain.path}} interpolation segments —
  *                  e.g. "lookup.geo.regions.{{resolver.country}}" — making
- *                  the option list follow another answer (cascading selects)
+ *                  the option list follow another answer (cascading selects);
+ *                  an entry whose interpolation cannot resolve falls through
+ *                  to the next entry.
  *
  * Object entries separate what the submitter SEES from what the payload
  * STORES: the select renders the label and emits the value (a DB-backed pick
@@ -62,24 +70,30 @@ function resolveFieldOptions(fieldSchema, ctx) {
     if (Array.isArray(staticEnum) && staticEnum.length > 0) {
         return staticEnum.map((v) => ({ value: v, label: String(v) }));
     }
-    const sourcePath = fieldSchema[exports.X_LT_OPTIONS];
-    if (typeof sourcePath !== 'string')
+    const token = fieldSchema[exports.X_LT_OPTIONS];
+    const paths = (typeof token === 'string' ? [token] : Array.isArray(token) ? token : [])
+        .filter((p) => typeof p === 'string' && p.length > 0);
+    if (paths.length === 0)
         return undefined;
-    // Interpolated tokens are a standing contract: even unresolvable, the field
-    // stays a (disabled) select and fails closed. Plain paths keep the legacy
-    // undefined-on-miss reading.
-    const dynamic = (0, ctx_path_1.hasInterpolation)(sourcePath);
-    const miss = dynamic ? [] : undefined;
-    let concrete = sourcePath;
-    if (dynamic) {
-        const resolved = (0, ctx_path_1.interpolatePath)(sourcePath, ctx);
-        if (resolved === null)
-            return miss;
-        concrete = resolved;
+    // Interpolated entries are a standing contract: when nothing resolves, the
+    // field stays a (disabled) select and fails closed — a cascade child never
+    // becomes free text. All-plain-path tokens keep the legacy undefined-on-miss
+    // reading (the field falls back to its typed plain input).
+    const miss = paths.some(ctx_path_1.hasInterpolation) ? [] : undefined;
+    for (const sourcePath of paths) {
+        let concrete = sourcePath;
+        if ((0, ctx_path_1.hasInterpolation)(sourcePath)) {
+            const resolved = (0, ctx_path_1.interpolatePath)(sourcePath, ctx);
+            if (resolved === null)
+                continue;
+            concrete = resolved;
+        }
+        const cur = (0, ctx_path_1.resolveCtxPath)(concrete, ctx);
+        if (!Array.isArray(cur))
+            continue;
+        const options = cur.map(toOption).filter((o) => o !== null);
+        if (options.length > 0)
+            return options;
     }
-    const cur = (0, ctx_path_1.resolveCtxPath)(concrete, ctx);
-    if (!Array.isArray(cur))
-        return miss;
-    const options = cur.map(toOption).filter((o) => o !== null);
-    return options.length > 0 ? options : miss;
+    return miss;
 }

package/build/system/mcp-servers/admin/exports.js

@@ -89,6 +89,21 @@ function registerExportTools(server) {
         }
         return { content: [{ type: 'text', text: JSON.stringify((0, pick_1.pickPaths)(result.data, args.select)) }] };
     });
+    // mirrors GET /api/workflow-states/:workflowId/envelopes
+    server.registerTool('get_workflow_envelopes', {
+        title: 'Get Workflow Envelopes',
+        description: 'The workflow\'s input and output envelopes — two narrow lookups, no event ' +
+            'stream. Output is null with status running until the workflow completes; a ' +
+            'failed run carries its error message. The token-cheap read when you only ' +
+            'need what went in and what came out.',
+        inputSchema: schemas_1.getWorkflowEnvelopesSchema,
+    }, async (args) => {
+        const result = await api.getWorkflowEnvelopes({ workflowId: args.workflow_id });
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors GET /api/workflow-states/:workflowId/status
     server.registerTool('get_export_status', {
         title: 'Get Workflow Status',

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -555,6 +555,22 @@ export declare const removeUserRoleSchema: z.ZodObject<{
     role: string;
     user_id: string;
 }>;
+export declare const patchUserPropertiesSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    remove: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    rename: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+    set?: Record<string, any> | undefined;
+    remove?: string[] | undefined;
+    rename?: Record<string, string> | undefined;
+}, {
+    user_id: string;
+    set?: Record<string, any> | undefined;
+    remove?: string[] | undefined;
+    rename?: Record<string, string> | undefined;
+}>;
 export declare const listRolesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export declare const createRoleSchema: z.ZodObject<{
     role: z.ZodString;
@@ -1420,6 +1436,13 @@ export declare const getExportStatusSchema: z.ZodObject<{
 }, {
     workflow_id: string;
 }>;
+export declare const getWorkflowEnvelopesSchema: z.ZodObject<{
+    workflow_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    workflow_id: string;
+}, {
+    workflow_id: string;
+}>;
 export declare const diagnoseJobSchema: z.ZodObject<{
     workflow_id: z.ZodString;
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -1803,17 +1826,17 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
             to: string;
         }>;
     }, "strip", z.ZodTypeAny, {
+        kind: "dwell";
         window: {
             from: string;
             to: string;
         };
-        kind: "dwell";
     }, {
+        kind: "dwell";
         window: {
             from: string;
             to: string;
         };
-        kind: "dwell";
     }>]>;
     distinctBy: z.ZodOptional<z.ZodString>;
     states: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1894,11 +1917,11 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
         kind: "membership";
         asOf?: string | undefined;
     } | {
+        kind: "dwell";
         window: {
             from: string;
             to: string;
         };
-        kind: "dwell";
     };
     limit?: number | undefined;
     offset?: number | undefined;
@@ -1943,11 +1966,11 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
         kind: "membership";
         asOf?: string | undefined;
     } | {
+        kind: "dwell";
         window: {
             from: string;
             to: string;
         };
-        kind: "dwell";
     };
     limit?: number | undefined;
     offset?: number | undefined;
@@ -2174,9 +2197,9 @@ export declare const upsertScanSchemeSchema: z.ZodObject<{
     description?: string | undefined;
     enabled?: boolean | undefined;
     encoding?: "fixed" | "delimited" | undefined;
-    kind?: "action" | "identity" | undefined;
     delimiter?: string | undefined;
     target_length?: number | undefined;
+    kind?: "action" | "identity" | undefined;
     grant_ttl_seconds?: number | undefined;
     grant_max_uses?: number | undefined;
 }, {
@@ -2186,9 +2209,9 @@ export declare const upsertScanSchemeSchema: z.ZodObject<{
     description?: string | undefined;
     enabled?: boolean | undefined;
     encoding?: "fixed" | "delimited" | undefined;
-    kind?: "action" | "identity" | undefined;
     delimiter?: string | undefined;
     target_length?: number | undefined;
+    kind?: "action" | "identity" | undefined;
     grant_ttl_seconds?: number | undefined;
     grant_max_uses?: number | undefined;
 }>;
@@ -2408,21 +2431,21 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
         markdown: z.ZodOptional<z.ZodString>;
         route: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        route?: string | undefined;
         markdown?: string | undefined;
-    }, {
         route?: string | undefined;
+    }, {
         markdown?: string | undefined;
+        route?: string | undefined;
     }>>;
     notPrimed: z.ZodOptional<z.ZodObject<{
         markdown: z.ZodOptional<z.ZodString>;
         route: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        route?: string | undefined;
         markdown?: string | undefined;
-    }, {
         route?: string | undefined;
+    }, {
         markdown?: string | undefined;
+        route?: string | undefined;
     }>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -2473,12 +2496,12 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
     }[];
     enabled?: boolean | undefined;
     fallback?: {
-        route?: string | undefined;
         markdown?: string | undefined;
+        route?: string | undefined;
     } | undefined;
     notPrimed?: {
-        route?: string | undefined;
         markdown?: string | undefined;
+        route?: string | undefined;
     } | undefined;
 }, {
     name: string;
@@ -2528,12 +2551,12 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
     }[];
     enabled?: boolean | undefined;
     fallback?: {
-        route?: string | undefined;
         markdown?: string | undefined;
+        route?: string | undefined;
     } | undefined;
     notPrimed?: {
-        route?: string | undefined;
         markdown?: string | undefined;
+        route?: string | undefined;
     } | undefined;
 }>;
 export declare const deleteScanRuleSchema: z.ZodObject<{

package/build/system/mcp-servers/admin/schemas.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assignPersonaSchema = exports.unlinkPersonaRoleSchema = exports.linkPersonaRoleSchema = exports.deletePersonaSchema = exports.updatePersonaSchema = exports.createPersonaSchema = exports.getPersonaSchema = exports.listPersonasSchema = exports.listRoleSchemaVersionsSchema = exports.getRoleSchemaSchema = exports.updateRoleSchema = exports.addEscalationChainSchema = exports.createRoleSchema = exports.listRolesSchema = exports.removeUserRoleSchema = exports.addUserRoleSchema = exports.createUserSchema = exports.listUsersSchema = exports.invokeYamlWorkflowSchema = exports.deployYamlWorkflowSchema = exports.createYamlWorkflowSchema = exports.getYamlWorkflowSchema = exports.listYamlWorkflowsSchema = exports.disconnectMcpServerSchema = exports.connectMcpServerSchema = exports.updateMcpServerSchema = exports.listMcpServersSchema = exports.getDomainContextSchema = exports.terminateWorkflowSchema = exports.getWorkflowStatusSchema = exports.invokeWorkflowSchema = exports.listDiscoveredWorkflowsSchema = exports.deleteWorkflowConfigSchema = exports.upsertWorkflowConfigSchema = exports.listWorkflowConfigsSchema = exports.bulkTriageSchema = exports.releaseExpiredClaimsSchema = exports.bulkCancelSchema = exports.cancelEscalationSchema = exports.escalateEscalationSchema = exports.resolveBySignalKeySchema = exports.resolveEscalationSchema = exports.releaseEscalationSchema = exports.claimEscalationSchema = exports.getEscalationStatsSchema = exports.getEscalationsByWorkflowSchema = exports.getEscalationSchema = exports.findEscalationsSchema = exports.getProcessDetailSchema = exports.findTasksSchema = void 0;
-exports.resolveByIdsSchema = exports.facetQuerySchema = exports.findOrphanedSignalsSchema = exports.findStalledJobsSchema = exports.diagnoseJobSchema = exports.getExportStatusSchema = exports.exportWorkflowExecutionSchema = exports.exportWorkflowStateSchema = exports.listExportJobsSchema = exports.getSettingsSchema = exports.updatePrioritySchema = exports.bulkEscalateSchema = exports.bulkUnassignSchema = exports.bulkAssignSchema = exports.bulkClaimSchema = exports.resolveByMetadataSchema = exports.claimByMetadataSchema = exports.findByMetadataSchema = exports.deleteTopicSchema = exports.updateTopicSchema = exports.createTopicSchema = exports.getTopicSchema = exports.listTopicsSchema = exports.interruptJobSchema = exports.getJobExecutionSchema = exports.listPipelineJobsSchema = exports.listPipelineEntitiesSchema = exports.listStreamMessagesSchema = exports.getStreamStatsSchema = exports.applyThrottleSchema = exports.rollCallSchema = exports.listAppsSchema = exports.revokeBotKeySchema = exports.createBotApiKeySchema = exports.deleteBotSchema = exports.updateBotSchema = exports.createBotSchema = exports.getBotSchema = exports.listBotsSchema = exports.deleteAgentSubscriptionSchema = exports.createAgentSubscriptionSchema = exports.listAgentSubscriptionsSchema = exports.deleteAgentSchema = exports.updateAgentSchema = exports.createAgentSchema = exports.getAgentSchema = exports.listAgentsSchema = exports.pruneSchema = exports.getUserPersonasSchema = exports.unassignPersonaSchema = void 0;
-exports.deleteScanRuleSchema = exports.upsertScanRuleSchema = exports.upsertScanSchemeSchema = exports.listScanSchemesSchema = exports.executeScanChoiceSchema = exports.executeScanCodeSchema = exports.timelineByFacetSchema = exports.aggregateByFacetsSchema = exports.claimByFacetsSchema = exports.claimGroupsSchema = exports.searchByFacetsSchema = void 0;
+exports.unlinkPersonaRoleSchema = exports.linkPersonaRoleSchema = exports.deletePersonaSchema = exports.updatePersonaSchema = exports.createPersonaSchema = exports.getPersonaSchema = exports.listPersonasSchema = exports.listRoleSchemaVersionsSchema = exports.getRoleSchemaSchema = exports.updateRoleSchema = exports.addEscalationChainSchema = exports.createRoleSchema = exports.listRolesSchema = exports.patchUserPropertiesSchema = exports.removeUserRoleSchema = exports.addUserRoleSchema = exports.createUserSchema = exports.listUsersSchema = exports.invokeYamlWorkflowSchema = exports.deployYamlWorkflowSchema = exports.createYamlWorkflowSchema = exports.getYamlWorkflowSchema = exports.listYamlWorkflowsSchema = exports.disconnectMcpServerSchema = exports.connectMcpServerSchema = exports.updateMcpServerSchema = exports.listMcpServersSchema = exports.getDomainContextSchema = exports.terminateWorkflowSchema = exports.getWorkflowStatusSchema = exports.invokeWorkflowSchema = exports.listDiscoveredWorkflowsSchema = exports.deleteWorkflowConfigSchema = exports.upsertWorkflowConfigSchema = exports.listWorkflowConfigsSchema = exports.bulkTriageSchema = exports.releaseExpiredClaimsSchema = exports.bulkCancelSchema = exports.cancelEscalationSchema = exports.escalateEscalationSchema = exports.resolveBySignalKeySchema = exports.resolveEscalationSchema = exports.releaseEscalationSchema = exports.claimEscalationSchema = exports.getEscalationStatsSchema = exports.getEscalationsByWorkflowSchema = exports.getEscalationSchema = exports.findEscalationsSchema = exports.getProcessDetailSchema = exports.findTasksSchema = void 0;
+exports.findOrphanedSignalsSchema = exports.findStalledJobsSchema = exports.diagnoseJobSchema = exports.getWorkflowEnvelopesSchema = exports.getExportStatusSchema = exports.exportWorkflowExecutionSchema = exports.exportWorkflowStateSchema = exports.listExportJobsSchema = exports.getSettingsSchema = exports.updatePrioritySchema = exports.bulkEscalateSchema = exports.bulkUnassignSchema = exports.bulkAssignSchema = exports.bulkClaimSchema = exports.resolveByMetadataSchema = exports.claimByMetadataSchema = exports.findByMetadataSchema = exports.deleteTopicSchema = exports.updateTopicSchema = exports.createTopicSchema = exports.getTopicSchema = exports.listTopicsSchema = exports.interruptJobSchema = exports.getJobExecutionSchema = exports.listPipelineJobsSchema = exports.listPipelineEntitiesSchema = exports.listStreamMessagesSchema = exports.getStreamStatsSchema = exports.applyThrottleSchema = exports.rollCallSchema = exports.listAppsSchema = exports.revokeBotKeySchema = exports.createBotApiKeySchema = exports.deleteBotSchema = exports.updateBotSchema = exports.createBotSchema = exports.getBotSchema = exports.listBotsSchema = exports.deleteAgentSubscriptionSchema = exports.createAgentSubscriptionSchema = exports.listAgentSubscriptionsSchema = exports.deleteAgentSchema = exports.updateAgentSchema = exports.createAgentSchema = exports.getAgentSchema = exports.listAgentsSchema = exports.pruneSchema = exports.getUserPersonasSchema = exports.unassignPersonaSchema = exports.assignPersonaSchema = void 0;
+exports.deleteScanRuleSchema = exports.upsertScanRuleSchema = exports.upsertScanSchemeSchema = exports.listScanSchemesSchema = exports.executeScanChoiceSchema = exports.executeScanCodeSchema = exports.timelineByFacetSchema = exports.aggregateByFacetsSchema = exports.claimByFacetsSchema = exports.claimGroupsSchema = exports.searchByFacetsSchema = exports.resolveByIdsSchema = exports.facetQuerySchema = void 0;
 /**
  * Zod schemas for the admin MCP server tools.
  *
@@ -240,6 +240,12 @@ exports.removeUserRoleSchema = zod_1.z.object({
     user_id: zod_1.z.string().describe('User UUID'),
     role: zod_1.z.string().describe('Role to remove'),
 });
+exports.patchUserPropertiesSchema = zod_1.z.object({
+    user_id: zod_1.z.string().describe('User UUID'),
+    set: zod_1.z.record(zod_1.z.any()).optional().describe('Properties to set — typed JSON values'),
+    remove: zod_1.z.array(zod_1.z.string()).optional().describe('Property keys to delete'),
+    rename: zod_1.z.record(zod_1.z.string()).optional().describe('{ oldKey: newKey } renames — values preserved'),
+});
 // ── roles (routes/roles.ts) ─────────────────────────────────────────────────
 exports.listRolesSchema = zod_1.z.object({});
 exports.createRoleSchema = zod_1.z.object({
@@ -579,6 +585,9 @@ exports.exportWorkflowExecutionSchema = zod_1.z.object({
 exports.getExportStatusSchema = zod_1.z.object({
     workflow_id: zod_1.z.string().describe('Workflow ID to check export status'),
 });
+exports.getWorkflowEnvelopesSchema = zod_1.z.object({
+    workflow_id: zod_1.z.string().describe('Workflow ID whose input/output envelopes to fetch'),
+});
 // ── Diagnostics ───────────────────────────────────────────────────────────────
 exports.diagnoseJobSchema = zod_1.z.object({
     workflow_id: zod_1.z.string().describe('Workflow ID to diagnose'),