@hotmeshio/long-tail 0.24.2 → 0.25.0

package/build/api/escalations/accumulate.js

@@ -177,6 +177,10 @@ async function gateReciprocal(input, auth) {
     }
     return { reciprocal: { id: row.id, payload: input.payload } };
 }
+/** The reciprocal of an add, stamped with who added it, as the container is. */
+function completedBy(reciprocal, userId) {
+    return reciprocal ? { ...reciprocal, metadata: { resolved_by: userId } } : undefined;
+}
 /** Validates the item payload against the container's versioned role form. */
 async function gatePayload(escalation, payload, userId) {
     if (payload === undefined)
@@ -245,7 +249,7 @@ async function accumulateItem(input, auth) {
             actor: initiator.actor,
             assertClaim: input.assertClaim ? auth.userId : undefined,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
-            reciprocal: reciprocal.reciprocal,
+            reciprocal: completedBy(reciprocal.reciprocal, auth.userId),
         });
         return accumulateOutcomeResult(result, itemKey, escalation.workflow_id);
     }
@@ -291,7 +295,7 @@ async function accumulateItemBySignalKey(input, auth) {
             metadata: { ...metadata, resolved_by: auth.userId },
             actor: initiator.actor,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
-            reciprocal: reciprocal.reciprocal,
+            reciprocal: completedBy(reciprocal.reciprocal, auth.userId),
         });
         return accumulateOutcomeResult(result, itemKey, escalation.workflow_id);
     }
@@ -344,7 +348,7 @@ async function accumulateItemByMetadata(input, auth) {
                 actor: initiator.actor,
                 resolvedBy,
                 roles: allowedRoles ?? undefined,
-                reciprocal: reciprocal.reciprocal,
+                reciprocal: completedBy(reciprocal.reciprocal, auth.userId),
             });
             if (result.outcome === 'not-found')
                 return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
