@hotmeshio/long-tail 0.22.2 → 0.23.0

package/build/services/knowledge/lookup-cache.js

@@ -1,21 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getKnowledgeSnapshot = getKnowledgeSnapshot;
+exports.resolveRefEdition = resolveRefEdition;
 exports.resolveLookupContext = resolveLookupContext;
 exports.resolveLookupRefs = resolveLookupRefs;
 /**
  * Lookup snapshot cache — keeps escalation lookup resolution off the SQL hot
- * path. A lookup ref pins {domain, key, version}; the snapshot behind it is
- * immutable by design, so entries cache indefinitely under an LRU bound.
- * Thousands of escalations sharing the same refs resolve from memory after
- * the first read. Missing snapshots are never cached — a later seed or
- * republish must become visible.
+ * path. An edition {domain, key, version} is immutable, so snapshots cache
+ * indefinitely under an LRU bound. A pinned ref resolves from memory after
+ * the first read; a current ref costs one indexed read to learn which
+ * edition is newest, then shares the same cache. Missing snapshots are never
+ * cached — a later seed or republish must become visible.
  */
 const db_1 = require("../../lib/db");
+const escalation_1 = require("../../types/escalation");
 const sql_1 = require("./sql");
 const SNAPSHOT_CACHE_MAX_ENTRIES = 256;
 // Map preserves insertion order — delete+set on read keeps it LRU.
 const snapshotCache = new Map();
+function remember(cacheKey, snapshot) {
+    snapshotCache.set(cacheKey, snapshot);
+    while (snapshotCache.size > SNAPSHOT_CACHE_MAX_ENTRIES) {
+        const oldest = snapshotCache.keys().next().value;
+        snapshotCache.delete(oldest);
+    }
+}
 /** The immutable snapshot at (domain, key, version), or null when absent. */
 async function getKnowledgeSnapshot(domain, key, version) {
     const cacheKey = `${domain} ${key} ${version}`;
@@ -33,13 +42,35 @@ async function getKnowledgeSnapshot(domain, key, version) {
         data: rows[0].data ?? {},
         tags: rows[0].tags ?? [],
     };
-    snapshotCache.set(cacheKey, snapshot);
-    while (snapshotCache.size > SNAPSHOT_CACHE_MAX_ENTRIES) {
-        const oldest = snapshotCache.keys().next().value;
-        snapshotCache.delete(oldest);
-    }
+    remember(cacheKey, snapshot);
     return snapshot;
 }
