@hotmeshio/long-tail 0.20.0 → 0.21.0

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -37,6 +37,15 @@ var resolve_batch_1 = require("./resolve-batch");
 Object.defineProperty(exports, "resolveBatchItem", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItem; } });
 Object.defineProperty(exports, "resolveBatchItemBySignalKey", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemBySignalKey; } });
 Object.defineProperty(exports, "resolveBatchItemByMetadata", { enumerable: true, get: function () { return resolve_batch_1.resolveBatchItemByMetadata; } });
+var accumulate_1 = require("./accumulate");
+Object.defineProperty(exports, "accumulateItem", { enumerable: true, get: function () { return accumulate_1.accumulateItem; } });
+Object.defineProperty(exports, "accumulateItemBySignalKey", { enumerable: true, get: function () { return accumulate_1.accumulateItemBySignalKey; } });
+Object.defineProperty(exports, "accumulateItemByMetadata", { enumerable: true, get: function () { return accumulate_1.accumulateItemByMetadata; } });
+Object.defineProperty(exports, "removeItem", { enumerable: true, get: function () { return accumulate_1.removeItem; } });
+Object.defineProperty(exports, "removeItemBySignalKey", { enumerable: true, get: function () { return accumulate_1.removeItemBySignalKey; } });
+Object.defineProperty(exports, "removeItemByMetadata", { enumerable: true, get: function () { return accumulate_1.removeItemByMetadata; } });
+Object.defineProperty(exports, "getEscalationItems", { enumerable: true, get: function () { return accumulate_1.getEscalationItems; } });
+Object.defineProperty(exports, "itemsView", { enumerable: true, get: function () { return accumulate_1.itemsView; } });
 var metadata_1 = require("./metadata");
 Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });
 Object.defineProperty(exports, "claimByMetadata", { enumerable: true, get: function () { return metadata_1.claimByMetadata; } });

package/build/api/roles.d.ts

@@ -1,3 +1,4 @@
+import { type RolePin, type RolePortal } from '../services/role/types';
 import type { LTApiResult } from '../types/sdk';
 /**
  * List all distinct role names in the system.
@@ -89,11 +90,9 @@ export declare function updateRole(input: {
     /** The escalation LIST schema — rich formatting for this role's list page. */
     list_schema?: Record<string, any> | null;
     /** Pinned-view seeds for the role's members: [{ label, url, badge? }] or null to clear. */
