@hotmeshio/long-tail 0.10.1 → 0.10.3

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

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
+ * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
+ * may declare `x-lt-bind: "a.b[0].c"`, the path its value occupies in the payload;
+ * a property with no bind sits at its own name at the root (1:1). This module is
+ * isomorphic — the dashboard renders forms with it, and the API layer inverts a
+ * submitted payload through it to validate against the form contract. One
+ * implementation, both sides.
+ *
+ *   mapPayloadToForm  — payload → flat form values, to PREFILL/display the form
+ *                       (server-side: to validate a submitted payload)
+ *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePath = parsePath;
+exports.setDeep = setDeep;
+exports.getDeep = getDeep;
+exports.bindPathFor = bindPathFor;
+exports.mapFormToPayload = mapFormToPayload;
+exports.mapPayloadToForm = mapPayloadToForm;
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
+function parsePath(path) {
+    const segs = [];
+    for (const raw of path.split('.')) {
+        const m = raw.match(/^([^[\]]*)((?:\[\d+\])*)$/);
+        if (!m)
+            throw new Error(`invalid x-lt-bind path segment: "${raw}"`);
+        const [, name, brackets] = m;
+        if (name) {
+            if (BLOCKED_KEYS.has(name))
+                throw new Error(`x-lt-bind path may not target "${name}"`);
+            segs.push({ key: name });
+        }
+        for (const b of brackets.match(/\d+/g) ?? [])
+            segs.push({ index: Number(b) });
+    }
+    if (segs.length === 0)
+        throw new Error(`empty x-lt-bind path: "${path}"`);
+    return segs;
+}
+/** Set `value` at `path` inside `root`, creating intermediate objects/arrays. */
+function setDeep(root, path, value) {
+    const segs = parsePath(path);
+    let node = root;
+    for (let i = 0; i < segs.length - 1; i++) {
+        const seg = segs[i];
+        const next = segs[i + 1];
+        const childKey = 'key' in seg ? seg.key : seg.index;
+        const wantArray = 'index' in next;
+        if (node[childKey] == null || typeof node[childKey] !== 'object') {
+            node[childKey] = wantArray ? [] : {};
+        }
+        node = node[childKey];
+    }
+    const last = segs[segs.length - 1];
+    node['key' in last ? last.key : last.index] = value;
+}
+/** Read the value at `path` inside `root` (undefined if any segment is missing). */
+function getDeep(root, path) {
+    let node = root;
+    for (const seg of parsePath(path)) {
+        if (node == null || typeof node !== 'object')
+            return undefined;
+        node = node['key' in seg ? seg.key : seg.index];
+    }
+    return node;
+}
+/** The bind path for a form property (its `x-lt-bind`, or the property name). */
+function bindPathFor(propName, propDef) {
+    const bind = propDef?.['x-lt-bind'];
+    return typeof bind === 'string' && bind.length > 0 ? bind : propName;
+}
+/**
+ * Assemble the payload from the form's flat values. A field absent from
+ * `formValues` is omitted (so clearing/deleting a field drops it from the
+ * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * properties, values pass through unchanged.
+ */
+function mapFormToPayload(formValues, formSchema) {
+    const props = formSchema?.properties;
+    if (!props)
+        return { ...formValues };
+    const payload = {};
+    for (const [name, def] of Object.entries(props)) {
+        if (!(name in formValues))
+            continue;
+        setDeep(payload, bindPathFor(name, def), formValues[name]);
+    }
+    return payload;
+}
+/**
+ * Reverse of {@link mapFormToPayload}: pull each form field's value out of the
+ * payload via its bind path, to prefill/display the form. A field whose bound
+ * path is missing from the payload is omitted (the caller falls back to the
+ * schema default).
+ */
+function mapPayloadToForm(payload, formSchema) {
+    const props = formSchema?.properties;
+    if (!props)
+        return payload ? { ...payload } : {};
+    const form = {};
+    for (const [name, def] of Object.entries(props)) {
+        const v = getDeep(payload, bindPathFor(name, def));
+        if (v !== undefined)
+            form[name] = v;
+    }
+    return form;
+}

