@hotmeshio/long-tail 0.10.13 → 0.10.14

package/README.md

@@ -4,9 +4,7 @@
 
 Durable platforms are built around determinism — that is their strength and their blind spot. They give you rich, first-class queues for deterministic work (retry, timeout, `backoffCoefficient`, exactly-once) and an `await condition()` to park a workflow until a signal arrives. All of it assumes the thing you are waiting on will, eventually, behave.
 
-Most of the work that decides an outcome behaves on its own schedule: an approval, a person, a shipment, a machine that needs service. You cannot set a `backoffCoefficient` on a person — retrying someone who has not answered just asks twice. This is why "human-in-the-loop" keeps getting bolted on as a feature: the platform perfected the deterministic queue and left the non-deterministic one for you to improvise.
-
-Long Tail makes it a primitive. The same `condition()` wait — except the act of waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. Machines answer some rows, people answer others; the workflow resumes either way, exactly where it paused.
+Long Tail makes non-determinism a primitive. The same `condition()` wait — except the act of waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. Machines answer some rows, people answer others; the workflow resumes either way, exactly where it paused.
 
 ```bash
 npm install @hotmeshio/long-tail
@@ -14,7 +12,7 @@ npm install @hotmeshio/long-tail
 
 ## How it works
 
-One workflow, both queues: `proxyActivities` for the deterministic one, `condition()` for the one reality answers.
+One workflow, both queues: `proxyActivities` for the deterministic one, `condition()` for non-determinism.
 
 ```typescript
 import { Durable } from '@hotmeshio/hotmesh';

package/build/api/escalations/metadata.js

@@ -161,7 +161,7 @@ async function resolveByMetadata(input, auth) {
         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, null, input.extraFacets);
         if (result.outcome === 'validation_required' && result.row) {
-            const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload);
+            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);

package/build/api/escalations/resolve.js

@@ -98,7 +98,7 @@ async function resolveEscalation(input, auth) {
         // the escalation's resolved form schema BEFORE any resolution path runs.
         // Costs nothing when the role does not enforce (cached role set); the
         // task-fallback envelope read only happens for enforcing roles.
-        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, () => reconstructEnvelope(escalation));
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, () => reconstructEnvelope(escalation), auth.userId);
         if (violation)
             return validationFailure(violation);
         // The resolver payload is stored exactly as submitted — its shape is the
@@ -181,7 +181,7 @@ async function resolveBySignalKey(input, auth) {
             return { status: 404, error: 'Escalation not found' };
         // Schema enforcement — the row (envelope included) is already loaded, so
         // this costs zero extra reads beyond the cached schema.
-        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload);
+        const violation = await (0, resolver_validation_1.checkResolverPayload)(escalation, resolverPayload, undefined, auth.userId);
         if (violation)
             return validationFailure(violation);
         // The payload is delivered as the signal the parked workflow's condition()
@@ -247,7 +247,7 @@ async function resolveByIds(input, auth) {
                 const fullRows = await escalationService.getEscalationsByIds(involved);
                 const failed = [];
                 for (const row of fullRows) {
-                    const report = await (0, resolver_validation_1.checkResolverPayload)(row, resolverPayload);
+                    const report = await (0, resolver_validation_1.checkResolverPayload)(row, resolverPayload, undefined, auth.userId);
                     if (report)
                         failed.push({ id: row.id, report });
                 }
@@ -346,7 +346,7 @@ async function resolveAllOrNone(input, auth) {
                 const row = rowById.get(item.id);
                 if (!row || !row.role || !enforcing.has(row.role))
                     continue;
-                const report = await (0, resolver_validation_1.checkResolverPayload)(row, item.resolverPayload);
+                const report = await (0, resolver_validation_1.checkResolverPayload)(row, item.resolverPayload, undefined, auth.userId);
                 if (report)
                     failed.push({ id: item.id, report });
             }

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

@@ -23,6 +23,6 @@ export interface ResolverSchemaViolationReport {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>): Promise<ResolverSchemaViolationReport | null>;
+export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>, resolvingUserId?: string): Promise<ResolverSchemaViolationReport | null>;
 /** 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

@@ -22,6 +22,7 @@ exports.toValidationErrorBody = toValidationErrorBody;
  * the gate passes.
  */
 const form_validation_1 = require("../../shared/form-validation");