@@ -364,7 +368,7 @@ async function accumulateItemByMetadata(input, auth) {
             metadata: outcome,
             actor: initiator.actor,
             resolvedBy,
-            reciprocal: reciprocal.reciprocal,
+            reciprocal: completedBy(reciprocal.reciprocal, auth.userId),
         });
         if (result.outcome === 'not-found') {
             return { status: 409, error: 'A concurrent change is already in progress for this escalation' };

package/build/api/escalations/metadata.js

@@ -175,12 +175,13 @@ async function resolveByMetadata(input, auth) {
         // writing; the payload validates here, then a second asserted pass claims
         // + resolves the same row with pending re-checked inside the statement.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, input.assertId ?? null, input.extraFacets, input.availability);
+        const outcome = { ...input.metadata, resolved_by: auth.userId };
+        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, outcome, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, input.assertId ?? null, input.extraFacets, input.availability);
         if (result.outcome === 'validation_required' && result.row) {
             const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload, undefined, resolveUserId);
             if (report)
                 return (0, resolve_1.validationFailure)(report);
-            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets, input.availability);
+            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, outcome, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets, input.availability);
             // The asserted row left pending between the two passes — a concurrent
             // resolution won the row; surface it as the conflict it is.
             if (result.outcome === 'not_found') {
@@ -199,7 +200,7 @@ async function resolveByMetadata(input, auth) {
         // Atomic conditional escalation (signal_key set) — SDK resolve atomically marks
         // resolved AND delivers the signal to the waiting condition(), resuming the workflow.
         if (result.signalKey) {
-            const resolved = await escalationService.resolveEscalation(result.escalationId, input.resolverPayload);
+            const resolved = await escalationService.resolveEscalation(result.escalationId, input.resolverPayload, outcome);
             if (!resolved) {
                 return { status: 409, error: 'Escalation not available for resolution' };
             }

package/build/api/escalations/related.d.ts

@@ -1,7 +1,7 @@
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /**
  * Aggregate every related set the role's list schema declares, for one page
- * of host rows. One statement per (set, split) pair, whatever the page size.
+ * of host rows. One statement per (set, aggregate) pair, whatever the page size.
  */
 export declare function getRelatedAggregates(input: {
     role: string;

package/build/api/escalations/related.js

@@ -84,16 +84,24 @@ async function resolveQueryRoles(query, readScope) {
     const restricted = readScope.global ? [] : roles.filter((r) => !readScope.allRoles.includes(r));
     return { roles, roleLabels, restricted };
 }
-/** The split paths the declared columns ask of one set ('' when unsplit). */
-function splitsFor(relations, set) {
-    const splits = new Set(relations.columns.filter((c) => c.related === set).map((c) => c.splitBy ?? ''));
-    if (!splits.size)
-        splits.add('');
-    return [...splits];
+/** The distinct aggregates the declared columns ask of one set; an unsplit count when none does. */
+function asksFor(relations, set, source) {
+    const asks = new Map();
+    for (const col of relations.columns.filter((c) => c.related === set)) {
+        const key = (0, list_schema_1.relatedAggregateKey)(col, source);
+        if (asks.has(key))
+            continue;
+        asks.set(key, (0, list_schema_1.isExtremeAggregate)(col.aggregate)
+            ? { key, extreme: { fold: col.aggregate, path: (0, list_schema_1.relatedValuePath)(source, col.value) } }
+            : { key, ...(col.splitBy ? { splitBy: col.splitBy } : {}) });
+    }
+    if (!asks.size)
+        asks.set('', { key: '' });
+    return [...asks.values()];
 }
 /**
  * Aggregate every related set the role's list schema declares, for one page
- * of host rows. One statement per (set, split) pair, whatever the page size.
+ * of host rows. One statement per (set, aggregate) pair, whatever the page size.
  */
 async function getRelatedAggregates(input, auth) {
     try {
@@ -118,11 +126,13 @@ async function getRelatedAggregates(input, auth) {
             const result = { source: decl.source, aggregates: {} };
             if (decl.source === list_schema_1.RELATED_SOURCES.ITEMS) {
                 const roles = new Set();
-                for (const splitBy of splitsFor(relations, name)) {
-                    const read = await escalationService.aggregateRelatedItems({
-                        hostIds, scope, splitBy: splitBy || undefined,
-                    });
-                    result.aggregates[splitBy] = read.aggregates;
+                for (const ask of asksFor(relations, name, decl.source)) {
+                    if (ask.extreme) {
+                        result.aggregates[ask.key] = await escalationService.extremeRelatedItems({ hostIds, scope, ...ask.extreme });
+                        continue;
+                    }
+                    const read = await escalationService.aggregateRelatedItems({ hostIds, scope, splitBy: ask.splitBy });
+                    result.aggregates[ask.key] = read.aggregates;
                     read.roles.forEach((r) => roles.add(r));
                 }
                 if (roles.size)
@@ -142,14 +152,14 @@ async function getRelatedAggregates(input, auth) {
                     else
                         unresolved.push(host.id);
                 }
-                for (const splitBy of splitsFor(relations, name)) {
-                    const agg = await escalationService.aggregateRelatedQuery({
-                        hosts: matched, roles: resolved.roles, status: decl.query.status ?? DEFAULT_STATUS, scope,
-                        splitBy: splitBy || undefined,
-                    });
+                for (const ask of asksFor(relations, name, decl.source)) {
+                    const query = { hosts: matched, roles: resolved.roles, status: decl.query.status ?? DEFAULT_STATUS, scope };
+                    const agg = ask.extreme
+                        ? await escalationService.extremeRelatedQuery({ ...query, ...ask.extreme })
+                        : await escalationService.aggregateRelatedQuery({ ...query, splitBy: ask.splitBy });
                     for (const id of unresolved)
                         agg[id] = { count: 0, unresolved: true };
-                    result.aggregates[splitBy] = agg;
+                    result.aggregates[ask.key] = agg;
                 }
             }
             data.sets[name] = result;

package/build/services/escalation/accumulate.d.ts

@@ -8,6 +8,8 @@ export interface AccumulateReciprocal {
     roles?: string[];
     /** Stored as the reciprocal entry's payload. */
     payload?: Record<string, any>;
+    /** Merge patch for the reciprocal row's metadata, same statement. */
+    metadata?: Record<string, any>;
 }
 export interface AccumulateItemInput {
     itemKey: string;
@@ -43,7 +45,7 @@ export interface AccumulateItemServiceOutcome {
 export interface RemoveItemInput {
     itemKey: string;
     actor?: string;
-    reciprocal?: Omit<AccumulateReciprocal, 'payload'>;
+    reciprocal?: Omit<AccumulateReciprocal, 'payload' | 'metadata'>;
 }
 export interface RemoveItemServiceOutcome {
     outcome: RemoveAccumulatedItemOutcome;

package/build/services/escalation/facet-sql.js

@@ -13,7 +13,9 @@ exports.buildFacetOrder = buildFacetOrder;
 exports.buildGroupOrder = buildGroupOrder;
 // Top-level columns a caller may sort/range on directly. Anything else must be a
 // `metadata.<key>` facet. Keeps interpolation to a fixed, audited set.
-const ORDER_COLUMNS = new Set(['priority', 'created_at', 'updated_at', 'status', 'role']);
+const ORDER_COLUMNS = new Set(['priority', 'created_at', 'updated_at', 'resolved_at', 'status', 'role']);
+// Columns a pending row leaves empty: they sort after every value, either direction.
+const NULLABLE_ORDER_COLUMNS = new Set(['resolved_at']);
 const RANGE_OPS = new Set(['<', '<=', '>', '>=', '=']);
 // Metadata keys are interpolated (as a JSON path), so they are strictly validated.
 // Exported so role config (priority_facet) validates keys against the same rule.
@@ -140,7 +142,7 @@ function buildFacetOrder(orderBy) {
     for (const o of orderBy) {
         const dir = o.direction === 'desc' ? 'DESC' : 'ASC';
         if (ORDER_COLUMNS.has(o.field)) {
-            parts.push(`${o.field} ${dir}`);
+            parts.push(`${o.field} ${dir}${NULLABLE_ORDER_COLUMNS.has(o.field) ? ' NULLS LAST' : ''}`);
         }
         else if (o.field.startsWith('metadata.')) {
             const key = o.field.slice('metadata.'.length);

package/build/services/escalation/index.d.ts

@@ -14,3 +14,4 @@ export { searchEscalationsGrouped } from './grouped-list';
 export type { EscalationGroup } from './grouped-list';
 export { aggregateRelatedItems, listRelatedItems, aggregateRelatedQuery, listRelatedQueryRows, readRelatedHosts, } from './related';
 export type { RelatedQueryHost } from './related';
+export { extremeRelatedItems, extremeRelatedQuery } from './related-extremes';

package/build/services/escalation/index.js

@@ -14,7 +14,7 @@ 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.readRelatedHosts = exports.listRelatedQueryRows = exports.aggregateRelatedQuery = exports.listRelatedItems = exports.aggregateRelatedItems = exports.searchEscalationsGrouped = exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
+exports.extremeRelatedQuery = exports.extremeRelatedItems = exports.readRelatedHosts = exports.listRelatedQueryRows = exports.aggregateRelatedQuery = exports.listRelatedItems = exports.aggregateRelatedItems = exports.searchEscalationsGrouped = exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 var claim_asserted_1 = require("./claim-asserted");
@@ -48,3 +48,6 @@ Object.defineProperty(exports, "listRelatedItems", { enumerable: true, get: func
 Object.defineProperty(exports, "aggregateRelatedQuery", { enumerable: true, get: function () { return related_1.aggregateRelatedQuery; } });
 Object.defineProperty(exports, "listRelatedQueryRows", { enumerable: true, get: function () { return related_1.listRelatedQueryRows; } });
 Object.defineProperty(exports, "readRelatedHosts", { enumerable: true, get: function () { return related_1.readRelatedHosts; } });
+var related_extremes_1 = require("./related-extremes");
+Object.defineProperty(exports, "extremeRelatedItems", { enumerable: true, get: function () { return related_extremes_1.extremeRelatedItems; } });
+Object.defineProperty(exports, "extremeRelatedQuery", { enumerable: true, get: function () { return related_extremes_1.extremeRelatedQuery; } });

package/build/services/escalation/related-extremes.d.ts

@@ -0,0 +1,17 @@
+import { type RelatedExtreme, type RelatedHostAggregate } from '../../shared/list-schema';
+import { type RelatedQueryInput } from './related';
+import type { ReadScopeInput } from './read-scope-sql';
+type Aggregates = Record<string, RelatedHostAggregate>;
+/** The least or greatest `payload.<path>` among each host's items. */
+export declare function extremeRelatedItems(opts: {
+    hostIds: string[];
+    scope: ReadScopeInput;
+    fold: RelatedExtreme;
+    path: string;
+}): Promise<Aggregates>;
+/** The least or greatest `metadata.<key>` among the rows sharing each host's facets. */
+export declare function extremeRelatedQuery(input: RelatedQueryInput & {
+    fold: RelatedExtreme;
+    path: string;
+}): Promise<Aggregates>;
+export {};

package/build/services/escalation/related-extremes.js

@@ -0,0 +1,65 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// min/max over a related set: the least or greatest item payload value, or
+// related row metadata value, per host. One statement per (set, value) pair,
+// under the same read scope as the set's counts.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extremeRelatedItems = extremeRelatedItems;
+exports.extremeRelatedQuery = extremeRelatedQuery;
+const db_1 = require("../../lib/db");
+const list_schema_1 = require("../../shared/list-schema");
+const client_1 = require("./client");
+const related_1 = require("./related");
+const NUMBER_TEXT = '^-?[0-9]+(\\.[0-9]+)?([eE][-+]?[0-9]+)?$';
+/**
+ * Per host: how many values, whether every one is numeric, and the extreme
+ * as a number and as text. `v` is the jsonb value; objects, arrays, nulls and
+ * blanks are not values. Text compares in code-unit order, as the dashboard folds.
+ */
+function extremeSelect(fold, hostId, v, from) {
+    const fn = fold === list_schema_1.RELATED_AGGREGATES.MIN ? 'min' : 'max';
+    return `SELECT host_id, count(*)::int AS n, bool_and(t ~ '${NUMBER_TEXT}') AS numeric,
+       ${fn}(CASE WHEN t ~ '${NUMBER_TEXT}' THEN t::numeric END)::text AS num,
+       ${fn}(t COLLATE "C") AS txt
+     FROM (SELECT h_id AS host_id, x #>> '{}' AS t
+       FROM (SELECT ${hostId}::text AS h_id, ${v} AS x ${from}) raw
+       WHERE jsonb_typeof(x) IN ('string', 'number', 'boolean') AND x #>> '{}' <> '') vals
+     GROUP BY host_id`;
+}
+function foldExtremeRows(rows, hostIds) {
+    const out = {};
+    for (const id of hostIds)
+        out[id] = { count: 0 };
+    for (const row of rows) {
+        if (!out[row.host_id])
+            continue;
+        const value = row.numeric && row.num !== null ? Number(row.num) : row.txt;
+        out[row.host_id] = value === null ? { count: row.n } : { count: row.n, value };
+    }
+    return out;
+}
+/** The least or greatest `payload.<path>` among each host's items. */
+async function extremeRelatedItems(opts) {
+    if (!opts.hostIds.length)
+        return {};
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const cte = (0, related_1.itemEntriesCte)(params, opts.scope, opts.hostIds);
+    const pi = params.push(opts.path.slice(list_schema_1.SPLIT_PATHS.PAYLOAD.length).split('.'));
+    const v = `(CASE WHEN en.acc THEN en.entry->'payload' ELSE en.entry END) #> $${pi}::text[]`;
+    const { rows } = await (0, db_1.getPool)().query(`WITH ${cte} ${extremeSelect(opts.fold, 'en.host_id', v, 'FROM entries en')}`, params);
+    return foldExtremeRows(rows, opts.hostIds);
+}
+/** The least or greatest `metadata.<key>` among the rows sharing each host's facets. */
+async function extremeRelatedQuery(input) {
+    const hostIds = input.hosts.map((h) => h.hostId);
+    if (!hostIds.length || !input.roles.length)
+        return foldExtremeRows([], hostIds);
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const from = (0, related_1.querySetFrom)(params, input);
+    const ki = params.push(input.path.slice(list_schema_1.SPLIT_PATHS.METADATA.length));
+    const { rows } = await (0, db_1.getPool)().query(extremeSelect(input.fold, 'h.host_id', `e.metadata->$${ki}`, from), params);
+    return foldExtremeRows(rows, hostIds);
+}

package/build/services/escalation/related.d.ts

@@ -12,6 +12,8 @@ export interface RelatedQueryInput {
     scope: ReadScopeInput;
 }
 type Aggregates = Record<string, RelatedHostAggregate>;
+/** The hosts and their item entries, read under the caller's scope. */
+export declare function itemEntriesCte(params: unknown[], scope: ReadScopeInput, hostIds: string[]): string;
 /**
  * Count each host's items, optionally split by `payload.<path>` or
  * `reciprocal.metadata.<key>`. A reciprocal split counts only reciprocal rows
@@ -35,6 +37,8 @@ export declare function listRelatedItems(opts: {
     rows: RelatedRow[];
     total: number;
 }>;
+/** The shared FROM/WHERE of a query set: hosts unnested beside their matches. */
+export declare function querySetFrom(params: unknown[], input: RelatedQueryInput): string;
 /**
  * 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.

package/build/services/escalation/related.js

@@ -7,8 +7,10 @@
 // the page size or the item count.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.itemEntriesCte = itemEntriesCte;
 exports.aggregateRelatedItems = aggregateRelatedItems;
 exports.listRelatedItems = listRelatedItems;
+exports.querySetFrom = querySetFrom;
 exports.aggregateRelatedQuery = aggregateRelatedQuery;
 exports.listRelatedQueryRows = listRelatedQueryRows;
 exports.readRelatedHosts = readRelatedHosts;

package/build/services/escalation/resolver-validation.js

@@ -23,6 +23,7 @@ exports.toValidationErrorBody = toValidationErrorBody;
  */
 const form_validation_1 = require("../../shared/form-validation");
 const submit_guard_1 = require("./submit-guard");
+const roster_1 = require("./roster");
 const enforcement_cache_1 = require("../role/enforcement-cache");
 const knowledge_1 = require("../knowledge");
 const escalation_1 = require("../../types/escalation");
@@ -85,6 +86,12 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, r
         payload: parseJsonOrNull(escalation.escalation_payload),
         ...(lookup ? { lookup } : {}),
     };
+    // Roster counts read the submitted form values (an `in` source may name a
+    // form field), then join the context so showIf and the guard see them.
+    const formValues = (0, form_validation_1.mapPayloadToForm)(resolverPayload, schema);
+    const roster = await (0, roster_1.loadRosterCounts)(schema, { ...ctx, resolver: formValues, input: formValues });
+    if (Object.keys(roster).length)
+        ctx.roster = roster;
     const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, ctx);
     // The query precondition (x-lt-submit-guard): reject while the embedded query
     // still returns rows. Enforced on the same enforce_schema opt-in as the field

package/build/services/escalation/roster.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+import { type RosterCounts, type ShowIfContext } from '../../shared/form-validation';
+/** Each roster field's counts, keyed by field name; empty when the schema declares none. */
+export declare function loadRosterCounts(schema: Record<string, unknown> | null | undefined, ctx: ShowIfContext): Promise<Record<string, RosterCounts>>;

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/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) {