@hotmeshio/long-tail 0.16.2 → 0.17.0

package/build/api/exports.d.ts

@@ -77,6 +77,21 @@ export declare function exportWorkflowExecution(input: {
 export declare function getWorkflowStatus(input: {
     workflowId: string;
 }): Promise<LTApiResult>;
+/**
+ * Get a workflow's input and output envelopes — the effortless read.
+ *
+ * Two narrow lookups (no event stream, no full export): the input is
+ * available for the life of the job; the output is null with
+ * `status: 'running'` until the workflow completes, making this the natural
+ * polling body. A failed run answers `status: 'failed'` with the workflow's
+ * error message.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: { workflow_id, status, input, output, error? } }`
+ */
+export declare function getWorkflowEnvelopes(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
 /**
  * Get the current state data of a workflow.
  *

package/build/api/exports.js

@@ -37,6 +37,7 @@ exports.listJobs = listJobs;
 exports.exportWorkflowState = exportWorkflowState;
 exports.exportWorkflowExecution = exportWorkflowExecution;
 exports.getWorkflowStatus = getWorkflowStatus;
+exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
 exports.getWorkflowState = getWorkflowState;
 const exportService = __importStar(require("../services/export"));
 const resolve_1 = require("../services/task/resolve");
@@ -171,6 +172,40 @@ async function getWorkflowStatus(input) {
         };
     }
 }
+/**
+ * Get a workflow's input and output envelopes — the effortless read.
+ *
+ * Two narrow lookups (no event stream, no full export): the input is
+ * available for the life of the job; the output is null with
+ * `status: 'running'` until the workflow completes, making this the natural
+ * polling body. A failed run answers `status: 'failed'` with the workflow's
+ * error message.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: { workflow_id, status, input, output, error? } }`
+ */
+async function getWorkflowEnvelopes(input) {
+    try {
+        let resolved;
+        try {
+            resolved = await (0, resolve_1.resolveWorkflowHandle)(input.workflowId);
+        }
+        catch {
+            return { status: 404, error: 'Workflow not found' };
+        }
+        const result = await exportService.getWorkflowEnvelopes(input.workflowId, resolved.taskQueue, resolved.workflowName);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        const status = err.status === 404 || err.message?.includes('Not Found') ? 404 : 500;
+        return {
+            status,
+            error: status === 404
+                ? 'Workflow data is no longer available (job may have expired)'
+                : err.message,
+        };
+    }
+}
 /**
  * Get the current state data of a workflow.
  *

package/build/api/users.d.ts

@@ -63,7 +63,8 @@ export declare function createUser(input: {
  * @param input.email — new email address
  * @param input.display_name — new display name
  * @param input.status — new user status
- * @param input.metadata — replacement metadata object
+ * @param input.metadata — REPLACES the whole properties dictionary; for
+ *   per-key edits use patchUserProperties (never clobbers siblings)
  * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
  */
 export declare function updateUser(input: {
@@ -74,6 +75,35 @@ export declare function updateUser(input: {
     status?: string;
     metadata?: Record<string, any>;
 }): Promise<LTApiResult>;
+/**
+ * Atomically patch the user's properties dictionary (lt_users.metadata) —
+ * one statement, never read-merge-write. Deleting a key is explicit
+ * (`remove`); a key absent from the patch is kept. `rename` preserves the
+ * value with no key-absent window. Identity-binding keys (badge scan
+ * scheme target facets) assert uniqueness among active users in the same
+ * statement.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.set — properties to set (typed JSON values)
+ * @param input.remove — property keys to delete
+ * @param input.rename — `{ oldKey: newKey }` renames, values preserved
+ * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ *   user; 409 when an identity value already belongs to another active user
+ */
+export declare function patchUserProperties(input: {
+    id: string;
+    set?: Record<string, unknown>;
+    remove?: string[];
+    rename?: Record<string, string>;
+}): Promise<LTApiResult>;
+/**
+ * The property keys the platform itself resolves identities against — every
+ * enabled identity scan scheme's target facet. The dashboard marks these as
+ * system properties.
+ *
+ * @returns `{ status: 200, data: { keys: string[] } }`
+ */
+export declare function getSystemPropertyKeys(): Promise<LTApiResult>;
 /**
  * Delete a user by ID. Requires admin privileges.
  *

package/build/api/users.js

@@ -37,6 +37,8 @@ exports.listUsers = listUsers;
 exports.getUser = getUser;
 exports.createUser = createUser;
 exports.updateUser = updateUser;
+exports.patchUserProperties = patchUserProperties;
+exports.getSystemPropertyKeys = getSystemPropertyKeys;
 exports.deleteUser = deleteUser;
 exports.getUserRoles = getUserRoles;
 exports.addUserRole = addUserRole;
@@ -145,7 +147,8 @@ async function createUser(input) {
  * @param input.email — new email address
  * @param input.display_name — new display name
  * @param input.status — new user status
- * @param input.metadata — replacement metadata object
+ * @param input.metadata — REPLACES the whole properties dictionary; for
+ *   per-key edits use patchUserProperties (never clobbers siblings)
  * @returns `{ status: 200, data: User }` on success, or `{ status: 404 }` if not found
  */
 async function updateUser(input) {
@@ -161,6 +164,56 @@ async function updateUser(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Atomically patch the user's properties dictionary (lt_users.metadata) —
+ * one statement, never read-merge-write. Deleting a key is explicit
+ * (`remove`); a key absent from the patch is kept. `rename` preserves the
+ * value with no key-absent window. Identity-binding keys (badge scan
+ * scheme target facets) assert uniqueness among active users in the same
+ * statement.
+ *
+ * @param input.id — the user's unique identifier
+ * @param input.set — properties to set (typed JSON values)
+ * @param input.remove — property keys to delete
+ * @param input.rename — `{ oldKey: newKey }` renames, values preserved
+ * @returns `{ status: 200, data: User }`; 400 malformed patch; 404 unknown
+ *   user; 409 when an identity value already belongs to another active user
+ */
+async function patchUserProperties(input) {
+    try {
+        const user = await userService.patchUserProperties(input.id, {
+            set: input.set,
+            remove: input.remove,
+            rename: input.rename,
+        });
+        if (!user) {
+            return { status: 404, error: 'User not found' };
+        }
+        return { status: 200, data: user };
+    }
+    catch (err) {
+        if (err.status === 400 || err.status === 409) {
+            return { status: err.status, error: err.message };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * The property keys the platform itself resolves identities against — every
+ * enabled identity scan scheme's target facet. The dashboard marks these as
+ * system properties.
+ *
+ * @returns `{ status: 200, data: { keys: string[] } }`
+ */
+async function getSystemPropertyKeys() {
+    try {
+        const keys = await userService.getIdentityPropertyKeys();
+        return { status: 200, data: { keys } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Delete a user by ID. Requires admin privileges.
  *

package/build/bin/ltc.js

@@ -259,6 +259,10 @@ wfCmd.command('status <id>')
 wfCmd.command('result <id>')
     .option('--json', 'JSON output')
     .action(wrap(wf.getWorkflowResult));
+wfCmd.command('envelopes <id>')
+    .description('The workflow\'s input and output envelopes — light, never blocks')
+    .option('--json', 'JSON output')
+    .action(wrap(wf.getWorkflowEnvelopes));
 wfCmd.command('terminate <id>')
     .action(wrap(wf.terminateWorkflow));
 // ── Pipelines (YAML Workflows) ──────────────────────────────────────────
@@ -331,6 +335,13 @@ usrCmd.command('list')
 usrCmd.command('get <id>')
     .option('--json', 'JSON output')
     .action(wrap(usr.getUser));
+usrCmd.command('props <id>')
+    .description('View or atomically patch the user\'s properties dictionary')
+    .option('--set <key=value...>', 'Set a property (repeatable; value JSON-parsed, string fallback)')
+    .option('--remove <key...>', 'Delete a property (repeatable)')
+    .option('--rename <old=new...>', 'Rename a property, value preserved (repeatable)')
+    .option('--json', 'JSON output')
+    .action(wrap(usr.userProps));
 // ── Roles ────────────────────────────────────────────────────────────────
 const rolesCmd = commander_1.program.command('roles').description('Roles — the queue-backed work surfaces where workflows hand off to people');
 rolesCmd.command('list')

package/build/lib/cli/commands/users.d.ts

@@ -5,3 +5,14 @@ export declare function listUsers(opts: {
 export declare function getUser(id: string, opts: {
     json?: boolean;
 }): Promise<void>;
+/**
+ * View or atomically patch a user's properties dictionary. With no flags,
+ * prints the dictionary; with --set/--remove/--rename, applies ONE atomic
+ * patch (never read-merge-write) and prints the result.
+ */
+export declare function userProps(id: string, opts: {
+    set?: string[];
+    remove?: string[];
+    rename?: string[];
+    json?: boolean;
+}): Promise<void>;

package/build/lib/cli/commands/users.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listUsers = listUsers;
 exports.getUser = getUser;
+exports.userProps = userProps;
+const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
 const COLUMNS = [
@@ -23,3 +28,57 @@ async function getUser(id, opts) {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/** Parse a repeatable `key=value` flag; values JSON-parse with string fallback. */
+function parsePairs(pairs) {
+    if (!pairs?.length)
+        return undefined;
+    const out = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`Expected key=value, got "${pair}"`);
+        const key = pair.slice(0, eq);
+        const raw = pair.slice(eq + 1);
+        try {
+            out[key] = JSON.parse(raw);
+        }
+        catch {
+            out[key] = raw;
+        }
+    }
+    return out;
+}
+/**
+ * View or atomically patch a user's properties dictionary. With no flags,
+ * prints the dictionary; with --set/--remove/--rename, applies ONE atomic
+ * patch (never read-merge-write) and prints the result.
+ */
+async function userProps(id, opts) {
+    const set = parsePairs(opts.set);
+    const rename = parsePairs(opts.rename);
+    const remove = opts.remove?.length ? opts.remove : undefined;
+    let user;
+    if (set || remove || rename) {
+        user = await (0, client_1.apiFetch)(`/users/${id}/properties`, {
+            method: 'PATCH',
+            body: JSON.stringify({ set, remove, rename }),
+        });
+    }
+    else {
+        user = await (0, client_1.apiFetch)(`/users/${id}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(user.metadata ?? {}, null, 2));
+        return;
+    }
+    const props = Object.entries(user.metadata ?? {});
+    console.log(`\n  ${picocolors_1.default.bold(user.display_name ?? user.external_id ?? id)} ${picocolors_1.default.dim(user.id ?? id)}`);
+    if (props.length === 0) {
+        console.log(picocolors_1.default.dim('  (no properties)\n'));
+        return;
+    }
+    for (const [key, value] of props) {
+        console.log(`  ${picocolors_1.default.bold(key)} = ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    }
+    console.log();
+}

package/build/lib/cli/commands/workflows.d.ts

@@ -13,4 +13,7 @@ export declare function getWorkflowStatus(id: string, opts: {
 export declare function getWorkflowResult(id: string, opts: {
     json?: boolean;
 }): Promise<void>;
+export declare function getWorkflowEnvelopes(id: string, opts: {
+    json?: boolean;
+}): Promise<void>;
 export declare function terminateWorkflow(id: string): Promise<void>;

package/build/lib/cli/commands/workflows.js

@@ -40,6 +40,7 @@ exports.listWorkflows = listWorkflows;
 exports.invokeWorkflow = invokeWorkflow;
 exports.getWorkflowStatus = getWorkflowStatus;
 exports.getWorkflowResult = getWorkflowResult;
+exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
 exports.terminateWorkflow = terminateWorkflow;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
@@ -98,6 +99,27 @@ async function getWorkflowResult(id, opts) {
         console.log();
     }
 }
+async function getWorkflowEnvelopes(id, opts) {
+    const data = await (0, client_1.apiFetch)(`/workflow-states/${id}/envelopes`);
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const status = data.status === 'completed' ? picocolors_1.default.green(data.status)
+        : data.status === 'failed' ? picocolors_1.default.red(data.status)
+            : picocolors_1.default.blue(data.status);
+    console.log(`\n  ${picocolors_1.default.dim(data.workflow_id)}  ${status}`);
+    console.log(`\n  ${picocolors_1.default.bold('Input')}`);
+    console.log(JSON.stringify(data.input, null, 2));
+    console.log(`\n  ${picocolors_1.default.bold('Output')}`);
+    if (data.error) {
+        console.log(picocolors_1.default.red(data.error));
+    }
+    else {
+        console.log(data.output === null ? picocolors_1.default.dim('(not yet — still running)') : JSON.stringify(data.output, null, 2));
+    }
+    console.log();
+}
 async function terminateWorkflow(id) {
     await (0, client_1.apiFetch)(`/workflows/terminate/${id}`, { method: 'POST' });
     console.log(`\n  ${picocolors_1.default.green('✓')} Terminated ${picocolors_1.default.dim(id)}\n`);

package/build/routes/exports.js

@@ -95,6 +95,17 @@ router.get('/:workflowId/execution', async (req, res) => {
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/workflow-states/:workflowId/envelopes
+ * The workflow's input and output envelopes — two narrow lookups, no event
+ * stream. Output is null with status 'running' until the workflow completes.
+ */
+router.get('/:workflowId/envelopes', async (req, res) => {
+    const result = await api.getWorkflowEnvelopes({
+        workflowId: req.params.workflowId,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/workflow-states/:workflowId/status
  * Return only the numeric status semaphore.

package/build/routes/users.js

@@ -55,6 +55,16 @@ router.get('/', async (req, res) => {
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/users/system-property-keys
+ * The property keys the platform resolves identities against (enabled
+ * identity scan schemes' target facets) — marked as system properties in
+ * the dashboard editor. Registered before /:id so the literal wins.
+ */
+router.get('/system-property-keys', async (_req, res) => {
+    const result = await api.getSystemPropertyKeys();
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/users/:id
  * Get a single user by ID.
@@ -81,6 +91,22 @@ router.put('/:id', auth_1.requireBuilder, async (req, res) => {
     const result = await api.updateUser({ id: req.params.id, ...(req.body || {}) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * PATCH /api/users/:id/properties
+ * Atomically patch the user's properties dictionary. Builder only — the
+ * same gate as every other user write.
+ * Body: { set?: { key: value }, remove?: [key], rename?: { old: new } }
+ */
+router.patch('/:id/properties', auth_1.requireBuilder, async (req, res) => {
+    const { set, remove, rename } = req.body || {};
+    const result = await api.patchUserProperties({
+        id: req.params.id,
+        set,
+        remove,
+        rename,
+    });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * DELETE /api/users/:id
  * Delete a user. Builder only.

package/build/sdk/index.d.ts

@@ -247,6 +247,7 @@ export declare function createClient(options?: LTClientOptions): {
             options?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         getStatus: typeof workflowsApi.getWorkflowStatus;
+        getEnvelopes: typeof exportsApi.getWorkflowEnvelopes;
         getResult: typeof workflowsApi.getWorkflowResult;
         terminate: typeof workflowsApi.terminateWorkflow;
         export: typeof workflowsApi.exportWorkflow;
@@ -289,6 +290,8 @@ export declare function createClient(options?: LTClientOptions): {
         get: typeof usersApi.getUser;
         create: typeof usersApi.createUser;
         update: typeof usersApi.updateUser;
+        patchProperties: typeof usersApi.patchUserProperties;
+        getSystemPropertyKeys: typeof usersApi.getSystemPropertyKeys;
         delete: typeof usersApi.deleteUser;
         getRoles: typeof usersApi.getUserRoles;
         addRole: typeof usersApi.addUserRole;

package/build/sdk/index.js

@@ -155,6 +155,7 @@ function createClient(options = {}) {
         workflows: {
             invoke: bindAuth(workflowsApi.invokeWorkflow, auth),
             getStatus: workflowsApi.getWorkflowStatus,
+            getEnvelopes: exportsApi.getWorkflowEnvelopes,
             getResult: workflowsApi.getWorkflowResult,
             terminate: workflowsApi.terminateWorkflow,
             export: workflowsApi.exportWorkflow,
@@ -193,6 +194,8 @@ function createClient(options = {}) {
             get: usersApi.getUser,
             create: usersApi.createUser,
             update: usersApi.updateUser,
+            patchProperties: usersApi.patchUserProperties,
+            getSystemPropertyKeys: usersApi.getSystemPropertyKeys,
             delete: usersApi.deleteUser,
             getRoles: usersApi.getUserRoles,
             addRole: usersApi.addUserRole,

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

@@ -24,6 +24,25 @@ export declare function getWorkflowStatus(workflowId: string, taskQueue: string,
  * system/user classification, and a summary.
  */
 export declare function exportWorkflowExecution(workflowId: string, taskQueue: string, workflowName: string, options?: ExecutionExportOptions): Promise<WorkflowExecution>;
+/** The input/output envelope pair plus the derived run status. */
+export interface WorkflowEnvelopes {
+    workflow_id: string;
+    status: 'running' | 'completed' | 'failed';
+    /** The workflow's input — the single LTEnvelope for one-arg workflows, else the args array. */
+    input: unknown;
+    /** The workflow's return envelope, or null while it is still running or when it failed. */
+    output: unknown;
+    /** The workflow's error message, present only when status is 'failed'. */
+    error?: string;
+}
+/**
+ * The effortless read: what went in, what came out. Two narrow lookups —
+ * `handle.input()` (one field read, available for the life of the job) and
+ * `handle.output()` (one state read, never blocks) — no event stream, no
+ * full export. While the workflow runs, `output` is null and `status` says
+ * so, making this the natural polling body.
+ */
+export declare function getWorkflowEnvelopes(workflowId: string, taskQueue: string, workflowName: string): Promise<WorkflowEnvelopes>;
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/export/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.exportWorkflow = exportWorkflow;
 exports.getWorkflowStatus = getWorkflowStatus;
 exports.exportWorkflowExecution = exportWorkflowExecution;
+exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
 exports.getWorkflowState = getWorkflowState;
 exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
@@ -66,21 +67,14 @@ async function getWorkflowStatus(workflowId, taskQueue, workflowName) {
 async function exportWorkflowExecution(workflowId, taskQueue, workflowName, options) {
     try {
         const handle = await (0, client_1.getHandle)(taskQueue, workflowName, workflowId);
-        const [execution, raw] = await Promise.all([
-            handle.exportExecution({ ...options, enrich_inputs: true }),
-            handle.export({ allow: ['state'], values: true }),
-        ]);
-        const processed = (0, post_process_1.postProcessExecution)(execution);
-        // Extract parent_workflow_id from the raw state metadata (HotMesh's `pj` field).
-        // The SDK's WorkflowExecution doesn't surface this yet; when it does,
-        // the SDK value takes precedence (defensive: only set if absent).
-        if (!processed.parent_workflow_id) {
-            const pj = extractParentJobId(raw);
-            if (pj && pj !== workflowId) {
-                processed.parent_workflow_id = pj;
-            }
-        }
-        return processed;
+        // include_lineage populates parent_workflow_id/origin_id from the jobs
+        // table in one indexed lookup — no second export call.
+        const execution = await handle.exportExecution({
+            ...options,
+            enrich_inputs: true,
+            include_lineage: true,
+        });
+        return (0, post_process_1.postProcessExecution)(execution);
     }
     catch (err) {
         if (err instanceof WorkflowNotFoundError)
@@ -89,25 +83,51 @@ async function exportWorkflowExecution(workflowId, taskQueue, workflowName, opti
     }
 }
 /**
- * Walk the raw export state looking for the `pj` (parent job ID) field.
- * HotMesh stores it at `state.output.metadata.pj` after symbol inflation.
- * Returns undefined if not found (workflow has no parent).
+ * The effortless read: what went in, what came out. Two narrow lookups —
+ * `handle.input()` (one field read, available for the life of the job) and
+ * `handle.output()` (one state read, never blocks) — no event stream, no
+ * full export. While the workflow runs, `output` is null and `status` says
+ * so, making this the natural polling body.
  */
-function extractParentJobId(raw) {
-    const state = raw?.state;
-    if (!state || typeof state !== 'object')
-        return undefined;
-    // Typical path: state.output.metadata.pj
-    const output = state.output ?? state;
-    const metadata = output?.metadata;
-    if (metadata?.pj && typeof metadata.pj === 'string') {
-        return metadata.pj;
-    }
-    // Fallback: walk top-level state keys (older export shapes)
-    if (state.pj && typeof state.pj === 'string') {
-        return state.pj;
-    }
-    return undefined;
+async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
+    let handle;
+    try {
+        handle = await (0, client_1.getHandle)(taskQueue, workflowName, workflowId);
+    }
+    catch {
+        throw new WorkflowNotFoundError(workflowId);
+    }
+    const [statusCode, args] = await Promise.all([
+        handle.status(),
+        handle.input().catch(() => undefined),
+    ]).catch(() => {
+        throw new WorkflowNotFoundError(workflowId);
+    });
+    // Long-tail workflows take a single LTEnvelope argument — unwrap it;
+    // multi-arg workflows keep the args array verbatim.
+    const input = Array.isArray(args) && args.length === 1 ? args[0] : args ?? null;
+    if (statusCode > 0) {
+        return { workflow_id: workflowId, status: 'running', input, output: null };
+    }
+    try {
+        const output = await handle.output();
+        return {
+            workflow_id: workflowId,
+            status: statusCode === 0 ? 'completed' : 'failed',
+            input,
+            output: output ?? null,
+        };
+    }
+    catch (err) {
+        // output() throws the workflow's own error for failed runs — that IS the outcome.
+        return {
+            workflow_id: workflowId,
+            status: 'failed',
+            input,
+            output: null,
+            error: err?.message ?? String(err),
+        };
+    }
 }
 /**
  * Return the current job state of a workflow.

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

@@ -1,5 +1,5 @@
 import type { LTUserRecord, LTRoleType, LTUserStatus } from '../../types';
-import type { CreateUserInput, UpdateUserInput } from './types';
+import type { CreateUserInput, UpdateUserInput, UserPropertyOps } from './types';
 export declare function attachRoles(user: any): Promise<LTUserRecord>;
 export declare function createUser(input: CreateUserInput): Promise<LTUserRecord>;
 export declare function getUser(id: string): Promise<LTUserRecord | null>;
@@ -12,6 +12,37 @@ export declare function getUserByEmail(email: string): Promise<LTUserRecord | nu
  */
 export declare function getUserByMetadataValue(key: string, value: string): Promise<LTUserRecord | null>;
 export declare function updateUser(id: string, input: UpdateUserInput): Promise<LTUserRecord | null>;
+/** A property write that would create an ambiguous identity binding. */
+export declare class UserPropertyConflictError extends Error {
+    status: number;
+    constructor(key: string);
+}
+/** A malformed property patch — rejected before any write. */
+export declare class UserPropertyValidationError extends Error {
+    status: number;
+    constructor(message: string);
+}
+/**
+ * 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.
+ */
+export declare function getIdentityPropertyKeys(): Promise<string[]>;
+/**
+ * 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).
+ */
+export declare function patchUserProperties(id: string, ops: UserPropertyOps): Promise<LTUserRecord | null>;
 export declare function deleteUser(id: string): Promise<boolean>;
 export declare function listUsers(filters: {
     role?: string;