limen-ai 1.0.0

package/dist/substrate/heartbeat/heartbeat_monitor.js

@@ -0,0 +1,170 @@
+/**
+ * Heartbeat Monitor implementation.
+ * S ref: §25.5 (Heartbeat Protocol), FM-20 (Infinite Loops / Hung Workers)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: 30s default heartbeat interval with escalation ladder:
+ *   1 miss = warn, 2 misses = notify orchestrator, 3 misses = kill worker + retry.
+ *
+ * Heartbeat state is colocated in core_task_queue (FPD-5/DL-2) to avoid JOINs
+ * on the hot path per I-14.
+ *
+ * Invariants enforced: I-12 (execution timeout as defense-in-depth), I-14 (latency)
+ * Failure modes defended: FM-20 (hung workers via escalation ladder)
+ *
+ * SYNC interface. All methods return Result<T>.
+ */
+// ─── Error Constructors ───
+function err(code, message, spec) {
+    return { ok: false, error: { code, message, spec } };
+}
+function ok(value) {
+    return { ok: true, value };
+}
+// ─── Heartbeat Monitor Factory ───
+/**
+ * Create a HeartbeatMonitor implementation.
+ * S ref: §25.5, C-07 (Object.freeze)
+ *
+ * Heartbeat data is stored in core_task_queue columns:
+ *   last_heartbeat_at, missed_heartbeats, heartbeat_interval_ms
+ *
+ * The checkCycle() method is designed to be called every polling interval
+ * by the scheduler. It scans all RUNNING tasks and checks for missed heartbeats.
+ */
+export function createHeartbeatMonitor(audit, time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    /** §25.5: Receive heartbeat from a running task */
+    function receiveHeartbeat(conn, taskId, workerId) {
+        const now = clock.nowISO();
+        // I-03: mutation + audit in same transaction
+        const result = conn.transaction(() => {
+            const r = conn.run(`UPDATE core_task_queue
+         SET last_heartbeat_at = ?, missed_heartbeats = 0
+         WHERE task_id = ? AND worker_id = ? AND status = 'RUNNING'`, [now, taskId, workerId]);
+            if (r.changes > 0) {
+                audit?.append(conn, {
+                    tenantId: null,
+                    actorType: 'system',
+                    actorId: 'substrate.heartbeat',
+                    operation: 'heartbeat.receive',
+                    resourceType: 'task',
+                    resourceId: taskId,
+                    detail: { workerId },
+                });
+            }
+            return r;
+        });
+        if (result.changes === 0) {
+            return err('HEARTBEAT_TASK_NOT_FOUND', `No running task ${taskId} on worker ${workerId}`, '§25.5');
+        }
+        return ok(undefined);
+    }
+    /**
+     * §25.5: Check all running tasks for missed heartbeats.
+     * Escalation ladder: 1 miss = warn, 2 = notify, 3 = kill.
+     *
+     * A heartbeat is "missed" if:
+     *   now - last_heartbeat_at > heartbeat_interval_ms
+     * OR if last_heartbeat_at is NULL and:
+     *   now - started_at > heartbeat_interval_ms
+     */
+    function checkCycle(conn, _ctx) {
+        const now = clock.nowMs();
+        const warned = [];
+        const notified = [];
+        const killed = [];
+        // I-03, CQ-08: All heartbeat updates and audit entries are atomic
+        conn.transaction(() => {
+            // Get all RUNNING tasks
+            const tasks = conn.query(`SELECT task_id, worker_id, heartbeat_interval_ms, last_heartbeat_at, started_at, missed_heartbeats
+         FROM core_task_queue
+         WHERE status = 'RUNNING'`);
+            for (const task of tasks) {
+                const lastBeat = task.last_heartbeat_at
+                    ? new Date(task.last_heartbeat_at).getTime()
+                    : (task.started_at ? new Date(task.started_at).getTime() : now);
+                const elapsed = now - lastBeat;
+                const intervalMs = task.heartbeat_interval_ms;
+                if (elapsed <= intervalMs) {
+                    // Heartbeat is on time -- nothing to do
+                    continue;
+                }
+                // Calculate how many heartbeats have been missed
+                const newMissed = task.missed_heartbeats + 1;
+                // Update missed count
+                conn.run(`UPDATE core_task_queue
+           SET missed_heartbeats = ?
+           WHERE task_id = ?`, [newMissed, task.task_id]);
+                // I-03: audit heartbeat check mutation
+                audit?.append(conn, {
+                    tenantId: null,
+                    actorType: 'scheduler',
+                    actorId: 'substrate.heartbeat',
+                    operation: 'heartbeat.check',
+                    resourceType: 'task',
+                    resourceId: task.task_id,
+                    detail: { missedCount: newMissed, workerId: task.worker_id, action: newMissed >= 3 ? 'kill' : newMissed === 2 ? 'notify' : 'warn' },
+                });
+                const taskId = task.task_id;
+                if (newMissed >= 3) {
+                    // §25.5: 3 misses = kill worker + mark for retry
+                    killed.push(taskId);
+                }
+                else if (newMissed === 2) {
+                    // §25.5: 2 misses = notify orchestrator
+                    notified.push(taskId);
+                }
+                else {
+                    // §25.5: 1 miss = warn
+                    warned.push(taskId);
+                }
+            }
+        });
+        return ok({ warned, notified, killed });
+    }
+    /** §25.5: Reset heartbeat counter for a task */
+    function resetHeartbeat(conn, taskId) {
+        const now = clock.nowISO();
+        // I-03: mutation + audit in same transaction
+        conn.transaction(() => {
+            conn.run(`UPDATE core_task_queue
+         SET missed_heartbeats = 0, last_heartbeat_at = ?
+         WHERE task_id = ?`, [now, taskId]);
+            audit?.append(conn, {
+                tenantId: null,
+                actorType: 'system',
+                actorId: 'substrate.heartbeat',
+                operation: 'heartbeat.reset',
+                resourceType: 'task',
+                resourceId: taskId,
+                detail: { resetAt: now },
+            });
+        });
+        return ok(undefined);
+    }
+    /** §25.5: Get heartbeat status for a task */
+    function getStatus(conn, taskId) {
+        const row = conn.get(`SELECT task_id, worker_id, missed_heartbeats, last_heartbeat_at, heartbeat_interval_ms
+       FROM core_task_queue
+       WHERE task_id = ?`, [taskId]);
+        if (!row || !row.worker_id) {
+            return ok(null);
+        }
+        return ok({
+            taskId: row.task_id,
+            workerId: row.worker_id,
+            missedHeartbeats: row.missed_heartbeats,
+            lastHeartbeatAt: row.last_heartbeat_at,
+            heartbeatIntervalMs: row.heartbeat_interval_ms,
+        });
+    }
+    const monitor = {
+        receiveHeartbeat,
+        checkCycle,
+        resetHeartbeat,
+        getStatus,
+    };
+    return Object.freeze(monitor);
+}
+//# sourceMappingURL=heartbeat_monitor.js.map