+/**
+ * The edition a ref names: its pin, or for a current ref the newest edition
+ * (the newest at `asOf` when given, so a closed row reads what was current
+ * when it closed). Null when there is none.
+ */
+async function resolveRefEdition(ref, asOf) {
+    if (!(0, escalation_1.isCurrentLookupRef)(ref)) {
+        const version = ref.version;
+        const snapshot = await getKnowledgeSnapshot(ref.domain, ref.key, version);
+        return snapshot ? { version, snapshot } : null;
+    }
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_LATEST_KNOWLEDGE_VERSION, [ref.domain, ref.key, asOf ?? null]);
+    if (!rows[0])
+        return null;
+    const version = Number(rows[0].version);
+    const cacheKey = `${ref.domain} ${ref.key} ${version}`;
+    const cached = snapshotCache.get(cacheKey);
+    if (cached)
+        return { version, snapshot: cached };
+    const snapshot = {
+        data: rows[0].data ?? {},
+        tags: rows[0].tags ?? [],
+    };
+    remember(cacheKey, snapshot);
+    return { version, snapshot };
+}
 /** Structural check for one ref — malformed entries in stored metadata are skipped, not fatal. */
 function isLookupRef(ref) {
     if (!ref || typeof ref !== 'object')
@@ -47,7 +78,7 @@ function isLookupRef(ref) {
     const r = ref;
     return typeof r.domain === 'string' && r.domain.length > 0
         && typeof r.key === 'string' && r.key.length > 0
-        && typeof r.version === 'number' && Number.isInteger(r.version) && r.version >= 1
+        && ((0, escalation_1.isCurrentLookupRef)(r) || (typeof r.version === 'number' && Number.isInteger(r.version) && r.version >= 1))
         && (r.as === undefined || (typeof r.as === 'string' && r.as.length > 0));
 }
 /**
@@ -56,7 +87,7 @@ function isLookupRef(ref) {
  * escalations without refs cost zero SQL. Missing snapshots are omitted —
  * interpolated selects then fail closed rather than render the wrong list.
  */
-async function resolveLookupContext(refs) {
+async function resolveLookupContext(refs, asOf) {
     if (!Array.isArray(refs) || refs.length === 0)
         return null;
     const valid = refs.filter(isLookupRef);
@@ -64,9 +95,9 @@ async function resolveLookupContext(refs) {
         return null;
     const ctx = {};
     for (const ref of valid) {
-        const snapshot = await getKnowledgeSnapshot(ref.domain, ref.key, ref.version);
-        if (snapshot)
-            ctx[ref.as ?? ref.key] = snapshot.data;
+        const edition = await resolveRefEdition(ref, asOf);
+        if (edition)
+            ctx[ref.as ?? ref.key] = edition.snapshot.data;
     }
     return ctx;
 }
@@ -75,19 +106,21 @@ async function resolveLookupContext(refs) {
  * `missing: true` marking a pin that has no snapshot — fail-visible per ref
  * without failing the batch.
  */
-async function resolveLookupRefs(refs) {
+async function resolveLookupRefs(refs, asOf) {
     const resolved = [];
     for (const ref of refs) {
         if (!isLookupRef(ref))
             continue;
-        const snapshot = await getKnowledgeSnapshot(ref.domain, ref.key, ref.version);
+        const current = (0, escalation_1.isCurrentLookupRef)(ref);
+        const edition = await resolveRefEdition(ref, asOf);
         resolved.push({
             domain: ref.domain,
             key: ref.key,
-            version: ref.version,
+            version: edition?.version ?? (current ? null : ref.version),
+            ...(current ? { current: true } : {}),
             ...(ref.as ? { as: ref.as } : {}),
-            data: snapshot ? snapshot.data : null,
-            ...(snapshot ? {} : { missing: true }),
+            data: edition ? edition.snapshot.data : null,
+            ...(edition ? {} : { missing: true }),
         });
     }
     return resolved;

package/build/services/knowledge/lookup-refs.d.ts

@@ -1,6 +1,7 @@
-import type { EscalationLookupRef } from '../../types/escalation';
+import { type EscalationLookupRef } from '../../types/escalation';
 /**
- * One message per ref whose pinned edition does not exist, naming what does.
+ * One message per ref with no edition behind it (a pin that does not exist,
+ * or a current ref to an entry with no editions), naming what does.
  * Shape is the caller's job (assertLookupRefs); this answers the second
  * question a saver has: is there an edition behind the pin.
  */

package/build/services/knowledge/lookup-refs.js

@@ -2,25 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeMissingLookupRefs = describeMissingLookupRefs;
 const db_1 = require("../../lib/db");
+const escalation_1 = require("../../types/escalation");
 const lookup_cache_1 = require("./lookup-cache");
 const sql_1 = require("./sql");
 /**
- * One message per ref whose pinned edition does not exist, naming what does.
+ * One message per ref with no edition behind it (a pin that does not exist,
+ * or a current ref to an entry with no editions), naming what does.
  * Shape is the caller's job (assertLookupRefs); this answers the second
  * question a saver has: is there an edition behind the pin.
  */
 async function describeMissingLookupRefs(refs) {
     const problems = [];
     for (const ref of refs) {
-        const snapshot = await (0, lookup_cache_1.getKnowledgeSnapshot)(ref.domain, ref.key, ref.version);
-        if (snapshot)
+        if (await (0, lookup_cache_1.resolveRefEdition)(ref))
             continue;
         const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_KNOWLEDGE_VERSIONS, [ref.domain, ref.key]);
         const versions = rows.map((r) => Number(r.version)).sort((a, b) => a - b);
         const where = versions.length
             ? `editions: ${versions.map((v) => `v${v}`).join(', ')}`
             : `no knowledge entry ${ref.domain}/${ref.key}`;
-        problems.push(`Lookup ref ${ref.domain}/${ref.key} v${ref.version} names no edition (${where})`);
+        const named = (0, escalation_1.isCurrentLookupRef)(ref) ? 'current' : `v${ref.version}`;
+        problems.push(`Lookup ref ${ref.domain}/${ref.key} ${named} names no edition (${where})`);
     }
     return problems;
 }

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

@@ -1,2 +1,4 @@
 export declare const GET_KNOWLEDGE_VERSION = "\n  SELECT domain, key, version, data, tags, change_summary, created_at\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND version = $3";
 export declare const LIST_KNOWLEDGE_VERSIONS = "\n  SELECT v.version, v.change_summary, v.created_at,\n         (v.version = k.current_version) AS is_current\n  FROM lt_knowledge_versions v\n  JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key\n  WHERE v.domain = $1 AND v.key = $2\n  ORDER BY v.version DESC";
+/** The newest edition, or the newest created at or before $3 when it is set. */
+export declare const GET_LATEST_KNOWLEDGE_VERSION = "\n  SELECT version, data, tags\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2\n    AND ($3::timestamptz IS NULL OR created_at <= $3)\n  ORDER BY version DESC\n  LIMIT 1";

package/build/services/knowledge/sql.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION = void 0;
+exports.GET_LATEST_KNOWLEDGE_VERSION = exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION = void 0;
 exports.GET_KNOWLEDGE_VERSION = `
   SELECT domain, key, version, data, tags, change_summary, created_at
   FROM lt_knowledge_versions
@@ -12,3 +12,11 @@ exports.LIST_KNOWLEDGE_VERSIONS = `
   JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key
   WHERE v.domain = $1 AND v.key = $2
   ORDER BY v.version DESC`;
+/** The newest edition, or the newest created at or before $3 when it is set. */
+exports.GET_LATEST_KNOWLEDGE_VERSION = `
+  SELECT version, data, tags
+  FROM lt_knowledge_versions
+  WHERE domain = $1 AND key = $2
+    AND ($3::timestamptz IS NULL OR created_at <= $3)
+  ORDER BY version DESC
+  LIMIT 1`;

package/build/services/mcp/server-tools.js

@@ -175,7 +175,7 @@ function registerHumanQueueTools(server) {
             };
         }
         const refs = (0, lookups_1.readLookupRefs)(escalation.envelope);
-        const lookups = refs.length > 0 ? await (0, knowledge_1.resolveLookupRefs)(refs) : [];
+        const lookups = refs.length > 0 ? await (0, knowledge_1.resolveLookupRefs)(refs, (0, lookups_1.lookupAsOf)(escalation)) : [];
         return {
             content: [{
                     type: 'text',

package/build/services/orchestrator/condition.d.ts

@@ -2,10 +2,11 @@ import type { Types } from '@hotmeshio/hotmesh';
 import { type AccumulateConfig, type AccumulatorResult, type EscalationLookupRef } from '../../types/escalation';
 /**
  * HotMesh's escalation config plus long-tail sugar. `schemaVersion` pins the
- * role form version (lt_role_schemas) the resolve UI renders; `lookups` pins
- * versioned knowledge editions the form may read (the `lookup.*` context
- * domain — see docs/hitl/lookups.md). Both are compile-time LITERALS the
- * workflow author sets, folded before the config reaches the engine:
+ * role form version (lt_role_schemas) the resolve UI renders; `lookups` names
+ * the knowledge entries the form may read (the `lookup.*` context domain, see
+ * docs/hitl/lookups.md), each pinned to an edition or following the current
+ * one. Both are LITERALS the workflow author sets, folded before the config
+ * reaches the engine:
  * schemaVersion into the GIN-indexed metadata (a queryable facet), lookups
  * into the unindexed envelope (form plumbing, never a facet). Folding is a
  * pure transform — no query, no activity — so a pinned `conditional` costs
@@ -57,17 +58,19 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * });
  * ```
  *
- * **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' }],
  * });
  * ```
  *
@@ -119,7 +122,10 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * items persist on the terminal row for audit. Add `partialOnTimeout: true`
  * (hotmesh 0.29.0+) and the timer instead resumes with the items filled so
  * far plus `$trigger: 'timeout'`. A plain resolve on a batch row remains an
- * admin override that resolves the whole row with its payload.
+ * admin override that resolves the whole row with its payload. Entries
+ * already satisfied go in `filled` (hotmesh 0.31.0+), keyed by item key
+ * with `payload`, `at` from the source of record, and an optional `actor`;
+ * the row starts with that progress and delivers them with the collection.
  *
  * **Open accumulation — items arrive over time (hotmesh 0.29.0+).** Declare
  * `accumulate` and the escalation holds items added via `accumulateItem`

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' }],
  * });
  * ```
  *
@@ -166,7 +168,10 @@ function toEngineConfig(escalation) {
  * items persist on the terminal row for audit. Add `partialOnTimeout: true`
  * (hotmesh 0.29.0+) and the timer instead resumes with the items filled so
  * far plus `$trigger: 'timeout'`. A plain resolve on a batch row remains an
- * admin override that resolves the whole row with its payload.
+ * admin override that resolves the whole row with its payload. Entries
+ * already satisfied go in `filled` (hotmesh 0.31.0+), keyed by item key
+ * with `payload`, `at` from the source of record, and an optional `actor`;
+ * the row starts with that progress and delivers them with the collection.
  *
  * **Open accumulation — items arrive over time (hotmesh 0.29.0+).** Declare
  * `accumulate` and the escalation holds items added via `accumulateItem`

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; } });