@hotmeshio/long-tail 0.24.1 → 0.25.0

package/build/services/escalation/roster.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRosterCounts = loadRosterCounts;
+/**
+ * Server-side roster counts: the API-first counterpart of the dashboard's
+ * roster widget. For each `x-lt-roster` field of a form schema, the member
+ * rows are read with the same query the widget runs and the shared
+ * `computeRoster` turns them into counts, so `roster.*` showIf conditions and
+ * a roster submit guard evaluate at resolve exactly as the form showed them.
+ *
+ * Member rows are read with `global: true`: a resolver who cannot see a
+ * member must never be told the roster is complete.
+ */
+const form_validation_1 = require("../../shared/form-validation");
+const queries_1 = require("./queries");
+/** Each roster field's counts, keyed by field name; empty when the schema declares none. */
+async function loadRosterCounts(schema, ctx) {
+    const defs = (0, form_validation_1.readRosterDefs)(schema);
+    const counts = {};
+    for (const [field, def] of Object.entries(defs)) {
+        counts[field] = (0, form_validation_1.computeRoster)(def, ctx, await readMemberRows(def, ctx)).counts;
+    }
+    return counts;
+}
+async function readMemberRows(def, ctx) {
+    const query = (0, form_validation_1.rosterQueryOf)(def);
+    const scoped = query ? (0, form_validation_1.resolveRosterQuery)(query, ctx) : null;
+    if (!scoped)
+        return [];
+    const { escalations } = await (0, queries_1.searchEscalationsFaceted)({
+        global: true,
+        facet: { roles: scoped.roles, status: scoped.status, facets: scoped.facets },
+        limit: scoped.limit,
+        offset: 0,
+    });
+    return escalations.map((row) => (0, form_validation_1.rosterRowContext)(row));
+}

package/build/services/escalation/submit-guard.d.ts

@@ -15,6 +15,9 @@
  *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
  *    with no resolving user, like an MCP resolve) is skipped here; the consuming
  *    workflow's own verification remains the durable backstop.
+ *
+ * A roster guard reads the counts the caller placed under `ctx.roster`
+ * (services/escalation/roster.ts) and rejects while entries are outstanding.
  */
 import { type ShowIfContext } from '../../shared/form-validation';
 import type { LTFieldViolation } from '../../types/validation';

package/build/services/escalation/submit-guard.js

@@ -19,6 +19,9 @@ exports.checkSubmitGuard = checkSubmitGuard;
  *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
  *    with no resolving user, like an MCP resolve) is skipped here; the consuming
  *    workflow's own verification remains the durable backstop.
+ *
+ * A roster guard reads the counts the caller placed under `ctx.roster`
+ * (services/escalation/roster.ts) and rejects while entries are outstanding.
  */
 const form_validation_1 = require("../../shared/form-validation");
 const queries_1 = require("./queries");
@@ -34,6 +37,10 @@ async function checkSubmitGuard(schema, ctx, resolvingUserId) {
     const guard = (0, form_validation_1.readSubmitGuard)(schema);
     if (!guard || guard.mustBeEmpty === false)
         return null;
+    if (guard.roster)
+        return checkRosterGuard(guard, ctx);
+    if (!guard.query)
+        return null;
     const scoped = (0, form_validation_1.resolveScopedQuery)(guard.query, ctx, resolvingUserId);
     if (!scoped.enabled)
         return null;
@@ -51,7 +58,19 @@ async function checkSubmitGuard(schema, ctx, resolvingUserId) {
     });
     if (total <= 0)
         return null;
-    const template = guard.message ?? form_validation_1.SUBMIT_GUARD_DEFAULT_MESSAGE;
-    const message = (0, form_validation_1.interpolateHelp)(template.replace(/\{\{count\}\}/g, String(total)), ctx);
+    return guardViolation(guard.message ?? form_validation_1.SUBMIT_GUARD_DEFAULT_MESSAGE, total, ctx);
+}
+/** A roster guard: outstanding entries reject; a roster the schema does not declare rejects too. */
+function checkRosterGuard(guard, ctx) {
+    const counts = ctx.roster?.[guard.roster];
+    if (!counts) {
+        return { field: exports.SUBMIT_GUARD_VIOLATION_FIELD, message: `Submit guard names roster "${guard.roster}", which the form does not declare` };
+    }
+    if (counts.outstanding <= 0)
+        return null;
+    return guardViolation(guard.message ?? form_validation_1.ROSTER_GUARD_DEFAULT_MESSAGE, counts.outstanding, ctx);
+}
+function guardViolation(template, count, ctx) {
+    const message = (0, form_validation_1.interpolateHelp)(template.replace(/\{\{count\}\}/g, String(count)), ctx);
     return { field: exports.SUBMIT_GUARD_VIOLATION_FIELD, message };
 }

