@hotmeshio/long-tail 0.10.11 → 0.10.14

package/README.md

@@ -4,9 +4,7 @@
 
 Durable platforms are built around determinism — that is their strength and their blind spot. They give you rich, first-class queues for deterministic work (retry, timeout, `backoffCoefficient`, exactly-once) and an `await condition()` to park a workflow until a signal arrives. All of it assumes the thing you are waiting on will, eventually, behave.
 
-Most of the work that decides an outcome behaves on its own schedule: an approval, a person, a shipment, a machine that needs service. You cannot set a `backoffCoefficient` on a person — retrying someone who has not answered just asks twice. This is why "human-in-the-loop" keeps getting bolted on as a feature: the platform perfected the deterministic queue and left the non-deterministic one for you to improvise.
-
-Long Tail makes it a primitive. The same `condition()` wait — except the act of waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. Machines answer some rows, people answer others; the workflow resumes either way, exactly where it paused.
+Long Tail makes non-determinism a primitive. The same `condition()` wait — except the act of waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. Machines answer some rows, people answer others; the workflow resumes either way, exactly where it paused.
 
 ```bash
 npm install @hotmeshio/long-tail
@@ -14,7 +12,7 @@ npm install @hotmeshio/long-tail
 
 ## How it works
 
-One workflow, both queues: `proxyActivities` for the deterministic one, `condition()` for the one reality answers.
+One workflow, both queues: `proxyActivities` for the deterministic one, `condition()` for non-determinism.
 
 ```typescript
 import { Durable } from '@hotmeshio/hotmesh';

package/build/api/escalations/list.d.ts

