@hotmeshio/long-tail 0.30.4 → 0.31.0

package/build/services/labels/templates/write.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelTemplateConflictError = void 0;
+exports.upsertLabelTemplate = upsertLabelTemplate;
+exports.deleteLabelTemplate = deleteLabelTemplate;
+exports.seedLabelTemplate = seedLabelTemplate;
+exports.applyLabelTemplate = applyLabelTemplate;
+const db_1 = require("../../../lib/db");
+const types_1 = require("../../../types");
+const scan_code_1 = require("../../scan-code");
+const user_1 = require("../../user");
+const media_1 = require("../media");
+const read_1 = require("./read");
+const sql_1 = require("./sql");
+const validate_1 = require("./validate");
+/** An API write raced another: the stored revision is not the one the caller read. */
+class LabelTemplateConflictError extends Error {
+    constructor(name, revision) {
+        super(`label template "${name}" changed (now revision ${revision}); reload and try again`);
+        this.status = 409;
+        this.name = 'LabelTemplateConflictError';
+    }
+}
+exports.LabelTemplateConflictError = LabelTemplateConflictError;
+async function validated(input) {
+    const [scheme, rules, identityKeys] = await Promise.all([
+        (0, scan_code_1.getScanScheme)(input.scheme_version),
+        (0, scan_code_1.listScanRules)(input.scheme_version),
+        (0, user_1.getIdentityPropertyKeys)(),
+    ]);
+    (0, validate_1.assertValidTemplate)(input, { scheme, rules, identityKeys, mediaIds: (0, media_1.labelMediaPresets)().map((m) => m.id) });
+    return { ...input, sensitive: scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY || !!input.sensitive };
+}
+function params(input, source) {
+    return [
+        input.name,
+        input.scheme_version,
+        input.title,
+        input.description ?? null,
+        JSON.stringify(input.codes.map((c) => ({ category: c.category, caption: c.caption ?? null, tone: c.tone }))),
+        JSON.stringify({ title: input.text?.title ?? '', lines: input.text?.lines ?? [] }),
+        input.symbology ?? 'code128',
+        input.human_readable ?? true,
+        input.media ?? null,
+        input.sensitive,
+        input.enabled ?? true,
+        source,
+    ];
+}
+/**
+ * Create or replace a template from the API. With `expectedRevision`, the
+ * write lands only on that revision; otherwise LabelTemplateConflictError.
+ */
+async function upsertLabelTemplate(input, expectedRevision) {
+    const row = await validated(input);
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_TEMPLATE, [...params(row, 'api'), expectedRevision ?? null]);
+    if (rows[0])
+        return (0, read_1.mapTemplate)(rows[0]);
+    const current = await (0, db_1.getPool)().query(sql_1.GET_TEMPLATE, [input.name]);
+    throw new LabelTemplateConflictError(input.name, current.rows[0]?.revision ?? 0);
+}
+async function deleteLabelTemplate(name) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.DELETE_TEMPLATE, [name]);
+    return (rowCount ?? 0) > 0;
+}
+/** Insert a template only when absent (database-owned configuration). */
+async function seedLabelTemplate(input) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_TEMPLATE, params(await validated(input), 'api'));
+    return (rowCount ?? 0) > 0;
+}
+/** Apply a template declared in code; unchanged declarations write nothing. */
+async function applyLabelTemplate(input) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.APPLY_TEMPLATE, params(await validated(input), 'code'));
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}

package/build/services/labels/token.d.ts

@@ -0,0 +1,9 @@
+import type { ScanScheme } from '../../types';
+/** Characters in a minted delimited credential when the scheme sets no target_length (about 50 bits). */
+export declare const DEFAULT_IDENTITY_TOKEN_LENGTH = 10;
+/**
+ * A random credential for the scheme: Crockford base32 of the scheme's
+ * target_length (default 10) when delimited, that many digits when fixed.
+ * The scheme prefix is added when the code is composed, never stored.
+ */
+export declare function mintIdentityToken(scheme: Pick<ScanScheme, 'encoding' | 'target_length'>): string;

package/build/services/labels/token.js

@@ -0,0 +1,28 @@
+"use strict";
+// New identity credentials, minted to fit the scheme's encoding.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IDENTITY_TOKEN_LENGTH = void 0;
+exports.mintIdentityToken = mintIdentityToken;
+const crypto_1 = require("crypto");
+const errors_1 = require("./errors");
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Characters in a minted delimited credential when the scheme sets no target_length (about 50 bits). */
+exports.DEFAULT_IDENTITY_TOKEN_LENGTH = 10;
+/**
+ * A random credential for the scheme: Crockford base32 of the scheme's
+ * target_length (default 10) when delimited, that many digits when fixed.
+ * The scheme prefix is added when the code is composed, never stored.
+ */
+function mintIdentityToken(scheme) {
+    if (scheme.encoding === 'delimited') {
+        const bytes = (0, crypto_1.randomBytes)(scheme.target_length ?? exports.DEFAULT_IDENTITY_TOKEN_LENGTH);
+        return Array.from(bytes, (b) => CROCKFORD[b % 32]).join('');
+    }
+    if (scheme.encoding === 'fixed') {
+        const length = scheme.target_length ?? 0;
+        if (length < 1)
+            throw new errors_1.LabelRequestError(400, 'the scheme has no target length');
+        return Array.from({ length }, () => String((0, crypto_1.randomInt)(10))).join('');
+    }
+    throw new errors_1.LabelRequestError(400, `credentials are minted for fixed and delimited schemes, not ${scheme.encoding}`);
+}

