@hotmeshio/long-tail 0.23.1 → 0.23.2

package/build/services/escalation/related.js

@@ -0,0 +1,196 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Related sets for list views: a host row's items (each read through its
+// payload or its reciprocal row) and rows in other roles that share facets
+// with it. Every statement serves a whole page of hosts and composes the
+// caller's read scope, so the cost is bounded by the declaration, never by
+// the page size or the item count.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateRelatedItems = aggregateRelatedItems;
+exports.listRelatedItems = listRelatedItems;
+exports.aggregateRelatedQuery = aggregateRelatedQuery;
+exports.listRelatedQueryRows = listRelatedQueryRows;
+exports.readRelatedHosts = readRelatedHosts;
+const db_1 = require("../../lib/db");
+const uuid_1 = require("../../lib/uuid");
+const escalation_1 = require("../../types/escalation");
+const list_schema_1 = require("../../shared/list-schema");
+const client_1 = require("./client");
+const map_1 = require("./map");
+const read_scope_sql_1 = require("./read-scope-sql");
+const UUID_PATTERN = uuid_1.UUID_RE.source;
+function foldAggregateRows(rows, hostIds, split) {
+    const out = {};
+    for (const id of hostIds)
+        out[id] = split ? { count: 0, splits: {} } : { count: 0 };
+    for (const row of rows) {
+        const agg = out[row.host_id];
+        if (!agg)
+            continue;
+        agg.count += row.n;
+        if (row.hidden) {
+            agg.hidden = (agg.hidden ?? 0) + row.n;
+        }
+        else if (split) {
+            const key = row.split ?? '';
+            agg.splits[key] = (agg.splits[key] ?? 0) + row.n;
+        }
+    }
+    return out;
+}
+/** The hosts and their item entries, read under the caller's scope. */
+function itemEntriesCte(params, scope, hostIds) {
+    const hi = params.push(hostIds);
+    const hostScope = (0, read_scope_sql_1.buildReadScopeClause)(scope, params, 'h');
+    return `hosts AS (
+      SELECT h.id, h.envelope,
+        (h.envelope ? '${escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS}') AS acc,
+        COALESCE(h.envelope->'${escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS}', h.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.ITEMS}') AS items
+      FROM public.lt_escalations h
+      WHERE h.id = ANY($${hi}::uuid[])${hostScope ? ` AND ${hostScope}` : ''}
+    ), entries AS (
+      SELECT hosts.id AS host_id, hosts.acc, hosts.envelope, e.key AS item_key, e.value AS entry,
+        CASE WHEN hosts.acc AND (e.value->>'reciprocalId') ~* '${UUID_PATTERN}'
+          THEN (e.value->>'reciprocalId')::uuid END AS rid
+      FROM hosts, jsonb_each(CASE WHEN jsonb_typeof(hosts.items) = 'object' THEN hosts.items ELSE '{}'::jsonb END) e
+    )`;
+}
+/**
+ * Count each host's items, optionally split by `payload.<path>` or
+ * `reciprocal.metadata.<key>`. A reciprocal split counts only reciprocal rows
+ * the caller can read; the rest are reported as `hidden`. `roles` names the
+ * roles of the readable reciprocal rows, so a list can follow their changes.
+ */
+async function aggregateRelatedItems(opts) {
+    if (!opts.hostIds.length)
+        return { aggregates: {}, roles: [] };
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const cte = itemEntriesCte(params, opts.scope, opts.hostIds);
+    const splitBy = opts.splitBy ?? '';
+    let splitExpr = 'NULL::text';
+    let join = '';
+    let hiddenExpr = 'false';
+    let rolesExpr = 'NULL::text[]';
+    if (splitBy.startsWith(list_schema_1.SPLIT_PATHS.PAYLOAD)) {
+        const pi = params.push(splitBy.slice(list_schema_1.SPLIT_PATHS.PAYLOAD.length).split('.'));
+        splitExpr = `(CASE WHEN en.acc THEN en.entry->'payload' ELSE en.entry END) #>> $${pi}::text[]`;
+    }
+    else if (splitBy.startsWith(list_schema_1.SPLIT_PATHS.RECIPROCAL_METADATA)) {
+        const ki = params.push(splitBy.slice(list_schema_1.SPLIT_PATHS.RECIPROCAL_METADATA.length));
+        const rScope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params, 'r');
+        join = `LEFT JOIN public.lt_escalations r ON r.id = en.rid${rScope ? ` AND ${rScope}` : ''}`;
+        splitExpr = `r.metadata->>$${ki}`;
+        hiddenExpr = '(en.rid IS NOT NULL AND r.id IS NULL)';
+        rolesExpr = 'array_agg(DISTINCT r.role) FILTER (WHERE r.id IS NOT NULL)';
+    }
+    const { rows } = await (0, db_1.getPool)().query(`WITH ${cte}
+     SELECT en.host_id::text AS host_id, ${splitExpr} AS split, ${hiddenExpr} AS hidden, count(*)::int AS n,
+       ${rolesExpr} AS roles
+     FROM entries en ${join}
+     GROUP BY 1, 2, 3`, params);
+    const roles = new Set(rows.flatMap((row) => row.roles ?? []));
+    return { aggregates: foldAggregateRows(rows, opts.hostIds, !!splitBy), roles: [...roles].sort() };
+}
+/** One host's items in fill order, each with its reciprocal row when readable. */
+async function listRelatedItems(opts) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const cte = itemEntriesCte(params, opts.scope, [opts.hostId]);
+    const rScope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params, 'r');
+    const li = params.push(opts.limit);
+    const { rows } = await (0, db_1.getPool)().query(`WITH ${cte}
+     SELECT en.item_key, en.entry, en.acc,
+       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_AT}'->>en.item_key AS batch_at,
+       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_BY}'->>en.item_key AS batch_actor,
+       (en.rid IS NOT NULL AND r.id IS NULL) AS hidden,
+       CASE WHEN r.id IS NULL THEN NULL ELSE to_jsonb(r) END AS reciprocal,
+       count(*) OVER ()::int AS total
+     FROM entries en
+     LEFT JOIN public.lt_escalations r ON r.id = en.rid${rScope ? ` AND ${rScope}` : ''}
+     ORDER BY COALESCE(CASE WHEN en.acc THEN en.entry->>'at' END,
+                       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_AT}'->>en.item_key) NULLS LAST, en.item_key
+     LIMIT $${li}`, params);
+    return {
+        total: rows[0]?.total ?? 0,
+        rows: rows.map((row) => {
+            const entry = row.entry ?? {};
+            const item = row.acc
+                ? {
+                    itemKey: row.item_key,
+                    payload: entry.payload,
+                    at: entry.at,
+                    ...(entry.actor ? { actor: entry.actor } : {}),
+                    ...(entry.reciprocalId ? { reciprocalId: entry.reciprocalId } : {}),
+                }
+                : {
+                    itemKey: row.item_key,
+                    payload: entry,
+                    ...(row.batch_at ? { at: row.batch_at } : {}),
+                    ...(row.batch_actor ? { actor: row.batch_actor } : {}),
+                };
+            return { item, escalation: row.reciprocal ? (0, map_1.toEscalationRecord)(row.reciprocal) : null };
+        }),
+    };
+}
+/** The shared FROM/WHERE of a query set: hosts unnested beside their matches. */
+function querySetFrom(params, input) {
+    const hi = params.push(input.hosts.map((h) => h.hostId));
+    const mi = params.push(input.hosts.map((h) => JSON.stringify(h.match)));
+    const ri = params.push(input.roles);
+    const si = params.push(input.status);
+    const scope = (0, read_scope_sql_1.buildReadScopeClause)(input.scope, params, 'e');
+    return `FROM unnest($${hi}::text[], $${mi}::jsonb[]) AS h(host_id, match)
+     JOIN public.lt_escalations e ON e.metadata @> h.match
+     WHERE e.role = ANY($${ri}::text[]) AND e.status = $${si}
+       AND e.id::text <> h.host_id${scope ? ` AND ${scope}` : ''}`;
+}
+/**
+ * Count the rows that share each host's facets, grouped by role and an
+ * optional `metadata.<key>` split. The GIN index serves each host's match.
+ */
+async function aggregateRelatedQuery(input) {
+    const hostIds = input.hosts.map((h) => h.hostId);
+    if (!hostIds.length || !input.roles.length)
+        return foldAggregateRows([], hostIds, !!input.splitBy);
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const from = querySetFrom(params, input);
+    let splitExpr = 'NULL::text';
+    if (input.splitBy === list_schema_1.SPLIT_PATHS.ROLE) {
+        splitExpr = 'e.role';
+    }
+    else if (input.splitBy?.startsWith(list_schema_1.SPLIT_PATHS.METADATA)) {
+        splitExpr = `e.metadata->>$${params.push(input.splitBy.slice(list_schema_1.SPLIT_PATHS.METADATA.length))}`;
+    }
+    const { rows } = await (0, db_1.getPool)().query(`SELECT h.host_id, ${splitExpr} AS split, count(*)::int AS n ${from} GROUP BY 1, 2`, params);
+    return foldAggregateRows(rows, hostIds, !!input.splitBy);
+}
+/** One host's related rows, in role order then age. */
+async function listRelatedQueryRows(input) {
+    if (!input.hosts.length || !input.roles.length)
+        return { rows: [], total: 0 };
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const from = querySetFrom(params, input);
+    const oi = params.push(input.roles);
+    const li = params.push(input.limit);
+    const { rows } = await (0, db_1.getPool)().query(`SELECT to_jsonb(e) AS row, count(*) OVER ()::int AS total ${from}
+     ORDER BY array_position($${oi}::text[], e.role), e.created_at
+     LIMIT $${li}`, params);
+    return {
+        total: rows[0]?.total ?? 0,
+        rows: rows.map((r) => ({ escalation: (0, map_1.toEscalationRecord)(r.row) })),
+    };
+}
+/** Host rows of one role, read under the caller's scope. */
+async function readRelatedHosts(opts) {
+    if (!opts.ids.length)
+        return [];
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [opts.ids, opts.role];
+    const scope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params);
+    const { rows } = await (0, db_1.getPool)().query(`SELECT * FROM public.lt_escalations WHERE id = ANY($1::uuid[]) AND role = $2${scope ? ` AND ${scope}` : ''}`, params);
+    return rows.map((row) => (0, map_1.toEscalationRecord)(row));
+}

