@hotmeshio/long-tail 0.19.1 → 0.21.0

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/routes/workflows/config.js

@@ -54,6 +54,15 @@ router.get('/:type/config', async (req, res) => {
     const result = await api.getWorkflowConfig({ type: req.params.type });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/workflows/:type/input-lookups
+ * Resolve the versioned knowledge lookups pinned on a workflow config.
+ * Open to any caller the invoke gate admits for that workflow.
+ */
+router.get('/:type/input-lookups', async (req, res) => {
+    const result = await api.getWorkflowInputLookups({ type: req.params.type }, { userId: req.auth?.userId ?? '', role: req.auth?.role, scopes: req.auth?.scopes });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * PUT /api/workflows/:type/config
  * Create or replace a workflow configuration.
@@ -75,6 +84,7 @@ router.put('/:type/config', auth_1.requireAdmin, async (req, res) => {
         envelope_schema: req.body.envelope_schema,
         input_schema: req.body.input_schema,
         icon: req.body.icon,
+        input_lookups: req.body.input_lookups,
         resolver_schema: req.body.resolver_schema,
         cron_schedule: req.body.cron_schedule,
     });

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/config/cache.js

@@ -18,6 +18,7 @@ async function loadAllConfigs() {
             envelopeSchema: c.envelope_schema ?? null,
             inputSchema: c.input_schema ?? null,
             icon: c.icon ?? null,
+            inputLookups: c.input_lookups ?? null,
             resolverSchema: c.resolver_schema ?? null,
             cronSchedule: c.cron_schedule ?? null,
             executeAs: c.execute_as ?? null,

package/build/services/config/read.js

@@ -28,6 +28,7 @@ async function getWorkflowConfig(workflowType) {
         envelope_schema: wf.envelope_schema ?? null,
         input_schema: wf.input_schema ?? null,
         icon: wf.icon ?? null,
+        input_lookups: wf.input_lookups ?? null,
         resolver_schema: wf.resolver_schema ?? null,
         cron_schedule: wf.cron_schedule ?? null,
         execute_as: wf.execute_as ?? null,
@@ -68,6 +69,7 @@ async function listWorkflowConfigs() {
         envelope_schema: wf.envelope_schema ?? null,
         input_schema: wf.input_schema ?? null,
         icon: wf.icon ?? null,
+        input_lookups: wf.input_lookups ?? null,
         resolver_schema: wf.resolver_schema ?? null,
         cron_schedule: wf.cron_schedule ?? null,
         execute_as: wf.execute_as ?? null,

package/build/services/config/sql.d.ts

@@ -5,13 +5,13 @@ export declare const LIST_ALL_WORKFLOWS = "SELECT * FROM lt_config_workflows ORD
 export declare const LIST_ALL_ROLES = "SELECT * FROM lt_config_roles ORDER BY workflow_type, role";
 export declare const LIST_ALL_INVOCATION_ROLES = "SELECT * FROM lt_config_invocation_roles ORDER BY workflow_type, role";
 export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
-export declare const UPSERT_WORKFLOW = "INSERT INTO lt_config_workflows\n  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)\nON CONFLICT (workflow_type) DO UPDATE SET\n  invocable = EXCLUDED.invocable,\n  task_queue = EXCLUDED.task_queue,\n  default_role = EXCLUDED.default_role,\n  description = EXCLUDED.description,\n  consumes = EXCLUDED.consumes,\n  envelope_schema = EXCLUDED.envelope_schema,\n  resolver_schema = EXCLUDED.resolver_schema,\n  cron_schedule = EXCLUDED.cron_schedule,\n  tool_tags = EXCLUDED.tool_tags,\n  execute_as = EXCLUDED.execute_as,\n  certified = EXCLUDED.certified,\n  read_safe = EXCLUDED.read_safe,\n  input_schema = EXCLUDED.input_schema,\n  icon = EXCLUDED.icon";
+export declare const UPSERT_WORKFLOW = "INSERT INTO lt_config_workflows\n  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon, input_lookups)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)\nON CONFLICT (workflow_type) DO UPDATE SET\n  invocable = EXCLUDED.invocable,\n  task_queue = EXCLUDED.task_queue,\n  default_role = EXCLUDED.default_role,\n  description = EXCLUDED.description,\n  consumes = EXCLUDED.consumes,\n  envelope_schema = EXCLUDED.envelope_schema,\n  resolver_schema = EXCLUDED.resolver_schema,\n  cron_schedule = EXCLUDED.cron_schedule,\n  tool_tags = EXCLUDED.tool_tags,\n  execute_as = EXCLUDED.execute_as,\n  certified = EXCLUDED.certified,\n  read_safe = EXCLUDED.read_safe,\n  input_schema = EXCLUDED.input_schema,\n  icon = EXCLUDED.icon,\n  input_lookups = EXCLUDED.input_lookups";
 export declare const DELETE_CONFIG_ROLES = "DELETE FROM lt_config_roles WHERE workflow_type = $1";
 export declare const INSERT_CONFIG_ROLE = "INSERT INTO lt_config_roles (workflow_type, role) VALUES ($1, $2)";
 export declare const DELETE_INVOCATION_ROLES = "DELETE FROM lt_config_invocation_roles WHERE workflow_type = $1";
 export declare const INSERT_INVOCATION_ROLE = "INSERT INTO lt_config_invocation_roles (workflow_type, role) VALUES ($1, $2)";
 export declare const DELETE_WORKFLOW = "DELETE FROM lt_config_workflows WHERE workflow_type = $1";
-export declare const SEED_WORKFLOW_CONFIG = "INSERT INTO lt_config_workflows\n  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)\nON CONFLICT (workflow_type) DO NOTHING";
+export declare const SEED_WORKFLOW_CONFIG = "INSERT INTO lt_config_workflows\n  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon, input_lookups)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)\nON CONFLICT (workflow_type) DO NOTHING";
 export declare const SEED_CONFIG_ROLE = "INSERT INTO lt_config_roles (workflow_type, role) VALUES ($1, $2)\nON CONFLICT (workflow_type, role) DO NOTHING";
 export declare const SEED_INVOCATION_ROLE = "INSERT INTO lt_config_invocation_roles (workflow_type, role) VALUES ($1, $2)\nON CONFLICT (workflow_type, role) DO NOTHING";
 export declare const GET_PROVIDER_DATA = "SELECT workflow_type, data, completed_at\n  FROM lt_tasks\n WHERE origin_id = $1\n   AND workflow_type = ANY($2)\n   AND status = 'completed'\n ORDER BY completed_at DESC";

package/build/services/config/sql.js

@@ -23,8 +23,8 @@ exports.ENSURE_ROLE_EXISTS = `\
 INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING`;
 exports.UPSERT_WORKFLOW = `\
 INSERT INTO lt_config_workflows
-  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
+  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon, input_lookups)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
 ON CONFLICT (workflow_type) DO UPDATE SET
   invocable = EXCLUDED.invocable,
   task_queue = EXCLUDED.task_queue,
@@ -39,7 +39,8 @@ ON CONFLICT (workflow_type) DO UPDATE SET
   certified = EXCLUDED.certified,
   read_safe = EXCLUDED.read_safe,
   input_schema = EXCLUDED.input_schema,
-  icon = EXCLUDED.icon`;
+  icon = EXCLUDED.icon,
+  input_lookups = EXCLUDED.input_lookups`;
 exports.DELETE_CONFIG_ROLES = `\
 DELETE FROM lt_config_roles WHERE workflow_type = $1`;
 exports.INSERT_CONFIG_ROLE = `\
@@ -55,8 +56,8 @@ DELETE FROM lt_config_workflows WHERE workflow_type = $1`;
 // ------------------------------------------------------------------ //
 exports.SEED_WORKFLOW_CONFIG = `\
 INSERT INTO lt_config_workflows
-  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
+  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as, certified, read_safe, input_schema, icon, input_lookups)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
 ON CONFLICT (workflow_type) DO NOTHING`;
 exports.SEED_CONFIG_ROLE = `\
 INSERT INTO lt_config_roles (workflow_type, role) VALUES ($1, $2)

package/build/services/config/write.js

@@ -14,6 +14,10 @@ const sql_1 = require("./sql");
  * seed blocks without `certified`): derived from roles/consumes presence —
  * the rule that governed the tier before the flag existed.
  */
+/** pg binds JS arrays as Postgres arrays; jsonb columns take the JSON text. */
+function toJsonb(value) {
+    return value == null ? null : JSON.stringify(value);
+}
 function resolveCertified(config) {
     return (config.certified ??
         ((config.roles?.length ?? 0) > 0 || (config.consumes?.length ?? 0) > 0));
@@ -55,6 +59,7 @@ async function replaceWorkflowConfig(config, certified) {
             config.read_safe ?? false,
             config.input_schema ?? null,
             config.icon ?? null,
+            toJsonb(config.input_lookups),
         ]);
         // Replace roles
         await client.query(sql_1.DELETE_CONFIG_ROLES, [config.workflow_type]);
@@ -118,6 +123,7 @@ async function seedWorkflowConfig(config) {
         config.read_safe ?? false,
         config.input_schema ?? null,
         config.icon ?? null,
+        toJsonb(config.input_lookups),
     ]);
     const inserted = (rowCount ?? 0) > 0;
     if (inserted) {
@@ -152,6 +158,8 @@ async function seedWorkflowConfig(config) {
                 drifts.push('input_schema');
             if ((config.icon ?? null) !== (existing.icon ?? null))
                 drifts.push('icon');
+            if (JSON.stringify(config.input_lookups ?? null) !== JSON.stringify(existing.input_lookups ?? null))
+                drifts.push('input_lookups');
             if (drifts.length) {
                 logger_1.loggerRegistry.warn(`[long-tail] config drift: ${config.workflow_type} — ${drifts.join(', ')} differ between code and DB`);
             }
@@ -191,7 +199,8 @@ async function applyWorkflowConfig(config) {
             (0, node_util_1.isDeepStrictEqual)(existing.envelope_schema ?? null, config.envelope_schema ?? null) &&
             (0, node_util_1.isDeepStrictEqual)(existing.resolver_schema ?? null, config.resolver_schema ?? null) &&
             (0, node_util_1.isDeepStrictEqual)(existing.input_schema ?? null, config.input_schema ?? null) &&
-            (existing.icon ?? null) === (config.icon ?? null);
+            (existing.icon ?? null) === (config.icon ?? null) &&
+            (0, node_util_1.isDeepStrictEqual)(existing.input_lookups ?? null, config.input_lookups ?? null);
         if (unchanged)
             return 'unchanged';
     }

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/knowledge/index.d.ts

@@ -1,4 +1,5 @@
 export * from './lookup-cache';
+export * from './lookup-refs';
 export interface KnowledgeVersionMeta {
     version: number;
     change_summary: string | null;

package/build/services/knowledge/index.js

@@ -24,6 +24,7 @@ exports.listKnowledgeVersions = listKnowledgeVersions;
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
 __exportStar(require("./lookup-cache"), exports);
+__exportStar(require("./lookup-refs"), exports);
 /** The immutable snapshot at (domain, key, version), uncached full shape. */
 async function getKnowledgeVersion(domain, key, version) {
     const pool = (0, db_1.getPool)();

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

@@ -0,0 +1,7 @@
+import type { EscalationLookupRef } from '../../types/escalation';
+/**
+ * One message per ref whose pinned edition does not exist, naming what does.
+ * Shape is the caller's job (assertLookupRefs); this answers the second
+ * question a saver has: is there an edition behind the pin.
+ */
+export declare function describeMissingLookupRefs(refs: EscalationLookupRef[]): Promise<string[]>;