package/dist/substrate/heartbeat/heartbeat_monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat_monitor.js","sourceRoot":"","sources":["../../../src/substrate/heartbeat/heartbeat_monitor.ts"],"names":[],"mappings":"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"}

package/dist/substrate/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Substrate facade -- composes all six subsystems into a frozen object.
+ * S ref: §2 (Three-layer model), §25 (Execution Substrate), C-07 (Object.freeze)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: createSubstrate() factory that assembles:
+ *   - TaskScheduler (§25.1)
+ *   - WorkerRuntime (§25.2)
+ *   - CapabilityAdapterRegistry (§25.3)
+ *   - LlmGateway (§25.4)
+ *   - HeartbeatMonitor (§25.5)
+ *   - ResourceAccounting (§25.6)
+ *
+ * Layer 1.5: Deterministic infrastructure hosting stochastic work.
+ * The substrate executes what the orchestrator approves and reports results.
+ */
+export type { PriorityPolicy, TaskQueueStatus, ExecutionMode, EnqueueRequest, QueuedTask, QueueStats, TaskScheduler, WorkerResourceLimits, WorkerPoolConfig, WorkerStatus, WorkerInfo, WorkerPoolStatus, WorkerTaskResult, WorkerRuntime, CapabilityType, CapabilityRequest, CapabilityResult, SandboxConfig, AdapterRegistration, CapabilityAdapterRegistry, LlmRole, LlmContentBlock, LlmMessage, LlmToolDefinition, LlmRequest, LlmToolCall, LlmResponse, LlmStreamChunk, ProviderHealthStatus, ProviderHealthSnapshot, FailoverBudgetCheck, FailoverPolicy, LlmProviderConfig, LlmGateway, HeartbeatCheckResult, HeartbeatStatus, HeartbeatMonitor, AccountingRecord, BudgetCheckResult, MissionConsumption, TenantConsumption, ResourceAccounting, SubstrateHealth, SubstrateConfig, Substrate, } from './interfaces/substrate.js';
+import type { DatabaseConnection } from '../kernel/interfaces/index.js';
+import type { Result, AuditCreateInput } from '../kernel/interfaces/index.js';
+import type { Substrate, SubstrateConfig } from './interfaces/substrate.js';
+/**
+ * Minimal audit dependency for substrate subsystems.
+ * Uses only the append method to keep coupling lightweight.
+ * S ref: I-03 (every state mutation and its audit entry in same transaction)
+ */
+interface SubstrateAuditDep {
+    append(conn: DatabaseConnection, input: AuditCreateInput): Result<unknown>;
+}
+/**
+ * CF-010: Encryption dependency for LLM gateway request/response body encryption.
+ * When provided, the LLM gateway encrypts request/response bodies before storage.
+ */
+interface SubstrateEncryptionDep {
+    encrypt(plaintext: string): string;
+    decrypt(ciphertext: string): string;
+}
+/**
+ * Create a Substrate instance composing all six subsystems.
+ * S ref: §2, §25, C-07 (Object.freeze on public API), I-03 (audit in same transaction)
+ *
+ * Returns a frozen Substrate object. The caller must call start() to
+ * initialize workers and register providers.
+ *
+ * @param config Substrate configuration
+ * @param audit Optional audit dependency for I-03 compliance. When provided,
+ *   every state mutation in the substrate appends an audit entry in the same
+ *   transaction as the mutation.
+ * @param encryption Optional encryption for LLM gateway request/response body encryption (CF-010)
+ */
+export declare function createSubstrate(config: SubstrateConfig, audit?: SubstrateAuditDep, encryption?: SubstrateEncryptionDep): Result<Readonly<Substrate>>;
+/** Re-export migrations for the database lifecycle */
+export { getPhase2Migrations } from './migration/002_substrate.js';
+export { getTransportDeliberationMigration } from './migration/022_transport_deliberation.js';
+/** Re-export transport layer */
+export { createTransportEngine, createAnthropicAdapter, createAnthropicAdapterFromEnv, parseSSEStream, parseNDJSONStream, } from './transport/index.js';
+export type { TransportErrorCode, SSEEvent, TransportHttpRequest, TransportHttpResponse, DeliberationMetrics, TransportResult, TransportStreamResult, ProviderAdapter, TransportExecuteOptions, TransportEngine, UpdateProviderHealthFn, IsCircuitOpenFn, TransportEngineOptions, } from './transport/index.js';
+/** Re-export accounting deliberation helper */
+export { recordAccountingDeliberation } from './accounting/resource_accounting.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/substrate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/substrate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,YAAY,EAEV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,UAAU,EACV,UAAU,EACV,aAAa,EAGb,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EAGb,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EAGzB,OAAO,EACP,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,UAAU,EAGV,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAGhB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAGlB,eAAe,EACf,eAAe,EACf,SAAS,GACV,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EACV,MAAM,EAEN,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAEhB,MAAM,2BAA2B,CAAC;AAgBnC;;;;GAIG;AACH,UAAU,iBAAiB;IACzB,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED;;;GAGG;AACH,UAAU,sBAAsB;IAC9B,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,iBAAiB,EAAE,UAAU,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAsGpJ;AAED,sDAAsD;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,iCAAiC,EAAE,MAAM,2CAA2C,CAAC;AAE9F,gCAAgC;AAChC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,6BAA6B,EAC7B,cAAc,EACd,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,kBAAkB,EAClB,QAAQ,EACR,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,+CAA+C;AAC/C,OAAO,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/substrate/index.js