-    default_pins?: {
-        label: string;
-        url: string;
-        badge?: boolean;
-    }[] | null;
+    default_pins?: RolePin[] | null;
+    /** The role's named portals, each rows of pin cells; null to clear. */
+    portals?: RolePortal[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     /** Make this role's sequence the home Pace Board's default segment (single-holder: setting it clears the previous holder). */

package/build/api/roles.js

@@ -48,6 +48,7 @@ exports.getRoleListSchema = getRoleListSchema;
 exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
+const types_1 = require("../services/role/types");
 const facet_sql_1 = require("../services/escalation/facet-sql");
 /**
  * List all distinct role names in the system.
@@ -201,6 +202,50 @@ async function replaceEscalationTargets(input) {
         return { status: 500, error: err.message };
     }
 }
+/** A pinned view: a non-blank label over a dashboard-relative url, optionally badged. */
+function isRolePin(p) {
+    if (!p || typeof p !== 'object')
+        return false;
+    const pin = p;
+    return typeof pin.label === 'string' && pin.label.trim() !== ''
+        && typeof pin.url === 'string' && pin.url.startsWith('/')
+        && (pin.badge === undefined || typeof pin.badge === 'boolean');
+}
+/** Rows of pin cells within the portal bounds; every row carries at least one pin. */
+function isPortalRows(value) {
+    return Array.isArray(value)
+        && value.length >= 1 && value.length <= types_1.PORTAL_LIMITS.MAX_ROWS
+        && value.every((row) => Array.isArray(row)
+            && row.length >= 1 && row.length <= types_1.PORTAL_LIMITS.MAX_COLS
+            && row.every(isRolePin));
+}
+/** A count tile: a pin plus an optional blurb. */
+function isPortalCount(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const blurb = value.blurb;
+    return isRolePin(value) && (blurb === undefined || typeof blurb === 'string');
+}
+/** A named portal: slug key, non-blank label, a valid matrix, optional bounded counts. */
+function isRolePortal(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const portal = value;
+    const countsOk = portal.counts === undefined
+        || (Array.isArray(portal.counts) && portal.counts.length <= types_1.PORTAL_LIMITS.MAX_COUNTS && portal.counts.every(isPortalCount));
+    return typeof portal.key === 'string' && types_1.PORTAL_KEY.test(portal.key)
+        && typeof portal.label === 'string' && portal.label.trim() !== ''
+        && isPortalRows(portal.rows)
+        && countsOk;
+}
+/** The role's portals: bounded in number, every key unique. */
+function isPortalList(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > types_1.PORTAL_LIMITS.MAX_PORTALS)
+        return false;
+    if (!value.every(isRolePortal))
+        return false;
+    return new Set(value.map((p) => p.key)).size === value.length;
+}
 /**
  * Update role metadata. Fields omitted from input are left unchanged.
  * form_schema, metadata_schema, and parent_role can be set to null to clear them.
@@ -241,14 +286,17 @@ async function updateRole(input) {
             return { status: 400, error: 'parent_role must reference a different role' };
         }
         if (input.default_pins != null) {
-            const pinsValid = Array.isArray(input.default_pins) && input.default_pins.every((p) => p && typeof p === 'object'
-                && typeof p.label === 'string' && p.label.trim() !== ''
-                && typeof p.url === 'string' && p.url.startsWith('/')
-                && (p.badge === undefined || typeof p.badge === 'boolean'));
+            const pinsValid = Array.isArray(input.default_pins) && input.default_pins.every(isRolePin);
             if (!pinsValid) {
                 return { status: 400, error: 'default_pins must be [{ label, url, badge? }] with dashboard-relative urls' };
             }
         }
+        if (input.portals != null && !isPortalList(input.portals)) {
+            return {
+                status: 400,
+                error: `portals must be 1..${types_1.PORTAL_LIMITS.MAX_PORTALS} of { key (slug, unique), label, rows, counts? }, rows being 1..${types_1.PORTAL_LIMITS.MAX_ROWS} rows of 1..${types_1.PORTAL_LIMITS.MAX_COLS} pins [{ label, url, badge? }] with dashboard-relative urls, counts up to ${types_1.PORTAL_LIMITS.MAX_COUNTS} of { label, url, blurb? }`,
+            };
+        }
         if (input.upstream_roles != null) {
             if (!Array.isArray(input.upstream_roles) || input.upstream_roles.some((u) => typeof u !== 'string' || !u.trim())) {
                 return { status: 400, error: 'upstream_roles must be an array of role names' };
@@ -269,6 +317,7 @@ async function updateRole(input) {
             metadata_schema: input.metadata_schema,
             list_schema: input.list_schema,
             default_pins: input.default_pins,
+            portals: input.portals,
             properties: input.properties,
             ops_visible: input.ops_visible,
             ops_home_default: input.ops_home_default,

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

@@ -171,6 +171,8 @@ async function executeStep(step, index, ctx) {
             return (0, verbs_1.releaseStep)(step, ctx);
         case types_1.SCAN_VERBS.CANCEL:
             return (0, verbs_1.cancelStep)(step, ctx);
+        case types_1.SCAN_VERBS.ACCUMULATE:
+            return (0, verbs_1.accumulateStep)(step, ctx);
         default:
             throw new Error(`unknown scan verb "${step.verb}"`);
     }

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

@@ -13,3 +13,18 @@ export declare function releaseStep(step: ScanStep, ctx: StepContext): Promise<L
  */
 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>;
+/**
+ * Adds the scanned item to an accumulator. Two modes, one atomic write:
+ *
+ * - Item-locate (`params.accumulate.containerFacet`): the scan locates the
+ *   item's own pending row through the scheme facet, reads the container
+ *   facet value it carries, and adds the target to the container that shares
+ *   it, writing the item row as the reciprocal in the same statement. An
+ *   item with no row, or no container facet, falls through.
+ * - Container-locate (no `containerFacet`): the scan locates the container
+ *   by the scheme facet and adds `params.itemKey` (template).
+ *
+ * The write is the SDK's guarded statement; the locate only picks ids. A
+ * container already holding the item answers conflict, never a second add.
+ */
+export declare function accumulateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;

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

@@ -39,14 +39,17 @@ exports.escalateStep = escalateStep;
 exports.releaseStep = releaseStep;
 exports.dispatchChoiceVerb = dispatchChoiceVerb;
 exports.cancelStep = cancelStep;
+exports.accumulateStep = accumulateStep;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const metadata_1 = require("../escalations/metadata");
+const accumulate_1 = require("../escalations/accumulate");
 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");
