@hotmeshio/long-tail 0.7.1 → 0.7.3

package/build/api/escalations/create.js

@@ -40,22 +40,24 @@ exports.createEscalation = createEscalation;
 const ajv_1 = __importDefault(require("ajv"));
 const escalationService = __importStar(require("../../services/escalation"));
 const roleService = __importStar(require("../../services/role"));
+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, keyed by the schema's serialized form
-// so an admin's schema edit invalidates the stale validator on the next create.
+// 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(role, schema) {
+function compileRoleValidator(cacheId, schema) {
     const key = JSON.stringify(schema);
-    const cached = validatorCache.get(role);
+    const cached = validatorCache.get(cacheId);
     if (cached && cached.key === key)
         return cached.validate;
     const validate = ajv.compile(schema);
-    validatorCache.set(role, { key, validate });
+    validatorCache.set(cacheId, { key, validate });
     return validate;
 }
 // ── Create ────────────────────────────────────────────────────────────────
@@ -92,13 +94,29 @@ 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).
+        // 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 schema = await roleService.getRoleMetadataSchema(role);
+            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;
+            }
+            else {
+                schema = await roleService.getRoleMetadataSchema(role);
+            }
             if (schema) {
                 let validate;
                 try {
-                    validate = compileRoleValidator(role, schema);
+                    validate = compileRoleValidator(`${role}@${pinned ?? 'live'}`, schema);
                 }
                 catch (compileErr) {
                     // A broken stored schema is the role admin's bug, not the creator's —
@@ -108,7 +126,10 @@ async function createEscalation(input, auth) {
                         error: `metadata_schema for role "${role}" is not a valid JSON Schema: ${compileErr.message}`,
                     };
                 }
-                const valid = validate(input.metadata);
+                // 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}` };

package/build/api/roles.d.ts

@@ -91,6 +91,38 @@ export declare function updateRole(input: {
     sla_minutes?: number | null;
     target_per_hour?: number | null;
     worker_count?: number | null;
+    /** Replace the upstream-input set (omitted = preserve; null or [] = clear). */
+    upstream_roles?: string[] | null;
+    /** Recorded on the schema snapshot when this update changes a schema field. */
+    change_summary?: string;
+}): Promise<LTApiResult>;
+/**
+ * Fetch a role's schema pair (form_schema + metadata_schema).
+ *
+ * With `version`, returns that immutable snapshot from the version history —
+ * a missing version is a 404, never a silent fall-through to latest. Without
+ * `version`, returns the live (latest) schema along with the current version
+ * number so callers can tell what they got.
+ *
+ * @param input.role — the role whose schema to fetch
+ * @param input.version — optional version pin (positive integer)
+ * @returns `{ status: 200, data: RoleSchemaVersion }` on success
+ */
+export declare function getRoleSchema(input: {
+    role: string;
+    version?: number;
+}): Promise<LTApiResult>;
+/**
+ * List a role's schema version history, newest first. Each entry carries the
+ * version number, presence flags for the two schemas, the change summary, and
+ * whether it is the role's current version. Full snapshots come from
+ * `getRoleSchema({ role, version })`.
+ *
+ * @param input.role — the role whose history to list
+ * @returns `{ status: 200, data: { versions: RoleSchemaVersionSummary[] } }` on success
+ */
+export declare function listRoleSchemaVersions(input: {
+    role: string;
 }): Promise<LTApiResult>;
 /**
  * Delete a role from the system. Requires admin privileges.

package/build/api/roles.js

@@ -42,6 +42,8 @@ exports.removeEscalationChain = removeEscalationChain;
 exports.getEscalationTargets = getEscalationTargets;
 exports.replaceEscalationTargets = replaceEscalationTargets;
 exports.updateRole = updateRole;
+exports.getRoleSchema = getRoleSchema;
+exports.listRoleSchemaVersions = listRoleSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
 /**
@@ -220,6 +222,19 @@ async function updateRole(input) {
         if (input.parent_role != null && input.parent_role === input.role) {
             return { status: 400, error: 'parent_role must reference a different role' };
         }
+        if (input.upstream_roles != null) {
+            if (!Array.isArray(input.upstream_roles) || input.upstream_roles.some((u) => typeof u !== 'string' || !u.trim())) {
+                return { status: 400, error: 'upstream_roles must be an array of role names' };
+            }
+            if (input.upstream_roles.includes(input.role)) {
+                return { status: 400, error: 'upstream_roles must not include the role itself' };
+            }
+            const known = new Set(await roleService.listDistinctRoles());
+            const unknown = input.upstream_roles.filter((u) => !known.has(u));
+            if (unknown.length > 0) {
+                return { status: 400, error: `upstream_roles reference unknown role(s): ${unknown.join(', ')}` };
+            }
+        }
         const updated = await roleService.updateRoleMetadata(input.role, {
             title: input.title,
             description: input.description,
@@ -231,6 +246,8 @@ async function updateRole(input) {
             sla_minutes: input.sla_minutes,
             target_per_hour: input.target_per_hour,
             worker_count: input.worker_count,
+            upstream_roles: input.upstream_roles,
+            change_summary: input.change_summary,
         });
         if (!updated) {
             return { status: 404, error: `Role '${input.role}' not found` };
@@ -241,6 +258,62 @@ async function updateRole(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Fetch a role's schema pair (form_schema + metadata_schema).
+ *
+ * With `version`, returns that immutable snapshot from the version history —
+ * a missing version is a 404, never a silent fall-through to latest. Without
+ * `version`, returns the live (latest) schema along with the current version
+ * number so callers can tell what they got.
+ *
+ * @param input.role — the role whose schema to fetch
+ * @param input.version — optional version pin (positive integer)
+ * @returns `{ status: 200, data: RoleSchemaVersion }` on success
+ */
+async function getRoleSchema(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 1)) {
+            return { status: 400, error: 'version must be a positive integer' };
+        }
+        const schema = await roleService.getRoleSchema(input.role, input.version);
+        if (!schema) {
+            return {
+                status: 404,
+                error: input.version !== undefined
+                    ? `Schema version ${input.version} not found for role '${input.role}'`
+                    : `Role '${input.role}' not found`,
+            };
+        }
+        return { status: 200, data: schema };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List a role's schema version history, newest first. Each entry carries the
+ * version number, presence flags for the two schemas, the change summary, and
+ * whether it is the role's current version. Full snapshots come from
+ * `getRoleSchema({ role, version })`.
+ *
+ * @param input.role — the role whose history to list
+ * @returns `{ status: 200, data: { versions: RoleSchemaVersionSummary[] } }` on success
+ */
+async function listRoleSchemaVersions(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        const versions = await roleService.listRoleSchemaVersions(input.role);
+        return { status: 200, data: { versions } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Delete a role from the system. Requires admin privileges.
  *

package/build/bin/ltc.js

@@ -54,6 +54,7 @@ const pip = __importStar(require("../lib/cli/commands/pipelines"));
 const kb = __importStar(require("../lib/cli/commands/knowledge"));
 const mcp = __importStar(require("../lib/cli/commands/mcp"));
 const usr = __importStar(require("../lib/cli/commands/users"));
+const roles = __importStar(require("../lib/cli/commands/roles"));
 const streams = __importStar(require("../lib/cli/commands/streams"));
 const pkg = require('../package.json');
 const envPath = path.resolve(process.cwd(), '.env');
@@ -277,6 +278,28 @@ usrCmd.command('list')
 usrCmd.command('get <id>')
     .option('--json', 'JSON output')
     .action(wrap(usr.getUser));
+// ── Roles ────────────────────────────────────────────────────────────────
+const rolesCmd = commander_1.program.command('roles').description('Roles — the queue-backed work surfaces where workflows hand off to people');
+rolesCmd.command('list')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'Names only')
+    .action(wrap(roles.listRoles));
+rolesCmd.command('schema <role>')
+    .description('Show a role\'s form/metadata schema (latest, or a pinned version)')
+    .option('--version <n>', 'Read an immutable snapshot from the version history')
+    .option('--json', 'JSON output')
+    .action(wrap(roles.getRoleSchema));
+rolesCmd.command('schema-versions <role>')
+    .description('List a role\'s schema version history (newest first)')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'Versions only')
+    .action(wrap(roles.listRoleSchemaVersions));
+rolesCmd.command('save-schema <role>')
+    .description('Save the role\'s escalation form schema (a change creates the next version)')
+    .option('--file <path>', 'JSON Schema file (reads stdin when omitted)')
+    .option('--summary <text>', 'Change summary recorded on the new version')
+    .option('--json', 'JSON output')
+    .action(wrap(roles.saveRoleSchema));
 // ── Streams ─────────────────────────────────────────────────────────────
 const streamsCmd = commander_1.program.command('streams').description('Browse stream messages (admin)');
 streamsCmd.command('list')

