@hotmeshio/long-tail 0.20.0 → 0.21.0

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() : [];

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

@@ -21,7 +21,7 @@ export declare const LIST_ROLES = "\n  SELECT role FROM lt_roles ORDER BY role";
  */
 export declare const LIST_CONFIGURED_ROLES = "\n  SELECT role FROM lt_roles\n  WHERE title IS NOT NULL OR form_schema IS NOT NULL\n  ORDER BY role";
 /** One role's full metadata row (plus upstream inputs) for startup diffing. */
-export declare const GET_ROLE_ROW = "\n  SELECT\n    r.role, r.title, r.description, r.form_schema, r.metadata_schema,\n    r.properties, r.ops_visible, r.ops_home_default, r.parent_role,\n    r.sla_minutes, r.target_per_hour, r.worker_count,\n    r.priority_threshold_minutes, r.priority_facet,\n    r.entity_facet, r.entity_state_source,\n    r.list_schema, r.default_pins, r.enforce_schema,\n    r.current_schema_version, r.current_list_schema_version,\n    COALESCE((SELECT array_agg(u.upstream_role ORDER BY u.upstream_role)\n              FROM lt_role_upstreams u WHERE u.role = r.role), '{}') AS upstream_roles\n  FROM lt_roles r\n  WHERE r.role = $1";
+export declare const GET_ROLE_ROW = "\n  SELECT\n    r.role, r.title, r.description, r.form_schema, r.metadata_schema,\n    r.properties, r.ops_visible, r.ops_home_default, r.parent_role,\n    r.sla_minutes, r.target_per_hour, r.worker_count,\n    r.priority_threshold_minutes, r.priority_facet,\n    r.entity_facet, r.entity_state_source,\n    r.list_schema, r.default_pins, r.portals, r.enforce_schema,\n    r.current_schema_version, r.current_list_schema_version,\n    COALESCE((SELECT array_agg(u.upstream_role ORDER BY u.upstream_role)\n              FROM lt_role_upstreams u WHERE u.role = r.role), '{}') AS upstream_roles\n  FROM lt_roles r\n  WHERE r.role = $1";
 export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
 /**
  * PATCH semantics in ONE atomic statement: each column has a boolean
@@ -66,8 +66,11 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * entity_state_source ($39 = provided sentinel, $40 = value) is unversioned
  * config: 'role' | 'subtype' — how this role names its contribution to the
  * entity's state space (the station itself, or its subtypes).
+ *
+ * portals ($41 = provided sentinel, $42 = value) is unversioned config: the
+ * role's named portal views, each a matrix of pin cells rendered as one page.
  */
-export declare const UPDATE_ROLE_METADATA = "\n  WITH home_clear AS (\n    UPDATE lt_roles SET ops_home_default = false\n    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default\n  ), updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      entity_facet    = CASE WHEN $37::boolean THEN $38                               ELSE entity_facet    END,\n      entity_state_source\n                      = CASE WHEN $39::boolean THEN COALESCE($40, 'role')             ELSE entity_state_source END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet, entity_facet, entity_state_source,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, enforce_schema\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
+export declare const UPDATE_ROLE_METADATA = "\n  WITH home_clear AS (\n    UPDATE lt_roles SET ops_home_default = false\n    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default\n  ), updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      entity_facet    = CASE WHEN $37::boolean THEN $38                               ELSE entity_facet    END,\n      entity_state_source\n                      = CASE WHEN $39::boolean THEN COALESCE($40, 'role')             ELSE entity_state_source END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      portals         = CASE WHEN $41::boolean THEN $42::jsonb                        ELSE portals         END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END,\n      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet, entity_facet, entity_state_source,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, portals, enforce_schema\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
 export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
 /**
  * The set of roles with server-side resolver validation turned on. Small and
@@ -92,7 +95,7 @@ export declare const GET_ROLE_LIST_SCHEMA_VERSION = "\n  SELECT s.role, s.versio
  * never versioned its list schema still answers, with version NULL).
  */
 export declare const GET_ROLE_LIST_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_list_schema_version AS version, r.list_schema,\n         s.change_summary, s.created_at,\n         r.current_list_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_list_schemas s\n    ON s.role = r.role AND s.version = r.current_list_schema_version\n  WHERE r.role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.ops_home_default,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.entity_facet,\n    r.entity_state_source,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.enforce_schema,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.ops_home_default,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.entity_facet,\n    r.entity_state_source,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.portals,\n    r.enforce_schema,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";

package/build/services/role/sql.js