+const locate_1 = require("./locate");
 // ── 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
@@ -203,3 +206,65 @@ async function cancelStep(step, ctx) {
         return (0, context_1.conflict)('Escalation is not cancellable (already terminal)');
     return (0, context_1.executed)(cancelled, step);
 }
+/**
+ * Adds the scanned item to an accumulator. Two modes, one atomic write:
+ *
+ * - Item-locate (`params.accumulate.containerFacet`): the scan locates the
+ *   item's own pending row through the scheme facet, reads the container
+ *   facet value it carries, and adds the target to the container that shares
+ *   it, writing the item row as the reciprocal in the same statement. An
+ *   item with no row, or no container facet, falls through.
+ * - Container-locate (no `containerFacet`): the scan locates the container
+ *   by the scheme facet and adds `params.itemKey` (template).
+ *
+ * The write is the SDK's guarded statement; the locate only picks ids. A
+ * container already holding the item answers conflict, never a second add.
+ */
+async function accumulateStep(step, ctx) {
+    const tpl = (0, context_1.templateContext)(ctx);
+    const payload = step.params?.resolverPayload
+        ? scanCodeService.interpolateScanTemplate(step.params.resolverPayload, tpl)
+        : undefined;
+    const metadata = { ...(0, context_1.interpolatedMetadata)(step, ctx), ...(0, context_1.provenance)(ctx) };
+    const options = step.params?.accumulate;
+    let request;
+    if (options?.containerFacet) {
+        const located = await (0, locate_1.locateForStep)(step, ctx, 1);
+        const item = located?.escalations[0];
+        if (!item)
+            return null;
+        const containerValue = item.metadata?.[options.containerFacet];
+        if (containerValue === undefined || containerValue === null || containerValue === '')
+            return null;
+        request = {
+            key: options.containerFacet,
+            value: String(containerValue),
+            itemKey: ctx.parsed.target,
+            payload,
+            metadata,
+            restrictRoles: options.containerRoles,
+            ...(options.reciprocal === false ? {} : { reciprocal: { id: item.id } }),
+        };
+    }
+    else {
+        request = {
+            key: ctx.scheme.target_facet,
+            value: ctx.parsed.target,
+            itemKey: scanCodeService.interpolateScanTemplate(step.params.itemKey, tpl),
+            payload,
+            metadata,
+            restrictRoles: step.query?.roles,
+        };
+    }
+    const result = await (0, accumulate_1.accumulateItemByMetadata)(request, 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.escalationId ? { id: result.data.escalationId, ...result.data } : undefined;
+    return (0, context_1.executed)(escalation, step);
+}

package/build/index.js

@@ -168,6 +168,66 @@ async function main() {
             },
         },
         examples: true,
