@hotmeshio/long-tail 0.20.0 → 0.21.1

package/README.md

@@ -234,13 +234,13 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](https
 
 | Guide | What it covers |
 |-------|---------------|
-| [The Long Tail Story](https://github.com/hotmeshio/long-tail/blob/main/docs/story.md) | Why this exists, what accumulates over time |
+| [The Long Tail Story](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/story.md) | Why this exists, what accumulates over time |
 | [Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/workflows.md) | Activities, interceptor, escalation lifecycle, composition |
 | [IAM](https://github.com/hotmeshio/long-tail/blob/main/docs/iam.md) | Identity propagation, service accounts, credential exchange |
 | [Dashboard](https://github.com/hotmeshio/long-tail/blob/main/docs/dashboard.md) | Navigation, key pages, event feed |
 | [MCP](https://github.com/hotmeshio/long-tail/blob/main/docs/mcp.md) | Server registration, tool calls, human queue |
-| [Compilation](https://github.com/hotmeshio/long-tail/blob/main/docs/compilation.md) | Dynamic to deterministic pipeline wizard |
-| [Compiler](https://github.com/hotmeshio/long-tail/blob/main/docs/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
+| [Compilation](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/compilation.md) | Dynamic to deterministic pipeline wizard |
+| [Compiler](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
 | [CLI](https://github.com/hotmeshio/long-tail/blob/main/docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
 | [Escalation Strategies](https://github.com/hotmeshio/long-tail/blob/main/docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
 | [Schema Enforcement](https://github.com/hotmeshio/long-tail/blob/main/docs/schema-enforcement.md) | form_schema as an enforced API contract on every resolve surface |
@@ -274,7 +274,7 @@ Open [http://localhost:3000](http://localhost:3000). Example workflows seed the
 | `engineer` | `l0ngt@1l` | engineer |
 | `reviewer` | `l0ngt@1l` | reviewer |
 
-See [Contributing](https://github.com/hotmeshio/long-tail/blob/main/docs/contributing.md).
+See [Contributing](https://github.com/hotmeshio/long-tail/blob/main/docs/donotpublish/contributing.md).
 
 ## License
 

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

@@ -0,0 +1,104 @@
+import type { AccumulatedItem, LTEscalationRecord } from '../../types';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/** Names the second row of a reciprocal add or removal. Exactly one selector. */
+export interface ReciprocalInput {
+    id?: string;
+    signalKey?: string;
+    key?: string;
+    value?: string;
+    payload?: Record<string, any>;
+}
+export interface AccumulateItemInput {
+    itemKey: string;
+    /** Stored on the entry and delivered inside `$accumulated`. Validates
+     * against the container's versioned role form when present. */
+    payload?: Record<string, any>;
+    metadata?: Record<string, any>;
+    assertClaim?: boolean;
+    reciprocal?: ReciprocalInput;
+}
+/**
+ * Add ONE item to an accumulator escalation (a `conditional` wait declared
+ * with `accumulate: {...}`). Interim adds are cheap atomic row appends: the
+ * row stays pending and `count`/`remaining` report progress. An add that
+ * reaches `max` completes the escalation: the row resolves and the waiting
+ * workflow wakes with the ordered collection, in the same statement.
+ *
+ * With `reciprocal`, a second accumulator row is written in that same
+ * statement or not at all: it holds this container's id as its item key and
+ * each entry points at the other row. The reciprocal is RBAC-gated here
+ * before the statement runs.
+ *
+ * Claim semantics match batch: claim-agnostic by default (a container
+ * collects contributions from many hands); `assertClaim: true` requires the
+ * caller's own live claim, asserted atomically inside the SDK statement.
+ */
+export declare function accumulateItem(input: {
+    id: string;
+} & AccumulateItemInput, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Add selecting the container by its `signal_key`, the deterministic home
+ * signal id the waiting workflow parked on. Mirrors resolve-by-signal-key:
+ * claim-agnostic, write-scope gated with 404 non-disclosure.
+ */
+export declare function accumulateItemBySignalKey(input: {
+    signalKey: string;
+} & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Add selecting the container by metadata facet, the faceted sibling of
+ * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
+ * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * roles exist and a payload is present: the row is picked first, validated
+ * against ITS schema, then written by asserted id; a row that went terminal
+ * between phases surfaces as a 409.
+ */
+export declare function accumulateItemByMetadata(input: {
+    key: string;
+    value: string;
+    restrictRoles?: string[];
+} & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
+export interface RemoveItemInput {
+    itemKey: string;
+    reciprocal?: Omit<ReciprocalInput, 'payload'>;
+}
+/**
+ * Remove ONE held item from a pending accumulator escalation, one guarded
+ * statement, no wake. With `reciprocal`, the container's id leaves that row
+ * in the same statement or neither row changes.
+ */
+export declare function removeItem(input: {
+    id: string;
+} & RemoveItemInput, auth: LTApiAuth): Promise<LTApiResult>;
+export declare function removeItemBySignalKey(input: {
+    signalKey: string;
+} & RemoveItemInput, auth: LTApiAuth): Promise<LTApiResult>;
+export declare function removeItemByMetadata(input: {
+    key: string;
+    value: string;
+    restrictRoles?: string[];
+} & RemoveItemInput, auth: LTApiAuth): Promise<LTApiResult>;
+export interface EscalationItemsView {
+    escalationId: string;
+    kind: 'accumulate' | 'batch';
+    status: LTEscalationRecord['status'];
+    count: number;
+    /** The count trigger (accumulate) or the declared size (batch); null when unbounded. */
+    max: number | null;
+    items: AccumulatedItem[];
+    /** Batch only: declared keys still awaiting submission. */
+    pending?: string[];
+}
+/** The normalized ordered item list of an accumulator or batch row. */
+export declare function itemsView(escalation: LTEscalationRecord): EscalationItemsView | null;
+/** GET the held items of an accumulator or batch row, in arrival order. Read access; 404 non-disclosure. */
+export declare function getEscalationItems(input: {
+    id: string;
+}, auth: LTApiAuth): Promise<LTApiResult<EscalationItemsView>>;
+/**
+ * GET the held items of an accumulator or batch row by its `signal_key`, the
+ * deterministic home signal id a workflow knows without a row id. Read scope
+ * gates it; anything the caller may not see answers 404.
+ */
+export declare function getEscalationItemsBySignalKey(input: {
+    signalKey: string;
+}, auth: LTApiAuth): Promise<LTApiResult<EscalationItemsView>>;

package/build/api/escalations/accumulate.js

@@ -0,0 +1,541 @@
+"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.accumulateItem = accumulateItem;
+exports.accumulateItemBySignalKey = accumulateItemBySignalKey;
+exports.accumulateItemByMetadata = accumulateItemByMetadata;
+exports.removeItem = removeItem;
+exports.removeItemBySignalKey = removeItemBySignalKey;
+exports.removeItemByMetadata = removeItemByMetadata;
+exports.itemsView = itemsView;
+exports.getEscalationItems = getEscalationItems;
+exports.getEscalationItemsBySignalKey = getEscalationItemsBySignalKey;
+const escalationService = __importStar(require("../../services/escalation"));
+const resolver_validation_1 = require("../../services/escalation/resolver-validation");
+const enforcement_cache_1 = require("../../services/role/enforcement-cache");
+const escalation_1 = require("../../types/escalation");
+const helpers_1 = require("./helpers");
+const resolve_1 = require("./resolve");
+const metadata_1 = require("./metadata");
+function parseEnvelope(escalation) {
+    try {
+        const parsed = JSON.parse(escalation.envelope || '{}');
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function isAccumulator(escalation) {
+    const items = parseEnvelope(escalation)[escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS];
+    return !!items && typeof items === 'object' && !Array.isArray(items);
+}
+function isBatch(escalation) {
+    return Array.isArray(escalation.metadata?.[escalation_1.ESCALATION_BATCH_KEYS.PENDING]);
+}
+function reciprocalSelectorCount(r) {
+    return (r.id ? 1 : 0) + (r.signalKey ? 1 : 0) + (r.key !== undefined ? 1 : 0);
+}
+/**
+ * Locates and RBAC-gates the reciprocal row before the statement. The row
+ * must be visible to the caller (404 non-disclosure otherwise) and within
+ * their write scope (403 by id; 404 for the ingress selectors). Returns the
+ * selector the service forwards, resolved to the row's id.
+ */
+async function gateReciprocal(input, auth) {
+    if (!input)
+        return {};
+    if (reciprocalSelectorCount(input) !== 1) {
+        return { error: { status: 400, error: 'reciprocal requires exactly one of id, signalKey, or key/value' } };
+    }
+    let row = null;
+    if (input.id) {
+        row = await escalationService.getEscalation(input.id);
+    }
+    else if (input.signalKey) {
+        row = await escalationService.getEscalationBySignalKey(input.signalKey);
+    }
+    else {
+        const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
+        const found = await escalationService.findByMetadata(input.key, String(input.value), 'pending', 1, 0, writeScope.global ? undefined : { allRoles: writeScope.allRoles, meUserId: auth.userId });
+        row = found.escalations[0] ?? null;
+    }
+    if (!row)
+        return { error: { status: 404, error: 'Reciprocal escalation not found' } };
+    if (input.id) {
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, row)) {
+            return { error: { status: 404, error: 'Reciprocal escalation not found' } };
+        }
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, row);
+        if (denied)
+            return { error: { ...denied, error: `Reciprocal: ${denied.error}` } };
+    }
+    else if (await (0, helpers_1.assertWriteAccess)(auth.userId, row)) {
+        return { error: { status: 404, error: 'Reciprocal escalation not found' } };
+    }
+    return { reciprocal: { id: row.id, payload: input.payload } };
+}
+/** Validates the item payload against the container's versioned role form. */
+async function gatePayload(escalation, payload, userId) {
+    if (payload === undefined)
+        return {};
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return { error: { status: 400, error: 'payload must be an object' } };
+    }
+    const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, payload, undefined, userId);
+    if (violation)
+        return { error: (0, resolve_1.validationFailure)(violation) };
+    return { payload: await (0, resolve_1.redactPasswords)(payload, escalation.metadata?.form_schema) };
+}
+/**
+ * Add ONE item to an accumulator escalation (a `conditional` wait declared
+ * with `accumulate: {...}`). Interim adds are cheap atomic row appends: the
+ * row stays pending and `count`/`remaining` report progress. An add that
+ * reaches `max` completes the escalation: the row resolves and the waiting
+ * workflow wakes with the ordered collection, in the same statement.
+ *
+ * With `reciprocal`, a second accumulator row is written in that same
+ * statement or not at all: it holds this container's id as its item key and
+ * each entry points at the other row. The reciprocal is RBAC-gated here
+ * before the statement runs.
+ *
+ * Claim semantics match batch: claim-agnostic by default (a container
+ * collects contributions from many hands); `assertClaim: true` requires the
+ * caller's own live claim, asserted atomically inside the SDK statement.
+ */
+async function accumulateItem(input, auth) {
+    try {
+        const { id, itemKey, metadata } = input;
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const escalation = await escalationService.getEscalation(id);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status === 'cancelled')
+            return { status: 409, error: 'Escalation is cancelled' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (!isAccumulator(escalation))
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return denied;
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const payload = await gatePayload(escalation, input.payload, auth.userId);
+        if ('error' in payload)
+            return payload.error;
+        const result = await escalationService.accumulateItem(escalation.id, {
+            itemKey,
+            payload: payload.payload,
+            metadata: { ...metadata, resolved_by: auth.userId },
+            actor: auth.userId,
+            assertClaim: input.assertClaim ? auth.userId : undefined,
+            resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
+            reciprocal: reciprocal.reciprocal,
+        });
+        return accumulateOutcomeResult(result, itemKey, escalation.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Add selecting the container by its `signal_key`, the deterministic home
+ * signal id the waiting workflow parked on. Mirrors resolve-by-signal-key:
+ * claim-agnostic, write-scope gated with 404 non-disclosure.
+ */
+async function accumulateItemBySignalKey(input, auth) {
+    try {
+        const { signalKey, itemKey, metadata } = input;
+        if (!signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (!isAccumulator(escalation))
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return { status: 404, error: 'Escalation not found' };
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const payload = await gatePayload(escalation, input.payload, auth.userId);
+        if ('error' in payload)
+            return payload.error;
+        const result = await escalationService.accumulateItemBySignalKey(signalKey, {
+            itemKey,
+            payload: payload.payload,
+            metadata: { ...metadata, resolved_by: auth.userId },
+            actor: auth.userId,
+            resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
+            reciprocal: reciprocal.reciprocal,
+        });
+        return accumulateOutcomeResult(result, itemKey, escalation.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Add selecting the container by metadata facet, the faceted sibling of
+ * {@link accumulateItem}. RBAC folds into the SDK's atomic facet selection
+ * as a flat role filter. Schema enforcement is two-phase when enforcing
+ * roles exist and a payload is present: the row is picked first, validated
+ * against ITS schema, then written by asserted id; a row that went terminal
+ * between phases surfaces as a 409.
+ */
+async function accumulateItemByMetadata(input, auth) {
+    try {
+        const { key, value, itemKey, metadata } = input;
+        if (!key || !value)
+            return { status: 400, error: 'key and value are required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
+        const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const resolvedBy = await (0, resolve_1.resolverIdentity)(auth);
+        const outcome = { ...metadata, resolved_by: auth.userId };
+        const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
+        if (enforcing.size === 0 || input.payload === undefined) {
+            const result = await escalationService.accumulateItemByMetadata(key, value, {
+                itemKey,
+                payload: input.payload,
+                metadata: outcome,
+                actor: auth.userId,
+                resolvedBy,
+                roles: allowedRoles ?? undefined,
+                reciprocal: reciprocal.reciprocal,
+            });
+            return accumulateOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
+        }
+        const found = await escalationService.findByMetadata(key, value, 'pending', 1, 0, allowedRoles === null ? undefined : { allRoles: allowedRoles, meUserId: auth.userId });
+        const row = found.escalations[0];
+        if (!row)
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        if (!isAccumulator(row))
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        const payload = await gatePayload(row, input.payload, auth.userId);
+        if ('error' in payload)
+            return payload.error;
+        const result = await escalationService.accumulateItem(row.id, {
+            itemKey,
+            payload: payload.payload,
+            metadata: outcome,
+            actor: auth.userId,
+            resolvedBy,
+            reciprocal: reciprocal.reciprocal,
+        });
+        if (result.outcome === 'not-found') {
+            return { status: 409, error: 'A concurrent change is already in progress for this escalation' };
+        }
+        return accumulateOutcomeResult(result, itemKey, row.workflow_id);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Remove ONE held item from a pending accumulator escalation, one guarded
+ * statement, no wake. With `reciprocal`, the container's id leaves that row
+ * in the same statement or neither row changes.
+ */
+async function removeItem(input, auth) {
+    try {
+        const { id, itemKey } = input;
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const escalation = await escalationService.getEscalation(id);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (!isAccumulator(escalation))
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
+        if (denied)
+            return denied;
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const result = await escalationService.removeAccumulatedItem(escalation.id, {
+            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+        });
+        return removeOutcomeResult(result, itemKey);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function removeItemBySignalKey(input, auth) {
+    try {
+        const { signalKey, itemKey } = input;
+        if (!signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for accumulation' };
+        if (!isAccumulator(escalation))
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        if (await (0, helpers_1.assertWriteAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const result = await escalationService.removeAccumulatedItemBySignalKey(signalKey, {
+            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+        });
+        return removeOutcomeResult(result, itemKey);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function removeItemByMetadata(input, auth) {
+    try {
+        const { key, value, itemKey } = input;
+        if (!key || !value)
+            return { status: 400, error: 'key and value are required' };
+        if (!itemKey)
+            return { status: 400, error: 'itemKey is required' };
+        const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
+        const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
+        const reciprocal = await gateReciprocal(input.reciprocal, auth);
+        if ('error' in reciprocal)
+            return reciprocal.error;
+        const result = await escalationService.removeAccumulatedItemByMetadata(key, value, {
+            itemKey, actor: auth.userId, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
+        });
+        return removeOutcomeResult(result, itemKey);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** The normalized ordered item list of an accumulator or batch row. */
+function itemsView(escalation) {
+    const envelope = parseEnvelope(escalation);
+    const metadata = (escalation.metadata ?? {});
+    if (isAccumulator(escalation)) {
+        const store = envelope[escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS];
+        const items = Object.entries(store)
+            .map(([itemKey, entry]) => ({ itemKey, ...entry }))
+            .sort((a, b) => a.at.localeCompare(b.at) || a.itemKey.localeCompare(b.itemKey));
+        const max = metadata[escalation_1.ESCALATION_ACCUMULATE_KEYS.MAX];
+        return {
+            escalationId: escalation.id,
+            kind: 'accumulate',
+            status: escalation.status,
+            count: items.length,
+            max: typeof max === 'number' ? max : null,
+            items,
+        };
+    }
+    if (isBatch(escalation)) {
+        const store = (envelope[escalation_1.ESCALATION_BATCH_KEYS.ITEMS] ?? {});
+        const filledAt = (envelope[escalation_1.ESCALATION_BATCH_KEYS.FILLED_AT] ?? {});
+        const keys = (metadata[escalation_1.ESCALATION_BATCH_KEYS.KEYS] ?? []);
+        const items = Object.entries(store)
+            .map(([itemKey, payload]) => ({ itemKey, payload: payload, at: filledAt[itemKey] ?? '' }))
+            .sort((a, b) => a.at.localeCompare(b.at) || a.itemKey.localeCompare(b.itemKey));
+        return {
+            escalationId: escalation.id,
+            kind: 'batch',
+            status: escalation.status,
+            count: items.length,
+            max: keys.length,
+            items,
+            pending: metadata[escalation_1.ESCALATION_BATCH_KEYS.PENDING] ?? [],
+        };
+    }
+    return null;
+}
+/** GET the held items of an accumulator or batch row, in arrival order. Read access; 404 non-disclosure. */
+async function getEscalationItems(input, auth) {
+    try {
+        const escalation = await escalationService.getEscalation(input.id);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const view = itemsView(escalation);
+        if (!view)
+            return { status: 400, error: 'Escalation holds no items' };
+        return { status: 200, data: view };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * GET the held items of an accumulator or batch row by its `signal_key`, the
+ * deterministic home signal id a workflow knows without a row id. Read scope
+ * gates it; anything the caller may not see answers 404.
+ */
+async function getEscalationItemsBySignalKey(input, auth) {
+    try {
+        if (!input.signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(input.signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (await (0, helpers_1.assertReadAccess)(auth.userId, escalation)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const view = itemsView(escalation);
+        if (!view)
+            return { status: 400, error: 'Escalation holds no items' };
+        return { status: 200, data: view };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+function sideData(side) {
+    return {
+        outcome: side.outcome,
+        count: side.count,
+        remaining: side.remaining,
+        escalationId: side.escalation.id,
+        signaled: side.outcome === 'completed' && !!side.escalation.signal_key,
+    };
+}
+/** Maps the SDK accumulate outcome vocabulary onto HTTP results. */
+function accumulateOutcomeResult(result, itemKey, workflowId) {
+    const reciprocal = result.reciprocal ? { reciprocal: sideData(result.reciprocal) } : {};
+    switch (result.outcome) {
+        case 'completed':
+            return {
+                status: 200,
+                data: {
+                    outcome: 'completed',
+                    count: result.count,
+                    remaining: 0,
+                    signaled: !!result.escalation?.signal_key,
+                    escalationId: result.escalation?.id,
+                    workflowId,
+                    ...reciprocal,
+                },
+            };
+        case 'accepted':
+            return {
+                status: 200,
+                data: {
+                    outcome: 'accepted',
+                    count: result.count,
+                    remaining: result.remaining,
+                    escalationId: result.escalation?.id,
+                    ...reciprocal,
+                },
+            };
+        case 'duplicate-item':
+            return { status: 409, error: 'Item already held', data: { error: 'Item already held', itemKey } };
+        case 'full':
+            return { status: 409, error: 'Accumulator is full', data: { error: 'Accumulator is full', itemKey } };
+        case 'claimed-by-other':
+            return { status: 409, error: 'Escalation is claimed by another user' };
+        case 'claim-expired':
+            return { status: 409, error: 'Your claim has expired; re-claim this escalation to add to it' };
+        case 'not-found':
+            return { status: 404, error: 'Escalation not found' };
+        case 'not-accumulator':
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        case 'reciprocal-not-found':
+            return { status: 404, error: 'Reciprocal escalation not found' };
+        case 'reciprocal-not-accumulator':
+            return { status: 400, error: 'Reciprocal escalation is not an accumulator' };
+        case 'reciprocal-duplicate':
+            return { status: 409, error: 'Reciprocal escalation already holds this container', data: { error: 'Reciprocal escalation already holds this container', outcome: result.outcome } };
+        case 'reciprocal-full':
+            return { status: 409, error: 'Reciprocal accumulator is full', data: { error: 'Reciprocal accumulator is full', outcome: result.outcome } };
+        case 'reciprocal-terminal':
+            return { status: 409, error: 'Reciprocal escalation is no longer pending', data: { error: 'Reciprocal escalation is no longer pending', outcome: result.outcome } };
+        default:
+            return { status: 409, error: 'Escalation not available for accumulation' };
+    }
+}
+function removeOutcomeResult(result, itemKey) {
+    switch (result.outcome) {
+        case 'removed':
+            return {
+                status: 200,
+                data: {
+                    outcome: 'removed',
+                    count: result.count,
+                    escalationId: result.escalation?.id,
+                    ...(result.reciprocal
+                        ? { reciprocal: { count: result.reciprocal.count, escalationId: result.reciprocal.escalation.id } }
+                        : {}),
+                },
+            };
+        case 'item-absent':
+            return { status: 404, error: 'Item not held by this escalation', data: { error: 'Item not held by this escalation', itemKey } };
+        case 'not-found':
+            return { status: 404, error: 'Escalation not found' };
+        case 'not-accumulator':
+            return { status: 400, error: 'Escalation is not an accumulator' };
+        case 'reciprocal-not-found':
+            return { status: 404, error: 'Reciprocal escalation not found' };
+        case 'reciprocal-not-accumulator':
+            return { status: 400, error: 'Reciprocal escalation is not an accumulator' };
+        case 'reciprocal-absent':
+            return { status: 404, error: 'Reciprocal escalation does not hold this container', data: { error: 'Reciprocal escalation does not hold this container', outcome: result.outcome } };
+        case 'reciprocal-terminal':
+            return { status: 409, error: 'Reciprocal escalation is no longer pending', data: { error: 'Reciprocal escalation is no longer pending', outcome: result.outcome } };
+        default:
+            return { status: 409, error: 'Escalation not available for accumulation' };
+    }
+}

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

@@ -6,6 +6,7 @@ export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
 export { resolveBatchItem, resolveBatchItemBySignalKey, resolveBatchItemByMetadata } from './resolve-batch';
+export { accumulateItem, accumulateItemBySignalKey, accumulateItemByMetadata, removeItem, removeItemBySignalKey, removeItemByMetadata, getEscalationItems, getEscalationItemsBySignalKey, itemsView, } from './accumulate';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';