@@ -0,0 +1,143 @@
+/**
+ * Substrate facade -- composes all six subsystems into a frozen object.
+ * S ref: §2 (Three-layer model), §25 (Execution Substrate), C-07 (Object.freeze)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: createSubstrate() factory that assembles:
+ *   - TaskScheduler (§25.1)
+ *   - WorkerRuntime (§25.2)
+ *   - CapabilityAdapterRegistry (§25.3)
+ *   - LlmGateway (§25.4)
+ *   - HeartbeatMonitor (§25.5)
+ *   - ResourceAccounting (§25.6)
+ *
+ * Layer 1.5: Deterministic infrastructure hosting stochastic work.
+ * The substrate executes what the orchestrator approves and reports results.
+ */
+import { createTaskScheduler } from './scheduler/task_scheduler.js';
+import { createWorkerRuntime } from './workers/worker_runtime.js';
+import { createCapabilityAdapterRegistry } from './adapters/capability_registry.js';
+import { createLlmGateway } from './gateway/llm_gateway.js';
+import { createHeartbeatMonitor } from './heartbeat/heartbeat_monitor.js';
+import { createResourceAccounting } from './accounting/resource_accounting.js';
+// ─── Error Constructors ───
+function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Create a Substrate instance composing all six subsystems.
+ * S ref: §2, §25, C-07 (Object.freeze on public API), I-03 (audit in same transaction)
+ *
+ * Returns a frozen Substrate object. The caller must call start() to
+ * initialize workers and register providers.
+ *
+ * @param config Substrate configuration
+ * @param audit Optional audit dependency for I-03 compliance. When provided,
+ *   every state mutation in the substrate appends an audit entry in the same
+ *   transaction as the mutation.
+ * @param encryption Optional encryption for LLM gateway request/response body encryption (CF-010)
+ */
+export function createSubstrate(config, audit, encryption) {
+    const scheduler = createTaskScheduler(audit);
+    const workers = createWorkerRuntime(audit);
+    const adapters = createCapabilityAdapterRegistry();
+    const gateway = createLlmGateway(audit, encryption);
+    const heartbeat = createHeartbeatMonitor(audit);
+    const accounting = createResourceAccounting(audit);
+    /** §25: Start the substrate (initialize workers, register providers) */
+    function start(conn, ctx) {
+        // Initialize the worker pool
+        const initResult = workers.initialize(conn, config.workerPool);
+        if (!initResult.ok)
+            return initResult;
+        // Register all configured providers
+        for (const providerConfig of config.providers) {
+            const regResult = gateway.registerProvider(conn, ctx, providerConfig);
+            if (!regResult.ok)
+                return regResult;
+        }
+        return ok(undefined);
+    }
+    /** §32.4: Get substrate health */
+    function health(conn) {
+        // Worker status
+        const poolResult = workers.poolStatus(conn);
+        if (!poolResult.ok)
+            return poolResult;
+        const pool = poolResult.value;
+        // Queue stats
+        const queueResult = scheduler.getStats(conn);
+        if (!queueResult.ok)
+            return queueResult;
+        const queue = queueResult.value;
+        // Provider health
+        const providerResult = gateway.getProviderHealth(conn);
+        if (!providerResult.ok)
+            return providerResult;
+        const providers = providerResult.value;
+        const healthyCount = providers.filter((p) => p.status === 'healthy').length;
+        const degradedCount = providers.filter((p) => p.status === 'degraded').length;
+        const cooldownCount = providers.filter((p) => p.status === 'cooldown').length;
+        const unavailableCount = providers.filter((p) => p.status === 'unavailable').length;
+        // Determine overall status
+        const workerExhaustion = pool.idle === 0 && pool.total > 0;
+        const allProvidersBusy = providers.length > 0 && healthyCount === 0 && degradedCount === 0;
+        let status;
+        if (allProvidersBusy || pool.total === 0) {
+            status = 'unhealthy';
+        }
+        else if (workerExhaustion || degradedCount > 0 || cooldownCount > 0) {
+            status = 'degraded';
+        }
+        else {
+            status = 'healthy';
+        }
+        return ok({
+            status,
+            workers: {
+                total: pool.total,
+                idle: pool.idle,
+                allocated: pool.allocated,
+                running: pool.running,
+            },
+            queue: {
+                pending: queue.pending,
+                running: queue.running,
+                total: queue.total,
+            },
+            providers: {
+                total: providers.length,
+                healthy: healthyCount,
+                degraded: degradedCount,
+                cooldown: cooldownCount,
+                unavailable: unavailableCount,
+            },
+            workerExhaustionWarning: workerExhaustion,
+            allProvidersBusy,
+        });
+    }
+    /** §25: Graceful shutdown */
+    function shutdown(conn, ctx, timeoutMs) {
+        return workers.shutdown(conn, ctx, timeoutMs);
+    }
+    const substrate = {
+        scheduler,
+        workers,
+        adapters,
+        gateway,
+        heartbeat,
+        accounting,
+        start,
+        health,
+        shutdown,
+    };
+    return ok(Object.freeze(substrate));
+}
+/** Re-export migrations for the database lifecycle */
+export { getPhase2Migrations } from './migration/002_substrate.js';
+export { getTransportDeliberationMigration } from './migration/022_transport_deliberation.js';
+/** Re-export transport layer */
+export { createTransportEngine, createAnthropicAdapter, createAnthropicAdapterFromEnv, parseSSEStream, parseNDJSONStream, } from './transport/index.js';
+/** Re-export accounting deliberation helper */
+export { recordAccountingDeliberation } from './accounting/resource_accounting.js';
+//# sourceMappingURL=index.js.map

package/dist/substrate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/substrate/index.ts"],"names":[],"mappings":"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"}