@hotmeshio/long-tail 0.22.1 → 0.22.2

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

@@ -1,9 +1,6 @@
+import { type ScanParseFailure } from '../../shared/scan-code';
 import { type ParsedScanCode, type ScanScheme } from '../../types';
-export interface ScanParseFailure {
-    /** Why the code did not parse. */
-    reason: 'empty' | 'unknown_version' | 'scheme_disabled' | 'malformed';
-    detail: string;
-}
+export type { ScanParseFailure };
 export type ScanParseResult = {
     ok: true;
     parsed: ParsedScanCode;
@@ -12,26 +9,26 @@ export type ScanParseResult = {
     ok: false;
     failure: ScanParseFailure;
 };
-/**
- * Parse a raw scan string against the configured schemes. Pure — no I/O.
- *
- * The leading TWO digits pick the scheme (10-99, so a code never starts with a
- * leading zero); the scheme then defines how the remainder splits into a
- * single-digit category (0-9) and the target:
- * - delimited: `10:1:ABC-123` (delimiter from the scheme row)
- * - fixed:     `1017554332` (one category digit, then target_length digits)
- */
+/** Parse a raw scan string against the configured schemes. Pure; see shared/scan-code. */
 export declare function parseScanCode(raw: string, schemes: ScanScheme[]): ScanParseResult;
 export interface ScanTemplateContext {
     target: string;
     category: string;
     scannedAt: string;
+    /** The code as scanned; defaults to the target. */
+    code?: string;
     /** The acting user's single live claim, its metadata; absent when none or ambiguous. */
     claim?: Record<string, unknown>;
-    /** The row an item-mode accumulate step located, its metadata. */
+    /** The row the step located (item-mode accumulate, hold), its metadata. */
     item?: Record<string, unknown>;
+    /** The held subject's row: its metadata plus `id`. */
+    subject?: Record<string, unknown>;
+    /** The container a subject step located, its metadata. */
+    container?: Record<string, unknown>;
+    /** The batch a fill step read: `pending`, `total`, `filled`. */
+    fill?: Record<string, unknown>;
 }
-/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+/** A bag token the context cannot resolve. */
 export declare class ScanTemplateError extends Error {
     readonly token: string;
     readonly reason: string;
@@ -41,9 +38,15 @@ export declare class ScanTemplateError extends Error {
 export declare function mentionsClaimToken(value: unknown): boolean;
 /**
  * Replace the template tokens inside string values of a params object.
- * Deep, pure, non-mutating. The three scan tokens are plain text
- * replacement; `{claim.<facet>}` and `{item.<facet>}` 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.
+ * 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
+ * {@link ScanTemplateError} when they cannot resolve, so a literal token
+ * never reaches a row. No expression language.
  */
 export declare function interpolateScanTemplate<T>(value: T, ctx: ScanTemplateContext): T;
+/**
+ * Render refusal copy, degrading instead of failing: a token with nothing to
+ * read becomes an empty string, so a refusal always has words to show.
+ */
+export declare function renderScanCopy(markdown: string, ctx: ScanTemplateContext): string;

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

@@ -4,87 +4,14 @@ exports.ScanTemplateError = void 0;
 exports.parseScanCode = parseScanCode;
 exports.mentionsClaimToken = mentionsClaimToken;
 exports.interpolateScanTemplate = interpolateScanTemplate;
+exports.renderScanCopy = renderScanCopy;
+const scan_code_1 = require("../../shared/scan-code");
 const types_1 = require("../../types");
-/**
- * Parse a raw scan string against the configured schemes. Pure — no I/O.
- *
- * The leading TWO digits pick the scheme (10-99, so a code never starts with a
- * leading zero); the scheme then defines how the remainder splits into a
- * single-digit category (0-9) and the target:
- * - delimited: `10:1:ABC-123` (delimiter from the scheme row)
- * - fixed:     `1017554332` (one category digit, then target_length digits)
- */
+/** Parse a raw scan string against the configured schemes. Pure; see shared/scan-code. */
 function parseScanCode(raw, schemes) {
-    const code = raw.trim();
-    if (!code) {
-        return { ok: false, failure: { reason: 'empty', detail: 'empty scan code' } };
-    }
-    const versionToken = code.slice(0, 2);
-    const version = Number(versionToken);
-    if (!/^[0-9]{2}$/.test(versionToken) || version < 10 || version > 99) {
-        return {
-            ok: false,
-            failure: { reason: 'unknown_version', detail: `code must start with a two-digit scheme 10-99, got "${versionToken}"` },
-        };
-    }
-    const scheme = schemes.find((s) => s.version === version);
-    if (!scheme) {
-        return {
-            ok: false,
-            failure: { reason: 'unknown_version', detail: `no scan scheme configured for version ${version}` },
-        };
-    }
-    if (!scheme.enabled) {
-        return {
-            ok: false,
-            failure: { reason: 'scheme_disabled', detail: `scan scheme ${version} ("${scheme.name}") is disabled` },
-        };
-    }
-    if (scheme.encoding === types_1.SCAN_ENCODINGS.DELIMITED) {
-        return parseDelimited(code, version, scheme);
-    }
-    return parseFixed(code, version, scheme);
+    return (0, scan_code_1.parseScanCode)(raw, schemes);
 }
-function parseDelimited(code, version, scheme) {
-    const d = scheme.delimiter;
-    // version(2 digits) <d> category(1 digit) <d> target(rest, non-empty)
-    if (code[2] !== d) {
-        return malformed(scheme, `expected "${d}" after the two-digit scheme`);
-    }
-    const category = code.slice(3, 4);
-    if (!/^[0-9]$/.test(category)) {
-        return malformed(scheme, 'category must be a single digit');
-    }
-    if (code[4] !== d) {
-        return malformed(scheme, `expected "${d}" after the category`);
-    }
-    const target = code.slice(5);
-    if (!target) {
-        return malformed(scheme, 'target is empty');
-    }
-    return { ok: true, parsed: { version, category, target }, scheme };
-}
-function parseFixed(code, version, scheme) {
-    const targetLength = scheme.target_length ?? 0;
-    const expected = 2 + 1 + targetLength;
-    // UPC-A wedges deliver the trailing check digit too; accept it as slack.
-    if (!/^[0-9]+$/.test(code)) {
-        return malformed(scheme, 'fixed encoding accepts digits only');
-    }
-    if (code.length !== expected && code.length !== expected + 1) {
-        return malformed(scheme, `expected ${expected} digits (or ${expected + 1} with check digit), got ${code.length}`);
-    }
-    const category = code.slice(2, 3);
-    const target = code.slice(3, 3 + targetLength);
-    return { ok: true, parsed: { version, category, target }, scheme };
-}
-function malformed(scheme, detail) {
-    return {
-        ok: false,
-        failure: { reason: 'malformed', detail: `scheme ${scheme.version} ("${scheme.name}"): ${detail}` },
-    };
-}
-/** A `{claim.x}` or `{item.x}` token the context cannot resolve. */
+/** A bag token the context cannot resolve. */
 class ScanTemplateError extends Error {
     constructor(token, reason) {
         super(`scan template ${token}: ${reason}`);
@@ -94,37 +21,45 @@ class ScanTemplateError extends Error {
     }
 }
 exports.ScanTemplateError = ScanTemplateError;
-const BAG_TOKEN = /\{(claim|item)\.([a-zA-Z0-9_]+)\}/g;
+const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([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',
+};
 /** 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}.`);
 }
 function resolveBagToken(ctx, bag, facet, token) {
-    const source = bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM ? ctx.claim : ctx.item;
-    if (!source) {
-        throw new ScanTemplateError(token, bag === types_1.SCAN_TEMPLATE_BAGS.CLAIM
-            ? 'the actor holds no single live claim'
-            : 'no located item row on this step');
-    }
+    const source = ctx[bag];
+    if (!source)
+        throw new ScanTemplateError(token, MISSING_BAG[bag]);
     const v = source[facet];
     if (v === undefined || v === null || v === '') {
         throw new ScanTemplateError(token, `facet ${facet} is absent`);
     }
+    if (Array.isArray(v))
+        return v.join(', ');
     return typeof v === 'object' ? JSON.stringify(v) : String(v);
 }
 /**
  * Replace the template tokens inside string values of a params object.
- * Deep, pure, non-mutating. The three scan tokens are plain text
- * replacement; `{claim.<facet>}` and `{item.<facet>}` 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.
+ * 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
+ * {@link ScanTemplateError} when they cannot resolve, so a literal token
+ * never reaches a row. No expression language.
  */
 function interpolateScanTemplate(value, ctx) {
     if (typeof value === 'string') {
         const scanned = value
             .split(types_1.SCAN_TEMPLATE_TOKENS.TARGET).join(ctx.target)
             .split(types_1.SCAN_TEMPLATE_TOKENS.CATEGORY).join(ctx.category)
-            .split(types_1.SCAN_TEMPLATE_TOKENS.SCANNED_AT).join(ctx.scannedAt);
+            .split(types_1.SCAN_TEMPLATE_TOKENS.SCANNED_AT).join(ctx.scannedAt)
+            .split(types_1.SCAN_TEMPLATE_TOKENS.CODE).join(ctx.code ?? ctx.target);
         return scanned.replace(BAG_TOKEN, (token, bag, facet) => resolveBagToken(ctx, bag, facet, token));
     }
     if (Array.isArray(value)) {
@@ -139,3 +74,23 @@ function interpolateScanTemplate(value, ctx) {
     }
     return value;
 }
+/**
+ * Render refusal copy, degrading instead of failing: a token with nothing to
+ * read becomes an empty string, so a refusal always has words to show.
+ */
+function renderScanCopy(markdown, ctx) {
+    try {
+        return interpolateScanTemplate(markdown, ctx);
+    }
+    catch {
+        const safe = markdown.replace(BAG_TOKEN, (token, bag, facet) => {
+            try {
+                return resolveBagToken(ctx, bag, facet, token);
+            }
+            catch {
+                return '';
+            }
+        });
+        return interpolateScanTemplate(safe, ctx);
+    }
+}

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

@@ -18,6 +18,7 @@ function mapScheme(row) {
         kind: row.kind ?? 'action',
         grant_ttl_seconds: row.grant_ttl_seconds ?? null,
         grant_max_uses: row.grant_max_uses ?? 0,
+        grant_scope: row.grant_scope ?? 'action',
         enabled: row.enabled,
         created_at: row.created_at,
         updated_at: row.updated_at,

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

@@ -2,16 +2,16 @@ export declare const LIST_SCHEMES = "SELECT * FROM lt_config_scan_schemes ORDER
 export declare const GET_SCHEME = "SELECT * FROM lt_config_scan_schemes WHERE version = $1";
 export declare const LIST_ACTIONS = "SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 ORDER BY category";
 export declare const GET_ACTION = "SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2";
-export declare const UPSERT_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO UPDATE SET\n  name = EXCLUDED.name,\n  description = EXCLUDED.description,\n  target_facet = EXCLUDED.target_facet,\n  encoding = EXCLUDED.encoding,\n  delimiter = EXCLUDED.delimiter,\n  target_length = EXCLUDED.target_length,\n  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\n  enabled = EXCLUDED.enabled\nRETURNING *";
+export declare const UPSERT_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (version) DO UPDATE SET\n  name = EXCLUDED.name,\n  description = EXCLUDED.description,\n  target_facet = EXCLUDED.target_facet,\n  encoding = EXCLUDED.encoding,\n  delimiter = EXCLUDED.delimiter,\n  target_length = EXCLUDED.target_length,\n  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\n  grant_scope = EXCLUDED.grant_scope,\n  enabled = EXCLUDED.enabled\nRETURNING *";
 export declare const DELETE_SCHEME = "DELETE FROM lt_config_scan_schemes WHERE version = $1";
 export declare const UPSERT_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO UPDATE SET\n  name = EXCLUDED.name,\n  steps = EXCLUDED.steps,\n  fallback = EXCLUDED.fallback,\n  not_primed = EXCLUDED.not_primed,\n  enabled = EXCLUDED.enabled\nRETURNING *";
 export declare const DELETE_ACTION = "DELETE FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2";
-export declare const SEED_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO NOTHING";
+export declare const SEED_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (version) DO NOTHING";
 export declare const SEED_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO NOTHING";
 /**
  * Apply — same column set as the upsert, guarded by IS DISTINCT FROM so an
  * unchanged declaration is a zero-row no-op. `(xmax = 0)` distinguishes
  * insert from update. jsonb columns compare content-wise in SQL.
  */
-export declare const APPLY_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (version) DO UPDATE SET\n  name = EXCLUDED.name,\n  description = EXCLUDED.description,\n  target_facet = EXCLUDED.target_facet,\n  encoding = EXCLUDED.encoding,\n  delimiter = EXCLUDED.delimiter,\n  target_length = EXCLUDED.target_length,\n  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\n  enabled = EXCLUDED.enabled,\n  updated_at = NOW()\nWHERE (lt_config_scan_schemes.name, lt_config_scan_schemes.description,\n       lt_config_scan_schemes.target_facet, lt_config_scan_schemes.encoding,\n       lt_config_scan_schemes.delimiter, lt_config_scan_schemes.target_length,\n       lt_config_scan_schemes.kind, lt_config_scan_schemes.grant_ttl_seconds,\n       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled)\n  IS DISTINCT FROM\n      (EXCLUDED.name, EXCLUDED.description, EXCLUDED.target_facet,\n       EXCLUDED.encoding, EXCLUDED.delimiter, EXCLUDED.target_length,\n       EXCLUDED.kind, EXCLUDED.grant_ttl_seconds, EXCLUDED.grant_max_uses,\n       EXCLUDED.enabled)\nRETURNING (xmax = 0) AS inserted";
+export declare const APPLY_SCHEME = "INSERT INTO lt_config_scan_schemes\n  (version, name, description, target_facet, encoding, delimiter, target_length,\n   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (version) DO UPDATE SET\n  name = EXCLUDED.name,\n  description = EXCLUDED.description,\n  target_facet = EXCLUDED.target_facet,\n  encoding = EXCLUDED.encoding,\n  delimiter = EXCLUDED.delimiter,\n  target_length = EXCLUDED.target_length,\n  kind = EXCLUDED.kind,\n  grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,\n  grant_max_uses = EXCLUDED.grant_max_uses,\n  grant_scope = EXCLUDED.grant_scope,\n  enabled = EXCLUDED.enabled,\n  updated_at = NOW()\nWHERE (lt_config_scan_schemes.name, lt_config_scan_schemes.description,\n       lt_config_scan_schemes.target_facet, lt_config_scan_schemes.encoding,\n       lt_config_scan_schemes.delimiter, lt_config_scan_schemes.target_length,\n       lt_config_scan_schemes.kind, lt_config_scan_schemes.grant_ttl_seconds,\n       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled,\n       lt_config_scan_schemes.grant_scope)\n  IS DISTINCT FROM\n      (EXCLUDED.name, EXCLUDED.description, EXCLUDED.target_facet,\n       EXCLUDED.encoding, EXCLUDED.delimiter, EXCLUDED.target_length,\n       EXCLUDED.kind, EXCLUDED.grant_ttl_seconds, EXCLUDED.grant_max_uses,\n       EXCLUDED.enabled, EXCLUDED.grant_scope)\nRETURNING (xmax = 0) AS inserted";
 export declare const APPLY_ACTION = "INSERT INTO lt_config_scan_actions\n  (scheme_version, category, name, steps, fallback, not_primed, enabled)\nVALUES ($1, $2, $3, $4, $5, $6, $7)\nON CONFLICT (scheme_version, category) DO UPDATE SET\n  name = EXCLUDED.name,\n  steps = EXCLUDED.steps,\n  fallback = EXCLUDED.fallback,\n  not_primed = EXCLUDED.not_primed,\n  enabled = EXCLUDED.enabled,\n  updated_at = NOW()\nWHERE (lt_config_scan_actions.name, lt_config_scan_actions.steps,\n       lt_config_scan_actions.fallback, lt_config_scan_actions.not_primed,\n       lt_config_scan_actions.enabled)\n  IS DISTINCT FROM\n      (EXCLUDED.name, EXCLUDED.steps, EXCLUDED.fallback,\n       EXCLUDED.not_primed, EXCLUDED.enabled)\nRETURNING (xmax = 0) AS inserted";

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

@@ -18,8 +18,8 @@ SELECT * FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2
 exports.UPSERT_SCHEME = `\
 INSERT INTO lt_config_scan_schemes
   (version, name, description, target_facet, encoding, delimiter, target_length,
-   kind, grant_ttl_seconds, grant_max_uses, enabled)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
 ON CONFLICT (version) DO UPDATE SET
   name = EXCLUDED.name,
   description = EXCLUDED.description,
@@ -30,6 +30,7 @@ ON CONFLICT (version) DO UPDATE SET
   kind = EXCLUDED.kind,
   grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,
   grant_max_uses = EXCLUDED.grant_max_uses,
+  grant_scope = EXCLUDED.grant_scope,
   enabled = EXCLUDED.enabled
 RETURNING *`;
 exports.DELETE_SCHEME = `\
@@ -53,8 +54,8 @@ DELETE FROM lt_config_scan_actions WHERE scheme_version = $1 AND category = $2`;
 exports.SEED_SCHEME = `\
 INSERT INTO lt_config_scan_schemes
   (version, name, description, target_facet, encoding, delimiter, target_length,
-   kind, grant_ttl_seconds, grant_max_uses, enabled)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
 ON CONFLICT (version) DO NOTHING`;
 exports.SEED_ACTION = `\
 INSERT INTO lt_config_scan_actions
@@ -72,8 +73,8 @@ ON CONFLICT (scheme_version, category) DO NOTHING`;
 exports.APPLY_SCHEME = `\
 INSERT INTO lt_config_scan_schemes
   (version, name, description, target_facet, encoding, delimiter, target_length,
-   kind, grant_ttl_seconds, grant_max_uses, enabled)
-VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+   kind, grant_ttl_seconds, grant_max_uses, enabled, grant_scope)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
 ON CONFLICT (version) DO UPDATE SET
   name = EXCLUDED.name,
   description = EXCLUDED.description,
@@ -84,18 +85,20 @@ ON CONFLICT (version) DO UPDATE SET
   kind = EXCLUDED.kind,
   grant_ttl_seconds = EXCLUDED.grant_ttl_seconds,
   grant_max_uses = EXCLUDED.grant_max_uses,
+  grant_scope = EXCLUDED.grant_scope,
   enabled = EXCLUDED.enabled,
   updated_at = NOW()
 WHERE (lt_config_scan_schemes.name, lt_config_scan_schemes.description,
        lt_config_scan_schemes.target_facet, lt_config_scan_schemes.encoding,
        lt_config_scan_schemes.delimiter, lt_config_scan_schemes.target_length,
        lt_config_scan_schemes.kind, lt_config_scan_schemes.grant_ttl_seconds,
-       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled)
+       lt_config_scan_schemes.grant_max_uses, lt_config_scan_schemes.enabled,
+       lt_config_scan_schemes.grant_scope)
   IS DISTINCT FROM
       (EXCLUDED.name, EXCLUDED.description, EXCLUDED.target_facet,
        EXCLUDED.encoding, EXCLUDED.delimiter, EXCLUDED.target_length,
        EXCLUDED.kind, EXCLUDED.grant_ttl_seconds, EXCLUDED.grant_max_uses,
-       EXCLUDED.enabled)
+       EXCLUDED.enabled, EXCLUDED.grant_scope)
 RETURNING (xmax = 0) AS inserted`;
 exports.APPLY_ACTION = `\
 INSERT INTO lt_config_scan_actions

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

@@ -0,0 +1,7 @@
+import { type ScanStep } from '../../types';
+/**
+ * Hold, fill, and the subject vocabulary (subject gate, match, refuse,
+ * accumulate from/into). A step that can never find its subject, or a
+ * guard that can never pass, fails the upsert rather than the bench.
+ */
+export declare function assertValidSubjectStep(step: ScanStep, at: string): void;

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

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidSubjectStep = assertValidSubjectStep;
+const types_1 = require("../../types");
+const facet_sql_1 = require("../escalation/facet-sql");
+function isSchemeList(value) {
+    return Array.isArray(value) && value.length > 0
+        && value.every((v) => Number.isInteger(v) && v >= 10 && v <= 99);
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === 'string' && v);
+}
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Hold, fill, and the subject vocabulary (subject gate, match, refuse,
+ * accumulate from/into). A step that can never find its subject, or a
+ * guard that can never pass, fails the upsert rather than the bench.
+ */
+function assertValidSubjectStep(step, at) {
+    const accumulate = step.params?.accumulate;
+    const subjectMode = accumulate?.from === 'subject' || accumulate?.into === 'subject'
+        || (step.verb === types_1.SCAN_VERBS.FILL && step.params?.fill?.into === 'subject');
+    if (step.subject !== undefined) {
+        if (!isPlainObject(step.subject) || !isSchemeList(step.subject.schemes)) {
+            throw new Error(`${at}: subject.schemes must be a non-empty array of scheme versions (10-99)`);
+        }
+        if (step.subject.claimedByOther !== undefined
+            && step.subject.claimedByOther !== 'refuse' && step.subject.claimedByOther !== 'allow') {
+            throw new Error(`${at}: subject.claimedByOther must be 'refuse' or 'allow'`);
+        }
+        const facets = step.subject.facets;
+        if (facets !== undefined) {
+            if (!facets || typeof facets !== 'object' || Array.isArray(facets) || Object.keys(facets).length === 0) {
+                throw new Error(`${at}: subject.facets must be a non-empty object`);
+            }
+            for (const [key, value] of Object.entries(facets)) {
+                if (!facet_sql_1.FACET_KEY.test(key))
+                    throw new Error(`${at}: subject.facets key "${key}" must be a facet key`);
+                if (!['string', 'number', 'boolean'].includes(typeof value)) {
+                    throw new Error(`${at}: subject.facets.${key} must be a string, number, or boolean`);
+                }
+            }
+        }
+        if (step.verb !== types_1.SCAN_VERBS.ACCUMULATE && step.verb !== types_1.SCAN_VERBS.FILL) {
+            throw new Error(`${at}: a subject gate applies only to accumulate and fill steps`);
+        }
+        if (step.confirm)
+            throw new Error(`${at}: a subject step acts on the scan; it cannot carry confirm`);
+        if (!subjectMode) {
+            throw new Error(`${at}: a subject step must act on it (accumulate from/into 'subject', or fill into 'subject')`);
+        }
+    }
+    else if (subjectMode) {
+        throw new Error(`${at}: acting on the held subject requires a subject gate`);
+    }
+    if (accumulate?.from !== undefined && accumulate.from !== 'subject') {
+        throw new Error(`${at}: params.accumulate.from must be 'subject'`);
+    }
+    if (accumulate?.into !== undefined && accumulate.into !== 'subject') {
+        throw new Error(`${at}: params.accumulate.into must be 'subject'`);
+    }
+    if (accumulate?.from && accumulate.into) {
+        throw new Error(`${at}: params.accumulate.from and into are exclusive`);
+    }
+    if ((accumulate?.from || accumulate?.into) && accumulate.containerFacet) {
+        throw new Error(`${at}: params.accumulate.containerFacet is item mode; drop it for from/into 'subject'`);
+    }
+    if (accumulate?.from && !step.params?.itemKey) {
+        throw new Error(`${at}: from-subject accumulate requires params.itemKey (e.g. '{subject.<facet>}')`);
+    }
+    if (step.match !== undefined) {
+        if (!step.subject)
+            throw new Error(`${at}: match applies only to steps with a subject gate`);
+        if (!isPlainObject(step.match))
+            throw new Error(`${at}: match must be an object`);
+        if (step.match.target === undefined && step.match.facets === undefined) {
+            throw new Error(`${at}: match needs target or facets`);
+        }
+        if (step.match.target !== undefined && !isStringList(step.match.target)) {
+            throw new Error(`${at}: match.target must be a non-empty array of templates`);
+        }
+        if (step.match.facets !== undefined) {
+            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 (step.refuse !== undefined) {
+        if (!isPlainObject(step.refuse) || typeof step.refuse.markdown !== 'string' || !step.refuse.markdown) {
+            throw new Error(`${at}: refuse.markdown is required`);
+        }
+        if (step.refuse.conflict !== undefined && typeof step.refuse.conflict !== 'string') {
+            throw new Error(`${at}: refuse.conflict must be markdown`);
+        }
+        if (step.refuse.missing !== undefined) {
+            if (typeof step.refuse.missing !== 'string' || !step.refuse.missing) {
+                throw new Error(`${at}: refuse.missing must be markdown`);
+            }
+            if (accumulate?.from !== 'subject') {
+                throw new Error(`${at}: refuse.missing applies only to a from-subject accumulate`);
+            }
+        }
+    }
+    if (step.verb === types_1.SCAN_VERBS.HOLD)
+        assertValidHold(step, at);
+    else if (step.params?.hold !== undefined)
+        throw new Error(`${at}: params.hold applies only to hold steps`);
+    if (step.verb === types_1.SCAN_VERBS.FILL)
+        assertValidFill(step, at);
+    else if (step.params?.fill !== undefined)
+        throw new Error(`${at}: params.fill applies only to fill steps`);
+}
+function assertValidHold(step, at) {
+    if (step.cardinality === 'many')
+        throw new Error(`${at}: hold locates a single row (cardinality first)`);
+    const hold = step.params?.hold;
+    if (hold === undefined)
+        return;
+    if (!isPlainObject(hold))
+        throw new Error(`${at}: params.hold must be an object`);
+    if (hold.ttlSeconds !== undefined && (!Number.isInteger(hold.ttlSeconds)
+        || hold.ttlSeconds < types_1.SCAN_HOLD_TTL_MIN_SECONDS || hold.ttlSeconds > types_1.SCAN_HOLD_TTL_MAX_SECONDS)) {
+        throw new Error(`${at}: params.hold.ttlSeconds must be ${types_1.SCAN_HOLD_TTL_MIN_SECONDS}-${types_1.SCAN_HOLD_TTL_MAX_SECONDS}`);
+    }
+    if (hold.label !== undefined && typeof hold.label !== 'string') {
+        throw new Error(`${at}: params.hold.label must be a template string`);
+    }
+    if (hold.expect !== undefined) {
+        if (!isPlainObject(hold.expect) || !isSchemeList(hold.expect.schemes)) {
+            throw new Error(`${at}: params.hold.expect.schemes must be a non-empty array of scheme versions`);
+        }
+        if (hold.expect.prompt !== undefined && typeof hold.expect.prompt !== 'string') {
+            throw new Error(`${at}: params.hold.expect.prompt must be markdown`);
+        }
+    }
+}
+function assertValidFill(step, at) {
+    const fill = step.params?.fill;
+    if (!fill || !isPlainObject(fill))
+        throw new Error(`${at}: fill requires params.fill`);
+    if (fill.into !== 'subject' && fill.into !== 'scanned') {
+        throw new Error(`${at}: params.fill.into must be 'subject' or 'scanned'`);
+    }
+    const separator = fill.separator ?? types_1.SCAN_FILL_SEPARATOR_DEFAULT;
+    if (typeof separator !== 'string' || separator.length !== 1) {
+        throw new Error(`${at}: params.fill.separator must be one character`);
+    }
+    if (fill.payload !== undefined && !isPlainObject(fill.payload)) {
+        throw new Error(`${at}: params.fill.payload must be an object`);
+    }
+    if (step.confirm)
+        throw new Error(`${at}: fill cannot carry confirm`);
+}

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

@@ -5,6 +5,13 @@ import { type ScanScheme, type ScanStep } from '../../types';
  * than a loud upsert failure.
  */
 export declare function assertValidScheme(scheme: Partial<ScanScheme>): void;
+/**
+ * A scheme must read codes no other scheme reads. Delimited and fixed
+ * schemes are told apart by their version prefix; a gtin scheme has none,
+ * so there is at most one, and no enabled fixed scheme may accept a GTIN
+ * length while it is enabled. Throws naming both schemes.
+ */
+export declare function assertSchemesCoexist(candidate: Partial<ScanScheme>, existing: ScanScheme[]): void;
 /** Identity rules never walk steps — their fallback is the unknown-badge screen. */
 export declare function assertValidIdentityRule(steps: ScanStep[]): void;
 /**