@hotmeshio/long-tail 0.31.0 → 0.32.0

package/build/services/escalation/aggregate-resolved-sql.js

@@ -0,0 +1,57 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// The resolved measure: rows resolved within a half-open window, counted per
+// group and optionally per UTC calendar bucket. `status = 'resolved'` inlines
+// as a literal and the role scope is required, so the planner reads the
+// role-led idx_hmsh_esc_resolved_cover range (role, resolved_at) instead of
+// sweeping every queue's history. Cost grows with the rows resolved in the
+// window for the scoped roles.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBucket = resolveBucket;
+exports.buildResolvedAggregate = buildResolvedAggregate;
+const config_1 = require("../../modules/config");
+const aggregate_validate_1 = require("./aggregate-validate");
+const types_1 = require("../../types");
+/** The bucket, validated against the closed set; it inlines into date_trunc. */
+function resolveBucket(bucket) {
+    if (bucket === undefined)
+        return null;
+    if (!types_1.RESOLVED_BUCKETS.includes(bucket)) {
+        throw new aggregate_validate_1.AnalyticsInputError(`measure.bucket "${String(bucket)}" is not one of ${types_1.RESOLVED_BUCKETS.join(', ')}`);
+    }
+    return bucket;
+}
+function buildResolvedAggregate(input) {
+    const win = (0, aggregate_validate_1.resolveWindow)(input.window, 'measure.window', {
+        days: config_1.config.LT_ANALYTICS_MAX_RESOLVED_WINDOW_DAYS,
+        envVar: 'LT_ANALYTICS_MAX_RESOLVED_WINDOW_DAYS',
+    });
+    if (!win)
+        throw new aggregate_validate_1.AnalyticsInputError('measure.window is required for resolved');
+    const { params } = input;
+    params.push(win.from.toISOString());
+    const fromP = `$${params.length}::timestamptz`;
+    params.push(win.to.toISOString());
+    const toP = `$${params.length}::timestamptz`;
+    const select = [...input.groupSelect];
+    const keys = [...input.groupKeys];
+    if (input.bucket) {
+        select.unshift(`(date_trunc('${input.bucket}', resolved_at AT TIME ZONE 'UTC') AT TIME ZONE 'UTC') AS bucket`);
+        keys.unshift('bucket');
+    }
+    const countExpr = input.distinctBy
+        ? `count(DISTINCT (metadata->>'${input.distinctBy}'))::int`
+        : 'count(*)::int';
+    const groupBySql = keys.length ? `GROUP BY ${keys.join(', ')}\n` : '';
+    params.push(input.pageLimit + 1, input.offset);
+    const sql = `SELECT ${[...select, `${countExpr} AS "count"`, 'count(*)::int AS sample_count'].join(',\n       ')}
+FROM public.lt_escalations
+WHERE ${input.where}
+  AND status = 'resolved'
+  AND resolved_at >= ${fromP}
+  AND resolved_at < ${toP}
+${groupBySql}ORDER BY ${input.order}
+LIMIT $${params.length - 1} OFFSET $${params.length}`;
+    return { sql, params, nowAnchored: win.nowAnchored };
+}

package/build/services/escalation/aggregate-sql.d.ts

@@ -9,10 +9,13 @@ export interface BuiltAggregateQuery {
     facets: string[];
     /** true when grouped by the derived state label (groupBy.state). */
     stateGrouped: boolean;
-    measureKind: 'membership' | 'dwell';
+    measureKind: AggregateMeasureKind;
+    /** true when the resolved measure groups by calendar bucket. */
+    bucketed: boolean;
     /** true = the anchor touches now (short cache); false = fully past (immutable). */
     nowAnchored: boolean;
 }
