@hotmeshio/long-tail 0.10.13 → 0.11.0

package/build/api/scan-codes/present.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presentStep = presentStep;
+const types_1 = require("../../types");
+const identity_1 = require("./identity");
+const locate_1 = require("./locate");
+const verbs_1 = require("./verbs");
+// ── The info-choice outcome — locate → present reality + labeled choices ───
+//
+// Some objects carry one code for their whole life: the next action cannot be
+// inferred from state alone, and the system should not guess. A PRESENT step
+// locates the row, states its reality, and returns the step's configured,
+// labeled choice set — the same escalation primitives, presented instead of
+// auto-executed. The human's tap (or a second scan matching a choice's code)
+// is the disambiguator; execution goes back through /execute-choice, which
+// re-validates everything.
+/**
+ * Locate the target and present the step's choices. Choices whose identity
+ * requirement is unsatisfied come back withheld — the screen renders the
+ * rule's "scan your badge" affordance beside them instead of a dead button.
+ */
+async function presentStep(step, ctx) {
+    const result = await (0, locate_1.locateForStep)(step, ctx, 2);
+    if (!result || result.escalations.length === 0)
+        return null;
+    const escalation = result.escalations[0];
+    // One satisfaction test covers the step's scope; per-choice requirements
+    // reuse it because a choice executes against the same step query.
+    const satisfied = await (0, identity_1.actingIdentitySatisfied)(step, ctx);
+    // One scan, one action: a single confirm-less choice executes directly when
+    // configured — presenting a one-button screen would be a pointless tap. An
+    // unsatisfied identity requirement still presents (the client's badge
+    // stop-over), never a silent or misattributed execution.
+    const only = step.choices?.length === 1 ? step.choices[0] : undefined;
+    const autoSelect = step.autoSelectSingle === true && only !== undefined && !only.confirm;
+    if (autoSelect && (!only.requireActingIdentity || satisfied)) {
+        return (0, verbs_1.dispatchChoiceVerb)({ query: step.query, verb: only.verb, params: only.params }, ctx, escalation);
+    }
+    const choices = (step.choices ?? []).map((choice, index) => ({
+        index,
+        label: choice.label,
+        verb: choice.verb,
+        ...(choice.confirm ? { confirm: choice.confirm } : {}),
+        ...(choice.requireActingIdentity ? { requireActingIdentity: true } : {}),
+        ...(choice.code ? { code: choice.code } : {}),
+        withheld: !!choice.requireActingIdentity && !satisfied,
+    }));
+    return {
+        status: 200,
+        data: {
+            outcome: types_1.SCAN_OUTCOMES.CHOICES,
+            verb: step.verb,
+            escalation,
+            choices,
+            notPrimed: ctx.rule.notPrimed,
+            ...(autoSelect ? { autoSelect: true } : {}),
+        },
+    };
+}

package/build/api/scan-codes/verbs.d.ts

@@ -0,0 +1,15 @@
+import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import type { LTApiResult } from '../../types/sdk';
+import { type StepContext } from './context';
+export declare function claimStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function resolveStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function escalateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function releaseStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+/**
+ * Dispatch one CHOICE verb against an already-presented row. Unlike the step
+ * walk (where a miss falls through to the next step), the screen showed this
+ * exact row — so a miss answers with the truth: FORBIDDEN when the actor
+ * holds no write scope here, CONFLICT when a concurrent actor won the race.
+ */
+export declare function dispatchChoiceVerb(step: ScanStep, ctx: StepContext, row: Record<string, any>): Promise<LTApiResult<ScanExecuteResponse>>;
+export declare function cancelStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;

package/build/api/scan-codes/verbs.js