package/build/services/role/index.js

@@ -19,6 +19,7 @@ exports.getRoleFormSchema = getRoleFormSchema;
 exports.getRoleMetadataSchema = getRoleMetadataSchema;
 exports.getRoleProperties = getRoleProperties;
 exports.deleteRole = deleteRole;
+const list_schema_1 = require("../../shared/list-schema");
 const db_1 = require("../../lib/db");
 const user_1 = require("../user");
 const sql_1 = require("./sql");
@@ -128,6 +129,11 @@ async function createRole(role) {
  * resets to {}). One atomic UPDATE — see UPDATE_ROLE_METADATA.
  */
 async function updateRoleMetadata(role, input) {
+    if (input.list_schema != null) {
+        const listSchemaError = (0, list_schema_1.listSchemaRelationsError)(input.list_schema);
+        if (listSchemaError)
+            throw new Error(`list_schema: ${listSchemaError}`);
+    }
     const pool = (0, db_1.getPool)();
     const provided = (key) => input[key] !== undefined;
     const upstreams = [...new Set(input.upstream_roles ?? [])].sort();

package/build/services/role/seed.js

@@ -9,6 +9,7 @@ const logger_1 = require("../../lib/logger");
 const index_1 = require("./index");
 const sql_1 = require("./sql");
 const badge_grant_1 = require("./badge-grant");
+const list_schema_1 = require("../../shared/list-schema");
 const types_1 = require("./types");
 /** Recorded on schema snapshots written by the startup apply. */
 exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
@@ -84,6 +85,9 @@ async function applyRoleConfig(cfg, codeOwned) {
     const grantError = (0, badge_grant_1.badgeGrantError)(cfg.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
     if (grantError)
         throw new Error(`role ${cfg.role}: ${grantError}`);
+    const listSchemaError = cfg.list_schema != null ? (0, list_schema_1.listSchemaRelationsError)(cfg.list_schema) : null;
+    if (listSchemaError)
+        throw new Error(`role ${cfg.role}: list_schema: ${listSchemaError}`);
     const created = await (0, index_1.createRole)(cfg.role);
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.GET_ROLE_ROW, [cfg.role]);

package/build/services/scan-code/validate-facts.d.ts

@@ -1,5 +1,5 @@
 import { type ScanStep } from '../../types';
 /** The most facts a station screen states before it reads as a data dump. */
 export declare const SCAN_FACTS_MAX = 12;
-/** `facts` on a present step: labeled template values the station states. */
+/** `facts` on a present step: labeled template values the station states, optionally formatted. */
 export declare function assertValidFacts(step: ScanStep, at: string): void;

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

@@ -3,9 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SCAN_FACTS_MAX = void 0;
 exports.assertValidFacts = assertValidFacts;
 const types_1 = require("../../types");
+const FACT_FORMATS = new Set(Object.values(types_1.SCAN_FACT_FORMATS));
+/** A formatted fact reads one value: a single `{bag.key}` token. */
+const SINGLE_TOKEN = /^\{[a-z]+\.[^{}]+\}$/;
 /** The most facts a station screen states before it reads as a data dump. */
 exports.SCAN_FACTS_MAX = 12;
-/** `facts` on a present step: labeled template values the station states. */
+/** `facts` on a present step: labeled template values the station states, optionally formatted. */
 function assertValidFacts(step, at) {
     if (step.facts === undefined)
         return;
@@ -20,5 +23,13 @@ function assertValidFacts(step, at) {
         }
         if (typeof fact.value !== 'string')
             throw new Error(`${at}: facts[${i}].value must be a template string`);
+        if (fact.format === undefined)
+            return;
+        if (!FACT_FORMATS.has(fact.format)) {
+            throw new Error(`${at}: facts[${i}].format must be one of ${[...FACT_FORMATS].join(', ')}`);
+        }
+        if (!SINGLE_TOKEN.test(fact.value.trim())) {
+            throw new Error(`${at}: facts[${i}] with a format must read a single token, e.g. {item.releaseAt}`);
+        }
     });
 }

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

