@hotmeshio/long-tail 0.10.1 → 0.10.3

package/build/services/role/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -73,6 +73,13 @@ exports.DELETE_ROLE = `
  * of the form/metadata pair: its own current_list_schema_version and its own
  * snapshot table (lt_role_list_schemas), so a list-view edit never advances the
  * resolve form's version. It shares $26 as the change summary.
+ *
+ * default_pins ($31 = provided sentinel, $32 = value) is unversioned config:
+ * the pinned-view seeds a role hands its members.
+ *
+ * enforce_schema ($33 = provided sentinel, $34 = value) is unversioned config:
+ * the server-side resolver-validation opt-in. The service layer invalidates
+ * the enforcement cache after this statement commits.
  */
 exports.UPDATE_ROLE_METADATA = `
   WITH updated AS (
@@ -91,6 +98,8 @@ exports.UPDATE_ROLE_METADATA = `
                       = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,
       priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,
       list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,
+      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,
+      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,
       current_schema_version = CASE
         WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)
           OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)
@@ -105,7 +114,8 @@ exports.UPDATE_ROLE_METADATA = `
       role, title, description, form_schema, metadata_schema, properties,
       ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,
       priority_threshold_minutes, priority_facet,
-      current_schema_version, list_schema, current_list_schema_version
+      current_schema_version, list_schema, current_list_schema_version,
+      default_pins, enforce_schema
   ), snapshot AS (
     INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
     SELECT role, current_schema_version, form_schema, metadata_schema, $26
@@ -130,6 +140,13 @@ exports.UPDATE_ROLE_METADATA = `
   SELECT * FROM updated`;
 exports.GET_ROLE_FORM_SCHEMA = `
   SELECT form_schema FROM lt_roles WHERE role = $1`;
+/**
+ * The set of roles with server-side resolver validation turned on. Small and
+ * slow-changing — the enforcement cache holds it under a short TTL so the
+ * resolve hot path costs zero SQL when no role (or no involved role) enforces.
+ */
+exports.LIST_ENFORCING_ROLES = `
+  SELECT role FROM lt_roles WHERE enforce_schema`;
 exports.GET_ROLE_METADATA_SCHEMA = `
   SELECT metadata_schema FROM lt_roles WHERE role = $1`;
 exports.GET_ROLE_UPSTREAMS = `
@@ -239,6 +256,8 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.current_schema_version,
     r.list_schema,
     r.current_list_schema_version,
+    r.default_pins,
+    r.enforce_schema,
     COALESCE(up.ups, '{}') AS upstream_roles,
     COALESCE(uc.cnt, 0) AS user_count,
     COALESCE(cc.cnt, 0) AS chain_count,

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

@@ -54,6 +54,24 @@ export interface RoleDetail {
     list_schema: Record<string, any> | null;
     /** Version of the live list_schema; null until the role first carries one. */
     current_list_schema_version: number | null;
+    /**
+     * When true, every resolve surface validates the submitted resolverPayload
+     * against the escalation's resolved form schema (same pass the dashboard
+     * runs) and rejects violations with 422 before any state changes. Opt-in
+     * per role; false leaves resolution behavior unchanged.
+     */
+    enforce_schema: boolean;
+    /**
+     * Pinned-view seeds this role hands its members: [{ label, url, badge? }].
+     * On first render, a member without an own pin of the same label sees these
+     * in their Pinned nav section (marked role-provided); users promote, hide,
+     * or reorder them through their own preferences. URLs only — never data.
+     */
+    default_pins: {
+        label: string;
+        url: string;
+        badge?: boolean;
+    }[] | null;
     /**
      * Roles this station draws input from that live in OTHER sequences.
      * parent_role is the single "prior step" placing the role in one sequence;
@@ -109,6 +127,11 @@ export interface UpdateRoleInput {
     metadata_schema?: Record<string, any> | null;
     /** JSON contract that richly formats this role's escalation list page. */
     list_schema?: Record<string, any> | null;
+    default_pins?: {
+        label: string;
+        url: string;
+        badge?: boolean;
+    }[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;
@@ -117,6 +140,8 @@ export interface UpdateRoleInput {
     worker_count?: number | null;
     priority_threshold_minutes?: number | null;
     priority_facet?: string | null;
+    /** Turn server-side resolver schema validation on/off for this role. */
+    enforce_schema?: boolean;
     /**
      * Replace the upstream-input set (omitted = preserve; null or [] = clear).
      * Every entry must name an existing role other than this one.

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

@@ -5,3 +5,4 @@ export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, h
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';
 export { verifyPassword } from './auth';
 export { seedAdmin } from './seed-admin';
+export { getPreferences, patchPreferences, PREFERENCES_MAX_BYTES } from './preferences';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = 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.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = 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");
@@ -39,3 +39,7 @@ var auth_1 = require("./auth");
 Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });
 var seed_admin_1 = require("./seed-admin");
 Object.defineProperty(exports, "seedAdmin", { enumerable: true, get: function () { return seed_admin_1.seedAdmin; } });
+var preferences_1 = require("./preferences");
+Object.defineProperty(exports, "getPreferences", { enumerable: true, get: function () { return preferences_1.getPreferences; } });
+Object.defineProperty(exports, "patchPreferences", { enumerable: true, get: function () { return preferences_1.patchPreferences; } });
+Object.defineProperty(exports, "PREFERENCES_MAX_BYTES", { enumerable: true, get: function () { return preferences_1.PREFERENCES_MAX_BYTES; } });

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

@@ -0,0 +1,15 @@
+/**
+ * Per-user preferences — a generic JSON store for presentation state (pinned
+ * views are the first tenant, not the schema). Preferences carry URLs and UI
+ * choices only, never data and never authorization.
+ */
+/** Server-side ceiling on the stored document (the API rejects beyond it). */
+export declare const PREFERENCES_MAX_BYTES: number;
+export declare function getPreferences(userId: string): Promise<Record<string, unknown>>;
+/**
+ * Shallow-merge `patch` into the user's preferences in ONE guarded UPDATE:
+ * top-level keys overwrite, a `null` value deletes its key, and the statement
+ * refuses to commit a document over the size cap (returns null → 413 at the
+ * API). No read-then-write — concurrent patches serialize on the row.
+ */
+export declare function patchPreferences(userId: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | null>;

package/build/services/user/preferences.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFERENCES_MAX_BYTES = void 0;
+exports.getPreferences = getPreferences;
+exports.patchPreferences = patchPreferences;
+const db_1 = require("../../lib/db");
+/**
+ * Per-user preferences — a generic JSON store for presentation state (pinned
+ * views are the first tenant, not the schema). Preferences carry URLs and UI
+ * choices only, never data and never authorization.
+ */
+/** Server-side ceiling on the stored document (the API rejects beyond it). */
+exports.PREFERENCES_MAX_BYTES = 32 * 1024;
+async function getPreferences(userId) {
+    const { rows } = await (0, db_1.getPool)().query('SELECT preferences FROM lt_users WHERE id = $1', [userId]);
+    return rows[0]?.preferences ?? {};
+}
+/**
+ * Shallow-merge `patch` into the user's preferences in ONE guarded UPDATE:
+ * top-level keys overwrite, a `null` value deletes its key, and the statement
+ * refuses to commit a document over the size cap (returns null → 413 at the
+ * API). No read-then-write — concurrent patches serialize on the row.
+ */
+async function patchPreferences(userId, patch) {
+    const deletions = Object.keys(patch).filter((k) => patch[k] === null);
+    const additions = {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v !== null)
+            additions[k] = v;
+    }
+    const { rows } = await (0, db_1.getPool)().query(`UPDATE lt_users u
+     SET preferences = ((COALESCE(u.preferences, '{}'::jsonb) || $2::jsonb) - $3::text[]),
+         updated_at = NOW()
+     WHERE u.id = $1
+       AND length(((COALESCE(u.preferences, '{}'::jsonb) || $2::jsonb) - $3::text[])::text) <= $4
+     RETURNING u.preferences`, [userId, JSON.stringify(additions), deletions, exports.PREFERENCES_MAX_BYTES]);
+    return rows[0]?.preferences ?? null;
+}

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

@@ -0,0 +1,45 @@
+export interface FieldError {
+    field: string;
+    message: string;
+}
+interface ChecklistItem {
+    id: string;
+    label: string;
+    required?: boolean;
+}
+/**
+ * Resolve a checklist widget's item definitions from its `x-lt-source`
+ * "domain.path" against the escalation context. Missing domain/path or a
+ * non-array value yields an empty list.
+ */
+export declare function resolveChecklistItems(sourcePath: unknown, ctx: Record<string, unknown> | undefined): ChecklistItem[];
+/**
+ * The checklist completion guard (`x-lt-require-all`): every rendered item must
+ * be checked, except items whose definition carries `required: false` (the
+ * explicit opt-out). Vacuous when the source resolves to no items — never
+ * blocks on zero. Returns the panel message, or undefined when satisfied.
+ * Stricter than (and composes with) the field-level required-array entry,
+ * which remains the at-least-one check.
+ */
+export declare function validateRequireAll(value: unknown, fieldSchema: Record<string, unknown> | undefined, ctx?: Record<string, unknown>): string | undefined;
+/**
+ * Runtime type check against the field's declared JSON Schema `type`. Guards
+ * the payload contract for API-first callers (a form widget already produces
+ * the right primitive; a script or agent submitting `"1"` for a number field
+ * does not). Absent/empty values pass — presence is the required check's job.
+ */
+export declare function validateFieldType(value: unknown, fieldSchema: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Per-field JSON Schema validation — subset used by the resolver form.
+ *
+ * Returns a human-readable error string when the value fails a constraint,
+ * or undefined when the value is valid. Callers are responsible for the
+ * required check (empty-when-required) before calling this for constraint checks.
+ *
+ * `ctx` is optional context (ShowIfContext-shaped) used to resolve dynamic
+ * constraint paths like `x-lt-minimum: "envelope.min_score"`.
+ */
+export declare function validateFieldConstraints(value: unknown, fieldSchema: Record<string, unknown> | undefined, ctx?: Record<string, unknown>): string | undefined;
+/** Full field error including required check then constraints. */
+export declare function validateField(value: unknown, fieldSchema: Record<string, unknown> | undefined, isRequired: boolean, isTouched: boolean, ctx?: Record<string, unknown>): string | undefined;
+export {};

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

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChecklistItems = resolveChecklistItems;
+exports.validateRequireAll = validateRequireAll;
+exports.validateFieldType = validateFieldType;
+exports.validateFieldConstraints = validateFieldConstraints;
+exports.validateField = validateField;
+/**
+ * Resolve a checklist widget's item definitions from its `x-lt-source`
+ * "domain.path" against the escalation context. Missing domain/path or a
+ * non-array value yields an empty list.
+ */
+function resolveChecklistItems(sourcePath, ctx) {
+    if (typeof sourcePath !== 'string' || !ctx)
+        return [];
+    const dot = sourcePath.indexOf('.');
+    if (dot === -1)
+        return [];
+    const domainObj = ctx[sourcePath.slice(0, dot)];
+    if (!domainObj || typeof domainObj !== 'object')
+        return [];
+    let cur = domainObj;
+    for (const p of sourcePath.slice(dot + 1).split('.')) {
+        cur = cur[p];
+        if (cur === undefined)
+            return [];
+    }
+    return Array.isArray(cur) ? cur : [];
+}
+/**
+ * The checklist completion guard (`x-lt-require-all`): every rendered item must
+ * be checked, except items whose definition carries `required: false` (the
+ * explicit opt-out). Vacuous when the source resolves to no items — never
+ * blocks on zero. Returns the panel message, or undefined when satisfied.
+ * Stricter than (and composes with) the field-level required-array entry,
+ * which remains the at-least-one check.
+ */
+function validateRequireAll(value, fieldSchema, ctx) {
+    if (fieldSchema?.['x-lt-widget'] !== 'checklist')
+        return undefined;
+    if (fieldSchema['x-lt-require-all'] !== true)
+        return undefined;
+    const items = resolveChecklistItems(fieldSchema['x-lt-source'], ctx);
+    const mandatory = items.filter((i) => i.required !== false);
+    if (mandatory.length === 0)
+        return undefined;
+    const state = (typeof value === 'object' && value !== null && !Array.isArray(value))
+        ? value
+        : {};
+    const incomplete = mandatory.filter((i) => !state[i.id]).length;
+    if (incomplete === 0)
+        return undefined;
+    return `${incomplete} of ${mandatory.length} checks incomplete`;
+}
+/**
+ * Runtime type check against the field's declared JSON Schema `type`. Guards
+ * the payload contract for API-first callers (a form widget already produces
+ * the right primitive; a script or agent submitting `"1"` for a number field
+ * does not). Absent/empty values pass — presence is the required check's job.
+ */
+function validateFieldType(value, fieldSchema) {
+    const declared = fieldSchema?.type;
+    if (typeof declared !== 'string')
+        return undefined;
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    switch (declared) {
+        case 'string':
+            return typeof value === 'string' ? undefined : 'Expected text';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? undefined : 'Expected a number';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value) ? undefined : 'Expected a whole number';
+        case 'boolean':
+            return typeof value === 'boolean' ? undefined : 'Expected true or false';
+        case 'array':
+            return Array.isArray(value) ? undefined : 'Expected a list';
+        case 'object':
+            return typeof value === 'object' && !Array.isArray(value) ? undefined : 'Expected an object';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Per-field JSON Schema validation — subset used by the resolver form.
+ *
+ * Returns a human-readable error string when the value fails a constraint,
+ * or undefined when the value is valid. Callers are responsible for the
+ * required check (empty-when-required) before calling this for constraint checks.
+ *
+ * `ctx` is optional context (ShowIfContext-shaped) used to resolve dynamic
+ * constraint paths like `x-lt-minimum: "envelope.min_score"`.
+ */
+function validateFieldConstraints(value, fieldSchema, ctx) {
+    if (!fieldSchema)
+        return undefined;
+    // Enum membership — the form's select widget constrains choices; API-first
+    // callers are unconstrained, so the schema's enum is the contract.
+    const allowed = fieldSchema.enum;
+    if (Array.isArray(allowed) && allowed.length > 0
+        && value !== undefined && value !== null && value !== ''
+        && !allowed.includes(value)) {
+        return `Must be one of: ${allowed.map((v) => String(v)).join(', ')}`;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (s === '')
+            return undefined; // empty string: required check is the caller's job
+        const minLength = resolveNumericConstraint(fieldSchema.minLength, fieldSchema['x-lt-min-length'], ctx);
+        if (minLength !== undefined && s.length < minLength) {
+            return `Minimum ${minLength} character${minLength === 1 ? '' : 's'}`;
+        }
+        const maxLength = resolveNumericConstraint(fieldSchema.maxLength, fieldSchema['x-lt-max-length'], ctx);
+        if (maxLength !== undefined && s.length > maxLength) {
+            return `Maximum ${maxLength} characters (${s.length} entered)`;
+        }
+        const pattern = fieldSchema.pattern;
+        if (pattern) {
+            try {
+                if (!new RegExp(pattern).test(s)) {
+                    const patternError = fieldSchema['x-lt-pattern-error'];
+                    return patternError ?? 'Invalid format';
+                }
+            }
+            catch {
+                // Malformed pattern in schema — silently skip
+            }
+        }
+        const fmt = fieldSchema.format;
+        if (fmt === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)) {
+            return 'Enter a valid email address';
+        }
+        if (fmt === 'uri' && !/^https?:\/\/.+/.test(s)) {
+            return 'Enter a valid URL';
+        }
+    }
+    if (typeof value === 'number') {
+        const minimum = resolveNumericConstraint(fieldSchema.minimum, fieldSchema['x-lt-minimum'], ctx);
+        const exclusiveMinimum = resolveNumericConstraint(fieldSchema.exclusiveMinimum, undefined, ctx);
+        const maximum = resolveNumericConstraint(fieldSchema.maximum, fieldSchema['x-lt-maximum'], ctx);
+        const exclusiveMaximum = resolveNumericConstraint(fieldSchema.exclusiveMaximum, undefined, ctx);
+        if (minimum !== undefined && value < minimum) {
+            return `Minimum value is ${minimum}`;
+        }
+        if (exclusiveMinimum !== undefined && value <= exclusiveMinimum) {
+            return `Must be greater than ${exclusiveMinimum}`;
+        }
+        if (maximum !== undefined && value > maximum) {
+            return `Maximum value is ${maximum}`;
+        }
+        if (exclusiveMaximum !== undefined && value >= exclusiveMaximum) {
+            return `Must be less than ${exclusiveMaximum}`;
+        }
+    }
+    return undefined;
+}
+function resolveNumericConstraint(staticVal, dynamicPath, ctx) {
+    if (typeof staticVal === 'number')
+        return staticVal;
+    if (typeof dynamicPath === 'string' && ctx) {
+        const dot = dynamicPath.indexOf('.');
+        if (dot !== -1) {
+            const domain = dynamicPath.slice(0, dot);
+            const path = dynamicPath.slice(dot + 1);
+            const domainObj = ctx[domain];
+            if (domainObj && typeof domainObj === 'object') {
+                const parts = path.split('.');
+                let cur = domainObj;
+                for (const p of parts) {
+                    cur = cur[p];
+                    if (cur === undefined)
+                        break;
+                }
+                if (typeof cur === 'number')
+                    return cur;
+                if (typeof cur === 'string') {
+                    const n = Number(cur);
+                    if (!Number.isNaN(n))
+                        return n;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Full field error including required check then constraints. */
+function validateField(value, fieldSchema, isRequired, isTouched, ctx) {
+    if (!isTouched)
+        return undefined;
+    if (isRequired) {
+        if (value === undefined || value === null)
+            return 'Required';
+        if (typeof value === 'boolean' && !value)
+            return 'Required';
+        if (typeof value === 'string' && value.trim() === '')
+            return 'Required';
+        if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
+            const vals = Object.values(value);
+            if (vals.length === 0 || vals.every((v) => !v))
+                return 'Required';
+        }
+    }
+    // Declared-type check runs before constraints: a mis-typed value would make
+    // the numeric/string constraint branches silently inapplicable.
+    const typeError = validateFieldType(value, fieldSchema);
+    if (typeError)
+        return typeError;
+    // Checklist completion — the stricter guard runs regardless of the
+    // required-array entry (which stays at-least-one when present).
+    const requireAll = validateRequireAll(value, fieldSchema, ctx);
+    if (requireAll)
+        return requireAll;
+    return validateFieldConstraints(value, fieldSchema, ctx);
+}

package/build/shared/form-validation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Isomorphic form-validation library for the x-lt-* enriched form_schema
+ * vocabulary. The dashboard renders and pre-validates resolver forms with it;
+ * the API layer enforces the same contract on every resolve surface. Pure
+ * functions only — no React, no DOM, no database.
+ */
+export * from './x-lt-bind';
+export * from './x-lt-help';
+export * from './x-lt-show-if';
+export * from './field-validator';
+export * from './validate-resolver-payload';

package/build/shared/form-validation/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Isomorphic form-validation library for the x-lt-* enriched form_schema
+ * vocabulary. The dashboard renders and pre-validates resolver forms with it;
+ * the API layer enforces the same contract on every resolve surface. Pure
+ * functions only — no React, no DOM, no database.
+ */
+__exportStar(require("./x-lt-bind"), exports);
+__exportStar(require("./x-lt-help"), exports);
+__exportStar(require("./x-lt-show-if"), exports);
+__exportStar(require("./field-validator"), exports);
+__exportStar(require("./validate-resolver-payload"), exports);

package/build/shared/form-validation/validate-resolver-payload.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The full pre-submission validation pass over a resolver form schema — the
+ * same pass on both sides of the wire. The dashboard runs it on the flat form
+ * values before submitting; the API layer runs it on the submitted (bound,
+ * nested) payload by inverting x-lt-bind first. Because both entry points
+ * funnel into one loop, a payload that passes the client panel passes the
+ * server gate, and a 422's violation list is exactly what the panel shows.
+ *
+ * Semantics per field:
+ *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
+ *     cannot see never blocks submission)
+ *   - required (schema.required membership), with checklist/empty-object rules
+ *   - declared-type check (string/number/integer/boolean/array/object)
+ *   - enum membership
+ *   - x-lt-require-all against the checklist items resolved from context
+ *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
+ *
+ * The showIf/`resolver.*` domain is always the FLAT form representation, so a
+ * condition like `resolver.approved` reads the same on both sides.
+ */
+import { type FieldError } from './field-validator';
+import { type ShowIfContext } from './x-lt-show-if';
+export type { FieldError } from './field-validator';
+/**
+ * The escalation-surface context the pass evaluates showIf conditions and
+ * dynamic constraints against. `resolver` is supplied by the pass itself
+ * (the flat form values under validation) — callers provide the rest.
+ */
+export type ResolverValidationContext = Omit<ShowIfContext, 'resolver'>;
+/**
+ * Validate FLAT form values against the form schema. This is the dashboard's
+ * entry point (the values the user edits, keyed by field name).
+ */
+export declare function validateResolverForm(schema: Record<string, unknown> | null | undefined, formValues: Record<string, unknown>, ctx?: ResolverValidationContext | null): FieldError[];
+/**
+ * Validate a SUBMITTED resolver payload (the bound, nested shape the workflow
+ * consumes) against the form schema. This is the API layer's entry point: the
+ * payload is inverted through each field's x-lt-bind path back to the flat
+ * form representation, then run through the same pass the client uses.
+ */
+export declare function validateResolverPayload(schema: Record<string, unknown> | null | undefined, payload: Record<string, unknown>, ctx?: ResolverValidationContext | null): FieldError[];

package/build/shared/form-validation/validate-resolver-payload.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateResolverForm = validateResolverForm;
+exports.validateResolverPayload = validateResolverPayload;
+/**
+ * The full pre-submission validation pass over a resolver form schema — the
+ * same pass on both sides of the wire. The dashboard runs it on the flat form
+ * values before submitting; the API layer runs it on the submitted (bound,
+ * nested) payload by inverting x-lt-bind first. Because both entry points
+ * funnel into one loop, a payload that passes the client panel passes the
+ * server gate, and a 422's violation list is exactly what the panel shows.
+ *
+ * Semantics per field:
+ *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
+ *     cannot see never blocks submission)
+ *   - required (schema.required membership), with checklist/empty-object rules
+ *   - declared-type check (string/number/integer/boolean/array/object)
+ *   - enum membership
+ *   - x-lt-require-all against the checklist items resolved from context
+ *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
+ *
+ * The showIf/`resolver.*` domain is always the FLAT form representation, so a
+ * condition like `resolver.approved` reads the same on both sides.
+ */
+const field_validator_1 = require("./field-validator");
+const x_lt_show_if_1 = require("./x-lt-show-if");
+const x_lt_bind_1 = require("./x-lt-bind");
+/**
+ * Validate FLAT form values against the form schema. This is the dashboard's
+ * entry point (the values the user edits, keyed by field name).
+ */
+function validateResolverForm(schema, formValues, ctx) {
+    if (!schema)
+        return [];
+    const properties = (schema.properties ?? {});
+    const required = new Set(schema.required ?? []);
+    const liveCtx = {
+        ...(ctx ?? {}),
+        resolver: formValues,
+    };
+    const errors = [];
+    for (const [field, fieldSchema] of Object.entries(properties)) {
+        if (!(0, x_lt_show_if_1.evaluateShowIf)(fieldSchema['x-lt-showIf'], liveCtx))
+            continue;
+        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field), true, liveCtx);
+        if (err)
+            errors.push({ field, message: err });
+    }
+    return errors;
+}
+/**
+ * Validate a SUBMITTED resolver payload (the bound, nested shape the workflow
+ * consumes) against the form schema. This is the API layer's entry point: the
+ * payload is inverted through each field's x-lt-bind path back to the flat
+ * form representation, then run through the same pass the client uses.
+ */
+function validateResolverPayload(schema, payload, ctx) {
+    if (!schema)
+        return [];
+    const formValues = (0, x_lt_bind_1.mapPayloadToForm)(payload, schema);
+    return validateResolverForm(schema, formValues, ctx);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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
+ */
+type PathSeg = {
+    key: string;
+} | {
+    index: number;
+};
+/** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
+export declare function parsePath(path: string): PathSeg[];
+/** Set `value` at `path` inside `root`, creating intermediate objects/arrays. */
+export declare function setDeep(root: Record<string, any>, path: string, value: unknown): void;
+/** Read the value at `path` inside `root` (undefined if any segment is missing). */
+export declare function getDeep(root: unknown, path: string): unknown;
+/** The bind path for a form property (its `x-lt-bind`, or the property name). */
+export declare function bindPathFor(propName: string, propDef: Record<string, any> | undefined): string;
+/**
+ * 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.
+ */
+export declare function mapFormToPayload(formValues: Record<string, any>, formSchema: Record<string, any> | null | undefined): Record<string, any>;
+/**
+ * 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).
+ */
+export declare function mapPayloadToForm(payload: Record<string, any> | null | undefined, formSchema: Record<string, any> | null | undefined): Record<string, any>;
+export {};