package/build/shared/form-validation/x-lt-help.d.ts

@@ -0,0 +1,21 @@
+/** The token domains a help template may reference. */
+export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver"];
+export type HelpDomain = (typeof HELP_DOMAINS)[number];
+export type HelpTokenContext = Partial<Record<HelpDomain, Record<string, unknown> | null>>;
+/** Replace every `{{domain.path}}` token with its value from the context. */
+export declare function interpolateHelp(template: string, ctx: HelpTokenContext): string;
+/** The schema's help source: `x-lt-help` first, `x-lt-context` as fallback. */
+export declare function resolveHelpSource(schema: Record<string, unknown> | null | undefined): string | null;
+/** The schema's help content, interpolated. Null when the schema declares none. */
+export declare function buildHelpMarkdown(schema: Record<string, unknown> | null | undefined, ctx: HelpTokenContext): string | null;
+export interface HelpStateHint {
+    isTerminal: boolean;
+    status?: string;
+    claimed: boolean;
+    claimedByMe: boolean;
+}
+/**
+ * State-aware guidance shown when the schema carries no help content — the
+ * panel always tells the user what this page expects of them right now.
+ */
+export declare function defaultHelpMarkdown({ isTerminal, status, claimed, claimedByMe }: HelpStateHint): string;

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

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_DOMAINS = void 0;
+exports.interpolateHelp = interpolateHelp;
+exports.resolveHelpSource = resolveHelpSource;
+exports.buildHelpMarkdown = buildHelpMarkdown;
+exports.defaultHelpMarkdown = defaultHelpMarkdown;
+/**
+ * x-lt-help — the form's guidance content, rendered in the side panel beside
+ * the resolve form. A form_schema may declare schema-level `x-lt-help`: a
+ * markdown string whose `{{domain.path}}` tokens interpolate values from the
+ * escalation surface, so help text can reference the live record:
+ *
+ *   {{escalation.role}}                        — any column on the escalation row
+ *   {{metadata.schema_version}}                — the row's metadata dict
+ *   {{envelope.formDefaults.customer.name}}    — the workflow-sent input envelope
+ *   {{payload.category}}                       — the escalation context payload
+ *   {{resolver.notes}}                         — the submitted resolver payload
+ *
+ * Paths reuse the x-lt-bind syntax (`a.b[0].c`). A missing value renders as an
+ * em dash. `x-lt-context` is accepted as the plain-text fallback source when
+ * `x-lt-help` is absent.
+ */
+const x_lt_bind_1 = require("./x-lt-bind");
+/** The token domains a help template may reference. */
+exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver'];
+const TOKEN_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const MISSING_VALUE = '—';
+function formatTokenValue(value) {
+    if (value === undefined || value === null)
+        return MISSING_VALUE;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return MISSING_VALUE;
+    }
+}
+/** Replace every `{{domain.path}}` token with its value from the context. */
+function interpolateHelp(template, ctx) {
+    return template.replace(TOKEN_PATTERN, (_match, rawPath) => {
+        const dot = rawPath.indexOf('.');
+        const domain = (dot === -1 ? rawPath : rawPath.slice(0, dot));
+        if (!exports.HELP_DOMAINS.includes(domain))
+            return MISSING_VALUE;
+        const root = ctx[domain];
+        if (dot === -1)
+            return formatTokenValue(root);
+        try {
+            return formatTokenValue((0, x_lt_bind_1.getDeep)(root, rawPath.slice(dot + 1)));
+        }
+        catch {
+            return MISSING_VALUE;
+        }
+    });
+}
+/** The schema's help source: `x-lt-help` first, `x-lt-context` as fallback. */
+function resolveHelpSource(schema) {
+    const help = schema?.['x-lt-help'];
+    if (typeof help === 'string' && help.trim().length > 0)
+        return help;
+    const context = schema?.['x-lt-context'];
+    if (typeof context === 'string' && context.trim().length > 0)
+        return context;
+    return null;
+}
+/** The schema's help content, interpolated. Null when the schema declares none. */
+function buildHelpMarkdown(schema, ctx) {
+    const source = resolveHelpSource(schema);
+    return source ? interpolateHelp(source, ctx) : null;
+}
+/**
+ * State-aware guidance shown when the schema carries no help content — the
+ * panel always tells the user what this page expects of them right now.
+ */
+function defaultHelpMarkdown({ isTerminal, status, claimed, claimedByMe }) {
+    if (isTerminal) {
+        return status === 'cancelled'
+            ? 'This escalation was cancelled. The record is shown for reference.'
+            : 'This escalation has been resolved. The submitted form is shown for reference.';
+    }
+    if (claimedByMe)
+        return 'You have claimed this escalation. Fill out the form and submit to resolve it.';
+    if (claimed)
+        return 'Another user has claimed this escalation. It unlocks if their claim expires or is released.';
+    return 'Claim this escalation to enable the form.';
+}

