@hotmeshio/long-tail 0.22.2 → 0.23.0

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

@@ -33,9 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bags = bags;
+exports.claimGuard = claimGuard;
 exports.matchGuard = matchGuard;
+exports.failedAdd = failedAdd;
+exports.rendered = rendered;
 exports.accumulateFromSubject = accumulateFromSubject;
-exports.accumulateIntoSubject = accumulateIntoSubject;
+exports.already = already;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const accumulate_1 = require("../escalations/accumulate");
@@ -52,13 +56,18 @@ const subject_1 = require("./subject");
 // the pairing first (match), refusing with nothing written when it is wrong,
 // then writes by id in one atomic statement: the subject joins the scanned
 // container with its own row as the reciprocal (from: 'subject'), or the
-// subject's row collects the scanned code (into: 'subject').
+// subject's row collects the scanned code (into: 'subject', in
+// verb-into-subject.ts).
 const STOCK_REFUSAL = 'That is not where this one goes.';
 const STOCK_CONFLICT = 'That container just closed. Scan it again, or the next one.';
 const STOCK_PLACED = 'This one is already placed.';
-/** The step's template bags with the subject (and the container, once located). */
-function bags(ctx, container) {
-    return { ...(0, context_1.templateContext)(ctx), ...(container ? { container: container.metadata ?? {} } : {}) };
+/** The step's template bags with the subject, the container, and the scanned item's row once located. */
+function bags(ctx, container, item) {
+    return {
+        ...(0, context_1.templateContext)(ctx),
+        ...(container ? { container: container.metadata ?? {} } : {}),
+        ...(item ? { item: item.metadata ?? {} } : {}),
+    };
 }
 /** Refuse the act when someone else holds a live claim on the subject. */
 async function claimGuard(step, ctx, subject) {
@@ -82,10 +91,10 @@ async function locateContainer(step, ctx) {
         status: 'pending',
         exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
         limit: 2,
-    });
+    }, { total: false });
     return found.escalations.filter((row) => row.id !== ctx.subject?.row.id);
 }
-const WHOLE_BAG_TOKEN = /^\{(subject|container)\.([a-zA-Z0-9_]+)\}$/;
+const WHOLE_BAG_TOKEN = /^\{(subject|container|item)\.([a-zA-Z0-9_]+)\}$/;
 /**
  * One match.target template as the values it allows. A template that is a
  * single bag token naming a list facet (`{subject.offeredContainers}`) allows every
@@ -110,11 +119,11 @@ function expandTarget(template, tpl) {
  * The pre-write guard. Returns the refusal when the pairing is wrong, null
  * when it holds (or the step declares no match).
  */