package/build/services/maintenance/index.js

@@ -107,7 +107,7 @@ async function executeRule(appId, rule) {
             break;
         }
         // Drop the authorization server's dead rows: spent or expired tokens and
-        // codes, grants with neither left or long revoked, clients with no live grant.
+        // codes, grants with neither left or long revoked, clients never consented to.
         case rule.target === 'oauth' && rule.action === 'delete': {
             const { pruneOAuthServer } = await Promise.resolve().then(() => __importStar(require('../auth/oauth-server')));
             const counts = await pruneOAuthServer(rule.olderThan);

package/build/services/mcp/server-tools.js

@@ -225,7 +225,7 @@ function registerHumanQueueTools(server) {
                 isError: true,
             };
         }
-        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, args.metadata);
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, { ...args.metadata, resolved_by: args.resolver_id });
         if (!resolved) {
             return {
                 content: [{

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

@@ -9,6 +9,7 @@ export declare const DISPLAY_ONLY_WIDGET_NAMES: {
     readonly ESCALATION: "escalation";
     readonly ESCALATION_LIST: "escalation-list";
     readonly INVOKE: "invoke";
+    readonly ROSTER: "roster";
 };
 export declare const DISPLAY_ONLY_WIDGETS: ReadonlySet<string>;
 export declare function isDisplayOnlyWidget(name: unknown): boolean;

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

@@ -14,6 +14,7 @@ exports.DISPLAY_ONLY_WIDGET_NAMES = {
     ESCALATION: 'escalation',
     ESCALATION_LIST: 'escalation-list',
     INVOKE: 'invoke',
+    ROSTER: 'roster',
 };
 exports.DISPLAY_ONLY_WIDGETS = new Set(Object.values(exports.DISPLAY_ONLY_WIDGET_NAMES));
 function isDisplayOnlyWidget(name) {

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

@@ -23,3 +23,4 @@ export * from './invoke-context';
 export * from './display-only-widgets';
 export * from './x-lt-invoke';
 export * from './x-lt-scan';
+export * from './x-lt-roster';

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

@@ -39,3 +39,4 @@ __exportStar(require("./invoke-context"), exports);
 __exportStar(require("./display-only-widgets"), exports);
 __exportStar(require("./x-lt-invoke"), exports);
 __exportStar(require("./x-lt-scan"), exports);
+__exportStar(require("./x-lt-roster"), exports);

package/build/shared/form-validation/validate-resolver-payload.d.ts

@@ -9,6 +9,7 @@
  * Semantics per field:
  *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
  *     cannot see never blocks submission)
+ *   - x-lt-hidden fields are never required; a value they carry is checked
  *   - required (schema.required membership), with checklist/empty-object rules
  *   - declared-type check (string/number/integer/boolean/array/object)
  *   - enum membership

package/build/shared/form-validation/validate-resolver-payload.js

@@ -13,6 +13,7 @@ exports.validateResolverPayload = validateResolverPayload;
  * Semantics per field:
  *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
  *     cannot see never blocks submission)
+ *   - x-lt-hidden fields are never required; a value they carry is checked
  *   - required (schema.required membership), with checklist/empty-object rules
  *   - declared-type check (string/number/integer/boolean/array/object)
  *   - enum membership
@@ -50,7 +51,7 @@ function validateResolverForm(schema, formValues, ctx) {
     for (const [field, fieldSchema] of Object.entries(properties)) {
         if (!(0, x_lt_show_if_1.evaluateShowIf)(fieldSchema['x-lt-showIf'], liveCtx))
             continue;
-        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field), true, liveCtx);
+        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field) && !(0, x_lt_show_if_1.isHiddenField)(fieldSchema), true, liveCtx);
         if (err)
             errors.push({ field, message: err });
     }

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

