@hotmeshio/long-tail 0.20.0 → 0.21.1

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

@@ -1,4 +1,4 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
 export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
-export { parseScanCode, interpolateScanTemplate, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
 export { assertValidScheme, assertValidSteps } from './validate';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
+exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
 var read_1 = require("./read");
 Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return read_1.listScanSchemes; } });
 Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return read_1.getScanScheme; } });
@@ -18,6 +18,8 @@ Object.defineProperty(exports, "applyScanRule", { enumerable: true, get: functio
 var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "interpolateScanTemplate", { enumerable: true, get: function () { return parse_1.interpolateScanTemplate; } });
+Object.defineProperty(exports, "mentionsClaimToken", { enumerable: true, get: function () { return parse_1.mentionsClaimToken; } });
+Object.defineProperty(exports, "ScanTemplateError", { enumerable: true, get: function () { return parse_1.ScanTemplateError; } });
 var validate_1 = require("./validate");
 Object.defineProperty(exports, "assertValidScheme", { enumerable: true, get: function () { return validate_1.assertValidScheme; } });
 Object.defineProperty(exports, "assertValidSteps", { enumerable: true, get: function () { return validate_1.assertValidSteps; } });

package/build/services/scan-code/parse.d.ts

@@ -26,10 +26,24 @@ export interface ScanTemplateContext {
     target: string;
     category: string;
     scannedAt: string;
+    /** The acting user's single live claim, its metadata; absent when none or ambiguous. */
+    claim?: Record<string, unknown>;
+    /** The row an item-mode accumulate step located, its metadata. */
+    item?: Record<string, unknown>;
 }
+/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+export declare class ScanTemplateError extends Error {
+    readonly token: string;
+    readonly reason: string;
+    constructor(token: string, reason: string);
+}
+/** True when any string in the params mentions a `{claim.…}` token. */
+export declare function mentionsClaimToken(value: unknown): boolean;
 /**
- * Replace SCAN_TEMPLATE_TOKENS inside string values of a params object.
- * Deep, pure, non-mutating. Only exact-token and in-string replacement of
- * the three known tokens — no expression language.
+ * Replace the template tokens inside string values of a params object.
+ * Deep, pure, non-mutating. The three scan tokens are plain text
+ * replacement; `{claim.<facet>}` and `{item.<facet>}` read the context's
+ * facet bags and throw {@link ScanTemplateError} when they cannot resolve,
+ * so a literal token never reaches a row. No expression language.
  */
 export declare function interpolateScanTemplate<T>(value: T, ctx: ScanTemplateContext): T;

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanTemplateError = void 0;
 exports.parseScanCode = parseScanCode;
+exports.mentionsClaimToken = mentionsClaimToken;
 exports.interpolateScanTemplate = interpolateScanTemplate;
 const types_1 = require("../../types");
 /**
@@ -82,17 +84,48 @@ function malformed(scheme, detail) {
         failure: { reason: 'malformed', detail: `scheme ${scheme.version} ("${scheme.name}"): ${detail}` },
     };
 }
+/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+class ScanTemplateError extends Error {
+    constructor(token, reason) {
+        super(`scan template ${token}: ${reason}`);
+        this.token = token;
+        this.reason = reason;
+        this.name = 'ScanTemplateError';
+    }
+}
+exports.ScanTemplateError = ScanTemplateError;
+const BAG_TOKEN = /\{(claim|item)\.([a-zA-Z0-9_]+)\}/g;
+/** True when any string in the params mentions a `{claim.…}` token. */
+function mentionsClaimToken(value) {
+    return JSON.stringify(value ?? null).includes(`{${types_1.SCAN_TEMPLATE_BAGS.CLAIM}.`);
+}
+function resolveBagToken(ctx, bag, facet, token) {
+    const source = bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM ? ctx.claim : ctx.item;
+    if (!source) {
+        throw new ScanTemplateError(token, bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM
+            ? 'the actor holds no single live claim'
+            : 'no located item row on this step');
+    }
+    const v = source[facet];
+    if (v === undefined || v === null || v === '') {
+        throw new ScanTemplateError(token, `facet ${facet} is absent`);
+    }
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+}
 /**
- * Replace SCAN_TEMPLATE_TOKENS inside string values of a params object.
- * Deep, pure, non-mutating. Only exact-token and in-string replacement of
- * the three known tokens — no expression language.
+ * Replace the template tokens inside string values of a params object.
+ * Deep, pure, non-mutating. The three scan tokens are plain text
+ * replacement; `{claim.<facet>}` and `{item.<facet>}` read the context's
+ * facet bags and throw {@link ScanTemplateError} when they cannot resolve,
+ * so a literal token never reaches a row. No expression language.
  */
 function interpolateScanTemplate(value, ctx) {
     if (typeof value === 'string') {
-        return value
+        const scanned = value
             .split(types_1.SCAN_TEMPLATE_TOKENS.TARGET).join(ctx.target)
             .split(types_1.SCAN_TEMPLATE_TOKENS.CATEGORY).join(ctx.category)
             .split(types_1.SCAN_TEMPLATE_TOKENS.SCANNED_AT).join(ctx.scannedAt);
+        return scanned.replace(BAG_TOKEN, (token, bag, facet) => resolveBagToken(ctx, bag, facet, token));
     }
     if (Array.isArray(value)) {
         return value.map((v) => interpolateScanTemplate(v, ctx));

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,22 @@ 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`);
+            }
+        }
+        assertValidTemplateTokens(step, at);
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);
         }
@@ -162,3 +179,21 @@ function assertValidSteps(steps) {
         }
     });
 }
+const BAG_TOKEN = /\{(claim|item)\.([^}]*)\}/g;
+/**
+ * `{claim.<facet>}` and `{item.<facet>}` name facet keys; `{item.…}` reads
+ * the located row, which only an item-mode accumulate step has.
+ */
+function assertValidTemplateTokens(step, at) {
+    const text = JSON.stringify(step.params ?? {});
+    const itemMode = step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet;
+    for (const match of text.matchAll(BAG_TOKEN)) {
+        const [token, bag, facet] = match;
+        if (!facet_sql_1.FACET_KEY.test(facet)) {
+            throw new Error(`${at}: template token ${token} must name a facet key`);
+        }
+        if (bag === 'item' && !itemMode) {
+            throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate step has`);
+        }
+    }
+}

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);