@@ -10,6 +10,8 @@ export interface ScanSink {
     expectError: string;
     /** Array fields: 'count' takes a value as many times as it is expected. */
     multiplicity: 'count' | 'once';
+    /** Array fields: the instruction shown while the field is empty. */
+    prompt?: string;
 }
 /** The parts of a parsed scan a sink reads. */
 export interface SinkScan {
@@ -30,6 +32,12 @@ export declare function resolveScanExpected(sink: ScanSink, ctx: Record<string,
  * each expected value once (or as many times as expected, with 'count').
  */
 export declare function scanSinkError(value: unknown, fieldSchema: Schema | undefined, ctx: Record<string, unknown> | undefined): string | undefined;
+/**
+ * How many scans complete an array field: the scans its expected list admits
+ * (each listing under 'count', each distinct value otherwise), else
+ * `maxItems`, else null. The checklist and the admission gate share it.
+ */
+export declare function scanTargetCount(fieldSchema: Schema | undefined, ctx: Record<string, unknown> | undefined): number | null;
 /** What a scan does to a field: the next value, or the error to show (nothing written). */
 export declare function applyScanToField(current: unknown, scan: SinkScan, fieldSchema: Schema, ctx: Record<string, unknown> | undefined): {
     ok: true;

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

@@ -5,6 +5,7 @@ exports.readScanSink = readScanSink;
 exports.sameScanValue = sameScanValue;
 exports.resolveScanExpected = resolveScanExpected;
 exports.scanSinkError = scanSinkError;
+exports.scanTargetCount = scanTargetCount;
 exports.applyScanToField = applyScanToField;
 exports.pickScanSink = pickScanSink;
 exports.wantsScanSubmit = wantsScanSubmit;
@@ -27,7 +28,9 @@ exports.scanFieldsFilled = scanFieldsFilled;
  * Root `x-lt-scan-submit: true` submits once every required scan field is
  * filled and the form validates. A string field is replaced by a scan; an
  * array field appends, and with `multiplicity: "count"` a value expected n
- * times takes n scans.
+ * times takes n scans. `prompt` is the empty array field's instruction (the
+ * field description when absent); the field reads `n of N` against the same
+ * expected list that admits each scan, or `maxItems`.
  */
 const ctx_path_1 = require("./ctx-path");
 exports.X_LT_SCAN = 'x-lt-scan';
@@ -50,6 +53,7 @@ function readScanSink(fieldSchema) {
         ...(expect?.length ? { expect } : {}),
         expectError: typeof cfg['expect-error'] === 'string' ? cfg['expect-error'] : DEFAULT_EXPECT_ERROR,
         multiplicity: cfg.multiplicity === 'count' ? 'count' : 'once',
+        ...(typeof cfg.prompt === 'string' && cfg.prompt.trim() ? { prompt: cfg.prompt } : {}),
     };
 }
 /** Manufacturer barcodes compare as GTINs, so a UPC-A matches its 14-digit form. */
@@ -102,6 +106,21 @@ function scanSinkError(value, fieldSchema, ctx) {
     }
     return undefined;
 }