+        // Code-owned declaration for the reviewer queue the examples route to: a
+        // portal that leads with the queue's counts and lays its lists beneath.
+        // `reset` keeps the declaration applied on every boot.
+        roles: [
+            {
+                role: 'reviewer',
+                title: 'Reviewer',
+                reset: true,
+                portals: [
+                    {
+                        key: 'review-desk',
+                        label: 'Review desk',
+                        counts: [
+                            { label: 'Waiting', url: '/escalations/available?role=reviewer', blurb: 'Unclaimed items in the queue' },
+                            { label: 'In progress', url: '/escalations/available?role=reviewer&status=claimed', blurb: 'Claimed and being worked' },
+                            { label: 'Resolved', url: '/escalations/available?role=reviewer&status=resolved', blurb: 'Closed out by a reviewer' },
+                            { label: 'Expired', url: '/escalations/available?role=reviewer&status=expired', blurb: 'Timed out before anyone acted' },
+                            { label: 'Cancelled', url: '/escalations/available?role=reviewer&status=cancelled', blurb: 'Withdrawn by the workflow' },
+                        ],
+                        rows: [
+                            [
+                                { label: 'Waiting', url: '/escalations/available?role=reviewer&view=table&layout=compact', badge: true },
+                                { label: 'In progress', url: '/escalations/available?role=reviewer&status=claimed&view=table&layout=compact', badge: true },
+                            ],
+                        ],
+                    },
+                ],
+            },
+            {
+                // The rollup-bin example's container queue: the list shows each
+                // bin's fill level from the accumulator facets.
+                role: 'bin',
+                title: 'Bin',
+                description: 'Open containers filling with scanned bags. Ships at max or when the window closes.',
+                reset: true,
+                list_schema: {
+                    'x-lt-layout': 'facet-table',
+                    'x-lt-columns': [
+                        { label: 'Bin', value: '{{metadata.binKey}}' },
+                        { label: 'Held', value: '{{metadata.accumulate_count}}' },
+                        { label: 'Max', value: '{{metadata.accumulate_max}}', priority: 2 },
+                        { label: 'Open since', value: '{{escalation.created_at}}', format: 'age', priority: 2 },
+                    ],
+                },
+            },
+            {
+                role: 'bag',
+                title: 'Bag',
+                description: 'Bags waiting to be scanned into a bin.',
+                reset: true,
+                list_schema: {
+                    'x-lt-layout': 'facet-table',
+                    'x-lt-columns': [
+                        { label: 'Order', value: '{{metadata.orderId}}' },
+                        { label: 'Bin', value: '{{metadata.binKey}}', priority: 2 },
+                        { label: 'Waiting', value: '{{escalation.created_at}}', format: 'age', priority: 2 },
+                    ],
+                },
+            },
+        ],
         features: {
             // The examples ship the full scan demo (schemes 10/11); surface it.
             scanCodes: true,

package/build/lib/db/schemas/036_role_portals.sql

@@ -0,0 +1,12 @@
+-- Migration 036: Role portals
+--
+-- portals is a role-owned list of named portal views. Each portal is a matrix
+-- of pins: rows of cells, each cell a pinned view ({ label, url, badge? }).
+-- The dashboard renders a portal as one page of live list panels at
+-- /portal/:role/:portal, the visual form of the role's pinned views: one
+-- portal for urgent items by facility, another for the team's focus of the
+-- day, each cell named for a person and scoped to their facets. Unversioned
+-- config, like default_pins; null means the role declares no portal.
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS portals JSONB;

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

@@ -0,0 +1,7 @@
+import type { Router } from 'express';
+/**
+ * Open-accumulator routes. The literal single-segment paths are registered
+ * before the parameterized routes so /:id never shadows them; the /:id/*
+ * forms run as the effective work actor (badge continuity at a station).
+ */
+export declare function registerAccumulateRoutes(router: Router): void;

package/build/routes/escalations/accumulate.js

@@ -0,0 +1,150 @@
+"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.registerAccumulateRoutes = registerAccumulateRoutes;
+const api = __importStar(require("../../api/escalations"));
+const acting_1 = require("./acting");
+/**
+ * Open-accumulator routes. The literal single-segment paths are registered
+ * before the parameterized routes so /:id never shadows them; the /:id/*
+ * forms run as the effective work actor (badge continuity at a station).
+ */
+function registerAccumulateRoutes(router) {
+    /**
+     * POST /api/escalations/accumulate-by-signal-key
+     * Add one item to an accumulator escalation by its signal_key.
+     * Body: { signalKey, itemKey, payload?, metadata?, reciprocal? }
+     */
+    router.post('/accumulate-by-signal-key', async (req, res) => {
+        const result = await api.accumulateItemBySignalKey({
+            signalKey: req.body?.signalKey,
+            itemKey: req.body?.itemKey,
+            payload: req.body?.payload,
+            metadata: req.body?.metadata,
+            reciprocal: req.body?.reciprocal,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/accumulate-by-metadata
+     * Add one item to the highest priority pending accumulator whose metadata
+     * contains the key/value.
+     * Body: { key, value, itemKey, payload?, metadata?, restrictRoles?, reciprocal? }
+     */
+    router.post('/accumulate-by-metadata', async (req, res) => {
+        const result = await api.accumulateItemByMetadata({
+            key: req.body?.key,
+            value: req.body?.value,
+            itemKey: req.body?.itemKey,
+            payload: req.body?.payload,
+            metadata: req.body?.metadata,
+            restrictRoles: req.body?.restrictRoles,
+            reciprocal: req.body?.reciprocal,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/remove-item-by-signal-key
+     * Body: { signalKey, itemKey, reciprocal? }
+     */
+    router.post('/remove-item-by-signal-key', async (req, res) => {
+        const result = await api.removeItemBySignalKey({
+            signalKey: req.body?.signalKey,
+            itemKey: req.body?.itemKey,
+            reciprocal: req.body?.reciprocal,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/remove-item-by-metadata
+     * Body: { key, value, itemKey, restrictRoles?, reciprocal? }
+     */
+    router.post('/remove-item-by-metadata', async (req, res) => {
+        const result = await api.removeItemByMetadata({
+            key: req.body?.key,
+            value: req.body?.value,
+            itemKey: req.body?.itemKey,
+            restrictRoles: req.body?.restrictRoles,
+            reciprocal: req.body?.reciprocal,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/accumulate
+     * Add one item. Interim adds answer { outcome: 'accepted', count, remaining };
+     * the add that reaches max answers { outcome: 'completed', signaled } and the
+     * waiting workflow resumes with the collection. Claim-agnostic unless
+     * assertClaim: true.
+     * Body: { itemKey, payload?, metadata?, assertClaim?, reciprocal? }
+     */
+    router.post('/:id/accumulate', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.accumulateItem({
+            id: req.params.id,
+            itemKey: req.body?.itemKey,
+            payload: req.body?.payload,
+            metadata: req.body?.metadata,
+            assertClaim: req.body?.assertClaim,
+            reciprocal: req.body?.reciprocal,
+        }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/remove-item
+     * Remove one held item; the row stays pending and the waiter never wakes.
+     * Body: { itemKey, reciprocal? }
+     */
+    router.post('/:id/remove-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.removeItem({
+            id: req.params.id,
+            itemKey: req.body?.itemKey,
+            reciprocal: req.body?.reciprocal,
+        }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * GET /api/escalations/:id/items
+     * The held items of an accumulator or batch row in arrival order.
+     */
+    router.get('/:id/items', async (req, res) => {
+        const result = await api.getEscalationItems({ id: req.params.id }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+}

package/build/routes/escalations/index.js

@@ -4,6 +4,7 @@ const express_1 = require("express");
 const list_1 = require("./list");
 const bulk_1 = require("./bulk");
 const metadata_1 = require("./metadata");
+const accumulate_1 = require("./accumulate");
 const single_1 = require("./single");
 const resolve_1 = require("./resolve");
 const facets_1 = require("./facets");
@@ -17,6 +18,10 @@ const router = (0, express_1.Router)();
 (0, bulk_1.registerBulkRoutes)(router);
 // GET /by-metadata, POST /claim-by-metadata, POST /resolve-by-metadata
 (0, metadata_1.registerMetadataRoutes)(router);
+// POST /accumulate-by-signal-key, /accumulate-by-metadata,
+// /remove-item-by-signal-key, /remove-item-by-metadata,
+// POST /:id/accumulate, POST /:id/remove-item, GET /:id/items
+(0, accumulate_1.registerAccumulateRoutes)(router);
 // POST /search-by-facets, /claim-groups, /claim-by-facets
 (0, facets_1.registerFacetRoutes)(router);
 // POST /aggregate-by-facets, /timeline-by-facet

package/build/sdk/index.d.ts

@@ -244,6 +244,31 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             restrictRoles?: string[];
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        accumulate: (input: {
+            id: string;
+        } & import("../api/escalations/accumulate").AccumulateItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        accumulateBySignalKey: (input: {
+            signalKey: string;
+        } & Omit<import("../api/escalations/accumulate").AccumulateItemInput, "assertClaim">, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        accumulateByMetadata: (input: {
+            key: string;
+            value: string;
+            restrictRoles?: string[];
+        } & Omit<import("../api/escalations/accumulate").AccumulateItemInput, "assertClaim">, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        removeItem: (input: {
+            id: string;
+        } & import("../api/escalations/accumulate").RemoveItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        removeItemBySignalKey: (input: {
+            signalKey: string;
+        } & import("../api/escalations/accumulate").RemoveItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        removeItemByMetadata: (input: {
+            key: string;
+            value: string;
+            restrictRoles?: string[];
+        } & import("../api/escalations/accumulate").RemoveItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getItems: (input: {
+            id: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<import("../api/escalations/accumulate").EscalationItemsView>>;
         searchByFacets: (input: import("..").FacetQuery, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         claimGroups: (input: {
             query: import("..").FacetQuery;

package/build/sdk/index.js

@@ -146,6 +146,14 @@ function createClient(options = {}) {
             resolveBatchItem: bindAuth(escalationsApi.resolveBatchItem, auth),
             resolveBatchItemBySignalKey: bindAuth(escalationsApi.resolveBatchItemBySignalKey, auth),
             resolveBatchItemByMetadata: bindAuth(escalationsApi.resolveBatchItemByMetadata, auth),
+            // Open accumulation: add and remove held items, read the ordered collection.
+            accumulate: bindAuth(escalationsApi.accumulateItem, auth),
+            accumulateBySignalKey: bindAuth(escalationsApi.accumulateItemBySignalKey, auth),
+            accumulateByMetadata: bindAuth(escalationsApi.accumulateItemByMetadata, auth),
+            removeItem: bindAuth(escalationsApi.removeItem, auth),
+            removeItemBySignalKey: bindAuth(escalationsApi.removeItemBySignalKey, auth),
+            removeItemByMetadata: bindAuth(escalationsApi.removeItemByMetadata, auth),
+            getItems: bindAuth(escalationsApi.getEscalationItems, auth),
             // Faceted-routing surface (pond search + batch claim), RBAC-scoped to the caller's role.
             searchByFacets: bindAuth(escalationsApi.searchByFacets, auth),
             claimGroups: bindAuth(escalationsApi.claimGroups, auth),

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

@@ -0,0 +1,81 @@
+import type { AccumulateItemOutcome, LTEscalationRecord, RemoveAccumulatedItemOutcome } from '../../types';
+/** Names the second row of a reciprocal add or removal. Exactly one selector. */
+export interface AccumulateReciprocal {
+    id?: string;
+    signalKey?: string;
+    key?: string;
+    value?: unknown;
+    roles?: string[];
+    /** Stored as the reciprocal entry's payload. */
+    payload?: Record<string, any>;
+}
+export interface AccumulateItemInput {
+    itemKey: string;
+    payload?: Record<string, any>;
+    /** Merge patch for the container's GIN-indexed metadata, same statement. */
+    metadata?: Record<string, any>;
+    /** Recorded on both entries as `actor`. */
+    actor?: string;
+    /** Claim-lock assertion on the container row (by-id form only). */
+    assertClaim?: string;
+    resolvedBy?: {
+        id: string;
+        email?: string;
+    };
+    reciprocal?: AccumulateReciprocal;
+}
+export interface AccumulateSideOutcome {
+    outcome: 'completed' | 'accepted';
+    count: number;
+    /** `max - count`, or null when the accumulator is unbounded. */
+    remaining: number | null;
+    escalation: LTEscalationRecord;
+}
+export interface AccumulateItemServiceOutcome {
+    outcome: AccumulateItemOutcome;
+    /** Items held after the add; -1 on every failure outcome. */
+    count: number;
+    remaining: number | null;
+    /** The post-add container row on `completed`/`accepted`; null on failure. */
+    escalation: LTEscalationRecord | null;
+    reciprocal?: AccumulateSideOutcome;
+}
+export interface RemoveItemInput {
+    itemKey: string;
+    actor?: string;
+    reciprocal?: Omit<AccumulateReciprocal, 'payload'>;
+}
+export interface RemoveItemServiceOutcome {
+    outcome: RemoveAccumulatedItemOutcome;
+    count: number;
+    escalation: LTEscalationRecord | null;
+    reciprocal?: {
+        count: number;
+        escalation: LTEscalationRecord;
+    };
+}
+/**
+ * Adds one item to an accumulator escalation in a single atomic SDK
+ * statement (guarded append + facet recompute + resolve-and-wake at max,
+ * with the reciprocal row written in the same statement or not at all).
+ * Interim adds publish `escalation.updated` with the count; a completing
+ * add publishes the standard `escalation.resolved`. Both rows publish.
+ * Failure outcomes publish nothing because no row changed.
+ */
+export declare function accumulateItem(id: string, input: AccumulateItemInput): Promise<AccumulateItemServiceOutcome>;
+/** Add selecting the container by its `signal_key`, the deterministic home signal id. */
+export declare function accumulateItemBySignalKey(signalKey: string, input: Omit<AccumulateItemInput, 'assertClaim'>): Promise<AccumulateItemServiceOutcome>;
+/** Add selecting the container by metadata facet, scoped by `roles`. */
+export declare function accumulateItemByMetadata(key: string, value: unknown, input: Omit<AccumulateItemInput, 'assertClaim'> & {
+    roles?: string[];
+}): Promise<AccumulateItemServiceOutcome>;
+/**
+ * Removes one held item from a pending accumulator escalation (and the
+ * container's id from the reciprocal row) in one guarded statement. The
+ * waiter never wakes; both rows publish `escalation.updated`.
+ */
+export declare function removeAccumulatedItem(id: string, input: RemoveItemInput): Promise<RemoveItemServiceOutcome>;
+export declare function removeAccumulatedItemBySignalKey(signalKey: string, input: RemoveItemInput): Promise<RemoveItemServiceOutcome>;
+export declare function removeAccumulatedItemByMetadata(key: string, value: unknown, input: RemoveItemInput & {
+    roles?: string[];
+}): Promise<RemoveItemServiceOutcome>;