@hotmeshio/long-tail 0.14.4 → 0.16.1

package/README.md

@@ -2,9 +2,9 @@
 
 **The queue durable systems forgot.**
 
-Durable platforms are built around determinism — that is their strength and their blind spot. They give you rich, first-class queues for deterministic work (retry, timeout, `backoffCoefficient`, exactly-once) and an `await condition()` to park a workflow until a signal arrives. All of it assumes the thing you are waiting on will, eventually, behave.
+Durable platforms queue deterministic work well — retries, timeouts, exactly-once — and give you `await condition()` to park a workflow until a signal arrives. But the wait itself is invisible: nothing to find, claim, or measure while it sits there.
 
-Long Tail makes non-determinism a primitive. The same `condition()` wait — except the act of waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. Machines answer some rows, people answer others; the workflow resumes either way, exactly where it paused.
+Long Tail's `conditional` is that same wait made visible. Waiting mints a row that is searchable, claimable, deadlined, and role-gated on a shared metadata surface. A person or a machine answers it; the workflow resumes exactly where it paused.
 
 ```bash
 npm install @hotmeshio/long-tail
@@ -12,26 +12,26 @@ npm install @hotmeshio/long-tail
 
 ## How it works
 
-One workflow, both queues: `proxyActivities` for the deterministic one, `condition()` for non-determinism.
+One workflow, both queues: `proxyActivities` for the deterministic one, `conditional` for non-determinism.
 
 ```typescript
 import { Durable } from '@hotmeshio/hotmesh';
