@hotmeshio/long-tail 0.25.0 → 0.25.2

package/build/api/scan-codes/verb-fill.js

@@ -40,6 +40,7 @@ const resolve_batch_1 = require("../escalations/resolve-batch");
 const escalation_1 = require("../../types/escalation");
 const types_1 = require("../../types");
 const context_1 = require("./context");
+const fill_labels_1 = require("./fill-labels");
 const grant_1 = require("./grant");
 const locate_1 = require("./locate");
 const subject_1 = require("./subject");
@@ -60,6 +61,18 @@ function codeOf(key, separator) {
 function keysFor(keys, target, separator) {
     return keys.filter((k) => codeOf(k, separator) === target);
 }
+/** Labeled pending entries read as one line; labels may carry commas. */
+const LABEL_JOIN = '; ';
+/** The `{fill.pending}` and `{fill.next}` values for the open keys. */
+function pendingCopy(pending, separator, labeler) {
+    const code = (key) => codeOf(key, separator);
+    if (!labeler) {
+        const codes = [...new Set(pending.map(code))];
+        return { pending: codes, ...(codes.length ? { next: codes[0] } : {}) };
+    }
+    const labels = (0, fill_labels_1.pendingLabels)(pending, code, labeler);
+    return { pending: labels.join(LABEL_JOIN), ...(labels.length ? { next: labels[0] } : {}) };
+}
 function progress(batch, filledNow) {
     const remaining = Math.max(0, batch.pending.length - filledNow);
     return { filled: batch.keys.length - remaining, total: batch.keys.length, remaining };
@@ -82,10 +95,12 @@ async function fillStep(step, ctx) {
     if (!batch)
         return (0, context_1.conflict)('the held row is not a batch');
     // 2. Which open slot this scan fills, or why none
+    const labeler = (0, fill_labels_1.entryLabeler)(options, row, ctx.scheme);
+    const open = pendingCopy(batch.pending, separator, labeler);
     const tpl = {
         ...(0, context_1.templateContext)(ctx),
         fill: {
-            pending: [...new Set(batch.pending.map((k) => codeOf(k, separator)))],
+            ...open,
             total: batch.keys.length,
             filled: batch.keys.length - batch.pending.length,
         },
@@ -96,9 +111,10 @@ async function fillStep(step, ctx) {
         const markdown = declared.length
             ? `All ${declared.length} of these are already checked off.`
             : scanCodeService.renderScanCopy(step.refuse?.markdown ?? STOCK_UNEXPECTED, tpl);
-        const expected = ctx.scheme.encoding === types_1.SCAN_ENCODINGS.GTIN
-            ? tpl.fill.pending.map((code) => scanCodeService.displayGtin(code))
-            : tpl.fill.pending;
+        const codes = [...new Set(batch.pending.map((k) => codeOf(k, separator)))];
+        const expected = labeler
+            ? (0, fill_labels_1.pendingLabels)(batch.pending, (k) => codeOf(k, separator), labeler)
+            : codes.map((code) => (0, fill_labels_1.printedCode)(code, ctx.scheme));
         return (0, context_1.refused)(markdown, {
             refusal: { markdown, expected },
             progress: progress(batch, 0),
@@ -125,6 +141,7 @@ async function fillStep(step, ctx) {
             const data = result.data;
             const done = data.outcome === 'completed';
             const filled = progress(batch, batch.pending.length - (done ? 0 : (data.remaining ?? 0)));
+            const next = pendingCopy(batch.pending.filter((k) => k !== itemKey), separator, labeler).next;
             return (0, context_1.withDone)({
                 status: 200,
                 data: {
@@ -134,7 +151,7 @@ async function fillStep(step, ctx) {
                     progress: filled,
                     ...(done ? { clearSubject: true } : {}),
                 },
-            }, step, { ...tpl, fill: { ...tpl.fill, ...filled } });
+            }, step, { ...tpl, fill: { ...tpl.fill, ...filled, next } });
         }
         const outcome = result.data?.outcome;
         if (outcome === 'duplicate-item')

package/build/routes/escalations/resolve.js

@@ -126,6 +126,51 @@ function registerResolveRoutes(router) {
         }, auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/:id/flag-batch-item
+     * Flag ONE pending key of a batch escalation (e.g. `Missing`). The key stays
+     * pending and still fills; a wait declared with `wakeOnFlag` ends on the flag.
+     * Body: { itemKey: string, label: string, payload?: Record<string, any> }
+     */
+    router.post('/:id/flag-batch-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.flagBatchItem({ id: req.params.id, itemKey: req.body?.itemKey, label: req.body?.label, payload: req.body?.payload }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/unflag-batch-item
+     * Clear ONE key's flag while the batch escalation is pending.
+     * Body: { itemKey: string }
+     */
+    router.post('/:id/unflag-batch-item', async (req, res) => {
+        const auth = await (0, acting_1.effectiveWorkAuth)(req, res);
+        if (!auth)
+            return;
+        const result = await api.unflagBatchItem({ id: req.params.id, itemKey: req.body?.itemKey }, auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/:id/roster-action
+     * Run one action a roster entry offers on this row's form. The server
+     * re-reads the action from the row's form schema, checks the entry and any
+     * role limit, and runs the act as the person acting: the badged person when
+     * X-LT-Acting-Token rides the request (spent only when the act runs).
+     * Body: { field: string, action: number, entry: string, code?: string }
+     */
+    router.post('/:id/roster-action', async (req, res) => {
+        const token = req.headers[acting_1.ACTING_TOKEN_HEADER];
+        const result = await api.runRosterAction({
+            id: req.params.id,
+            field: req.body?.field,
+            action: req.body?.action,
+            entry: req.body?.entry,
+            code: req.body?.code,
+            actingToken: typeof token === 'string' && token ? token : undefined,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
      * Resolve a pending escalation with a human-provided payload. Routes by

package/build/sdk/index.d.ts

@@ -247,6 +247,17 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             restrictRoles?: string[];
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        flagBatchItem: (input: {
+            id: string;
+            itemKey: string;
+            label: string;
+            payload?: Record<string, any>;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        unflagBatchItem: (input: {
+            id: string;
+            itemKey: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        runRosterAction: (input: import("../api/escalations/roster-action").RosterActionInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         accumulate: (input: {
             id: string;
         } & import("../api/escalations/accumulate").AccumulateItemInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;

package/build/sdk/index.js

@@ -146,6 +146,9 @@ function createClient(options = {}) {
             resolveBatchItem: bindAuth(escalationsApi.resolveBatchItem, auth),
             resolveBatchItemBySignalKey: bindAuth(escalationsApi.resolveBatchItemBySignalKey, auth),
             resolveBatchItemByMetadata: bindAuth(escalationsApi.resolveBatchItemByMetadata, auth),
+            flagBatchItem: bindAuth(escalationsApi.flagBatchItem, auth),
+            unflagBatchItem: bindAuth(escalationsApi.unflagBatchItem, auth),
+            runRosterAction: bindAuth(escalationsApi.runRosterAction, auth),
             // Open accumulation: add and remove held items, read the ordered collection.
             accumulate: bindAuth(escalationsApi.accumulateItem, auth),
             accumulateBySignalKey: bindAuth(escalationsApi.accumulateItemBySignalKey, auth),

package/build/services/domain/seed.d.ts

@@ -1,18 +1,20 @@
+import type { DomainDictionary } from '../../types';
 /**
- * Seed the domain dictionary from a host-declared JSON file.
+ * Seed the domain dictionary declared by the host: inline in the start
+ * config, or in a JSON file named by path.
  *
  * Default (db-owned): the same insert-if-absent + drift-log contract as
- * seedWorkflowConfig/seedMcpServer — the DB row is runtime truth, an existing
- * row is never overwritten, and a name/version mismatch against the file logs
- * one drift warning.
+ * seedWorkflowConfig/seedMcpServer: the DB row is runtime truth, an existing
+ * row is never overwritten, and a name/version mismatch against the declared
+ * document logs one drift warning.
  *
- * With `apply` (code-owned): the file is compared against the stored document
- * as parsed values; a changed document is written through the same upsert the
- * PUT path uses, advancing the row's version counter exactly once. An
- * identical document is a no-op.
+ * With `apply` (code-owned): the declared document is compared against the
+ * stored one as parsed values; a changed document is written through the same
+ * upsert the PUT path uses, advancing the row's version counter exactly once.
+ * An identical document is a no-op.
  *
  * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
  * unknown references log warnings here (the PUT path enforces them hard).
- * Never throws — a missing or malformed file must not brick boot.
+ * Never throws: a missing or malformed file must not brick boot.
  */
-export declare function seedDomainDictionary(dictionaryPath: string, apply?: boolean): Promise<void>;
+export declare function seedDomainDictionary(source: string | DomainDictionary, apply?: boolean): Promise<void>;

package/build/services/domain/seed.js

@@ -14,38 +14,27 @@ const write_1 = require("./write");
 const read_1 = require("./read");
 const sql_1 = require("./sql");
 /**
- * Seed the domain dictionary from a host-declared JSON file.
+ * Seed the domain dictionary declared by the host: inline in the start
+ * config, or in a JSON file named by path.
  *
  * Default (db-owned): the same insert-if-absent + drift-log contract as
- * seedWorkflowConfig/seedMcpServer — the DB row is runtime truth, an existing
- * row is never overwritten, and a name/version mismatch against the file logs
- * one drift warning.
+ * seedWorkflowConfig/seedMcpServer: the DB row is runtime truth, an existing
+ * row is never overwritten, and a name/version mismatch against the declared
+ * document logs one drift warning.
  *
- * With `apply` (code-owned): the file is compared against the stored document
- * as parsed values; a changed document is written through the same upsert the
- * PUT path uses, advancing the row's version counter exactly once. An
- * identical document is a no-op.
+ * With `apply` (code-owned): the declared document is compared against the
+ * stored one as parsed values; a changed document is written through the same
+ * upsert the PUT path uses, advancing the row's version counter exactly once.
+ * An identical document is a no-op.
  *
  * WARN-ONLY validation: hosts commonly seed roles after long-tail boots, so
  * unknown references log warnings here (the PUT path enforces them hard).
- * Never throws — a missing or malformed file must not brick boot.
+ * Never throws: a missing or malformed file must not brick boot.
  */
-async function seedDomainDictionary(dictionaryPath, apply = false) {
-    const resolved = path_1.default.isAbsolute(dictionaryPath)
-        ? dictionaryPath
-        : path_1.default.join(process.cwd(), dictionaryPath);
-    let dictionary;
-    try {
-        if (!(0, fs_1.existsSync)(resolved)) {
-            logger_1.loggerRegistry.warn(`[lt-domain] domainDictionaryPath not found: ${resolved}`);
-            return;
-        }
-        dictionary = JSON.parse((0, fs_1.readFileSync)(resolved, 'utf-8'));
-    }
-    catch (err) {
-        logger_1.loggerRegistry.warn(`[lt-domain] dictionary file unreadable (${resolved}): ${err.message}`);
+async function seedDomainDictionary(source, apply = false) {
+    const dictionary = typeof source === 'string' ? readDictionaryFile(source) : source;
+    if (!dictionary)
         return;
-    }
     try {
         const registry = await (0, write_1.snapshotRegistries)();
         const { errors, warnings, dictionary: derived } = (0, validate_1.validateDictionary)(dictionary, registry);
@@ -75,10 +64,27 @@ async function seedDomainDictionary(dictionaryPath, apply = false) {
         // Row already existed — drift check on name/version only (no deep diff).
         if (doc && (doc.name !== dictionary.name || doc.version !== dictionary.version)) {
             logger_1.loggerRegistry.warn(`[lt-domain] dictionary drift: DB holds "${doc.name}" v${doc.version}, ` +
-                `file declares "${dictionary.name}" v${dictionary.version} — DB is runtime truth`);
+                `start config declares "${dictionary.name}" v${dictionary.version}; DB is runtime truth`);
         }
     }
     catch (err) {
         logger_1.loggerRegistry.warn(`[lt-domain] dictionary seed failed: ${err.message}`);
     }
 }
+/** The dictionary in a JSON file, resolved against the host cwd; null (logged) when missing or unreadable. */
+function readDictionaryFile(dictionaryPath) {
+    const resolved = path_1.default.isAbsolute(dictionaryPath)
+        ? dictionaryPath
+        : path_1.default.join(process.cwd(), dictionaryPath);
+    try {
+        if (!(0, fs_1.existsSync)(resolved)) {
+            logger_1.loggerRegistry.warn(`[lt-domain] domainDictionaryPath not found: ${resolved}`);
+            return null;
+        }
+        return JSON.parse((0, fs_1.readFileSync)(resolved, 'utf-8'));
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[lt-domain] dictionary file unreadable (${resolved}): ${err.message}`);
+        return null;
+    }
+}

package/build/services/escalation/batch-flag.d.ts

@@ -0,0 +1,25 @@
+import type { FlagBatchItemOutcome, LTEscalationRecord, UnflagBatchItemOutcome } from '../../types';
+export interface FlagBatchItemInput {
+    label: string;
+    payload?: Record<string, any>;
+    actor?: string;
+    metadata?: Record<string, any>;
+    resolvedBy?: {
+        id: string;
+        email?: string;
+    };
+}
+export interface BatchFlagOutcome<O extends string> {
+    outcome: O;
+    /** The post-write row; null on every failure outcome. */
+    escalation: LTEscalationRecord | null;
+}
+/**
+ * Flag one pending key of a batch escalation in a single SDK statement. The
+ * key stays pending. A row whose wait declared `wakeOnFlag` resolves in the
+ * same statement and its workflow wakes; that publishes `escalation.resolved`,
+ * any other flag `escalation.updated`. Failures publish nothing.
+ */
+export declare function flagBatchItem(id: string, itemKey: string, input: FlagBatchItemInput): Promise<BatchFlagOutcome<FlagBatchItemOutcome>>;
+/** Clear one key's flag while the row is pending; publishes `escalation.updated`. */
+export declare function unflagBatchItem(id: string, itemKey: string): Promise<BatchFlagOutcome<UnflagBatchItemOutcome>>;

package/build/services/escalation/batch-flag.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flagBatchItem = flagBatchItem;
+exports.unflagBatchItem = unflagBatchItem;
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Flag one pending key of a batch escalation in a single SDK statement. The
+ * key stays pending. A row whose wait declared `wakeOnFlag` resolves in the
+ * same statement and its workflow wakes; that publishes `escalation.resolved`,
+ * any other flag `escalation.updated`. Failures publish nothing.
+ */
+async function flagBatchItem(id, itemKey, input) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.flagBatchItem({ id, itemKey, ...input });
+    if (!result.ok)
+        return { outcome: result.outcome, escalation: null };
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    publishFlagChange(escalation, itemKey, result.outcome === 'completed');
+    return { outcome: result.outcome, escalation };
+}
+/** Clear one key's flag while the row is pending; publishes `escalation.updated`. */
+async function unflagBatchItem(id, itemKey) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', escalation: null };
+    const client = await (0, client_1.escalations)();
+    const result = await client.unflagBatchItem({ id, itemKey });
+    if (!result.ok)
+        return { outcome: result.outcome, escalation: null };
+    const escalation = (0, map_1.toEscalationRecord)(result.entry);
+    publishFlagChange(escalation, itemKey, false);
+    return { outcome: result.outcome, escalation };
+}
+function publishFlagChange(escalation, itemKey, completed) {
+    (0, crud_1.publishEscalationChange)({
+        type: completed ? 'escalation.resolved' : 'escalation.updated',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: completed ? 'resolved' : 'pending',
+        data: (0, escalation_wire_1.escalationEventData)(escalation, { item_key: itemKey }),
+    });
+}

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

@@ -2,6 +2,7 @@ export * from './types';
 export * from './crud';
 export { claimAssertedByMetadata } from './claim-asserted';
 export * from './batch';
+export * from './batch-flag';
 export * from './accumulate';
 export * from './bulk';
 export * from './queries';

package/build/services/escalation/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./crud"), exports);
 var claim_asserted_1 = require("./claim-asserted");
 Object.defineProperty(exports, "claimAssertedByMetadata", { enumerable: true, get: function () { return claim_asserted_1.claimAssertedByMetadata; } });
 __exportStar(require("./batch"), exports);
+__exportStar(require("./batch-flag"), exports);
 __exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);
 __exportStar(require("./queries"), exports);

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

@@ -8,6 +8,8 @@
  * 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';
+import { type RosterCounts, type RosterDef, type RosterResult, 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>>;
+/** One roster's entries and counts, read the way the widget reads them. */
+export declare function loadRoster(def: RosterDef, ctx: ShowIfContext): Promise<RosterResult>;

package/build/services/escalation/roster.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadRosterCounts = loadRosterCounts;
+exports.loadRoster = loadRoster;
 /**
  * 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
@@ -18,10 +19,14 @@ 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;
+        counts[field] = (await loadRoster(def, ctx)).counts;
     }
     return counts;
 }
+/** One roster's entries and counts, read the way the widget reads them. */
+async function loadRoster(def, ctx) {
+    return (0, form_validation_1.computeRoster)(def, ctx, await readMemberRows(def, ctx));
+}
 async function readMemberRows(def, ctx) {
     const query = (0, form_validation_1.rosterQueryOf)(def);
     const scoped = query ? (0, form_validation_1.resolveRosterQuery)(query, ctx) : null;

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

@@ -10,6 +10,10 @@ function isSchemeList(value) {
 function isStringList(value) {
     return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === 'string' && v);
 }
+/** A form field name, as `hold.show` names one. */
+const HOLD_SHOW_FIELD = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** A fill's label map lives on the batch row: `envelope.<path>` or `metadata.<path>`. */
+const FILL_LABELS_PATH = /^(envelope|metadata)\.[A-Za-z0-9_.-]+$/;
 function isPlainObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -165,6 +169,9 @@ function assertValidHold(step, at) {
             throw new Error(`${at}: params.hold.expect.prompt must be markdown`);
         }
     }
+    if (hold.show !== undefined && (typeof hold.show !== 'string' || !HOLD_SHOW_FIELD.test(hold.show))) {
+        throw new Error(`${at}: params.hold.show must name a roster field of the held row's form`);
+    }
 }
 function assertValidFill(step, at) {
     const fill = step.params?.fill;
@@ -180,6 +187,15 @@ function assertValidFill(step, at) {
     if (fill.payload !== undefined && !isPlainObject(fill.payload)) {
         throw new Error(`${at}: params.fill.payload must be an object`);
     }
+    if (fill.labels !== undefined && (typeof fill.labels !== 'string' || !FILL_LABELS_PATH.test(fill.labels))) {
+        throw new Error(`${at}: params.fill.labels must name a map on the row, e.g. "envelope.labels"`);
+    }
+    if (fill.label !== undefined && (typeof fill.label !== 'string' || !fill.label.trim())) {
+        throw new Error(`${at}: params.fill.label must be a non-empty template`);
+    }
+    if (fill.label !== undefined && fill.labels === undefined) {
+        throw new Error(`${at}: params.fill.label requires params.fill.labels`);
+    }
     if (step.confirm)
         throw new Error(`${at}: fill cannot carry confirm`);
 }

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

@@ -127,6 +127,13 @@ function assertValidChoices(choices, at) {
             || choice.verb === types_1.SCAN_VERBS.FILL) {
             throw new Error(`${cat}: ${choice.verb} cannot be a choice verb`);
         }
+        if (choice.roles !== undefined && (!Array.isArray(choice.roles) || choice.roles.length === 0
+            || choice.roles.some((r) => typeof r !== 'string' || !r))) {
+            throw new Error(`${cat}: roles must be a non-empty array of role names`);
+        }
+        if (choice.refuse !== undefined && (typeof choice.refuse !== 'string' || !choice.refuse.trim())) {
+            throw new Error(`${cat}: refuse must be non-empty text`);
+        }
         if (choice.confirm && !choice.confirm.prompt) {
             throw new Error(`${cat}: confirm requires a prompt`);
         }

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

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

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

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

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

@@ -0,0 +1,80 @@
+/**
+ * x-lt-actions on a roster field: the acts an entry offers, read the same way
+ * by the dashboard (which shows them) and the API (which runs them). Each
+ * action is exactly one act:
+ *
+ *   { "label": "Missing",      "resolverPayload": { "outcome": "missing" } }  resolve the member row
+ *   { "label": "Key in",       "fill": { "payload": { "source": "key-in" }, "enterCode": true } }
+ *   { "label": "Missing",      "flag": { "label": "Missing" } }               flag the batch key
+ *   { "label": "Found it",     "unflag": true }                               clear the flag
+ *
+ * `when` names the entry states that offer it. `roles` limits who may run it:
+ * the action shows to everyone and runs only for a person holding one of the
+ * roles; `refuse` is what anyone else is told. The server re-reads the action
+ * from the row's form schema and decides; the dashboard only displays.
+ */
+import { type HelpTokenContext } from './x-lt-help';
+import { type RosterEntry, type RosterState } from './x-lt-roster';
+export declare const X_LT_ACTIONS = "x-lt-actions";
+export declare const ROSTER_ACTION_KINDS: {
+    readonly RESOLVE: "resolve";
+    readonly FILL: "fill";
+    readonly FLAG: "flag";
+    readonly UNFLAG: "unflag";
+};
+export type RosterActionKind = (typeof ROSTER_ACTION_KINDS)[keyof typeof ROSTER_ACTION_KINDS];
+/** The separator of counted batch keys when the roster names none. */
+export declare const ROSTER_KEY_SEPARATOR_DEFAULT = "#";
+/** The payload key a key-in records the entered code under. */
+export declare const ENTERED_CODE_KEY = "enteredCode";
+export interface RosterActionDef {
+    label: string;
+    /** The entry states that offer it; the default follows the act. */
+    when?: RosterState | RosterState[];
+    /** A confirmation asked in place before firing; tokens interpolate per entry. */
+    confirm?: string;
+    /** Resolve the entry's member row with this canned payload (a query set). */
+    resolverPayload?: Record<string, unknown>;
+    /** Fill the entry's batch key; `enterCode` asks for the code and checks it against the key. */
+    fill?: {
+        payload?: Record<string, unknown>;
+        enterCode?: boolean;
+    };
+    /** Flag the entry's batch key. */
+    flag?: {
+        label: string;
+        payload?: Record<string, unknown>;
+    };
+    /** Clear the entry's flag. */
+    unflag?: true;
+    /** Runs only for a person holding one of these roles. */
+    roles?: string[];
+    /** What a person without the roles is told. */
+    refuse?: string;
+}
+/** The one act an action declares, or null when it declares none or several. */
+export declare function rosterActionKind(action: RosterActionDef): RosterActionKind | null;
+/** The field's actions with a label and exactly one act, in declared order. */
+export declare function readRosterActions(fieldSchema: Record<string, unknown> | null | undefined): RosterActionDef[];
+/**
+ * True when the entry offers the action: the entry is in one of its states,
+ * and the act fits the entry (a resolve needs a member row; batch acts need
+ * a batch set).
+ */
+export declare function offersAction(action: RosterActionDef, entry: RosterEntry, batch: boolean): boolean;
+/** True when a person holding `roles` may run the action. */
+export declare function holdsActionRole(action: Pick<RosterActionDef, 'roles'>, roles: string[], superadmin?: boolean): boolean;
+/** What a person without the action's roles is told. */
+export declare function actionRefusal(action: Pick<RosterActionDef, 'label' | 'roles' | 'refuse'>): string;
+/** Deep-walk a payload template: string leaves interpolate against the context; other types pass through typed. */
+export declare function interpolatePayload(value: unknown, ctx: HelpTokenContext): unknown;
+/** The code a batch key names, without its ordinal suffix. */
+export declare function batchKeyCode(key: string, separator?: string): string;
+/** The batch key's code as its label prints it: a GTIN in its EAN-13 or EAN-8 form. */
+export declare function printedKeyCode(key: string, separator?: string): string;
+/**
+ * True when an entered code names the batch key's code. GTINs compare in
+ * their 14-digit form, so a UPC-A typed from the label matches its GTIN-14
+ * key; anything else compares as trimmed text.
+ */
+export declare function enteredCodeMatches(entered: string, key: string, separator?: string): boolean;