@hotmeshio/long-tail 0.30.4 → 0.30.5

package/build/api/scan-codes/open.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withOpen = withOpen;
+const escalationService = __importStar(require("../../services/escalation"));
+const types_1 = require("../../types");
+const OPEN_LABEL_DEFAULT = 'Open';
+/** The answers the station shows on its own screen: a hold, a refusal, a write's done copy. */
+function screenOf(data) {
+    if (data.outcome === types_1.SCAN_OUTCOMES.HELD && data.subject)
+        return 'hold';
+    if (data.outcome === types_1.SCAN_OUTCOMES.REFUSED)
+        return 'screen';
+    if (data.outcome === types_1.SCAN_OUTCOMES.EXECUTED
+        && (data.done || data.clearSubject || data.progress || data.already))
+        return 'screen';
+    return null;
+}
+/**
+ * Attach the step's Open button to the answer: on the held subject for a
+ * hold, so it stays while the row is held, else on the response. A target
+ * with no row, or a list facet the row does not carry, offers no button.
+ */
+async function withOpen(result, step, ctx) {
+    const data = result.data;
+    if (!step.open || !data)
+        return result;
+    const screen = screenOf(data);
+    if (!screen)
+        return result;
+    const link = await resolveOpen(step.open, ctx, data);
+    if (!link)
+        return result;
+    if (screen === 'hold')
+        return { ...result, data: { ...data, subject: { ...data.subject, open: link } } };
+    return { ...result, data: { ...data, open: link } };
+}
+async function resolveOpen(open, ctx, data) {
+    const row = await targetRow(open, ctx, data);
+    if (!row)
+        return null;
+    const label = open.label ?? OPEN_LABEL_DEFAULT;
+    if (!open.list)
+        return { label, escalationId: row.id, ...(open.claim ? { claim: true } : {}) };
+    const meta = (row.metadata ?? {});
+    const facets = {};
+    for (const key of open.list.facets) {
+        const value = meta[key];
+        if (!['string', 'number', 'boolean'].includes(typeof value) || value === '')
+            return null;
+        facets[key] = value;
+    }
+    return { label, facets, ...(open.list.role ? { role: open.list.role } : {}) };
+}
+/** The row the button opens: the one the step answered with, the held subject, or the scanned code's own row. */
+async function targetRow(open, ctx, data) {
+    const answered = data.escalation;
+    if (open.target === 'located')
+        return ctx.located ?? null;
+    if (open.target === 'subject' && data.outcome !== types_1.SCAN_OUTCOMES.HELD)
+        return ctx.subject?.row ?? null;
+    if (!answered?.id)
+        return null;
+    if (!open.list || answered.metadata)
+        return answered;
+    return escalationService.getEscalation(String(answered.id));
+}

package/build/api/scan-codes/present.js

@@ -117,6 +117,7 @@ async function presentStep(step, ctx) {
             escalation,
             choices,
             ...(step.facts ? { facts: renderFacts(step, ctx, escalation) } : {}),
+            ...(step.show ? { show: step.show } : {}),
             notPrimed: ctx.rule.notPrimed,
             ...(autoSelect ? { autoSelect: true } : {}),
         },

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

@@ -105,7 +105,7 @@ async function fillStep(step, ctx) {
             filled: batch.keys.length - batch.pending.length,
         },
     };