-import type { LTEnvelope } from '@hotmeshio/long-tail';
+import { conditional, type LTEnvelope } from '@hotmeshio/long-tail';
 import * as activities from './activities';
 
 const { analyzeContent } = Durable.workflow.proxyActivities<typeof activities>({ activities });
 
 export async function reviewContent(envelope: LTEnvelope) {
-  // method calls are checkpointed and crash safe
+  // activity calls are checkpointed and crash-safe
   const analysis = await analyzeContent(envelope.data.content);
 
   if (analysis.confidence >= 0.85) {
     return { data: { approved: true, analysis } };
   }
 
-  //role-based escalations are baked-in. create HITL escalations with one call
+  // low confidence: pause as a claimable, role-gated escalation
   const { workflowId } = Durable.workflow.workflowInfo();
-  const decision = await Durable.workflow.condition<{ approved: boolean; notes?: string }>(
+  const decision = await conditional<{ approved: boolean; notes?: string }>(
     `review-${workflowId}`,
     {
       role: 'reviewer',
@@ -40,14 +40,28 @@ export async function reviewContent(envelope: LTEnvelope) {
       description: `Confidence ${analysis.confidence} — needs a human`,
       metadata: { contentId: envelope.data.contentId },
       envelope: { data: envelope.data, analysis },
+      schemaVersion: 1,   // the reviewer form edition this code is written for
     },
   );
 
-  return { data: { approved: decision.approved, analysis } };
+  return { data: { approved: decision && decision.approved, analysis } };
 }
 ```
 
-Two surfaces, one model. A `proxyActivity` targets a machine: call it, get a result. `condition()` targets the external world — a reviewer, an operator, a factory cell. It suspends the workflow and writes a single escalation row carrying everything needed to route the work: the `role` that should act, its `type` and `priority`, and any `metadata` to display or filter on. People work that row through an RBAC-scoped surface — find it, claim it, resolve it — from the dashboard, the API, or MCP, and resolving it resumes the workflow exactly where it paused.
+The `reviewer` role owns a versioned form schema. The platform renders it as the resolver's UI, validates every submission against it, and `schemaVersion` pins the edition this code expects — evolve the form and the payload type together, and rows in flight keep the form they were minted for:
+
+```json
+{
+  "title": "Content Review",
+  "required": ["approved"],
+  "properties": {
+    "approved": { "type": "boolean", "description": "Approve this content?" },
+    "notes":    { "type": "string", "format": "textarea", "description": "What you saw" }
+  }
+}
+```
+
+Two surfaces, one model. A `proxyActivity` targets a machine: call it, get a result. `conditional` targets the external world — a reviewer, an operator, a factory cell. It suspends the workflow and writes a single escalation row carrying everything needed to route the work: the `role` that should act, its `type` and `priority`, and any `metadata` to display or filter on. People work that row through an RBAC-scoped surface — find it, claim it, resolve it — from the dashboard, the API, or MCP, and resolving it resumes the workflow exactly where it paused.
 
 Activities are plain functions:
 

package/build/api/escalations/create.js

@@ -80,6 +80,24 @@ async function createEscalation(input, auth) {
         // stamped here — omitting it means the resolve UI renders the role's latest
         // form at fetch time.
         const metadata = input.metadata ?? {};
+        // Lookup refs ride the envelope under a reserved key with a fixed
+        // contract: version required — a ref pins an immutable knowledge edition,
+        // never a moving target.
+        if (input.envelope) {
+            try {
+                const envelopeObj = JSON.parse(input.envelope);
+                if (envelopeObj && typeof envelopeObj === 'object'
+                    && envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS] !== undefined) {
+                    (0, escalation_1.assertLookupRefs)(envelopeObj[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]);
+                }
+            }
+            catch (refErr) {
+                if (refErr instanceof SyntaxError) {
+                    return { status: 400, error: 'envelope must be valid JSON' };
+                }
+                return { status: 400, error: refErr.message };
+            }
+        }
         const metadataSchema = await roleService.getRoleMetadataSchema(role);
         if (metadataSchema) {
             let validate;

package/build/api/escalations/index.d.ts

@@ -1,6 +1,7 @@
 export { createEscalation } from './create';
 export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacetKeys, getEscalationStats, getStationMetrics } from './list';
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
+export { getEscalationLookups } from './lookups';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -14,6 +14,8 @@ var single_1 = require("./single");
 Object.defineProperty(exports, "getEscalation", { enumerable: true, get: function () { return single_1.getEscalation; } });
 Object.defineProperty(exports, "getEscalationsByWorkflowId", { enumerable: true, get: function () { return single_1.getEscalationsByWorkflowId; } });
 Object.defineProperty(exports, "escalateToRole", { enumerable: true, get: function () { return single_1.escalateToRole; } });
+var lookups_1 = require("./lookups");
+Object.defineProperty(exports, "getEscalationLookups", { enumerable: true, get: function () { return lookups_1.getEscalationLookups; } });
 var claim_1 = require("./claim");
 Object.defineProperty(exports, "claimEscalation", { enumerable: true, get: function () { return claim_1.claimEscalation; } });
 Object.defineProperty(exports, "releaseEscalation", { enumerable: true, get: function () { return claim_1.releaseEscalation; } });

package/build/api/escalations/lookups.d.ts

@@ -0,0 +1,20 @@
+import { type EscalationLookupRef } from '../../types/escalation';
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/** The refs riding the row's envelope under the reserved key, or []. */
+export declare function readLookupRefs(envelope: string | null | undefined): EscalationLookupRef[];
+/**
+ * Resolve an escalation's versioned knowledge lookups.
+ *
+ * The refs on `envelope.lookups` ARE the grant: any user who may read the
+ * escalation may read exactly the pinned editions it names — nothing else in
+ * the knowledge store. Snapshots are immutable, so responses are served from
+ * an in-process cache after the first read; a ref whose snapshot does not
+ * exist answers with `missing: true` rather than failing the batch.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context (must hold the escalation's role)
+ * @returns `{ status: 200, data: { lookups: [{ domain, key, version, as?, data, missing? }] } }`
+ */
+export declare function getEscalationLookups(input: {
+    id: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/lookups.js

@@ -0,0 +1,90 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLookupRefs = readLookupRefs;
+exports.getEscalationLookups = getEscalationLookups;
+const escalationService = __importStar(require("../../services/escalation"));
+const knowledge_1 = require("../../services/knowledge");
+const escalation_1 = require("../../types/escalation");
+const helpers_1 = require("./helpers");
+// ── Lookups ────────────────────────────────────────────────────────────────
+/** The refs riding the row's envelope under the reserved key, or []. */
+function readLookupRefs(envelope) {
+    if (!envelope)
+        return [];
+    try {
+        const parsed = JSON.parse(envelope);
+        const refs = parsed && typeof parsed === 'object'
+            ? parsed[escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]
+            : undefined;
+        return Array.isArray(refs) ? refs : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve an escalation's versioned knowledge lookups.
+ *
+ * The refs on `envelope.lookups` ARE the grant: any user who may read the
+ * escalation may read exactly the pinned editions it names — nothing else in
+ * the knowledge store. Snapshots are immutable, so responses are served from
+ * an in-process cache after the first read; a ref whose snapshot does not
+ * exist answers with `missing: true` rather than failing the batch.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context (must hold the escalation's role)
+ * @returns `{ status: 200, data: { lookups: [{ domain, key, version, as?, data, missing? }] } }`
+ */
+async function getEscalationLookups(input, auth) {
+    try {
+        const escalation = await escalationService.getEscalation(input.id);
+        if (!escalation) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const denied = await (0, helpers_1.assertReadAccess)(auth.userId, escalation);
+        if (denied)
+            return denied;
+        const refs = readLookupRefs(escalation.envelope);
+        if (refs.length === 0) {
+            return { status: 200, data: { lookups: [] } };
+        }
+        const lookups = await (0, knowledge_1.resolveLookupRefs)(refs);
+        return { status: 200, data: { lookups } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/escalations/metadata.d.ts

@@ -43,7 +43,7 @@ export declare function claimByMetadata(input: {
  * Single atomic query with signal guard:
  * - No signal_id → claim + resolve atomically in SQL. One query. Done.
  * - signal_id present → SQL returns the signal info without resolving.
- *   Caller signals the workflow; conditionLT resolves durably inside
+ *   Caller signals the workflow; conditional resolves durably inside
  *   the workflow via ltResolveEscalation.
  *
  * Never does SELECT-then-UPDATE. The SQL CTE handles find + RBAC +

package/build/api/escalations/metadata.js

@@ -124,7 +124,7 @@ async function claimByMetadata(input, auth) {
  * Single atomic query with signal guard:
  * - No signal_id → claim + resolve atomically in SQL. One query. Done.
  * - signal_id present → SQL returns the signal info without resolving.
- *   Caller signals the workflow; conditionLT resolves durably inside
+ *   Caller signals the workflow; conditional resolves durably inside
  *   the workflow via ltResolveEscalation.
  *
  * Never does SELECT-then-UPDATE. The SQL CTE handles find + RBAC +
@@ -180,7 +180,7 @@ async function resolveByMetadata(input, auth) {
         if (result.outcome === 'resolved') {
             return { status: 200, data: { escalation: result.escalation } };
         }
-        // Atomic conditionLT escalation (signal_key set) — SDK resolve atomically marks
+        // Atomic conditional escalation (signal_key set) — SDK resolve atomically marks
         // resolved AND delivers the signal to the waiting condition(), resuming the workflow.
         if (result.signalKey) {
             const resolved = await escalationService.resolveEscalation(result.escalationId, input.resolverPayload);
@@ -192,8 +192,8 @@ async function resolveByMetadata(input, auth) {
                 data: { signaled: true, escalationId: result.escalationId, workflowId: result.workflowId },
             };
         }
-        // Legacy conditionLT escalation (metadata.signal_id set) — signal the workflow,
-        // conditionLT interceptor resolves durably via ltResolveEscalation.
+        // Legacy conditional escalation (metadata.signal_id set) — signal the workflow,
+        // conditional interceptor resolves durably via ltResolveEscalation.
         const { createClient } = await Promise.resolve().then(() => __importStar(require('../../workers')));
         const client = createClient();
         const handle = await client.workflow.getHandle(result.taskQueue, result.workflowType, result.workflowId);

package/build/api/escalations/resolve.d.ts

@@ -4,7 +4,7 @@ import type { LTApiResult, LTApiAuth } from '../../types/sdk';
  * Resolve a pending escalation with a human-provided payload.
  *
  * Handles multiple resolution paths:
- * 1. **Condition signal** — lightweight `conditionLT` signal via metadata.signal_id
+ * 1. **Condition signal** — lightweight `conditional` signal via metadata.signal_id
  * 2. **Signal-routed** — full signal_routing via YAML engine or Durable handle
  * 3. **Strategy triage** — escalation strategy redirects to a triage workflow
  * 4. **Notification-only** — no workflow_type; acknowledge and close

package/build/api/escalations/resolve.js

@@ -54,7 +54,7 @@ const enforcement_cache_1 = require("../../services/role/enforcement-cache");
  * Resolve a pending escalation with a human-provided payload.
  *
  * Handles multiple resolution paths:
- * 1. **Condition signal** — lightweight `conditionLT` signal via metadata.signal_id
+ * 1. **Condition signal** — lightweight `conditional` signal via metadata.signal_id
  * 2. **Signal-routed** — full signal_routing via YAML engine or Durable handle
  * 3. **Strategy triage** — escalation strategy redirects to a triage workflow
  * 4. **Notification-only** — no workflow_type; acknowledge and close
@@ -105,7 +105,7 @@ async function resolveEscalation(input, auth) {
         // workflow's contract, formed by the caller (the React app maps the form to
         // the payload via x-lt-bind before submitting). No server-side transform.
         // Resolution provenance, both surfaces at once: `resolvedBy` rides the
-        // signal to the waiting workflow ($resolution — see conditionLT), and
+        // signal to the waiting workflow ($resolution — see conditional), and
         // `resolved_by` merges into the row's GIN-indexed metadata inside the same
         // atomic resolve, making "who resolved it" `@>`-queryable without a
         // follow-up read.
@@ -116,7 +116,7 @@ async function resolveEscalation(input, auth) {
         // single status='pending'-guarded UPDATE (HotMesh `resolve(metadata)`). Paths that
         // resolve here pass it as the 3rd arg; paths that resume a workflow carry it on the
         // signal so the downstream resolve commits it atomically.
-        // Path A: conditionLT signal
+        // Path A: conditional signal
         const metadataSignalId = escalation.metadata?.signal_id;
         if (metadataSignalId && escalation.workflow_id && escalation.task_queue && escalation.workflow_type) {
             return resolveViaConditionSignal(escalation, resolverPayload, outcome, resolvedBy);
@@ -378,15 +378,15 @@ async function resolveAllOrNone(input, auth) {
     }
 }
 // ── Resolution paths ─────────────────────────────────────────────────────
-/** Path A: lightweight conditionLT signal — inject $escalation_id and signal the running workflow. */
+/** Path A: lightweight conditional signal — inject $escalation_id and signal the running workflow. */
 async function resolveViaConditionSignal(escalation, resolverPayload, metadata, resolvedBy) {
     const signalId = escalation.metadata.signal_id;
     const client = (0, workers_1.createClient)();
     const handle = await client.workflow.getHandle(escalation.task_queue, escalation.workflow_type, escalation.workflow_id);
-    // The row is resolved downstream by the workflow's `conditionLT` → `ltResolveEscalation`.
+    // The row is resolved downstream by the workflow's `conditional` → `ltResolveEscalation`.
     // Carry the outcome patch on the signal ($escalation_metadata, symmetric to $escalation_id)
     // so it merges inside that single atomic resolve — never a separate write here.
-    // $resolution (provenance) is surfaced to the workflow by conditionLT and stripped
+    // $resolution (provenance) is surfaced to the workflow by conditional and stripped
     // from the stored resolver_payload, same as the other $-control keys.
     await handle.signal(signalId, {
         ...resolverPayload,

package/build/api/knowledge.d.ts

@@ -11,6 +11,15 @@ export declare function getEntry(input: {
     domain: string;
     key: string;
 }): Promise<LTApiResult>;
+export declare function getEntryVersion(input: {
+    domain: string;
+    key: string;
+    version: number;
+}): Promise<LTApiResult>;
+export declare function listEntryVersions(input: {
+    domain: string;
+    key: string;
+}): Promise<LTApiResult>;
 export declare function storeEntry(input: {
     domain: string;
     key: string;

package/build/api/knowledge.js

@@ -36,11 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.listDomains = listDomains;
 exports.listEntries = listEntries;
 exports.getEntry = getEntry;
+exports.getEntryVersion = getEntryVersion;
+exports.listEntryVersions = listEntryVersions;
 exports.storeEntry = storeEntry;
 exports.setField = setField;
 exports.removeField = removeField;
 exports.deleteEntry = deleteEntry;
 const knowledgeActivity = __importStar(require("../system/activities/knowledge"));
+const knowledgeService = __importStar(require("../services/knowledge"));
 async function listDomains() {
     try {
         const result = await knowledgeActivity.listDomains();
@@ -68,6 +71,27 @@ async function getEntry(input) {
         return { status: 500, error: err.message };
     }
 }
+async function getEntryVersion(input) {
+    try {
+        const result = await knowledgeService.getKnowledgeVersion(input.domain, input.key, input.version);
+        if (!result) {
+            return { status: 404, error: `No version ${input.version} of ${input.domain}/${input.key}` };
+        }
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function listEntryVersions(input) {
+    try {
+        const versions = await knowledgeService.listKnowledgeVersions(input.domain, input.key);
+        return { status: 200, data: { domain: input.domain, key: input.key, versions } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 async function storeEntry(input) {
     try {
         const result = await knowledgeActivity.storeKnowledge(input);

package/build/bin/ltc.js

@@ -145,6 +145,10 @@ escCmd.command('list')
 escCmd.command('get <id>')
     .option('--json', 'JSON output')
     .action(wrap(esc.getEscalation));
+escCmd.command('lookups <id>')
+    .description('Resolve the versioned knowledge lookups pinned on an escalation')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.getLookups));
 escCmd.command('claim <id>')
     .option('--duration <minutes>', 'Claim duration in minutes')
     .action(wrap(esc.claimEscalation));
@@ -290,8 +294,14 @@ kbCmd.command('list <domain>')
     .option('-q, --quiet', 'Keys only')
     .action(wrap(kb.listEntries));
 kbCmd.command('get <domain> <key>')
+    .option('--version <n>', 'Fetch this immutable edition instead of the live entry')
     .option('--json', 'JSON output')
     .action(wrap(kb.getEntry));
+kbCmd.command('versions <domain> <key>')
+    .description('List every immutable edition of an entry, newest first')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'Versions only')
+    .action(wrap(kb.listVersions));
 kbCmd.command('set <domain> <key> <path> <value>')
     .option('--json', 'JSON output')
     .description('Set a value at a dot-path (e.g., ltc kb set research screenshots google.holiday "Mother\'s Day")')

package/build/index.d.ts

@@ -3,7 +3,7 @@ export { midnightTheme } from './themes/midnight';
 export { registerLT, createLTInterceptor } from './services/interceptor';
 export { createLTActivityInterceptor } from './services/interceptor/activity-interceptor';
 export { executeLT } from './services/orchestrator';
-export { conditionLT } from './services/orchestrator/condition';
+export { conditional, conditionLT } from './services/orchestrator/condition';
 export type { ExecuteLTOptions } from './services/orchestrator/types';
 export { JwtAuthAdapter, createAuthMiddleware, requireAuth, requireAdmin, signToken, setAuthAdapter } from './modules/auth';
 export * from './types';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = 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.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionLT = 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 = void 0;
+exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = 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.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = 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 = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -55,6 +55,7 @@ Object.defineProperty(exports, "createLTActivityInterceptor", { enumerable: true
 var orchestrator_1 = require("./services/orchestrator");
 Object.defineProperty(exports, "executeLT", { enumerable: true, get: function () { return orchestrator_1.executeLT; } });
 var condition_1 = require("./services/orchestrator/condition");
+Object.defineProperty(exports, "conditional", { enumerable: true, get: function () { return condition_1.conditional; } });
 Object.defineProperty(exports, "conditionLT", { enumerable: true, get: function () { return condition_1.conditionLT; } });
 var auth_1 = require("./modules/auth");
 Object.defineProperty(exports, "JwtAuthAdapter", { enumerable: true, get: function () { return auth_1.JwtAuthAdapter; } });

package/build/lib/cli/commands/escalations.d.ts

@@ -17,6 +17,9 @@ export declare function listEscalations(opts: ListOptions): Promise<void>;
 export declare function getEscalation(id: string, opts: {
     json?: boolean;
 }): Promise<void>;
+export declare function getLookups(id: string, opts: {
+    json?: boolean;
+}): Promise<void>;
 export declare function claimEscalation(id: string, opts: {
     duration?: string;
 }): Promise<void>;

package/build/lib/cli/commands/escalations.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listEscalations = listEscalations;
 exports.getEscalation = getEscalation;
+exports.getLookups = getLookups;
 exports.claimEscalation = claimEscalation;
 exports.releaseEscalation = releaseEscalation;
 exports.resolveEscalation = resolveEscalation;
@@ -72,6 +73,30 @@ async function getEscalation(id, opts) {
     console.log(`  Created: ${(0, format_1.formatTime)(data.created_at)}  Updated: ${(0, format_1.formatTime)(data.updated_at)}`);
     console.log();
 }
+async function getLookups(id, opts) {
+    const data = await (0, client_1.apiFetch)(`/escalations/${id}/lookups`);
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const lookups = data.lookups ?? [];
+    if (lookups.length === 0) {
+        console.log(picocolors_1.default.dim('\n  No lookup refs on this escalation.\n'));
+        return;
+    }
+    console.log();
+    for (const l of lookups) {
+        const label = `${l.domain}/${l.key} v${l.version}${l.as ? ` (as ${l.as})` : ''}`;
+        if (l.missing) {
+            console.log(`  ${picocolors_1.default.yellow('missing')} ${picocolors_1.default.bold(label)}`);
+        }
+        else {
+            console.log(`  ${picocolors_1.default.green('✓')} ${picocolors_1.default.bold(label)}`);
+            console.log(`    ${JSON.stringify(l.data)}`);
+        }
+    }
+    console.log();
+}
 async function claimEscalation(id, opts) {
     const body = {};
     if (opts.duration)

package/build/lib/cli/commands/knowledge.d.ts

@@ -10,6 +10,11 @@ export declare function listEntries(domain: string, opts: {
 }): Promise<void>;
 export declare function getEntry(domain: string, key: string, opts: {
     json?: boolean;
+    version?: string;
+}): Promise<void>;
+export declare function listVersions(domain: string, key: string, opts: {
+    json?: boolean;
+    quiet?: boolean;
 }): Promise<void>;
 export declare function setField(domain: string, key: string, path: string, value: string, opts: {
     json?: boolean;

package/build/lib/cli/commands/knowledge.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.listDomains = listDomains;
 exports.listEntries = listEntries;
 exports.getEntry = getEntry;
+exports.listVersions = listVersions;
 exports.setField = setField;
 exports.removeField = removeField;
 exports.deleteEntry = deleteEntry;
@@ -42,6 +43,8 @@ async function listEntries(domain, opts) {
 }
 async function getEntry(domain, key, opts) {
     const params = new URLSearchParams({ domain, key });
+    if (opts.version)
+        params.set('version', opts.version);
     const data = await (0, client_1.apiFetch)(`/knowledge/entry?${params}`);
     if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
@@ -51,13 +54,25 @@ async function getEntry(domain, key, opts) {
         console.log(picocolors_1.default.yellow(`\n  Not found: ${domain}/${key}\n`));
         return;
     }
-    console.log(`\n  ${picocolors_1.default.bold(`${domain}/${key}`)} ${picocolors_1.default.dim(data.id)}`);
+    const versionLabel = data.version ?? data.current_version;
+    console.log(`\n  ${picocolors_1.default.bold(`${domain}/${key}`)}${versionLabel != null ? ` ${picocolors_1.default.dim(`v${versionLabel}`)}` : ''} ${data.id ? picocolors_1.default.dim(data.id) : ''}`);
     if (data.tags?.length)
         console.log(`  Tags: ${data.tags.join(', ')}`);
-    console.log(`  Updated: ${(0, format_1.formatTime)(data.updated_at)}\n`);
+    console.log(`  Updated: ${(0, format_1.formatTime)(data.updated_at ?? data.created_at)}\n`);
     console.log(JSON.stringify(data.data, null, 2));
     console.log();
 }
+const VERSION_COLUMNS = [
+    { key: 'version', label: 'Version', width: 8, align: 'right' },
+    { key: 'is_current', label: 'Current', width: 8, format: (v) => (v ? '●' : '') },
+    { key: 'change_summary', label: 'Summary', width: 32, format: (v) => v ?? '' },
+    { key: 'created_at', label: 'Created', width: 12, format: format_1.formatTime },
+];
+async function listVersions(domain, key, opts) {
+    const params = new URLSearchParams({ domain, key });
+    const data = await (0, client_1.apiFetch)(`/knowledge/entry/versions?${params}`);
+    (0, format_1.output)(data, data.versions || [], VERSION_COLUMNS, opts, 'version');
+}
 async function setField(domain, key, path, value, opts) {
     // Try to parse as JSON, fall back to string
     let parsed = value;

package/build/lib/cli/scanner.js

@@ -89,6 +89,8 @@ function extractPrimitives(source) {
             primitives.push(p);
         }
     }
+    if (/\bconditional\s*[<(]/.test(source) && !seen.has('conditional'))
+        primitives.push('conditional');
     if (/conditionLT/.test(source) && !seen.has('conditionLT'))
         primitives.push('conditionLT');
     if (/executeLT/.test(source) && !seen.has('executeLT'))

package/build/lib/db/schemas/033_knowledge_versions.sql

@@ -0,0 +1,33 @@
+-- Migration 033: Versioned knowledge entries.
+--
+-- Every knowledge entry carries a current_version counter, and every write
+-- that changes `data` snapshots the new edition into lt_knowledge_versions
+-- (same pattern as lt_role_schemas). Snapshots are immutable: escalation
+-- lookup refs pin {domain, key, version} and always resolve to the exact
+-- edition the workflow was written against.
+--
+-- ON DELETE CASCADE is deliberate: a delete-then-recreate restarts the entry
+-- at version 1, and stale snapshots must not misattribute the old entry's
+-- data to the new lineage. A pinned ref to a deleted entry fails visible
+-- (missing) rather than resolving to the wrong list.
+
+CREATE TABLE IF NOT EXISTS lt_knowledge_versions (
+  domain          TEXT NOT NULL,
+  key             TEXT NOT NULL,
+  version         INTEGER NOT NULL,
+  data            JSONB NOT NULL DEFAULT '{}',
+  tags            TEXT[] NOT NULL DEFAULT '{}',
+  change_summary  TEXT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (domain, key, version),
+  FOREIGN KEY (domain, key) REFERENCES lt_knowledge (domain, key) ON DELETE CASCADE
+);
+
+ALTER TABLE lt_knowledge
+  ADD COLUMN IF NOT EXISTS current_version INTEGER NOT NULL DEFAULT 1;
+
+-- Backfill: every existing entry becomes version 1 of its lineage.
+INSERT INTO lt_knowledge_versions (domain, key, version, data, tags)
+SELECT domain, key, current_version, data, tags
+FROM lt_knowledge
+ON CONFLICT (domain, key, version) DO NOTHING;

package/build/routes/escalations/single.js

@@ -57,6 +57,16 @@ function registerSingleRoutes(router) {
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     // -- Parameterized routes (must come after literal paths) --
+    /**
+     * GET /api/escalations/:id/lookups
+     * Resolve the escalation's versioned knowledge lookups. The refs on the row
+     * are the grant: readers of the escalation may fetch exactly the pinned
+     * editions it names.
+     */
+    router.get('/:id/lookups', async (req, res) => {
+        const result = await api.getEscalationLookups({ id: req.params.id }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * GET /api/escalations/:id
      * Get a single escalation by ID.