@hotmeshio/long-tail 0.22.1 → 0.22.3

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' }],
  * });
  * ```
  *

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/role/badge-grant.d.ts

@@ -0,0 +1,5 @@
+import { type RoleBadgeGrant } from './types';
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+export declare function badgeGrantError(value: unknown): string | null;
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+export declare function readBadgeGrant(properties: Record<string, unknown> | null | undefined): RoleBadgeGrant | null;

package/build/services/role/badge-grant.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badgeGrantError = badgeGrantError;
+exports.readBadgeGrant = readBadgeGrant;
+const types_1 = require("./types");
+const SCOPES = ['action', 'subject'];
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+function badgeGrantError(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return 'properties.badge_grant must be an object';
+    const grant = value;
+    const known = new Set(['ttl_seconds', 'max_uses', 'scope']);
+    const extra = Object.keys(grant).filter((k) => !known.has(k));
+    if (extra.length)
+        return `properties.badge_grant has unknown key(s): ${extra.join(', ')}`;
+    if (grant.ttl_seconds !== undefined
+        && (!Number.isInteger(grant.ttl_seconds) || grant.ttl_seconds < 1 || grant.ttl_seconds > 86_400)) {
+        return 'properties.badge_grant.ttl_seconds must be an integer from 1 to 86400';
+    }
+    if (grant.max_uses !== undefined && (!Number.isInteger(grant.max_uses) || grant.max_uses < 0)) {
+        return 'properties.badge_grant.max_uses must be a non-negative integer';
+    }
+    if (grant.scope !== undefined && !SCOPES.includes(grant.scope)) {
+        return `properties.badge_grant.scope must be one of ${SCOPES.join(', ')}`;
+    }
+    return null;
+}
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+function readBadgeGrant(properties) {
+    const value = properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT];
+    if (value === undefined || value === null || badgeGrantError(value))
+        return null;
+    return value;
+}

package/build/services/role/seed.js

@@ -8,6 +8,8 @@ const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const index_1 = require("./index");
 const sql_1 = require("./sql");
+const badge_grant_1 = require("./badge-grant");
+const types_1 = require("./types");
 /** Recorded on schema snapshots written by the startup apply. */
 exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
 /** Metadata fields shared 1:1 between LTRoleConfig and UpdateRoleInput. */
@@ -79,6 +81,9 @@ async function listConfiguredRoles() {
  * Escalation targets use replace semantics when declared.
  */
 async function applyRoleConfig(cfg, codeOwned) {
+    const grantError = (0, badge_grant_1.badgeGrantError)(cfg.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
+    if (grantError)
+        throw new Error(`role ${cfg.role}: ${grantError}`);
     const created = await (0, index_1.createRole)(cfg.role);
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.GET_ROLE_ROW, [cfg.role]);

package/build/services/role/types.d.ts

@@ -15,6 +15,10 @@ export interface EscalationChain {
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    A badge scanned on a device signed in as a member of this role mints
+ *    its acting grant under this policy instead of the badge scheme's own
+ *    (see api/scan-codes/badge-policy.ts).
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -27,7 +31,17 @@ export declare const ROLE_PROPERTY_KEYS: {
     readonly WORKED_BY: "worked_by";
     readonly KIOSK: "kiosk";
     readonly LINK_VARIABLES: "link_variables";
+    readonly BADGE_GRANT: "badge_grant";
 };
+/** A station role's badge policy. Absent fields keep the badge scheme's value. */
+export interface RoleBadgeGrant {
+    /** How long a badge scan stays primed (1-86400 s). */
+    ttl_seconds?: number;
+    /** 0 = TTL-bound; n = the grant covers n acts. */
+    max_uses?: number;
+    /** 'action' spends a use per act; 'subject' binds to one held item. */
+    scope?: 'action' | 'subject';
+}
 /**
  * One link-variable declaration inside `properties.link_variables`. `name` is
  * the metadata facet key (facet-key charset); `label` is the human annotation

package/build/services/role/types.js

@@ -14,6 +14,10 @@ exports.PORTAL_KEY = exports.PORTAL_LIMITS = exports.ROLE_PROPERTY_KEYS = void 0
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    A badge scanned on a device signed in as a member of this role mints
+ *    its acting grant under this policy instead of the badge scheme's own
+ *    (see api/scan-codes/badge-policy.ts).
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -26,6 +30,7 @@ exports.ROLE_PROPERTY_KEYS = {
     WORKED_BY: 'worked_by',
     KIOSK: 'kiosk',
     LINK_VARIABLES: 'link_variables',
+    BADGE_GRANT: 'badge_grant',
 };
 /** Bounds for a role's portals: how many, and the matrix of each (rows of cells, each cell a pin). */
 exports.PORTAL_LIMITS = {

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

@@ -1,4 +1,5 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
 export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
-export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
-export { assertValidScheme, assertValidSteps } from './validate';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, renderScanCopy, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { assertValidScheme, assertValidSteps, assertValidIdentityRule, assertSchemesCoexist, } from './validate';
+export { isValidGtin, normalizeGtin, displayGtin } from '../../shared/scan-code';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = 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; } });
@@ -19,7 +19,14 @@ var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "interpolateScanTemplate", { enumerable: true, get: function () { return parse_1.interpolateScanTemplate; } });
 Object.defineProperty(exports, "mentionsClaimToken", { enumerable: true, get: function () { return parse_1.mentionsClaimToken; } });
+Object.defineProperty(exports, "renderScanCopy", { enumerable: true, get: function () { return parse_1.renderScanCopy; } });
 Object.defineProperty(exports, "ScanTemplateError", { enumerable: true, get: function () { return parse_1.ScanTemplateError; } });
 var validate_1 = require("./validate");
 Object.defineProperty(exports, "assertValidScheme", { enumerable: true, get: function () { return validate_1.assertValidScheme; } });
 Object.defineProperty(exports, "assertValidSteps", { enumerable: true, get: function () { return validate_1.assertValidSteps; } });
+Object.defineProperty(exports, "assertValidIdentityRule", { enumerable: true, get: function () { return validate_1.assertValidIdentityRule; } });
+Object.defineProperty(exports, "assertSchemesCoexist", { enumerable: true, get: function () { return validate_1.assertSchemesCoexist; } });
+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/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;