@@ -37,6 +37,7 @@ export declare function listEscalations(input: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    parent_id?: string;
     claimed?: boolean;
     priority?: number;
     limit?: number;

package/build/api/escalations/list.js

@@ -115,6 +115,7 @@ async function listEscalations(input, auth) {
             type: input.type,
             subtype: input.subtype,
             assigned_to: input.assigned_to,
+            parent_id: input.parent_id,
             claimed: input.claimed,
             priority: input.priority,
             limit: input.limit,

package/build/api/escalations/metadata.d.ts

@@ -1,5 +1,13 @@
 import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Intersect the caller's scope roles with an optional caller-supplied
+ * restriction (e.g. a scan step's expected queues). Global scope with no
+ * restriction stays unfiltered (null); a restriction always applies. An
+ * empty intersection returns [] — which matches nothing in the SQL filter,
+ * the correct fail-closed outcome.
+ */
+export declare function restrictScopeRoles(scopeRoles: string[], global: boolean, restrictRoles?: string[]): string[] | null;
 /**
  * Find escalations by a metadata key-value pair.
  *
@@ -27,6 +35,7 @@ export declare function claimByMetadata(input: {
     assignee?: string;
     metadata?: Record<string, any>;
     provisionIfAbsent?: ProvisionIfAbsent;
+    restrictRoles?: string[];
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Resolve an escalation by metadata key-value pair.
@@ -46,4 +55,6 @@ export declare function resolveByMetadata(input: {
     resolverPayload: Record<string, any>;
     assignee?: string;
     metadata?: Record<string, any>;
+    restrictRoles?: string[];
+    extraFacets?: Record<string, any>;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.restrictScopeRoles = restrictScopeRoles;
 exports.findByMetadata = findByMetadata;
 exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadata = resolveByMetadata;
@@ -41,6 +42,20 @@ const helpers_1 = require("./helpers");
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const resolve_1 = require("./resolve");
+/**
+ * Intersect the caller's scope roles with an optional caller-supplied
+ * restriction (e.g. a scan step's expected queues). Global scope with no
+ * restriction stays unfiltered (null); a restriction always applies. An
+ * empty intersection returns [] — which matches nothing in the SQL filter,
+ * the correct fail-closed outcome.
+ */
+function restrictScopeRoles(scopeRoles, global, restrictRoles) {
+    if (!restrictRoles || restrictRoles.length === 0)
+        return global ? null : scopeRoles;
+    if (global)
+        return restrictRoles;
+    return scopeRoles.filter((r) => restrictRoles.includes(r));
+}
 /**
  * Find escalations by a metadata key-value pair.
  *
@@ -85,9 +100,10 @@ async function claimByMetadata(input, auth) {
         // Write-scope: global → no filter; otherwise restrict to write_all roles. The
         // SDK claim-by-metadata uses a flat role filter and cannot enforce write_self
         // ownership, so self-scope members are excluded from this path (their items
-        // are pre-claimed and acted on by id).
+        // are pre-claimed and acted on by id). An optional caller restriction
+        // (expected queues) intersects with the scope inside the same SQL filter.
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const allowedRoles = writeScope.global ? null : writeScope.allRoles;
+        const allowedRoles = restrictScopeRoles(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes, input.metadata, allowedRoles);
         if (!result) {
             // No rows matched. Check if candidates existed (role mismatch vs no match).
@@ -129,22 +145,26 @@ async function resolveByMetadata(input, auth) {
         // Write-scope folds into the atomic resolve SQL: global → no filter; otherwise
         // write_all roles match any item, write_self roles match only items assigned
         // to the resolver. A non-global caller cannot pass a foreign assignee, so the
-        // self-branch (assigned_to = resolveUserId) is the caller's own items.
+        // self-branch (assigned_to = resolveUserId) is the caller's own items. An
+        // optional caller restriction (expected queues) intersects with both arrays
+        // inside the same SQL filter.
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
-        const writeAllRoles = writeScope.global ? null : writeScope.allRoles;
-        const writeSelfRoles = writeScope.global ? null : writeScope.selfRoles;
+        const writeAllRoles = restrictScopeRoles(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        const writeSelfRoles = writeScope.global
+            ? (input.restrictRoles?.length ? [] : null)
+            : restrictScopeRoles(writeScope.selfRoles, false, input.restrictRoles);
         // Schema enforcement rides the atomic statement: with the cached enforcing
         // set empty (the common case) the single-call behavior is unchanged. When
         // the picked row's role enforces, the statement returns the row WITHOUT
         // writing; the payload validates here, then a second asserted pass claims
         // + resolves the same row with pending re-checked inside the statement.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null);
+        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, null, input.extraFacets);
         if (result.outcome === 'validation_required' && result.row) {
-            const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload);
+            const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload, undefined, resolveUserId);
             if (report)
                 return (0, resolve_1.validationFailure)(report);
-            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id);
+            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets);
             // The asserted row left pending between the two passes — a concurrent
             // resolution won the row; surface it as the conflict it is.
             if (result.outcome === 'not_found') {

package/build/api/escalations/resolve.js

@@ -98,7 +98,7 @@ async function resolveEscalation(input, auth) {
         // the escalation's resolved form schema BEFORE any resolution path runs.
         // Costs nothing when the role does not enforce (cached role set); the
         // task-fallback envelope read only happens for enforcing roles.
-        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, () => reconstructEnvelope(escalation));
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, () => reconstructEnvelope(escalation), auth.userId);
         if (violation)
             return validationFailure(violation);
         // The resolver payload is stored exactly as submitted — its shape is the
@@ -181,7 +181,7 @@ async function resolveBySignalKey(input, auth) {
             return { status: 404, error: 'Escalation not found' };
         // Schema enforcement — the row (envelope included) is already loaded, so
         // this costs zero extra reads beyond the cached schema.
-        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload);
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, undefined, auth.userId);
         if (violation)
             return validationFailure(violation);
         // The payload is delivered as the signal the parked workflow's condition()
@@ -247,7 +247,7 @@ async function resolveByIds(input, auth) {
                 const fullRows = await escalationService.getEscalationsByIds(involved);
                 const failed = [];
                 for (const row of fullRows) {
-                    const report = await (0, resolver_validation_1.checkResolverPayload)(row, resolverPayload);
+                    const report = await (0, resolver_validation_1.checkResolverPayload)(row, resolverPayload, undefined, auth.userId);
                     if (report)
                         failed.push({ id: row.id, report });
                 }
@@ -346,7 +346,7 @@ async function resolveAllOrNone(input, auth) {
                 const row = rowById.get(item.id);
                 if (!row || !row.role || !enforcing.has(row.role))
                     continue;
-                const report = await (0, resolver_validation_1.checkResolverPayload)(row, item.resolverPayload);
+                const report = await (0, resolver_validation_1.checkResolverPayload)(row, item.resolverPayload, undefined, auth.userId);
                 if (report)
                     failed.push({ id: item.id, report });
             }

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

@@ -0,0 +1,22 @@
+import * as scanCodeService from '../../services/scan-code';
+import type { LTApiResult } from '../../types/sdk';
+export declare function listScanSchemes(): Promise<LTApiResult>;
+export declare function getScanScheme(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function upsertScanScheme(input: scanCodeService.ScanSchemeInput): Promise<LTApiResult>;
+export declare function deleteScanScheme(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function listScanRules(input: {
+    version: number;
+}): Promise<LTApiResult>;
+export declare function getScanRule(input: {
+    version: number;
+    category: string;
+}): Promise<LTApiResult>;
+export declare function upsertScanRule(input: scanCodeService.ScanRuleInput): Promise<LTApiResult>;
+export declare function deleteScanRule(input: {
+    version: number;
+    category: string;
+}): Promise<LTApiResult>;

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

@@ -0,0 +1,136 @@
+"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.listScanSchemes = listScanSchemes;
+exports.getScanScheme = getScanScheme;
+exports.upsertScanScheme = upsertScanScheme;
+exports.deleteScanScheme = deleteScanScheme;
+exports.listScanRules = listScanRules;
+exports.getScanRule = getScanRule;
+exports.upsertScanRule = upsertScanRule;
+exports.deleteScanRule = deleteScanRule;
+const scanCodeService = __importStar(require("../../services/scan-code"));
+// ── Scheme CRUD ────────────────────────────────────────────────────────────
+// Admin gating happens at the transport layer (requireAdmin on routes, admin
+// MCP registration) — same convention as workflow config.
+async function listScanSchemes() {
+    try {
+        const schemes = await scanCodeService.listScanSchemes();
+        return { status: 200, data: { schemes } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function getScanScheme(input) {
+    try {
+        const scheme = await scanCodeService.getScanScheme(input.version);
+        if (!scheme)
+            return { status: 404, error: `No scan scheme for version ${input.version}` };
+        const rules = await scanCodeService.listScanRules(input.version);
+        return { status: 200, data: { scheme, rules } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function upsertScanScheme(input) {
+    try {
+        const scheme = await scanCodeService.upsertScanScheme(input);
+        return { status: 200, data: { scheme } };
+    }
+    catch (err) {
+        // Write-time invariant violations are caller errors, not server faults.
+        return { status: 400, error: err.message };
+    }
+}
+async function deleteScanScheme(input) {
+    try {
+        const deleted = await scanCodeService.deleteScanScheme(input.version);
+        if (!deleted)
+            return { status: 404, error: `No scan scheme for version ${input.version}` };
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+// ── Rule CRUD ──────────────────────────────────────────────────────────────
+async function listScanRules(input) {
+    try {
+        const rules = await scanCodeService.listScanRules(input.version);
+        return { status: 200, data: { rules } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function getScanRule(input) {
+    try {
+        const rule = await scanCodeService.getScanRule(input.version, input.category);
+        if (!rule) {
+            return { status: 404, error: `No scan rule for ${input.version}:${input.category}` };
+        }
+        return { status: 200, data: { rule } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function upsertScanRule(input) {
+    try {
+        const scheme = await scanCodeService.getScanScheme(input.scheme_version);
+        if (!scheme) {
+            return { status: 404, error: `No scan scheme for version ${input.scheme_version} — create the scheme first` };
+        }
+        const rule = await scanCodeService.upsertScanRule(input);
+        return { status: 200, data: { rule } };
+    }
+    catch (err) {
+        return { status: 400, error: err.message };
+    }
+}
+async function deleteScanRule(input) {
+    try {
+        const deleted = await scanCodeService.deleteScanRule(input.version, input.category);
+        if (!deleted) {
+            return { status: 404, error: `No scan rule for ${input.version}:${input.category}` };
+        }
+        return { status: 200, data: { deleted: true } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -0,0 +1,9 @@
+import { type ScanExecuteRequest, type ScanExecuteResponse } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Execute a raw scan code: parse → load the rule → walk its steps in order.
+ * The first step whose condition matches performs its verb and answers; a
+ * step that matches nothing falls through to the next. Every terminal state
+ * is a structured 200 outcome — the scan surface reports, it doesn't throw.
+ */
+export declare function executeScanCode(input: ScanExecuteRequest, auth: LTApiAuth): Promise<LTApiResult<ScanExecuteResponse>>;