+/**
+ * How many scans complete an array field: the scans its expected list admits
+ * (each listing under 'count', each distinct value otherwise), else
+ * `maxItems`, else null. The checklist and the admission gate share it.
+ */
+function scanTargetCount(fieldSchema, ctx) {
+    const sink = readScanSink(fieldSchema);
+    if (sink) {
+        const expected = resolveScanExpected(sink, ctx);
+        if (expected !== null)
+            return sink.multiplicity === 'count' ? expected.length : new Set(expected).size;
+    }
+    const max = fieldSchema?.maxItems;
+    return typeof max === 'number' ? max : null;
+}
 /** What a scan does to a field: the next value, or the error to show (nothing written). */
 function applyScanToField(current, scan, fieldSchema, ctx) {
     const sink = readScanSink(fieldSchema);

package/build/shared/list-schema/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { METADATA_KEY, readListSchemaRelations, listSchemaRelationsError, splitPathError } from './validate';
+export { rowTemplateContext, resolveTemplateValue, resolveRelatedFacets } from './template';

package/build/shared/list-schema/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRelatedFacets = exports.resolveTemplateValue = exports.rowTemplateContext = exports.splitPathError = exports.listSchemaRelationsError = exports.readListSchemaRelations = exports.METADATA_KEY = void 0;
+__exportStar(require("./types"), exports);
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "METADATA_KEY", { enumerable: true, get: function () { return validate_1.METADATA_KEY; } });
+Object.defineProperty(exports, "readListSchemaRelations", { enumerable: true, get: function () { return validate_1.readListSchemaRelations; } });
+Object.defineProperty(exports, "listSchemaRelationsError", { enumerable: true, get: function () { return validate_1.listSchemaRelationsError; } });
+Object.defineProperty(exports, "splitPathError", { enumerable: true, get: function () { return validate_1.splitPathError; } });
+var template_1 = require("./template");
+Object.defineProperty(exports, "rowTemplateContext", { enumerable: true, get: function () { return template_1.rowTemplateContext; } });
+Object.defineProperty(exports, "resolveTemplateValue", { enumerable: true, get: function () { return template_1.resolveTemplateValue; } });
+Object.defineProperty(exports, "resolveRelatedFacets", { enumerable: true, get: function () { return template_1.resolveRelatedFacets; } });