-    const candidates = keysFor(batch.pending, ctx.parsed.target, separator);
+    const candidates = (0, fill_labels_1.preferredKeys)(keysFor(batch.pending, ctx.parsed.target, separator), options, row, ctx.subject?.parsed.target);
     if (candidates.length === 0) {
         const declared = keysFor(batch.keys, ctx.parsed.target, separator);
         const markdown = declared.length

package/build/routes/escalations/resolve.js

@@ -171,6 +171,24 @@ function registerResolveRoutes(router) {
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/:id/roster-scan
+     * A scan into a batch roster on this row's form. The field must declare
+     * x-lt-scan accepting the code's scheme; the scan fills the first open entry
+     * whose key is the code, as the person acting (the badged person when
+     * X-LT-Acting-Token rides the request).
+     * Body: { field: string, code: string }
+     */
+    router.post('/:id/roster-scan', async (req, res) => {
+        const token = req.headers[acting_1.ACTING_TOKEN_HEADER];
+        const result = await api.runRosterScan({
+            id: req.params.id,
+            field: req.body?.field,
+            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/services/role/index.d.ts

@@ -84,6 +84,8 @@ export declare function getRoleFormSchema(role: string): Promise<Record<string,
 export declare function getRoleMetadataSchema(role: string): Promise<Record<string, any> | null>;
 /** The role's `properties` bag (incl. the reserved ROLE_PROPERTY_KEYS). One PK read. */
 export declare function getRoleProperties(role: string): Promise<Record<string, any> | null>;
+/** The role's display title, or null when it declares none. One PK read. */
+export declare function getRoleTitle(role: string): Promise<string | null>;
 /**
  * Delete a role. Returns an error message if the role is referenced.
  */

package/build/services/role/index.js

@@ -18,6 +18,7 @@ exports.getRoleListSchema = getRoleListSchema;
 exports.getRoleFormSchema = getRoleFormSchema;
 exports.getRoleMetadataSchema = getRoleMetadataSchema;
 exports.getRoleProperties = getRoleProperties;
+exports.getRoleTitle = getRoleTitle;
 exports.deleteRole = deleteRole;
 const list_schema_1 = require("../../shared/list-schema");
 const db_1 = require("../../lib/db");
@@ -252,6 +253,12 @@ async function getRoleProperties(role) {
     const { rows } = await pool.query(sql_1.GET_ROLE_PROPERTIES, [role]);
     return rows[0]?.properties ?? null;
 }
+/** The role's display title, or null when it declares none. One PK read. */
+async function getRoleTitle(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_TITLE, [role]);
+    return rows[0]?.title ?? null;
+}
 /**
  * Delete a role. Returns an error message if the role is referenced.
  */

package/build/services/role/scan-done.js

@@ -14,7 +14,7 @@ function scanDoneError(value) {
     if (typeof value !== 'object' || Array.isArray(value))
         return 'properties.scan_done must be an object';
     const done = value;
-    const known = new Set(['return', 'after_seconds']);
+    const known = new Set(['return', 'after_seconds', 'button']);
     const extra = Object.keys(done).filter((k) => !known.has(k));
     if (extra.length)
         return `properties.scan_done has unknown key(s): ${extra.join(', ')}`;
@@ -25,6 +25,9 @@ function scanDoneError(value) {
         && (!Number.isInteger(done.after_seconds) || done.after_seconds < 0 || done.after_seconds > AFTER_SECONDS_MAX)) {
         return `properties.scan_done.after_seconds must be an integer from 0 to ${AFTER_SECONDS_MAX}`;
     }
+    if (done.button !== undefined && (typeof done.button !== 'string' || !done.button.trim())) {
+        return 'properties.scan_done.button must be non-empty text';
+    }
     return null;
 }
 /** The role's return policy from its properties bag, or null when it declares none (or an unusable one). */

package/build/services/role/sql.d.ts

@@ -80,6 +80,7 @@ export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_role
 export declare const LIST_ENFORCING_ROLES = "\n  SELECT role FROM lt_roles WHERE enforce_schema";
 export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_PROPERTIES = "\n  SELECT properties FROM lt_roles WHERE role = $1";
+export declare const GET_ROLE_TITLE = "\n  SELECT title FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_UPSTREAMS = "\n  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role";
 export declare const LIST_ROLE_SCHEMA_VERSIONS = "\n  SELECT\n    s.version,\n    s.form_schema IS NOT NULL     AS has_form_schema,\n    s.metadata_schema IS NOT NULL AS has_metadata_schema,\n    s.change_summary,\n    s.created_at,\n    s.version = r.current_schema_version AS is_current\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1\n  ORDER BY s.version DESC";
 export declare const GET_ROLE_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.form_schema, s.metadata_schema,\n         s.change_summary, s.created_at, r.current_schema_version AS latest_version\n  FROM lt_role_schemas s\n  JOIN lt_roles r ON r.role = s.role\n  WHERE s.role = $1 AND s.version = $2";

package/build/services/role/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_PROPERTIES = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.GET_ROLE_ROW = exports.LIST_CONFIGURED_ROLES = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_LIST_SCHEMA_CURRENT = exports.GET_ROLE_LIST_SCHEMA_VERSION = exports.LIST_ROLE_LIST_SCHEMA_VERSIONS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_TITLE = exports.GET_ROLE_PROPERTIES = exports.GET_ROLE_METADATA_SCHEMA = exports.LIST_ENFORCING_ROLES = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.GET_ROLE_ROW = exports.LIST_CONFIGURED_ROLES = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -197,6 +197,8 @@ exports.GET_ROLE_METADATA_SCHEMA = `
   SELECT metadata_schema FROM lt_roles WHERE role = $1`;
 exports.GET_ROLE_PROPERTIES = `
   SELECT properties FROM lt_roles WHERE role = $1`;
+exports.GET_ROLE_TITLE = `
+  SELECT title FROM lt_roles WHERE role = $1`;
 exports.GET_ROLE_UPSTREAMS = `
   SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role`;
 // ─── Versioned role schemas ─────────────────────────────────────────────────

package/build/services/role/types.d.ts

@@ -43,6 +43,8 @@ export interface RoleScanDone {
     return: 'home' | string;
     /** Seconds the done copy stays up first (0-60, default 2). */
     after_seconds?: number;
+    /** A button on the done screen that returns at once, e.g. "Done". */
+    button?: string;
 }
 /** A station role's badge policy. Absent fields keep the badge scheme's value. */
 export interface RoleBadgeGrant {

package/build/services/scan-code/index.d.ts

@@ -1,5 +1,5 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
 export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
-export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, renderScanCopy, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, mentionsLocatedToken, renderScanCopy, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
 export { assertValidScheme, assertValidSteps, assertValidIdentityRule, assertSchemesCoexist, } from './validate';
 export { isValidGtin, normalizeGtin, displayGtin } from '../../shared/scan-code';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertSchemesCoexist = exports.assertValidIdentityRule = exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.renderScanCopy = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
+exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertSchemesCoexist = exports.assertValidIdentityRule = exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.renderScanCopy = exports.mentionsLocatedToken = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
 var read_1 = require("./read");
 Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return read_1.listScanSchemes; } });
 Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return read_1.getScanScheme; } });
