@hotmeshio/long-tail 0.22.0 → 0.22.2

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;
 /**

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

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertValidScheme = assertValidScheme;
+exports.assertSchemesCoexist = assertSchemesCoexist;
 exports.assertValidIdentityRule = assertValidIdentityRule;
 exports.assertValidSteps = assertValidSteps;
 const types_1 = require("../../types");
+const scan_code_1 = require("../../shared/scan-code");
 const facet_sql_1 = require("../escalation/facet-sql");
+const validate_subject_1 = require("./validate-subject");
 const VALID_VERBS = new Set(Object.values(types_1.SCAN_VERBS));
 /** Double-scan selection tokens — short, label-printable, never scheme-shaped. */
 const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
@@ -22,6 +25,12 @@ function assertValidScheme(scheme) {
     if (!scheme.target_facet)
         throw new Error('scheme target_facet is required');
     const encoding = scheme.encoding ?? types_1.SCAN_ENCODINGS.FIXED;
+    if (!Object.values(types_1.SCAN_ENCODINGS).includes(encoding)) {
+        throw new Error(`unknown scheme encoding "${encoding}"`);
+    }
+    if (encoding === types_1.SCAN_ENCODINGS.GTIN && (scheme.kind ?? types_1.SCAN_SCHEME_KINDS.ACTION) !== types_1.SCAN_SCHEME_KINDS.ACTION) {
+        throw new Error('gtin encoding applies only to action schemes');
+    }
     if (encoding === types_1.SCAN_ENCODINGS.FIXED) {
         if (!Number.isInteger(scheme.target_length) || scheme.target_length < 1) {
             throw new Error('fixed encoding requires a positive integer target_length');
@@ -48,11 +57,50 @@ function assertValidScheme(scheme) {
         if (!Number.isInteger(scheme.grant_max_uses ?? 0) || (scheme.grant_max_uses ?? 0) < 0) {
             throw new Error('grant_max_uses must be a non-negative integer');
         }
+        const scope = scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION;
+        if (!Object.values(types_1.SCAN_GRANT_SCOPES).includes(scope)) {
+            throw new Error(`unknown grant_scope "${scope}"`);
+        }
     }
-    else if (scheme.grant_ttl_seconds != null || (scheme.grant_max_uses ?? 0) !== 0) {
+    else if (scheme.grant_ttl_seconds != null || (scheme.grant_max_uses ?? 0) !== 0
+        || (scheme.grant_scope ?? types_1.SCAN_GRANT_SCOPES.ACTION) !== types_1.SCAN_GRANT_SCOPES.ACTION) {
         throw new Error('grant policy applies only to identity schemes');
     }
 }
+/**
+ * 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.
+ */
+function assertSchemesCoexist(candidate, existing) {
+    const others = existing.filter((s) => s.version !== candidate.version);
+    const encoding = candidate.encoding ?? types_1.SCAN_ENCODINGS.FIXED;
+    const enabled = candidate.enabled ?? true;
+    if (encoding === types_1.SCAN_ENCODINGS.GTIN) {
+        const gtin = others.find((s) => s.encoding === types_1.SCAN_ENCODINGS.GTIN);
+        if (gtin) {
+            throw new Error(`scheme ${gtin.version} ("${gtin.name}") already reads manufacturer barcodes; only one gtin scheme is allowed`);
+        }
+        if (!enabled)
+            return;
+        const clash = others.find((s) => s.enabled && s.encoding === types_1.SCAN_ENCODINGS.FIXED
+            && (0, scan_code_1.fixedCodeLengths)(s).some((n) => types_1.GTIN_LENGTHS.includes(n)));
+        if (clash) {
+            throw new Error(`fixed scheme ${clash.version} ("${clash.name}") accepts ${(0, scan_code_1.fixedCodeLengths)(clash).join(' or ')}-digit codes, which a gtin scheme also reads; change its target_length or leave the gtin scheme disabled`);
+        }
+        return;
+    }
+    if (encoding === types_1.SCAN_ENCODINGS.FIXED && enabled) {
+        const lengths = (0, scan_code_1.fixedCodeLengths)({ target_length: candidate.target_length ?? null });
+        if (!lengths.some((n) => types_1.GTIN_LENGTHS.includes(n)))
+            return;
+        const gtin = others.find((s) => s.enabled && s.encoding === types_1.SCAN_ENCODINGS.GTIN);
+        if (gtin) {
+            throw new Error(`a fixed scheme accepting ${lengths.join(' or ')}-digit codes collides with gtin scheme ${gtin.version} ("${gtin.name}"); change target_length or disable the gtin scheme`);
+        }
+    }
+}
 /** Identity rules never walk steps — their fallback is the unknown-badge screen. */
 function assertValidIdentityRule(steps) {
     if (Array.isArray(steps) && steps.length > 0) {
@@ -73,7 +121,8 @@ function assertValidChoices(choices, at) {
             throw new Error(`${cat}: label is required`);
         if (!VALID_VERBS.has(choice.verb))
             throw new Error(`${cat}: unknown verb "${choice.verb}"`);
-        if (choice.verb === types_1.SCAN_VERBS.PRESENT || choice.verb === types_1.SCAN_VERBS.SHOW_LIST) {
+        if (choice.verb === types_1.SCAN_VERBS.PRESENT || choice.verb === types_1.SCAN_VERBS.SHOW_LIST
+            || choice.verb === types_1.SCAN_VERBS.FILL) {
             throw new Error(`${cat}: ${choice.verb} cannot be a choice verb`);
         }
         if (choice.confirm && !choice.confirm.prompt) {
@@ -157,10 +206,38 @@ function assertValidSteps(steps) {
             if (options?.containerRoles !== undefined && !Array.isArray(options.containerRoles)) {
                 throw new Error(`${at}: params.accumulate.containerRoles must be an array`);
             }
-            if (!options?.containerFacet && !step.params?.itemKey) {
+            const container = options?.container;
+            if (container !== undefined) {
+                if (!container || typeof container !== 'object' || Array.isArray(container)) {
+                    throw new Error(`${at}: params.accumulate.container must be an object`);
+                }
+                for (const list of ['roles', 'types', 'subtypes']) {
+                    const value = container[list];
+                    if (value !== undefined && (!Array.isArray(value) || !value.every((v) => typeof v === 'string' && v))) {
+                        throw new Error(`${at}: params.accumulate.container.${list} must be an array of strings`);
+                    }
+                }
+                if (container.facets !== undefined
+                    && (!container.facets || typeof container.facets !== 'object' || Array.isArray(container.facets))) {
+                    throw new Error(`${at}: params.accumulate.container.facets must be an object`);
+                }
+                if (!options?.containerFacet && options?.from !== 'subject') {
+                    throw new Error(`${at}: params.accumulate.container requires params.accumulate.containerFacet or from: 'subject'`);
+                }
+            }
+            if (!options?.containerFacet && !options?.into && !step.params?.itemKey) {
                 throw new Error(`${at}: accumulate requires params.itemKey or params.accumulate.containerFacet`);
             }
         }
+        (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`);
+            }
+        }
         assertValidTemplateTokens(step, at);
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);
@@ -179,21 +256,39 @@ function assertValidSteps(steps) {
         }
     });
 }
-const BAG_TOKEN = /\{(claim|item)\.([^}]*)\}/g;
+const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([^}]*)\}/g;
 /**
- * `{claim.<facet>}` and `{item.<facet>}` name facet keys; `{item.…}` reads
- * the located row, which only an item-mode accumulate step has.
+ * Bag tokens name facet keys and may only read what the step has:
+ * `{item.…}` the row an item-mode accumulate or a hold located,
+ * `{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.
  */
 function assertValidTemplateTokens(step, at) {
-    const text = JSON.stringify(step.params ?? {});
-    const itemMode = step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet;
-    for (const match of text.matchAll(BAG_TOKEN)) {
-        const [token, bag, facet] = match;
-        if (!facet_sql_1.FACET_KEY.test(facet)) {
-            throw new Error(`${at}: template token ${token} must name a facet key`);
-        }
-        if (bag === 'item' && !itemMode) {
-            throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate step has`);
+    const itemRow = (step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet)
+        || step.verb === types_1.SCAN_VERBS.HOLD;
+    const check = (value, inRefusal) => {
+        for (const match of JSON.stringify(value ?? {}).matchAll(BAG_TOKEN)) {
+            const [token, bag, facet] = match;
+            if (!facet_sql_1.FACET_KEY.test(facet)) {
+                throw new Error(`${at}: template token ${token} must name a facet key`);
+            }
+            if (bag === 'item' && !itemRow) {
+                throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate or a hold step has`);
+            }
+            if (bag === 'subject' && !step.subject) {
+                throw new Error(`${at}: ${token} reads the held subject, which only a step with a subject gate has`);
+            }
+            if (bag === 'container' && !(inRefusal && step.params?.accumulate?.from === 'subject')) {
+                throw new Error(`${at}: ${token} is readable only in the refusal or done copy of a from-subject accumulate step`);
+            }
+            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`);
+            }
         }
-    }
+    };
+    check(step.params, false);
+    check(step.match, false);
+    check(step.refuse, true);
+    check(step.done, true);
 }

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

@@ -10,6 +10,7 @@ export interface ScanSchemeInput {
     kind?: ScanScheme['kind'];
     grant_ttl_seconds?: number | null;
     grant_max_uses?: number;
+    grant_scope?: ScanScheme['grant_scope'];
     enabled?: boolean;
 }
 export interface ScanRuleInput {