package/build/shared/list-schema/template.d.ts

@@ -0,0 +1,14 @@
+import { type HelpTokenContext } from '../form-validation/x-lt-help';
+/** The template domains of one escalation row, JSON-string columns parsed. */
+export declare function rowTemplateContext(row: Record<string, unknown>): HelpTokenContext;
+/**
+ * Resolve one facet value. A lone `{{token}}` keeps the value's own JSON type
+ * (a numeric facet matches a numeric facet); a mixed template interpolates to
+ * a string; a literal passes through. Undefined when a token is missing.
+ */
+export declare function resolveTemplateValue(value: unknown, ctx: HelpTokenContext): unknown;
+/**
+ * Resolve a related query's match against a host row: every required facet
+ * (null when any is missing), plus each `narrow` facet the row resolves.
+ */
+export declare function resolveRelatedFacets(facets: Record<string, unknown>, ctx: HelpTokenContext, narrow?: Record<string, unknown>): Record<string, unknown> | null;

package/build/shared/list-schema/template.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rowTemplateContext = rowTemplateContext;
+exports.resolveTemplateValue = resolveTemplateValue;
+exports.resolveRelatedFacets = resolveRelatedFacets;
+const x_lt_bind_1 = require("../form-validation/x-lt-bind");
+const x_lt_help_1 = require("../form-validation/x-lt-help");
+const SINGLE_TOKEN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const ANY_TOKEN = /\{\{\s*[^{}]+?\s*\}\}/;
+const MISSING_VALUE = '—';
+function parseJsonObject(value) {
+    if (value && typeof value === 'object')
+        return value;
+    if (typeof value !== 'string' || !value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The template domains of one escalation row, JSON-string columns parsed. */
+function rowTemplateContext(row) {
+    return {
+        escalation: row,
+        metadata: row.metadata ?? {},
+        envelope: parseJsonObject(row.envelope) ?? {},
+        payload: parseJsonObject(row.escalation_payload) ?? {},
+        resolver: parseJsonObject(row.resolver_payload) ?? {},
+    };
+}
+function readToken(path, ctx) {
+    const dot = path.indexOf('.');
+    const domain = (dot === -1 ? path : path.slice(0, dot));
+    if (!x_lt_help_1.HELP_DOMAINS.includes(domain))
+        return undefined;
+    const root = ctx[domain];
+    if (dot === -1)
+        return root ?? undefined;
+    try {
+        return (0, x_lt_bind_1.getDeep)(root, path.slice(dot + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one facet value. A lone `{{token}}` keeps the value's own JSON type
+ * (a numeric facet matches a numeric facet); a mixed template interpolates to
+ * a string; a literal passes through. Undefined when a token is missing.
+ */
+function resolveTemplateValue(value, ctx) {
+    if (typeof value !== 'string')
+        return value;
+    const single = value.match(SINGLE_TOKEN);
+    if (single) {
+        const raw = readToken(single[1], ctx);
+        return raw === null || raw === '' ? undefined : raw;
+    }
+    if (!ANY_TOKEN.test(value))
+        return value;
+    const text = (0, x_lt_help_1.interpolateHelp)(value, ctx);
+    return text.includes(MISSING_VALUE) ? undefined : text;
+}
+/**
+ * Resolve a related query's match against a host row: every required facet
+ * (null when any is missing), plus each `narrow` facet the row resolves.
+ */
+function resolveRelatedFacets(facets, ctx, narrow) {
+    const out = {};
+    for (const [key, value] of Object.entries(facets)) {
+        const resolved = resolveTemplateValue(value, ctx);
+        if (resolved === undefined)
+            return null;
+        out[key] = resolved;
+    }
+    for (const [key, value] of Object.entries(narrow ?? {})) {
+        const resolved = resolveTemplateValue(value, ctx);
+        if (resolved !== undefined)
+            out[key] = resolved;
+    }
+    return out;
+}

package/build/shared/list-schema/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Related sets on a role's list schema. A set is named once under
+ * `x-lt-related`; columns (`related`) and row details (`x-lt-row-detail`)
+ * reference it by name. The server reads the declaration from the stored
+ * list schema, never from the caller.
+ *
+ *   items  the host row's accumulated or batch items, each read through its
+ *          payload or its reciprocal row
+ *   query  rows in other roles that share facets with the host row; facet
+ *          values are `{{domain.path}}` templates over the host row
+ */
+export declare const LIST_SCHEMA_KEYS: {
+    readonly RELATED: "x-lt-related";
+    readonly COLUMNS: "x-lt-columns";
+    readonly ROW_DETAIL: "x-lt-row-detail";
+    readonly GROUP_BY: "x-lt-group-by";
+    readonly LAYOUT: "x-lt-layout";
+};
+export declare const RELATED_SOURCES: {
+    readonly ITEMS: "items";
+    readonly QUERY: "query";
+};
+export type RelatedSource = (typeof RELATED_SOURCES)[keyof typeof RELATED_SOURCES];
+export declare const RELATED_AGGREGATES: {
+    readonly COUNT: "count";
+};
+export type RelatedAggregate = (typeof RELATED_AGGREGATES)[keyof typeof RELATED_AGGREGATES];
+/** How a grouped table folds a plain column across a group's rows. */
+export declare const GROUP_FOLDS: {
+    readonly FIRST: "first";
+    readonly MIN: "min";
+    readonly MAX: "max";
+    readonly SUM: "sum";
+    readonly COUNT: "count";
+    /** The distinct values, in row order, joined: "standard, express". */
+    readonly DISTINCT: "distinct";
+};
+export type GroupFold = (typeof GROUP_FOLDS)[keyof typeof GROUP_FOLDS];
+/** Split prefixes. `role` splits a query set by the related row's role. */
+export declare const SPLIT_PATHS: {
+    readonly ROLE: "role";
+    readonly METADATA: "metadata.";
+    readonly PAYLOAD: "payload.";
+    readonly RECIPROCAL_METADATA: "reciprocal.metadata.";
+};
+export declare const RELATED_LIMITS: {
+    readonly MAX_SETS: 4;
+    readonly MAX_QUERY_ROLES: 12;
+    readonly MAX_ROW_DETAIL_SECTIONS: 4;
+    readonly MAX_HOSTS: 100;
+    readonly ROWS_DEFAULT: 25;
+    readonly ROWS_MAX: 100;
+};
+/** The table layout that renders related columns, row details, and groups. */
+export declare const FACET_TABLE_LAYOUT = "facet-table";
+export interface RelatedQueryDecl {
+    /** Related roles, in display order. Exclusive with `segment`. */
+    roles?: string[];
+    /** A Pace Board sequence by its first role; resolves to the ordered chain. */
+    segment?: string;
+    /** Facet containment; string values may be `{{domain.path}}` templates. */
+    facets?: Record<string, unknown>;
+    /**
+     * Facets that narrow the match when the host row carries a value, and
+     * drop away when it does not: a lane narrows its tub's look-ahead to its
+     * own service level, a tub without lanes keeps the whole destination.
+     */
+    narrow?: Record<string, unknown>;
+    /** Default `pending`. */
+    status?: string;
+}
+export interface RelatedSetDecl {
+    source: RelatedSource;
+    query?: RelatedQueryDecl;
+}
+export interface RelatedColumnDecl {
+    label: string;
+    related: string;
+    aggregate?: RelatedAggregate;
+    splitBy?: string;
+    labels?: Record<string, string>;
+    priority?: 1 | 2 | 3;
+    /** CSS width, as on any facet-table column. */
+    width?: string;
+}
+export interface RowDetailColumnDecl {
+    label: string;
+    value: string;
+    format?: string;
+    priority?: 1 | 2 | 3;
+}
+export interface RowDetailSectionDecl {
+    related: string;
+    label?: string;
+    columns: RowDetailColumnDecl[];
+    limit?: number;
+}
+/** The validated, normalized related declaration of one list schema. */
+export interface ListSchemaRelations {
+    sets: Record<string, RelatedSetDecl>;
+    columns: RelatedColumnDecl[];
+    rowDetail: RowDetailSectionDecl[];
+    /** The metadata key a facet-table groups by, when declared. */
+    groupKey: string | null;
+}
+/** Per-host aggregate for one (set, splitBy) pair. */
+export interface RelatedHostAggregate {
+    count: number;
+    /** Split value to count; a null value is keyed by the empty string. */
+    splits?: Record<string, number>;
+    /** Items whose reciprocal row the viewer cannot read. */
+    hidden?: number;
+    /** A host whose facet templates resolved to nothing; the set did not run. */
+    unresolved?: boolean;
+}
+export interface RelatedSetResult {
+    source: RelatedSource;
+    /**
+     * The roles whose rows the set reads, which a list follows for live
+     * changes: a query set's resolved roles in order, or the roles of an item
+     * set's readable reciprocal rows when a column splits by them.
+     */
+    roles?: string[];
+    /** Query sets: role titles, keyed by role. */
+    roleLabels?: Record<string, string>;
+    /** Query sets: declared roles outside the viewer's full read scope. */
+    restricted?: string[];
+    /** Keyed by splitBy ('' when unsplit), then host id. */
+    aggregates: Record<string, Record<string, RelatedHostAggregate>>;
+}
+export interface RelatedAggregatesResponse {
+    version: number | null;
+    sets: Record<string, RelatedSetResult>;
+}
+export interface RelatedItemEntry {
+    itemKey: string;
+    payload?: unknown;
+    at?: string;
+    actor?: string;
+    reciprocalId?: string;
+}
+export interface RelatedRow {
+    /** Items sets only. */
+    item?: RelatedItemEntry;
+    /** The reciprocal row (items) or the related row (query); null when unreadable. */
+    escalation: Record<string, unknown> | null;
+}
+export interface RelatedRowsResponse {
+    source: RelatedSource;
+    rows: RelatedRow[];
+    total: number;
+    restricted?: string[];
+    roleLabels?: Record<string, string>;
+}