@@ -64,7 +64,7 @@ exports.GET_ROLE_ROW = `
     r.sla_minutes, r.target_per_hour, r.worker_count,
     r.priority_threshold_minutes, r.priority_facet,
     r.entity_facet, r.entity_state_source,
-    r.list_schema, r.default_pins, r.enforce_schema,
+    r.list_schema, r.default_pins, r.portals, r.enforce_schema,
     r.current_schema_version, r.current_list_schema_version,
     COALESCE((SELECT array_agg(u.upstream_role ORDER BY u.upstream_role)
               FROM lt_role_upstreams u WHERE u.role = r.role), '{}') AS upstream_roles
@@ -115,6 +115,9 @@ exports.DELETE_ROLE = `
  * entity_state_source ($39 = provided sentinel, $40 = value) is unversioned
  * config: 'role' | 'subtype' — how this role names its contribution to the
  * entity's state space (the station itself, or its subtypes).
+ *
+ * portals ($41 = provided sentinel, $42 = value) is unversioned config: the
+ * role's named portal views, each a matrix of pin cells rendered as one page.
  */
 exports.UPDATE_ROLE_METADATA = `
   WITH home_clear AS (
@@ -140,6 +143,7 @@ exports.UPDATE_ROLE_METADATA = `
                       = CASE WHEN $39::boolean THEN COALESCE($40, 'role')             ELSE entity_state_source END,
       list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,
       default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,
+      portals         = CASE WHEN $41::boolean THEN $42::jsonb                        ELSE portals         END,
       enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,
       ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default END,
       current_schema_version = CASE