@@ -19,6 +19,7 @@ var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "interpolateScanTemplate", { enumerable: true, get: function () { return parse_1.interpolateScanTemplate; } });
 Object.defineProperty(exports, "mentionsClaimToken", { enumerable: true, get: function () { return parse_1.mentionsClaimToken; } });
+Object.defineProperty(exports, "mentionsLocatedToken", { enumerable: true, get: function () { return parse_1.mentionsLocatedToken; } });
 Object.defineProperty(exports, "renderScanCopy", { enumerable: true, get: function () { return parse_1.renderScanCopy; } });
 Object.defineProperty(exports, "ScanTemplateError", { enumerable: true, get: function () { return parse_1.ScanTemplateError; } });
 var validate_1 = require("./validate");

package/build/services/scan-code/parse.d.ts

@@ -27,6 +27,8 @@ export interface ScanTemplateContext {
     container?: Record<string, unknown>;
     /** The batch a fill step read: `pending`, `total`, `filled`. */
     fill?: Record<string, unknown>;
+    /** The scanned code's own pending row: its metadata plus `id`, `role` and `roleTitle`. */
+    located?: Record<string, unknown>;
 }
 /** A bag token the context cannot resolve. */
 export declare class ScanTemplateError extends Error {
@@ -36,11 +38,13 @@ export declare class ScanTemplateError extends Error {
 }
 /** True when any string in the params mentions a `{claim.…}` token. */
 export declare function mentionsClaimToken(value: unknown): boolean;
+/** True when any string in the value mentions a `{located.…}` token. */
+export declare function mentionsLocatedToken(value: unknown): boolean;
 /**
  * Replace the template tokens inside string values of a params object.
  * Deep, pure, non-mutating. The scan tokens are plain text replacement; the
  * bag tokens (`{claim.x}`, `{item.x}`, `{subject.x}`, `{container.x}`,
- * `{fill.x}`) read the context's facet bags and throw
+ * `{fill.x}`, `{located.x}`) read the context's facet bags and throw
  * {@link ScanTemplateError} when they cannot resolve, so a literal token
  * never reaches a row. No expression language.
  */

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScanTemplateError = void 0;
 exports.parseScanCode = parseScanCode;
 exports.mentionsClaimToken = mentionsClaimToken;
+exports.mentionsLocatedToken = mentionsLocatedToken;
 exports.interpolateScanTemplate = interpolateScanTemplate;
 exports.renderScanCopy = renderScanCopy;
 const scan_code_1 = require("../../shared/scan-code");
@@ -21,18 +22,23 @@ class ScanTemplateError extends Error {
     }
 }
 exports.ScanTemplateError = ScanTemplateError;