+const submit_guard_1 = require("./submit-guard");
 const enforcement_cache_1 = require("../role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const validation_1 = require("../../types/validation");
@@ -54,7 +55,7 @@ function pinnedVersionOf(metadata) {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
+async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId) {
     const role = escalation.role;
     if (!role)
         return null;
@@ -72,15 +73,21 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
     const envelope = loadEnvelope
         ? await loadEnvelope()
         : parseJsonOrNull(escalation.envelope) ?? {};
-    const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, {
+    const ctx = {
         escalation: escalation,
         metadata,
         envelope,
         payload: parseJsonOrNull(escalation.escalation_payload),
-    });
-    if (violations.length === 0)
+    };
+    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
+    // 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 };
+    return { role, schemaVersion: pin, violations: allViolations };
 }
 /** The canonical 422 body for a violation report (types/validation.ts). */
 function toValidationErrorBody(report) {

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

@@ -0,0 +1,29 @@
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - 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.
+ */
+import { type ShowIfContext } from '../../shared/form-validation';
+import type { LTFieldViolation } from '../../types/validation';
+/** The synthetic violation field for a guard rejection — not a form field. */
+export declare const SUBMIT_GUARD_VIOLATION_FIELD = "_submitGuard";
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+export declare function checkSubmitGuard(schema: Record<string, any> | null | undefined, ctx: ShowIfContext, resolvingUserId: string | undefined): Promise<LTFieldViolation | null>;

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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBMIT_GUARD_VIOLATION_FIELD = void 0;
+exports.checkSubmitGuard = checkSubmitGuard;
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - 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.
+ */
+const form_validation_1 = require("../../shared/form-validation");
+const queries_1 = require("./queries");
+/** The synthetic violation field for a guard rejection — not a form field. */
+exports.SUBMIT_GUARD_VIOLATION_FIELD = '_submitGuard';
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+async function checkSubmitGuard(schema, ctx, resolvingUserId) {
+    const guard = (0, form_validation_1.readSubmitGuard)(schema);
+    if (!guard || guard.mustBeEmpty === false)
+        return null;
+    const scoped = (0, form_validation_1.resolveScopedQuery)(guard.query, ctx, resolvingUserId);
+    if (!scoped.enabled)
+        return null;
+    const { total } = await (0, queries_1.searchEscalationsFaceted)({
+        global: true,
+        facet: {
+            role: scoped.role,
+            status: scoped.status,
+            available: scoped.available,
+            facets: scoped.facets,
+        },
+        assigned_to: scoped.assigned_to,
+        limit: 1,
+        offset: 0,
+    });
+    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 { field: exports.SUBMIT_GUARD_VIOLATION_FIELD, message };
+}

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

@@ -8,6 +8,10 @@ export * from './derive-field-label';
 export * from './x-lt-bind';
 export * from './x-lt-help';
 export * from './x-lt-transition';
+export * from './x-lt-submit-on-claim';
+export * from './x-lt-labels';
+export * from './x-lt-query';
+export * from './x-lt-submit-guard';
 export * from './x-lt-show-if';
 export * from './field-validator';
 export * from './validate-resolver-payload';

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

@@ -24,6 +24,10 @@ __exportStar(require("./derive-field-label"), exports);
 __exportStar(require("./x-lt-bind"), exports);
 __exportStar(require("./x-lt-help"), exports);
 __exportStar(require("./x-lt-transition"), exports);
+__exportStar(require("./x-lt-submit-on-claim"), exports);
+__exportStar(require("./x-lt-labels"), exports);
+__exportStar(require("./x-lt-query"), exports);
+__exportStar(require("./x-lt-submit-guard"), exports);
 __exportStar(require("./x-lt-show-if"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);

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

@@ -0,0 +1,28 @@
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+export declare const X_LT_LABELS = "x-lt-labels";
+/** The footer controls a schema may rename. */
+export declare const FOOTER_LABEL_TARGETS: readonly ["claim", "cancel", "submit", "escalate", "release"];
+export type FooterLabelTarget = (typeof FOOTER_LABEL_TARGETS)[number];
+/** A partial map of target → override label. Absent targets keep their default. */
+export type FooterLabels = Partial<Record<FooterLabelTarget, string>>;
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+export declare function readFooterLabels(schema: Record<string, unknown> | null | undefined): FooterLabels;

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

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * x-lt-labels — configurable copy for the standard escalation footer. A
+ * form_schema may declare, at its schema root, an object that renames the
+ * footer's action controls. Each key is a standard target; its value is the
+ * label to render in place of the default.
+ *
+ *   x-lt-labels   object — { claim, cancel, submit, escalate, release }
+ *
+ * ```jsonc
+ * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
+ * ```
+ *
+ * Only the five known targets are read; unknown keys and non-string values are
+ * ignored. Any target the schema omits keeps its default label, so a schema
+ * overrides just the controls it cares about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOOTER_LABEL_TARGETS = exports.X_LT_LABELS = void 0;
+exports.readFooterLabels = readFooterLabels;
+exports.X_LT_LABELS = 'x-lt-labels';
+/** The footer controls a schema may rename. */
+exports.FOOTER_LABEL_TARGETS = ['claim', 'cancel', 'submit', 'escalate', 'release'];
+/**
+ * The schema's footer label overrides, or an empty map when none are declared.
+ * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
+ * blank or non-string values are dropped.
+ */
+function readFooterLabels(schema) {
+    const raw = schema?.[exports.X_LT_LABELS];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const source = raw;
+    const labels = {};
+    for (const target of exports.FOOTER_LABEL_TARGETS) {
+        const value = source[target];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            labels[target] = value.trim();
+        }
+    }
+    return labels;
+}

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

@@ -0,0 +1,56 @@
+import type { ShowIfContext } from './x-lt-show-if';
+/**
+ * The embedded escalation query shape shared by `x-lt-query` (escalation-list
+ * widget) and `x-lt-submit-guard.query` (form-level submit gate). String
+ * values inside `facets` support `{{domain.path}}` token interpolation against
+ * the host escalation's context. Isomorphic: the dashboard renders embeds from
+ * it, and the API layer enforces the submit gate from the identical mapping.
+ *
+ * `assigned` is the ownership scope. Ownership is not a separate list — it is
+ * one more dimension of the same faceted query language the escalation API
+ * composes server-side ("claimed" is the implied status: pending, held, claim
+ * window live):
+ * - `"me"`  — rows claimed by the viewing user (the walk case: I walk what I own)
+ * - `"any"` — all matching rows regardless of claim state
+ * - omitted — available rows only (unclaimed, or claim window lapsed)
+ */
+export interface EmbedQuery {
+    role?: string;
+    status?: string;
+    facets?: Record<string, string>;
+    limit?: number;
+    assigned?: 'me' | 'any';
+    /** Superseded by `assigned`; honored only when `assigned` is omitted. */
+    available?: boolean;
+}
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+export declare function resolveQueryFacets(facets: Record<string, string> | undefined, ctx: ShowIfContext): Record<string, unknown>;
+/** The escalation-query params an EmbedQuery resolves to — the exact input
+ *  shape of `useEscalations`, so every embed surface queries identically. */
+export interface ScopedQueryParams {
+    role?: string;
+    status: string;
+    facets: Record<string, unknown>;
+    assigned_to?: string;
+    available?: boolean;
+    limit?: number;
+    enabled: boolean;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+export declare function resolveScopedQuery(query: EmbedQuery, ctx: ShowIfContext, viewerId: string | undefined): ScopedQueryParams;

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQueryFacets = resolveQueryFacets;
+exports.resolveScopedQuery = resolveScopedQuery;
+const x_lt_help_1 = require("./x-lt-help");
+/** Interpolate `{{domain.path}}` tokens in every string value of the facets map. */
+function resolveQueryFacets(facets, ctx) {
+    if (!facets)
+        return {};
+    const resolved = {};
+    for (const [k, v] of Object.entries(facets)) {
+        resolved[k] = typeof v === 'string' ? (0, x_lt_help_1.interpolateHelp)(v, ctx) : v;
+    }
+    return resolved;
+}
+/**
+ * Resolve an EmbedQuery into concrete escalation-query params — the ONE
+ * mapping every embed surface (escalation-list, x-lt-actions, x-lt-submit-guard)
+ * consumes, so the visible rows and any count derived from the same query can
+ * never disagree.
+ *
+ * Ownership scope translates into the faceted query language:
+ * - `assigned: "me"`  → `assigned_to = viewer AND available = false` — the
+ *   implied "claimed" status (pending + live claim window held by the viewer)
+ * - `assigned: "any"` → no ownership constraint
+ * - omitted           → `available = true` (the unclaimed pool; a declared
+ *   legacy `available` value is honored)
+ *
+ * When `assigned: "me"` and no viewer id is supplied (a surface with no
+ * resolving user, e.g. an MCP resolve), the scope cannot be evaluated —
+ * `enabled` is false rather than silently widening to another scope.
+ */
+function resolveScopedQuery(query, ctx, viewerId) {
+    const facets = resolveQueryFacets(query.facets, ctx);
+    const base = {
+        role: query.role,
+        status: query.status ?? 'pending',
+        facets,
+        limit: query.limit,
+        enabled: !!(query.role || Object.keys(facets).length),
+    };
+    if (query.assigned === 'me') {
+        return { ...base, assigned_to: viewerId, available: false, enabled: base.enabled && !!viewerId };
+    }
+    if (query.assigned === 'any') {
+        return base;
+    }
+    return { ...base, available: query.available ?? true };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * x-lt-submit-guard — a query precondition on the resolve. A form_schema may
+ * declare, at its root, that the escalation cannot be resolved while an embedded
+ * escalation query still returns rows: the parent references a set of children
+ * (commonly claimed by the same person) that must all be completed first, a
+ * to-do list that empties as children resolve.
+ *
+ *   "x-lt-submit-guard": {
+ *     "query": { "role": "print-harvest", "status": "pending",
+ *                "assigned": "me",
+ *                "facets": { "walkId": "{{metadata.walkId}}" } },
+ *     "mustBeEmpty": true,               // the only mode today; defaults true
+ *     "message": "{{count}} plates still pending — bag them before closing.",
+ *     "autoResolveWhenEmpty": true       // auto-submit the parent once empty
+ *   }
+ *
+ * The gate is isomorphic. The dashboard disables the submit while the query
+ * returns rows (UI honesty), and the API layer enforces the same precondition
+ * for `enforce_schema` roles so a raw-API resolve is rejected too. Only a
+ * confirmed empty result (a successful read with zero rows) clears the gate — a
+ * 403 or any error never does.
+ *
+ * `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.
+ */
+import type { EmbedQuery } from './x-lt-query';
+export declare const X_LT_SUBMIT_GUARD = "x-lt-submit-guard";
+export interface SubmitGuardDef {
+    query: EmbedQuery;
+    /** The gate condition; defaults to true (the only supported mode today). */
+    mustBeEmpty?: boolean;
+    /** Shown beside the disabled submit. `{{count}}` and `{{domain.path}}` tokens interpolate. */
+    message?: string;
+    /** When true, auto-submit the claimed parent the moment the query is confirmed empty. */
+    autoResolveWhenEmpty?: boolean;
+}
+export declare const SUBMIT_GUARD_DEFAULT_MESSAGE = "{{count}} related items are still pending";
+/** The schema's submit-guard, or undefined when it declares none. */
+export declare function readSubmitGuard(schema: Record<string, unknown> | null | undefined): SubmitGuardDef | undefined;
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+export declare function guardBlocks(count: number, guard: SubmitGuardDef | undefined): boolean;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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';
+/** 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 (!guard.query || typeof guard.query !== 'object')
+        return undefined;
+    return guard;
+}
+/**
+ * Whether a guard blocks the resolve given the query's row count. `mustBeEmpty`
+ * defaults to true, so any matching row blocks. A pure decision — the caller
+ * supplies the count from a confirmed read (never an error/loading state).
+ */
+function guardBlocks(count, guard) {
+    return !!guard && guard.mustBeEmpty !== false && count > 0;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+export declare const X_LT_SUBMIT_ON_CLAIM = "x-lt-submit-on-claim";
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+export declare function readSubmitOnClaim(schema: Record<string, unknown> | null | undefined): boolean;

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

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * x-lt-submit-on-claim — a one-gesture claim. A form_schema may declare, at its
+ * schema root, that claiming one of its escalations should also resolve it in
+ * the same gesture, submitting whatever the form currently holds (its seeded
+ * defaults). The person clicks Claim once and the work item advances — no
+ * second Submit step.
+ *
+ *   x-lt-submit-on-claim   boolean — opt in to claim-and-submit
+ *
+ * It is opt-in and defaults off. Pair it with `x-lt-labels` to rename the Claim
+ * button ("Claim and Submit") so the single gesture reads honestly. When the
+ * seeded defaults fail validation the claim still lands; the page drops into the
+ * normal claimed state with the field errors surfaced, so the person finishes
+ * the form by hand.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_SUBMIT_ON_CLAIM = void 0;
+exports.readSubmitOnClaim = readSubmitOnClaim;
+exports.X_LT_SUBMIT_ON_CLAIM = 'x-lt-submit-on-claim';
+/**
+ * Whether the schema opts into claim-and-submit. Truthy `x-lt-submit-on-claim`
+ * turns it on; anything else (absent, false) leaves the standard two-step claim
+ * then submit.
+ */
+function readSubmitOnClaim(schema) {
+    return !!schema?.[exports.X_LT_SUBMIT_ON_CLAIM];
+}