@hotmeshio/long-tail 0.10.13 → 0.11.0

package/build/routes/escalations/index.js

@@ -7,6 +7,7 @@ const metadata_1 = require("./metadata");
 const single_1 = require("./single");
 const resolve_1 = require("./resolve");
 const facets_1 = require("./facets");
+const analytics_1 = require("./analytics");
 const router = (0, express_1.Router)();
 // Registration order matters: literal paths before parameterized /:id routes.
 // GET /, /available, /types, /stats
@@ -18,6 +19,8 @@ const router = (0, express_1.Router)();
 (0, metadata_1.registerMetadataRoutes)(router);
 // POST /search-by-facets, /claim-groups, /claim-by-facets
 (0, facets_1.registerFacetRoutes)(router);
+// POST /aggregate-by-facets, /timeline-by-facet
+(0, analytics_1.registerAnalyticsRoutes)(router);
 // PATCH /:id/escalate, GET /by-workflow/:workflowId,
 // GET /:id, POST /:id/claim, POST /:id/release
 (0, single_1.registerSingleRoutes)(router);

package/build/routes/escalations/resolve.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerResolveRoutes = registerResolveRoutes;
 const api = __importStar(require("../../api/escalations"));
+const acting_1 = require("./acting");
 function registerResolveRoutes(router) {
     /**
      * POST /api/escalations/resolve-by-signal-key
@@ -92,7 +93,13 @@ function registerResolveRoutes(router) {
      * Body: { resolverPayload: Record<string, any>, metadata?: Record<string, any> }
      */
     router.post('/:id/resolve', async (req, res) => {
-        const result = await api.resolveEscalation({ id: req.params.id, resolverPayload: req.body?.resolverPayload, metadata: req.body?.metadata }, req.auth);
+        // The actor is the token user — or the badged person when an
+        // X-LT-Acting-Token grant rides the request (station continuity: the
+        // person who claimed by badge submits by badge).
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.resolveEscalation({ id: req.params.id, resolverPayload: req.body?.resolverPayload, metadata: req.body?.metadata }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
 }

package/build/routes/escalations/single.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSingleRoutes = registerSingleRoutes;
 const api = __importStar(require("../../api/escalations"));
+const acting_1 = require("./acting");
 function registerSingleRoutes(router) {
     /**
      * PATCH /api/escalations/:id/escalate
@@ -67,20 +68,28 @@ function registerSingleRoutes(router) {
     });
     /**
      * POST /api/escalations/:id/claim
-     * Claim an escalation. userId comes from auth token.
+     * Claim an escalation. The actor is the auth token's user — or the badged
+     * person when an X-LT-Acting-Token grant rides the request.
      * Body: { durationMinutes?: number }
      */
     router.post('/:id/claim', async (req, res) => {
-        const result = await api.claimEscalation({ id: req.params.id, durationMinutes: req.body?.durationMinutes, provisionIfAbsent: req.body?.provisionIfAbsent }, req.auth);
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.claimEscalation({ id: req.params.id, durationMinutes: req.body?.durationMinutes, provisionIfAbsent: req.body?.provisionIfAbsent }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**
      * POST /api/escalations/:id/release
      * Release a claimed escalation back to the available pool.
-     * Only the assigned user may release their own claim.
+     * Only the assigned actor (token user, or the badged person when an
+     * X-LT-Acting-Token grant rides the request) may release their own claim.
      */
     router.post('/:id/release', async (req, res) => {
-        const result = await api.releaseEscalation({ id: req.params.id }, req.auth);
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.releaseEscalation({ id: req.params.id }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**

package/build/routes/roles.js

@@ -95,7 +95,7 @@ router.delete('/escalation-chains', auth_1.requireRoleManager, async (req, res)
 /**
  * PATCH /api/roles/:role
  * Update role metadata. Requires admin.
- * Body: { title?, description?, form_schema?, metadata_schema?, properties?, ops_visible?, parent_role?, sla_minutes?, target_per_hour?, worker_count?, priority_threshold_minutes?, priority_facet? }
+ * Body: { title?, description?, form_schema?, metadata_schema?, properties?, ops_visible?, parent_role?, sla_minutes?, target_per_hour?, worker_count?, priority_threshold_minutes?, priority_facet?, entity_facet?, entity_state_source? }
  */
 router.patch('/:role', auth_1.requireRoleManager, async (req, res) => {
     // URL is the resource identity — a `role` key in the body must not redirect

package/build/routes/scan-codes.js

@@ -40,11 +40,33 @@ const router = (0, express_1.Router)();
 // ── Execute ───────────────────────────────────────────────────────────────
 /**
  * POST /api/scan-codes/execute
- * Execute a raw scan code (from any input source) as the calling user.
+ * Execute a raw scan code (from any input source). Verbs run as the calling
+ * user, or as the badged person when an acting-identity grant rides along.
  * Every terminal state is a structured 200 outcome.
  */
 router.post('/execute', async (req, res) => {
-    const result = await api.executeScanCode({ code: req.body.code }, req.auth);
+    const result = await api.executeScanCode({
+        code: req.body.code,
+        actingToken: req.body.actingToken,
+        previousActingToken: req.body.previousActingToken,
+    }, req.auth);
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * POST /api/scan-codes/execute-choice
+ * Execute one choice presented by a PRESENT step. The body is a pointer
+ * (scheme/category/step/choice + escalationId); the server re-validates
+ * config, row state, identity, and RBAC before the verb runs.
+ */
+router.post('/execute-choice', async (req, res) => {
+    const result = await api.executeScanChoice({
+        schemeVersion: req.body.schemeVersion,
+        category: req.body.category,
+        stepIndex: req.body.stepIndex,
+        choiceIndex: req.body.choiceIndex,
+        escalationId: req.body.escalationId,
+        actingToken: req.body.actingToken,
+    }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 // ── Scheme CRUD (admin, engineer, superadmin) ─────────────────────────────
@@ -77,6 +99,9 @@ router.put('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
         encoding: req.body.encoding,
         delimiter: req.body.delimiter,
         target_length: req.body.target_length,
+        kind: req.body.kind,
+        grant_ttl_seconds: req.body.grant_ttl_seconds,
+        grant_max_uses: req.body.grant_max_uses,
         enabled: req.body.enabled,
     });
     res.status(result.status).json(result.data ?? { error: result.error });
@@ -120,6 +145,7 @@ router.put('/schemes/:version/actions/:category', auth_1.requireRoleManager, asy
         name: req.body.name,
         steps: req.body.steps,
         fallback: req.body.fallback,
+        notPrimed: req.body.notPrimed,
         enabled: req.body.enabled,
     });
     res.status(result.status).json(result.data ?? { error: result.error });

package/build/scripts/ortho-populate.js

@@ -162,6 +162,20 @@ async function ensureSideQuestRoles() {
         await api('PATCH', '/api/roles/ship', { upstream_roles: [...upstreams, 'inserting'] });
     }
     console.log(`[${ts()}] Side-quest roles ready (ordering → inserting ⇒ ship)`);
+    // Declare each station's entity: the order is what moves through every one
+    // of these roles, so entity_facet = 'order_id' unlocks distinct-order
+    // counts, per-order dwell, and order timelines on the Pace Board. Set only
+    // where unset — an operator-configured entity is never overwritten.
+    let declared = 0;
+    for (const role of ALL_ROLES) {
+        const detail = (details?.roles ?? []).find((r) => r.role === role);
+        if (!detail || detail.entity_facet)
+            continue;
+        await api('PATCH', `/api/roles/${role}`, { entity_facet: 'order_id' }).catch(() => { });
+        declared++;
+    }
+    if (declared > 0)
+        console.log(`[${ts()}] Entity declared on ${declared} role(s): order_id`);
 }
 // ── Side-quest escalations (standalone rows — no workflow behind them) ────────
 async function createSideEscalation(role, workflowId, orderId, runId, description, authorizedAt) {

package/build/scripts/printer-cycle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * printer-cycle — drive the seeded printer fleet through its states live.
+ *
+ * The flagship entity-analytics demo (examples/seed-fleet-sim.ts) seeds six
+ * printers with backdated history and one open interval each. This driver
+ * keeps the fleet moving: each printer dwells in its current state, then the
+ * open escalation resolves and the next state's escalation is created after a
+ * short untracked settle gap — exactly the authoring contract a real workflow
+ * follows with condition(). Watch /operations: the state band, slice-by, and
+ * per-printer timelines move within seconds of every transition.
+ *
+ * State machine per printer:  idle → printing → harvest → (service |) idle …
+ *
+ * Usage:
+ *   npx ts-node scripts/printer-cycle.ts
+ *   DWELL_SCALE=0.2 npx ts-node scripts/printer-cycle.ts   (5× faster)
+ *
+ * Env vars:
+ *   DWELL_SCALE — multiply every dwell/gap (default 1; smaller = faster demo)
+ *   CYCLES      — stop after each printer completes this many transitions
+ *                 (default: run until interrupted)
+ *   POLL_MS     — poll interval ms (default 1000)
+ *   BASE_URL    — server URL (default http://localhost:3000)
+ */
+export {};

package/build/scripts/printer-cycle.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * printer-cycle — drive the seeded printer fleet through its states live.
+ *
+ * The flagship entity-analytics demo (examples/seed-fleet-sim.ts) seeds six
+ * printers with backdated history and one open interval each. This driver
+ * keeps the fleet moving: each printer dwells in its current state, then the
+ * open escalation resolves and the next state's escalation is created after a
+ * short untracked settle gap — exactly the authoring contract a real workflow
+ * follows with condition(). Watch /operations: the state band, slice-by, and
+ * per-printer timelines move within seconds of every transition.
+ *
+ * State machine per printer:  idle → printing → harvest → (service |) idle …
+ *
+ * Usage:
+ *   npx ts-node scripts/printer-cycle.ts
+ *   DWELL_SCALE=0.2 npx ts-node scripts/printer-cycle.ts   (5× faster)
+ *
+ * Env vars:
+ *   DWELL_SCALE — multiply every dwell/gap (default 1; smaller = faster demo)
+ *   CYCLES      — stop after each printer completes this many transitions
+ *                 (default: run until interrupted)
+ *   POLL_MS     — poll interval ms (default 1000)
+ *   BASE_URL    — server URL (default http://localhost:3000)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+try {
+    require('dotenv/config');
+}
+catch { }
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const DWELL_SCALE = parseFloat(process.env.DWELL_SCALE || '1');
+const CYCLES = parseInt(process.env.CYCLES || '0', 10);
+const POLL_MS = parseInt(process.env.POLL_MS || '1000', 10);
+const FLEET_ROLE = 'printer-fleet';
+const HARVEST_ROLE = 'printer-harvest';
+const SERVICE_ROLE = 'printer-service';
+const ROLES = [FLEET_ROLE, HARVEST_ROLE, SERVICE_ROLE];
+const ENTITY_FACET = 'serialNumber';
+/** Seconds a printer dwells in each state (before DWELL_SCALE and jitter). */
+const DWELL_S = { idle: 45, printing: 120, harvest: 20, service: 60 };
+const GAP_S = 5; // untracked settle time between queues
+const STATES = {
+    idle: { role: FLEET_ROLE, subtype: 'idle' },
+    printing: { role: FLEET_ROLE, subtype: 'printing' },
+    harvest: { role: HARVEST_ROLE, subtype: 'harvest' },
+    service: { role: SERVICE_ROLE, subtype: 'service' },
+};
+let token = '';
+let transitions = 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-row jitter in [0, 1) — FNV-1a of the escalation id. */
+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;
+}
+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;
+    if (!token) {
+        console.error('[auth] Login failed');
+        process.exit(1);
+    }
+    console.log(`[${ts()}] Logged in`);
+}
+/** Self-heal the entity dials: declare where unset, never overwrite (S2). */
+async function ensureEntityDials() {
+    const details = await api('GET', '/api/roles/details').catch(() => ({ roles: [] }));
+    const byRole = new Map((details?.roles ?? []).map((r) => [r.role, r]));
+    for (const role of ROLES) {
+        const row = byRole.get(role);
+        if (!row) {
+            console.error(`[${ts()}] role ${role} is missing — run the seeded install first (docker compose up with examples)`);
+            process.exit(1);
+        }
+        if (row.entity_facet == null) {
+            await api('PATCH', `/api/roles/${role}`, {
+                entity_facet: ENTITY_FACET,
+                entity_state_source: role === FLEET_ROLE ? 'subtype' : 'role',
+            }).catch(() => { });
+            console.log(`[${ts()}] declared entity dials on ${role}`);
+        }
+    }
+}
+/** The state a printer enters after `current` — service follows ~⅓ of harvests. */
+function nextState(current, rowId) {
+    if (current === 'idle')
+        return 'printing';
+    if (current === 'printing')
+        return 'harvest';
+    if (current === 'harvest')
+        return jitter(rowId, 'svc') < 0.33 ? 'service' : 'idle';
+    return 'idle'; // service → back to the floor
+}
+async function transition(row) {
+    const serial = row.metadata?.[ENTITY_FACET];
+    const current = row.role === FLEET_ROLE ? row.subtype : row.role === HARVEST_ROLE ? 'harvest' : 'service';
+    const next = nextState(current, row.id);
+    await api('POST', `/api/escalations/${row.id}/resolve`, {
+        resolverPayload: { outcome: current, driver: 'printer-cycle' },
+    });
+    await sleep(GAP_S * DWELL_SCALE * 1000 * (0.5 + jitter(row.id, 'gap')));
+    const def = STATES[next];
+    await api('POST', '/api/escalations', {
+        type: 'fleet',
+        subtype: def.subtype,
+        role: def.role,
+        description: `${serial} — ${next}`,
+        priority: 3,
+        envelope: JSON.stringify({ source: 'printer-cycle' }),
+        metadata: { ...row.metadata },
+    });
+    transitions++;
+    console.log(`[${ts()}] ${serial}: ${current} → ${next}`);
+}
+/** Every live printer interval across the three queues. */
+async function liveRows() {
+    const params = new URLSearchParams({
+        status: 'pending',
+        roles: JSON.stringify(ROLES),
+        exists: JSON.stringify([ENTITY_FACET]),
+        limit: '200',
+    });
+    const data = await api('GET', `/api/escalations?${params}`);
+    return data.escalations ?? [];
+}
+async function main() {
+    console.log(`[${ts()}] printer-cycle starting (scale ${DWELL_SCALE}, ${CYCLES || '∞'} transitions/printer)`);
+    await login();
+    await ensureEntityDials();
+    const perPrinterCap = CYCLES > 0 ? CYCLES * 6 : Infinity; // 6 seeded printers
+    while (transitions < perPrinterCap) {
+        const rows = await liveRows();
+        if (rows.length === 0) {
+            console.log(`[${ts()}] no live printer intervals — seed the fleet first`);
+            break;
+        }
+        for (const row of rows) {
+            const state = row.role === FLEET_ROLE ? row.subtype : row.role === HARVEST_ROLE ? 'harvest' : 'service';
+            const dwell = (DWELL_S[state] ?? 30) * DWELL_SCALE * (0.6 + 0.8 * jitter(row.id, 'dwell'));
+            if (ageSeconds(row.created_at) >= dwell) {
+                await transition(row).catch((err) => console.error(`[${ts()}] transition failed: ${String(err.message).slice(0, 100)}`));
+            }
+        }
+        await sleep(POLL_MS);
+    }
+    console.log(`[${ts()}] done — ${transitions} transitions`);
+}
+main().catch((err) => { console.error(err); process.exit(1); });

package/build/scripts/twin-farm.js

@@ -111,12 +111,17 @@ async function login() {
  *
  * Topology: print-jobs ─▶ printer-fleet  (production line), with print-servicer
  * a side-quest root merging into the fleet.
+ *
+ * The three printer roles share entity_facet 'serialNumber' (every twin row
+ * carries it) — together with the flagship printer roles they form the
+ * printer's SYSTEM, so onboarding and servicing intervals join the machine's
+ * timeline and state band.
  */
 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.' },
+    { 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'], entity_facet: 'serialNumber', entity_state_source: 'subtype' },
+    { 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.', entity_facet: 'serialNumber', entity_state_source: 'role' },
+    { 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.', entity_facet: 'serialNumber', entity_state_source: 'role' },
 ];
 async function ensureTwinRoles() {
     const details = await api('GET', '/api/roles/details').catch(() => ({ roles: [] }));
@@ -129,8 +134,17 @@ async function ensureTwinRoles() {
     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
+        if (row?.title) {
+            // Already configured — respect admin tuning, but self-heal the entity
+            // dials where the role predates them (set only when unset).
+            if ('entity_facet' in cfg && row.entity_facet == null) {
+                await api('PATCH', `/api/roles/${cfg.role}`, {
+                    entity_facet: cfg.entity_facet,
+                    entity_state_source: cfg.entity_state_source,
+                }).catch(() => { });
+            }
+            continue;
+        }
         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)}`);

package/build/sdk/index.d.ts

@@ -227,6 +227,8 @@ export declare function createClient(options?: LTClientOptions): {
             durationMinutes?: number;
             allOrNone?: boolean;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        aggregateByFacets: (input: import("..").AggregateByFacetsInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        timelineByFacet: (input: import("..").TimelineByFacetInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
     };
     workflows: {
         invoke: (input: {

package/build/sdk/index.js

@@ -145,6 +145,9 @@ function createClient(options = {}) {
             searchByFacets: bindAuth(escalationsApi.searchByFacets, auth),
             claimGroups: bindAuth(escalationsApi.claimGroups, auth),
             claimByFacets: bindAuth(escalationsApi.claimByFacets, auth),
+            // Analytics surface (grouped membership/dwell + per-entity timeline), read_all-gated.
+            aggregateByFacets: bindAuth(escalationsApi.aggregateByFacets, auth),
+            timelineByFacet: bindAuth(escalationsApi.timelineByFacet, auth),
         },
         // ── Workflows ──────────────────────────────────────────────────────────
         workflows: {

package/build/services/escalation/aggregate-sql.d.ts

@@ -0,0 +1,36 @@
+import type { AggregateByFacetsInput, GroupableColumn, TimelineByFacetInput } from '../../types';
+export { AnalyticsInputError } from './aggregate-validate';
+export interface BuiltAggregateQuery {
+    sql: string;
+    params: unknown[];
+    /** Groups per page; the SQL fetches pageLimit + 1 rows to detect overflow. */
+    pageLimit: number;
+    columns: GroupableColumn[];
+    facets: string[];
+    /** true when grouped by the derived state label (groupBy.state). */
+    stateGrouped: boolean;
+    measureKind: 'membership' | 'dwell';
+    /** true = the anchor touches now (short cache); false = fully past (immutable). */
+    nowAnchored: boolean;
+}
+/** Per-role state naming, from lt_roles.entity_state_source. */
+export type StateSources = Record<string, 'role' | 'subtype'>;
+export interface BuiltTimelineQuery {
+    sql: string;
+    params: unknown[];
+    pageLimit: number;
+    columns: GroupableColumn[];
+    facets: string[];
+    nowAnchored: boolean;
+}
+/**
+ * Build the grouped aggregate (membership or dwell) as one parameterized
+ * query. `query.entity` must be RESOLVED by the caller before building
+ * (aggregates.ts turns it into roles + opts.stateSources); the builder
+ * rejects an unresolved entity so it can never be silently ignored.
+ */
+export declare function buildAggregateQuery(input: AggregateByFacetsInput, opts?: {
+    stateSources?: StateSources;
+}): BuiltAggregateQuery;
+/** Build the single-entity interval sequence, created_at-ordered, gaps preserved. */
+export declare function buildTimelineQuery(input: TimelineByFacetInput): BuiltTimelineQuery;