@hotmeshio/long-tail 0.10.13 → 0.11.0

package/build/shared/form-validation/x-lt-labels.d.ts

@@ -0,0 +1,28 @@
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+export declare const X_LT_LABELS = "x-lt-labels";
+/** The footer controls a schema may rename. */
+export declare const FOOTER_LABEL_TARGETS: readonly ["claim", "cancel", "submit", "escalate", "release"];
+export type FooterLabelTarget = (typeof FOOTER_LABEL_TARGETS)[number];
+/** A partial map of target → override label. Absent targets keep their default. */
+export type FooterLabels = Partial<Record<FooterLabelTarget, string>>;
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+export declare function readFooterLabels(schema: Record<string, unknown> | null | undefined): FooterLabels;

package/build/shared/form-validation/x-lt-labels.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOOTER_LABEL_TARGETS = exports.X_LT_LABELS = void 0;
+exports.readFooterLabels = readFooterLabels;
+exports.X_LT_LABELS = 'x-lt-labels';
+/** The footer controls a schema may rename. */
+exports.FOOTER_LABEL_TARGETS = ['claim', 'cancel', 'submit', 'escalate', 'release'];
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+function readFooterLabels(schema) {
+    const raw = schema?.[exports.X_LT_LABELS];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const source = raw;
+    const labels = {};
+    for (const target of exports.FOOTER_LABEL_TARGETS) {
+        const value = source[target];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            labels[target] = value.trim();
+        }
+    }
+    return labels;
+}

package/build/shared/form-validation/x-lt-query.d.ts