-function matchGuard(step, ctx, container) {
+function matchGuard(step, ctx, container, item) {
     const match = step.match;
     if (!match)
         return null;
-    const tpl = bags(ctx, container);
+    const tpl = bags(ctx, container, item);
     const expected = (match.target ?? []).flatMap((t) => expandTarget(t, tpl));
     const targetOk = match.target === undefined || expected.includes(ctx.parsed.target);
     const subjectMeta = (ctx.subject?.row.metadata ?? {});
@@ -126,15 +135,20 @@ function matchGuard(step, ctx, container) {
     const markdown = scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_REFUSAL, tpl);
     return (0, context_1.refused)(markdown, { refusal: { markdown, ...(expected.length ? { expected } : {}) } });
 }
-/** Map a failed add onto what the bench says. 404 falls through. */
-function failedAdd(step, ctx, result, container) {
+const PLACED_OUTCOMES = ['reciprocal-terminal', 'reciprocal-full', 'reciprocal-duplicate'];
+/**
+ * Map a failed add onto what the bench says. 404 falls through. `keepSubject`
+ * leaves the hold in place when the reciprocal was already placed (the
+ * subject is the container the actor is still filling).
+ */
+function failedAdd(step, ctx, result, container, keepSubject = false) {
     const outcome = result.data?.outcome;
     if (result.status === 404)
         return null;
     if (result.status === 403)
         return (0, context_1.forbidden)(result.error);
-    if (outcome === 'reciprocal-terminal' || outcome === 'reciprocal-full' || outcome === 'reciprocal-duplicate') {
-        return (0, context_1.refused)(STOCK_PLACED, { clearSubject: true });
+    if (outcome && PLACED_OUTCOMES.includes(outcome)) {
+        return (0, context_1.refused)(STOCK_PLACED, { clearSubject: !keepSubject });
     }
     if (outcome === 'claimed-by-other' || outcome === 'claim-expired')
         return (0, context_1.conflict)(result.error);
@@ -145,8 +159,9 @@ function failedAdd(step, ctx, result, container) {
     }
     return (0, context_1.refused)(result.error ?? STOCK_REFUSAL);
 }
-function rendered(step, ctx, itemKeyDefault) {
-    const tpl = (0, context_1.templateContext)(ctx);
+/** The step's itemKey, payload and metadata, or null when a template token has nothing to read. */
+function rendered(step, ctx, itemKeyDefault, item) {
+    const tpl = bags(ctx, undefined, item);
     try {
         return {
             itemKey: scanCodeService.interpolateScanTemplate(step.params?.itemKey ?? itemKeyDefault ?? '', tpl),
@@ -217,46 +232,8 @@ async function accumulateFromSubject(step, ctx) {
         },
     }, step, bags(ctx, container));
 }
-/** The subject's own row collects the scanned code. */
-async function accumulateIntoSubject(step, ctx) {
-    const subject = ctx.subject;
-    const claimed = await claimGuard(step, ctx, subject);
-    if (claimed)
-        return claimed;
-    const mismatch = matchGuard(step, ctx);
-    if (mismatch)
-        return mismatch;
-    const values = rendered(step, ctx, '{scan.target}');
-    if (!values)
-        return null;
-    const notPrimed = (await (0, grant_1.identityGate)(step, ctx)) ?? (await (0, grant_1.spendGrant)(ctx));
-    if (notPrimed)
-        return notPrimed;
-    const result = await (0, accumulate_1.accumulateItem)({
-        id: subject.row.id,
-        itemKey: values.itemKey,
-        payload: values.payload,
-        metadata: values.metadata,
-    }, ctx.auth);
-    if (result.status !== 200) {
-        if (result.data?.outcome === 'duplicate-item') {
-            return already(step, subject.row);
-        }
-        return failedAdd(step, ctx, result);
-    }
-    const data = result.data;
-    return (0, context_1.withDone)({
-        status: 200,
-        data: {
-            outcome: types_1.SCAN_OUTCOMES.EXECUTED,
-            verb: step.verb,
-            escalation: { id: subject.row.id, ...result.data },
-            clearSubject: data.outcome === 'completed',
-        },
-    }, step, bags(ctx));
-}
 /** The item is already where the scan says: harmless, nothing written. */
-function already(step, row) {
+function already(step, row, keepSubject = false) {
     return {
         status: 200,
         data: {
@@ -264,7 +241,7 @@ function already(step, row) {
             verb: step.verb,
             escalation: { id: row.id },
             already: true,
-            clearSubject: true,
+            clearSubject: !keepSubject,
         },
     };
 }

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

@@ -1,21 +1,23 @@
 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>;
+/** Claims the scanned row; a presented choice passes the row it showed. */
+export declare function claimStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 /**
  * Resolves the row the step's query names: the scanned target, the extra
  * facets, and the claim state, all inside the atomic statement. A presented
  * choice passes the row it showed, so the resolve lands on that row or misses.
  */
 export declare function resolveStep(step: ScanStep, ctx: StepContext, presentedId?: string): 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>;
+export declare function escalateStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
+export declare function releaseStep(step: ScanStep, ctx: StepContext, presentedId?: string): 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.
+ * Dispatch one CHOICE verb against an already-presented row. Every verb that
+ * writes the row writes that row by id, so a code shared by several rows
+ * never moves the write elsewhere. Unlike the step walk (where a miss falls
+ * through to the next step), a miss answers with the truth: FORBIDDEN when
+ * the actor holds no write scope here, CONFLICT when a concurrent actor won.
  */
 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>;
+export declare function cancelStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 export { accumulateStep } from './verb-accumulate';

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

@@ -54,7 +54,8 @@ const hold_1 = require("./hold");
 // 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) {
+/** Claims the scanned row; a presented choice passes the row it showed. */
+async function claimStep(step, ctx, presentedId) {
     const metadata = await (0, context_1.templated)(step, ctx, (tpl) => (0, context_1.interpolatedMetadata)(step, ctx, tpl));
     if (metadata === null)
         return null;
@@ -67,6 +68,7 @@ async function claimStep(step, ctx) {
         durationMinutes: step.params?.durationMinutes,
         metadata: { ...metadata, ...(0, context_1.provenance)(ctx) },
         restrictRoles: step.query?.roles,
+        assertId: presentedId,
     }, ctx.auth);
     if (result.status === 404)
         return null;
@@ -115,19 +117,19 @@ async function resolveStep(step, ctx, presentedId) {
         ?? (result.data.escalationId ? { id: result.data.escalationId } : undefined);
     return (0, context_1.executed)(escalation, step);
 }
-async function escalateStep(step, ctx) {
+async function escalateStep(step, ctx, presentedId) {
     // 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);
+        const closed = await resolveStep({ ...step, params: { ...step.params, resolverPayload: step.params?.resolverPayload ?? {} } }, ctx, presentedId);
         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);
+        const cancelled = await cancelStep(step, ctx, presentedId);
         if (cancelled === null)
             return null;
         if (cancelled.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
@@ -152,9 +154,11 @@ async function escalateStep(step, ctx) {
         return created;
     return (0, context_1.executed)(created.data, step);
 }
-async function releaseStep(step, ctx) {
+async function releaseStep(step, ctx, presentedId) {
     // 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.
+    if (presentedId)
+        return releaseById(presentedId, step, ctx);
     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);
@@ -169,23 +173,27 @@ async function releaseStep(step, ctx) {
     });
     if (escalations.length === 0)
         return null;
+    return releaseById(escalations[0].id, step, ctx);
+}
+async function releaseById(id, step, ctx) {
     const notPrimed = await (0, grant_1.spendGrant)(ctx);
     if (notPrimed)
         return notPrimed;
-    const result = await (0, claim_1.releaseEscalation)({ id: escalations[0].id }, ctx.auth);
+    const result = await (0, claim_1.releaseEscalation)({ id }, ctx.auth);
     if (result.status === 403)
         return (0, context_1.forbidden)(result.error);
-    if (result.status === 409)
+    if (result.status === 409 || result.status === 404)
         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.
+ * Dispatch one CHOICE verb against an already-presented row. Every verb that
+ * writes the row writes that row by id, so a code shared by several rows
+ * never moves the write elsewhere. Unlike the step walk (where a miss falls
+ * through to the next step), a miss answers with the truth: FORBIDDEN when
+ * the actor holds no write scope here, CONFLICT when a concurrent actor won.
  */
 async function dispatchChoiceVerb(step, ctx, row) {
     switch (step.verb) {
@@ -195,15 +203,15 @@ async function dispatchChoiceVerb(step, ctx, row) {
             return (await (0, hold_1.holdStep)(step, ctx, row));
         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'));
+            return (await claimStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer claimable'));
         case types_1.SCAN_VERBS.RESOLVE:
             return (await resolveStep(step, ctx, row.id)) ?? (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'));
+            return (await escalateStep(step, ctx, row.id)) ?? (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');
+            return (await releaseStep(step, ctx, row.id)) ?? (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'));
+            return (await cancelStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer cancellable'));
         default:
             throw new Error(`unknown choice verb "${step.verb}"`);
     }
@@ -218,7 +226,7 @@ async function missReason(step, ctx, raceMessage) {
     }
     return (0, context_1.conflict)(raceMessage);
 }
-async function cancelStep(step, ctx) {
+async function cancelStep(step, ctx, presentedId) {
     // Claim-as-lock: the atomic claim pins the row to this caller (or extends
     // their claim), serializing concurrent double-scans before the cancel.
     const notPrimed = await (0, grant_1.spendGrant)(ctx);
@@ -229,6 +237,7 @@ async function cancelStep(step, ctx) {
         value: ctx.parsed.target,
         metadata: (0, context_1.provenance)(ctx),
         restrictRoles: step.query?.roles,
+        assertId: presentedId,
     }, ctx.auth);
     if (claimed.status === 404)
         return null;

package/build/index.d.ts

@@ -12,7 +12,7 @@ export * as TaskService from './services/task';
 export * as EscalationService from './services/escalation';
 export * as ConfigService from './services/config';
 export * as UserService from './services/user';
-export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
+export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, displayGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
 export * as TopicService from './services/topics';
 export { seedSystemTopics, seedConfigTopics } from './services/topics/system-topics';
 export { ltConfig } from './modules/ltconfig';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = void 0;
+exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -76,6 +76,7 @@ Object.defineProperty(exports, "assertValidScanSteps", { enumerable: true, get:
 Object.defineProperty(exports, "assertValidScanIdentityRule", { enumerable: true, get: function () { return scan_code_1.assertValidIdentityRule; } });
 Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
 Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });
+Object.defineProperty(exports, "displayGtin", { enumerable: true, get: function () { return scan_code_1.displayGtin; } });
 exports.TopicService = __importStar(require("./services/topics"));
 var system_topics_1 = require("./services/topics/system-topics");
 Object.defineProperty(exports, "seedSystemTopics", { enumerable: true, get: function () { return system_topics_1.seedSystemTopics; } });

package/build/sdk/index.d.ts

@@ -213,6 +213,7 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
             restrictRoles?: string[];
+            assertId?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveByMetadata: (input: {
             key: string;

package/build/services/escalation/batch.d.ts

@@ -9,14 +9,14 @@ export interface ResolveBatchItemOutcome {
 /**
  * Fills one declared item of a batch escalation in a single atomic SDK
  * statement (guarded fill + facet recompute + resolve-and-wake on the last
- * item). Interim fills publish `escalation.updated` with progress; the
+ * item). `actor` is recorded under `envelope.batch_filled_by[itemKey]`. Interim fills publish `escalation.updated` with progress; the
  * completing fill publishes the standard `escalation.resolved`. Failure
  * outcomes publish nothing — the row was untouched.
  */
 export declare function resolveBatchItem(id: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>, assertClaim?: string, resolvedBy?: {
     id: string;
     email?: string;
-}): Promise<ResolveBatchItemOutcome>;
+}, actor?: string): Promise<ResolveBatchItemOutcome>;
 /**
  * Batch-item fill selecting the row by its `signal_key` — the deterministic
  * home signal id the parent parked on. For callers that already own that
@@ -26,7 +26,7 @@ export declare function resolveBatchItem(id: string, itemKey: string, payload: R
 export declare function resolveBatchItemBySignalKey(signalKey: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>, resolvedBy?: {
     id: string;
     email?: string;
-}): Promise<ResolveBatchItemOutcome>;
+}, actor?: string): Promise<ResolveBatchItemOutcome>;
 /**
  * Batch-item fill selecting the row by metadata facet — the highest-priority
  * pending row whose metadata contains the key/value, scoped by `roles`.
@@ -35,4 +35,4 @@ export declare function resolveBatchItemBySignalKey(signalKey: string, itemKey:
 export declare function resolveBatchItemByMetadata(key: string, value: unknown, itemKey: string, payload: Record<string, any>, roles?: string[], metadata?: Record<string, any>, resolvedBy?: {
     id: string;
     email?: string;
-}): Promise<ResolveBatchItemOutcome>;
+}, actor?: string): Promise<ResolveBatchItemOutcome>;

package/build/services/escalation/batch.js

@@ -11,11 +11,11 @@ const map_1 = require("./map");
 /**
  * Fills one declared item of a batch escalation in a single atomic SDK
  * statement (guarded fill + facet recompute + resolve-and-wake on the last
- * item). Interim fills publish `escalation.updated` with progress; the
+ * item). `actor` is recorded under `envelope.batch_filled_by[itemKey]`. Interim fills publish `escalation.updated` with progress; the
  * completing fill publishes the standard `escalation.resolved`. Failure
  * outcomes publish nothing — the row was untouched.
  */
-async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, resolvedBy) {
+async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, resolvedBy, actor) {
     if (!(0, uuid_1.isUuid)(id))
         return { outcome: 'not-found', remaining: -1, escalation: null };
     const client = await (0, client_1.escalations)();
@@ -26,6 +26,7 @@ async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, res
         metadata,
         assertClaim,
         resolvedBy,
+        actor,
     });
     return settleBatchOutcome(result, itemKey);
 }
@@ -35,7 +36,7 @@ async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, res
  * identity (a child calling home, a webhook), skipping both the UUID lookup
  * and any facet duplication. Same event contract as {@link resolveBatchItem}.
  */
-async function resolveBatchItemBySignalKey(signalKey, itemKey, payload, metadata, resolvedBy) {
+async function resolveBatchItemBySignalKey(signalKey, itemKey, payload, metadata, resolvedBy, actor) {
     const client = await (0, client_1.escalations)();
     const result = await client.resolveBatchItem({
         signalKey,
@@ -43,6 +44,7 @@ async function resolveBatchItemBySignalKey(signalKey, itemKey, payload, metadata
         payload,
         metadata,
         resolvedBy,
+        actor,
     });
     return settleBatchOutcome(result, itemKey);
 }
@@ -51,7 +53,7 @@ async function resolveBatchItemBySignalKey(signalKey, itemKey, payload, metadata
  * pending row whose metadata contains the key/value, scoped by `roles`.
  * Same event contract as {@link resolveBatchItem}.
  */
-async function resolveBatchItemByMetadata(key, value, itemKey, payload, roles, metadata, resolvedBy) {
+async function resolveBatchItemByMetadata(key, value, itemKey, payload, roles, metadata, resolvedBy, actor) {
     const client = await (0, client_1.escalations)();
     const result = await client.resolveBatchItemByMetadata({
         key,
@@ -61,6 +63,7 @@ async function resolveBatchItemByMetadata(key, value, itemKey, payload, roles, m
         payload,
         metadata,
         resolvedBy,
+        actor,
     });
     return settleBatchOutcome(result, itemKey);
 }

package/build/services/escalation/claim-asserted.d.ts

@@ -0,0 +1,10 @@
+import type { ClaimResult } from './types';
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+export declare const CLAIM_ASSERTED = "WITH target AS MATERIALIZED (\n  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations\n  WHERE id = $6\n    AND metadata @> $1::jsonb\n    AND ($4::text[] IS NULL OR role = ANY($4::text[]))\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n  FOR UPDATE SKIP LOCKED\n)\nUPDATE public.hmsh_escalations e\nSET assigned_to      = $2,\n    claimed_at       = NOW(),\n    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),\n    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),\n    metadata         = CASE WHEN $5::jsonb IS NOT NULL\n                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb\n                            ELSE e.metadata END,\n    updated_at       = NOW()\nFROM target WHERE e.id = target.id\nRETURNING e.*, target.prior_assigned_to\n";
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+export declare function claimAssertedByMetadata(id: string, key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ClaimResult | null>;

package/build/services/escalation/claim-asserted.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAIM_ASSERTED = void 0;
+exports.claimAssertedByMetadata = claimAssertedByMetadata;
+const db_1 = require("../../lib/db");
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+exports.CLAIM_ASSERTED = `\
+WITH target AS MATERIALIZED (
+  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations
+  WHERE id = $6
+    AND metadata @> $1::jsonb
+    AND ($4::text[] IS NULL OR role = ANY($4::text[]))
+    AND status = 'pending'
+    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE public.hmsh_escalations e
+SET assigned_to      = $2,
+    claimed_at       = NOW(),
+    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),
+    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),
+    metadata         = CASE WHEN $5::jsonb IS NOT NULL
+                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb
+                            ELSE e.metadata END,
+    updated_at       = NOW()
+FROM target WHERE e.id = target.id
+RETURNING e.*, target.prior_assigned_to
+`;
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+async function claimAssertedByMetadata(id, key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
+    await (0, client_1.ensureEscalationCompatView)();
+    const { rows } = await (0, db_1.getPool)().query(exports.CLAIM_ASSERTED, [
+        JSON.stringify({ [key]: value }), userId, durationMinutes,
+        allowedRoles ?? null, metadata ? JSON.stringify(metadata) : null, id,
+    ]);
+    if (rows.length === 0)
+        return null;
+    const { prior_assigned_to: prior, ...entry } = rows[0];
+    const escalation = (0, map_1.toEscalationRecord)(entry);
+    (0, crud_1.publishEscalationChange)({
+        type: 'escalation.claimed',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: 'claimed',
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
+    });
+    return { escalation, isExtension: prior === userId };
+}

package/build/services/escalation/facets.d.ts

@@ -2,7 +2,9 @@ import type { ClaimedGroup, FacetQuery, GroupSummary, LTEscalationRecord } from
 /** Ensure the compat view + the origin_id index exist before the first query. */
 export declare function ensureFacetReady(): Promise<void>;
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-export declare function searchByFacets(query: FacetQuery): Promise<{
+export declare function searchByFacets(query: FacetQuery, opts?: {
+    total?: boolean;
+}): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
 }>;

package/build/services/escalation/facets.js

@@ -45,7 +45,7 @@ function ensureFacetReady() {
 }
 // ── Reads ────────────────────────────────────────────────────────────────────
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-async function searchByFacets(query) {
+async function searchByFacets(query, opts = {}) {
     await ensureFacetReady();
     const pool = (0, db_1.getPool)();
     const params = [];
@@ -55,9 +55,13 @@ async function searchByFacets(query) {
     const offset = query.offset ?? 0;
     const [rows, count] = await Promise.all([
         pool.query(`SELECT * FROM public.lt_escalations WHERE ${where} ORDER BY ${order} LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit, offset]),
-        pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
+        // A caller that only picks among a few rows skips the count.
+        opts.total === false
+            ? null
+            : pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
     ]);
-    return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: count.rows[0]?.total ?? 0 };
+    const escalations = (0, map_1.toEscalationRecords)(rows.rows);
+    return { escalations, total: count ? count.rows[0]?.total ?? 0 : escalations.length };
 }
 /**
  * Order-level view of the pond — what a batched dispatcher reads to page by

package/build/services/escalation/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './crud';
+export { claimAssertedByMetadata } from './claim-asserted';
 export * from './batch';
 export * from './accumulate';
 export * from './bulk';

package/build/services/escalation/index.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
+exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
+var claim_asserted_1 = require("./claim-asserted");
+Object.defineProperty(exports, "claimAssertedByMetadata", { enumerable: true, get: function () { return claim_asserted_1.claimAssertedByMetadata; } });
 __exportStar(require("./batch"), exports);
 __exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);

package/build/services/knowledge/lookup-cache.d.ts

@@ -1,4 +1,4 @@
-import type { EscalationLookupRef } from '../../types/escalation';
+import { type EscalationLookupRef } from '../../types/escalation';
 interface KnowledgeSnapshot {
     data: Record<string, unknown>;
     tags: string[];
@@ -6,24 +6,36 @@ interface KnowledgeSnapshot {
 export interface ResolvedLookup {
     domain: string;
     key: string;
-    version: number;
+    /** The edition served; null when a current ref found no edition. */
+    version: number | null;
+    /** The ref follows the newest edition rather than pinning one. */
+    current?: true;
     as?: string;
     data: Record<string, unknown> | null;
     missing?: boolean;
 }
 /** The immutable snapshot at (domain, key, version), or null when absent. */
 export declare function getKnowledgeSnapshot(domain: string, key: string, version: number): Promise<KnowledgeSnapshot | null>;
+/**
+ * The edition a ref names: its pin, or for a current ref the newest edition
+ * (the newest at `asOf` when given, so a closed row reads what was current
+ * when it closed). Null when there is none.
+ */
+export declare function resolveRefEdition(ref: EscalationLookupRef, asOf?: string | null): Promise<{
+    version: number;
+    snapshot: KnowledgeSnapshot;
+} | null>;
 /**
  * Resolve a metadata `lookups` array into the form-context `lookup` domain:
  * { [as ?? key]: data }. Returns null when there is nothing to resolve, so
  * escalations without refs cost zero SQL. Missing snapshots are omitted —
  * interpolated selects then fail closed rather than render the wrong list.
  */
-export declare function resolveLookupContext(refs: unknown): Promise<Record<string, unknown> | null>;
+export declare function resolveLookupContext(refs: unknown, asOf?: string | null): Promise<Record<string, unknown> | null>;
 /**
  * Full per-ref resolution for the lookups endpoint: every ref answers, with
  * `missing: true` marking a pin that has no snapshot — fail-visible per ref
  * without failing the batch.
  */
-export declare function resolveLookupRefs(refs: EscalationLookupRef[]): Promise<ResolvedLookup[]>;
+export declare function resolveLookupRefs(refs: EscalationLookupRef[], asOf?: string | null): Promise<ResolvedLookup[]>;
 export {};