@hotmeshio/long-tail 0.7.1 → 0.7.2

package/build/scripts/ortho-populate.js

@@ -3,20 +3,58 @@
  * ortho-populate — Populate the Operations dashboard with ortho pipeline history.
  *
  * Adapted from the boilerplate's 08-day-resolver.ts pattern:
- *   - concurrent claim loop + resolve loop + watchdog via Promise.all
+ *   - concurrent enqueue + claim loop + resolve loop + watchdog via Promise.all
  *   - hold time read from esc.claimed_at (API), not tracked in memory
  *   - simple resolve payload { approved: true, station: role }
  *
  * Usage:
  *   npx ts-node scripts/ortho-populate.ts
  *   ORDERS=50 HOLD_S=3 npx ts-node scripts/ortho-populate.ts
- *   ORDERS=5  HOLD_S=0 POLL_MS=500 npx ts-node scripts/ortho-populate.ts
+ *   ORDERS=10 HOLD_S=25 npx ts-node scripts/ortho-populate.ts
+ *   ORDERS=5  HOLD_S=0 QUEUE_S=0 SHOES_PCT=0 POLL_MS=500 npx ts-node scripts/ortho-populate.ts
  *
  * Env vars:
- *   ORDERS    — number of orders to run (default 20)
- *   HOLD_S    — seconds to hold each escalation before resolving (default 2)
- *   POLL_MS   — poll interval ms (default 1000)
- *   BASE_URL  — server URL (default http://localhost:3000)
+ *   ORDERS     — number of orders to run (default 20)
+ *   HOLD_S     — average seconds to hold each claimed escalation before
+ *                resolving (default 2)
+ *   QUEUE_S    — average seconds an escalation waits in the queue before being
+ *                claimed (default: HOLD_S). This is what builds a visible
+ *                backlog: on the Operations chart, queued-but-unclaimed and
+ *                claimed-and-worked are two different bands — with QUEUE_S=0
+ *                everything is claimed the moment it lands and pending always
+ *                equals active.
+ *   SHOES_PCT  — percent of orders that include shoes (default 50). A shoe
+ *                order runs the side-quest sequence (ordering → inserting)
+ *                alongside its manufacturing line — see below.
+ *   ARRIVAL_S  — average seconds between order arrivals (default: HOLD_S).
+ *                Orders trickle in at this rate instead of landing as one
+ *                wave, so the chart shows throughput, not a step function.
+ *   POLL_MS    — poll interval ms (default 1000)
+ *   BASE_URL   — server URL (default http://localhost:3000)
+ *
+ * All durations are per-item averages, not fixed delays: each escalation gets
+ * its own wait and hold spread across 0.4×–1.6× of the configured value (a
+ * stable hash of its id — no state to track between polls). That staggering is
+ * what makes the Operations chart read like a real floor: at any moment a
+ * station holds a mix of waiting and active items, claims burn the backlog
+ * down gradually, and resolves feed the next station a trickle instead of a
+ * wave.
+ *
+ * ── The shoe side-quest ──────────────────────────────────────────────────────
+ * A shoe order exercises the cross-sequence model (ordering → inserting feeds
+ * ship via upstream_roles — its own Operations sequence, not a bend in the
+ * main line). Timing tells the physical story, scaled to the manufacturing
+ * duration (MFG ≈ 8 stages × (QUEUE_S + HOLD_S)):
+ *
+ *   arrival     ordering escalation created with the order
+ *   + ~½·QUEUE  claimed quickly — the shoes are on order, work is underway
+ *   + ~35% MFG  shoes arrive → ordering resolves → inserting created
+ *   + ~35% MFG  inserting sits AVAILABLE (you cannot stuff inserts until the
+ *               insole is made) — a long sky band on its station
+ *   + HOLD      claimed and resolved just ahead of shipping
+ *
+ * The script provisions the side-quest roles idempotently on start (ordering,
+ * inserting under it, ship fed by inserting).
  */
 try {
     require('dotenv/config');
@@ -25,8 +63,18 @@ catch { }
 const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
 const ORDERS = parseInt(process.env.ORDERS || '20', 10);
 const HOLD_S = parseFloat(process.env.HOLD_S || '2');
+const QUEUE_S = parseFloat(process.env.QUEUE_S ?? String(HOLD_S));
+const SHOES_PCT = parseInt(process.env.SHOES_PCT || '50', 10);
+const ARRIVAL_S = parseFloat(process.env.ARRIVAL_S ?? String(HOLD_S));
 const POLL_MS = parseInt(process.env.POLL_MS || '1000', 10);
 const ORTHO_ROLES = ['design', 'review', 'print', 'grind', 'glue', 'finish', 'qa', 'ship'];
+const SIDE_ROLES = ['ordering', 'inserting'];
+const ALL_ROLES = [...ORTHO_ROLES, ...SIDE_ROLES];
+// Average end-to-end manufacturing time — the side-quest paces derive from it.
+const MFG_S = ORTHO_ROLES.length * (QUEUE_S + HOLD_S);
+const TRANSIT_S = 0.35 * MFG_S; // shoes underway with the vendor (held)
+const INSERT_QUEUE_S = 0.35 * MFG_S; // inserting waits available for inserts
+const ORDERING_QUEUE_S = 0.5 * QUEUE_S; // shoes get ordered promptly
 let token = '';
 let userId = '';
 let totalClaimed = 0;
@@ -34,6 +82,35 @@ let totalResolved = 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; }
+// Deterministic per-item jitter — FNV-1a hash of the escalation id into [0, 1).
+// Stable across polls, so each item has one fixed wait and one fixed hold
+// without any bookkeeping.
+function jitter(id, salt) {
+    let h = 2166136261;
+    for (const c of salt + id) {
+        h ^= c.charCodeAt(0);
+        h = Math.imul(h, 16777619);
+    }
+    return ((h >>> 0) % 1000) / 1000;
+}
+/** Spread a base duration across 0.4×–1.6× so a stage's items trickle instead of toggling together. */
+function spread(base, r) { return base * (0.4 + 1.2 * r); }
+/** Evenly distribute SHOES_PCT across the order sequence (deterministic). */
+function hasShoes(i) {
+    return Math.floor(((i + 1) * SHOES_PCT) / 100) > Math.floor((i * SHOES_PCT) / 100);
+}
+/** Queue wait before this escalation may be claimed. */
+function claimWaitFor(esc) {
+    const base = esc.role === 'ordering' ? ORDERING_QUEUE_S
+        : esc.role === 'inserting' ? INSERT_QUEUE_S
+            : QUEUE_S;
+    return spread(base, jitter(esc.id, 'queue'));
+}
+/** Hold time after claim before this escalation may be resolved. */
+function holdFor(esc) {
+    const base = esc.role === 'ordering' ? TRANSIT_S : HOLD_S;
+    return spread(base, jitter(esc.id, 'hold'));
+}
 // ── HTTP helper (mirrors boilerplate 07-shared) ───────────────────────────────
 async function api(method, path, body) {
     const res = await fetch(`${BASE_URL}${path}`, {
@@ -60,22 +137,66 @@ async function login() {
     }
     console.log(`[${ts()}] Logged in (userId: ${userId.slice(0, 8)}…)`);
 }
-// ── Claim: grab available ortho-stage escalations for this run ────────────────
+// ── Side-quest role provisioning (idempotent) ─────────────────────────────────
+async function ensureSideQuestRoles() {
+    for (const role of SIDE_ROLES) {
+        await api('POST', '/api/roles', { role }).catch(() => { });
+    }
+    await api('PATCH', '/api/roles/ordering', {
+        title: 'Ordering', ops_visible: true, target_per_hour: 22,
+    });
+    await api('PATCH', '/api/roles/inserting', {
+        title: 'Inserting', ops_visible: true, parent_role: 'ordering', target_per_hour: 22,
+    });
+    // ship draws from inserting across sequences — union, never clobber.
+    const details = await api('GET', '/api/roles/details');
+    const ship = (details?.roles ?? []).find((r) => r.role === 'ship');
+    const upstreams = ship?.upstream_roles ?? [];
+    if (!upstreams.includes('inserting')) {
+        await api('PATCH', '/api/roles/ship', { upstream_roles: [...upstreams, 'inserting'] });
+    }
+    console.log(`[${ts()}] Side-quest roles ready (ordering → inserting ⇒ ship)`);
+}
+// ── Side-quest escalations (standalone rows — no workflow behind them) ────────
+async function createSideEscalation(role, workflowId, orderId, runId, description) {
+    try {
+        await api('POST', '/api/escalations', {
+            type: 'ortho-stage',
+            subtype: role,
+            role,
+            description,
+            workflow_id: workflowId,
+            envelope: JSON.stringify({ order_id: orderId }),
+            metadata: { order_id: orderId, source: 'populate', run_id: runId },
+        });
+        return true;
+    }
+    catch (err) {
+        console.error(`[${ts()}]   [${role}] create error: ${String(err.message).slice(0, 80)}`);
+        return false;
+    }
+}
+// ── Claim: grab available escalations for this run once their wait elapses ────
 async function claimBatch(batchTag) {
     try {
         const resp = await api('GET', '/api/escalations/available?type=ortho-stage&limit=100&sort_by=created_at&order=asc');
         const escalations = resp?.escalations ?? [];
         let claimed = 0;
         for (const esc of escalations) {
-            if (!ORTHO_ROLES.includes(esc.role))
+            if (!ALL_ROLES.includes(esc.role))
                 continue;
             if (!String(esc.workflow_id ?? '').includes(batchTag))
                 continue;
+            // Let the item sit in the queue first — this is the unclaimed backlog the
+            // Operations chart renders as the "waiting" band above the active band.
+            // Each item gets its own wait so the backlog burns down gradually.
+            if (esc.created_at && ageSeconds(esc.created_at) < claimWaitFor(esc))
+                continue;
             try {
                 await api('POST', `/api/escalations/${esc.id}/claim`, { durationMinutes: 600 });
                 totalClaimed++;
                 claimed++;
-                console.log(`[${ts()}]   [claim]   ${esc.role.padEnd(8)} ${esc.id.slice(0, 8)}… [${totalClaimed} total]`);
+                console.log(`[${ts()}]   [claim]   ${esc.role.padEnd(9)} ${esc.id.slice(0, 8)}… [${totalClaimed} total]`);
             }
             catch (err) {
                 const msg = String(err.message).slice(0, 80);
@@ -92,18 +213,21 @@ async function claimBatch(batchTag) {
     }
 }
 // ── Resolve: drain all claimed+held escalations for this run ─────────────────
-async function resolveBatch(batchTag) {
+async function resolveBatch(batchTag, runId) {
     try {
         const resp = await api('GET', `/api/escalations?type=ortho-stage&status=pending&assigned_to=${userId}&limit=100&sort_by=created_at&order=asc`);
         const escalations = resp?.escalations ?? [];
         let resolved = 0;
         for (const esc of escalations) {
-            if (!ORTHO_ROLES.includes(esc.role))
+            if (!ALL_ROLES.includes(esc.role))
                 continue;
             if (!String(esc.workflow_id ?? '').includes(batchTag))
                 continue;
+            // Per-item hold: some resolvers are quick, some slow — resolves trickle
+            // out and feed the next station a steady stream instead of a wave.
+            // ordering holds for the vendor transit time instead of a work hold.
             const heldS = esc.claimed_at ? ageSeconds(esc.claimed_at) : 0;
-            if (heldS < HOLD_S)
+            if (heldS < holdFor(esc))
                 continue;
             try {
                 await api('POST', `/api/escalations/${esc.id}/resolve`, {
@@ -111,7 +235,13 @@ async function resolveBatch(batchTag) {
                 });
                 totalResolved++;
                 resolved++;
-                console.log(`[${ts()}]   [resolve] ${esc.role.padEnd(8)} ${esc.id.slice(0, 8)}… held ${heldS.toFixed(1)}s [${totalResolved} total]`);
+                console.log(`[${ts()}]   [resolve] ${esc.role.padEnd(9)} ${esc.id.slice(0, 8)}… held ${heldS.toFixed(1)}s [${totalResolved} total]`);
+                // Shoes arrived — the side quest advances to inserting, which sits
+                // available until the manufactured inserts catch up with it.
+                if (esc.role === 'ordering') {
+                    const orderId = esc.metadata?.order_id ?? '';
+                    await createSideEscalation('inserting', esc.workflow_id, orderId, runId, `Stuff inserts into shoes for ${orderId}`);
+                }
             }
             catch (err) {
                 console.error(`[${ts()}]   [resolve] ${esc.id.slice(0, 8)}… error: ${err.message.slice(0, 60)}`);
@@ -124,10 +254,38 @@ async function resolveBatch(batchTag) {
         return 0;
     }
 }
-// ── Run all orders through all 8 stages ───────────────────────────────────────
-async function runOrders(batchTag, target) {
+async function runOrders(batchTag, runId, plan, target) {
     let done = false;
-    // Claim loop — runs continuously until done.
+    const workflowIds = [];
+    // Enqueue loop — orders arrive at ARRIVAL_S pace (jittered), simulating
+    // intake throughput instead of one opening wave. A shoe order launches its
+    // ordering escalation the moment it lands.
+    const enqueueLoop = async () => {
+        for (const order of plan) {
+            if (done)
+                break;
+            try {
+                await api('POST', '/api/workflows/orthoPipeline/invoke', {
+                    workflowId: order.wfId,
+                    data: { order_id: order.orderId, item_type: 'insole-standard' },
+                    metadata: { source: 'populate', run_id: runId, shoes: order.shoes },
+                });
+                workflowIds.push(order.wfId);
+                console.log(`[${ts()}]   [arrive]  ${order.index + 1}/${plan.length} → ${order.wfId}${order.shoes ? ' +shoes' : ''}`);
+            }
+            catch (err) {
+                target.value -= 8 + (order.shoes ? 2 : 0);
+                console.error(`[${ts()}]   [arrive]  ${order.index + 1}/${plan.length} FAILED: ${err.message}`);
+                continue;
+            }
+            if (order.shoes) {
+                const ok = await createSideEscalation('ordering', `${order.wfId}-shoes`, order.orderId, runId, `Order shoes for ${order.orderId}`);
+                if (!ok)
+                    target.value -= 2;
+            }
+            await sleep(spread(ARRIVAL_S, jitter(order.wfId, 'arrive')) * 1000);
+        }
+    };
     const claimLoop = async () => {
         while (!done) {
             await claimBatch(batchTag);
@@ -135,22 +293,24 @@ async function runOrders(batchTag, target) {
                 await sleep(POLL_MS);
         }
     };
-    // Resolve loop — drains all held escalations each poll.
     const resolveLoop = async () => {
         while (!done) {
-            await resolveBatch(batchTag);
+            await resolveBatch(batchTag, runId);
             if (!done)
                 await sleep(POLL_MS);
         }
     };
-    // Watchdog — stops when target hit or stalled too long.
-    const STALL_S = Math.max(30, HOLD_S * 6);
+    // Watchdog — stops when target hit or stalled too long. Stages spend
+    // QUEUE_S unclaimed + HOLD_S claimed (the side quest waits longer but
+    // overlaps the main line, which keeps resolutions flowing), so the quiet
+    // window scales with both.
+    const STALL_S = Math.max(30, (HOLD_S + QUEUE_S) * 8);
     const watchdog = async () => {
         let lastResolved = totalResolved;
         let stalledFor = 0;
         while (!done) {
             await sleep(1000);
-            if (totalResolved >= target) {
+            if (totalResolved >= target.value) {
                 done = true;
                 break;
             }
@@ -161,51 +321,42 @@ async function runOrders(batchTag, target) {
             else {
                 stalledFor++;
                 if (stalledFor % 10 === 0) {
-                    console.log(`[${ts()}]   … ${totalResolved}/${target} resolved — waiting (${stalledFor}s quiet)`);
+                    console.log(`[${ts()}]   … ${totalResolved}/${target.value} resolved — waiting (${stalledFor}s quiet)`);
                 }
                 if (stalledFor >= STALL_S) {
-                    console.warn(`[${ts()}]   ⚠ stalled ${stalledFor}s with ${totalResolved}/${target} — stopping`);
+                    console.warn(`[${ts()}]   ⚠ stalled ${stalledFor}s with ${totalResolved}/${target.value} — stopping`);
                     done = true;
                     break;
                 }
             }
         }
     };
-    await Promise.all([claimLoop(), resolveLoop(), watchdog()]);
+    await Promise.all([enqueueLoop(), claimLoop(), resolveLoop(), watchdog()]);
+    return workflowIds;
 }
 // ── Main ─────────────────────────────────────────────────────────────────────
 async function main() {
-    console.log(`\n  Ortho Populate  ──  ${ORDERS} orders × 8 stages  (hold=${HOLD_S}s, poll=${POLL_MS}ms)`);
-    console.log(`  Server: ${BASE_URL}\n`);
-    await login();
     const runId = Math.floor(Date.now() / 1000).toString();
     const batchTag = `ortho-pop-${runId}`;
-    const workflowIds = [];
-    // Enqueue all orders.
-    console.log(`[${ts()}] Enqueuing ${ORDERS} orders…`);
-    for (let i = 0; i < ORDERS; i++) {
-        const wfId = `${batchTag}-${i}`;
-        try {
-            await api('POST', '/api/workflows/orthoPipeline/invoke', {
-                workflowId: wfId,
-                data: { order_id: `ORD-${runId}-${i}`, item_type: 'insole-standard' },
-                metadata: { source: 'populate', run_id: runId },
-            });
-            workflowIds.push(wfId);
-            console.log(`[${ts()}]   ${i + 1}/${ORDERS} → ${wfId}`);
-        }
-        catch (err) {
-            console.error(`[${ts()}]   ${i + 1}/${ORDERS} FAILED: ${err.message}`);
-        }
-    }
-    if (workflowIds.length === 0) {
-        console.error('Nothing enqueued — aborting');
-        process.exit(1);
-    }
-    const target = workflowIds.length * 8;
-    console.log(`\n[${ts()}] Running — target: ${target} resolutions (${workflowIds.length} orders × 8 stages)\n`);
+    const plan = Array.from({ length: ORDERS }, (_, i) => ({
+        index: i,
+        wfId: `${batchTag}-${i}`,
+        orderId: `ORD-${runId}-${i}`,
+        shoes: hasShoes(i),
+    }));
+    const shoeCount = plan.filter((o) => o.shoes).length;
+    // Each order resolves 8 manufacturing stages; a shoe order adds
+    // ordering + inserting on the side-quest sequence.
+    const target = { value: ORDERS * 8 + shoeCount * 2 };
+    console.log(`\n  Ortho Populate  ──  ${ORDERS} orders × 8 stages, ${shoeCount} with shoes (+2 each)`);
+    console.log(`  queue=${QUEUE_S}s hold=${HOLD_S}s arrival=${ARRIVAL_S}s shoes=${SHOES_PCT}% poll=${POLL_MS}ms`);
+    console.log(`  Side quest: transit≈${TRANSIT_S.toFixed(0)}s, inserting waits≈${INSERT_QUEUE_S.toFixed(0)}s (MFG≈${MFG_S.toFixed(0)}s)`);
+    console.log(`  Server: ${BASE_URL}\n`);
+    await login();
+    await ensureSideQuestRoles();
+    console.log(`\n[${ts()}] Running — target: ${target.value} resolutions\n`);
     const startMs = Date.now();
-    await runOrders(batchTag, target);
+    const workflowIds = await runOrders(batchTag, runId, plan, target);
     const elapsed = ((Date.now() - startMs) / 1000).toFixed(1);
     await sleep(2000);
     // Count completed workflows.
@@ -220,6 +371,7 @@ async function main() {
     }
     console.log(`\n[${ts()}] Done in ${elapsed}s`);
     console.log(`  Orders submitted:  ${workflowIds.length}`);
+    console.log(`  Orders with shoes: ${shoeCount}`);
     console.log(`  Orders completed:  ${completed}`);
     console.log(`  Claimed:           ${totalClaimed}`);
     console.log(`  Resolved:          ${totalResolved}`);

package/build/sdk/index.d.ts

@@ -273,6 +273,8 @@ export declare function createClient(options?: LTClientOptions): {
         create: typeof rolesApi.createRole;
         update: typeof rolesApi.updateRole;
         delete: typeof rolesApi.deleteRole;
+        getSchema: typeof rolesApi.getRoleSchema;
+        listSchemaVersions: typeof rolesApi.listRoleSchemaVersions;
         getEscalationChains: typeof rolesApi.getEscalationChains;
         addEscalationChain: typeof rolesApi.addEscalationChain;
         removeEscalationChain: typeof rolesApi.removeEscalationChain;

package/build/sdk/index.js

@@ -196,6 +196,8 @@ function createClient(options = {}) {
             create: rolesApi.createRole,
             update: rolesApi.updateRole,
             delete: rolesApi.deleteRole,
+            getSchema: rolesApi.getRoleSchema,
+            listSchemaVersions: rolesApi.listRoleSchemaVersions,
             getEscalationChains: rolesApi.getEscalationChains,
             addEscalationChain: rolesApi.addEscalationChain,
             removeEscalationChain: rolesApi.removeEscalationChain,

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

@@ -1,4 +1,14 @@
 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.
+ */
+export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
+    schemaVersion?: number;
+};
 /**
  * Wait for a signal and resolve the associated escalation automatically.
  *
@@ -23,6 +33,20 @@ import type { Types } from '@hotmeshio/hotmesh';
  * });
  * ```
  *
+ * **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.
+ *
+ * ```typescript
+ * const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
+ *   role: 'reviewer',
+ *   description: instructions,
+ *   schemaVersion: 3,                     // render role schema v3 for this row
+ * });
+ * ```
+ *
  * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
  * single wait arms a resume timer alongside the escalation row: when the timer
  * fires first, this helper returns `false`, the row transitions to
@@ -56,4 +80,4 @@ import type { Types } from '@hotmeshio/hotmesh';
  * const decision = await conditionLT<{ approved: boolean }>(signalId);
  * ```
  */
-export declare function conditionLT<T = Record<string, any>>(signalId: string, escalation?: Types.ConditionQueueConfig): Promise<T | false | null>;
+export declare function conditionLT<T = Record<string, any>>(signalId: string, escalation?: ConditionEscalationConfig): Promise<T | false | null>;

package/build/services/orchestrator/condition.js

@@ -35,8 +35,22 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.conditionLT = conditionLT;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
+const escalation_1 = require("../../types/escalation");
 const interceptorActivities = __importStar(require("../interceptor/activities"));
 const LT_ACTIVITY_QUEUE = 'lt-interceptor';
+/** Fold the schemaVersion sugar into metadata; pass everything else through. */
+function toEngineConfig(escalation) {
+    if (!escalation || escalation.schemaVersion == null)
+        return escalation;
+    const { schemaVersion, ...config } = escalation;
+    return {
+        ...config,
+        metadata: {
+            ...config.metadata,
+            [escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION]: schemaVersion,
+        },
+    };
+}
 /**
  * Wait for a signal and resolve the associated escalation automatically.
  *
@@ -61,6 +75,20 @@ const LT_ACTIVITY_QUEUE = 'lt-interceptor';
  * });
  * ```
  *
+ * **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.
+ *
+ * ```typescript
+ * const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
+ *   role: 'reviewer',
+ *   description: instructions,
+ *   schemaVersion: 3,                     // render role schema v3 for this row
+ * });
+ * ```
+ *
  * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
  * single wait arms a resume timer alongside the escalation row: when the timer
  * fires first, this helper returns `false`, the row transitions to
@@ -95,7 +123,7 @@ const LT_ACTIVITY_QUEUE = 'lt-interceptor';
  * ```
  */
 async function conditionLT(signalId, escalation) {
-    const raw = await hotmesh_1.Durable.workflow.condition(signalId, escalation);
+    const raw = await hotmesh_1.Durable.workflow.condition(signalId, toEngineConfig(escalation));
     // false = timeout, null = escalation was cancelled — propagate both as-is
     if (raw === null || raw === false)
         return raw;

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

@@ -1,4 +1,4 @@
-import type { EscalationChain, RoleDetail, UpdateRoleInput } from './types';
+import type { EscalationChain, RoleDetail, RoleSchemaVersion, RoleSchemaVersionSummary, UpdateRoleInput } from './types';
 /**
  * Get the roles a given source role can escalate to.
  */
@@ -46,6 +46,20 @@ export declare function createRole(role: string): Promise<boolean>;
  * resets to {}). One atomic UPDATE — see UPDATE_ROLE_METADATA.
  */
 export declare function updateRoleMetadata(role: string, input: UpdateRoleInput): Promise<RoleDetail | null>;
+/** Roles this station draws input from across other sequences. */
+export declare function getRoleUpstreams(role: string): Promise<string[]>;
+/**
+ * List the schema version history for a role (newest first). Schemas are
+ * elided — presence flags only; fetch a full snapshot via getRoleSchema.
+ */
+export declare function listRoleSchemaVersions(role: string): Promise<RoleSchemaVersionSummary[]>;
+/**
+ * Fetch a role's schema pair. With a version, reads the immutable snapshot
+ * from lt_role_schemas; without one, reads the live (latest) columns — a role
+ * that has never versioned its schema still answers with version null.
+ * Returns null when the role (or the requested version) does not exist.
+ */
+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).

package/build/services/role/index.js

@@ -10,6 +10,9 @@ exports.listDistinctRoles = listDistinctRoles;
 exports.listRolesWithDetails = listRolesWithDetails;
 exports.createRole = createRole;
 exports.updateRoleMetadata = updateRoleMetadata;
+exports.getRoleUpstreams = getRoleUpstreams;
+exports.listRoleSchemaVersions = listRoleSchemaVersions;
+exports.getRoleSchema = getRoleSchema;
 exports.getRoleFormSchema = getRoleFormSchema;
 exports.getRoleMetadataSchema = getRoleMetadataSchema;
 exports.deleteRole = deleteRole;
@@ -123,6 +126,7 @@ async function createRole(role) {
 async function updateRoleMetadata(role, input) {
     const pool = (0, db_1.getPool)();
     const provided = (key) => input[key] !== undefined;
+    const upstreams = [...new Set(input.upstream_roles ?? [])].sort();
     const { rows } = await pool.query(sql_1.UPDATE_ROLE_METADATA, [
         role,
         provided('title'), input.title ?? null,
@@ -135,8 +139,48 @@ async function updateRoleMetadata(role, input) {
         provided('sla_minutes'), input.sla_minutes ?? null,
         provided('target_per_hour'), input.target_per_hour ?? null,
         provided('worker_count'), input.worker_count ?? null,
+        input.change_summary ?? null,
+        provided('upstream_roles'), upstreams,
     ]);
-    return rows[0] ?? null;
+    if (!rows[0])
+        return null;
+    // The statement's CTEs share one snapshot, so the returned row cannot see
+    // the upstream sync it just performed — echo the write, or read when the
+    // field wasn't touched.
+    const upstream_roles = provided('upstream_roles')
+        ? upstreams
+        : await getRoleUpstreams(role);
+    return { ...rows[0], upstream_roles };
+}
+/** Roles this station draws input from across other sequences. */
+async function getRoleUpstreams(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_UPSTREAMS, [role]);
+    return rows.map((r) => r.upstream_role);
+}
+/**
+ * List the schema version history for a role (newest first). Schemas are
+ * elided — presence flags only; fetch a full snapshot via getRoleSchema.
+ */
+async function listRoleSchemaVersions(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_ROLE_SCHEMA_VERSIONS, [role]);
+    return rows;
+}
+/**
+ * Fetch a role's schema pair. With a version, reads the immutable snapshot
+ * from lt_role_schemas; without one, reads the live (latest) columns — a role
+ * that has never versioned its schema still answers with version null.
+ * Returns null when the role (or the requested version) does not exist.
+ */
+async function getRoleSchema(role, version) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = version != null
+        ? await pool.query(sql_1.GET_ROLE_SCHEMA_VERSION, [role, version])
+        : await pool.query(sql_1.GET_ROLE_SCHEMA_CURRENT, [role]);
+    if (!rows[0])
+        return null;
+    return { ...rows[0], role };
 }
 /**
  * Fetch form_schema for a role (used as default escalation form when workflow

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

@@ -21,11 +21,32 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * true the paired value is written (null clears; properties resets to '{}').
  * This is what lets the dashboard's per-tab saves and single-field MCP calls
  * coexist on the same row without read-modify-write.
+ *
+ * Schema versioning rides in the same statement: when a provided form_schema
+ * or metadata_schema actually differs from the stored value (IS DISTINCT FROM,
+ * evaluated against the pre-update row), current_schema_version advances and
+ * the post-update schema pair is snapshotted into lt_role_schemas. A no-change
+ * save leaves the version alone and the snapshot INSERT conflicts away.
+ * $22 = optional change summary recorded on the snapshot.
+ *
+ * Upstream inputs ($23 = provided sentinel, $24 = replacement set) sync in the
+ * same statement with replace semantics. The two CTEs deliberately avoid
+ * touching the same row: the DELETE only removes rows leaving the set, and the
+ * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
+ * SAME key in one statement would silently drop it — CTEs share a snapshot).
  */
-export declare const UPDATE_ROLE_METADATA = "\n  UPDATE lt_roles SET\n    title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n    description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n    form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n    metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n    properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n    ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n    parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n    sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n    target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n    worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END\n  WHERE role = $1\n  RETURNING\n    role, title, description, form_schema, metadata_schema, properties,\n    ops_visible, parent_role, sla_minutes, target_per_hour, worker_count";
+export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      current_schema_version\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $22\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $23::boolean AND role = $1 AND upstream_role <> ALL($24::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($24::text[]) AS u\n    WHERE $23::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
 export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  ORDER BY r.role";
+export declare const GET_ROLE_UPSTREAMS = "\n  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role";
+export declare const LIST_ROLE_SCHEMA_VERSIONS = "\n  SELECT\n    s.version,\n    s.form_schema IS NOT NULL     AS has_form_schema,\n    s.metadata_schema IS NOT NULL AS has_metadata_schema,\n    s.change_summary,\n    s.created_at,\n    s.version = r.current_schema_version AS is_current\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1\n  ORDER BY s.version DESC";
+export declare const GET_ROLE_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.form_schema, s.metadata_schema, s.change_summary,\n         s.created_at, r.current_schema_version AS latest_version\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1 AND s.version = $2";
+/**
+ * Latest schema resolves from the live lt_roles columns (a role that has never
+ * versioned its schema still answers, with version NULL).
+ */
+export declare const GET_ROLE_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_schema_version AS version, r.form_schema,\n         r.metadata_schema, s.change_summary, s.created_at,\n         r.current_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_schemas s\n    ON s.role = r.role AND s.version = r.current_schema_version\n  WHERE r.role = $1";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.current_schema_version,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";