-const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([a-zA-Z0-9_]+)\}/g;
+const BAG_TOKEN = /\{(claim|item|subject|container|fill|located)\.([a-zA-Z0-9_]+)\}/g;
 const MISSING_BAG = {
     claim: 'the actor holds no single live claim',
     item: 'no located item row on this step',
     subject: 'no subject is held',
     container: 'no container was located',
     fill: 'no batch was read',
+    located: 'the scanned code has no pending row the reader can read',
 };
 /** True when any string in the params mentions a `{claim.…}` token. */
 function mentionsClaimToken(value) {
     return JSON.stringify(value ?? null).includes(`{${types_1.SCAN_TEMPLATE_BAGS.CLAIM}.`);
 }
+/** True when any string in the value mentions a `{located.…}` token. */
+function mentionsLocatedToken(value) {
+    return JSON.stringify(value ?? null).includes(`{${types_1.SCAN_TEMPLATE_BAGS.LOCATED}.`);
+}
 function resolveBagToken(ctx, bag, facet, token) {
     const source = ctx[bag];
     if (!source)
@@ -49,7 +55,7 @@ function resolveBagToken(ctx, bag, facet, token) {
  * Replace the template tokens inside string values of a params object.
  * Deep, pure, non-mutating. The scan tokens are plain text replacement; the
  * bag tokens (`{claim.x}`, `{item.x}`, `{subject.x}`, `{container.x}`,
- * `{fill.x}`) read the context's facet bags and throw
+ * `{fill.x}`, `{located.x}`) read the context's facet bags and throw
  * {@link ScanTemplateError} when they cannot resolve, so a literal token
  * never reaches a row. No expression language.
  */

package/build/services/scan-code/validate-station.d.ts

@@ -0,0 +1,13 @@
+import { type ScanDoneCopy, type ScanStep, type ScanVerb } from '../../types';
+/** A form field name, as `hold.show` and a present step's `show` name one. */
+export declare const ROSTER_FIELD: RegExp;
+/** The longest a done screen waits before the station returns. */
+export declare const SCAN_DONE_AFTER_SECONDS_MAX = 60;
+/** A done copy: markdown, an optional pause before the station returns, and the line under it. */
+export declare function assertValidDoneCopy(done: ScanDoneCopy | undefined, at: string, field?: string): void;
+/** `done` on a step or a choice that writes. */
+export declare function assertValidDone(done: ScanDoneCopy | undefined, verb: ScanVerb, at: string, kind?: 'steps' | 'choices'): void;
+/** `open`: the Open button on the hold, done or refusal screen a step answers with. */
+export declare function assertValidOpen(step: ScanStep, at: string): void;
+/** `show` on a present step: the roster field rendered above the choices. */
+export declare function assertValidPresentShow(step: ScanStep, at: string): void;

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

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCAN_DONE_AFTER_SECONDS_MAX = exports.ROSTER_FIELD = void 0;
+exports.assertValidDoneCopy = assertValidDoneCopy;
+exports.assertValidDone = assertValidDone;
+exports.assertValidOpen = assertValidOpen;
+exports.assertValidPresentShow = assertValidPresentShow;
+const types_1 = require("../../types");
+const facet_sql_1 = require("../escalation/facet-sql");
+/** A form field name, as `hold.show` and a present step's `show` name one. */
+exports.ROSTER_FIELD = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** The longest a done screen waits before the station returns. */
+exports.SCAN_DONE_AFTER_SECONDS_MAX = 60;
+const OPEN_TARGETS = new Set(['row', 'subject', 'located']);
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** A done copy: markdown, an optional pause before the station returns, and the line under it. */
+function assertValidDoneCopy(done, at, field = 'done') {
+    if (!isPlainObject(done) || typeof done.markdown !== 'string' || !done.markdown) {
+        throw new Error(`${at}: ${field}.markdown is required`);
+    }
+    const after = done.afterSeconds;
+    if (after !== undefined && (typeof after !== 'number' || !Number.isInteger(after)
+        || after < 0 || after > exports.SCAN_DONE_AFTER_SECONDS_MAX)) {
+        throw new Error(`${at}: ${field}.afterSeconds must be an integer from 0 to ${exports.SCAN_DONE_AFTER_SECONDS_MAX}`);
+    }
+    if (done.nextPrompt !== undefined && (typeof done.nextPrompt !== 'string' || !done.nextPrompt.trim())) {
+        throw new Error(`${at}: ${field}.nextPrompt must be non-empty markdown`);
+    }
+}
+/** `done` on a step or a choice that writes. */
+function assertValidDone(done, verb, at, kind = 'steps') {
+    if (done === undefined)
+        return;
+    assertValidDoneCopy(done, at);
+    if (!types_1.SCAN_MUTATING_VERBS.includes(verb))
+        throw new Error(`${at}: done applies only to ${kind} that write`);
+}
+/** `open`: the Open button on the hold, done or refusal screen a step answers with. */
+function assertValidOpen(step, at) {
+    const open = step.open;
+    if (open === undefined)
+        return;
+    if (!isPlainObject(open))
+        throw new Error(`${at}: open must be an object`);
+    if (!OPEN_TARGETS.has(open.target)) {
+        throw new Error(`${at}: open.target must be 'row', 'subject' or 'located'`);
+    }
+    if (open.target === 'subject' && !step.subject && step.verb !== types_1.SCAN_VERBS.HOLD) {
+        throw new Error(`${at}: open.target 'subject' needs a held subject (a hold step, or a step with a subject gate)`);
+    }
+    if (open.label !== undefined && (typeof open.label !== 'string' || !open.label.trim())) {
+        throw new Error(`${at}: open.label must be non-empty text`);
+    }
+    if (open.claim !== undefined && typeof open.claim !== 'boolean') {
+        throw new Error(`${at}: open.claim must be a boolean`);
+    }
+    if (open.list !== undefined) {
+        const list = open.list;
+        if (!isPlainObject(list) || !Array.isArray(list.facets) || list.facets.length === 0
+            || !list.facets.every((f) => typeof f === 'string' && facet_sql_1.FACET_KEY.test(f))) {
+            throw new Error(`${at}: open.list.facets must be a non-empty array of facet keys`);
+        }
+        if (list.role !== undefined && (typeof list.role !== 'string' || !list.role)) {
+            throw new Error(`${at}: open.list.role must be a role name`);
+        }
+        if (open.claim)
+            throw new Error(`${at}: open.claim applies to a row, not a list`);
+    }
+}
+/** `show` on a present step: the roster field rendered above the choices. */
+function assertValidPresentShow(step, at) {
+    if (step.show === undefined)
+        return;
+    if (step.verb !== types_1.SCAN_VERBS.PRESENT)
+        throw new Error(`${at}: show applies only to present steps (a hold uses params.hold.show)`);
+    if (typeof step.show !== 'string' || !exports.ROSTER_FIELD.test(step.show)) {
+        throw new Error(`${at}: show must name a roster field of the row's form`);
+    }
+}

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertValidSubjectStep = assertValidSubjectStep;
 const types_1 = require("../../types");
 const facet_sql_1 = require("../escalation/facet-sql");
+const validate_station_1 = require("./validate-station");
 function isSchemeList(value) {
     return Array.isArray(value) && value.length > 0
         && value.every((v) => Number.isInteger(v) && v >= 10 && v <= 99);
@@ -10,9 +11,7 @@ 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>`. */
+/** A fill's per-key maps live 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);
@@ -91,8 +90,8 @@ function assertValidSubjectStep(step, at) {
             if (!isStringList(step.match.facets) || !step.match.facets.every((f) => facet_sql_1.FACET_KEY.test(f))) {
                 throw new Error(`${at}: match.facets must be a non-empty array of facet keys`);
             }
-            if (accumulate?.from !== 'subject') {
-                throw new Error(`${at}: match.facets compares the located container, which only a from-subject accumulate has`);
+            if (accumulate?.from !== 'subject' && !(accumulate?.into === 'subject' && accumulate.item)) {
+                throw new Error(`${at}: match.facets compares the subject with a located row: the container of a from-subject accumulate, or the item's own row of an into-subject accumulate with item`);
             }
         }
     }
