@hotmeshio/long-tail 0.8.3 → 0.8.5

package/build/scripts/twin-farm.js

@@ -4,16 +4,19 @@
  *
  * Spins up the whole DIGITAL side of the physical/digital twin farm from one
  * command and plays every human part automatically, so a single run exercises
- * the full lifecycle: register → advertise → dispatch → print → settle, plus the
- * failure detour (cancel → service → back in the pool). The PHYSICAL side is the
- * app's farm-manager backend — `mock` by default (self-contained), or `http`
- * against a real print-farm-manager host once you wire the office up.
+ * the full lifecycle: onboard (register + bind) → advertise → dispatch → print →
+ * reconcile → settle, plus the failure detours (autonomous fail → inspect, and
+ * filament runout → change → resume). The PHYSICAL side is the app's Bambu
+ * backend — `BAMBU_BACKEND=mock` by default (a deterministic in-repo simulation),
+ * or `http` against a real Farm Manager Server once the office link is wired.
+ *
+ * Faults are injected deterministically via each order unit's `simOutcome` (the
+ * mock honors it), so the service escalations fire on demand — no racing.
  *
  * Usage:
  *   npm run twin:farm
  *   FLEET=6 ORDERS=10 UNITS=2 npm run twin:farm
- *   FAIL_PCT=25 npm run twin:farm                 # rehearse dead-machine → service
- *   FARM_MANAGER_URL=http://192.168.1.50:4000 npm run twin:farm   # preflight the office link
+ *   FAIL_PCT=30 FAIL_MODE=filament_runout npm run twin:farm   # fault → service → recover
  *   FLEET=4 ORDERS=4 KEEP=1 npm run twin:farm     # leave twins running to poke in the UI
  *
  * Env vars:
@@ -25,17 +28,13 @@
  *   FILAMENTS         comma-separated filament pool the fleet + orders draw from
  *                     (default "pla,petg")
  *   ARRIVAL_S         average seconds between order arrivals (default 2)
- *   FAIL_PCT          percent of print jobs to cancel mid-print, exercising the
- *                     service path (default 0). Best-effort: it races the
- *                     physical side, so raise MOCK_PRINT_SECONDS on the app for
- *                     a wider window (see README).
- *   POLL_MS           poll interval ms (default 750)
+ *   FAIL_PCT          percent of orders with one faulted unit (default 0)
+ *   FAIL_MODE         the injected fault: filament_runout | failed (default filament_runout)
+ *   POLL_MS           servicer/registrar poll interval ms (default 750)
  *   BROKER_IDLE       idle broker ticks before it self-terminates (default 40)
  *   RUN_BROKER        launch a broker (default 1; set 0 if one already runs)
  *   KEEP              1 = leave twins advertising at the end (default 0 = retire
  *                     them with a power-down so nothing lingers between runs)
- *   FARM_MANAGER_URL  optional: GET this before running and report reachability,
- *                     a preflight for the office laptop → farm-manager-host link
  *
  * Capabilities: each twin is registered with a capability profile (xl/pdac/soft).
  * By default the fleet is fully capable and only filament routes; set FLEET_CAPS
@@ -55,17 +54,17 @@ const UNITS = parseInt(process.env.UNITS || '2', 10);
 const FILAMENTS = (process.env.FILAMENTS || 'pla,petg').split(',').map((f) => f.trim()).filter(Boolean);
 const ARRIVAL_S = parseFloat(process.env.ARRIVAL_S || '2');
 const FAIL_PCT = parseInt(process.env.FAIL_PCT || '0', 10);
+const FAIL_MODE = (process.env.FAIL_MODE || 'filament_runout');
 const POLL_MS = parseInt(process.env.POLL_MS || '750', 10);
 const BROKER_IDLE = parseInt(process.env.BROKER_IDLE || '40', 10);
 const RUN_BROKER = process.env.RUN_BROKER !== '0';
 const KEEP = process.env.KEEP === '1';
-const FARM_MANAGER_URL = process.env.FARM_MANAGER_URL || '';
 const CAPABILITY_KEYS = ['xl', 'pdac', 'soft'];
 const MODELS = ['Fab-X1', 'Fab-X1C', 'Fab-P2', 'Fab-Mini'];
 let token = '';
 let userId = '';
 let done = false;