@@ -1,5 +1,5 @@
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input"];
+export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input", "roster"];
 export type HelpDomain = (typeof HELP_DOMAINS)[number];
 export type HelpTokenContext = Partial<Record<HelpDomain, Record<string, unknown> | null>>;
 /** Replace every `{{domain.path}}` token with its value from the context. */

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

@@ -17,6 +17,7 @@ exports.defaultHelpMarkdown = defaultHelpMarkdown;
  *   {{payload.category}}                       — the escalation context payload
  *   {{resolver.notes}}                         — the submitted resolver payload
  *   {{lookup.materials.items}}                 — versioned knowledge lookups pinned on the row
+ *   {{roster.orders.outstanding}}              (a roster field's counts, x-lt-roster.ts)
  *
  * Paths reuse the x-lt-bind syntax (`a.b[0].c`). A missing value renders as an
  * em dash. `x-lt-context` is accepted as the plain-text fallback source when
@@ -24,7 +25,7 @@ exports.defaultHelpMarkdown = defaultHelpMarkdown;
  */
 const x_lt_bind_1 = require("./x-lt-bind");
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input'];
+exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input', 'roster'];
 const TOKEN_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
 const MISSING_VALUE = '—';
 function formatTokenValue(value) {

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

@@ -0,0 +1,92 @@
+import { type HelpTokenContext } from './x-lt-help';
+export declare const X_LT_ROSTER = "x-lt-roster";
+export declare const ROSTER_WIDGET = "roster";
+/** The context domain the counts are read from: `roster.<field>.outstanding`. */
+export declare const ROSTER_DOMAIN = "roster";
+/** The most member rows a query set reads. */
+export declare const ROSTER_QUERY_LIMIT = 200;
+/** The `in` source naming the host row's held keys. */
+export declare const ROSTER_ITEMS_SOURCE = "items";
+/** `query.status` value that reads every status (the default). */
+export declare const ROSTER_ANY_STATUS = "any";
+export declare const ROSTER_STATES: {
+    readonly WAITING: "waiting";
+    readonly IN: "in";
+    readonly FLAGGED: "flagged";
+};
+export type RosterState = (typeof ROSTER_STATES)[keyof typeof ROSTER_STATES];
+export interface RosterQuery {
+    role?: string;
+    roles?: string[];
+    facets?: Record<string, string>;
+    /** A status to narrow to; omitted or `any` reads every status. */
+    status?: string;
+}
+export type RosterExpected = {
+    query: RosterQuery;
+} | {
+    list: string;
+} | {
+    batch: true;
+    labels?: string;
+};
+export interface RosterFlagRule {
+    /** An x-lt-showIf condition over the member row's own context. */
+    when: string | string[];
+    label: string;
+}
+export interface RosterDef {
+    expected: RosterExpected;
+    key?: string;
+    in?: string[];
+    flagged?: RosterFlagRule[];
+}
+/** One member row's token context (the row's own domains). */
+export type RosterRow = HelpTokenContext & {
+    escalation: Record<string, unknown>;
+};
+export interface RosterEntry {
+    key: string;
+    state: RosterState;
+    /** The matching flag rule's label, when flagged. */
+    flag?: string;
+    /** The member row, for a query set. */
+    row?: RosterRow;
+    /** The per-key label value from a batch's `labels` map. */
+    label?: unknown;
+}
+export interface RosterCounts {
+    expected: number;
+    in: number;
+    flagged: number;
+    waiting: number;
+    /** Entries neither in nor flagged: the count a roster guard waits on. */
+    outstanding: number;
+}
+export interface RosterResult {
+    entries: RosterEntry[];
+    counts: RosterCounts;
+}
+/** The field's roster declaration, or undefined when it declares none or an unusable one. */
+export declare function readRosterDef(fieldSchema: Record<string, unknown> | null | undefined): RosterDef | undefined;
+/** Every roster field of a form schema, by field name. */
+export declare function readRosterDefs(schema: Record<string, unknown> | null | undefined): Record<string, RosterDef>;
+/** The roster's member-row query, or null when its set is not a query. */
+export declare function rosterQueryOf(def: RosterDef): RosterQuery | null;
+/** The query's concrete params: facets interpolated, `any` status dropped. Null when the scope is empty. */
+export declare function resolveRosterQuery(query: RosterQuery, ctx: HelpTokenContext): {
+    roles?: string[];
+    facets: Record<string, string>;
+    status?: string;
+    limit: number;
+} | null;
+/** A member row's token context, from a row whose JSON columns are strings or objects. */
+export declare function rosterRowContext(row: Record<string, unknown>): RosterRow;
+/**
+ * Every expected entry with its state, and the counts. `rows` are the
+ * member rows a query set read (ignored for list and batch sets). `ctx` is
+ * the host row's context with the live form values under `resolver`.
+ */
+export declare function computeRoster(def: RosterDef, ctx: HelpTokenContext, rows?: RosterRow[]): RosterResult;
+/** The header line: "3 of 5 in · 1 Missing". */
+export declare function rosterHeadline(result: RosterResult): string;

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

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROSTER_STATES = exports.ROSTER_ANY_STATUS = exports.ROSTER_ITEMS_SOURCE = exports.ROSTER_QUERY_LIMIT = exports.ROSTER_DOMAIN = exports.ROSTER_WIDGET = exports.X_LT_ROSTER = void 0;
+exports.readRosterDef = readRosterDef;
+exports.readRosterDefs = readRosterDefs;
+exports.rosterQueryOf = rosterQueryOf;
+exports.resolveRosterQuery = resolveRosterQuery;
+exports.rosterRowContext = rosterRowContext;
+exports.computeRoster = computeRoster;
+exports.rosterHeadline = rosterHeadline;
+/**
+ * x-lt-roster: every member a container row expects, each with its state.
+ * A form field declares `x-lt-widget: "roster"` and an `x-lt-roster` block:
+ *
+ *   "x-lt-roster": {
+ *     "expected": { "query": { "roles": ["packing"], "facets": { "box": "{{escalation.id}}" } } },
+ *     "key": "{{metadata.orderId}}",
+ *     "in": ["items", "resolver.bags"],
+ *     "flagged": [{ "when": "resolver.outcome=missing", "label": "Missing" }]
+ *   }
+ *
+ * The expected set is one of:
+ *   - `query`: member rows matched by role(s) and facets, any status unless
+ *     `status` narrows it. `key` names each row's entry (default its id).
+ *   - `list`: a `domain.path` naming an array of keys on the host row.
+ *   - `batch`: the host row's batch keys; `labels` names a per-key map.
+ *
+ * An entry is `in` when its key is held by the host row (`items`: the
+ * accumulated keys, or a batch's filled keys) or appears in a named context
+ * value (`resolver.<field>`, a string or an array). It is `flagged` when its
+ * member row matches a `flagged` rule, and `waiting` otherwise. In wins over
+ * flagged, so a member flagged on its own row and then added reads in.
+ *
+ * Isomorphic: the dashboard renders the widget and the form's `roster.*`
+ * context from it, and the API layer computes the same counts to evaluate
+ * showIf and the roster submit guard at resolve.
+ */
+const x_lt_bind_1 = require("./x-lt-bind");
+const ctx_path_1 = require("./ctx-path");
+const x_lt_help_1 = require("./x-lt-help");
+const x_lt_show_if_1 = require("./x-lt-show-if");
+exports.X_LT_ROSTER = 'x-lt-roster';
+exports.ROSTER_WIDGET = 'roster';
+/** The context domain the counts are read from: `roster.<field>.outstanding`. */
+exports.ROSTER_DOMAIN = 'roster';
+/** The most member rows a query set reads. */
+exports.ROSTER_QUERY_LIMIT = 200;
+/** The `in` source naming the host row's held keys. */
+exports.ROSTER_ITEMS_SOURCE = 'items';
+/** `query.status` value that reads every status (the default). */
+exports.ROSTER_ANY_STATUS = 'any';
+exports.ROSTER_STATES = { WAITING: 'waiting', IN: 'in', FLAGGED: 'flagged' };
+const DEFAULT_KEY = '{{escalation.id}}';
+const MISSING = '—';
+const BATCH_KEYS = 'batch_keys';
+const BATCH_PENDING = 'batch_pending';
+const ACCUMULATE_KEYS = 'accumulate_keys';
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function strings(v) {
+    if (typeof v === 'string')
+        return v ? [v] : [];
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((s) => typeof s === 'string' && s.length > 0);
+}
+/** The field's roster declaration, or undefined when it declares none or an unusable one. */
+function readRosterDef(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_ROSTER];
+    if (!isRecord(raw) || !isRecord(raw.expected))
+        return undefined;
+    const e = raw.expected;
+    const hasSource = isRecord(e.query) || typeof e.list === 'string' || e.batch === true;
+    return hasSource ? raw : undefined;
+}
+/** Every roster field of a form schema, by field name. */
+function readRosterDefs(schema) {
+    const properties = isRecord(schema?.properties) ? schema.properties : {};
+    const defs = {};
+    for (const [field, def] of Object.entries(properties)) {
+        const roster = isRecord(def) ? readRosterDef(def) : undefined;
+        if (roster)
+            defs[field] = roster;
+    }
+    return defs;
+}
+/** The roster's member-row query, or null when its set is not a query. */
+function rosterQueryOf(def) {
+    return 'query' in def.expected && isRecord(def.expected.query) ? def.expected.query : null;
+}
+/** The query's concrete params: facets interpolated, `any` status dropped. Null when the scope is empty. */
+function resolveRosterQuery(query, ctx) {
+    const facets = {};
+    for (const [k, v] of Object.entries(query.facets ?? {})) {
+        if (typeof v !== 'string')
+            continue;
+        const resolved = (0, x_lt_help_1.interpolateHelp)(v, ctx);
+        if (!resolved || resolved === MISSING)
+            return null;
+        facets[k] = resolved;
+    }
+    const roles = [...(query.role ? [query.role] : []), ...strings(query.roles)];
+    if (!roles.length && !Object.keys(facets).length)
+        return null;
+    const status = query.status && query.status !== exports.ROSTER_ANY_STATUS ? query.status : undefined;
+    return { ...(roles.length ? { roles } : {}), facets, ...(status ? { status } : {}), limit: exports.ROSTER_QUERY_LIMIT };
+}
+function parseJson(v) {
+    if (isRecord(v))
+        return v;
+    if (typeof v !== 'string' || !v)
+        return null;
+    try {
+        const parsed = JSON.parse(v);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A member row's token context, from a row whose JSON columns are strings or objects. */
+function rosterRowContext(row) {
+    return {
+        escalation: row,
+        metadata: isRecord(row.metadata) ? row.metadata : parseJson(row.metadata),
+        envelope: parseJson(row.envelope),
+        payload: parseJson(row.escalation_payload),
+        resolver: parseJson(row.resolver_payload),
+    };
+}
+/** The keys the host row holds: its accumulated keys, or a batch's filled keys. */
+function heldKeys(ctx) {
+    const metadata = ctx.metadata ?? {};
+    const accumulated = metadata[ACCUMULATE_KEYS];
+    if (Array.isArray(accumulated))
+        return new Set(strings(accumulated));
+    const envelopeItems = (0, x_lt_bind_1.getDeep)(ctx.envelope, 'accumulate_items');
+    if (isRecord(envelopeItems))
+        return new Set(Object.keys(envelopeItems));
+    if (Array.isArray(metadata[BATCH_PENDING])) {
+        const pending = new Set(strings(metadata[BATCH_PENDING]));
+        return new Set(strings(metadata[BATCH_KEYS]).filter((k) => !pending.has(k)));
+    }
+    return new Set();
+}
+function arrivedKeys(def, ctx) {
+    const arrived = new Set();
+    for (const source of def.in ?? [exports.ROSTER_ITEMS_SOURCE]) {
+        const keys = source === exports.ROSTER_ITEMS_SOURCE
+            ? [...heldKeys(ctx)]
+            : strings((0, ctx_path_1.resolveCtxPath)(source, ctx));
+        keys.forEach((k) => arrived.add(k));
+    }
+    return arrived;
+}
+function flagFor(def, row) {
+    if (!row)
+        return undefined;
+    for (const rule of def.flagged ?? []) {
+        const conditions = strings(rule.when);
+        if (!conditions.length || typeof rule.label !== 'string')
+            continue;
+        if ((0, x_lt_show_if_1.evaluateShowIf)(conditions, row))
+            return rule.label;
+    }
+    return undefined;
+}
+/** The expected keys in order, each with its member row (query) or label (batch). */
+function expectedEntries(def, ctx, rows) {
+    const seen = new Set();
+    const out = [];
+    const push = (key, extra = {}) => {
+        if (!key || key === MISSING || seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ key, ...extra });
+    };
+    const e = def.expected;
+    if ('query' in e) {
+        const template = def.key ?? DEFAULT_KEY;
+        for (const row of rows)
+            push((0, x_lt_help_1.interpolateHelp)(template, row), { row });
+    }
+    else if ('list' in e) {
+        strings((0, ctx_path_1.resolveCtxPath)(e.list, ctx)).forEach((k) => push(k));
+    }
+    else {
+        const labels = e.labels ? (0, ctx_path_1.resolveCtxPath)(e.labels, ctx) : undefined;
+        for (const key of strings(ctx.metadata?.[BATCH_KEYS])) {
+            push(key, isRecord(labels) && key in labels ? { label: labels[key] } : {});
+        }
+    }
+    return out;
+}
+/**
+ * Every expected entry with its state, and the counts. `rows` are the
+ * member rows a query set read (ignored for list and batch sets). `ctx` is
+ * the host row's context with the live form values under `resolver`.
+ */
+function computeRoster(def, ctx, rows = []) {
+    const arrived = arrivedKeys(def, ctx);
+    const entries = expectedEntries(def, ctx, rows).map((e) => {
+        if (arrived.has(e.key))
+            return { ...e, state: exports.ROSTER_STATES.IN };
+        const flag = flagFor(def, e.row);
+        return flag ? { ...e, state: exports.ROSTER_STATES.FLAGGED, flag } : { ...e, state: exports.ROSTER_STATES.WAITING };
+    });
+    const count = (s) => entries.filter((e) => e.state === s).length;
+    const waiting = count(exports.ROSTER_STATES.WAITING);
+    return {
+        entries,
+        counts: {
+            expected: entries.length,
+            in: count(exports.ROSTER_STATES.IN),
+            flagged: count(exports.ROSTER_STATES.FLAGGED),
+            waiting,
+            outstanding: waiting,
+        },
+    };
+}
+/** The header line: "3 of 5 in · 1 Missing". */
+function rosterHeadline(result) {
+    const { counts } = result;
+    const parts = [`${counts.in} of ${counts.expected} in`];
+    const byFlag = new Map();
+    for (const e of result.entries) {
+        if (e.state === exports.ROSTER_STATES.FLAGGED && e.flag)
+            byFlag.set(e.flag, (byFlag.get(e.flag) ?? 0) + 1);
+    }
+    for (const [flag, n] of byFlag)
+        parts.push(`${n} ${flag}`);
+    return parts.join(' · ');
+}

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

@@ -11,3 +11,11 @@ export declare function evaluateShowIf(condition: unknown, ctx: ShowIfContext |
  * (null, undefined, '', false, or 0). Render and validation share this test.
  */
 export declare function isHiddenIfEmpty(fieldSchema: Record<string, unknown> | undefined, value: unknown): boolean;
+/**
+ * `x-lt-hidden: true`: the field never renders. A value set by the caller
+ * (a workflow default, an API submitter) passes through to the payload and
+ * is checked against the field's type and enum; the field is never required,
+ * since no one on the form can answer it.
+ */
+export declare const X_LT_HIDDEN = "x-lt-hidden";
+export declare function isHiddenField(fieldSchema: Record<string, unknown> | undefined): boolean;

package/build/shared/form-validation/x-lt-show-if.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_HIDDEN = void 0;
 exports.evaluateShowIf = evaluateShowIf;
 exports.isHiddenIfEmpty = isHiddenIfEmpty;
+exports.isHiddenField = isHiddenField;
 /**
  * x-lt-showIf — conditional field visibility. A form_schema property may
  * declare `x-lt-showIf: "domain.path"` to show the field only when the value
@@ -21,6 +23,7 @@ exports.isHiddenIfEmpty = isHiddenIfEmpty;
  *   envelope   — the workflow-sent input envelope
  *   escalation — top-level escalation row fields
  *   resolver   — the submitted resolver payload
+ *   roster     (each roster field's counts: `roster.orders.outstanding=0`)
  *
  * A missing or non-string condition always shows the field (opt-in, safe default).
  */
@@ -95,3 +98,13 @@ function isHiddenIfEmpty(fieldSchema, value) {
         return false;
     return value === null || value === undefined || value === '' || value === false || value === 0;
 }
+/**
+ * `x-lt-hidden: true`: the field never renders. A value set by the caller
+ * (a workflow default, an API submitter) passes through to the payload and
+ * is checked against the field's type and enum; the field is never required,
+ * since no one on the form can answer it.
+ */
+exports.X_LT_HIDDEN = 'x-lt-hidden';
+function isHiddenField(fieldSchema) {
+    return fieldSchema?.[exports.X_LT_HIDDEN] === true;
+}

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

@@ -23,11 +23,23 @@
  * `autoResolveWhenEmpty` closes the loop: the moment the query is confirmed
  * empty, the claimed parent auto-submits — checked on page-load and after each
  * inline child-resolve — so a set of escalations completes with no extra click.
+ *
+ * A guard may name a roster field instead of a query: the resolve waits while
+ * that roster has outstanding entries (x-lt-roster.ts), so the list the person
+ * works from and the rule that holds the submit are one computation.
+ *
+ *   "x-lt-submit-guard": { "roster": "orders",
+ *                          "message": "{{count}} orders are still unaccounted for" }
+ *
+ * `{{count}}` is the outstanding count. A roster guard never auto-submits.
  */
 import type { EmbedQuery } from './x-lt-query';
 export declare const X_LT_SUBMIT_GUARD = "x-lt-submit-guard";
 export interface SubmitGuardDef {
-    query: EmbedQuery;
+    /** The embedded query that must be empty; absent for a roster guard. */
+    query?: EmbedQuery;
+    /** A roster field whose outstanding entries hold the resolve. */
+    roster?: string;
     /** The gate condition; defaults to true (the only supported mode today). */
     mustBeEmpty?: boolean;
     /** Shown beside the disabled submit. `{{count}}` and `{{domain.path}}` tokens interpolate. */
@@ -36,6 +48,7 @@ export interface SubmitGuardDef {
     autoResolveWhenEmpty?: boolean;
 }
 export declare const SUBMIT_GUARD_DEFAULT_MESSAGE = "{{count}} related items are still pending";
+export declare const ROSTER_GUARD_DEFAULT_MESSAGE = "{{count}} expected items are still outstanding";
 /** The schema's submit-guard, or undefined when it declares none. */
 export declare function readSubmitGuard(schema: Record<string, unknown> | null | undefined): SubmitGuardDef | undefined;
 /**

package/build/shared/form-validation/x-lt-submit-guard.js

@@ -1,16 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
+exports.ROSTER_GUARD_DEFAULT_MESSAGE = exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
 exports.readSubmitGuard = readSubmitGuard;
 exports.guardBlocks = guardBlocks;
 exports.X_LT_SUBMIT_GUARD = 'x-lt-submit-guard';
 exports.SUBMIT_GUARD_DEFAULT_MESSAGE = '{{count}} related items are still pending';
+exports.ROSTER_GUARD_DEFAULT_MESSAGE = '{{count}} expected items are still outstanding';
 /** The schema's submit-guard, or undefined when it declares none. */
 function readSubmitGuard(schema) {
     const raw = schema?.[exports.X_LT_SUBMIT_GUARD];
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return undefined;
     const guard = raw;
+    if (typeof guard.roster === 'string' && guard.roster)
+        return guard;
     if (!guard.query || typeof guard.query !== 'object')
         return undefined;
     return guard;

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

@@ -0,0 +1,19 @@
+import { RELATED_AGGREGATES, type RelatedAggregate, type RelatedColumnDecl } from './types';
+export type RelatedExtreme = typeof RELATED_AGGREGATES.MIN | typeof RELATED_AGGREGATES.MAX;
+/** True for the aggregates that pick one value rather than count. */
+export declare function isExtremeAggregate(aggregate: unknown): aggregate is RelatedExtreme;
+/**
+ * The stored path a min/max `value` template reads: `payload.<path>` for an
+ * items set, `metadata.<key>` for a query set. Null when the template does
+ * not fit the set's source.
+ */
+export declare function relatedValuePath(source: string, value: unknown): string | null;
+/** The key a column's per-host aggregates are stored under in its set's result. */
+export declare function relatedAggregateKey(col: Pick<RelatedColumnDecl, 'aggregate' | 'splitBy' | 'value'>, source: string): string;
+/** A count column's display text, or null when the column declares none for this count. */
+export declare function relatedCountText(display: Record<string, string> | undefined, count: number): string | null;
+/**
+ * The least or greatest of several values: numbers when every value is a
+ * number, otherwise text in code-unit order (ISO instants order as text).
+ */
+export declare function foldExtreme(fold: RelatedAggregate, values: Array<string | number>): string | number | undefined;