@@ -0,0 +1,56 @@
+import type { ShowIfContext } from './x-lt-show-if';
+/**
+ * The embedded escalation query shape shared by `x-lt-query` (escalation-list
+ * widget) and `x-lt-submit-guard.query` (form-level submit gate). String
+ * values inside `facets` support `{{domain.path}}` token interpolation against
+ * the host escalation's context. Isomorphic: the dashboard renders embeds from
+ * it, and the API layer enforces the submit gate from the identical mapping.
+ *
+ * `assigned` is the ownership scope. Ownership is not a separate list — it is
+ * one more dimension of the same faceted query language the escalation API
+ * composes server-side ("claimed" is the implied status: pending, held, claim
+ * window live):
+ * - `"me"`  — rows claimed by the viewing user (the walk case: I walk what I own)
+ * - `"any"` — all matching rows regardless of claim state
+ * - omitted — available rows only (unclaimed, or claim window lapsed)
+ */
+export interface EmbedQuery {
+    role?: string;
+    status?: string;
+    facets?: Record<string, string>;
+    limit?: number;
+    assigned?: 'me' | 'any';
+    /** Superseded by `assigned`; honored only when `assigned` is omitted. */
+    available?: boolean;
+}
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+export declare function resolveQueryFacets(facets: Record<string, string> | undefined, ctx: ShowIfContext): Record<string, unknown>;
+/** The escalation-query params an EmbedQuery resolves to — the exact input
+ *  shape of `useEscalations`, so every embed surface queries identically. */
+export interface ScopedQueryParams {
+    role?: string;
+    status: string;
+    facets: Record<string, unknown>;
+    assigned_to?: string;
+    available?: boolean;
+    limit?: number;
+    enabled: boolean;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+export declare function resolveScopedQuery(query: EmbedQuery, ctx: ShowIfContext, viewerId: string | undefined): ScopedQueryParams;

package/build/shared/form-validation/x-lt-query.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQueryFacets = resolveQueryFacets;
+exports.resolveScopedQuery = resolveScopedQuery;
+const x_lt_help_1 = require("./x-lt-help");
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+function resolveQueryFacets(facets, ctx) {
+    if (!facets)
+        return {};
+    const resolved = {};
+    for (const [k, v] of Object.entries(facets)) {
+        resolved[k] = typeof v === 'string' ? (0, x_lt_help_1.interpolateHelp)(v, ctx) : v;
+    }
+    return resolved;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+function resolveScopedQuery(query, ctx, viewerId) {
+    const facets = resolveQueryFacets(query.facets, ctx);
+    const base = {
+        role: query.role,
+        status: query.status ?? 'pending',
+        facets,
+        limit: query.limit,
+        enabled: !!(query.role || Object.keys(facets).length),
+    };
+    if (query.assigned === 'me') {
+        return { ...base, assigned_to: viewerId, available: false, enabled: base.enabled && !!viewerId };
+    }
+    if (query.assigned === 'any') {
+        return base;
+    }
+    return { ...base, available: query.available ?? true };
+}

package/build/shared/form-validation/x-lt-submit-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * x-lt-submit-guard — a query precondition on the resolve. A form_schema may
+ * declare, at its root, that the escalation cannot be resolved while an embedded
+ * escalation query still returns rows: the parent references a set of children
+ * (commonly claimed by the same person) that must all be completed first, a
+ * to-do list that empties as children resolve.
+ *
+ *   "x-lt-submit-guard": {
+ *     "query": { "role": "print-harvest", "status": "pending",
+ *                "assigned": "me",
+ *                "facets": { "walkId": "{{metadata.walkId}}" } },
+ *     "mustBeEmpty": true,               // the only mode today; defaults true
+ *     "message": "{{count}} plates still pending — bag them before closing.",
+ *     "autoResolveWhenEmpty": true       // auto-submit the parent once empty
+ *   }
+ *
+ * The gate is isomorphic. The dashboard disables the submit while the query
+ * returns rows (UI honesty), and the API layer enforces the same precondition
+ * for `enforce_schema` roles so a raw-API resolve is rejected too. Only a
+ * confirmed empty result (a successful read with zero rows) clears the gate — a
+ * 403 or any error never does.
+ *
+ * `autoResolveWhenEmpty` closes the loop: the moment the query is confirmed
+ * empty, the claimed parent auto-submits — checked on page-load and after each
+ * inline child-resolve — so a set of escalations completes with no extra click.
+ */
+import type { EmbedQuery } from './x-lt-query';
+export declare const X_LT_SUBMIT_GUARD = "x-lt-submit-guard";
+export interface SubmitGuardDef {
+    query: EmbedQuery;
+    /** The gate condition; defaults to true (the only supported mode today). */
+    mustBeEmpty?: boolean;
+    /** Shown beside the disabled submit. `{{count}}` and `{{domain.path}}` tokens interpolate. */
+    message?: string;
+    /** When true, auto-submit the claimed parent the moment the query is confirmed empty. */
+    autoResolveWhenEmpty?: boolean;
+}
+export declare const SUBMIT_GUARD_DEFAULT_MESSAGE = "{{count}} related items are still pending";
+/** The schema's submit-guard, or undefined when it declares none. */
+export declare function readSubmitGuard(schema: Record<string, unknown> | null | undefined): SubmitGuardDef | undefined;
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+export declare function guardBlocks(count: number, guard: SubmitGuardDef | undefined): boolean;

package/build/shared/form-validation/x-lt-submit-guard.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
+exports.readSubmitGuard = readSubmitGuard;
+exports.guardBlocks = guardBlocks;
+exports.X_LT_SUBMIT_GUARD = 'x-lt-submit-guard';
+exports.SUBMIT_GUARD_DEFAULT_MESSAGE = '{{count}} related items are still pending';
+/** The schema's submit-guard, or undefined when it declares none. */
+function readSubmitGuard(schema) {
+    const raw = schema?.[exports.X_LT_SUBMIT_GUARD];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const guard = raw;
+    if (!guard.query || typeof guard.query !== 'object')
+        return undefined;
+    return guard;
+}
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+function guardBlocks(count, guard) {
+    return !!guard && guard.mustBeEmpty !== false && count > 0;
+}

package/build/shared/form-validation/x-lt-submit-on-claim.d.ts

@@ -0,0 +1,22 @@
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+export declare const X_LT_SUBMIT_ON_CLAIM = "x-lt-submit-on-claim";
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+export declare function readSubmitOnClaim(schema: Record<string, unknown> | null | undefined): boolean;

package/build/shared/form-validation/x-lt-submit-on-claim.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_SUBMIT_ON_CLAIM = void 0;
+exports.readSubmitOnClaim = readSubmitOnClaim;
+exports.X_LT_SUBMIT_ON_CLAIM = 'x-lt-submit-on-claim';
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+function readSubmitOnClaim(schema) {
+    return !!schema?.[exports.X_LT_SUBMIT_ON_CLAIM];
+}

package/build/system/mcp-servers/admin/escalations.js

@@ -259,6 +259,40 @@ function registerEscalationTools(server) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
     });