package/build/shared/form-validation/x-lt-bind.d.ts

@@ -1,16 +1,3 @@
-/**
- * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
- * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
- * may declare `x-lt-bind: "a.b[0].c"`, the path its value occupies in the payload;
- * a property with no bind sits at its own name at the root (1:1). This module is
- * isomorphic — the dashboard renders forms with it, and the API layer inverts a
- * submitted payload through it to validate against the form contract. One
- * implementation, both sides.
- *
- *   mapPayloadToForm  — payload → flat form values, to PREFILL/display the form
- *                       (server-side: to validate a submitted payload)
- *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
- */
 type PathSeg = {
     key: string;
 } | {
@@ -27,7 +14,8 @@ export declare function bindPathFor(propName: string, propDef: Record<string, an
 /**
  * Assemble the payload from the form's flat values. A field absent from
  * `formValues` is omitted (so clearing/deleting a field drops it from the
- * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * payload). Unknown keys not declared in the schema are dropped, and so are
+ * display-only widget fields, which carry no answer. With no schema
  * properties, values pass through unchanged.
  */
 export declare function mapFormToPayload(formValues: Record<string, any>, formSchema: Record<string, any> | null | undefined): Record<string, any>;

package/build/shared/form-validation/x-lt-bind.js

@@ -1,4 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePath = parsePath;
+exports.setDeep = setDeep;
+exports.getDeep = getDeep;
+exports.bindPathFor = bindPathFor;
+exports.mapFormToPayload = mapFormToPayload;
+exports.mapPayloadToForm = mapPayloadToForm;
 /**
  * x-lt-bind — maps the escalation FORM (flat field values the user edits) to and
  * from the PAYLOAD (the nested JSON the workflow consumes). A form_schema property
@@ -12,13 +19,7 @@
  *                       (server-side: to validate a submitted payload)
  *   mapFormToPayload  — flat form values → payload, the shape submitted/stored
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parsePath = parsePath;
-exports.setDeep = setDeep;
-exports.getDeep = getDeep;
-exports.bindPathFor = bindPathFor;
-exports.mapFormToPayload = mapFormToPayload;
-exports.mapPayloadToForm = mapPayloadToForm;
+const display_only_widgets_1 = require("./display-only-widgets");
 const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 /** Parse a bind path — dot keys with optional `[n]` indices. Rejects pollution keys. */
 function parsePath(path) {
@@ -75,7 +76,8 @@ function bindPathFor(propName, propDef) {
 /**
  * Assemble the payload from the form's flat values. A field absent from
  * `formValues` is omitted (so clearing/deleting a field drops it from the
- * payload). Unknown keys not declared in the schema are dropped. With no schema
+ * payload). Unknown keys not declared in the schema are dropped, and so are
+ * display-only widget fields, which carry no answer. With no schema
  * properties, values pass through unchanged.
  */
 function mapFormToPayload(formValues, formSchema) {
@@ -86,6 +88,8 @@ function mapFormToPayload(formValues, formSchema) {
     for (const [name, def] of Object.entries(props)) {
         if (!(name in formValues))
             continue;
+        if ((0, display_only_widgets_1.isDisplayOnlyField)(def))
+            continue;
         setDeep(payload, bindPathFor(name, def), formValues[name]);
     }
     return payload;

package/build/shared/form-validation/x-lt-invoke.d.ts

@@ -0,0 +1,38 @@
+export declare const X_LT_INVOKE = "x-lt-invoke";
+export declare const INVOKE_WIDGET: "invoke";
+export declare const INVOKE_VARIANTS: {
+    readonly LINK: "link";
+    readonly BUTTON: "button";
+};
+export type InvokeVariant = (typeof INVOKE_VARIANTS)[keyof typeof INVOKE_VARIANTS];
+export interface InvokeConfig {
+    /** The workflow_type to start. */
+    workflow: string;
+    /** Nested invoke `data` template; leaves interpolate against the context. */
+    data: Record<string, unknown>;
+    /** Extra run metadata template, merged over the workflow's declared metadata. */
+    metadata: Record<string, unknown>;
+    /** Open the workflow's input form prefilled instead of posting directly. */
+    modal: boolean;
+    /** Direct mode only: a prompt to confirm before posting; tokens interpolate. */
+    confirm: string | null;
+    variant: InvokeVariant;
+    /** Lead the label with the workflow's registered icon. */
+    icon: boolean;
+}
+export interface InvokePayload {
+    data: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+}
+type Ctx = Record<string, unknown> | null | undefined;
+/** The field's invoke declaration, or null when it names no workflow. */
+export declare function readInvokeConfig(fieldSchema: Record<string, unknown> | null | undefined): InvokeConfig | null;
+/**
+ * Resolve one template value against the context, keeping the type of a
+ * whole-token leaf. Returns undefined for a token with no value so the
+ * caller omits the key.
+ */
+export declare function interpolateInvokeValue(value: unknown, ctx: Ctx): unknown;
+/** The invoke payload for one context: `data` and `metadata` fully resolved. */
+export declare function resolveInvokePayload(config: InvokeConfig, ctx: Ctx): InvokePayload;
+export {};

package/build/shared/form-validation/x-lt-invoke.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVOKE_VARIANTS = exports.INVOKE_WIDGET = exports.X_LT_INVOKE = void 0;
+exports.readInvokeConfig = readInvokeConfig;
+exports.interpolateInvokeValue = interpolateInvokeValue;
+exports.resolveInvokePayload = resolveInvokePayload;
+/**
+ * x-lt-invoke: start a workflow from inside a form. A display-only field
+ * declares the target workflow and how the form's context maps into the
+ * invoke payload:
+ *
+ *   "x-lt-widget": "invoke",
+ *   "x-lt-invoke": {
+ *     "workflow": "printPamphlet",
+ *     "data": { "order": { "id": "{{metadata.orderId}}" }, "copies": 1 },
+ *     "metadata": { "escalationId": "{{escalation.id}}" },
+ *     "modal": true,
+ *     "confirm": "Print a pamphlet for {{metadata.orderId}}?",
+ *     "variant": "link",
+ *     "icon": true
+ *   }
+ *
+ * `data` is the nested payload the invoke API receives. In direct mode it is
+ * posted as resolved; in modal mode it prefills the workflow's own input form
+ * through the x-lt-bind inversion. One declaration serves both.
+ *
+ * Interpolation keeps types: a leaf that is exactly one `{{domain.path}}`
+ * token becomes the raw context value (a number stays a number); a leaf that
+ * mixes text and tokens becomes a string; a token with no value drops its key
+ * so the target's own defaults apply. Objects and arrays recurse; every other
+ * leaf passes through unchanged.
+ */
+const display_only_widgets_1 = require("./display-only-widgets");
+const ctx_path_1 = require("./ctx-path");
+exports.X_LT_INVOKE = 'x-lt-invoke';
+exports.INVOKE_WIDGET = display_only_widgets_1.DISPLAY_ONLY_WIDGET_NAMES.INVOKE;
+exports.INVOKE_VARIANTS = {
+    LINK: 'link',
+    BUTTON: 'button',
+};
+const WHOLE_TOKEN_PATTERN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isVariant(value) {
+    return value === exports.INVOKE_VARIANTS.LINK || value === exports.INVOKE_VARIANTS.BUTTON;
+}
+/** The field's invoke declaration, or null when it names no workflow. */
+function readInvokeConfig(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_INVOKE];
+    if (!isPlainObject(raw))
+        return null;
+    const workflow = raw.workflow;
+    if (typeof workflow !== 'string' || workflow.trim().length === 0)
+        return null;
+    const confirm = raw.confirm;
+    return {
+        workflow: workflow.trim(),
+        data: isPlainObject(raw.data) ? raw.data : {},
+        metadata: isPlainObject(raw.metadata) ? raw.metadata : {},
+        modal: raw.modal === true,
+        confirm: typeof confirm === 'string' && confirm.trim().length > 0 ? confirm : null,
+        variant: isVariant(raw.variant) ? raw.variant : exports.INVOKE_VARIANTS.LINK,
+        icon: raw.icon !== false,
+    };
+}
+/**
+ * Resolve one template value against the context, keeping the type of a
+ * whole-token leaf. Returns undefined for a token with no value so the
+ * caller omits the key.
+ */
+function interpolateInvokeValue(value, ctx) {
+    if (typeof value === 'string') {
+        const whole = WHOLE_TOKEN_PATTERN.exec(value);
+        if (whole) {
+            const resolved = (0, ctx_path_1.resolveCtxPath)(whole[1], ctx ?? undefined);
+            return resolved === null ? undefined : resolved;
+        }
+        if ((0, ctx_path_1.hasInterpolation)(value))
+            return (0, ctx_path_1.interpolatePath)(value, ctx ?? undefined) ?? undefined;
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => interpolateInvokeValue(v, ctx)).filter((v) => v !== undefined);
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            const resolved = interpolateInvokeValue(v, ctx);
+            if (resolved !== undefined)
+                out[key] = resolved;
+        }
+        return out;
+    }
+    return value;
+}
+/** The invoke payload for one context: `data` and `metadata` fully resolved. */
+function resolveInvokePayload(config, ctx) {
+    return {
+        data: interpolateInvokeValue(config.data, ctx),
+        metadata: interpolateInvokeValue(config.metadata, ctx),
+    };
+}