@@ -169,9 +168,30 @@ 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))) {
+    if (hold.show !== undefined && (typeof hold.show !== 'string' || !validate_station_1.ROSTER_FIELD.test(hold.show))) {
         throw new Error(`${at}: params.hold.show must name a roster field of the held row's form`);
     }
+    if (hold.release !== undefined)
+        assertValidRelease(hold.release, at);
+    if (hold.whenAllIn !== undefined) {
+        if (hold.show === undefined)
+            throw new Error(`${at}: params.hold.whenAllIn requires params.hold.show`);
+        (0, validate_station_1.assertValidDoneCopy)(hold.whenAllIn, at, 'params.hold.whenAllIn');
+    }
+}
+function assertValidRelease(release, at) {
+    if (!isPlainObject(release))
+        throw new Error(`${at}: params.hold.release must be an object`);
+    if (release.label !== undefined && (typeof release.label !== 'string' || !release.label.trim())) {
+        throw new Error(`${at}: params.hold.release.label must be non-empty text`);
+    }
+    if (release.tone !== undefined && release.tone !== 'neutral' && release.tone !== 'accent') {
+        throw new Error(`${at}: params.hold.release.tone must be 'neutral' or 'accent'`);
+    }
+    if (release.return !== undefined
+        && (typeof release.return !== 'string' || !(release.return === 'home' || release.return.startsWith('/')))) {
+        throw new Error(`${at}: params.hold.release.return must be 'home' or a dashboard-relative route`);
+    }
 }
 function assertValidFill(step, at) {
     const fill = step.params?.fill;
@@ -196,6 +216,13 @@ function assertValidFill(step, at) {
     if (fill.label !== undefined && fill.labels === undefined) {
         throw new Error(`${at}: params.fill.label requires params.fill.labels`);
     }
+    if (fill.prefer !== undefined) {
+        if (typeof fill.prefer !== 'string' || !FILL_LABELS_PATH.test(fill.prefer)) {
+            throw new Error(`${at}: params.fill.prefer must name a map on the row, e.g. "envelope.key_owners"`);
+        }
+        if (fill.into !== 'subject')
+            throw new Error(`${at}: params.fill.prefer compares with the held subject, so it needs into: 'subject'`);
+    }
     if (step.confirm)
         throw new Error(`${at}: fill cannot carry confirm`);
 }

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

@@ -10,6 +10,7 @@ const facet_sql_1 = require("../escalation/facet-sql");
 const validate_subject_1 = require("./validate-subject");
 const validate_query_1 = require("./validate-query");
 const validate_facts_1 = require("./validate-facts");
+const validate_station_1 = require("./validate-station");
 const validate_scheme_pattern_1 = require("./validate-scheme-pattern");
 const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
 /** Double-scan selection tokens — short, label-printable, never scheme-shaped. */
@@ -156,14 +157,7 @@ function assertValidChoices(choices, at) {
                 throw new Error(`${cat}: duplicate code "${choice.code}"`);
             codes.add(choice.code);
         }
-        if (choice.done !== undefined) {
-            if (!choice.done || typeof choice.done !== 'object' || typeof choice.done.markdown !== 'string' || !choice.done.markdown) {
-                throw new Error(`${cat}: done.markdown is required`);
-            }
-            if (!types_1.SCAN_MUTATING_VERBS.includes(choice.verb)) {
-                throw new Error(`${cat}: done applies only to choices that write`);
-            }
-        }
+        (0, validate_station_1.assertValidDone)(choice.done, choice.verb, cat, 'choices');
         if (choice.hidden !== undefined) {
             if (typeof choice.hidden !== 'boolean')
                 throw new Error(`${cat}: hidden must be a boolean`);
@@ -293,14 +287,9 @@ function assertValidSteps(steps) {
             }
         }
         (0, validate_subject_1.assertValidSubjectStep)(step, at);
-        if (step.done !== undefined) {
-            if (!step.done || typeof step.done !== 'object' || typeof step.done.markdown !== 'string' || !step.done.markdown) {
-                throw new Error(`${at}: done.markdown is required`);
-            }
-            if (!types_1.SCAN_MUTATING_VERBS.includes(step.verb)) {
-                throw new Error(`${at}: done applies only to steps that write`);
-            }
-        }
+        (0, validate_station_1.assertValidDone)(step.done, step.verb, at);
+        (0, validate_station_1.assertValidOpen)(step, at);
+        (0, validate_station_1.assertValidPresentShow)(step, at);
         assertValidFollow(step, at);
         assertValidTemplateTokens(step, at);
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
@@ -322,7 +311,7 @@ function assertValidSteps(steps) {
         }
     });
 }