+    // mirrors POST /api/escalations/aggregate-by-facets
+    server.registerTool('aggregate_by_facets', {
+        title: 'Aggregate by Facets',
+        description: 'Grouped analytics over the escalation intervals. Every escalation is one open ' +
+            'interval [created_at, ended_at); this tool reads it two ways: membership (rows or, ' +
+            'with distinctBy, distinct entities open at an instant — a past asOf reconstructs the ' +
+            'live set then) and dwell (open-seconds per group within a half-open [from,to) window). ' +
+            'Group by role/subtype/status columns plus metadata facet keys; optional states[] label ' +
+            'each group. One call replaces N per-filter count round-trips. The filter takes the WHAT ' +
+            'fields only — status/available/jeopardy are rejected (liveness derives from the measure).',
+        inputSchema: schemas_1.aggregateByFacetsSchema,
+    }, async (args) => {
+        const result = await escalationApi.aggregateByFacets(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/timeline-by-facet
+    server.registerTool('timeline_by_facet', {
+        title: 'Timeline by Facet',
+        description: 'One entity\'s ordered interval sequence — every escalation the entity facet ' +
+            '(e.g. a machine id) appeared in, as [startedAt, endedAt) spans with durations, in ' +
+            'created_at order. Open intervals report endedAt: null. Gaps between consecutive ' +
+            'intervals are untracked time and are preserved, not filled. The entity facet value ' +
+            'must be stored as a JSON string (GIN containment match).',
+        inputSchema: schemas_1.timelineByFacetSchema,
+    }, async (args) => {
+        const result = await escalationApi.timelineByFacet(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors POST /api/escalations/claim-groups
     server.registerTool('claim_groups', {
         title: 'Claim Groups',

package/build/system/mcp-servers/admin/scan-codes.js

@@ -56,7 +56,23 @@ function registerScanCodeTools(server) {
             'no_match_fallback, unconfigured, invalid_code, forbidden, conflict).',
         inputSchema: schemas_1.executeScanCodeSchema,
     }, async (args) => {
-        const result = await scanCodesApi.executeScanCode({ code: args.code }, await systemAuth());
+        const result = await scanCodesApi.executeScanCode({
+            code: args.code,
+            actingToken: args.actingToken,
+            previousActingToken: args.previousActingToken,
+        }, await systemAuth());
+        return asText(result.data ?? { error: result.error });
+    });
+    // mirrors POST /api/scan-codes/execute-choice
+    server.registerTool('execute_scan_choice', {
+        title: 'Execute Scan Choice',
+        description: 'Execute one choice presented by a PRESENT step (the info-choice screen). ' +
+            'The pointer (scheme/category/step/choice + escalationId) is re-validated ' +
+            'against live config, the row\'s current state, the acting-identity gate, ' +
+            'and RBAC before the verb runs.',
+        inputSchema: schemas_1.executeScanChoiceSchema,
+    }, async (args) => {
+        const result = await scanCodesApi.executeScanChoice(args, await systemAuth());
         return asText(result.data ?? { error: result.error });
     });
     // mirrors GET /api/scan-codes/schemes