package/build/lib/cli/commands/roles.d.ts

@@ -0,0 +1,17 @@
+export declare function listRoles(opts: {
+    json?: boolean;
+    quiet?: boolean;
+}): Promise<void>;
+export declare function getRoleSchema(role: string, opts: {
+    version?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function listRoleSchemaVersions(role: string, opts: {
+    json?: boolean;
+    quiet?: boolean;
+}): Promise<void>;
+export declare function saveRoleSchema(role: string, opts: {
+    file?: string;
+    summary?: string;
+    json?: boolean;
+}): Promise<void>;

package/build/lib/cli/commands/roles.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRoles = listRoles;
+exports.getRoleSchema = getRoleSchema;
+exports.listRoleSchemaVersions = listRoleSchemaVersions;
+exports.saveRoleSchema = saveRoleSchema;
+const fs = __importStar(require("fs"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const client_1 = require("../client");
+const format_1 = require("../format");
+const ROLE_COLUMNS = [
+    { key: 'role', label: 'Role', width: 20 },
+    { key: 'title', label: 'Title', width: 24 },
+    { key: 'current_schema_version', label: 'Schema v', width: 8, align: 'right' },
+    { key: 'user_count', label: 'Users', width: 6, align: 'right' },
+    { key: 'workflow_count', label: 'Workflows', width: 9, align: 'right' },
+];
+const VERSION_COLUMNS = [
+    { key: 'version', label: 'Version', width: 8, align: 'right' },
+    { key: 'is_current', label: 'Current', width: 8, format: (v) => (v ? '●' : '') },
+    { key: 'change_summary', label: 'Summary', width: 40 },
+    { key: 'created_at', label: 'Created', width: 12, format: format_1.formatTime },
+];
+async function listRoles(opts) {
+    const data = await (0, client_1.apiFetch)('/roles/details');
+    (0, format_1.output)(data, data.roles || [], ROLE_COLUMNS, opts, 'role');
+}
+async function getRoleSchema(role, opts) {
+    const params = new URLSearchParams();
+    if (opts.version)
+        params.set('version', opts.version);
+    const qs = params.toString();
+    const data = await (0, client_1.apiFetch)(`/roles/${encodeURIComponent(role)}/schema${qs ? `?${qs}` : ''}`);
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const versionLabel = data.version != null ? `v${data.version}` : 'unversioned';
+    const pinNote = opts.version ? ' (pinned)' : ` (latest: v${data.latest_version ?? '—'})`;
+    console.log(`\n  ${picocolors_1.default.bold(role)} schema ${versionLabel}${pinNote}`);
+    if (data.change_summary)
+        console.log(`  ${data.change_summary}`);
+    console.log(`\n  ${picocolors_1.default.bold('form_schema')}\n${JSON.stringify(data.form_schema, null, 2)}`);
+    console.log(`\n  ${picocolors_1.default.bold('metadata_schema')}\n${JSON.stringify(data.metadata_schema, null, 2)}`);
+    console.log();
+}
+async function listRoleSchemaVersions(role, opts) {
+    const data = await (0, client_1.apiFetch)(`/roles/${encodeURIComponent(role)}/schema/versions`);
+    (0, format_1.output)(data, data.versions || [], VERSION_COLUMNS, opts, 'version');
+}
+async function saveRoleSchema(role, opts) {
+    // One PATCH carrying only the schema (and its summary) — a schema change
+    // appends the next immutable version; an identical save leaves it alone.
+    const raw = opts.file ? fs.readFileSync(opts.file, 'utf8') : fs.readFileSync(0, 'utf8');
+    const schema = JSON.parse(raw);
+    const data = await (0, client_1.apiFetch)(`/roles/${encodeURIComponent(role)}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ form_schema: schema, change_summary: opts.summary }),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const version = data.current_schema_version != null ? ` — v${data.current_schema_version} in use` : '';
+    console.log(`\n  ${picocolors_1.default.green('✓')} Saved ${role} escalation schema${version}\n`);
+}

package/build/lib/db/schemas/017_role_schema_versions.sql

@@ -0,0 +1,40 @@
+-- Migration 017: Versioned role schemas
+--
+-- lt_role_schemas holds an immutable snapshot of a role's form_schema and
+-- metadata_schema per version. lt_roles.form_schema / metadata_schema remain
+-- the live "latest" copy (single-query reads stay cheap); every schema edit
+-- also appends the next (role, version) snapshot and advances
+-- lt_roles.current_schema_version — see UPDATE_ROLE_METADATA in
+-- services/role/sql.ts, which does both in one atomic statement.
+--
+-- Why: an escalation can pin the exact schema it was created against
+-- (metadata.schema_version, set via conditionLT's schemaVersion config field).
+-- The resolver UI then renders the pinned version even after the role's
+-- schema moves on. Escalations without a pin always use the latest.
+
+CREATE TABLE IF NOT EXISTS lt_role_schemas (
+  role            TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  version         INTEGER NOT NULL,
+  form_schema     JSONB,
+  metadata_schema JSONB,
+  change_summary  TEXT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (role, version)
+);
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS current_schema_version INTEGER;
+
+-- Seed version 1 from the live columns for roles that already carry a schema.
+-- ON CONFLICT keeps re-runs (and multi-container boot races behind the
+-- advisory lock) no-ops.
+INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
+SELECT role, 1, form_schema, metadata_schema, 'Initial version (seeded from lt_roles)'
+FROM lt_roles
+WHERE form_schema IS NOT NULL OR metadata_schema IS NOT NULL
+ON CONFLICT (role, version) DO NOTHING;
+
+UPDATE lt_roles
+SET current_schema_version = 1
+WHERE current_schema_version IS NULL
+  AND (form_schema IS NOT NULL OR metadata_schema IS NOT NULL);

package/build/lib/db/schemas/018_role_upstreams.sql

@@ -0,0 +1,21 @@
+-- Migration 018: Role upstream inputs
+--
+-- Execution is a graph; the Operations page tells its story as sequences.
+-- lt_roles.parent_role stays the sequence membership — the single "prior
+-- step" that places a station in one line. lt_role_upstreams carries the
+-- other edges: the roles a station draws input from that live in OTHER
+-- sequences (mixin-like, many allowed). The Operations chart renders these
+-- as a merge affordance on the station rather than bending the line —
+-- the table stays true to the queue, the SVG stays honest about the graph.
+--
+-- Example: a shoe side-quest (ordering → inserting) feeds shipping. ordering
+-- roots its own sequence; shipping declares inserting as an upstream input
+-- instead of pretending ordering descends from qa.
+
+CREATE TABLE IF NOT EXISTS lt_role_upstreams (
+  role          TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  upstream_role TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (role, upstream_role),
+  CHECK (role <> upstream_role)
+);

package/build/routes/roles.js

@@ -103,6 +103,26 @@ router.patch('/:role', auth_1.requireRoleManager, async (req, res) => {
     const result = await api.updateRole({ ...req.body, role: req.params.role });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/roles/:role/schema
+ * Fetch the role's schema pair. `?version=N` pins an immutable snapshot from
+ * the version history; omitted, the live (latest) schema is returned with its
+ * current version number.
+ */
+router.get('/:role/schema', async (req, res) => {
+    const versionParam = req.query.version;
+    const version = versionParam !== undefined ? Number(versionParam) : undefined;
+    const result = await api.getRoleSchema({ role: req.params.role, version });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/roles/:role/schema/versions
+ * List the role's schema version history (newest first).
+ */
+router.get('/:role/schema/versions', async (req, res) => {
+    const result = await api.listRoleSchemaVersions({ role: req.params.role });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/roles/:role/escalation-targets
  * Get allowed escalation targets for a specific role.

package/build/scripts/ortho-populate.d.ts

@@ -2,26 +2,73 @@
  * 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).
  */
 declare const BASE_URL: string;
 declare const ORDERS: number;
 declare const HOLD_S: number;
+declare const QUEUE_S: number;
+declare const SHOES_PCT: number;
+declare const ARRIVAL_S: number;
 declare const POLL_MS: number;
 declare const ORTHO_ROLES: string[];
+declare const SIDE_ROLES: string[];
+declare const ALL_ROLES: string[];
+declare const MFG_S: number;
+declare const TRANSIT_S: number;
+declare const INSERT_QUEUE_S: number;
+declare const ORDERING_QUEUE_S: number;
 declare let token: string;
 declare let userId: string;
 declare let totalClaimed: number;
@@ -29,9 +76,34 @@ declare let totalResolved: number;
 declare function ts(): string;
 declare function sleep(ms: number): Promise<unknown>;
 declare function ageSeconds(iso: string): number;
+declare function jitter(id: string, salt: string): number;
+/** Spread a base duration across 0.4×–1.6× so a stage's items trickle instead of toggling together. */
+declare function spread(base: number, r: number): number;
+/** Evenly distribute SHOES_PCT across the order sequence (deterministic). */
+declare function hasShoes(i: number): boolean;
+/** Queue wait before this escalation may be claimed. */
+declare function claimWaitFor(esc: {
+    id: string;
+    role: string;
+}): number;
+/** Hold time after claim before this escalation may be resolved. */
+declare function holdFor(esc: {
+    id: string;
+    role: string;
+}): number;
 declare function api(method: string, path: string, body?: unknown): Promise<any>;
 declare function login(): Promise<void>;
+declare function ensureSideQuestRoles(): Promise<void>;
+declare function createSideEscalation(role: string, workflowId: string, orderId: string, runId: string, description: string): Promise<boolean>;
 declare function claimBatch(batchTag: string): Promise<number>;
-declare function resolveBatch(batchTag: string): Promise<number>;
-declare function runOrders(batchTag: string, target: number): Promise<void>;
+declare function resolveBatch(batchTag: string, runId: string): Promise<number>;
+interface PlannedOrder {
+    index: number;
+    wfId: string;
+    orderId: string;
+    shoes: boolean;
+}
+declare function runOrders(batchTag: string, runId: string, plan: PlannedOrder[], target: {
+    value: number;
+}): Promise<string[]>;
 declare function main(): Promise<void>;