@hotmeshio/long-tail 0.20.0 → 0.21.1

package/build/routes/escalations/accumulate.js

@@ -0,0 +1,158 @@
+"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 });
+    });
+    /**
+     * GET /api/escalations/items-by-signal-key?signalKey=…
+     * The held items of an accumulator or batch row by its signal_key.
+     */
+    router.get('/items-by-signal-key', async (req, res) => {
+        const result = await api.getEscalationItemsBySignalKey({ signalKey: String(req.query.signalKey ?? '') }, 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,34 @@ 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>>;
+        getItemsBySignalKey: (input: {
+            signalKey: 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,15 @@ 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),
+            getItemsBySignalKey: bindAuth(escalationsApi.getEscalationItemsBySignalKey, 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>;

package/build/services/escalation/accumulate.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accumulateItem = accumulateItem;
+exports.accumulateItemBySignalKey = accumulateItemBySignalKey;
+exports.accumulateItemByMetadata = accumulateItemByMetadata;
+exports.removeAccumulatedItem = removeAccumulatedItem;
+exports.removeAccumulatedItemBySignalKey = removeAccumulatedItemBySignalKey;
+exports.removeAccumulatedItemByMetadata = removeAccumulatedItemByMetadata;
+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");
+const NOT_FOUND = { outcome: 'not-found', count: -1, remaining: null, escalation: null };
+const RECIPROCAL_NOT_FOUND = { ...NOT_FOUND, outcome: 'reciprocal-not-found' };
+function reciprocalIdValid(reciprocal) {
+    return !reciprocal?.id || (0, uuid_1.isUuid)(reciprocal.id);
+}
+/**
+ * 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.
+ */
+async function accumulateItem(id, input) {
+    if (!(0, uuid_1.isUuid)(id))
+        return NOT_FOUND;
+    if (!reciprocalIdValid(input.reciprocal))
+        return RECIPROCAL_NOT_FOUND;
+    const client = await (0, client_1.escalations)();
+    const result = await client.accumulateItem({ id, ...input });
+    return settleAccumulateOutcome(result, input);
+}
+/** Add selecting the container by its `signal_key`, the deterministic home signal id. */
+async function accumulateItemBySignalKey(signalKey, input) {
+    if (!reciprocalIdValid(input.reciprocal))
+        return RECIPROCAL_NOT_FOUND;
+    const client = await (0, client_1.escalations)();
+    const result = await client.accumulateItem({ signalKey, ...input });
+    return settleAccumulateOutcome(result, input);
+}
+/** Add selecting the container by metadata facet, scoped by `roles`. */
+async function accumulateItemByMetadata(key, value, input) {
+    if (!reciprocalIdValid(input.reciprocal))
+        return RECIPROCAL_NOT_FOUND;
+    const client = await (0, client_1.escalations)();
+    const result = await client.accumulateItemByMetadata({ key, value, ...input });
+    return settleAccumulateOutcome(result, input);
+}
+/**
+ * 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`.
+ */
+async function removeAccumulatedItem(id, input) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', count: -1, escalation: null };
+    if (!reciprocalIdValid(input.reciprocal))
+        return { outcome: 'reciprocal-not-found', count: -1, escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.removeAccumulatedItem({ id, ...input });
+    return settleRemoveOutcome(result, input);
+}
+async function removeAccumulatedItemBySignalKey(signalKey, input) {
+    if (!reciprocalIdValid(input.reciprocal))
+        return { outcome: 'reciprocal-not-found', count: -1, escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.removeAccumulatedItem({ signalKey, ...input });
+    return settleRemoveOutcome(result, input);
+}
+async function removeAccumulatedItemByMetadata(key, value, input) {
+    if (!reciprocalIdValid(input.reciprocal))
+        return { outcome: 'reciprocal-not-found', count: -1, escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.removeAccumulatedItemByMetadata({ key, value, ...input });
+    return settleRemoveOutcome(result, input);
+}
+function publishSide(escalation, completed, data) {
+    (0, crud_1.publishEscalationChange)({
+        type: completed ? 'escalation.resolved' : 'escalation.updated',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: completed ? 'resolved' : 'pending',
+        data: (0, escalation_wire_1.escalationEventData)(escalation, data),
+    });
+}
+function settleAccumulateOutcome(result, input) {
+    if (!result.ok) {
+        return { outcome: result.outcome, count: -1, remaining: null, escalation: null };
+    }
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    const reciprocal = result.reciprocal
+        ? {
+            outcome: result.reciprocal.outcome,
+            count: result.reciprocal.count,
+            remaining: result.reciprocal.remaining,
+            escalation: (0, map_1.toEscalationRecord)(result.reciprocal.entry),
+        }
+        : undefined;
+    publishSide(escalation, result.outcome === 'completed', {
+        item_key: input.itemKey,
+        count: result.count,
+        remaining: result.remaining,
+        actor: input.actor ?? null,
+        reciprocal_id: reciprocal?.escalation.id ?? null,
+    });
+    if (reciprocal) {
+        publishSide(reciprocal.escalation, reciprocal.outcome === 'completed', {
+            item_key: escalation.id,
+            count: reciprocal.count,
+            remaining: reciprocal.remaining,
+            actor: input.actor ?? null,
+            reciprocal_id: escalation.id,
+        });
+    }
+    return {
+        outcome: result.outcome,
+        count: result.count,
+        remaining: result.remaining,
+        escalation,
+        ...(reciprocal ? { reciprocal } : {}),
+    };
+}
+function settleRemoveOutcome(result, input) {
+    if (!result.ok)
+        return { outcome: result.outcome, count: -1, escalation: null };
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    const reciprocal = result.reciprocal
+        ? { count: result.reciprocal.count, escalation: (0, map_1.toEscalationRecord)(result.reciprocal.entry) }
+        : undefined;
+    publishSide(escalation, false, {
+        item_key: input.itemKey,
+        count: result.count,
+        removed: true,
+        actor: input.actor ?? null,
+        reciprocal_id: reciprocal?.escalation.id ?? null,
+    });
+    if (reciprocal) {
+        publishSide(reciprocal.escalation, false, {
+            item_key: escalation.id,
+            count: reciprocal.count,
+            removed: true,
+            actor: input.actor ?? null,
+            reciprocal_id: escalation.id,
+        });
+    }
+    return { outcome: 'removed', count: result.count, escalation, ...(reciprocal ? { reciprocal } : {}) };
+}

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

@@ -1,6 +1,7 @@
 export * from './types';
 export * from './crud';
 export * from './batch';
+export * from './accumulate';
 export * from './bulk';
 export * from './queries';
 export * from './resolver-validation';

package/build/services/escalation/index.js

@@ -18,6 +18,7 @@ exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEnti
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 __exportStar(require("./batch"), exports);
+__exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);
 __exportStar(require("./queries"), exports);
 __exportStar(require("./resolver-validation"), exports);

package/build/services/mcp/playwright-server/schemas.d.ts

@@ -54,12 +54,12 @@ export declare const waitForSchema: z.ZodObject<{
     timeout: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     selector: string;
-    page_id?: string | undefined;
     timeout?: number | undefined;
+    page_id?: string | undefined;
 }, {
     selector: string;
-    page_id?: string | undefined;
     timeout?: number | undefined;
+    page_id?: string | undefined;
 }>;
 export declare const evaluateSchema: z.ZodObject<{
     page_id: z.ZodOptional<z.ZodString>;

package/build/services/orchestrator/condition.d.ts

@@ -1,5 +1,5 @@
 import type { Types } from '@hotmeshio/hotmesh';
-import { type EscalationLookupRef } from '../../types/escalation';
+import { type AccumulateConfig, type AccumulatorResult, type EscalationLookupRef } from '../../types/escalation';
 /**
  * HotMesh's escalation config plus long-tail sugar. `schemaVersion` pins the
  * role form version (lt_role_schemas) the resolve UI renders; `lookups` pins
@@ -116,8 +116,32 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * ```
  *
  * `timeout`/cancel semantics are unchanged (`false`/`null`); partially filled
- * items persist on the terminal row for audit. A plain resolve on a batch row
- * remains an admin override that resolves the whole row with its payload.
+ * items persist on the terminal row for audit. Add `partialOnTimeout: true`
+ * (hotmesh 0.29.0+) and the timer instead resumes with the items filled so
+ * far plus `$trigger: 'timeout'`. A plain resolve on a batch row remains an
+ * admin override that resolves the whole row with its payload.
+ *
+ * **Open accumulation — items arrive over time (hotmesh 0.29.0+).** Declare
+ * `accumulate` and the escalation holds items added via `accumulateItem`
+ * (HTTP: POST /:id/accumulate, /accumulate-by-signal-key,
+ * /accumulate-by-metadata) until `max` items are held, the `timeout` fires,
+ * or someone resolves the row. Every path except cancel delivers the ordered
+ * collection with the trigger that ended the wait, so a timeout is a
+ * delivery window, never a failure. Progress rides `metadata.accumulate_count`
+ * / `accumulate_max` / `accumulate_keys` as queryable facets; entries live in
+ * `envelope.accumulate_items`. Use {@link conditionalAccumulator} for the
+ * typed form:
+ *
+ * ```typescript
+ * const bin = await conditionalAccumulator<BagV1>(signalId, {
+ *   role: 'bin',
+ *   metadata: { binKey },
+ *   accumulate: { max: 12 },
+ *   timeout: '4h',
+ * });
+ * if (bin === null) { /* cancelled *​/ }
+ * else bin.$trigger; // 'count' | 'timeout' | 'resolve'
+ * ```
  *
  * **Resolution provenance — the reserved `$resolution` key.** When the resolve
  * carries the resolver's identity (the API layer supplies it for interactive
@@ -155,3 +179,16 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
 export declare function conditional<T = Record<string, any>>(signalId: string, escalation?: ConditionEscalationConfig): Promise<T | false | null>;
 /** @deprecated Alias of {@link conditional}. */
 export declare const conditionLT: typeof conditional;
+/** {@link ConditionEscalationConfig} with the accumulator declaration required. */
+export type ConditionAccumulatorConfig = ConditionEscalationConfig & {
+    accumulate: AccumulateConfig;
+};
+/**
+ * {@link conditional} for an open accumulator: the same wait, typed for the
+ * contract an accumulator row keeps. It resolves with the ordered
+ * `$accumulated` collection and its `$trigger` on every terminal path
+ * (`count`, `timeout`, `resolve`), so `false` is not in the return type;
+ * cancellation still yields `null`. `P` types each item's payload, `R` the
+ * manual resolver payload merged in on `resolve`.
+ */
+export declare function conditionalAccumulator<P = Record<string, any>, R extends Record<string, any> = Record<string, any>>(signalId: string, escalation: ConditionAccumulatorConfig): Promise<AccumulatorResult<P, R> | null>;

package/build/services/orchestrator/condition.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.conditionLT = void 0;
 exports.conditional = conditional;
+exports.conditionalAccumulator = conditionalAccumulator;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
 const escalation_1 = require("../../types/escalation");
 const interceptorActivities = __importStar(require("../interceptor/activities"));
@@ -162,8 +163,32 @@ function toEngineConfig(escalation) {
  * ```
  *
  * `timeout`/cancel semantics are unchanged (`false`/`null`); partially filled
- * items persist on the terminal row for audit. A plain resolve on a batch row
- * remains an admin override that resolves the whole row with its payload.
+ * items persist on the terminal row for audit. Add `partialOnTimeout: true`
+ * (hotmesh 0.29.0+) and the timer instead resumes with the items filled so
+ * far plus `$trigger: 'timeout'`. A plain resolve on a batch row remains an
+ * admin override that resolves the whole row with its payload.
+ *
+ * **Open accumulation — items arrive over time (hotmesh 0.29.0+).** Declare
+ * `accumulate` and the escalation holds items added via `accumulateItem`
+ * (HTTP: POST /:id/accumulate, /accumulate-by-signal-key,
+ * /accumulate-by-metadata) until `max` items are held, the `timeout` fires,
+ * or someone resolves the row. Every path except cancel delivers the ordered
+ * collection with the trigger that ended the wait, so a timeout is a
+ * delivery window, never a failure. Progress rides `metadata.accumulate_count`
+ * / `accumulate_max` / `accumulate_keys` as queryable facets; entries live in
+ * `envelope.accumulate_items`. Use {@link conditionalAccumulator} for the
+ * typed form:
+ *
+ * ```typescript
+ * const bin = await conditionalAccumulator<BagV1>(signalId, {
+ *   role: 'bin',
+ *   metadata: { binKey },
+ *   accumulate: { max: 12 },
+ *   timeout: '4h',
+ * });
+ * if (bin === null) { /* cancelled *​/ }
+ * else bin.$trigger; // 'count' | 'timeout' | 'resolve'
+ * ```
  *
  * **Resolution provenance — the reserved `$resolution` key.** When the resolve
  * carries the resolver's identity (the API layer supplies it for interactive
@@ -231,3 +256,18 @@ async function conditional(signalId, escalation) {
 }
 /** @deprecated Alias of {@link conditional}. */
 exports.conditionLT = conditional;
+/**
+ * {@link conditional} for an open accumulator: the same wait, typed for the
+ * contract an accumulator row keeps. It resolves with the ordered
+ * `$accumulated` collection and its `$trigger` on every terminal path
+ * (`count`, `timeout`, `resolve`), so `false` is not in the return type;
+ * cancellation still yields `null`. `P` types each item's payload, `R` the
+ * manual resolver payload merged in on `resolve`.
+ */
+async function conditionalAccumulator(signalId, escalation) {
+    const result = await conditional(signalId, escalation);
+    if (result === false) {
+        throw new Error(`Accumulator wait ${signalId} resumed with false; expected a delivered collection`);
+    }
+    return result;
+}

package/build/services/role/index.js

@@ -153,6 +153,7 @@ async function updateRoleMetadata(role, input) {
         provided('ops_home_default'), input.ops_home_default ?? null,
         provided('entity_facet'), input.entity_facet ?? null,
         provided('entity_state_source'), input.entity_state_source ?? null,
+        provided('portals'), input.portals != null ? JSON.stringify(input.portals) : null,
     ]);
     if (!rows[0])
         return null;

package/build/services/role/seed.js

@@ -14,10 +14,12 @@ exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
 const METADATA_FIELDS = [
     'title', 'description', 'form_schema', 'metadata_schema', 'list_schema',
     'properties', 'ops_visible', 'ops_home_default', 'parent_role',
-    'upstream_roles', 'default_pins', 'enforce_schema', 'sla_minutes',
+    'upstream_roles', 'default_pins', 'portals', 'enforce_schema', 'sla_minutes',
     'target_per_hour', 'worker_count', 'priority_threshold_minutes',
     'priority_facet', 'entity_facet', 'entity_state_source',
 ];
+// Arrays whose order is meaning (portals and their rows), compared as declared.
+const ORDERED_ARRAY_FIELDS = new Set(['portals']);
 /**
  * Compare one declared field against the stored row. jsonb round-trips lose
  * key order, so structured values must be compared as parsed values — never
@@ -25,6 +27,9 @@ const METADATA_FIELDS = [
  */
 function fieldDiffers(field, declared, row) {
     const stored = row[field];
+    if (Array.isArray(declared) && ORDERED_ARRAY_FIELDS.has(field)) {
+        return !(0, node_util_1.isDeepStrictEqual)(declared, stored ?? null);
+    }
     if (Array.isArray(declared)) {
         const a = [...declared].sort();
         const b = Array.isArray(stored) ? [...stored].sort() : [];