package/build/shared/form-validation/x-lt-show-if.d.ts

@@ -0,0 +1,7 @@
+import { type HelpTokenContext } from './x-lt-help';
+export type ShowIfContext = HelpTokenContext;
+/**
+ * Evaluates an x-lt-showIf condition. Returns true when the field should be
+ * shown. Returns true when condition is absent, non-string, or context is null.
+ */
+export declare function evaluateShowIf(condition: unknown, ctx: ShowIfContext | null | undefined): boolean;

package/build/shared/form-validation/x-lt-show-if.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateShowIf = evaluateShowIf;
+/**
+ * x-lt-showIf — conditional field visibility. A form_schema property may
+ * declare `x-lt-showIf: "domain.path"` to show the field only when the value
+ * at that path is present and truthy. Prefix `!` to invert: show when absent
+ * or falsy.
+ *
+ * Equality forms compare the resolved value's string form:
+ *   "domain.path=VALUE"   — show when String(value) equals VALUE
+ *   "domain.path!=VALUE"  — show when it does not
+ * An absent value compares as the empty string, so `=X` is false and `!=X` is
+ * true when the path is missing. VALUE is the raw remainder after the operator
+ * (trimmed; no quoting). The truthy/! forms are unchanged.
+ *
+ * Domains follow the same `domain.path` convention as x-lt-help tokens:
+ *   metadata   — the escalation row's metadata dict
+ *   payload    — the escalation context payload (escalation_payload)
+ *   envelope   — the workflow-sent input envelope
+ *   escalation — top-level escalation row fields
+ *   resolver   — the submitted resolver payload
+ *
+ * A missing or non-string condition always shows the field (opt-in, safe default).
+ */
+const x_lt_bind_1 = require("./x-lt-bind");
+const x_lt_help_1 = require("./x-lt-help");
+function isTruthy(value) {
+    return value !== null && value !== undefined && value !== '' && value !== false && value !== 0;
+}
+/** The value's comparable string form; absent compares as the empty string. */
+function asComparable(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+function resolvePath(expr, ctx) {
+    const dot = expr.indexOf('.');
+    const domain = (dot === -1 ? expr : expr.slice(0, dot));
+    if (!x_lt_help_1.HELP_DOMAINS.includes(domain))
+        return { known: false, value: undefined };
+    const root = ctx[domain];
+    if (dot === -1)
+        return { known: true, value: root };
+    try {
+        return { known: true, value: (0, x_lt_bind_1.getDeep)(root, expr.slice(dot + 1)) };
+    }
+    catch {
+        return { known: true, value: undefined };
+    }
+}
+/**
+ * Evaluates an x-lt-showIf condition. Returns true when the field should be
+ * shown. Returns true when condition is absent, non-string, or context is null.
+ */
+function evaluateShowIf(condition, ctx) {
+    if (typeof condition !== 'string' || condition.length === 0)
+        return true;
+    if (!ctx)
+        return true;
+    const negate = condition.startsWith('!');
+    const expr = negate ? condition.slice(1) : condition;
+    // Equality forms — `!=` first so it never parses as `=` with a `!` in the path.
+    const neqAt = expr.indexOf('!=');
+    const eqAt = expr.indexOf('=');
+    if (neqAt !== -1 || (eqAt !== -1 && eqAt !== neqAt + 1)) {
+        const isNeq = neqAt !== -1 && (eqAt === -1 || neqAt < eqAt);
+        const opAt = isNeq ? neqAt : eqAt;
+        const path = expr.slice(0, opAt).trim();
+        const expected = expr.slice(opAt + (isNeq ? 2 : 1)).trim();
+        const { known, value } = resolvePath(path, ctx);
+        if (!known)
+            return true; // unknown domain — safe default, same as truthy form
+        const matches = asComparable(value) === expected;
+        const result = isNeq ? !matches : matches;
+        return negate ? !result : result;
+    }
+    const { known, value } = resolvePath(expr, ctx);
+    if (!known)
+        return true;
+    return negate ? !isTruthy(value) : isTruthy(value);
+}

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

@@ -567,7 +567,22 @@ export declare const updateRoleSchema: z.ZodObject<{
     worker_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     priority_threshold_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     priority_facet: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enforce_schema: z.ZodOptional<z.ZodBoolean>;
     upstream_roles: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    list_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    default_pins: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+        badge: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }, {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }>, "many">>>;
     change_summary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     role: string;
@@ -576,6 +591,12 @@ export declare const updateRoleSchema: z.ZodObject<{
     title?: string | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
+    list_schema?: Record<string, any> | null | undefined;
+    default_pins?: {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }[] | null | undefined;
     ops_visible?: boolean | undefined;
     parent_role?: string | null | undefined;
     sla_minutes?: number | null | undefined;
@@ -583,6 +604,7 @@ export declare const updateRoleSchema: z.ZodObject<{
     worker_count?: number | null | undefined;
     priority_threshold_minutes?: number | null | undefined;
     priority_facet?: string | null | undefined;
+    enforce_schema?: boolean | undefined;
     upstream_roles?: string[] | null | undefined;
     change_summary?: string | undefined;
 }, {
@@ -592,6 +614,12 @@ export declare const updateRoleSchema: z.ZodObject<{
     title?: string | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
+    list_schema?: Record<string, any> | null | undefined;
+    default_pins?: {
+        url: string;
+        label: string;
+        badge?: boolean | undefined;
+    }[] | null | undefined;
     ops_visible?: boolean | undefined;
     parent_role?: string | null | undefined;
     sla_minutes?: number | null | undefined;
@@ -599,6 +627,7 @@ export declare const updateRoleSchema: z.ZodObject<{
     worker_count?: number | null | undefined;
     priority_threshold_minutes?: number | null | undefined;
     priority_facet?: string | null | undefined;
+    enforce_schema?: boolean | undefined;
     upstream_roles?: string[] | null | undefined;
     change_summary?: string | undefined;
 }>;

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

@@ -249,7 +249,14 @@ exports.updateRoleSchema = zod_1.z.object({
     worker_count: zod_1.z.number().nullable().optional().describe('Capacity at this station (staff or machine count). One of the capacity settings.'),
     priority_threshold_minutes: zod_1.z.number().min(0).nullable().optional().describe('Max age in minutes before a pending unclaimed escalation counts toward the Pace Board priority count. Falls back to sla_minutes when null.'),
     priority_facet: zod_1.z.string().regex(facet_sql_1.FACET_KEY).nullable().optional().describe('lt_escalations.metadata key holding the age origin for the priority count as an ISO 8601 UTC timestamp (e.g. authorized_at). Falls back to created_at when null. When set, items missing the key or holding an unparseable value are not counted.'),
+    enforce_schema: zod_1.z.boolean().optional().describe('When true, every resolve surface validates the submitted resolverPayload against the escalation\'s form schema (the same pass the dashboard runs) and rejects violations with a structured schema_validation error before any state changes.'),
     upstream_roles: zod_1.z.array(zod_1.z.string()).nullable().optional().describe('Replace the set of roles this station draws input from across other sequences (parent_role stays the single prior step in its own sequence). Omitted = preserve; null or [] = clear.'),
+    list_schema: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('JSON contract (x-lt-* markup) that richly formats this role\'s escalation LIST page. Versioned independently of form_schema; the list always renders the latest version.'),
+    default_pins: zod_1.z.array(zod_1.z.object({
+        label: zod_1.z.string().describe('Pin label shown in the member\'s Pinned nav section'),
+        url: zod_1.z.string().describe('Dashboard-relative deep link (must start with /)'),
+        badge: zod_1.z.boolean().optional().describe('Render a live count beside the label (escalations-list URLs)'),
+    })).nullable().optional().describe('Pinned-view seeds handed to every member of this role. Members promote, hide, or reorder them via their own preferences. Null clears.'),
     change_summary: zod_1.z.string().optional().describe('Recorded on the schema version snapshot when this update changes form_schema or metadata_schema'),
 });
 exports.getRoleSchemaSchema = zod_1.z.object({

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

@@ -194,9 +194,11 @@ function registerUserTools(server) {
     server.registerTool('update_role', {
         title: 'Update Role',
         description: 'Update role metadata with PATCH semantics — omitted fields keep their ' +
-            'values. Covers display name, description, form/metadata schemas, the ' +
-            'free properties bag, ops_visible flag, parent role, and the typed ' +
-            'operational targets (sla_minutes, target_per_hour, worker_count, ' +
+            'values. Covers display name, description, form/metadata/list schemas, ' +
+            'the free properties bag, ops_visible flag, enforce_schema ' +
+            '(server-side resolver validation), parent role, default_pins ' +
+            '(member pinned-view seeds), and the typed operational targets ' +
+            '(sla_minutes, target_per_hour, worker_count, ' +
             'priority_threshold_minutes, priority_facet).',
         inputSchema: schemas_1.updateRoleSchema,
     }, async (args) => {
@@ -213,7 +215,10 @@ function registerUserTools(server) {
             worker_count: args.worker_count,
             priority_threshold_minutes: args.priority_threshold_minutes,
             priority_facet: args.priority_facet,
+            enforce_schema: args.enforce_schema,
             upstream_roles: args.upstream_roles,
+            list_schema: args.list_schema,
+            default_pins: args.default_pins,
             change_summary: args.change_summary,
         });
         if (!updated) {

package/build/system/mcp-servers/human-queue-schemas.d.ts

@@ -46,23 +46,23 @@ export declare const claimAndResolveSchema: z.ZodObject<{
     resolver_id: z.ZodString;
     payload: z.ZodRecord<z.ZodString, z.ZodAny>;
 }, "strip", z.ZodTypeAny, {
+    payload: Record<string, any>;
     escalation_id: string;
     resolver_id: string;
-    payload: Record<string, any>;
 }, {
+    payload: Record<string, any>;
     escalation_id: string;
     resolver_id: string;
-    payload: Record<string, any>;
 }>;
 export declare const resolveEscalationSchema: z.ZodObject<{
     escalation_id: z.ZodString;
     payload: z.ZodRecord<z.ZodString, z.ZodAny>;
 }, "strip", z.ZodTypeAny, {
-    escalation_id: string;
     payload: Record<string, any>;
-}, {
     escalation_id: string;
+}, {
     payload: Record<string, any>;
+    escalation_id: string;
 }>;
 export declare const escalateAndWaitSchema: z.ZodObject<{
     role: z.ZodString;

package/build/system/mcp-servers/human-queue-schemas.js

@@ -24,7 +24,10 @@ exports.getAvailableWorkSchema = zod_1.z.object({
 // The payload is stored exactly as submitted — the resolver payload IS the
 // payload. Shape it to match the role form's x-lt-bind paths (see the form_schema
 // check_resolution returns for a pending escalation); no server-side transform.
-const RESOLVER_PAYLOAD_DESC = 'Resolution payload, stored as-is. Match the shape the workflow consumes (the form_schema\'s x-lt-bind paths).';
+const RESOLVER_PAYLOAD_DESC = 'Resolution payload, stored as-is. Match the shape the workflow consumes (the form_schema\'s x-lt-bind paths). '
+    + 'Roles with enforce_schema validate it server-side: required fields (respecting x-lt-showIf), declared types '
+    + '(number vs string), enums, bounds, patterns, and x-lt-require-all checklists. Violations return a '
+    + 'schema_validation error listing each field.';
 exports.claimAndResolveSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation ID to claim and resolve'),
     resolver_id: zod_1.z.string().describe('Identifier for who/what is resolving'),

package/build/system/mcp-servers/human-queue.js

@@ -40,9 +40,36 @@ const crypto = __importStar(require("crypto"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../lib/logger");
 const escalationService = __importStar(require("../../services/escalation"));
+const resolver_validation_1 = require("../../services/escalation/resolver-validation");
+const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const human_queue_schemas_1 = require("./human-queue-schemas");
 let server = null;
+/**
+ * Schema enforcement for the MCP resolve tools — the same gate the HTTP
+ * surfaces run (agents and the sim workforce submit through these tools, so
+ * they get the same contract and the same canonical violation body). Costs
+ * zero reads when no role enforces (cached set); otherwise one row read.
+ * Returns the MCP error content when the payload is rejected, null to proceed.
+ */
+async function checkResolveToolPayload(escalationId, payload) {
+    const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
+    if (enforcing.size === 0)
+        return null;
+    const escalation = await escalationService.getEscalation(escalationId);
+    if (!escalation || !enforcing.has(escalation.role))
+        return null;
+    const report = await (0, resolver_validation_1.checkResolverPayload)(escalation, payload);
+    if (!report)
+        return null;
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify((0, resolver_validation_1.toValidationErrorBody)(report)),
+            }],
+        isError: true,
+    };
+}
 /**
  * Create the Long Tail Human Queue MCP server.
  *
@@ -129,6 +156,11 @@ async function createHumanQueueServer(options) {
         else if (escalation.status === 'pending' && detail.form_schema) {
             // The shape the resolver payload should take (fields + x-lt-bind paths).
             result.form_schema = detail.form_schema;
+            // Tell the agent when this role ENFORCES the form: an incomplete or
+            // mis-typed payload will be rejected with a schema_validation error.
+            if ((await (0, enforcement_cache_1.getEnforcingRoles)()).has(escalation.role)) {
+                result.schema_enforced = true;
+            }
         }
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
@@ -163,9 +195,13 @@ async function createHumanQueueServer(options) {
     // ── claim_and_resolve ───────────────────────────────────────────────
     server.registerTool('claim_and_resolve', {
         title: 'Claim and Resolve',
-        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation.',
+        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation. Roles with enforce_schema validate the payload against the form_schema (see check_resolution) and reject violations with a schema_validation error listing each field.',
         inputSchema: human_queue_schemas_1.claimAndResolveSchema,
     }, async (args) => {
+        // Validate BEFORE claiming — a rejected payload must never strand a claim.
+        const rejected = await checkResolveToolPayload(args.escalation_id, args.payload);
+        if (rejected)
+            return rejected;
         const claimed = await escalationService.claimEscalation(args.escalation_id, args.resolver_id, 5);
         if (!claimed) {
             return {
@@ -200,9 +236,12 @@ async function createHumanQueueServer(options) {
     // ── resolve_escalation ──────────────────────────────────────────────
     server.registerTool('resolve_escalation', {
         title: 'Resolve Escalation',
-        description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API).',
+        description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API). Roles with enforce_schema validate the payload against the form_schema (see check_resolution) and reject violations with a schema_validation error listing each field.',
         inputSchema: human_queue_schemas_1.resolveEscalationSchema,
     }, async (args) => {
+        const rejected = await checkResolveToolPayload(args.escalation_id, args.payload);
+        if (rejected)
+            return rejected;
         const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
         if (!resolved) {
             return {