@hotmeshio/long-tail 0.22.2 → 0.22.3

package/build/services/orchestrator/condition.js

@@ -104,17 +104,19 @@ function toEngineConfig(escalation) {
  * });
  * ```
  *
- * **Pin versioned knowledge lookups — option lists the form reads.** Each ref
- * names an immutable knowledge edition; the resolve UI fetches them once and
- * the form addresses the content as the `lookup.*` context domain
- * (`x-lt-options: "lookup.materials.items"`). Evolve the list by writing the
- * entry (a new version mints automatically) and repinning the literal here.
+ * **Knowledge lookups — option lists the form reads.** Each ref names a
+ * knowledge entry; the resolve UI fetches it and the form addresses the
+ * content as the `lookup.*` context domain (`x-lt-options:
+ * "lookup.materials.items"`). Leave `version` out (or set `'current'`) and
+ * the form reads the newest edition, so a long-open row sees today's list
+ * and a closed row the list current when it closed. Pin a `version` when the
+ * form must read one exact edition.
  *
  * ```typescript
  * const decision = await conditional<PickerResolverV1>(signalId, {
  *   role: 'catalog-picker',
  *   description: instructions,
- *   lookups: [{ domain: 'catalog', key: 'materials', version: 2 }],
+ *   lookups: [{ domain: 'catalog', key: 'materials' }],
  * });
  * ```
  *

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

@@ -2,4 +2,4 @@ export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './r
 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 { assertValidScheme, assertValidSteps, assertValidIdentityRule, assertSchemesCoexist, } from './validate';
-export { isValidGtin, normalizeGtin } from '../../shared/scan-code';
+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.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.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; } });
@@ -29,3 +29,4 @@ Object.defineProperty(exports, "assertSchemesCoexist", { enumerable: true, get:
 var scan_code_1 = require("../../shared/scan-code");
 Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
 Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });
+Object.defineProperty(exports, "displayGtin", { enumerable: true, get: function () { return scan_code_1.displayGtin; } });

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

@@ -0,0 +1,5 @@
+import { type ScanStep } from '../../types';
+/** The most facts a station screen states before it reads as a data dump. */
+export declare const SCAN_FACTS_MAX = 12;
+/** `facts` on a present step: labeled template values the station states. */
+export declare function assertValidFacts(step: ScanStep, at: string): void;

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCAN_FACTS_MAX = void 0;
+exports.assertValidFacts = assertValidFacts;
+const types_1 = require("../../types");
+/** The most facts a station screen states before it reads as a data dump. */
+exports.SCAN_FACTS_MAX = 12;
+/** `facts` on a present step: labeled template values the station states. */
+function assertValidFacts(step, at) {
+    if (step.facts === undefined)
+        return;
+    if (step.verb !== types_1.SCAN_VERBS.PRESENT)
+        throw new Error(`${at}: facts apply only to present steps`);
+    if (!Array.isArray(step.facts) || step.facts.length === 0 || step.facts.length > exports.SCAN_FACTS_MAX) {
+        throw new Error(`${at}: facts must be an array of 1-${exports.SCAN_FACTS_MAX} { label, value } entries`);
+    }
+    step.facts.forEach((fact, i) => {
+        if (!fact || typeof fact !== 'object' || typeof fact.label !== 'string' || !fact.label.trim()) {
+            throw new Error(`${at}: facts[${i}].label must be non-empty text`);
+        }
+        if (typeof fact.value !== 'string')
+            throw new Error(`${at}: facts[${i}].value must be a template string`);
+    });
+}

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

@@ -0,0 +1,8 @@
+import { type ScanStep } from '../../types';
+/**
+ * query.types / query.subtypes narrow a locate that is followed by a write
+ * by id. Every present choice writes the row it showed, so a present step
+ * takes them with any choice; claim, cancel, release, resolve and escalate
+ * steps do not.
+ */
+export declare function assertValidQueryKinds(step: ScanStep, at: string): void;

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidQueryKinds = assertValidQueryKinds;
+const types_1 = require("../../types");
+// Verbs whose atomic statement locates by the target facet alone when they
+// run as a step; a type/subtype guard on the step would never reach it.
+const RELOCATING_VERBS = [
+    types_1.SCAN_VERBS.CLAIM, types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL, types_1.SCAN_VERBS.CANCEL,
+    types_1.SCAN_VERBS.RELEASE, types_1.SCAN_VERBS.ESCALATE, types_1.SCAN_VERBS.RESOLVE,
+];
+/**
+ * query.types / query.subtypes narrow a locate that is followed by a write
+ * by id. Every present choice writes the row it showed, so a present step
+ * takes them with any choice; claim, cancel, release, resolve and escalate
+ * steps do not.
+ */
+function assertValidQueryKinds(step, at) {
+    const { types, subtypes } = step.query ?? {};
+    if (types === undefined && subtypes === undefined)
+        return;
+    for (const [name, list] of [['types', types], ['subtypes', subtypes]]) {
+        if (list !== undefined && (!Array.isArray(list) || list.length === 0
+            || !list.every((v) => typeof v === 'string' && v))) {
+            throw new Error(`${at}: query.${name} must be a non-empty array of strings`);
+        }
+    }
+    if (RELOCATING_VERBS.includes(step.verb)) {
+        throw new Error(`${at}: query.types/subtypes are not supported on ${step.verb} steps (the write re-locates by the target facet)`);
+    }
+    if (step.subject) {
+        throw new Error(`${at}: a subject step narrows with params.accumulate.container or item, not query.types/subtypes`);
+    }
+    if (step.query?.availability === types_1.SCAN_AVAILABILITY.MINE && ((types?.length ?? 0) > 1 || (subtypes?.length ?? 0) > 1)) {
+        throw new Error(`${at}: with availability 'mine', query.types and query.subtypes take at most one entry each`);
+    }
+}

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

@@ -67,6 +67,8 @@ function assertValidSubjectStep(step, at) {
     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?.item !== undefined)
+        assertValidItemSelector(accumulate, at);
     if (accumulate?.from && !step.params?.itemKey) {
         throw new Error(`${at}: from-subject accumulate requires params.itemKey (e.g. '{subject.<facet>}')`);
     }
@@ -101,8 +103,8 @@ function assertValidSubjectStep(step, at) {
             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 (accumulate?.from !== 'subject' && !(accumulate?.into === 'subject' && accumulate.item)) {
+                throw new Error(`${at}: refuse.missing applies only to a from-subject accumulate, or an into-subject accumulate with item`);
             }
         }
     }
@@ -115,6 +117,31 @@ function assertValidSubjectStep(step, at) {
     else if (step.params?.fill !== undefined)
         throw new Error(`${at}: params.fill applies only to fill steps`);
 }
+function assertValidItemSelector(accumulate, at) {
+    const item = accumulate.item;
+    if (accumulate.into !== 'subject') {
+        throw new Error(`${at}: params.accumulate.item applies only to an into-subject accumulate`);
+    }
+    if (!isPlainObject(item))
+        throw new Error(`${at}: params.accumulate.item must be an object`);
+    if (item.roles !== undefined && !isStringList(item.roles)) {
+        throw new Error(`${at}: params.accumulate.item.roles must be a non-empty array of roles`);
+    }
+    if (item.types !== undefined && !isStringList(item.types)) {
+        throw new Error(`${at}: params.accumulate.item.types must be a non-empty array of strings`);
+    }
+    if (item.subtypes !== undefined && !isStringList(item.subtypes)) {
+        throw new Error(`${at}: params.accumulate.item.subtypes must be a non-empty array of strings`);
+    }
+    if (item.facets !== undefined) {
+        if (!isPlainObject(item.facets))
+            throw new Error(`${at}: params.accumulate.item.facets must be an object`);
+        for (const key of Object.keys(item.facets)) {
+            if (!facet_sql_1.FACET_KEY.test(key))
+                throw new Error(`${at}: params.accumulate.item.facets key "${key}" must be a facet key`);
+        }
+    }
+}
 function assertValidHold(step, at) {
     if (step.cardinality === 'many')
         throw new Error(`${at}: hold locates a single row (cardinality first)`);

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

@@ -8,6 +8,8 @@ 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 validate_query_1 = require("./validate-query");
+const validate_facts_1 = require("./validate-facts");
 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}$/;
@@ -242,6 +244,8 @@ function assertValidSteps(steps) {
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);
         }
+        (0, validate_query_1.assertValidQueryKinds)(step, at);
+        (0, validate_facts_1.assertValidFacts)(step, at);
         // Claim and cancel lock via claim-by-metadata, whose SQL filter is the
         // target facet + roles only — extra facet guards would be silently
         // ignored there, so reject them at write time. (Locate, resolve, and
@@ -259,28 +263,32 @@ function assertValidSteps(steps) {
 const BAG_TOKEN = /\{(claim|item|subject|container|fill)\.([^}]*)\}/g;
 /**
  * Bag tokens name facet keys and may only read what the step has:
- * `{item.…}` the row an item-mode accumulate or a hold located,
+ * `{item.…}` the row an item-mode accumulate, an into-subject accumulate
+ * with `item`, or a hold located (and, in a present step's facts, the row it
+ * 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.
+ * subject accumulate or a fill has read them (into-subject: the held row).
  */
 function assertValidTemplateTokens(step, at) {
-    const itemRow = (step.verb === types_1.SCAN_VERBS.ACCUMULATE && !!step.params?.accumulate?.containerFacet)
+    const accumulate = step.verb === types_1.SCAN_VERBS.ACCUMULATE ? step.params?.accumulate : undefined;
+    const itemRow = !!accumulate?.containerFacet || (accumulate?.into === 'subject' && !!accumulate.item)
         || step.verb === types_1.SCAN_VERBS.HOLD;
-    const check = (value, inRefusal) => {
+    const containerCopy = accumulate?.from === 'subject' || accumulate?.into === 'subject';
+    const check = (value, inRefusal, inFacts = false) => {
         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 === 'item' && !itemRow && !inFacts) {
+                throw new Error(`${at}: ${token} reads the located item row, which only an item-mode accumulate, an into-subject accumulate with item, 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 === 'container' && !(inRefusal && containerCopy)) {
+                throw new Error(`${at}: ${token} is readable only in the refusal or done copy of a 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`);
@@ -291,4 +299,5 @@ function assertValidTemplateTokens(step, at) {
     check(step.match, false);
     check(step.refuse, true);
     check(step.done, true);
+    check(step.facts, false, true);
 }

package/build/shared/scan-code/gtin.d.ts

@@ -3,3 +3,9 @@ export declare const GTIN_CODE_LENGTHS: readonly number[];
 export declare function isValidGtin(code: string): boolean;
 /** The 14-digit form of a valid GTIN: UPC-A, EAN-13 and EAN-8 left-padded with zeros. */
 export declare function normalizeGtin(code: string): string;
+/**
+ * A stored 14-digit GTIN as the package prints it: EAN-8 when it was padded
+ * from eight digits, otherwise EAN-13 (a UPC-A reads as its EAN-13 with a
+ * leading zero). Anything else comes back unchanged.
+ */
+export declare function displayGtin(code: string): string;

package/build/shared/scan-code/gtin.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GTIN_CODE_LENGTHS = void 0;
 exports.isValidGtin = isValidGtin;
 exports.normalizeGtin = normalizeGtin;
+exports.displayGtin = displayGtin;
 exports.GTIN_CODE_LENGTHS = [8, 12, 13, 14];
 /** True when `code` is all digits, a GTIN length, and its mod-10 check digit holds. */
 function isValidGtin(code) {
@@ -23,3 +24,15 @@ function isValidGtin(code) {
 function normalizeGtin(code) {
     return code.padStart(14, '0');
 }
+/**
+ * A stored 14-digit GTIN as the package prints it: EAN-8 when it was padded
+ * from eight digits, otherwise EAN-13 (a UPC-A reads as its EAN-13 with a
+ * leading zero). Anything else comes back unchanged.
+ */
+function displayGtin(code) {
+    if (code.length !== 14 || !isValidGtin(code))
+        return code;
+    if (code.startsWith('000000') && isValidGtin(code.slice(6)))
+        return code.slice(6);
+    return code.startsWith('0') ? code.slice(1) : code;
+}

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

@@ -1,2 +1,2 @@
 export { parseScanCode, fixedCodeLengths, type ParseableScheme, type ParsedCode, type ScanParseFailure, type ScanParseResult, } from './parse';
-export { isValidGtin, normalizeGtin, GTIN_CODE_LENGTHS } from './gtin';
+export { isValidGtin, normalizeGtin, displayGtin, GTIN_CODE_LENGTHS } from './gtin';

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

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GTIN_CODE_LENGTHS = exports.normalizeGtin = exports.isValidGtin = exports.fixedCodeLengths = exports.parseScanCode = void 0;
+exports.GTIN_CODE_LENGTHS = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.fixedCodeLengths = exports.parseScanCode = void 0;
 var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "fixedCodeLengths", { enumerable: true, get: function () { return parse_1.fixedCodeLengths; } });
 var gtin_1 = require("./gtin");
 Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return gtin_1.isValidGtin; } });
 Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return gtin_1.normalizeGtin; } });
+Object.defineProperty(exports, "displayGtin", { enumerable: true, get: function () { return gtin_1.displayGtin; } });
 Object.defineProperty(exports, "GTIN_CODE_LENGTHS", { enumerable: true, get: function () { return gtin_1.GTIN_CODE_LENGTHS; } });