@substrate-ai/factory 0.19.54

package/dist/twins/docker-compose.js

@@ -0,0 +1,172 @@
+/**
+ * TwinManager — Docker Compose orchestration for digital twin containers.
+ *
+ * Generates Docker Compose files, manages container lifecycles (start, stop,
+ * health check, cleanup), and emits twin lifecycle events.
+ *
+ * Story 47-2.
+ */
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// TwinError
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when Docker is unavailable or the compose lifecycle fails.
+ */
+export class TwinError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TwinError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Generates a Docker Compose v3.8 YAML string from an array of twin definitions.
+ * Built manually with template strings — no external YAML library required.
+ */
+function generateComposeYaml(twins) {
+    const lines = [];
+    lines.push("version: '3.8'");
+    lines.push('services:');
+    for (const twin of twins) {
+        lines.push(`  ${twin.name}:`);
+        lines.push(`    image: ${twin.image}`);
+        if (twin.ports.length > 0) {
+            lines.push('    ports:');
+            for (const port of twin.ports) {
+                lines.push(`      - "${port.host}:${port.container}"`);
+            }
+        }
+        if (twin.environment && Object.keys(twin.environment).length > 0) {
+            lines.push('    environment:');
+            for (const [key, value] of Object.entries(twin.environment)) {
+                lines.push(`      ${key}: ${value}`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Polls a twin's health endpoint until it returns a 2xx response or exhausts attempts.
+ *
+ * Algorithm (from story 47-2 dev notes):
+ *   attempts = 0
+ *   while attempts < maxAttempts:
+ *     try fetch → if ok, return
+ *     catch (connection refused) → continue
+ *     attempts++
+ *     sleep(intervalMs)
+ *   throw TwinError
+ */
+async function pollTwinHealth(twin, maxAttempts, healthIntervalMs) {
+    if (!twin.healthcheck?.url)
+        return;
+    const url = twin.healthcheck.url;
+    const intervalMs = twin.healthcheck.interval_ms ?? healthIntervalMs;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+        try {
+            const response = await fetch(url);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Connection refused — container not yet up; continue polling
+        }
+        attempts++;
+        if (attempts < maxAttempts) {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    throw new TwinError(`Twin '${twin.name}' failed health check after ${maxAttempts} attempts`);
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Creates a TwinManager that orchestrates Docker Compose for digital twin services.
+ *
+ * The event bus is injected — do NOT import a global singleton or create one internally.
+ *
+ * @param eventBus - Typed event bus for emitting twin lifecycle events
+ * @param options - Optional health check configuration
+ * @returns TwinManager with start() and stop() methods
+ */
+export function createTwinManager(eventBus, options) {
+    const maxHealthAttempts = options?.maxHealthAttempts ?? 30;
+    const healthIntervalMs = options?.healthIntervalMs ?? 1000;
+    /** Temp directory containing the generated docker-compose.yml. Null when not started. */
+    let composeDir = null;
+    /** Twins that were passed to start() — used by stop() to emit twin:stopped events. */
+    let startedTwins = [];
+    return {
+        async start(twins) {
+            // AC4: Check Docker availability before doing anything
+            try {
+                execSync('docker info', { stdio: 'ignore' });
+            }
+            catch {
+                throw new TwinError('Docker not found — twins require Docker');
+            }
+            // AC1, AC2: Generate and write docker-compose.yml to a temp directory
+            const yaml = generateComposeYaml(twins);
+            const dir = join(tmpdir(), randomUUID());
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'docker-compose.yml'), yaml, 'utf-8');
+            composeDir = dir;
+            startedTwins = twins;
+            // AC1: Execute docker compose up -d
+            try {
+                execSync('docker compose up -d', { cwd: dir, stdio: 'pipe' });
+            }
+            catch (err) {
+                const error = err;
+                const stderr = error.stderr?.toString() ?? '';
+                throw new TwinError(`docker compose up failed: ${stderr}`);
+            }
+            // AC3: Poll health endpoints before resolving
+            for (const twin of twins) {
+                await pollTwinHealth(twin, maxHealthAttempts, healthIntervalMs);
+            }
+            // AC5: Emit twin:started for each twin
+            for (const twin of twins) {
+                eventBus.emit('twin:started', {
+                    twinName: twin.name,
+                    ports: twin.ports,
+                    healthStatus: 'healthy',
+                });
+            }
+        },
+        async stop() {
+            // AC6: Guard — no-op if start() was never called
+            if (!composeDir)
+                return;
+            const dir = composeDir;
+            // AC6: Shut down containers
+            try {
+                execSync('docker compose down --remove-orphans', { cwd: dir, stdio: 'pipe' });
+            }
+            catch {
+                // Best-effort shutdown — still clean up the temp dir
+            }
+            // AC6: Delete the temp compose directory
+            rmSync(dir, { recursive: true, force: true });
+            // Emit twin:stopped for each twin that was started
+            for (const twin of startedTwins) {
+                eventBus.emit('twin:stopped', { twinName: twin.name });
+            }
+            composeDir = null;
+            startedTwins = [];
+        },
+        getComposeDir() {
+            return composeDir;
+        },
+    };
+}
+//# sourceMappingURL=docker-compose.js.map

package/dist/twins/docker-compose.js.map

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

package/dist/twins/health-monitor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TwinHealthMonitor — polls twin health endpoints at a configurable interval
+ * and emits events when twins become degraded or unhealthy.
+ *
+ * Story 47-6.
+ */
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+import type { TwinDefinition } from './types.js';
+/** Current health status of a monitored twin. */
+export type TwinHealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+/** Options for configuring the health monitor. */
+export interface TwinHealthMonitorOptions {
+    /** Milliseconds between health check polls. Default: 30000. */
+    monitorIntervalMs?: number;
+    /** Consecutive failures before emitting twin:health-failed. Default: 3. */
+    maxConsecutiveFailures?: number;
+}
+/** Interface for monitoring the health of digital twins during pipeline runs. */
+export interface TwinHealthMonitor {
+    /** Begin periodic health monitoring for the given twins. */
+    start(twins: TwinDefinition[]): void;
+    /** Stop all polling timers. Idempotent — safe to call multiple times. */
+    stop(): void;
+    /** Returns current health status for all monitored twins. */
+    getStatus(): Record<string, TwinHealthStatus>;
+}
+/**
+ * Create a TwinHealthMonitor that polls twin health endpoints and emits
+ * health events on the provided event bus.
+ *
+ * @param eventBus - Factory event bus for emitting health events.
+ * @param options  - Optional configuration for polling interval and failure threshold.
+ */
+export declare function createTwinHealthMonitor(eventBus: TypedEventBus<FactoryEvents>, options?: TwinHealthMonitorOptions): TwinHealthMonitor;
+//# sourceMappingURL=health-monitor.d.ts.map

package/dist/twins/health-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-monitor.d.ts","sourceRoot":"","sources":["../../src/twins/health-monitor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAMhD,iDAAiD;AACjD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAA;AAEnE,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAA;IACpC,yEAAyE;IACzE,IAAI,IAAI,IAAI,CAAA;IACZ,6DAA6D;IAC7D,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAC9C;AAeD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,EACtC,OAAO,CAAC,EAAE,wBAAwB,GACjC,iBAAiB,CA4GnB"}

package/dist/twins/health-monitor.js

@@ -0,0 +1,114 @@
+/**
+ * TwinHealthMonitor — polls twin health endpoints at a configurable interval
+ * and emits events when twins become degraded or unhealthy.
+ *
+ * Story 47-6.
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a TwinHealthMonitor that polls twin health endpoints and emits
+ * health events on the provided event bus.
+ *
+ * @param eventBus - Factory event bus for emitting health events.
+ * @param options  - Optional configuration for polling interval and failure threshold.
+ */
+export function createTwinHealthMonitor(eventBus, options) {
+    const monitorIntervalMs = options?.monitorIntervalMs ?? 30000;
+    const maxConsecutiveFailures = options?.maxConsecutiveFailures ?? 3;
+    const stateMap = new Map();
+    const intervals = new Map();
+    /**
+     * Fetch a twin's health URL with a timeout. Resolves with the Response on
+     * success, or rejects with an error on non-2xx, timeout, or connection failure.
+     */
+    async function fetchWithTimeout(url, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Health check timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            fetch(url)
+                .then((res) => {
+                clearTimeout(timer);
+                resolve(res);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Poll a single twin's health endpoint.
+     * Updates internal state and emits events as appropriate.
+     */
+    async function pollTwin(twin) {
+        if (!twin.healthcheck?.url)
+            return;
+        const timeoutMs = twin.healthcheck.timeout_ms ?? 5000;
+        try {
+            const response = await fetchWithTimeout(twin.healthcheck.url, timeoutMs);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            // Successful poll — reset failure state
+            stateMap.set(twin.name, { consecutiveFailures: 0, status: 'healthy' });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            const state = stateMap.get(twin.name);
+            const prevFailures = state?.consecutiveFailures ?? 0;
+            const count = prevFailures + 1;
+            if (count >= maxConsecutiveFailures) {
+                // Twin is now confirmed unhealthy
+                stateMap.set(twin.name, { consecutiveFailures: count, status: 'unhealthy' });
+                eventBus.emit('twin:health-failed', { twinName: twin.name, error });
+                // Stop polling this twin
+                const id = intervals.get(twin.name);
+                if (id !== undefined) {
+                    clearInterval(id);
+                    intervals.delete(twin.name);
+                }
+            }
+            else {
+                // Twin is degraded but not yet confirmed unhealthy
+                stateMap.set(twin.name, { consecutiveFailures: count, status: 'degraded' });
+                eventBus.emit('twin:health-warning', {
+                    twinName: twin.name,
+                    error,
+                    consecutiveFailures: count,
+                });
+            }
+        }
+    }
+    return {
+        start(twins) {
+            for (const twin of twins) {
+                if (!twin.healthcheck?.url)
+                    continue;
+                // Initialize state
+                stateMap.set(twin.name, { consecutiveFailures: 0, status: 'healthy' });
+                // Start polling interval.
+                // Note: returning the Promise from pollTwin allows vi.advanceTimersByTimeAsync
+                // to properly await the async callback in tests.
+                const id = setInterval(() => pollTwin(twin), monitorIntervalMs);
+                intervals.set(twin.name, id);
+            }
+        },
+        stop() {
+            for (const id of intervals.values()) {
+                clearInterval(id);
+            }
+            intervals.clear();
+        },
+        getStatus() {
+            const result = {};
+            for (const [name, state] of stateMap.entries()) {
+                result[name] = state.status;
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=health-monitor.js.map

package/dist/twins/health-monitor.js.map

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

package/dist/twins/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Twin Registry — public API barrel export.
+ *
+ * Story 47-1: registry, types, schema.
+ * Story 47-2: TwinManager, createTwinManager, TwinError (Docker Compose orchestration).
+ */
+export { createTwinRegistry, TwinRegistry } from './registry.js';
+export type { TwinDefinition, PortMapping, TwinHealthcheck, HealthPollResult, } from './types.js';
+export { TwinDefinitionError, TwinRegistryError } from './types.js';
+export { TwinDefinitionSchema } from './schema.js';
+export type { TwinDefinitionInput } from './schema.js';
+export { createTwinManager, TwinError } from './docker-compose.js';
+export type { TwinManager, TwinManagerOptions } from './docker-compose.js';
+export { TWIN_TEMPLATES, getTwinTemplate, listTwinTemplates } from './templates.js';
+export type { TwinTemplateEntry } from './templates.js';
+export { readRunState, writeRunState, clearRunState, runStatePath } from './run-state.js';
+export type { TwinRunState } from './run-state.js';
+export { createTwinHealthMonitor } from './health-monitor.js';
+export type { TwinHealthMonitor, TwinHealthStatus, TwinHealthMonitorOptions } from './health-monitor.js';
+export type { TwinRunInput, TwinRunRow, TwinRunSummary, TwinHealthFailureInput, } from './persistence.js';
+export { insertTwinRun, updateTwinRun, recordTwinHealthFailure, getTwinRunsForRun, TwinPersistenceCoordinator, createTwinPersistenceCoordinator, } from './persistence.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/twins/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAChE,YAAY,EACV,cAAc,EACd,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGtD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAClE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAG1E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACnF,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAGvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AACzF,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAGxG,YAAY,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,kBAAkB,CAAA"}

package/dist/twins/index.js

@@ -0,0 +1,19 @@
+/**
+ * Twin Registry — public API barrel export.
+ *
+ * Story 47-1: registry, types, schema.
+ * Story 47-2: TwinManager, createTwinManager, TwinError (Docker Compose orchestration).
+ */
+export { createTwinRegistry, TwinRegistry } from './registry.js';
+export { TwinDefinitionError, TwinRegistryError } from './types.js';
+export { TwinDefinitionSchema } from './schema.js';
+// Docker Compose orchestration (story 47-2)
+export { createTwinManager, TwinError } from './docker-compose.js';
+// Pre-built twin templates (story 47-4)
+export { TWIN_TEMPLATES, getTwinTemplate, listTwinTemplates } from './templates.js';
+// Run state management (story 47-5)
+export { readRunState, writeRunState, clearRunState, runStatePath } from './run-state.js';
+// Twin health monitoring (story 47-6)
+export { createTwinHealthMonitor } from './health-monitor.js';
+export { insertTwinRun, updateTwinRun, recordTwinHealthFailure, getTwinRunsForRun, TwinPersistenceCoordinator, createTwinPersistenceCoordinator, } from './persistence.js';
+//# sourceMappingURL=index.js.map

package/dist/twins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/twins/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAOhE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAGlD,4CAA4C;AAC5C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGlE,wCAAwC;AACxC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAGnF,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGzF,sCAAsC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAU7D,OAAO,EACL,aAAa,EACb,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,kBAAkB,CAAA"}

package/dist/twins/persistence.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Twin persistence — database query functions and coordinator for twin lifecycle events.
+ *
+ * Provides:
+ *   - Schema types: TwinRunInput, TwinRunRow, TwinRunSummary, TwinHealthFailureInput
+ *   - Query functions: insertTwinRun, updateTwinRun, recordTwinHealthFailure, getTwinRunsForRun
+ *   - TwinPersistenceCoordinator: subscribes to factory event bus and persists twin lifecycle events
+ *
+ * Stories 47-7.
+ */
+import type { DatabaseAdapter, TypedEventBus } from '@substrate-ai/core';
+import type { PortMapping } from './types.js';
+import type { FactoryEvents } from '../events.js';
+/**
+ * Input for inserting a new twin run record.
+ */
+export interface TwinRunInput {
+    /** Optional custom id — defaults to a new UUID if not provided */
+    id?: string;
+    /** Optional parent factory run id */
+    run_id?: string;
+    /** Name of the twin */
+    twin_name: string;
+    /** Port mappings for this twin */
+    ports: PortMapping[];
+    /** ISO timestamp for started_at — defaults to current timestamp if not provided */
+    started_at?: string;
+}
+/**
+ * Row shape mirroring twin_runs table columns.
+ */
+export interface TwinRunRow {
+    id: string;
+    run_id: string | null;
+    twin_name: string;
+    started_at: string;
+    stopped_at: string | null;
+    status: string;
+    ports_json: string | null;
+}
+/**
+ * Input for inserting a twin health failure record.
+ */
+export interface TwinHealthFailureInput {
+    twin_name: string;
+    run_id?: string;
+    error_message: string;
+    /** ISO timestamp — defaults to current timestamp if not provided */
+    checked_at?: string;
+}
+/**
+ * Enriched view of a twin_runs row with parsed ports and health failure count.
+ */
+export interface TwinRunSummary extends TwinRunRow {
+    /** Parsed PortMapping[] from ports_json (empty array if ports_json is null) */
+    ports: PortMapping[];
+    /** Count of health failures for this twin within the same run_id */
+    health_failure_count: number;
+}
+/**
+ * Insert a new row into twin_runs with status='running'.
+ *
+ * @returns The id of the inserted row.
+ */
+export declare function insertTwinRun(adapter: DatabaseAdapter, input: TwinRunInput): Promise<string>;
+/**
+ * Update an existing twin_runs row with stop information.
+ */
+export declare function updateTwinRun(adapter: DatabaseAdapter, id: string, patch: {
+    status: string;
+    stopped_at: string;
+}): Promise<void>;
+/**
+ * Insert a row into twin_health_failures for a failed health check.
+ */
+export declare function recordTwinHealthFailure(adapter: DatabaseAdapter, input: TwinHealthFailureInput): Promise<void>;
+/**
+ * Retrieve all twin run summaries for a given run_id, with health failure counts.
+ *
+ * Uses two portable queries and merges results client-side.
+ *
+ * @returns Array of TwinRunSummary — empty array if no twins found for this run.
+ */
+export declare function getTwinRunsForRun(adapter: DatabaseAdapter, runId: string): Promise<TwinRunSummary[]>;
+/**
+ * Subscribes to factory event bus twin lifecycle events and persists them to the database.
+ *
+ * On twin:started — calls insertTwinRun and stores the row id by twin name.
+ * On twin:stopped — calls updateTwinRun with status='stopped' and current timestamp.
+ */
+export declare class TwinPersistenceCoordinator {
+    private readonly _adapter;
+    private readonly _rowIds;
+    constructor(_adapter: DatabaseAdapter, eventBus: TypedEventBus<FactoryEvents>);
+}
+/**
+ * Create a TwinPersistenceCoordinator that wires twin lifecycle events to database persistence.
+ */
+export declare function createTwinPersistenceCoordinator(adapter: DatabaseAdapter, eventBus: TypedEventBus<FactoryEvents>): TwinPersistenceCoordinator;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/twins/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/twins/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAMjD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,+EAA+E;IAC/E,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAMD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAMD;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAKf;AAMD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAOf;AAMD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,EAAE,CAAC,CAmB3B;AAMD;;;;;GAKG;AACH,qBAAa,0BAA0B;IAInC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAH3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAGjC,QAAQ,EAAE,eAAe,EAC1C,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC;CAgCzC;AAMD;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,GACrC,0BAA0B,CAE5B"}

package/dist/twins/persistence.js

@@ -0,0 +1,120 @@
+/**
+ * Twin persistence — database query functions and coordinator for twin lifecycle events.
+ *
+ * Provides:
+ *   - Schema types: TwinRunInput, TwinRunRow, TwinRunSummary, TwinHealthFailureInput
+ *   - Query functions: insertTwinRun, updateTwinRun, recordTwinHealthFailure, getTwinRunsForRun
+ *   - TwinPersistenceCoordinator: subscribes to factory event bus and persists twin lifecycle events
+ *
+ * Stories 47-7.
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// insertTwinRun
+// ---------------------------------------------------------------------------
+/**
+ * Insert a new row into twin_runs with status='running'.
+ *
+ * @returns The id of the inserted row.
+ */
+export async function insertTwinRun(adapter, input) {
+    const id = input.id ?? randomUUID();
+    const startedAt = input.started_at ?? new Date().toISOString();
+    const portsJson = JSON.stringify(input.ports);
+    await adapter.query('INSERT INTO twin_runs (id, run_id, twin_name, started_at, status, ports_json) VALUES (?, ?, ?, ?, ?, ?)', [id, input.run_id ?? null, input.twin_name, startedAt, 'running', portsJson]);
+    return id;
+}
+// ---------------------------------------------------------------------------
+// updateTwinRun
+// ---------------------------------------------------------------------------
+/**
+ * Update an existing twin_runs row with stop information.
+ */
+export async function updateTwinRun(adapter, id, patch) {
+    await adapter.query('UPDATE twin_runs SET status = ?, stopped_at = ? WHERE id = ?', [patch.status, patch.stopped_at, id]);
+}
+// ---------------------------------------------------------------------------
+// recordTwinHealthFailure
+// ---------------------------------------------------------------------------
+/**
+ * Insert a row into twin_health_failures for a failed health check.
+ */
+export async function recordTwinHealthFailure(adapter, input) {
+    const checkedAt = input.checked_at ?? new Date().toISOString();
+    await adapter.query('INSERT INTO twin_health_failures (twin_name, run_id, checked_at, error_message) VALUES (?, ?, ?, ?)', [input.twin_name, input.run_id ?? null, checkedAt, input.error_message]);
+}
+// ---------------------------------------------------------------------------
+// getTwinRunsForRun
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve all twin run summaries for a given run_id, with health failure counts.
+ *
+ * Uses two portable queries and merges results client-side.
+ *
+ * @returns Array of TwinRunSummary — empty array if no twins found for this run.
+ */
+export async function getTwinRunsForRun(adapter, runId) {
+    // Query 1: fetch twin run rows for this run
+    const rows = await adapter.query('SELECT * FROM twin_runs WHERE run_id = ?', [runId]);
+    // Query 2: fetch health failure counts per twin for this run
+    const failureCounts = await adapter.query('SELECT twin_name, COUNT(*) as cnt FROM twin_health_failures WHERE run_id = ? GROUP BY twin_name', [runId]);
+    const failureMap = new Map(failureCounts.map((r) => [r.twin_name, r.cnt]));
+    return rows.map((row) => ({
+        ...row,
+        ports: row.ports_json ? JSON.parse(row.ports_json) : [],
+        health_failure_count: failureMap.get(row.twin_name) ?? 0,
+    }));
+}
+// ---------------------------------------------------------------------------
+// TwinPersistenceCoordinator
+// ---------------------------------------------------------------------------
+/**
+ * Subscribes to factory event bus twin lifecycle events and persists them to the database.
+ *
+ * On twin:started — calls insertTwinRun and stores the row id by twin name.
+ * On twin:stopped — calls updateTwinRun with status='stopped' and current timestamp.
+ */
+export class TwinPersistenceCoordinator {
+    _adapter;
+    _rowIds = new Map();
+    constructor(_adapter, eventBus) {
+        this._adapter = _adapter;
+        eventBus.on('twin:started', (e) => {
+            void insertTwinRun(this._adapter, {
+                ...(e.runId !== undefined ? { run_id: e.runId } : {}),
+                twin_name: e.twinName,
+                ports: e.ports,
+            }).then((id) => {
+                this._rowIds.set(e.twinName, id);
+            });
+        });
+        eventBus.on('twin:stopped', (e) => {
+            const id = this._rowIds.get(e.twinName);
+            if (id !== undefined) {
+                void updateTwinRun(this._adapter, id, {
+                    status: 'stopped',
+                    stopped_at: new Date().toISOString(),
+                });
+                this._rowIds.delete(e.twinName);
+            }
+        });
+        // Story 47-7 AC2: persist health check failures
+        eventBus.on('twin:health-failed', (e) => {
+            void recordTwinHealthFailure(this._adapter, {
+                twin_name: e.twinName,
+                ...(e.runId !== undefined ? { run_id: e.runId } : {}),
+                error_message: e.error,
+            });
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a TwinPersistenceCoordinator that wires twin lifecycle events to database persistence.
+ */
+export function createTwinPersistenceCoordinator(adapter, eventBus) {
+    return new TwinPersistenceCoordinator(adapter, eventBus);
+}
+//# sourceMappingURL=persistence.js.map

package/dist/twins/persistence.js.map

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