package/build/services/labels/verify.d.ts

@@ -0,0 +1,4 @@
+import { type ScanRule, type ScanScheme } from '../../types';
+import type { LabelContent, LabelWarning } from '../../shared/labels/types';
+import type { LabelTarget, LabelTemplate } from '../../types/labels';
+export declare function verifyLabels(template: LabelTemplate, scheme: ScanScheme, schemes: ScanScheme[], rules: ScanRule[], targets: LabelTarget[], contents: LabelContent[]): LabelWarning[];

package/build/services/labels/verify.js

@@ -0,0 +1,38 @@
+"use strict";
+// Flags labels that would fail on the floor: a code that does not parse back,
+// a disabled rule or scheme, or a target that names nothing today.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyLabels = verifyLabels;
+const parse_1 = require("../../shared/scan-code/parse");
+const types_1 = require("../../types");
+function verifyLabels(template, scheme, schemes, rules, targets, contents) {
+    const identity = scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY;
+    const warnings = [];
+    if (!scheme.enabled) {
+        contents.forEach((_c, index) => warnings.push({ index, kind: 'unparseable', detail: `scheme ${scheme.version} is disabled; its codes do not scan` }));
+        return warnings;
+    }
+    const disabled = template.codes.filter((c) => !rules.find((r) => r.category === c.category)?.enabled);
+    contents.forEach((content, index) => {
+        for (const c of disabled) {
+            warnings.push({ index, kind: 'rule_disabled', detail: `the rule for category ${c.category} is disabled; that code does nothing when scanned` });
+        }
+        for (const { code } of content.codes) {
+            const parsed = (0, parse_1.parseScanCode)(code, schemes);
+            const same = parsed.ok && parsed.parsed.version === scheme.version && parsed.parsed.target === targets[index].target;
+            if (!same) {
+                warnings.push({
+                    index, kind: 'unparseable',
+                    detail: identity ? 'a badge code does not read back as this scheme' : `${code} does not read back as scheme ${scheme.version}`,
+                });
+            }
+        }
+        if (targets[index].resolved === false) {
+            warnings.push({
+                index, kind: 'unresolved',
+                detail: identity ? 'the badge holder is not an active user' : `${targets[index].target} names no row today`,
+            });
+        }
+    });
+    return warnings;
+}

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.d.ts

@@ -4,6 +4,9 @@ import { type ScanScheme, type ScanStep } from '../../types';
  * problem — a bad scheme silently misparsing every scan is far worse
  * than a loud upsert failure.
  */
+/** Generated badges on a delimited identity scheme: long enough to resist guessing, short enough to scan. */
+export declare const IDENTITY_TOKEN_MIN_LENGTH = 8;
+export declare const IDENTITY_TOKEN_MAX_LENGTH = 64;
 export declare function assertValidScheme(scheme: Partial<ScanScheme>): void;
 /**
  * A scheme must read codes no other scheme reads. Delimited and fixed

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_TOKEN_MAX_LENGTH = exports.IDENTITY_TOKEN_MIN_LENGTH = void 0;
 exports.assertValidScheme = assertValidScheme;
 exports.assertSchemesCoexist = assertSchemesCoexist;
 exports.assertValidIdentityRule = assertValidIdentityRule;
@@ -10,6 +11,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. */
@@ -19,6 +21,9 @@ const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
  * problem — a bad scheme silently misparsing every scan is far worse
  * than a loud upsert failure.
  */
+/** Generated badges on a delimited identity scheme: long enough to resist guessing, short enough to scan. */
+exports.IDENTITY_TOKEN_MIN_LENGTH = 8;
+exports.IDENTITY_TOKEN_MAX_LENGTH = 64;
 function assertValidScheme(scheme) {
     if (!Number.isInteger(scheme.version) || scheme.version < 10 || scheme.version > 99) {
         throw new Error('scheme version must be a two-digit integer between 10 and 99');
@@ -52,6 +57,12 @@ function assertValidScheme(scheme) {
     if (kind !== types_1.SCAN_SCHEME_KINDS.ACTION && kind !== types_1.SCAN_SCHEME_KINDS.IDENTITY) {
         throw new Error(`unknown scheme kind "${kind}"`);
     }
+    if (kind === types_1.SCAN_SCHEME_KINDS.IDENTITY && encoding === types_1.SCAN_ENCODINGS.DELIMITED && scheme.target_length != null) {
+        const length = scheme.target_length;
+        if (!Number.isInteger(length) || length < exports.IDENTITY_TOKEN_MIN_LENGTH || length > exports.IDENTITY_TOKEN_MAX_LENGTH) {
+            throw new Error(`a delimited identity scheme's target_length (the length of a generated badge) must be ${exports.IDENTITY_TOKEN_MIN_LENGTH} to ${exports.IDENTITY_TOKEN_MAX_LENGTH}`);
+        }
+    }
     if (kind === types_1.SCAN_SCHEME_KINDS.IDENTITY) {
         const ttl = scheme.grant_ttl_seconds;
         if (!Number.isInteger(ttl) || ttl < 1 || ttl > 86_400) {
@@ -156,14 +167,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 +297,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 +321,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 +329,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 +356,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);