@hotmeshio/long-tail 0.8.2 → 0.8.4

package/build/api/escalations/create.js

@@ -32,34 +32,13 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
-const ajv_1 = __importDefault(require("ajv"));
 const escalationService = __importStar(require("../../services/escalation"));
 const roleService = __importStar(require("../../services/role"));
+const schema_validator_1 = require("../../services/role/schema-validator");
 const escalation_1 = require("../../types/escalation");
 const helpers_1 = require("./helpers");
-// strict: false — role metadata_schemas use the project's house extension
-// keywords (x-lt-widget etc., the same style as seeded form_schemas); Ajv 8's
-// strict mode throws at compile on any unknown keyword, which would turn every
-// metadata-bearing create for that role into a 500.
-const ajv = new ajv_1.default({ allErrors: true, strict: false });
-// Compiled validators cached per role+version, keyed by the schema's serialized
-// form so an admin's schema edit invalidates the stale validator on the next
-// create. Pinned versions are immutable, but the same key logic covers both.
-const validatorCache = new Map();
-function compileRoleValidator(cacheId, schema) {
-    const key = JSON.stringify(schema);
-    const cached = validatorCache.get(cacheId);
-    if (cached && cached.key === key)
-        return cached.validate;
-    const validate = ajv.compile(schema);
-    validatorCache.set(cacheId, { key, validate });
-    return validate;
-}
 // ── Create ────────────────────────────────────────────────────────────────
 /**
  * Create a standalone escalation (not tied to a workflow).
@@ -94,46 +73,26 @@ async function createEscalation(input, auth) {
         if (denied) {
             return { status: 403, error: `You must have write access to the "${role}" role or be a superadmin to create escalations for it` };
         }
-        // Validate metadata against the role's declared schema (if any). A
-        // metadata.schema_version pin selects that immutable snapshot; a pin that
-        // names a missing version is a 400, never a silent fall-through to latest.
-        if (input.metadata) {
-            const pinned = input.metadata[escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION];
-            if (pinned !== undefined && (!Number.isInteger(pinned) || pinned < 1)) {
-                return { status: 400, error: `metadata.${escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION} must be a positive integer` };
-            }
-            let schema;
-            if (pinned !== undefined) {
-                const snapshot = await roleService.getRoleSchema(role, pinned);
-                if (!snapshot) {
-                    return { status: 400, error: `Schema version ${pinned} does not exist for role "${role}"` };
-                }
-                schema = snapshot.metadata_schema;
+        // Validate the caller-supplied metadata against the role's metadata_schema
+        // (the queryable-facet contract). An escalation may carry a form-version pin
+        // (metadata.schema_version) chosen by the workflow author; that is a system
+        // key, not caller data, so it is excluded from validation. No version is
+        // stamped here — omitting it means the resolve UI renders the role's latest
+        // form at fetch time.
+        const metadata = input.metadata ?? {};
+        const metadataSchema = await roleService.getRoleMetadataSchema(role);
+        if (metadataSchema) {
+            let validate;
+            try {
+                validate = (0, schema_validator_1.compileSchemaValidator)(`${role}:meta`, metadataSchema);
             }
-            else {
-                schema = await roleService.getRoleMetadataSchema(role);
+            catch (compileErr) {
+                // A broken stored schema is the role admin's bug, not the creator's.
+                return { status: 422, error: `metadata_schema for role "${role}" is not a valid JSON Schema: ${compileErr.message}` };
             }
-            if (schema) {
-                let validate;
-                try {
-                    validate = compileRoleValidator(`${role}@${pinned ?? 'live'}`, schema);
-                }
-                catch (compileErr) {
-                    // A broken stored schema is the role admin's bug, not the creator's —
-                    // name it explicitly instead of surfacing an opaque 500.
-                    return {
-                        status: 422,
-                        error: `metadata_schema for role "${role}" is not a valid JSON Schema: ${compileErr.message}`,
-                    };
-                }
-                // The pin is a system key, not caller data — strip it so schemas with
-                // additionalProperties: false still validate the caller's bag.
-                const { [escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION]: _pin, ...callerMetadata } = input.metadata;
-                const valid = validate(callerMetadata);
-                if (!valid) {
-                    const msgs = (validate.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
-                    return { status: 400, error: `metadata does not match the role schema: ${msgs}` };
-                }
+            const { [escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION]: _pin, ...callerMetadata } = metadata;
+            if (!validate(callerMetadata)) {
+                return { status: 400, error: `metadata does not match the role schema: ${(0, schema_validator_1.formatValidationErrors)(validate)}` };
             }
         }
         const escalation = await escalationService.createEscalation({

package/build/api/escalations/resolve.js

@@ -60,7 +60,7 @@ const helpers_1 = require("./helpers");
  */
 async function resolveEscalation(input, auth) {
     try {
-        const { id, resolverPayload, metadata } = input;
+        const { id, metadata, resolverPayload } = input;
         if (!resolverPayload) {
             return { status: 400, error: 'resolverPayload is required' };
         }
@@ -82,6 +82,9 @@ async function resolveEscalation(input, auth) {
         const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
         if (denied)
             return denied;
+        // The resolver payload is stored exactly as submitted — its shape is the
+        // workflow's contract, formed by the caller (the React app maps the form to
+        // the payload via x-lt-bind before submitting). No server-side transform.
         // `metadata` (the outcome patch) is never written separately — it rides WITH the
         // resolverPayload to whichever path performs the resolve, so it merges inside the
         // single status='pending'-guarded UPDATE (HotMesh `resolve(metadata)`). Paths that
@@ -133,7 +136,7 @@ async function resolveEscalation(input, auth) {
  */
 async function resolveBySignalKey(input, auth) {
     try {
-        const { signalKey, resolverPayload, metadata } = input;
+        const { signalKey, metadata, resolverPayload } = input;
         if (!signalKey)
             return { status: 400, error: 'signalKey is required' };
         if (!resolverPayload)
@@ -147,6 +150,8 @@ async function resolveBySignalKey(input, auth) {
         const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
         if (denied)
             return { status: 404, error: 'Escalation not found' };
+        // The payload is delivered as the signal the parked workflow's condition()
+        // receives — stored exactly as submitted (the caller formed its shape).
         return resolveViaSignalKey(escalation, resolverPayload, metadata);
     }
     catch (err) {
@@ -166,12 +171,15 @@ async function resolveBySignalKey(input, auth) {
  */
 async function resolveByIds(input, auth) {
     try {
-        const { ids, resolverPayload, metadata } = input;
+        const { ids, metadata } = input;
         if (!Array.isArray(ids) || ids.length === 0) {
             return { status: 400, error: 'ids must be a non-empty array' };
         }
-        if (!resolverPayload)
+        if (!input.resolverPayload)
             return { status: 400, error: 'resolverPayload is required' };
+        // One pre-shaped payload for a homogeneous group of bookkeeping rows, stored
+        // as submitted — the caller forms the payload's shape.
+        const resolverPayload = input.resolverPayload;
         // Bulk resolve ("ack") is a write verb, gated PER ITEM: write_all roles may
         // resolve any item in the role; write_self roles may resolve only items assigned
         // to the caller (same rule single-resolve applies via assertWriteAccess). Global

package/build/api/escalations/single.js

@@ -51,14 +51,18 @@ const helpers_1 = require("./helpers");
  */
 async function getEscalation(input, auth) {
     try {
-        const escalation = await escalationService.getEscalation(input.id);
-        if (!escalation) {
+        // One query: the escalation plus its role's form, resolved to the version the
+        // row pinned (or the role's latest) and embedded as `form_schema`. The resolve
+        // UI renders from this without a second schema call, and the form is never
+        // stored on the row — it is JOINed in from the roles tables.
+        const detail = await escalationService.getEscalationWithFormSchema(input.id);
+        if (!detail) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const denied = await (0, helpers_1.assertReadAccess)(auth.userId, escalation);
+        const denied = await (0, helpers_1.assertReadAccess)(auth.userId, detail.escalation);
         if (denied)
             return denied;
-        return { status: 200, data: escalation };
+        return { status: 200, data: { ...detail.escalation, form_schema: detail.form_schema } };
     }
     catch (err) {
         return { status: 500, error: err.message };

package/build/api/roles.d.ts

@@ -83,6 +83,7 @@ export declare function updateRole(input: {
     role: string;
     title?: string | null;
     description?: string | null;
+    /** The escalation resolve FORM schema (the JIT UI). Fields may carry x-lt-bind. */
     form_schema?: Record<string, any> | null;
     metadata_schema?: Record<string, any> | null;
     properties?: Record<string, any> | null;

package/build/scripts/twin-farm.d.ts

@@ -0,0 +1,44 @@
+/**
+ * twin-farm — drive the printer-twin example end to end, effortlessly.
+ *
+ * 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: 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=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:
+ *   BASE_URL          long-tail API (default http://localhost:3000)
+ *   FLEET             printer twins to launch (default 4)
+ *   ORDERS            orders to place (default 6)
+ *   UNITS             max units per order (default 2; capped to the fleet that
+ *                     shares an order's filament, so every order is satisfiable)
+ *   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 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)
+ *
+ * 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
+ * to vary it (e.g. "xl,soft|pdac|full|full" — one spec per printer, pipe-separated,
+ * each a comma list of capabilities or "full"/"base"). Orders only ever require a
+ * capability the fleet can satisfy for the chosen filament and unit count.
+ */
+export {};

package/build/scripts/twin-farm.js

@@ -0,0 +1,427 @@
+"use strict";
+/**
+ * twin-farm — drive the printer-twin example end to end, effortlessly.
+ *
+ * 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: 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=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:
+ *   BASE_URL          long-tail API (default http://localhost:3000)
+ *   FLEET             printer twins to launch (default 4)
+ *   ORDERS            orders to place (default 6)
+ *   UNITS             max units per order (default 2; capped to the fleet that
+ *                     shares an order's filament, so every order is satisfiable)
+ *   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 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)
+ *
+ * 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
+ * to vary it (e.g. "xl,soft|pdac|full|full" — one spec per printer, pipe-separated,
+ * each a comma list of capabilities or "full"/"base"). Orders only ever require a
+ * capability the fleet can satisfy for the chosen filament and unit count.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+try {
+    require('dotenv/config');
+}
+catch { /* dotenv optional */ }
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const FLEET = parseInt(process.env.FLEET || '4', 10);
+const ORDERS = parseInt(process.env.ORDERS || '6', 10);
+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 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, 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; }
+// Deterministic per-item jitter — FNV-1a hash of a key into [0, 1). Stable
+// across polls, so a job's fail/no-fail verdict never flip-flops mid-run.
+function jitter(key, salt = '') {
+    let h = 2166136261;
+    for (const c of salt + key) {
+        h ^= c.charCodeAt(0);
+        h = Math.imul(h, 16777619);
+    }
+    return ((h >>> 0) % 1000) / 1000;
+}
+function spread(base, r) { return base * (0.4 + 1.2 * r); }
+// ── HTTP + auth (mirrors ortho-populate) ──────────────────────────────────────
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(`${method} ${path} → ${res.status}: ${JSON.stringify(data)}`);
+    return data;
+}
+async function login() {
+    const auth = await api('POST', '/api/auth/login', { username: 'superadmin', password: 'l0ngt@1l' });
+    token = auth.token;
+    userId = auth.user?.id || '';
+    if (!token) {
+        console.error('[auth] Login failed');
+        process.exit(1);
+    }
+    console.log(`[${ts()}] Logged in (userId ${userId.slice(0, 8)}…)`);
+}
+// ── Pace Board role config (idempotent — never clobbers admin tuning) ─────────
+/**
+ * Ensure the twin farm's roles are operationalized on the Pace Board. The
+ * startup seeder (examples/seed-twin.ts) normally owns this; the driver repeats
+ * it so `npm run twin:farm` populates the board even against an app that did not
+ * seed the examples. Only UNCONFIGURED roles (no title) are touched — a role an
+ * admin has tuned keeps its dials.
+ *
+ * Topology: print-jobs ─▶ printer-fleet  (production line), with print-servicer
+ * a side-quest root merging into the fleet.
+ */
+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-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: [] }));
+    const configured = new Map((details?.roles ?? []).map((r) => [r.role, r]));
+    // Create bare rows first — upstream_roles references must resolve.
+    for (const cfg of TWIN_ROLE_CONFIG) {
+        if (!configured.has(cfg.role))
+            await api('POST', '/api/roles', { role: cfg.role }).catch(() => { });
+    }
+    let applied = 0;
+    for (const cfg of TWIN_ROLE_CONFIG) {
+        const row = configured.get(cfg.role);
+        if (row?.title)
+            continue; // already configured — respect admin tuning
+        const { role, ...body } = cfg;
+        await api('PATCH', `/api/roles/${role}`, { ...body, ops_visible: true }).then(() => { applied++; }).catch((err) => {
+            console.warn(`[${ts()}]   ⚠ role ${role}: ${String(err.message).slice(0, 80)}`);
+        });
+    }
+    console.log(`[${ts()}] Pace Board roles ready (print-jobs → printer-fleet, print-servicer side)${applied ? ` — configured ${applied}` : ''}`);
+}
+function parseCapSpec(spec) {
+    const s = spec.trim().toLowerCase();
+    if (s === 'full' || s === '')
+        return { xl: true, pdac: true, soft: true };
+    if (s === 'base' || s === 'none')
+        return { xl: false, pdac: false, soft: false };
+    const set = { xl: false, pdac: false, soft: false };
+    for (const k of s.split(',').map((x) => x.trim())) {
+        if (CAPABILITY_KEYS.includes(k))
+            set[k] = true;
+    }
+    return set;
+}
+function planFleet(batchTag) {
+    const capSpecs = (process.env.FLEET_CAPS || '').split('|').map((s) => s.trim()).filter(Boolean);
+    return Array.from({ length: FLEET }, (_, i) => {
+        const filament = FILAMENTS[i % FILAMENTS.length];
+        const caps = capSpecs.length ? parseCapSpec(capSpecs[i % capSpecs.length]) : { xl: true, pdac: true, soft: true };
+        const printerId = `${batchTag}-p${i}`;
+        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];
+        const pool = fleet.filter((t) => t.filament === filament);
+        const units = Math.max(1, Math.min(UNITS, pool.length));
+        // Require a rotating capability only if enough printers of this filament have
+        // it — otherwise the order would never place. Proves capability routing when
+        // the fleet varies; a no-op (but still-threaded) facet when it's fully capable.
+        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 } : {};
+        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 ────────────────────────────────────────────
+async function startTwin(spec) {
+    await api('POST', '/api/workflows/printerTwin/invoke', {
+        workflowId: spec.wfId,
+        data: { printerId: spec.printerId, operatorId: userId },
+        metadata: { source: 'twin-farm' },
+    });
+}
+async function startBroker(batchTag) {
+    const wfId = `${batchTag}-broker`;
+    await api('POST', '/api/workflows/twinBroker/invoke', {
+        workflowId: wfId,
+        data: { brokerId: userId, tickSeconds: 1, idleTickSeconds: 3, maxIdleRuns: BROKER_IDLE },
+        metadata: { source: 'twin-farm' },
+    });
+    return wfId;
+}
+async function placeOrder(spec) {
+    await api('POST', '/api/workflows/twinOrder/invoke', {
+        workflowId: spec.wfId,
+        data: {
+            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`,
+                ...(spec.fault && spec.fault.unit === u ? { simOutcome: spec.fault.mode } : {}),
+            })),
+            operatorId: userId,
+        },
+        metadata: { source: 'twin-farm' },
+    });
+}
+// ── Human automation: the print-servicer ──────────────────────────────────────
+/** Resolve registration escalations — the servicer bringing a machine online. */
+async function registerLoop(fleet) {
+    while (!done) {
+        try {
+            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)
+                    continue;
+                await api('POST', `/api/escalations/${esc.id}/resolve`, {
+                    resolverPayload: {
+                        serialNumber: spec.serialNumber,
+                        model: spec.model,
+                        manufactureDate: '2026-01-15',
+                        filament: spec.filament,
+                        certifications: 'CE, RoHS',
+                        xl: spec.caps.xl, pdac: spec.caps.pdac, soft: spec.caps.soft,
+                        notes: 'Auto-registered by twin-farm',
+                    },
+                }).then(() => {
+                    stats.registered++;
+                    const c = CAPABILITY_KEYS.filter((k) => spec.caps[k]).join('+') || 'base';
+                    console.log(`[${ts()}]   [register] ${spec.printerId} — ${spec.model} ${spec.filament} (${c}) [${stats.registered}/${FLEET}]`);
+                }).catch(() => { });
+            }
+        }
+        catch (err) {
+            logPollErr('register', err);
+        }
+        if (!done)
+            await sleep(POLL_MS);
+    }
+}
+/** 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&limit=100');
+            for (const esc of resp?.escalations ?? []) {
+                await api('POST', `/api/escalations/${esc.id}/resolve`, {
+                    resolverPayload: servicePayload(esc),
+                }).then(() => {
+                    stats.serviced++;
+                    console.log(`[${ts()}]   [service]  ${esc.subtype.padEnd(18)} ${esc.metadata?.printerId ?? esc.id.slice(0, 8)} [${stats.serviced}]`);
+                }).catch(() => { });
+            }
+        }
+        catch (err) {
+            logPollErr('service', err);
+        }
+        if (!done)
+            await sleep(POLL_MS);
+    }
+}
+let lastPollErr = '';
+function logPollErr(loop, err) {
+    const msg = `[${loop}] ${String(err?.message).slice(0, 80)}`;
+    if (msg !== lastPollErr) {
+        console.warn(`[${ts()}]   ⚠ ${msg}`);
+        lastPollErr = msg;
+    }
+}
+// ── Order arrival + settlement watch ──────────────────────────────────────────
+async function orderLoop(orders) {
+    for (const order of orders) {
+        if (done)
+            break;
+        try {
+            await placeOrder(order);
+            const req = Object.keys(order.require).length ? ` require:${Object.keys(order.require).join('+')}` : '';
+            console.log(`[${ts()}]   [order]    ${order.index + 1}/${orders.length} ${order.orderId} — ${order.filament} ×${order.units}${req}`);
+        }
+        catch (err) {
+            console.error(`[${ts()}]   [order]    ${order.orderId} FAILED: ${String(err.message).slice(0, 100)}`);
+        }
+        await sleep(spread(ARRIVAL_S, jitter(order.wfId, 'arrive')) * 1000);
+    }
+}
+/** Poll each order's result; a settled order returns its outcomes. */
+async function settlementWatch(orders) {
+    const settled = new Set();
+    let stalled = 0;
+    // 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;
+        for (const order of orders) {
+            if (settled.has(order.wfId))
+                continue;
+            try {
+                const resp = await api('GET', `/api/workflows/${order.wfId}/result`);
+                const data = resp?.result?.data;
+                if (data && data.completedAt !== undefined) {
+                    settled.add(order.wfId);
+                    progressed = true;
+                    stats.settled++;
+                    const outcomes = data.outcomes ?? [];
+                    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} faulted` : ''} [${stats.settled}/${ORDERS}]`);
+                }
+            }
+            catch { /* 202 still running */ }
+        }
+        if (stats.settled >= ORDERS) {
+            done = true;
+            break;
+        }
+        stalled = progressed ? 0 : stalled + 1;
+        if (stalled && stalled % 10 === 0)
+            console.log(`[${ts()}]   … ${stats.settled}/${ORDERS} settled — waiting (${stalled}s quiet)`);
+        if (stalled >= STALL_S) {
+            console.warn(`[${ts()}]   ⚠ stalled ${stalled}s at ${stats.settled}/${ORDERS} — stopping`);
+            done = true;
+            break;
+        }
+    }
+}
+// ── Teardown: retire idle twins so nothing lingers ────────────────────────────
+async function retireTwins(fleet) {
+    if (KEEP) {
+        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++) {
+        try {
+            const resp = await api('GET', '/api/escalations/available?role=printer-fleet&subtype=ready&limit=200');
+            for (const esc of resp?.escalations ?? []) {
+                try {
+                    await api('POST', `/api/escalations/${esc.id}/resolve`, { resolverPayload: { powerdown: true } });
+                    retired++;
+                }
+                catch { /* claimed or already gone */ }
+            }
+        }
+        catch { /* ignore */ }
+        if (retired < fleet.length)
+            await sleep(1500);
+    }
+    console.log(`[${ts()}] Retired ${retired} idle twin${retired === 1 ? '' : 's'}`);
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+    const runId = Math.floor(Date.now() / 1000).toString();
+    const batchTag = `twin-${runId}`;
+    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 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();
+    // 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()];
+    // 3. Broker (once the humans are watching).
+    if (RUN_BROKER) {
+        await startBroker(batchTag);
+        console.log(`[${ts()}] Broker running`);
+    }
+    // 4. Wait for the fleet to register before placing demand (so orders place).
+    const registerDeadline = Date.now() + 30_000;
+    while (stats.registered < FLEET && Date.now() < registerDeadline && !done)
+        await sleep(500);
+    if (stats.registered < FLEET)
+        console.warn(`[${ts()}] ⚠ only ${stats.registered}/${FLEET} registered — placing orders anyway`);
+    // 5. Orders arrive; settlement watch drives the run to completion.
+    const orders = planOrders(batchTag, fleet);
+    console.log(`\n[${ts()}] Placing ${ORDERS} orders …\n`);
+    const startMs = Date.now();
+    await Promise.all([orderLoop(orders), settlementWatch(orders), ...humanLoops.map((p) => p.catch(() => { }))]);
+    const elapsed = ((Date.now() - startMs) / 1000).toFixed(1);
+    await retireTwins(fleet);
+    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.faulted ? `, ${stats.faulted} faulted` : ''} (${stats.dispatched} dispatched)`);
+    console.log(`  Serviced:    ${stats.serviced}`);
+    console.log(`\n  Dashboard: ${BASE_URL}/escalations\n`);
+    process.exit(0);
+}
+main().catch((err) => { console.error(err); process.exit(1); });