@hotmeshio/long-tail 0.19.1 → 0.21.0

package/build/services/knowledge/lookup-refs.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeMissingLookupRefs = describeMissingLookupRefs;
+const db_1 = require("../../lib/db");
+const lookup_cache_1 = require("./lookup-cache");
+const sql_1 = require("./sql");
+/**
+ * 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.
+ */
+async function describeMissingLookupRefs(refs) {
+    const problems = [];
+    for (const ref of refs) {
+        const snapshot = await (0, lookup_cache_1.getKnowledgeSnapshot)(ref.domain, ref.key, ref.version);
+        if (snapshot)
+            continue;
+        const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_KNOWLEDGE_VERSIONS, [ref.domain, ref.key]);
+        const versions = rows.map((r) => Number(r.version)).sort((a, b) => a - b);
+        const where = versions.length
+            ? `editions: ${versions.map((v) => `v${v}`).join(', ')}`
+            : `no knowledge entry ${ref.domain}/${ref.key}`;
+        problems.push(`Lookup ref ${ref.domain}/${ref.key} v${ref.version} names no edition (${where})`);
+    }
+    return problems;
+}

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

@@ -7,12 +7,12 @@ export declare const findTasksSchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
-    status?: "pending" | "in_progress" | "completed" | "needs_intervention" | "failed" | undefined;
+    status?: "completed" | "pending" | "in_progress" | "needs_intervention" | "failed" | undefined;
     workflow_type?: string | undefined;
     workflow_id?: string | undefined;
     origin_id?: string | undefined;
 }, {
-    status?: "pending" | "in_progress" | "completed" | "needs_intervention" | "failed" | undefined;
+    status?: "completed" | "pending" | "in_progress" | "needs_intervention" | "failed" | undefined;
     workflow_type?: string | undefined;
     workflow_id?: string | undefined;
     origin_id?: string | undefined;

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/field-validator.d.ts

@@ -38,6 +38,7 @@ export declare function resolveChecklistDefault(fieldSchema: Record<string, unkn
  * which remains the at-least-one check.
  */
 export declare function validateRequireAll(value: unknown, fieldSchema: Record<string, unknown> | undefined, ctx?: Record<string, unknown>): string | undefined;
+export declare const INVALID_JSON = "Invalid JSON";
 /**
  * Runtime type check against the field's declared JSON Schema `type`. Guards
  * the payload contract for API-first callers (a form widget already produces

package/build/shared/form-validation/field-validator.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.X_LT_DEFAULT_CHECKED = void 0;
+exports.INVALID_JSON = exports.X_LT_DEFAULT_CHECKED = void 0;
 exports.resolveChecklistItems = resolveChecklistItems;
 exports.resolveChecklistDefault = resolveChecklistDefault;
 exports.validateRequireAll = validateRequireAll;
@@ -87,6 +87,18 @@ function validateRequireAll(value, fieldSchema, ctx) {
         return undefined;
     return `${incomplete} of ${mandatory.length} checks incomplete`;
 }
+exports.INVALID_JSON = 'Invalid JSON';
+/** The json editor holds unparseable text as a string at the field's key. */
+function isJsonWidget(fieldSchema) {
+    return fieldSchema?.['x-lt-widget'] === 'json';
+}
+/** A list is edited through the json editor or a multi-select; any other list value is display only. */
+function isEditableList(fieldSchema) {
+    return isJsonWidget(fieldSchema) || fieldSchema?.[x_lt_options_1.X_LT_OPTIONS] !== undefined;
+}
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
 /**
  * Runtime type check against the field's declared JSON Schema `type`. Guards
  * the payload contract for API-first callers (a form widget already produces
@@ -109,9 +121,13 @@ function validateFieldType(value, fieldSchema) {
         case 'boolean':
             return typeof value === 'boolean' ? undefined : 'Expected true or false';
         case 'array':
-            return Array.isArray(value) ? undefined : 'Expected a list';
+            if (Array.isArray(value))
+                return undefined;
+            return isJsonWidget(fieldSchema) && typeof value === 'string' ? exports.INVALID_JSON : 'Expected a list';
         case 'object':
-            return typeof value === 'object' && !Array.isArray(value) ? undefined : 'Expected an object';
+            if (typeof value === 'object' && !Array.isArray(value))
+                return undefined;
+            return isJsonWidget(fieldSchema) && typeof value === 'string' ? exports.INVALID_JSON : 'Expected an object';
         default:
             return undefined;
     }
@@ -136,7 +152,7 @@ function validateFieldConstraints(value, fieldSchema, ctx) {
     // interpolated list that currently offers nothing fails closed — a stale
     // cascade child value never submits.
     const allowed = (0, x_lt_options_1.resolveFieldOptions)(fieldSchema, ctx);
-    if (allowed !== undefined && value !== undefined && value !== null && value !== '') {
+    if (allowed !== undefined && value !== undefined && value !== null && value !== '' && !Array.isArray(value)) {
         if (allowed.length === 0) {
             return 'No valid options for this selection';
         }
@@ -144,6 +160,12 @@ function validateFieldConstraints(value, fieldSchema, ctx) {
             return `Must be one of: ${allowed.map((o) => String(o.value)).join(', ')}`;
         }
     }
+    if (Array.isArray(value)) {
+        return isEditableList(fieldSchema) ? validateListConstraints(value, fieldSchema, allowed, ctx) : undefined;
+    }
+    if (value !== null && typeof value === 'object') {
+        return validateMapConstraints(value, fieldSchema, ctx);
+    }
     if (typeof value === 'string') {
         const s = value.trim();
         if (s === '')
@@ -196,6 +218,65 @@ function validateFieldConstraints(value, fieldSchema, ctx) {
     }
     return undefined;
 }
+/**
+ * An edited list: every item must belong to the field's `x-lt-options` when
+ * declared, the length must sit within `minItems`/`maxItems`, and each item
+ * must satisfy `items`. An empty list passes; presence is the required
+ * check's job.
+ */
+function validateListConstraints(value, fieldSchema, allowed, ctx) {
+    if (value.length === 0)
+        return undefined;
+    if (allowed !== undefined) {
+        if (allowed.length === 0)
+            return 'No valid options for this selection';
+        if (value.some((v) => !allowed.some((o) => o.value === v))) {
+            return `Must be one of: ${allowed.map((o) => String(o.value)).join(', ')}`;
+        }
+    }
+    const minItems = resolveNumericConstraint(fieldSchema.minItems, undefined, ctx);
+    if (minItems !== undefined && value.length < minItems)
+        return `At least ${plural(minItems, 'item')}`;
+    const maxItems = resolveNumericConstraint(fieldSchema.maxItems, undefined, ctx);
+    if (maxItems !== undefined && value.length > maxItems)
+        return `At most ${plural(maxItems, 'item')}`;
+    const items = fieldSchema.items;
+    if (items && typeof items === 'object' && !Array.isArray(items)) {
+        const itemSchema = items;
+        for (let i = 0; i < value.length; i++) {
+            const err = validateFieldType(value[i], itemSchema) ?? validateFieldConstraints(value[i], itemSchema, ctx);
+            if (err)
+                return `Item ${i + 1}: ${err}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * A map value: keys must belong to `propertyNames.enum` when declared, and
+ * every value must satisfy an object-shaped `additionalProperties`.
+ */
+function validateMapConstraints(value, fieldSchema, ctx) {
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return undefined;
+    const propertyNames = fieldSchema.propertyNames;
+    const allowedKeys = Array.isArray(propertyNames?.enum) ? propertyNames.enum.map(String) : undefined;
+    if (allowedKeys) {
+        const unknown = entries.find(([k]) => !allowedKeys.includes(k));
+        if (unknown)
+            return `Unknown key "${unknown[0]}". Allowed: ${allowedKeys.join(', ')}`;
+    }
+    const ap = fieldSchema.additionalProperties;
+    if (ap && typeof ap === 'object' && !Array.isArray(ap)) {
+        const valueSchema = ap;
+        for (const [k, v] of entries) {
+            const err = validateFieldType(v, valueSchema) ?? validateFieldConstraints(v, valueSchema, ctx);
+            if (err)
+                return `"${k}": ${err}`;
+        }
+    }
+    return undefined;
+}
 function resolveNumericConstraint(staticVal, dynamicPath, ctx) {
     if (typeof staticVal === 'number')
         return staticVal;
@@ -232,13 +313,20 @@ function validateField(value, fieldSchema, isRequired, isTouched, ctx) {
     if (isRequired) {
         if (value === undefined || value === null)
             return 'Required';
-        if (typeof value === 'boolean' && !value)
+        // A checkbox must be checked; a boolean with an option list is answered by either value.
+        if (typeof value === 'boolean' && !value && (0, x_lt_options_1.resolveFieldOptions)(fieldSchema, ctx) === undefined)
             return 'Required';
         if (typeof value === 'string' && value.trim() === '')
             return 'Required';
+        // A picked or edited list needs one item; a plain list value is not checked.
+        if (Array.isArray(value) && value.length === 0 && isEditableList(fieldSchema))
+            return 'Required';
         if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
             const vals = Object.values(value);
-            if (vals.length === 0 || vals.every((v) => !v))
+            if (vals.length === 0)
+                return 'Required';
+            // A json map is answered by any key; every other object needs one truthy value.
+            if (!isJsonWidget(fieldSchema) && vals.every((v) => !v))
                 return 'Required';
         }
     }