-const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([^}]*)\}/g;
+const BAG_TOKEN = /\{(claim|item|subject|container|fill|located)\.([^}]*)\}/g;
 /**
  * Bag tokens name facet keys and may only read what the step has:
  * `{item.…}` the row an item-mode accumulate, an into-subject accumulate
@@ -330,7 +319,9 @@ const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([^}]*)\}/g;
  * presents),
  * `{subject.…}` the held subject (steps with a subject gate), and
  * `{container.…}` / `{fill.…}` only inside refusal and done copy, where a
- * subject accumulate or a fill has read them (into-subject: the held row).
+ * subject accumulate or a fill has read them (into-subject: the held row),
+ * and `{located.…}` (the scanned code's own pending row) only inside refusal
+ * and done copy.
  */
 function assertValidTemplateTokens(step, at) {
     const accumulate = step.verb === types_1.SCAN_VERBS.ACCUMULATE ? step.params?.accumulate : undefined;
@@ -355,6 +346,9 @@ function assertValidTemplateTokens(step, at) {
             if (bag === 'fill' && !(inRefusal && step.verb === types_1.SCAN_VERBS.FILL)) {
                 throw new Error(`${at}: ${token} is readable only in the refusal or done copy of a fill step`);
             }
+            if (bag === 'located' && !inRefusal) {
+                throw new Error(`${at}: ${token} is readable only in refusal or done copy`);
+            }
         }
     };
     check(step.params, false);