-const stats = { registered: 0, dispatched: 0, printed: 0, cancelled: 0, serviced: 0, settled: 0 };
+const stats = { registered: 0, dispatched: 0, printed: 0, faulted: 0, serviced: 0, settled: 0 };
 function ts() { return new Date().toISOString().slice(11, 19); }
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 function ageSeconds(iso) { return (Date.now() - new Date(iso).getTime()) / 1000; }
@@ -115,8 +114,9 @@ async function login() {
  */
 const TWIN_ROLE_CONFIG = [
     { role: 'print-jobs', title: 'Print Jobs', parent_role: null, sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Order demand — one print-job escalation per unit, claimed as a set.' },
-    { role: 'printer-fleet', title: 'Printer Fleet', parent_role: 'print-jobs', sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Twin availability adverts and in-flight print rows — the machines at work.', upstream_roles: ['print-servicer'] },
-    { role: 'print-servicer', title: 'Print Servicer', parent_role: null, sla_minutes: 10, target_per_hour: 10, priority_threshold_minutes: 10, description: 'Register unboxed machines and restore ones that fell offline.' },
+    { role: 'printer-fleet', title: 'Printer Fleet', parent_role: 'print-jobs', sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Twin availability adverts and in-flight print rows — the machines at work.', upstream_roles: ['print-onboarder', 'print-servicer'] },
+    { role: 'print-onboarder', title: 'Print Onboarder', parent_role: null, sla_minutes: 15, target_per_hour: 5, priority_threshold_minutes: 15, description: 'Register + bind a newly unboxed machine.' },
+    { role: 'print-servicer', title: 'Print Servicer', parent_role: null, sla_minutes: 10, target_per_hour: 10, priority_threshold_minutes: 10, description: 'Reload filament, inspect failures, restore offline machines.' },
 ];
 async function ensureTwinRoles() {
     const details = await api('GET', '/api/roles/details').catch(() => ({ roles: [] }));
@@ -160,6 +160,10 @@ function planFleet(batchTag) {
         return { printerId, wfId: printerId, filament, caps, model: MODELS[i % MODELS.length], serialNumber: `SN-${batchTag.slice(-6)}-${i}` };
     });
 }
+/** Evenly distribute FAIL_PCT across the order sequence (deterministic). */
+function hasFault(i) {
+    return Math.floor(((i + 1) * FAIL_PCT) / 100) > Math.floor((i * FAIL_PCT) / 100);
+}
 function planOrders(batchTag, fleet) {
     return Array.from({ length: ORDERS }, (_, i) => {
         const filament = FILAMENTS[i % FILAMENTS.length];
@@ -171,7 +175,8 @@ function planOrders(batchTag, fleet) {
         const cap = CAPABILITY_KEYS[i % CAPABILITY_KEYS.length];
         const capable = pool.filter((t) => t.caps[cap]).length;
         const require = (i % 2 === 0 && capable >= units) ? { [cap]: true } : {};
-        return { index: i, wfId: `${batchTag}-o${i}`, orderId: `TWIN-${batchTag.slice(-6)}-${i}`, filament, require, units };
+        const fault = hasFault(i) ? { unit: 0, mode: FAIL_MODE } : undefined;
+        return { index: i, wfId: `${batchTag}-o${i}`, orderId: `TWIN-${batchTag.slice(-6)}-${i}`, filament, require, units, fault };
     });
 }
 // ── Launch twins + broker + orders ────────────────────────────────────────────
@@ -198,7 +203,10 @@ async function placeOrder(spec) {
             orderId: spec.orderId,
             filament: spec.filament,
             require: spec.require,
-            units: Array.from({ length: spec.units }, (_, u) => ({ gcodeUrl: `https://example.com/${spec.orderId}-u${u}.gcode` })),
+            units: Array.from({ length: spec.units }, (_, u) => ({
+                gcodeUrl: `https://example.com/${spec.orderId}-u${u}.gcode`,
+                ...(spec.fault && spec.fault.unit === u ? { simOutcome: spec.fault.mode } : {}),
+            })),
             operatorId: userId,
         },
         metadata: { source: 'twin-farm' },
@@ -209,7 +217,7 @@ async function placeOrder(spec) {
 async function registerLoop(fleet) {
     while (!done) {
         try {
-            const resp = await api('GET', '/api/escalations/available?role=print-servicer&subtype=registering&limit=100');
+            const resp = await api('GET', '/api/escalations/available?role=print-onboarder&subtype=registering&limit=100');
             for (const esc of resp?.escalations ?? []) {
                 const spec = fleet.get(String(esc.metadata?.printerId ?? ''));
                 if (!spec)
@@ -238,17 +246,31 @@ async function registerLoop(fleet) {
             await sleep(POLL_MS);
     }
 }
-/** Resolve service escalations — the servicer realigning a downed machine. */
+/** The servicer's resolution for each escalation subtype the twin raises. Reloads
+ *  the SAME filament the machine had (from the escalation metadata) so a service
+ *  visit restores the machine rather than repurposing it. */
+function servicePayload(esc) {
+    const subtype = esc.subtype;
+    if (subtype === 'filament_change')
+        return { filamentLoaded: esc.metadata?.filament || 'pla', notes: 'Reloaded by twin-farm' };
+    if (subtype === 'failure_inspect')
+        return { action: 'reset', notes: 'Inspected by twin-farm' };
+    if (subtype === 'offline_investigate')
+        return { action: 'checked', notes: 'Reconnected by twin-farm' };
+    return { action: 'restored', notes: 'Auto-serviced by twin-farm' };
+}
+/** Resolve every servicer escalation (except registration) — filament changes,
+ *  failure inspections, offline investigations — the way a technician would. */
 async function serviceLoop() {
     while (!done) {
         try {
-            const resp = await api('GET', '/api/escalations/available?role=print-servicer&subtype=service&limit=100');
+            const resp = await api('GET', '/api/escalations/available?role=print-servicer&limit=100');
             for (const esc of resp?.escalations ?? []) {
                 await api('POST', `/api/escalations/${esc.id}/resolve`, {
-                    resolverPayload: { action: 'restored', notes: 'Auto-serviced by twin-farm' },
+                    resolverPayload: servicePayload(esc),
                 }).then(() => {
                     stats.serviced++;
-                    console.log(`[${ts()}]   [service]  ${esc.metadata?.printerId ?? esc.id.slice(0, 8)} restored [${stats.serviced}]`);
+                    console.log(`[${ts()}]   [service]  ${esc.subtype.padEnd(18)} ${esc.metadata?.printerId ?? esc.id.slice(0, 8)} [${stats.serviced}]`);
                 }).catch(() => { });
             }
         }
@@ -259,35 +281,6 @@ async function serviceLoop() {
             await sleep(POLL_MS);
     }
 }
-/** Cancel a deterministic fraction of in-flight prints — the power-outage /
- *  dead-machine drill. Best-effort: it races the physical side's resolve. */
-async function failLoop() {
-    if (FAIL_PCT <= 0)
-        return;
-    const acted = new Set();
-    while (!done) {
-        try {
-            const resp = await api('GET', '/api/escalations/available?role=printer-fleet&subtype=printing&limit=100');
-            for (const esc of resp?.escalations ?? []) {
-                const jobId = String(esc.metadata?.jobId ?? esc.id);
-                if (acted.has(jobId))
-                    continue;
-                if (jitter(jobId, 'fail') * 100 >= FAIL_PCT)
-                    continue;
-                acted.add(jobId);
-                await api('POST', `/api/escalations/${esc.id}/cancel`).then(() => {
-                    stats.cancelled++;
-                    console.log(`[${ts()}]   [FAIL]     cancelled print ${jobId} — machine went dark [${stats.cancelled}]`);
-                }).catch(() => { });
-            }
-        }
-        catch (err) {
-            logPollErr('fail', err);
-        }
-        if (!done)
-            await sleep(Math.min(POLL_MS, 300));
-    }
-}
 let lastPollErr = '';
 function logPollErr(loop, err) {
     const msg = `[${loop}] ${String(err?.message).slice(0, 80)}`;
@@ -316,7 +309,11 @@ async function orderLoop(orders) {
 async function settlementWatch(orders) {
     const settled = new Set();
     let stalled = 0;
-    const STALL_S = Math.max(40, ORDERS * (ARRIVAL_S + 8));
+    // Poll-driven twins add latency per order (poll pickup + print + report), and
+    // a fault adds a service round-trip, so the broker needs generous time to
+    // converge (it retries placement every tick via release-on-skip). This is a
+    // no-progress watchdog, not a deadline — steady settling keeps resetting it.
+    const STALL_S = Math.max(60, ORDERS * (ARRIVAL_S + 14));
     while (!done) {
         await sleep(1000);
         let progressed = false;
@@ -334,8 +331,9 @@ async function settlementWatch(orders) {
                     const ok = outcomes.filter((o) => o.outcome === 'success').length;
                     const bad = outcomes.length - ok;
                     stats.printed += ok;
+                    stats.faulted += bad;
                     stats.dispatched += outcomes.length;
-                    console.log(`[${ts()}]   [settle]   ${order.orderId} — ${ok} printed${bad ? `, ${bad} cancelled` : ''} [${stats.settled}/${ORDERS}]`);
+                    console.log(`[${ts()}]   [settle]   ${order.orderId} — ${ok} printed${bad ? `, ${bad} faulted` : ''} [${stats.settled}/${ORDERS}]`);
                 }
             }
             catch { /* 202 still running */ }
@@ -360,6 +358,10 @@ async function retireTwins(fleet) {
         console.log(`[${ts()}] KEEP=1 — leaving ${fleet.length} twins advertising`);
         return;
     }
+    if (stats.settled < ORDERS) {
+        console.log(`[${ts()}] ${stats.settled}/${ORDERS} settled — leaving twins up so the broker can finish (rerun with KEEP=1 to keep them)`);
+        return;
+    }
     await sleep(2000); // let any last twin re-advertise after a service visit
     let retired = 0;
     for (let sweep = 0; sweep < 4 && retired < fleet.length; sweep++) {
@@ -379,21 +381,6 @@ async function retireTwins(fleet) {
     }
     console.log(`[${ts()}] Retired ${retired} idle twin${retired === 1 ? '' : 's'}`);
 }
-// ── Optional office-link preflight ────────────────────────────────────────────
-async function preflightFarmManager() {
-    if (!FARM_MANAGER_URL)
-        return;
-    process.stdout.write(`[${ts()}] Preflight → ${FARM_MANAGER_URL} … `);
-    try {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), 4000);
-        const res = await fetch(FARM_MANAGER_URL, { signal: ctrl.signal }).finally(() => clearTimeout(t));
-        console.log(`reachable (HTTP ${res.status}). Set FARM_MANAGER_BACKEND=http + FARM_MANAGER_BASE_URL on the app to dispatch for real.`);
-    }
-    catch (err) {
-        console.log(`UNREACHABLE (${String(err?.message).slice(0, 60)}). Check the office wifi link — see the README connectivity walkthrough.`);
-    }
-}
 // ── Main ──────────────────────────────────────────────────────────────────────
 async function main() {
     const runId = Math.floor(Date.now() / 1000).toString();
@@ -401,17 +388,16 @@ async function main() {
     const fleet = planFleet(batchTag);
     const fleetById = new Map(fleet.map((t) => [t.printerId, t]));
     console.log(`\n  Twin Farm  ──  ${FLEET} printers, ${ORDERS} orders (≤${UNITS} units), filaments [${FILAMENTS.join(', ')}]`);
-    console.log(`  arrival=${ARRIVAL_S}s poll=${POLL_MS}ms fail=${FAIL_PCT}% broker=${RUN_BROKER ? `on (idle≤${BROKER_IDLE})` : 'external'} keep=${KEEP}`);
+    console.log(`  arrival=${ARRIVAL_S}s fail=${FAIL_PCT}% (${FAIL_MODE}) broker=${RUN_BROKER ? `on (idle≤${BROKER_IDLE})` : 'external'} keep=${KEEP}`);
     console.log(`  Server: ${BASE_URL}\n`);
     await login();
     await ensureTwinRoles();
-    await preflightFarmManager();
-    // 1. Launch the fleet — each twin raises a registration escalation and parks.
+    // 1. Launch the fleet — each twin onboards (register → bind) then advertises.
     console.log(`\n[${ts()}] Launching ${FLEET} twins …`);
     for (const spec of fleet)
         await startTwin(spec);
     // 2. Register + service loops start now so twins come online as they appear.
-    const humanLoops = [registerLoop(fleetById), serviceLoop(), failLoop()];
+    const humanLoops = [registerLoop(fleetById), serviceLoop()];
     // 3. Broker (once the humans are watching).
     if (RUN_BROKER) {
         await startBroker(batchTag);
@@ -433,7 +419,7 @@ async function main() {
     console.log(`\n[${ts()}] Done in ${elapsed}s`);
     console.log(`  Registered:  ${stats.registered}/${FLEET}`);
     console.log(`  Orders:      ${stats.settled}/${ORDERS} settled`);
-    console.log(`  Units:       ${stats.printed} printed${stats.cancelled ? `, ${stats.cancelled} cancelled` : ''} (${stats.dispatched} dispatched)`);
+    console.log(`  Units:       ${stats.printed} printed${stats.faulted ? `, ${stats.faulted} faulted` : ''} (${stats.dispatched} dispatched)`);
     console.log(`  Serviced:    ${stats.serviced}`);
     console.log(`\n  Dashboard: ${BASE_URL}/escalations\n`);
     process.exit(0);

package/build/sdk/index.d.ts

@@ -153,6 +153,14 @@ export declare function createClient(options?: LTClientOptions): {
             resolverPayload: Record<string, any>;
             metadata?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveAllOrNone: (input: {
+            items: Array<{
+                id: string;
+                resolverPayload: Record<string, any>;
+            }>;
+            metadata?: Record<string, any>;
+            requireClaimed?: boolean;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         releaseExpired: typeof escalationsApi.releaseExpiredClaims;
         updatePriority: (input: {
             ids: string[];

package/build/sdk/index.js

@@ -128,6 +128,7 @@ function createClient(options = {}) {
             resolve: bindAuth(escalationsApi.resolveEscalation, auth),
             resolveBySignalKey: bindAuth(escalationsApi.resolveBySignalKey, auth),
             resolveByIds: bindAuth(escalationsApi.resolveByIds, auth),
+            resolveAllOrNone: bindAuth(escalationsApi.resolveAllOrNone, auth),
             releaseExpired: escalationsApi.releaseExpiredClaims,
             updatePriority: bindAuth(escalationsApi.updatePriority, auth),
             bulkClaim: bindAuth(escalationsApi.bulkClaim, auth),

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

@@ -36,6 +36,42 @@ export declare function resolveEscalation(id: string, resolverPayload: Record<st
  * `resolveEscalation` (which delivers the signal).
  */
 export declare function resolveEscalationsByIds(ids: string[], resolverPayload: Record<string, any>, metadata?: Record<string, any>): Promise<LTEscalationRecord[]>;
+/**
+ * Resolve a SET of escalations atomically — every listed row resolves, each
+ * with its OWN resolverPayload, or none do. One SQL statement locks the rows
+ * in deterministic id order, applies per-row payloads, and commits each
+ * waiter's wake WITH its resolve. Unlike {@link resolveEscalationsByIds},
+ * rows backing a live `condition()` waiter are first-class here: each is
+ * woken with its own payload as the condition's return value.
+ *
+ * On failure NOTHING is written and `failed` names exactly the rows that
+ * blocked the batch (`not-found`, `already-resolved`, `already-cancelled`,
+ * `already-expired`, `assignee-mismatch`) — rows that were themselves
+ * resolvable stay pending and are not listed.
+ *
+ * `assertAssignee` (optional) additionally requires every row to be assigned
+ * to that principal, asserted inside the same guarded statement — closing the
+ * claim-race window for claim-then-resolve flows.
+ */
+export declare function resolveEscalationsAllOrNone(items: Array<{
+    id: string;
+    resolverPayload: Record<string, any>;
+}>, metadata?: Record<string, any>, assertAssignee?: string): Promise<{
+    ok: true;
+    escalations: LTEscalationRecord[];
+} | {
+    ok: false;
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * Fetch full records for a set of escalation IDs in one indexed query.
+ * Used by bulk orchestrators that need per-row context beyond the scope
+ * fields — signal routing shape, `metadata.form_schema` for redaction.
+ */
+export declare function getEscalationsByIds(ids: string[]): Promise<LTEscalationRecord[]>;
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.

package/build/services/escalation/crud.js

@@ -4,6 +4,8 @@ exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;
 exports.resolveEscalationsByIds = resolveEscalationsByIds;
+exports.resolveEscalationsAllOrNone = resolveEscalationsAllOrNone;
+exports.getEscalationsByIds = getEscalationsByIds;
 exports.getEscalationBySignalKey = getEscalationBySignalKey;
 exports.resolveEscalationBySignalKey = resolveEscalationBySignalKey;
 exports.cancelEscalation = cancelEscalation;
@@ -165,6 +167,57 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
     }
     return records;
 }
+/**
+ * Resolve a SET of escalations atomically — every listed row resolves, each
+ * with its OWN resolverPayload, or none do. One SQL statement locks the rows
+ * in deterministic id order, applies per-row payloads, and commits each
+ * waiter's wake WITH its resolve. Unlike {@link resolveEscalationsByIds},
+ * rows backing a live `condition()` waiter are first-class here: each is
+ * woken with its own payload as the condition's return value.
+ *
+ * On failure NOTHING is written and `failed` names exactly the rows that
+ * blocked the batch (`not-found`, `already-resolved`, `already-cancelled`,
+ * `already-expired`, `assignee-mismatch`) — rows that were themselves
+ * resolvable stay pending and are not listed.
+ *
+ * `assertAssignee` (optional) additionally requires every row to be assigned
+ * to that principal, asserted inside the same guarded statement — closing the
+ * claim-race window for claim-then-resolve flows.
+ */
+async function resolveEscalationsAllOrNone(items, metadata, assertAssignee) {
+    if (items.length === 0)
+        return { ok: true, escalations: [] };
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolveAllOrNone({ items, metadata, assertAssignee });
+    if (!result.ok)
+        return { ok: false, failed: result.failed };
+    const records = (0, map_1.toEscalationRecords)(result.entries);
+    for (const escalation of records) {
+        publishEscalationChange({
+            type: 'escalation.resolved',
+            source: 'service',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: escalation.id,
+            status: 'resolved',
+            data: {},
+        });
+    }
+    return { ok: true, escalations: records };
+}
+/**
+ * Fetch full records for a set of escalation IDs in one indexed query.
+ * Used by bulk orchestrators that need per-row context beyond the scope
+ * fields — signal routing shape, `metadata.form_schema` for redaction.
+ */
+async function getEscalationsByIds(ids) {
+    if (ids.length === 0)
+        return [];
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({ ids, limit: LOOKUP_LIMIT });
+    return (0, map_1.toEscalationRecords)(rows);
+}
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.

package/build/services/escalation/queries.d.ts

@@ -29,6 +29,19 @@ export declare function searchEscalationsFaceted(opts: {
     escalations: LTEscalationRecord[];
     total: number;
 }>;
+/**
+ * Single-query escalation read for the resolve UI: the escalation row PLUS the
+ * role's escalation form, resolved to the version the escalation pinned
+ * (`metadata.schema_version`) or the role's latest when unpinned, JOINed from the
+ * roles tables and returned as `form_schema`. The form is NOT stored on the
+ * escalation — it rides in from lt_role_schemas/lt_roles on this one query, so a
+ * versioned JIT UI costs no per-row space and one SQL call to render. The version
+ * cast is guarded, so a non-numeric pin simply falls through to the latest form.
+ */
+export declare function getEscalationWithFormSchema(id: string): Promise<{
+    escalation: LTEscalationRecord;
+    form_schema: Record<string, any> | null;
+} | null>;
 /**
  * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
  * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the

package/build/services/escalation/queries.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchEscalationsFaceted = searchEscalationsFaceted;
+exports.getEscalationWithFormSchema = getEscalationWithFormSchema;
 exports.listFacetKeys = listFacetKeys;
 exports.getEscalationStats = getEscalationStats;
 exports.listDistinctTypes = listDistinctTypes;
@@ -143,6 +144,32 @@ async function searchEscalationsFaceted(opts) {
     ]);
     return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: countRows.rows[0]?.total ?? 0 };
 }
+/**
+ * Single-query escalation read for the resolve UI: the escalation row PLUS the
+ * role's escalation form, resolved to the version the escalation pinned
+ * (`metadata.schema_version`) or the role's latest when unpinned, JOINed from the
+ * roles tables and returned as `form_schema`. The form is NOT stored on the
+ * escalation — it rides in from lt_role_schemas/lt_roles on this one query, so a
+ * versioned JIT UI costs no per-row space and one SQL call to render. The version
+ * cast is guarded, so a non-numeric pin simply falls through to the latest form.
+ */
+async function getEscalationWithFormSchema(id) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(`SELECT e.*, COALESCE(ps.form_schema, r.form_schema) AS resolved_form_schema
+       FROM public.lt_escalations e
+       LEFT JOIN public.lt_roles r ON r.role = e.role
+       LEFT JOIN public.lt_role_schemas ps
+         ON ps.role = e.role
+        AND ps.version = CASE WHEN e.metadata->>'schema_version' ~ '^[0-9]+$'
+                              THEN (e.metadata->>'schema_version')::int END
+      WHERE e.id = $1`, [id]);
+    if (!rows[0])
+        return null;
+    const { resolved_form_schema, ...row } = rows[0];
+    const [escalation] = (0, map_1.toEscalationRecords)([row]);
+    return { escalation, form_schema: resolved_form_schema ?? null };
+}
 /**
  * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
  * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the

package/build/services/maintenance/index.js

@@ -38,6 +38,7 @@ const hotmesh_1 = require("@hotmeshio/hotmesh");
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const dbaService = __importStar(require("../dba"));
+const client_1 = require("../escalation/client");
 const CRON_TOPIC = 'lt.maintenance.prune';
 const CRON_ID = 'lt-maintenance-nightly';
 /**
@@ -84,6 +85,27 @@ async function executeRule(appId, rule) {
                 streams: false,
             });
             break;
+        // Age out terminal escalation rows (resolved/cancelled/expired). The
+        // engine-owned prune deletes at most one batch per call in one atomic
+        // statement; loop until the horizon is drained. Pending rows and live
+        // condition() waiters are never touched — every engine state transition
+        // guards on status='pending', so terminal rows are inert audit records.
+        case rule.target === 'escalations' && rule.action === 'delete': {
+            const client = await (0, client_1.escalations)();
+            let deleted = 0;
+            let batch;
+            do {
+                ({ deleted: batch } = await client.prune({
+                    olderThan: rule.olderThan,
+                    statuses: rule.statuses,
+                }));
+                deleted += batch;
+            } while (batch > 0);
+            if (deleted > 0) {
+                logger_1.loggerRegistry.info(`[lt-maintenance] escalations pruned: ${deleted} (olderThan: ${rule.olderThan})`);
+            }
+            break;
+        }
         default:
             logger_1.loggerRegistry.warn(`[lt-maintenance] unknown rule, skipping: ${JSON.stringify(rule)}`);
     }

package/build/services/orchestrator/condition.d.ts

@@ -1,10 +1,13 @@
 import type { Types } from '@hotmeshio/hotmesh';
 /**
  * HotMesh's escalation config plus long-tail sugar. `schemaVersion` pins the
- * role-schema version (lt_role_schemas) the resolver form should render; it is
- * folded into `metadata.schema_version` before the config reaches the engine,
- * so the pin rides the row's GIN-indexed metadata like any other facet. Omit
- * it and the resolver UI simply uses the role's latest schema.
+ * role form version (lt_role_schemas) the resolve UI renders; it is a
+ * compile-time LITERAL the workflow author sets, folded into
+ * `metadata.schema_version` before the config reaches the engine, so the pin
+ * rides the row's GIN-indexed metadata like any other facet. Folding is a pure
+ * transform — no query, no activity — so a pinned `conditionLT` costs exactly
+ * what an unpinned one does. Omit it and the resolve UI renders the role's latest
+ * form when the escalation is fetched.
  */
 export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
     schemaVersion?: number;
@@ -33,17 +36,20 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * });
  * ```
  *
- * **Pin the role schema version (optional).** Role form/metadata schemas are
- * versioned (lt_role_schemas). Set `schemaVersion` when this wait depends on a
- * specific shape — e.g. a review form that gained a field the workflow expects
- * back. The resolver UI renders exactly that version for this escalation;
- * without it, the role's latest schema always applies.
+ * **Pin the role form version — a compile-time literal.** A role's escalation
+ * form is versioned (lt_role_schemas); its first form is version 1. Pass the
+ * version as a literal, paired with the generic `<T>` payload type, both bumped
+ * together when the form evolves. The literal folds into metadata for the same
+ * cost as an unpinned wait. Omit it and the resolve UI renders the role's latest
+ * form when the escalation is fetched.
  *
  * ```typescript
- * const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
- *   role: 'reviewer',
+ * import { INTAKE_SCHEMA_VERSION, type IntakeResolverV1 } from './forms';
+ *
+ * const decision = await conditionLT<IntakeResolverV1>(signalId, {
+ *   role: INTAKE_ROLE,
  *   description: instructions,
- *   schemaVersion: 3,                     // render role schema v3 for this row
+ *   schemaVersion: INTAKE_SCHEMA_VERSION, // the form version this code is written for
  * });
  * ```
  *

package/build/services/orchestrator/condition.js

@@ -75,17 +75,20 @@ function toEngineConfig(escalation) {
  * });
  * ```
  *
- * **Pin the role schema version (optional).** Role form/metadata schemas are
- * versioned (lt_role_schemas). Set `schemaVersion` when this wait depends on a
- * specific shape — e.g. a review form that gained a field the workflow expects
- * back. The resolver UI renders exactly that version for this escalation;
- * without it, the role's latest schema always applies.
+ * **Pin the role form version — a compile-time literal.** A role's escalation
+ * form is versioned (lt_role_schemas); its first form is version 1. Pass the
+ * version as a literal, paired with the generic `<T>` payload type, both bumped
+ * together when the form evolves. The literal folds into metadata for the same
+ * cost as an unpinned wait. Omit it and the resolve UI renders the role's latest
+ * form when the escalation is fetched.
  *
  * ```typescript
- * const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
- *   role: 'reviewer',
+ * import { INTAKE_SCHEMA_VERSION, type IntakeResolverV1 } from './forms';
+ *
+ * const decision = await conditionLT<IntakeResolverV1>(signalId, {
+ *   role: INTAKE_ROLE,
  *   description: instructions,
- *   schemaVersion: 3,                     // render role schema v3 for this row
+ *   schemaVersion: INTAKE_SCHEMA_VERSION, // the form version this code is written for
  * });
  * ```
  *

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

@@ -61,8 +61,7 @@ export declare function listRoleSchemaVersions(role: string): Promise<RoleSchema
  */
 export declare function getRoleSchema(role: string, version?: number): Promise<RoleSchemaVersion | null>;
 /**
- * Fetch form_schema for a role (used as default escalation form when workflow
- * config does not specify a resolver_schema).
+ * Fetch a role's live form_schema — the escalation form the dashboard renders.
  */
 export declare function getRoleFormSchema(role: string): Promise<Record<string, any> | null>;
 /**

package/build/services/role/index.js

@@ -185,8 +185,7 @@ async function getRoleSchema(role, version) {
     return { ...rows[0], role };
 }
 /**
- * Fetch form_schema for a role (used as default escalation form when workflow
- * config does not specify a resolver_schema).
+ * Fetch a role's live form_schema — the escalation form the dashboard renders.
  */
 async function getRoleFormSchema(role) {
     const pool = (0, db_1.getPool)();

package/build/services/role/schema-validator.d.ts

@@ -0,0 +1,9 @@
+import { type ValidateFunction } from 'ajv';
+/**
+ * Compile (and cache) a validator for a role schema. Throws if the stored schema
+ * is not a valid JSON Schema — callers surface that as a 422 (the role admin's
+ * bug), distinct from a 400 (the submitter's payload does not match).
+ */
+export declare function compileSchemaValidator(cacheId: string, schema: Record<string, any>): ValidateFunction;
+/** Join a validator's errors into one human-readable line (instancePath + message). */
+export declare function formatValidationErrors(validate: ValidateFunction): string;