@hotmeshio/long-tail 0.14.3 → 0.16.0

package/build/routes/knowledge.js

@@ -35,7 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const api = __importStar(require("../api/knowledge"));
+const auth_1 = require("../modules/auth");
 const router = (0, express_1.Router)();
+// The knowledge store is a builder surface (superadmin or engineer) — the
+// same gate as the dashboard's Knowledge page. Members reach knowledge
+// content only through escalation lookup refs: an escalation's
+// envelope.lookups grants its readers exactly the pinned editions it names,
+// served by GET /api/escalations/:id/lookups.
+router.use(auth_1.requireBuilder);
 /**
  * GET /api/knowledge/domains
  * List all knowledge domains with entry counts.
@@ -66,8 +73,9 @@ router.get('/entries', async (req, res) => {
 });
 /**
  * GET /api/knowledge/entry
- * Get a single knowledge entry.
- * Query: ?domain=...&key=...
+ * Get a single knowledge entry — the live edition, or an immutable snapshot
+ * when ?version=N is present.
+ * Query: ?domain=...&key=...&version=N
  */
 router.get('/entry', async (req, res) => {
     const domain = req.query.domain;
@@ -76,9 +84,34 @@ router.get('/entry', async (req, res) => {
         res.status(400).json({ error: 'domain and key are required' });
         return;
     }
+    if (req.query.version !== undefined) {
+        const version = Number(req.query.version);
+        if (!Number.isInteger(version) || version < 1) {
+            res.status(400).json({ error: 'version must be a positive integer' });
+            return;
+        }
+        const result = await api.getEntryVersion({ domain, key, version });
+        res.status(result.status).json(result.data ?? { error: result.error });
+        return;
+    }
     const result = await api.getEntry({ domain, key });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/knowledge/entry/versions
+ * List every edition of an entry, newest first, with the current one marked.
+ * Query: ?domain=...&key=...
+ */
+router.get('/entry/versions', async (req, res) => {
+    const domain = req.query.domain;
+    const key = req.query.key;
+    if (!domain || !key) {
+        res.status(400).json({ error: 'domain and key are required' });
+        return;
+    }
+    const result = await api.listEntryVersions({ domain, key });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * POST /api/knowledge/entry
  * Create or update a knowledge entry.

package/build/sdk/index.d.ts

@@ -127,6 +127,9 @@ export declare function createClient(options?: LTClientOptions): {
         get: (input: {
             id: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getLookups: (input: {
+            id: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         getByWorkflowId: typeof escalationsApi.getEscalationsByWorkflowId;
         escalate: (input: {
             id: string;
@@ -459,6 +462,8 @@ export declare function createClient(options?: LTClientOptions): {
         listDomains: typeof knowledgeApi.listDomains;
         listEntries: typeof knowledgeApi.listEntries;
         getEntry: typeof knowledgeApi.getEntry;
+        getEntryVersion: typeof knowledgeApi.getEntryVersion;
+        listEntryVersions: typeof knowledgeApi.listEntryVersions;
         storeEntry: typeof knowledgeApi.storeEntry;
         setField: typeof knowledgeApi.setField;
         removeField: typeof knowledgeApi.removeField;

package/build/sdk/index.js

@@ -124,6 +124,7 @@ function createClient(options = {}) {
             getStats: bindAuth(escalationsApi.getEscalationStats, auth),
             getStationMetrics: bindAuth(escalationsApi.getStationMetrics, auth),
             get: bindAuth(escalationsApi.getEscalation, auth),
+            getLookups: bindAuth(escalationsApi.getEscalationLookups, auth),
             getByWorkflowId: escalationsApi.getEscalationsByWorkflowId,
             escalate: bindAuth(escalationsApi.escalateToRole, auth),
             claim: bindAuth(escalationsApi.claimEscalation, auth),
@@ -346,6 +347,8 @@ function createClient(options = {}) {
             listDomains: knowledgeApi.listDomains,
             listEntries: knowledgeApi.listEntries,
             getEntry: knowledgeApi.getEntry,
+            getEntryVersion: knowledgeApi.getEntryVersion,
+            listEntryVersions: knowledgeApi.listEntryVersions,
             storeEntry: knowledgeApi.storeEntry,
             setField: knowledgeApi.setField,
             removeField: knowledgeApi.removeField,

package/build/services/diagnostics/patterns.js

@@ -59,7 +59,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
     // ── Pattern: normal_wait ──────────────────────────────────────────────────
     // Two paths reach here:
     // 1. Open signal in event stream (signal_wait_started) + pending escalation
-    // 2. No terminal event + pending escalation (conditionLT path — no signal_wait_started in export)
+    // 2. No terminal event + pending escalation (conditional path — no signal_wait_started in export)
     const isRunning = !events.some(e => e.event_type === 'workflow_execution_completed' || e.event_type === 'workflow_execution_failed');
     const isNormalWait = (openSignals.length > 0 && escalationRow?.status === 'pending') ||
         (isRunning && events.length > 0 && escalationRow?.status === 'pending');

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

@@ -85,7 +85,7 @@ export declare function resolveEscalationsAllOrNone(items: Array<{
 export declare function getEscalationsByIds(ids: string[]): Promise<LTEscalationRecord[]>;
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
- * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
+ * passed to `conditional(signalId, config)` / `condition(signalId, config)`.
  * Returns null when no row carries that key.
  */
 export declare function getEscalationBySignalKey(signalKey: string): Promise<LTEscalationRecord | null>;
@@ -222,9 +222,9 @@ export interface ResolveByMetadataResult {
     outcome: 'resolved' | 'signal_required' | 'conflict' | 'not_found' | 'validation_required';
     /** The resolved escalation (when outcome = 'resolved') */
     escalation?: LTEscalationRecord;
-    /** Legacy conditionLT signal info (when signalId is set, caller uses handle.signal) */
+    /** Legacy conditional signal info (when signalId is set, caller uses handle.signal) */
     signalId?: string;
-    /** Atomic conditionLT signal key (when signalKey is set, caller uses SDK resolve to atomically mark+signal) */
+    /** Atomic conditional signal key (when signalKey is set, caller uses SDK resolve to atomically mark+signal) */
     signalKey?: string;
     escalationId?: string;
     workflowId?: string;

package/build/services/escalation/crud.js

@@ -27,6 +27,7 @@ exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
 const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const escalation_1 = require("../../types/escalation");
 const client_1 = require("./client");
 const queries_1 = require("./queries");
 const map_1 = require("./map");
@@ -48,6 +49,12 @@ function publishEscalationChange(...args) {
 // few; this avoids a silent page cap without an unbounded scan.
 const LOOKUP_LIMIT = 1000;
 async function createEscalation(input) {
+    // Lookup refs must pin immutable knowledge editions — reject malformed refs
+    // before the row exists rather than let a broken grant reach the queue.
+    const envelopeObj = (0, map_1.toEnvelopeObject)(input.envelope);
+    if (envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS] !== undefined) {
+        (0, escalation_1.assertLookupRefs)(envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]);
+    }
     const client = await (0, client_1.escalations)();
     const entry = await client.create({
         type: input.type,
@@ -63,7 +70,7 @@ async function createEscalation(input) {
         workflowType: input.workflow_type,
         traceId: input.trace_id,
         spanId: input.span_id,
-        envelope: (0, map_1.toEnvelopeObject)(input.envelope),
+        envelope: envelopeObj,
         metadata: input.metadata,
         escalationPayload: (0, map_1.toJsonObject)(input.escalation_payload),
     });
@@ -235,7 +242,7 @@ async function getEscalationsByIds(ids) {
 }
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
- * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
+ * passed to `conditional(signalId, config)` / `condition(signalId, config)`.
  * Returns null when no row carries that key.
  */
 async function getEscalationBySignalKey(signalKey) {

package/build/services/escalation/resolver-validation.js

@@ -24,6 +24,7 @@ exports.toValidationErrorBody = toValidationErrorBody;
 const form_validation_1 = require("../../shared/form-validation");
 const submit_guard_1 = require("./submit-guard");
 const enforcement_cache_1 = require("../role/enforcement-cache");
+const knowledge_1 = require("../knowledge");
 const escalation_1 = require("../../types/escalation");
 const validation_1 = require("../../types/validation");
 function parseJsonOrNull(value) {
@@ -73,11 +74,16 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, r
     const envelope = loadEnvelope
         ? await loadEnvelope()
         : parseJsonOrNull(escalation.envelope) ?? {};
+    // Versioned lookup refs ride the envelope; they resolve through the
+    // immutable snapshot cache, so enforcement reads the exact editions the
+    // form rendered from. Rows without refs cost zero SQL here.
+    const lookup = await (0, knowledge_1.resolveLookupContext)(envelope[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]);
     const ctx = {
         escalation: escalation,
         metadata,
         envelope,
         payload: parseJsonOrNull(escalation.escalation_payload),
+        ...(lookup ? { lookup } : {}),
     };
     const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, ctx);
     // The query precondition (x-lt-submit-guard): reject while the embedded query

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

@@ -43,7 +43,7 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * 3. `metadata.signal_id` present, row already claimed and claim not expired →
  *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
  *    caller returns 409 without re-signaling.
- * 4. `signal_key` present (atomic conditionLT) → the write skips entirely.
+ * 4. `signal_key` present (atomic conditional) → the write skips entirely.
  *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
  *
  * Signal_id hardening: the write runs for signal_id rows too, stamping

package/build/services/escalation/sql.js

@@ -151,7 +151,7 @@ function searchEscalationsQuery(orderBy) {
  * 3. `metadata.signal_id` present, row already claimed and claim not expired →
  *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
  *    caller returns 409 without re-signaling.
- * 4. `signal_key` present (atomic conditionLT) → the write skips entirely.
+ * 4. `signal_key` present (atomic conditional) → the write skips entirely.
  *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
  *
  * Signal_id hardening: the write runs for signal_id rows too, stamping

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

@@ -0,0 +1,18 @@
+export * from './lookup-cache';
+export interface KnowledgeVersionMeta {
+    version: number;
+    change_summary: string | null;
+    created_at: string;
+    is_current: boolean;
+}
+/** The immutable snapshot at (domain, key, version), uncached full shape. */
+export declare function getKnowledgeVersion(domain: string, key: string, version: number): Promise<{
+    domain: string;
+    key: string;
+    version: number;
+    data: Record<string, unknown>;
+    tags: string[];
+    created_at: string;
+} | null>;
+/** Every edition of an entry, newest first, with the current one marked. */
+export declare function listKnowledgeVersions(domain: string, key: string): Promise<KnowledgeVersionMeta[]>;

package/build/services/knowledge/index.js

@@ -0,0 +1,52 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.getKnowledgeVersion = getKnowledgeVersion;
+exports.listKnowledgeVersions = listKnowledgeVersions;
+/**
+ * Knowledge version reads. Writes live in system/activities/knowledge.ts and
+ * snapshot every data change; this module reads the immutable editions those
+ * writes produce, and resolves escalation lookup refs against them.
+ */
+const db_1 = require("../../lib/db");
+const sql_1 = require("./sql");
+__exportStar(require("./lookup-cache"), exports);
+/** The immutable snapshot at (domain, key, version), uncached full shape. */
+async function getKnowledgeVersion(domain, key, version) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_KNOWLEDGE_VERSION, [domain, key, version]);
+    if (!rows[0])
+        return null;
+    return {
+        domain: rows[0].domain,
+        key: rows[0].key,
+        version: rows[0].version,
+        data: rows[0].data ?? {},
+        tags: rows[0].tags ?? [],
+        created_at: rows[0].created_at.toISOString(),
+    };
+}
+/** Every edition of an entry, newest first, with the current one marked. */
+async function listKnowledgeVersions(domain, key) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_KNOWLEDGE_VERSIONS, [domain, key]);
+    return rows.map((r) => ({
+        version: r.version,
+        change_summary: r.change_summary ?? null,
+        created_at: r.created_at.toISOString(),
+        is_current: r.is_current === true,
+    }));
+}

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

@@ -0,0 +1,29 @@
+import type { EscalationLookupRef } from '../../types/escalation';
+interface KnowledgeSnapshot {
+    data: Record<string, unknown>;
+    tags: string[];
+}
+export interface ResolvedLookup {
+    domain: string;
+    key: string;
+    version: number;
+    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>;
+/**
+ * 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>;
+/**
+ * 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 {};

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

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKnowledgeSnapshot = getKnowledgeSnapshot;
+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.
+ */
+const db_1 = require("../../lib/db");
+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();
+/** The immutable snapshot at (domain, key, version), or null when absent. */
+async function getKnowledgeSnapshot(domain, key, version) {
+    const cacheKey = `${domain} ${key} ${version}`;
+    const hit = snapshotCache.get(cacheKey);
+    if (hit) {
+        snapshotCache.delete(cacheKey);
+        snapshotCache.set(cacheKey, hit);
+        return hit;
+    }
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_KNOWLEDGE_VERSION, [domain, key, version]);
+    if (!rows[0])
+        return null;
+    const snapshot = {
+        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);
+    }
+    return snapshot;
+}
+/** Structural check for one ref — malformed entries in stored metadata are skipped, not fatal. */
+function isLookupRef(ref) {
+    if (!ref || typeof ref !== 'object')
+        return false;
+    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
+        && (r.as === undefined || (typeof r.as === 'string' && r.as.length > 0));
+}
+/**
+ * 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.
+ */
+async function resolveLookupContext(refs) {
+    if (!Array.isArray(refs) || refs.length === 0)
+        return null;
+    const valid = refs.filter(isLookupRef);
+    if (valid.length === 0)
+        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;
+    }
+    return ctx;
+}
+/**
+ * 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.
+ */
+async function resolveLookupRefs(refs) {
+    const resolved = [];
+    for (const ref of refs) {
+        if (!isLookupRef(ref))
+            continue;
+        const snapshot = await getKnowledgeSnapshot(ref.domain, ref.key, ref.version);
+        resolved.push({
+            domain: ref.domain,
+            key: ref.key,
+            version: ref.version,
+            ...(ref.as ? { as: ref.as } : {}),
+            data: snapshot ? snapshot.data : null,
+            ...(snapshot ? {} : { missing: true }),
+        });
+    }
+    return resolved;
+}

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

@@ -0,0 +1,2 @@
+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";

package/build/services/knowledge/sql.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+  WHERE domain = $1 AND key = $2 AND version = $3`;
+exports.LIST_KNOWLEDGE_VERSIONS = `
+  SELECT v.version, v.change_summary, v.created_at,
+         (v.version = k.current_version) AS is_current
+  FROM lt_knowledge_versions v
+  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`;

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

@@ -37,6 +37,8 @@ exports.registerHumanQueueTools = registerHumanQueueTools;
 const crypto = __importStar(require("crypto"));
 const zod_1 = require("zod");
 const escalationService = __importStar(require("../escalation"));
+const knowledge_1 = require("../knowledge");
+const lookups_1 = require("../../api/escalations/lookups");
 // ── Schemas (extracted to break TS2589 deep-instantiation in registerTool generics) ──
 const escalateSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
@@ -50,6 +52,9 @@ const escalateSchema = zod_1.z.object({
 const checkResolutionSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation ID to check'),
 });
+const getEscalationLookupsSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation whose pinned knowledge lookups to resolve'),
+});
 const getAvailableWorkSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Role to filter by'),
     limit: zod_1.z.number().optional().default(10).describe('Max results to return'),
@@ -153,6 +158,31 @@ function registerHumanQueueTools(server) {
             content: [{ type: 'text', text: JSON.stringify(result) }],
         };
     });
+    // ── get_escalation_lookups ──────────────────────────────────────────
+    server.registerTool('get_escalation_lookups', {
+        title: 'Get Escalation Lookups',
+        description: 'Resolve the versioned knowledge lookups pinned on an escalation (envelope.lookups). Each ref answers with its immutable edition; a ref whose snapshot does not exist answers with missing: true.',
+        inputSchema: getEscalationLookupsSchema,
+    }, async (args) => {
+        const escalation = await escalationService.getEscalation(args.escalation_id);
+        if (!escalation) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Escalation not found' }),
+                    }],
+                isError: true,
+            };
+        }
+        const refs = (0, lookups_1.readLookupRefs)(escalation.envelope);
+        const lookups = refs.length > 0 ? await (0, knowledge_1.resolveLookupRefs)(refs) : [];
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ escalation_id: escalation.id, lookups }),
+                }],
+        };
+    });
     // ── get_available_work ──────────────────────────────────────────────
     server.registerTool('get_available_work', {
         title: 'Get Available Work',

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

@@ -1,16 +1,20 @@
 import type { Types } from '@hotmeshio/hotmesh';
+import { 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; it is a
- * compile-time LITERAL the workflow author sets, folded into
- * `metadata.schema_version` before the config reaches the engine, so the pin
- * rides the row's GIN-indexed metadata like any other facet. Folding is a pure
- * transform — no query, no activity — so a pinned `conditionLT` costs exactly
- * what an unpinned one does. Omit it and the resolve UI renders the role's latest
- * form when the escalation is fetched.
+ * 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:
+ * 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
+ * exactly what an unpinned one does. Omit `schemaVersion` and the resolve UI
+ * renders the role's latest form when the escalation is fetched.
  */
 export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
     schemaVersion?: number;
+    lookups?: EscalationLookupRef[];
 };
 /**
  * Wait for a signal and resolve the associated escalation automatically.
@@ -25,7 +29,7 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * from the engine automatically.
  *
  * ```typescript
- * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ * const decision = await conditional<{ approved: boolean }>(signalId, {
  *   role: 'reviewer',
  *   type: 'orderPipeline',
  *   subtype: stationName,
@@ -46,13 +50,27 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * ```typescript
  * import { INTAKE_SCHEMA_VERSION, type IntakeResolverV1 } from './forms';
  *
- * const decision = await conditionLT<IntakeResolverV1>(signalId, {
+ * const decision = await conditional<IntakeResolverV1>(signalId, {
  *   role: INTAKE_ROLE,
  *   description: instructions,
  *   schemaVersion: INTAKE_SCHEMA_VERSION, // the form version this code is written for
  * });
  * ```
  *
+ * **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.
+ *
+ * ```typescript
+ * const decision = await conditional<PickerResolverV1>(signalId, {
+ *   role: 'catalog-picker',
+ *   description: instructions,
+ *   lookups: [{ domain: 'catalog', key: 'materials', version: 2 }],
+ * });
+ * ```
+ *
  * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
  * single wait arms a resume timer alongside the escalation row: when the timer
  * fires first, this helper returns `false`, the row transitions to
@@ -61,7 +79,7 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * timer is inert.
  *
  * ```typescript
- * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ * const decision = await conditional<{ approved: boolean }>(signalId, {
  *   role: 'reviewer',
  *   description: instructions,
  *   metadata: { orderId },
@@ -82,7 +100,7 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * ```typescript
  * import type { EscalationResolution } from '@hotmeshio/hotmesh/types';
  *
- * const decision = await conditionLT<{
+ * const decision = await conditional<{
  *   approved: boolean;
  *   $resolution?: EscalationResolution;
  * }>(signalId, { role: 'print-operator' });
@@ -103,7 +121,9 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  *
  * ```typescript
  * await activities.ltCreateEscalation({ type: 'approval', role: 'reviewer', metadata: { signal_id: signalId } });
- * const decision = await conditionLT<{ approved: boolean }>(signalId);
+ * const decision = await conditional<{ approved: boolean }>(signalId);
  * ```
  */
-export declare function conditionLT<T = Record<string, any>>(signalId: string, escalation?: ConditionEscalationConfig): Promise<T | false | null>;
+export declare function conditional<T = Record<string, any>>(signalId: string, escalation?: ConditionEscalationConfig): Promise<T | false | null>;
+/** @deprecated Alias of {@link conditional}. */
+export declare const conditionLT: typeof conditional;