+export type AggregateMeasureKind = 'membership' | 'dwell' | 'resolved';
 /** Per-role state naming, from lt_roles.entity_state_source. */
 export type StateSources = Record<string, 'role' | 'subtype'>;
 export interface BuiltTimelineQuery {
@@ -23,6 +26,8 @@ export interface BuiltTimelineQuery {
     facets: string[];
     nowAnchored: boolean;
 }
+/** The projected-facet output alias; the key is FACET_KEY-validated. */
+export declare function facetAlias(key: string): string;
 /**
  * Build the grouped aggregate (membership or dwell) as one parameterized
  * query. `query.entity` must be RESOLVED by the caller before building

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

@@ -18,9 +18,11 @@
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsInputError = void 0;
+exports.facetAlias = facetAlias;
 exports.buildAggregateQuery = buildAggregateQuery;
 exports.buildTimelineQuery = buildTimelineQuery;
 const facet_sql_1 = require("./facet-sql");
+const aggregate_resolved_sql_1 = require("./aggregate-resolved-sql");
 const aggregate_validate_1 = require("./aggregate-validate");
 const types_1 = require("../../types");
 var aggregate_validate_2 = require("./aggregate-validate");
@@ -60,24 +62,27 @@ function overlapsAfter(liveList, fromParam) {
     return `(status IN (${liveList}) OR (status NOT IN (${liveList}) AND COALESCE(resolved_at, updated_at) > ${fromParam}))`;
 }
 /** ORDER BY over the RESULT groups: measure aliases and grouped keys only. */
-function buildAggregateOrder(orderBy, measureKind, columns, facets, stateGrouped = false) {
+function buildAggregateOrder(orderBy, measureKind, columns, facets, stateGrouped = false, bucketed = false) {
     if (!orderBy || !orderBy.length)
-        return 'sample_count DESC';
+        return bucketed ? 'bucket ASC, sample_count DESC' : 'sample_count DESC';
     const parts = [];
     for (const o of orderBy) {
         const dir = o.direction === 'desc' ? 'DESC' : 'ASC';
         if (o.field === 'state' && stateGrouped) {
             parts.push(`state_label ${dir}`);
         }
+        else if (o.field === 'bucket' && bucketed) {
+            parts.push(`bucket ${dir}`);
+        }
         else if (o.field === 'count') {
-            if (measureKind !== 'membership') {
-                throw new aggregate_validate_1.AnalyticsInputError('orderBy "count" applies to membership; use "dwellSeconds" for dwell');
+            if (measureKind === 'dwell') {
+                throw new aggregate_validate_1.AnalyticsInputError('orderBy "count" applies to membership and resolved; use "dwellSeconds" for dwell');
             }
             parts.push(`"count" ${dir}`);
         }
         else if (o.field === 'dwellSeconds') {
             if (measureKind !== 'dwell') {
-                throw new aggregate_validate_1.AnalyticsInputError('orderBy "dwellSeconds" applies to dwell; use "count" for membership');
+                throw new aggregate_validate_1.AnalyticsInputError('orderBy "dwellSeconds" applies to dwell; use "count" for membership and resolved');
             }
             parts.push(`dwell_seconds ${dir}`);
         }
@@ -91,7 +96,7 @@ function buildAggregateOrder(orderBy, measureKind, columns, facets, stateGrouped
             parts.push(`${facetAlias(o.field)} ${dir} NULLS LAST`);
         }
         else {
-            throw new aggregate_validate_1.AnalyticsInputError(`orderBy field "${o.field}" is not a measure (count, dwellSeconds, sampleCount) or a grouped key`);
+            throw new aggregate_validate_1.AnalyticsInputError(`orderBy field "${o.field}" is not a measure (count, dwellSeconds, sampleCount), a bucket, or a grouped key`);
         }
     }
     return parts.join(', ');
@@ -119,12 +124,13 @@ function buildAggregateQuery(input, opts = {}) {
     const liveList = statusLiterals(live);
     const { pageLimit, offset } = (0, aggregate_validate_1.resolvePage)(input.limit, input.offset);
     const measure = input.measure;
-    if (measure?.kind !== 'membership' && measure?.kind !== 'dwell') {
-        throw new aggregate_validate_1.AnalyticsInputError('measure.kind must be "membership" or "dwell"');
+    if (measure?.kind !== 'membership' && measure?.kind !== 'dwell' && measure?.kind !== 'resolved') {
+        throw new aggregate_validate_1.AnalyticsInputError('measure.kind must be "membership", "dwell" or "resolved"');
     }
+    const bucket = measure.kind === 'resolved' ? (0, aggregate_resolved_sql_1.resolveBucket)(measure.bucket) : null;
     const params = [];
     const where = (0, facet_sql_1.buildFacetWhere)(query, params);
-    const order = buildAggregateOrder(input.orderBy, measure.kind, columns, facets, state);
+    const order = buildAggregateOrder(input.orderBy, measure.kind, columns, facets, state, bucket !== null);
     const groupSelect = [];
     const groupKeys = [];
     if (state) {
@@ -139,6 +145,21 @@ function buildAggregateQuery(input, opts = {}) {
         groupSelect.push(`(metadata->>'${key}') AS ${facetAlias(key)}`);
         groupKeys.push(facetAlias(key));
     }
+    if (measure.kind === 'resolved') {
+        if (input.liveStatuses !== undefined) {
+            throw new aggregate_validate_1.AnalyticsInputError('liveStatuses does not apply to the resolved measure, which counts resolved rows');
+        }
+        if (!query.role && !query.roles?.length) {
+            throw new aggregate_validate_1.AnalyticsInputError('the resolved measure requires a role scope: query.role, query.roles or query.entity');
+        }
+        if (input.distinctBy !== undefined)
+            (0, aggregate_validate_1.requireFacetKey)(input.distinctBy, 'distinctBy');
+        const built = (0, aggregate_resolved_sql_1.buildResolvedAggregate)({
+            window: measure.window, bucket, where, params, groupSelect, groupKeys, order,
+            distinctBy: input.distinctBy, pageLimit, offset,
+        });
+        return { ...built, pageLimit, columns, facets, stateGrouped: state, measureKind: 'resolved', bucketed: bucket !== null };
+    }
     const groupBySql = groupKeys.length ? `GROUP BY ${groupKeys.join(', ')}\n` : '';
     if (measure.kind === 'membership') {
         const asOf = (0, aggregate_validate_1.resolveAsOf)(measure.asOf);
@@ -165,11 +186,11 @@ WHERE ${where}
   AND ${intervalPred}
 ${groupBySql}ORDER BY ${order}
 LIMIT $${params.length - 1} OFFSET $${params.length}`;
-        return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'membership', nowAnchored: asOf === null };
+        return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'membership', bucketed: false, nowAnchored: asOf === null };
     }
     // Dwell: clip each overlapping interval to the window, sum open-seconds.
     if (input.distinctBy !== undefined) {
-        throw new aggregate_validate_1.AnalyticsInputError('distinctBy is a membership concept — for per-entity dwell, put the entity facet in groupBy.facets');
+        throw new aggregate_validate_1.AnalyticsInputError('distinctBy applies to membership and resolved; for per-entity dwell, put the entity facet in groupBy.facets');
     }
     const win = (0, aggregate_validate_1.resolveWindow)(measure.window, 'measure.window');
     if (!win)
@@ -198,7 +219,7 @@ SELECT ${[...groupKeys, 'SUM(EXTRACT(EPOCH FROM (e - s)))::float8 AS dwell_secon
 FROM span
 ${groupBySql}ORDER BY ${order}
 LIMIT $${params.length - 1} OFFSET $${params.length}`;
-    return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'dwell', nowAnchored: win.nowAnchored };
+    return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'dwell', bucketed: false, nowAnchored: win.nowAnchored };
 }
 /** Build the single-entity interval sequence, created_at-ordered, gaps preserved. */
 function buildTimelineQuery(input) {

package/build/services/escalation/aggregate-validate.d.ts

@@ -29,8 +29,11 @@ export declare function resolveTimelinePage(order: 'asc' | 'desc' | undefined, b
     before: Date | null;
 };
 export declare function toInstant(value: Date | string, label: string): Date;
-/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS. */
-export declare function resolveWindow(window: AnalyticsWindow | undefined, label?: string): {
+/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS (or the env var naming `maxDays`). */
+export declare function resolveWindow(window: AnalyticsWindow | undefined, label?: string, maxDays?: {
+    days: number;
+    envVar: string;
+}): {
     from: Date;
     to: Date;
     nowAnchored: boolean;

package/build/services/escalation/aggregate-validate.js

@@ -142,8 +142,11 @@ function toInstant(value, label) {
     }
     return d;
 }
-/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS. */
-function resolveWindow(window, label = 'window') {
+/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS (or the env var naming `maxDays`). */
+function resolveWindow(window, label = 'window', maxDays = {
+    days: config_1.config.LT_ANALYTICS_MAX_WINDOW_DAYS,
+    envVar: 'LT_ANALYTICS_MAX_WINDOW_DAYS',
+}) {
     if (!window)
         return null;
     const from = toInstant(window.from, `${label}.from`);
@@ -152,8 +155,8 @@ function resolveWindow(window, label = 'window') {
         throw new AnalyticsInputError(`${label} is empty: from must be before to`);
     }
     const spanDays = (to.getTime() - from.getTime()) / 86_400_000;
-    if (spanDays > config_1.config.LT_ANALYTICS_MAX_WINDOW_DAYS) {
-        throw new AnalyticsInputError(`${label} spans ${spanDays.toFixed(1)} days; the maximum is ${config_1.config.LT_ANALYTICS_MAX_WINDOW_DAYS} (LT_ANALYTICS_MAX_WINDOW_DAYS)`);
+    if (spanDays > maxDays.days) {
+        throw new AnalyticsInputError(`${label} spans ${spanDays.toFixed(1)} days; the maximum is ${maxDays.days} (${maxDays.envVar})`);
     }
     return { from, to, nowAnchored: to.getTime() >= Date.now() };
 }

package/build/services/escalation/aggregates.js

@@ -67,10 +67,12 @@ function toAggregateRow(raw, built, states) {
     const row = { facets, sampleCount: Number(raw.sample_count) };
     for (const column of built.columns)
         row[column] = raw[column] ?? undefined;
-    if (built.measureKind === 'membership')
-        row.count = Number(raw.count);
-    else
+    if (built.measureKind === 'dwell')
         row.dwellSeconds = Number(raw.dwell_seconds);
+    else
+        row.count = Number(raw.count);
+    if (built.bucketed)
+        row.bucket = toIso(raw.bucket);
     if (built.stateGrouped) {
         row.state = raw.state_label;
     }

package/build/services/escalation/crud.js

@@ -58,6 +58,9 @@ async function createEscalation(input) {
     if (envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS] !== undefined) {
         (0, escalation_1.assertLookupRefs)(envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]);
     }
+    if (envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.FILES] !== undefined) {
+        (0, escalation_1.assertFileRefs)(envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.FILES]);
+    }
     const client = await (0, client_1.escalations)();
     const entry = await client.create({
         type: input.type,

package/build/services/escalation/file-links.d.ts

@@ -0,0 +1,39 @@
+import { type EscalationFileRef, type LTEscalationRecord } from '../../types/escalation';
+/** One file ref answered: a signed link, or the reason there is none. */
+export interface EscalationFileLink {
+    as: string;
+    path: string;
+    name: string;
+    contentType: string;
+    url?: string;
+    expiresAt?: string;
+    error?: string;
+}
+/**
+ * The refs riding the row's envelope under the reserved key, each checked
+ * again at read time: an engine-written envelope can carry refs that never
+ * passed the creation check, and nothing outside the store is ever signed.
+ */
+export declare function readFileRefs(envelope: string | Record<string, unknown> | null | undefined): Array<EscalationFileRef | {
+    error: string;
+    ref: unknown;
+}>;
+/**
+ * The `file` form domain without links, keyed by each ref's `as`: what the
+ * server's validation pass sees, so a condition on a file's presence
+ * evaluates the same on both sides of the wire.
+ */
+export declare function fileContext(envelope: string | Record<string, unknown> | null | undefined): Record<string, Pick<EscalationFileLink, 'as' | 'path' | 'name' | 'contentType'>> | null;
+/** Seconds left on the reader's own live claim, or 0. */
+export declare function claimSecondsLeft(escalation: Pick<LTEscalationRecord, 'assigned_to' | 'assigned_until'>, userId: string, now?: number): number;
+/**
+ * How long a link lives: the ref's ask (else the default), stretched to
+ * cover the reader's live claim, held within the configured bounds.
+ */
+export declare function fileLinkSeconds(ref: Pick<EscalationFileRef, 'expiresIn'>, claimSeconds: number): number;
+/**
+ * Sign every ref. Signing is local to the process (no storage round trip),
+ * so a page open costs one signature per file. A ref that cannot be signed
+ * answers with `error`; the batch never fails.
+ */
+export declare function signFileRefs(refs: ReturnType<typeof readFileRefs>, claimSeconds: number, now?: number): Promise<EscalationFileLink[]>;

package/build/services/escalation/file-links.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFileRefs = readFileRefs;
+exports.fileContext = fileContext;
+exports.claimSecondsLeft = claimSecondsLeft;
+exports.fileLinkSeconds = fileLinkSeconds;
+exports.signFileRefs = signFileRefs;
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../../modules/config");
+const storage_1 = require("../../lib/storage");
+const mime_1 = require("../../lib/storage/mime");
+const escalation_1 = require("../../types/escalation");
+/**
+ * The refs riding the row's envelope under the reserved key, each checked
+ * again at read time: an engine-written envelope can carry refs that never
+ * passed the creation check, and nothing outside the store is ever signed.
+ */
+function readFileRefs(envelope) {
+    if (!envelope)
+        return [];
+    let refs;
+    try {
+        const parsed = typeof envelope === 'string' ? JSON.parse(envelope) : envelope;
+        refs = parsed && typeof parsed === 'object' ? parsed[escalation_1.ESCALATION_ENVELOPE_KEYS.FILES] : undefined;
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(refs))
+        return [];
+    const seen = new Set();
+    return refs.slice(0, escalation_1.ESCALATION_FILE_REFS_MAX).map((ref) => {
+        const problem = (0, escalation_1.fileRefProblem)(ref);
+        if (problem)
+            return { error: problem, ref };
+        const alias = ref.as;
+        if (seen.has(alias))
+            return { error: `File ref ${alias}: "as" names more than one file`, ref };
+        seen.add(alias);
+        return ref;
+    });
+}
+/**
+ * The `file` form domain without links, keyed by each ref's `as`: what the
+ * server's validation pass sees, so a condition on a file's presence
+ * evaluates the same on both sides of the wire.
+ */
+function fileContext(envelope) {
+    const entries = readFileRefs(envelope).filter((r) => !('error' in r));
+    if (entries.length === 0)
+        return null;
+    return Object.fromEntries(entries.map((ref) => {
+        const key = (0, escalation_1.normalizeFileRefPath)(ref.path);
+        return [ref.as, {
+                as: ref.as,
+                path: key,
+                name: ref.name ?? path_1.default.posix.basename(key),
+                contentType: ref.contentType ?? (0, mime_1.mimeFromPath)(key),
+            }];
+    }));
+}
+/** Seconds left on the reader's own live claim, or 0. */
+function claimSecondsLeft(escalation, userId, now = Date.now()) {
+    if (!escalation.assigned_to || escalation.assigned_to !== userId || !escalation.assigned_until)
+        return 0;
+    const until = new Date(escalation.assigned_until).getTime();
+    return Number.isFinite(until) && until > now ? Math.ceil((until - now) / 1000) : 0;
+}
+/**
+ * How long a link lives: the ref's ask (else the default), stretched to
+ * cover the reader's live claim, held within the configured bounds.
+ */
+function fileLinkSeconds(ref, claimSeconds) {
+    const asked = ref.expiresIn ?? config_1.config.LT_ESCALATION_FILE_URL_TTL_SECONDS;
+    const wanted = Math.max(asked, claimSeconds);
+    const min = config_1.config.LT_ESCALATION_FILE_URL_MIN_SECONDS;
+    const max = Math.max(min, config_1.config.LT_ESCALATION_FILE_URL_MAX_SECONDS);
+    return Math.min(Math.max(wanted, min), max);
+}
+/**
+ * Sign every ref. Signing is local to the process (no storage round trip),
+ * so a page open costs one signature per file. A ref that cannot be signed
+ * answers with `error`; the batch never fails.
+ */
+async function signFileRefs(refs, claimSeconds, now = Date.now()) {
+    const storage = (0, storage_1.getStorageBackend)();
+    return Promise.all(refs.map(async (entry) => {
+        if ('error' in entry) {
+            const raw = (entry.ref ?? {});
+            return {
+                as: typeof raw.as === 'string' ? raw.as : '',
+                path: typeof raw.path === 'string' ? raw.path : '',
+                name: '',
+                contentType: '',
+                error: entry.error,
+            };
+        }
+        const key = (0, escalation_1.normalizeFileRefPath)(entry.path);
+        const link = {
+            as: entry.as,
+            path: key,
+            name: entry.name ?? path_1.default.posix.basename(key),
+            contentType: entry.contentType ?? (0, mime_1.mimeFromPath)(key),
+        };
+        const seconds = fileLinkSeconds(entry, claimSeconds);
+        try {
+            link.url = await storage.getSignedUrl(key, seconds);
+            link.expiresAt = new Date(now + seconds * 1000).toISOString();
+        }
+        catch (err) {
+            link.error = err?.message ?? 'The file link could not be signed';
+        }
+        return link;
+    }));
+}

package/build/services/escalation/resolver-validation.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Server-side resolver schema enforcement — the API-first counterpart of the
+ * dashboard's pre-submission pass. Every resolve surface (HTTP, SDK, MCP)
+ * calls checkResolverPayload before committing a resolution; roles that opt in
+ * via enforce_schema get their form_schema enforced as an API contract, and
+ * violations surface as the canonical 422 body (types/validation.ts).
+ *
+ * Production shape: the gate consults the cached enforcing-role set first, so
+ * when no involved role enforces, a resolve costs zero additional SQL. Schema
+ * reads for enforcing roles come from the enforcement cache (immutable pinned
+ * snapshots cached indefinitely; latest schemas under a short TTL).
+ *
+ * Schema resolution matches the resolve UI, most specific first:
+ *   1. metadata.form_schema — a full form embedded on the row
+ *   2. the lt_role_schemas snapshot pinned by metadata.schema_version
+ *   3. the role's live (latest) form_schema
+ * A role that enforces but declares no schema has no contract to enforce —
+ * the gate passes.
+ */
+import { type ReviewFacets } from '../../shared/form-validation';
 import { type LTFieldViolation, type LTValidationErrorBody } from '../../types/validation';
 /** The row fields the gate reads — every resolve surface already holds these. */
 export interface ResolvableEscalationRow {
@@ -14,6 +34,12 @@ export interface ResolverSchemaViolationReport {
     schemaVersion: number | null;
     violations: LTFieldViolation[];
 }
+/** The gate's verdict, plus the review facets a passing answer stamps. */
+export interface ResolverPayloadAssessment {
+    violation: ResolverSchemaViolationReport | null;
+    /** Review summary for the row's metadata, when the form opts in (x-lt-confidence facets). */
+    facets: ReviewFacets | null;
+}
 /**
  * Validate a submitted resolverPayload against the escalation's enforced form
  * schema. Returns null when the resolution may proceed (role does not enforce,
@@ -24,5 +50,12 @@ export interface ResolverSchemaViolationReport {
  * It is only invoked when the role actually enforces.
  */
 export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>, resolvingUserId?: string): Promise<ResolverSchemaViolationReport | null>;
+/**
+ * The same gate, also returning the review facets a passing answer stamps
+ * onto the row. Single-row resolve paths merge `facets` into the outcome
+ * patch, so they commit inside the guarded resolve UPDATE. Computed from the
+ * schema and context the gate already loaded: no extra reads.
+ */
+export declare function assessResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>, resolvingUserId?: string): Promise<ResolverPayloadAssessment>;
 /** The canonical 422 body for a violation report (types/validation.ts). */
 export declare function toValidationErrorBody(report: ResolverSchemaViolationReport): LTValidationErrorBody;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkResolverPayload = checkResolverPayload;
+exports.assessResolverPayload = assessResolverPayload;
 exports.toValidationErrorBody = toValidationErrorBody;
 /**
  * Server-side resolver schema enforcement — the API-first counterpart of the
@@ -24,6 +25,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 file_links_1 = require("./file-links");
 const enforcement_cache_1 = require("../role/enforcement-cache");
 const knowledge_1 = require("../knowledge");
 const escalation_1 = require("../../types/escalation");
@@ -48,6 +50,7 @@ function pinnedVersionOf(metadata) {
         return parseInt(raw, 10);
     return null;
 }
+const PASS = { violation: null, facets: null };
 /**
  * Validate a submitted resolverPayload against the escalation's enforced form
  * schema. Returns null when the resolution may proceed (role does not enforce,
@@ -58,12 +61,22 @@ function pinnedVersionOf(metadata) {
  * It is only invoked when the role actually enforces.
  */
 async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId) {
+    const { violation } = await assessResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId);
+    return violation;
+}
+/**
+ * The same gate, also returning the review facets a passing answer stamps
+ * onto the row. Single-row resolve paths merge `facets` into the outcome
+ * patch, so they commit inside the guarded resolve UPDATE. Computed from the
+ * schema and context the gate already loaded: no extra reads.
+ */
+async function assessResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId) {
     const role = escalation.role;
     if (!role)
-        return null;
+        return PASS;
     const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
     if (!enforcing.has(role))
-        return null;
+        return PASS;
     const metadata = (escalation.metadata ?? {});
     const pin = pinnedVersionOf(metadata);
     const embedded = metadata[escalation_1.ESCALATION_METADATA_KEYS.FORM_SCHEMA];
@@ -71,7 +84,7 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, r
         ? embedded
         : await (0, enforcement_cache_1.getEnforcedFormSchema)(role, pin);
     if (!schema)
-        return null;
+        return PASS;
     const envelope = loadEnvelope
         ? await loadEnvelope()
         : parseJsonOrNull(escalation.envelope) ?? {};
@@ -79,12 +92,14 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, r
     // immutable snapshot cache, so enforcement reads the exact editions the
     // form rendered from. Rows without refs cost zero SQL here.
     const lookup = await (0, knowledge_1.resolveLookupContext)(envelope[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]);
+    const file = (0, file_links_1.fileContext)(envelope);
     const ctx = {
         escalation: escalation,
         metadata,
         envelope,
         payload: parseJsonOrNull(escalation.escalation_payload),
         ...(lookup ? { lookup } : {}),
+        ...(file ? { file } : {}),
     };
     // 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.
@@ -98,9 +113,10 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, r
     // contract, so a raw-API resolve honors the gate the dashboard shows.
     const guardViolation = await (0, submit_guard_1.checkSubmitGuard)(schema, ctx, resolvingUserId);
     const allViolations = guardViolation ? [...violations, guardViolation] : violations;
-    if (allViolations.length === 0)
-        return null;
-    return { role, schemaVersion: pin, violations: allViolations };
+    if (allViolations.length > 0) {
+        return { violation: { role, schemaVersion: pin, violations: allViolations }, facets: null };
+    }
+    return { violation: null, facets: (0, form_validation_1.buildReviewFacets)(schema, ctx, formValues) };
 }
 /** The canonical 422 body for a violation report (types/validation.ts). */
 function toValidationErrorBody(report) {

package/build/services/orchestrator/condition.d.ts

@@ -1,14 +1,15 @@
 import type { Types } from '@hotmeshio/hotmesh';
-import { type AccumulateConfig, type AccumulatorResult, type EscalationLookupRef } from '../../types/escalation';
+import { type AccumulateConfig, type AccumulatorResult, type EscalationLookupRef, type EscalationFileRef } from '../../types/escalation';
 /**
  * HotMesh's escalation config plus long-tail sugar. `schemaVersion` pins the
  * role form version (lt_role_schemas) the resolve UI renders; `lookups` names
  * the knowledge entries the form may read (the `lookup.*` context domain, see
  * docs/hitl/lookups.md), each pinned to an edition or following the current
- * one. Both are LITERALS the workflow author sets, folded before the config
- * reaches the engine:
+ * one; `files` names the stored files the form shows (the `file.*` context
+ * domain, see docs/hitl/files.md). All are set by the workflow author and
+ * folded before the config reaches the engine:
  * schemaVersion into the GIN-indexed metadata (a queryable facet), lookups
- * into the unindexed envelope (form plumbing, never a facet). Folding is a
+ * and files into the unindexed envelope (form plumbing, never a facet). Folding is a
  * pure transform — no query, no activity — so a pinned `conditional` costs
  * exactly what an unpinned one does. Omit `schemaVersion` and the resolve UI
  * renders the role's latest form when the escalation is fetched.
@@ -16,6 +17,7 @@ import { type AccumulateConfig, type AccumulatorResult, type EscalationLookupRef
 export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
     schemaVersion?: number;
     lookups?: EscalationLookupRef[];
+    files?: EscalationFileRef[];
 };
 /**
  * Wait for a signal and resolve the associated escalation automatically.
@@ -74,6 +76,20 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * });
  * ```
  *
+ * **Stored files: documents the form shows.** Each ref names an object in
+ * file storage and the address the form reads it at (`file.<as>`). The
+ * resolve UI fetches time-limited signed links when the page opens and again
+ * on claim; a `document` widget renders PDFs and images inline.
+ *
+ * ```typescript
+ * const decision = await conditional<IntakeReviewV1>(signalId, {
+ *   role: 'intake-verifier',
+ *   description: instructions,
+ *   envelope: { formDefaults: extracted, confidence: scores },
+ *   files: [{ path: `referrals/${referralId}.pdf`, as: 'referral' }],
+ * });
+ * ```
+ *
  * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
  * single wait arms a resume timer alongside the escalation row: when the timer
  * fires first, this helper returns `false`, the row transitions to