@@ -0,0 +1,205 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimStep = claimStep;
+exports.resolveStep = resolveStep;
+exports.escalateStep = escalateStep;
+exports.releaseStep = releaseStep;
+exports.dispatchChoiceVerb = dispatchChoiceVerb;
+exports.cancelStep = cancelStep;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+const escalationService = __importStar(require("../../services/escalation"));
+const metadata_1 = require("../escalations/metadata");
+const create_1 = require("../escalations/create");
+const claim_1 = require("../escalations/claim");
+const helpers_1 = require("../escalations/helpers");
+const types_1 = require("../../types");
+const context_1 = require("./context");
+// ── Mutating verbs — each a single atomic operation under the ACTOR's RBAC ──
+// ctx.auth is the effective actor: the badged person when a grant rode the
+// request, otherwise the authenticated principal. Attribution and write
+// scoping both derive from it, live, inside the escalation APIs.
+async function claimStep(step, ctx) {
+    const result = await (0, metadata_1.claimByMetadata)({
+        key: ctx.scheme.target_facet,
+        value: ctx.parsed.target,
+        durationMinutes: step.params?.durationMinutes,
+        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) },
+        restrictRoles: step.query?.roles,
+    }, ctx.auth);
+    if (result.status === 404)
+        return null;
+    if (result.status === 403)
+        return (0, context_1.forbidden)(result.error);
+    if (result.status !== 200)
+        return result;
+    return (0, context_1.executed)(result.data.escalation, step);
+}
+async function resolveStep(step, ctx) {
+    const result = await (0, metadata_1.resolveByMetadata)({
+        key: ctx.scheme.target_facet,
+        value: ctx.parsed.target,
+        resolverPayload: scanCodeService.interpolateScanTemplate(step.params?.resolverPayload ?? {}, (0, context_1.templateContext)(ctx)),
+        metadata: { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) },
+        restrictRoles: step.query?.roles,
+        extraFacets: step.query?.facets,
+    }, ctx.auth);
+    if (result.status === 404)
+        return null;
+    if (result.status === 403)
+        return (0, context_1.forbidden)(result.error);
+    if (result.status === 409)
+        return (0, context_1.conflict)(result.error);
+    if (result.status !== 200)
+        return result;
+    const escalation = result.data.escalation
+        ?? (result.data.escalationId ? { id: result.data.escalationId } : undefined);
+    return (0, context_1.executed)(escalation, step);
+}
+async function escalateStep(step, ctx) {
+    // Close the located escalation first when configured — the close doubles as
+    // the condition check AND the double-scan guard (second scan finds nothing
+    // to close and falls through).
+    if (step.params?.closeCurrent === 'resolve') {
+        const closed = await resolveStep({ ...step, params: { ...step.params, resolverPayload: step.params?.resolverPayload ?? {} } }, ctx);
+        if (closed === null)
+            return null;
+        if (closed.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
+            return closed;
+    }
+    else if (step.params?.closeCurrent === 'cancel') {
+        const cancelled = await cancelStep(step, ctx);
+        if (cancelled === null)
+            return null;
+        if (cancelled.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
+            return cancelled;
+    }
+    const created = await (0, create_1.createEscalation)({
+        type: step.params?.escalationType ?? 'scan',
+        role: step.params.targetRole,
+        description: step.params?.description ?? ctx.rule.name,
+        metadata: {
+            [ctx.scheme.target_facet]: ctx.parsed.target,
+            ...(0, context_1.interpolatedMetadata)(step, ctx),
+            ...(0, context_1.provenance)(ctx),
+        },
+    }, ctx.auth);
+    if (created.status === 403)
+        return (0, context_1.forbidden)(created.error);
+    if (created.status !== 201)
+        return created;
+    return (0, context_1.executed)(created.data, step);
+}
+async function releaseStep(step, ctx) {
+    // Locate the caller's own claim; release-by-id re-asserts the assignee
+    // inside the SDK, so a lost race resolves to 409, never a foreign release.
+    const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
+    const readable = [...scope.allRoles, ...scope.selfRoles];
+    const roles = (0, metadata_1.restrictScopeRoles)(readable, scope.global, step.query?.roles);
+    if (roles !== null && roles.length === 0)
+        return null;
+    const { escalations } = await escalationService.listEscalations({
+        metadata: (0, context_1.targetFilter)(step, ctx),
+        status: 'pending',
+        assigned_to: ctx.auth.userId,
+        visibleRoles: roles ?? undefined,
+        limit: 1,
+    });
+    if (escalations.length === 0)
+        return null;
+    const result = await (0, claim_1.releaseEscalation)({ id: escalations[0].id }, ctx.auth);
+    if (result.status === 403)
+        return (0, context_1.forbidden)(result.error);
+    if (result.status === 409)
+        return (0, context_1.conflict)(result.error);
+    if (result.status !== 200)
+        return result;
+    return (0, context_1.executed)(result.data.escalation, step);
+}
+/**
+ * Dispatch one CHOICE verb against an already-presented row. Unlike the step
+ * walk (where a miss falls through to the next step), the screen showed this
+ * exact row — so a miss answers with the truth: FORBIDDEN when the actor
+ * holds no write scope here, CONFLICT when a concurrent actor won the race.
+ */
+async function dispatchChoiceVerb(step, ctx, row) {
+    switch (step.verb) {
+        case types_1.SCAN_VERBS.SHOW_DETAIL:
+            return (0, context_1.executed)(row, step); // already located under the actor's scope
+        case types_1.SCAN_VERBS.CLAIM:
+        case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
+            return (await claimStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer claimable'));
+        case types_1.SCAN_VERBS.RESOLVE:
+            return (await resolveStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer resolvable'));
+        case types_1.SCAN_VERBS.ESCALATE:
+            return (await escalateStep(step, ctx)) ?? (await missReason(step, ctx, 'the item already moved on'));
+        case types_1.SCAN_VERBS.RELEASE:
+            return (await releaseStep(step, ctx)) ?? (0, context_1.conflict)('no claim of yours to release');
+        case types_1.SCAN_VERBS.CANCEL:
+            return (await cancelStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer cancellable'));
+        default:
+            throw new Error(`unknown choice verb "${step.verb}"`);
+    }
+}
+async function missReason(step, ctx, raceMessage) {
+    const scope = await (0, helpers_1.getEscalationWriteScope)(ctx.auth.userId);
+    if (!scope.global) {
+        const roles = (0, metadata_1.restrictScopeRoles)(scope.allRoles, scope.global, step.query?.roles);
+        if (roles !== null && roles.length === 0) {
+            return (0, context_1.forbidden)('your roles do not permit acting on this queue');
+        }
+    }
+    return (0, context_1.conflict)(raceMessage);
+}
+async function cancelStep(step, ctx) {
+    // Claim-as-lock: the atomic claim pins the row to this caller (or extends
+    // their claim), serializing concurrent double-scans before the cancel.
+    const claimed = await (0, metadata_1.claimByMetadata)({
+        key: ctx.scheme.target_facet,
+        value: ctx.parsed.target,
+        metadata: (0, context_1.provenance)(ctx),
+        restrictRoles: step.query?.roles,
+    }, ctx.auth);
+    if (claimed.status === 404)
+        return null;
+    if (claimed.status === 403)
+        return (0, context_1.forbidden)(claimed.error);
+    if (claimed.status !== 200)
+        return claimed;
+    const cancelled = await escalationService.cancelEscalation(claimed.data.escalation.id);
+    if (!cancelled)
+        return (0, context_1.conflict)('Escalation is not cancellable (already terminal)');
+    return (0, context_1.executed)(cancelled, step);
+}

package/build/bin/ltc.js

@@ -205,6 +205,39 @@ escCmd.command('claim-by-facets')
     .option('--all-or-none', 'Claim all matched rows or none')
     .option('--json', 'JSON output')
     .action(wrap(esc.claimByFacets));
+escCmd.command('aggregate-facets')
+    .description('Grouped analytics over escalation intervals: membership at an instant, or dwell over a window')
+    .option('--role <role>', 'Single pond role')
+    .option('--roles <json>', 'Multiple roles, JSON array (no role at all = every pond; global principals only)')
+    .option('--entity <key>', "Entity facet key (e.g. serialNumber) — scopes to every role declaring it (the entity's system)")
+    .option('--group-state', "Group by the derived STATE label (each role's subtypes or itself) — 'how do the entities spend their time'")
+    .option('--facets <json>', 'Required facets (JSON object, metadata @>)')
+    .option('--exists <json>', 'Metadata keys that must be present (JSON array)')
+    .option('--prefix <json>', 'Case-insensitive prefix match on facet values, e.g. \'{"serialNumber":"PRN"}\'')
+    .option('--any-of <json>', 'Rows carrying ANY of these facet sets (JSON array, max 200) — target an explicit entity set')
+    .option('--group-columns <list>', 'Comma-separated group columns: role,subtype,status')
+    .option('--group-facets <list>', 'Comma-separated metadata keys to group by')
+    .option('--as-of <iso>', 'Membership at this ISO instant (default: now; past reconstructs the live set then)')
+    .option('--window <json>', 'Dwell window {"from":"...","to":"..."} — switches the measure to dwell')
+    .option('--distinct-by <key>', 'Count DISTINCT of this facet (entities, not rows; membership only)')
+    .option('--live-statuses <list>', 'Comma-separated statuses considered live (default: pending)')
+    .option('--order-by <json>', 'Result-group order, JSON array e.g. \'[{"field":"count","direction":"desc"}]\'')
+    .option('--limit <n>', 'Max result groups')
+    .option('--offset <n>', 'Result-group offset')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.aggregateByFacets));
+escCmd.command('timeline <key> <value>')
+    .description("One entity's ordered escalation-interval timeline (gaps = untracked time)")
+    .option('--roles <json>', 'Restrict to these roles, JSON array')
+    .option('--entity <key>', "Scope to the entity's system (every role declaring this entity facet); omitted with no --roles, the query spans every queue (global principals only)")
+    .option('--from <iso>', 'Window start (with --to; only overlapping intervals)')
+    .option('--to <iso>', 'Window end')
+    .option('--select-facets <list>', 'Comma-separated metadata keys to surface per interval')
+    .option('--order <dir>', 'asc (default) or desc — desc + --before pages a long history recent-first')
+    .option('--before <iso>', 'Strict upper bound on startedAt — the "load earlier" cursor')
+    .option('--limit <n>', 'Max intervals')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.timelineByFacet));
 // ── Workflows ────────────────────────────────────────────────────────────
 const wfCmd = commander_1.program.command('workflows').alias('wf').description('Manage durable workflows');
 wfCmd.command('list')

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

@@ -64,4 +64,35 @@ export declare function claimByFacets(opts: {
     allOrNone?: boolean;
     json?: boolean;
 }): Promise<void>;
+export declare function aggregateByFacets(opts: {
+    role?: string;
+    roles?: string;
+    entity?: string;
+    facets?: string;
+    exists?: string;
+    prefix?: string;
+    anyOf?: string;
+    groupColumns?: string;
+    groupFacets?: string;
+    groupState?: boolean;
+    asOf?: string;
+    window?: string;
+    distinctBy?: string;
+    liveStatuses?: string;
+    orderBy?: string;
+    limit?: string;
+    offset?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function timelineByFacet(key: string, value: string, opts: {
+    roles?: string;
+    entity?: string;
+    from?: string;
+    to?: string;
+    selectFacets?: string;
+    order?: string;
+    before?: string;
+    limit?: string;
+    json?: boolean;
+}): Promise<void>;
 export {};

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

@@ -15,6 +15,8 @@ exports.resolveByIds = resolveByIds;
 exports.searchByFacets = searchByFacets;
 exports.claimGroups = claimGroups;
 exports.claimByFacets = claimByFacets;
+exports.aggregateByFacets = aggregateByFacets;
+exports.timelineByFacet = timelineByFacet;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
@@ -207,3 +209,89 @@ async function claimByFacets(opts) {
     }
     console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${data.claimed?.length || 0} escalation(s)\n`);
 }
+// --- Analytics commands -------------------------------------------------------
+const AGG_COLUMNS = [
+    { key: 'state', label: 'State', width: 16 },
+    { key: 'role', label: 'Role', width: 16 },
+    { key: 'subtype', label: 'Subtype', width: 16 },
+    { key: 'facets', label: 'Facets', width: 28, format: (v) => (v && Object.keys(v).length ? JSON.stringify(v) : '') },
+    { key: 'count', label: 'Count', width: 7, align: 'right' },
+    { key: 'dwellSeconds', label: 'Dwell(s)', width: 10, align: 'right', format: (v) => (v == null ? '' : String(Math.round(v))) },
+    { key: 'sampleCount', label: 'Rows', width: 6, align: 'right' },
+];
+const TIMELINE_COLUMNS = [
+    { key: 'role', label: 'Role', width: 16 },
+    { key: 'subtype', label: 'Subtype', width: 16 },
+    { key: 'status', label: 'Status', width: 10, format: format_1.formatStatus },
+    { key: 'startedAt', label: 'Started', width: 12, format: format_1.formatTime },
+    { key: 'endedAt', label: 'Ended', width: 12, format: (v) => (v ? (0, format_1.formatTime)(v) : 'open') },
+    { key: 'durationSeconds', label: 'Secs', width: 8, align: 'right', format: (v) => String(Math.round(v)) },
+];
+async function aggregateByFacets(opts) {
+    const query = {};
+    if (opts.role)
+        query.role = opts.role;
+    if (opts.roles)
+        query.roles = parseJsonOption('--roles', opts.roles);
+    if (opts.entity)
+        query.entity = opts.entity;
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    if (opts.exists)
+        query.exists = parseJsonOption('--exists', opts.exists);
+    if (opts.prefix)
+        query.prefix = parseJsonOption('--prefix', opts.prefix);
+    if (opts.anyOf)
+        query.anyOf = parseJsonOption('--any-of', opts.anyOf);
+    const groupBy = {};
+    if (opts.groupColumns)
+        groupBy.columns = opts.groupColumns.split(',').map((s) => s.trim());
+    if (opts.groupFacets)
+        groupBy.facets = opts.groupFacets.split(',').map((s) => s.trim());
+    if (opts.groupState)
+        groupBy.state = true;
+    // --window switches the measure to dwell; otherwise membership (at --as-of, default now).
+    const measure = opts.window
+        ? { kind: 'dwell', window: parseJsonOption('--window', opts.window) }
+        : { kind: 'membership', ...(opts.asOf ? { asOf: opts.asOf } : {}) };
+    const body = { query, groupBy, measure };
+    if (opts.distinctBy)
+        body.distinctBy = opts.distinctBy;
+    if (opts.liveStatuses)
+        body.liveStatuses = opts.liveStatuses.split(',').map((s) => s.trim());
+    if (opts.orderBy)
+        body.orderBy = parseJsonOption('--order-by', opts.orderBy);
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    if (opts.offset)
+        body.offset = parseInt(opts.offset, 10);
+    const data = await (0, client_1.apiFetch)('/escalations/aggregate-by-facets', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    (0, format_1.output)(data, data.groups || [], AGG_COLUMNS, opts);
+    if (data.overflow && !opts.json)
+        console.log(`  ${picocolors_1.default.yellow('!')} more groups exist — raise --limit or --offset\n`);
+}
+async function timelineByFacet(key, value, opts) {
+    const body = { facet: { key, value } };
+    if (opts.entity)
+        body.query = { entity: opts.entity };
+    else if (opts.roles)
+        body.query = { roles: parseJsonOption('--roles', opts.roles) };
+    if (opts.from && opts.to)
+        body.window = { from: opts.from, to: opts.to };
+    if (opts.selectFacets)
+        body.select = { facets: opts.selectFacets.split(',').map((s) => s.trim()) };
+    if (opts.order)
+        body.order = opts.order;
+    if (opts.before)
+        body.before = opts.before;
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    const data = await (0, client_1.apiFetch)('/escalations/timeline-by-facet', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    (0, format_1.output)(data, data.intervals || [], TIMELINE_COLUMNS, opts);
+}

package/build/lib/db/schemas/028_role_entity_facet.sql

@@ -0,0 +1,18 @@
+-- entity_facet — the lt_escalations.metadata key identifying the ENTITY that
+-- moves through this role (e.g. serialNumber, orderId). A role's escalations
+-- are the intervals that entity spends in the role's state, so declaring the
+-- key powers the derived surfaces: distinct-entity counts on the Pace Board,
+-- per-entity dwell in the station panel, entity timelines, and the entity
+-- lens. Roles sharing an entity_facet form that entity's SYSTEM. FACET_KEY-
+-- validated at the API (letters, digits, underscore). NULL = the role has no
+-- entity notion; the surfaces simply don't render.
+--
+-- entity_state_source — how this role names its contribution to the entity's
+-- state space: 'role' (the station itself is the state — one state per role,
+-- e.g. a harvesting or servicing queue) or 'subtype' (the role's subtypes are
+-- its states — one role holding several, e.g. a fleet role whose escalations
+-- park as ready/printing). Only meaningful while entity_facet is set.
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS entity_facet TEXT;
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS entity_state_source TEXT NOT NULL DEFAULT 'role';

package/build/lib/db/schemas/029_scan_scheme_kind.sql

@@ -0,0 +1,31 @@
+-- Scheme kind — what a code under this scheme IS:
+--   'action'   the shipped ECA model: the target resolves against escalations
+--              (scheme.target_facet names the escalation metadata key) and the
+--              rule's steps run.
+--   'identity' a badge: the target resolves against USERS (scheme.target_facet
+--              names the lt_users.metadata key it matches, e.g. badge_id) and a
+--              match mints a short-lived acting-identity grant through the
+--              ephemeral keystore. Identity schemes never walk steps; the
+--              rule's fallback is the unknown-badge screen.
+--
+-- Grant policy (identity kind only): grant_ttl_seconds bounds the elevation
+-- window; grant_max_uses = 0 means TTL-bound (unlimited exchanges within the
+-- window), 1 expresses a strict one-scan-one-grant policy (each scan request
+-- consumes the grant), n > 1 an n-request budget.
+ALTER TABLE lt_config_scan_schemes
+  ADD COLUMN IF NOT EXISTS kind TEXT NOT NULL DEFAULT 'action'
+    CHECK (kind IN ('action', 'identity')),
+  ADD COLUMN IF NOT EXISTS grant_ttl_seconds INT,
+  ADD COLUMN IF NOT EXISTS grant_max_uses INT NOT NULL DEFAULT 0;
+
+ALTER TABLE lt_config_scan_schemes
+  ADD CONSTRAINT chk_scan_scheme_identity_grant
+    CHECK (kind <> 'identity'
+      OR (grant_ttl_seconds BETWEEN 1 AND 86400 AND grant_max_uses >= 0));
+
+-- The rule-configured "scan your badge" screen: rendered when a step (or a
+-- presented choice) requires an acting identity and the request carries none
+-- the effective actor can satisfy. Mirrors `fallback` exactly — same shape
+-- ({ markdown, route }), different moment.
+ALTER TABLE lt_config_scan_actions
+  ADD COLUMN IF NOT EXISTS not_primed JSONB NOT NULL DEFAULT '{}';

package/build/modules/config.d.ts

@@ -13,5 +13,10 @@ export declare const config: {
     JWT_SECRET: string;
     HONEYCOMB_API_KEY: string;
     ROLE_ENFORCEMENT_CACHE_TTL_MS: number;
+    LT_ANALYTICS_MAX_GROUPS: number;
+    LT_ANALYTICS_MAX_WINDOW_DAYS: number;
+    LT_ANALYTICS_CACHE_TTL_MS: number;
+    LT_ANALYTICS_PAST_CACHE_TTL_MS: number;
+    LT_ANALYTICS_CACHE_MAX_ENTRIES: number;
 };
 export declare const postgres_options: Record<string, unknown>;

package/build/modules/config.js

@@ -24,6 +24,18 @@ exports.config = {
     // admin flips enforce_schema or edits a schema; pinned snapshots are
     // immutable and cache indefinitely.
     ROLE_ENFORCEMENT_CACHE_TTL_MS: parseInt(process.env.ROLE_ENFORCEMENT_CACHE_TTL_MS || '30000', 10),
+    // Escalation analytics (aggregateByFacets / timelineByFacet) bounds.
+    // MAX_GROUPS caps the result-group page (the API signals `overflow` instead
+    // of silently truncating); MAX_WINDOW_DAYS caps a dwell/timeline window so
+    // one query can never sweep unbounded history. The two cache TTLs split by
+    // anchor: now-anchored results tolerate pace-board-grade staleness, while a
+    // fully-past window is immutable under every long-tail write path and may
+    // live longer; MAX_ENTRIES LRU-bounds the past cache.
+    LT_ANALYTICS_MAX_GROUPS: parseInt(process.env.LT_ANALYTICS_MAX_GROUPS || '5000', 10),
+    LT_ANALYTICS_MAX_WINDOW_DAYS: parseInt(process.env.LT_ANALYTICS_MAX_WINDOW_DAYS || '35', 10),
+    LT_ANALYTICS_CACHE_TTL_MS: parseInt(process.env.LT_ANALYTICS_CACHE_TTL_MS || '30000', 10),
+    LT_ANALYTICS_PAST_CACHE_TTL_MS: parseInt(process.env.LT_ANALYTICS_PAST_CACHE_TTL_MS || '600000', 10),
+    LT_ANALYTICS_CACHE_MAX_ENTRIES: parseInt(process.env.LT_ANALYTICS_CACHE_MAX_ENTRIES || '512', 10),
 };
 exports.postgres_options = {
     host: exports.config.POSTGRES_HOST,

package/build/routes/escalations/acting.d.ts

@@ -0,0 +1,12 @@
+import type { Request, Response } from 'express';
+import type { LTApiAuth } from '../../types/sdk';
+/** The header a shared station device rides its badge grant on. */
+export declare const ACTING_TOKEN_HEADER = "x-lt-acting-token";
+/**
+ * The effective actor for an escalation WORK verb (claim, release, resolve):
+ * the badged person when an acting grant rides the request, otherwise the
+ * authenticated principal. A supplied-but-dead grant answers 401 and returns
+ * null — never a silent fall-back to the session identity, which would
+ * misattribute the mutation. Read paths never consult this header.
+ */
+export declare function effectiveWorkAuth(req: Request, res: Response): Promise<LTApiAuth | null>;

package/build/routes/escalations/acting.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTING_TOKEN_HEADER = void 0;
+exports.effectiveWorkAuth = effectiveWorkAuth;
+const acting_identity_1 = require("../../services/iam/acting-identity");
+/** The header a shared station device rides its badge grant on. */
+exports.ACTING_TOKEN_HEADER = 'x-lt-acting-token';
+/**
+ * The effective actor for an escalation WORK verb (claim, release, resolve):
+ * the badged person when an acting grant rides the request, otherwise the
+ * authenticated principal. A supplied-but-dead grant answers 401 and returns
+ * null — never a silent fall-back to the session identity, which would
+ * misattribute the mutation. Read paths never consult this header.
+ */
+async function effectiveWorkAuth(req, res) {
+    const token = req.headers[exports.ACTING_TOKEN_HEADER];
+    if (!token || typeof token !== 'string')
+        return req.auth;
+    const resolved = await (0, acting_identity_1.resolveActingAuth)(token);
+    if (!resolved.ok) {
+        res.status(401).json({ error: resolved.error });
+        return null;
+    }
+    return resolved.auth;
+}

package/build/routes/escalations/analytics.d.ts

@@ -0,0 +1,8 @@
+import type { Router } from 'express';
+/**
+ * Escalation analytics HTTP surface — grouped membership/dwell aggregates and
+ * per-entity timelines over the interval time-series. Read-only; the api layer
+ * enforces the read_all-per-role / global-for-cross-role gate. These mirror
+ * the SDK `escalations.aggregateByFacets / timelineByFacet`.
+ */
+export declare function registerAnalyticsRoutes(router: Router): void;

package/build/routes/escalations/analytics.js

@@ -0,0 +1,63 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAnalyticsRoutes = registerAnalyticsRoutes;
+const api = __importStar(require("../../api/escalations"));
+/**
+ * Escalation analytics HTTP surface — grouped membership/dwell aggregates and
+ * per-entity timelines over the interval time-series. Read-only; the api layer
+ * enforces the read_all-per-role / global-for-cross-role gate. These mirror
+ * the SDK `escalations.aggregateByFacets / timelineByFacet`.
+ */
+function registerAnalyticsRoutes(router) {
+    /**
+     * POST /api/escalations/aggregate-by-facets
+     * Body: AggregateByFacetsInput — { query, groupBy, measure, distinctBy?,
+     *       states?, liveStatuses?, orderBy?, limit?, offset? }
+     */
+    router.post('/aggregate-by-facets', async (req, res) => {
+        const result = await api.aggregateByFacets(req.body ?? {}, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/timeline-by-facet
+     * Body: TimelineByFacetInput — { facet, query?, window?, select?,
+     *       liveStatuses?, limit? }
+     */
+    router.post('/timeline-by-facet', async (req, res) => {
+        const result = await api.timelineByFacet(req.body ?? {}, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+}