@hotmeshio/long-tail 0.22.2 → 0.22.3

package/build/api/scan-codes/verbs.js

@@ -54,7 +54,8 @@ const hold_1 = require("./hold");
 // ctx.auth is the effective actor: the badged person when a grant rode the
 // request, otherwise the authenticated principal. Attribution and write
 // scoping both derive from it, live, inside the escalation APIs.
-async function claimStep(step, ctx) {
+/** Claims the scanned row; a presented choice passes the row it showed. */
+async function claimStep(step, ctx, presentedId) {
     const metadata = await (0, context_1.templated)(step, ctx, (tpl) => (0, context_1.interpolatedMetadata)(step, ctx, tpl));
     if (metadata === null)
         return null;
@@ -67,6 +68,7 @@ async function claimStep(step, ctx) {
         durationMinutes: step.params?.durationMinutes,
         metadata: { ...metadata, ...(0, context_1.provenance)(ctx) },
         restrictRoles: step.query?.roles,
+        assertId: presentedId,
     }, ctx.auth);
     if (result.status === 404)
         return null;
@@ -115,19 +117,19 @@ async function resolveStep(step, ctx, presentedId) {
         ?? (result.data.escalationId ? { id: result.data.escalationId } : undefined);
     return (0, context_1.executed)(escalation, step);
 }
-async function escalateStep(step, ctx) {
+async function escalateStep(step, ctx, presentedId) {
     // Close the located escalation first when configured — the close doubles as
     // the condition check AND the double-scan guard (second scan finds nothing
     // to close and falls through).
     if (step.params?.closeCurrent === 'resolve') {
-        const closed = await resolveStep({ ...step, params: { ...step.params, resolverPayload: step.params?.resolverPayload ?? {} } }, ctx);
+        const closed = await resolveStep({ ...step, params: { ...step.params, resolverPayload: step.params?.resolverPayload ?? {} } }, ctx, presentedId);
         if (closed === null)
             return null;
         if (closed.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
             return closed;
     }
     else if (step.params?.closeCurrent === 'cancel') {
-        const cancelled = await cancelStep(step, ctx);
+        const cancelled = await cancelStep(step, ctx, presentedId);
         if (cancelled === null)
             return null;
         if (cancelled.data?.outcome !== types_1.SCAN_OUTCOMES.EXECUTED)
@@ -152,9 +154,11 @@ async function escalateStep(step, ctx) {
         return created;
     return (0, context_1.executed)(created.data, step);
 }
-async function releaseStep(step, ctx) {
+async function releaseStep(step, ctx, presentedId) {
     // Locate the caller's own claim; release-by-id re-asserts the assignee
     // inside the SDK, so a lost race resolves to 409, never a foreign release.
+    if (presentedId)
+        return releaseById(presentedId, step, ctx);
     const scope = await (0, helpers_1.getEscalationReadScope)(ctx.auth.userId);
     const readable = [...scope.allRoles, ...scope.selfRoles];
     const roles = (0, metadata_1.restrictScopeRoles)(readable, scope.global, step.query?.roles);
@@ -169,23 +173,27 @@ async function releaseStep(step, ctx) {
     });
     if (escalations.length === 0)
         return null;
+    return releaseById(escalations[0].id, step, ctx);
+}
+async function releaseById(id, step, ctx) {
     const notPrimed = await (0, grant_1.spendGrant)(ctx);
     if (notPrimed)
         return notPrimed;
-    const result = await (0, claim_1.releaseEscalation)({ id: escalations[0].id }, ctx.auth);
+    const result = await (0, claim_1.releaseEscalation)({ id }, ctx.auth);
     if (result.status === 403)
         return (0, context_1.forbidden)(result.error);
-    if (result.status === 409)
+    if (result.status === 409 || result.status === 404)
         return (0, context_1.conflict)(result.error);
     if (result.status !== 200)
         return result;
     return (0, context_1.executed)(result.data.escalation, step);
 }
 /**
- * Dispatch one CHOICE verb against an already-presented row. Unlike the step
- * walk (where a miss falls through to the next step), the screen showed this
- * exact row — so a miss answers with the truth: FORBIDDEN when the actor
- * holds no write scope here, CONFLICT when a concurrent actor won the race.
+ * Dispatch one CHOICE verb against an already-presented row. Every verb that
+ * writes the row writes that row by id, so a code shared by several rows
+ * never moves the write elsewhere. Unlike the step walk (where a miss falls
+ * through to the next step), a miss answers with the truth: FORBIDDEN when
+ * the actor holds no write scope here, CONFLICT when a concurrent actor won.
  */
 async function dispatchChoiceVerb(step, ctx, row) {
     switch (step.verb) {
@@ -195,15 +203,15 @@ async function dispatchChoiceVerb(step, ctx, row) {
             return (await (0, hold_1.holdStep)(step, ctx, row));
         case types_1.SCAN_VERBS.CLAIM:
         case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
-            return (await claimStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer claimable'));
+            return (await claimStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer claimable'));
         case types_1.SCAN_VERBS.RESOLVE:
             return (await resolveStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer resolvable'));
         case types_1.SCAN_VERBS.ESCALATE:
-            return (await escalateStep(step, ctx)) ?? (await missReason(step, ctx, 'the item already moved on'));
+            return (await escalateStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item already moved on'));
         case types_1.SCAN_VERBS.RELEASE:
-            return (await releaseStep(step, ctx)) ?? (0, context_1.conflict)('no claim of yours to release');
+            return (await releaseStep(step, ctx, row.id)) ?? (0, context_1.conflict)('no claim of yours to release');
         case types_1.SCAN_VERBS.CANCEL:
-            return (await cancelStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer cancellable'));
+            return (await cancelStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer cancellable'));
         default:
             throw new Error(`unknown choice verb "${step.verb}"`);
     }
@@ -218,7 +226,7 @@ async function missReason(step, ctx, raceMessage) {
     }
     return (0, context_1.conflict)(raceMessage);
 }
-async function cancelStep(step, ctx) {
+async function cancelStep(step, ctx, presentedId) {
     // Claim-as-lock: the atomic claim pins the row to this caller (or extends
     // their claim), serializing concurrent double-scans before the cancel.
     const notPrimed = await (0, grant_1.spendGrant)(ctx);
@@ -229,6 +237,7 @@ async function cancelStep(step, ctx) {
         value: ctx.parsed.target,
         metadata: (0, context_1.provenance)(ctx),
         restrictRoles: step.query?.roles,
+        assertId: presentedId,
     }, ctx.auth);
     if (claimed.status === 404)
         return null;

package/build/index.d.ts

@@ -12,7 +12,7 @@ export * as TaskService from './services/task';
 export * as EscalationService from './services/escalation';
 export * as ConfigService from './services/config';
 export * as UserService from './services/user';
-export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
+export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, displayGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
 export * as TopicService from './services/topics';
 export { seedSystemTopics, seedConfigTopics } from './services/topics/system-topics';
 export { ltConfig } from './modules/ltconfig';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = void 0;
+exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -76,6 +76,7 @@ Object.defineProperty(exports, "assertValidScanSteps", { enumerable: true, get:
 Object.defineProperty(exports, "assertValidScanIdentityRule", { enumerable: true, get: function () { return scan_code_1.assertValidIdentityRule; } });
 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; } });
 exports.TopicService = __importStar(require("./services/topics"));
 var system_topics_1 = require("./services/topics/system-topics");
 Object.defineProperty(exports, "seedSystemTopics", { enumerable: true, get: function () { return system_topics_1.seedSystemTopics; } });

package/build/sdk/index.d.ts

@@ -213,6 +213,7 @@ export declare function createClient(options?: LTClientOptions): {
             metadata?: Record<string, any>;
             provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
             restrictRoles?: string[];
+            assertId?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveByMetadata: (input: {
             key: string;

package/build/services/escalation/claim-asserted.d.ts

@@ -0,0 +1,10 @@
+import type { ClaimResult } from './types';
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+export declare const CLAIM_ASSERTED = "WITH target AS MATERIALIZED (\n  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations\n  WHERE id = $6\n    AND metadata @> $1::jsonb\n    AND ($4::text[] IS NULL OR role = ANY($4::text[]))\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n  FOR UPDATE SKIP LOCKED\n)\nUPDATE public.hmsh_escalations e\nSET assigned_to      = $2,\n    claimed_at       = NOW(),\n    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),\n    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),\n    metadata         = CASE WHEN $5::jsonb IS NOT NULL\n                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb\n                            ELSE e.metadata END,\n    updated_at       = NOW()\nFROM target WHERE e.id = target.id\nRETURNING e.*, target.prior_assigned_to\n";
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+export declare function claimAssertedByMetadata(id: string, key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ClaimResult | null>;

package/build/services/escalation/claim-asserted.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAIM_ASSERTED = void 0;
+exports.claimAssertedByMetadata = claimAssertedByMetadata;
+const db_1 = require("../../lib/db");
+const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
+const client_1 = require("./client");
+const crud_1 = require("./crud");
+const map_1 = require("./map");
+/**
+ * Claims one named row, the same claim `claimByMetadata` makes on the row it
+ * picks: pending, the facet still matches, the role is allowed, and no live
+ * claim by someone else. One statement; a miss writes nothing.
+ * $1=filter $2=assignee $3=minutes $4=roles $5=metadata patch $6=id
+ */
+exports.CLAIM_ASSERTED = `\
+WITH target AS MATERIALIZED (
+  SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations
+  WHERE id = $6
+    AND metadata @> $1::jsonb
+    AND ($4::text[] IS NULL OR role = ANY($4::text[]))
+    AND status = 'pending'
+    AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE public.hmsh_escalations e
+SET assigned_to      = $2,
+    claimed_at       = NOW(),
+    claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),
+    assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),
+    metadata         = CASE WHEN $5::jsonb IS NOT NULL
+                            THEN COALESCE(e.metadata, '{}'::jsonb) || $5::jsonb
+                            ELSE e.metadata END,
+    updated_at       = NOW()
+FROM target WHERE e.id = target.id
+RETURNING e.*, target.prior_assigned_to
+`;
+/** Claim the row `id` when it still carries `key = value`; null when it does not. */
+async function claimAssertedByMetadata(id, key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
+    await (0, client_1.ensureEscalationCompatView)();
+    const { rows } = await (0, db_1.getPool)().query(exports.CLAIM_ASSERTED, [
+        JSON.stringify({ [key]: value }), userId, durationMinutes,
+        allowedRoles ?? null, metadata ? JSON.stringify(metadata) : null, id,
+    ]);
+    if (rows.length === 0)
+        return null;
+    const { prior_assigned_to: prior, ...entry } = rows[0];
+    const escalation = (0, map_1.toEscalationRecord)(entry);
+    (0, crud_1.publishEscalationChange)({
+        type: 'escalation.claimed',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        role: escalation.role,
+        status: 'claimed',
+        data: (0, escalation_wire_1.escalationEventData)(escalation),
+    });
+    return { escalation, isExtension: prior === userId };
+}

package/build/services/escalation/facets.d.ts

@@ -2,7 +2,9 @@ import type { ClaimedGroup, FacetQuery, GroupSummary, LTEscalationRecord } from
 /** Ensure the compat view + the origin_id index exist before the first query. */
 export declare function ensureFacetReady(): Promise<void>;
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-export declare function searchByFacets(query: FacetQuery): Promise<{
+export declare function searchByFacets(query: FacetQuery, opts?: {
+    total?: boolean;
+}): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
 }>;

package/build/services/escalation/facets.js

@@ -45,7 +45,7 @@ function ensureFacetReady() {
 }
 // ── Reads ────────────────────────────────────────────────────────────────────
 /** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
-async function searchByFacets(query) {
+async function searchByFacets(query, opts = {}) {
     await ensureFacetReady();
     const pool = (0, db_1.getPool)();
     const params = [];
@@ -55,9 +55,13 @@ async function searchByFacets(query) {
     const offset = query.offset ?? 0;
     const [rows, count] = await Promise.all([
         pool.query(`SELECT * FROM public.lt_escalations WHERE ${where} ORDER BY ${order} LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit, offset]),
-        pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
+        // A caller that only picks among a few rows skips the count.
+        opts.total === false
+            ? null
+            : pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
     ]);
-    return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: count.rows[0]?.total ?? 0 };
+    const escalations = (0, map_1.toEscalationRecords)(rows.rows);
+    return { escalations, total: count ? count.rows[0]?.total ?? 0 : escalations.length };
 }
 /**
  * Order-level view of the pond — what a batched dispatcher reads to page by

package/build/services/escalation/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './crud';
+export { claimAssertedByMetadata } from './claim-asserted';
 export * from './batch';
 export * from './accumulate';
 export * from './bulk';

package/build/services/escalation/index.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
+exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
+var claim_asserted_1 = require("./claim-asserted");
+Object.defineProperty(exports, "claimAssertedByMetadata", { enumerable: true, get: function () { return claim_asserted_1.claimAssertedByMetadata; } });
 __exportStar(require("./batch"), exports);
 __exportStar(require("./accumulate"), exports);
 __exportStar(require("./bulk"), exports);

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

@@ -1,4 +1,4 @@
-import type { EscalationLookupRef } from '../../types/escalation';
+import { type EscalationLookupRef } from '../../types/escalation';
 interface KnowledgeSnapshot {
     data: Record<string, unknown>;
     tags: string[];
@@ -6,24 +6,36 @@ interface KnowledgeSnapshot {
 export interface ResolvedLookup {
     domain: string;
     key: string;
-    version: number;
+    /** The edition served; null when a current ref found no edition. */
+    version: number | null;
+    /** The ref follows the newest edition rather than pinning one. */
+    current?: true;
     as?: string;
     data: Record<string, unknown> | null;
     missing?: boolean;
 }
 /** The immutable snapshot at (domain, key, version), or null when absent. */
 export declare function getKnowledgeSnapshot(domain: string, key: string, version: number): Promise<KnowledgeSnapshot | null>;
+/**
+ * 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.
+ */
+export declare function resolveRefEdition(ref: EscalationLookupRef, asOf?: string | null): Promise<{
+    version: number;
+    snapshot: KnowledgeSnapshot;
+} | null>;
 /**
  * Resolve a metadata `lookups` array into the form-context `lookup` domain:
  * { [as ?? key]: data }. Returns null when there is nothing to resolve, so
  * escalations without refs cost zero SQL. Missing snapshots are omitted —
  * interpolated selects then fail closed rather than render the wrong list.
  */
-export declare function resolveLookupContext(refs: unknown): Promise<Record<string, unknown> | null>;
+export declare function resolveLookupContext(refs: unknown, asOf?: string | null): Promise<Record<string, unknown> | null>;
 /**
  * Full per-ref resolution for the lookups endpoint: every ref answers, with
  * `missing: true` marking a pin that has no snapshot — fail-visible per ref
  * without failing the batch.
  */
-export declare function resolveLookupRefs(refs: EscalationLookupRef[]): Promise<ResolvedLookup[]>;
+export declare function resolveLookupRefs(refs: EscalationLookupRef[], asOf?: string | null): Promise<ResolvedLookup[]>;
 export {};

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