@@ -157,7 +161,7 @@ exports.UPDATE_ROLE_METADATA = `
       ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,
       priority_threshold_minutes, priority_facet, entity_facet, entity_state_source,
       current_schema_version, list_schema, current_list_schema_version,
-      default_pins, enforce_schema
+      default_pins, portals, enforce_schema
   ), snapshot AS (
     INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
     SELECT role, current_schema_version, form_schema, metadata_schema, $26
@@ -304,6 +308,7 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.list_schema,
     r.current_list_schema_version,
     r.default_pins,
+    r.portals,
     r.enforce_schema,
     COALESCE(up.ups, '{}') AS upstream_roles,
     COALESCE(uc.cnt, 0) AS user_count,

package/build/services/role/types.d.ts

@@ -35,6 +35,35 @@ export declare const ROLE_PROPERTY_KEYS: {
  * binding. Values are strings — jsonb containment is type-sensitive, so
  * numeric facets are not templatable.
  */
+/** One pinned view: a label over a dashboard-relative URL, optionally badged with its live count. */
+export interface RolePin {
+    label: string;
+    url: string;
+    badge?: boolean;
+}
+/** Bounds for a role's portals: how many, and the matrix of each (rows of cells, each cell a pin). */
+export declare const PORTAL_LIMITS: {
+    readonly MAX_PORTALS: 12;
+    readonly MAX_ROWS: 4;
+    readonly MAX_COLS: 6;
+    readonly MAX_COUNTS: 8;
+};
+/** One count tile above a portal: a label, a blurb, and the live total of an escalations-list URL. */
+export interface PortalCount {
+    label: string;
+    url: string;
+    blurb?: string;
+}
+/** A portal key: a short url-safe slug, unique within the role. */
+export declare const PORTAL_KEY: RegExp;
+/** One named portal view: a matrix of pins rendered as one page. */
+export interface RolePortal {
+    key: string;
+    label: string;
+    rows: RolePin[][];
+    /** Count tiles shown above the panels, each the live total of a list URL. */
+    counts?: PortalCount[];
+}
 export interface RoleLinkVariable {
     name: string;
     label?: string;
@@ -125,11 +154,12 @@ export interface RoleDetail {
      * in their Pinned nav section (marked role-provided); users promote, hide,
      * or reorder them through their own preferences. URLs only — never data.
      */
-    default_pins: {
-        label: string;
-        url: string;
-        badge?: boolean;
-    }[] | null;
+    default_pins: RolePin[] | null;
+    /**
+     * The role's portals: named matrices of pins, each rendered as one page of
+     * live list panels at /portal/:role/:portal. Null when the role declares none.
+     */
+    portals: RolePortal[] | null;
     /**
      * Roles this station draws input from that live in OTHER sequences.
      * parent_role is the single "prior step" placing the role in one sequence;
@@ -185,11 +215,9 @@ export interface UpdateRoleInput {
     metadata_schema?: Record<string, any> | null;
     /** JSON contract that richly formats this role's escalation list page. */
     list_schema?: Record<string, any> | null;
-    default_pins?: {
-        label: string;
-        url: string;
-        badge?: boolean;
-    }[] | null;
+    default_pins?: RolePin[] | null;
+    /** The role's named portals; null clears. */
+    portals?: RolePortal[] | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     /** Make this role's sequence the home Pace Board's default segment (single-holder). */

package/build/services/role/types.js

@@ -1,7 +1,7 @@
 "use strict";
 /** Type definitions for the role and escalation chain service. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ROLE_PROPERTY_KEYS = void 0;
+exports.PORTAL_KEY = exports.PORTAL_LIMITS = exports.ROLE_PROPERTY_KEYS = void 0;
 /**
  * Reserved keys inside `lt_roles.properties`. Everything else in the bag is
  * user-owned. Readers type-guard (the bag is open, PATCH can write anything).
@@ -27,3 +27,12 @@ exports.ROLE_PROPERTY_KEYS = {
     KIOSK: 'kiosk',
     LINK_VARIABLES: 'link_variables',
 };
+/** Bounds for a role's portals: how many, and the matrix of each (rows of cells, each cell a pin). */
+exports.PORTAL_LIMITS = {
+    MAX_PORTALS: 12,
+    MAX_ROWS: 4,
+    MAX_COLS: 6,
+    MAX_COUNTS: 8,
+};
+/** A portal key: a short url-safe slug, unique within the role. */
+exports.PORTAL_KEY = /^[a-z0-9][a-z0-9-]{0,63}$/;

package/build/services/scan-code/validate.js

@@ -4,6 +4,7 @@ exports.assertValidScheme = assertValidScheme;
 exports.assertValidIdentityRule = assertValidIdentityRule;
 exports.assertValidSteps = assertValidSteps;
 const types_1 = require("../../types");
+const facet_sql_1 = require("../escalation/facet-sql");
 const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
 /** Double-scan selection tokens — short, label-printable, never scheme-shaped. */
 const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
@@ -145,6 +146,21 @@ function assertValidSteps(steps) {
         if (step.verb === types_1.SCAN_VERBS.RESOLVE && !step.params?.resolverPayload) {
             throw new Error(`${at}: resolve requires params.resolverPayload`);
         }
+        if (step.verb === types_1.SCAN_VERBS.ACCUMULATE) {
+            const options = step.params?.accumulate;
+            if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+                throw new Error(`${at}: params.accumulate must be an object`);
+            }
+            if (options?.containerFacet !== undefined && !facet_sql_1.FACET_KEY.test(String(options.containerFacet))) {
+                throw new Error(`${at}: params.accumulate.containerFacet must be a facet key`);
+            }
+            if (options?.containerRoles !== undefined && !Array.isArray(options.containerRoles)) {
+                throw new Error(`${at}: params.accumulate.containerRoles must be an array`);
+            }
+            if (!options?.containerFacet && !step.params?.itemKey) {
+                throw new Error(`${at}: accumulate requires params.itemKey or params.accumulate.containerFacet`);
+            }
+        }
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);
         }

package/build/shared/form-validation/display-only-widgets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Widgets that render from the escalation context and produce no answer of
+ * their own: navigation links, embedded records and lists, and invoke
+ * controls. Their form slot exists only to place them in the layout, so
+ * the payload mapper drops them and the server never sees a value.
+ */
+export declare const DISPLAY_ONLY_WIDGET_NAMES: {
+    readonly LINK: "link";
+    readonly ESCALATION: "escalation";
+    readonly ESCALATION_LIST: "escalation-list";
+    readonly INVOKE: "invoke";
+};
+export declare const DISPLAY_ONLY_WIDGETS: ReadonlySet<string>;
+export declare function isDisplayOnlyWidget(name: unknown): boolean;
+/** Whether a property definition renders a display-only widget. */
+export declare function isDisplayOnlyField(def: Record<string, unknown> | null | undefined): boolean;

package/build/shared/form-validation/display-only-widgets.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPLAY_ONLY_WIDGETS = exports.DISPLAY_ONLY_WIDGET_NAMES = void 0;
+exports.isDisplayOnlyWidget = isDisplayOnlyWidget;
+exports.isDisplayOnlyField = isDisplayOnlyField;
+/**
+ * Widgets that render from the escalation context and produce no answer of
+ * their own: navigation links, embedded records and lists, and invoke
+ * controls. Their form slot exists only to place them in the layout, so
+ * the payload mapper drops them and the server never sees a value.
+ */
+exports.DISPLAY_ONLY_WIDGET_NAMES = {
+    LINK: 'link',
+    ESCALATION: 'escalation',
+    ESCALATION_LIST: 'escalation-list',
+    INVOKE: 'invoke',
+};
+exports.DISPLAY_ONLY_WIDGETS = new Set(Object.values(exports.DISPLAY_ONLY_WIDGET_NAMES));
+function isDisplayOnlyWidget(name) {
+    return typeof name === 'string' && exports.DISPLAY_ONLY_WIDGETS.has(name);
+}
+/** Whether a property definition renders a display-only widget. */
+function isDisplayOnlyField(def) {
+    return isDisplayOnlyWidget(def?.['x-lt-widget']);
+}

package/build/shared/form-validation/index.d.ts

@@ -20,3 +20,5 @@ export * from './ctx-path';
 export * from './field-validator';
 export * from './validate-resolver-payload';
 export * from './invoke-context';
+export * from './display-only-widgets';
+export * from './x-lt-invoke';

package/build/shared/form-validation/index.js

@@ -36,3 +36,5 @@ __exportStar(require("./ctx-path"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);
 __exportStar(require("./invoke-context"), exports);
+__exportStar(require("./display-only-widgets"), exports);
+__exportStar(require("./x-lt-invoke"), exports);