@n-dx/core 0.1.0

package/packages/web/dist/server/aggregation-cache.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Aggregation result cache with filesystem-based invalidation.
+ *
+ * Caches computed aggregation results (summary, events, by-command, etc.)
+ * and automatically invalidates when the underlying data sources change.
+ *
+ * ## Change Detection
+ *
+ * Three data sources feed the token usage aggregation:
+ * - Hench run files (`.hench/runs/*.json`) — tracked via directory mtime + file count
+ * - Rex execution log (`.rex/execution-log.jsonl`) — tracked via mtime + size
+ * - Sourcevision manifest (`.sourcevision/manifest.json`) — tracked via mtime + size
+ *
+ * On each cache access, the current filesystem state is compared against the
+ * last-known fingerprint. If any source has changed, all cached results are
+ * invalidated and the fingerprint is updated.
+ *
+ * ## Memory Bounding
+ *
+ * Cache entries are bounded by a configurable `maxEntries` limit. When full,
+ * the oldest entry (by insertion order) is evicted. This prevents unbounded
+ * growth from diverse query parameter combinations.
+ *
+ * @module web/server/aggregation-cache
+ */
+/**
+ * Filesystem metadata snapshot for the three token usage data sources.
+ * Used to detect when source data has changed and cached results need
+ * to be invalidated.
+ */
+export interface SourceFingerprint {
+    /** Hench runs directory modification time (changes on add/delete). */
+    henchDirMtimeMs: number;
+    /** Number of JSON files in the hench runs directory. */
+    henchFileCount: number;
+    /** Rex execution log modification time. */
+    rexLogMtimeMs: number;
+    /** Rex execution log size in bytes. */
+    rexLogSize: number;
+    /** Sourcevision manifest modification time. */
+    svManifestMtimeMs: number;
+    /** Sourcevision manifest size in bytes. */
+    svManifestSize: number;
+}
+/**
+ * Take a fingerprint of the current filesystem state of all aggregation
+ * data sources. Missing files/directories produce zero values rather than
+ * errors — this allows the cache to work even when some sources haven't
+ * been initialized yet.
+ */
+export declare function takeFingerprint(projectDir: string, rexDir: string): Promise<SourceFingerprint>;
+/** Compare two fingerprints for equality. */
+export declare function fingerprintsMatch(a: SourceFingerprint, b: SourceFingerprint): boolean;
+/**
+ * Caches aggregation results with automatic filesystem-based invalidation.
+ *
+ * Usage:
+ * ```ts
+ * const cache = new AggregationResultCache(projectDir, rexDir);
+ *
+ * const events = await cache.getOrCompute(
+ *   "events:::",
+ *   () => collectAllEvents(ctx),
+ * );
+ * ```
+ *
+ * Cache keys should encode all parameters that affect the result
+ * (e.g. `"summary:2026-01-01:2026-02-01"` for a date-scoped summary).
+ */
+export declare class AggregationResultCache {
+    private readonly projectDir;
+    private readonly rexDir;
+    private readonly maxEntries;
+    /** Last-known filesystem fingerprint. */
+    private fingerprint;
+    /** Cached results keyed by scope string. */
+    private entries;
+    constructor(projectDir: string, rexDir: string, options?: {
+        maxEntries?: number;
+    });
+    /**
+     * Get a cached result or compute and cache it.
+     *
+     * Before returning a cached value, checks whether any source data has
+     * changed since the last fingerprint. If so, all entries are invalidated
+     * and the value is recomputed.
+     *
+     * @param key - Cache key encoding the query scope (e.g. `"summary:since:until"`)
+     * @param compute - Synchronous function that produces the result
+     */
+    getOrCompute<T>(key: string, compute: () => T): Promise<T>;
+    /** Number of cached entries (for monitoring/testing). */
+    get size(): number;
+    /** Current fingerprint (for testing/debugging). */
+    get currentFingerprint(): SourceFingerprint | null;
+    /** Force invalidation of all cached results and fingerprint. */
+    invalidate(): void;
+    /**
+     * Check source freshness. If stale or uninitialized, clear all entries
+     * and update the fingerprint.
+     */
+    private ensureFresh;
+    /** Store a value, evicting the oldest entry if at capacity. */
+    private put;
+}

package/packages/web/dist/server/aggregation-cache.js

@@ -0,0 +1,163 @@
+/**
+ * Aggregation result cache with filesystem-based invalidation.
+ *
+ * Caches computed aggregation results (summary, events, by-command, etc.)
+ * and automatically invalidates when the underlying data sources change.
+ *
+ * ## Change Detection
+ *
+ * Three data sources feed the token usage aggregation:
+ * - Hench run files (`.hench/runs/*.json`) — tracked via directory mtime + file count
+ * - Rex execution log (`.rex/execution-log.jsonl`) — tracked via mtime + size
+ * - Sourcevision manifest (`.sourcevision/manifest.json`) — tracked via mtime + size
+ *
+ * On each cache access, the current filesystem state is compared against the
+ * last-known fingerprint. If any source has changed, all cached results are
+ * invalidated and the fingerprint is updated.
+ *
+ * ## Memory Bounding
+ *
+ * Cache entries are bounded by a configurable `maxEntries` limit. When full,
+ * the oldest entry (by insertion order) is evicted. This prevents unbounded
+ * growth from diverse query parameter combinations.
+ *
+ * @module web/server/aggregation-cache
+ */
+import { join } from "node:path";
+import { stat, readdir } from "node:fs/promises";
+// ---------------------------------------------------------------------------
+// Fingerprinting
+// ---------------------------------------------------------------------------
+/**
+ * Take a fingerprint of the current filesystem state of all aggregation
+ * data sources. Missing files/directories produce zero values rather than
+ * errors — this allows the cache to work even when some sources haven't
+ * been initialized yet.
+ */
+export async function takeFingerprint(projectDir, rexDir) {
+    const henchRunsDir = join(projectDir, ".hench", "runs");
+    const rexLogPath = join(rexDir, "execution-log.jsonl");
+    const svManifestPath = join(projectDir, ".sourcevision", "manifest.json");
+    // Run all stat operations in parallel for performance
+    const [henchDirResult, henchFilesResult, rexLogResult, svManifestResult] = await Promise.all([
+        stat(henchRunsDir).catch(() => null),
+        readdir(henchRunsDir)
+            .then((files) => files.filter((f) => f.endsWith(".json") && !f.startsWith(".")))
+            .catch(() => []),
+        stat(rexLogPath).catch(() => null),
+        stat(svManifestPath).catch(() => null),
+    ]);
+    return {
+        henchDirMtimeMs: henchDirResult?.mtimeMs ?? 0,
+        henchFileCount: henchFilesResult.length,
+        rexLogMtimeMs: rexLogResult?.mtimeMs ?? 0,
+        rexLogSize: rexLogResult?.size ?? 0,
+        svManifestMtimeMs: svManifestResult?.mtimeMs ?? 0,
+        svManifestSize: svManifestResult?.size ?? 0,
+    };
+}
+/** Compare two fingerprints for equality. */
+export function fingerprintsMatch(a, b) {
+    return (a.henchDirMtimeMs === b.henchDirMtimeMs &&
+        a.henchFileCount === b.henchFileCount &&
+        a.rexLogMtimeMs === b.rexLogMtimeMs &&
+        a.rexLogSize === b.rexLogSize &&
+        a.svManifestMtimeMs === b.svManifestMtimeMs &&
+        a.svManifestSize === b.svManifestSize);
+}
+// ---------------------------------------------------------------------------
+// AggregationResultCache
+// ---------------------------------------------------------------------------
+/**
+ * Caches aggregation results with automatic filesystem-based invalidation.
+ *
+ * Usage:
+ * ```ts
+ * const cache = new AggregationResultCache(projectDir, rexDir);
+ *
+ * const events = await cache.getOrCompute(
+ *   "events:::",
+ *   () => collectAllEvents(ctx),
+ * );
+ * ```
+ *
+ * Cache keys should encode all parameters that affect the result
+ * (e.g. `"summary:2026-01-01:2026-02-01"` for a date-scoped summary).
+ */
+export class AggregationResultCache {
+    projectDir;
+    rexDir;
+    maxEntries;
+    /** Last-known filesystem fingerprint. */
+    fingerprint = null;
+    /** Cached results keyed by scope string. */
+    entries = new Map();
+    constructor(projectDir, rexDir, options) {
+        this.projectDir = projectDir;
+        this.rexDir = rexDir;
+        this.maxEntries = options?.maxEntries ?? 64;
+    }
+    /**
+     * Get a cached result or compute and cache it.
+     *
+     * Before returning a cached value, checks whether any source data has
+     * changed since the last fingerprint. If so, all entries are invalidated
+     * and the value is recomputed.
+     *
+     * @param key - Cache key encoding the query scope (e.g. `"summary:since:until"`)
+     * @param compute - Synchronous function that produces the result
+     */
+    async getOrCompute(key, compute) {
+        await this.ensureFresh();
+        if (this.entries.has(key)) {
+            return this.entries.get(key);
+        }
+        const result = compute();
+        this.put(key, result);
+        return result;
+    }
+    /** Number of cached entries (for monitoring/testing). */
+    get size() {
+        return this.entries.size;
+    }
+    /** Current fingerprint (for testing/debugging). */
+    get currentFingerprint() {
+        return this.fingerprint;
+    }
+    /** Force invalidation of all cached results and fingerprint. */
+    invalidate() {
+        this.fingerprint = null;
+        this.entries.clear();
+    }
+    // ---- Internal -------------------------------------------------------------
+    /**
+     * Check source freshness. If stale or uninitialized, clear all entries
+     * and update the fingerprint.
+     */
+    async ensureFresh() {
+        const current = await takeFingerprint(this.projectDir, this.rexDir);
+        if (this.fingerprint && fingerprintsMatch(this.fingerprint, current)) {
+            return; // Sources unchanged — cache is still valid
+        }
+        // Sources changed (or first access) — invalidate everything
+        this.entries.clear();
+        this.fingerprint = current;
+    }
+    /** Store a value, evicting the oldest entry if at capacity. */
+    put(key, value) {
+        // If key already exists, just update it (no eviction needed)
+        if (this.entries.has(key)) {
+            this.entries.set(key, value);
+            return;
+        }
+        // Evict oldest entries until under capacity
+        while (this.entries.size >= this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        this.entries.set(key, value);
+    }
+}
+//# sourceMappingURL=aggregation-cache.js.map

package/packages/web/dist/server/aggregation-cache.js.map

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

package/packages/web/dist/server/concurrent-execution-metrics.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Concurrent execution metrics collection and resource utilization tracking.
+ *
+ * Collects time-series snapshots of concurrent process counts, total memory
+ * utilization across all hench processes, and per-task resource metrics.
+ * Snapshots are stored in bounded ring buffers and aggregated into patterns
+ * (peak, average) for dashboard consumption.
+ *
+ * This is the web-server counterpart to hench's own ConcurrentExecutionMetrics.
+ * Implemented separately to avoid adding a runtime dependency from
+ * @n-dx/web to hench (web reads hench data from disk, never imports it).
+ *
+ * @module @n-dx/web/server/concurrent-execution-metrics
+ */
+export interface ConcurrentExecutionMetricsConfig {
+    maxSnapshots: number;
+    maxCompletedTasks: number;
+}
+export declare const DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG: ConcurrentExecutionMetricsConfig;
+/** A single point-in-time snapshot of concurrent execution state. */
+export interface ExecutionMetricsSnapshot {
+    concurrentCount: number;
+    totalRssBytes: number;
+    systemMemoryPercent: number;
+    loadAvg1m: number;
+    timestamp: string;
+    epochMs: number;
+}
+/** Resource utilization metrics for a single task execution. */
+export interface TaskResourceMetrics {
+    taskId: string;
+    taskTitle: string;
+    pid: number;
+    startedAt: string;
+    completedAt?: string;
+    durationMs: number;
+    peakRssBytes: number;
+    avgRssBytes: number;
+    currentRssBytes: number;
+    sampleCount: number;
+    avgConcurrentDuringExecution: number;
+}
+/** Aggregated utilization patterns from time-series data. */
+export interface UtilizationPatterns {
+    peakConcurrent: number;
+    avgConcurrent: number;
+    peakTotalRssBytes: number;
+    avgTotalRssBytes: number;
+    avgSystemMemoryPercent: number;
+    peakSystemMemoryPercent: number;
+    avgLoadAvg1m: number;
+    peakLoadAvg1m: number;
+    windowDurationMs: number;
+    snapshotCount: number;
+}
+/** Full metrics summary for API response. */
+export interface ExecutionMetricsSummary {
+    current: ExecutionMetricsSnapshot;
+    patterns: UtilizationPatterns;
+    activeTasks: TaskResourceMetrics[];
+    completedTasks: TaskResourceMetrics[];
+    timestamp: string;
+}
+/**
+ * Collects and aggregates concurrent execution metrics across hench processes.
+ *
+ * Records periodic snapshots of concurrent process counts and memory utilization,
+ * tracks per-task resource usage, and computes utilization patterns.
+ */
+export declare class ConcurrentExecutionMetrics {
+    private readonly _config;
+    private readonly _snapshots;
+    private readonly _activeTasks;
+    private readonly _completedTasks;
+    private readonly _now;
+    constructor(config?: Partial<ConcurrentExecutionMetricsConfig>, overrides?: {
+        now?: () => number;
+    });
+    get config(): Readonly<ConcurrentExecutionMetricsConfig>;
+    get snapshotCount(): number;
+    get activeTaskCount(): number;
+    get completedTaskCount(): number;
+    taskStarted(taskId: string, taskTitle: string, pid: number): void;
+    taskCompleted(taskId: string): void;
+    recordSnapshot(input: {
+        concurrentCount: number;
+        totalRssBytes: number;
+        systemMemoryPercent: number;
+        loadAvg1m: number;
+        perTaskRss: Array<{
+            taskId: string;
+            rssBytes: number;
+        }>;
+    }): void;
+    getLatestSnapshot(): ExecutionMetricsSnapshot;
+    getSnapshots(): ExecutionMetricsSnapshot[];
+    computePatterns(): UtilizationPatterns;
+    getActiveTaskMetrics(): TaskResourceMetrics[];
+    getCompletedTaskMetrics(): TaskResourceMetrics[];
+    getSummary(): ExecutionMetricsSummary;
+    reset(): void;
+    private _buildTaskMetrics;
+}

package/packages/web/dist/server/concurrent-execution-metrics.js

@@ -0,0 +1,253 @@
+/**
+ * Concurrent execution metrics collection and resource utilization tracking.
+ *
+ * Collects time-series snapshots of concurrent process counts, total memory
+ * utilization across all hench processes, and per-task resource metrics.
+ * Snapshots are stored in bounded ring buffers and aggregated into patterns
+ * (peak, average) for dashboard consumption.
+ *
+ * This is the web-server counterpart to hench's own ConcurrentExecutionMetrics.
+ * Implemented separately to avoid adding a runtime dependency from
+ * @n-dx/web to hench (web reads hench data from disk, never imports it).
+ *
+ * @module @n-dx/web/server/concurrent-execution-metrics
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum time-series snapshots retained (ring buffer size). */
+const DEFAULT_MAX_SNAPSHOTS = 360;
+/** Maximum completed task metrics retained for post-mortem analysis. */
+const DEFAULT_MAX_COMPLETED_TASKS = 50;
+export const DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG = {
+    maxSnapshots: DEFAULT_MAX_SNAPSHOTS,
+    maxCompletedTasks: DEFAULT_MAX_COMPLETED_TASKS,
+};
+// ---------------------------------------------------------------------------
+// ConcurrentExecutionMetrics
+// ---------------------------------------------------------------------------
+/**
+ * Collects and aggregates concurrent execution metrics across hench processes.
+ *
+ * Records periodic snapshots of concurrent process counts and memory utilization,
+ * tracks per-task resource usage, and computes utilization patterns.
+ */
+export class ConcurrentExecutionMetrics {
+    _config;
+    _snapshots = [];
+    _activeTasks = new Map();
+    _completedTasks = [];
+    _now;
+    constructor(config, overrides) {
+        this._config = { ...DEFAULT_CONCURRENT_EXECUTION_METRICS_CONFIG, ...config };
+        this._now = overrides?.now ?? Date.now;
+    }
+    get config() {
+        return { ...this._config };
+    }
+    get snapshotCount() {
+        return this._snapshots.length;
+    }
+    get activeTaskCount() {
+        return this._activeTasks.size;
+    }
+    get completedTaskCount() {
+        return this._completedTasks.length;
+    }
+    // -----------------------------------------------------------------------
+    // Task lifecycle
+    // -----------------------------------------------------------------------
+    taskStarted(taskId, taskTitle, pid) {
+        const now = this._now();
+        this._activeTasks.set(taskId, {
+            taskId,
+            taskTitle,
+            pid,
+            startedAt: new Date(now).toISOString(),
+            startedEpochMs: now,
+            rssSumBytes: 0,
+            rssSampleCount: 0,
+            peakRssBytes: 0,
+            currentRssBytes: 0,
+            concurrentSum: 0,
+            concurrentSampleCount: 0,
+            active: true,
+        });
+    }
+    taskCompleted(taskId) {
+        const tracked = this._activeTasks.get(taskId);
+        if (!tracked)
+            return;
+        const now = this._now();
+        tracked.active = false;
+        tracked.completedAt = new Date(now).toISOString();
+        tracked.completedEpochMs = now;
+        this._activeTasks.delete(taskId);
+        this._completedTasks.push(tracked);
+        while (this._completedTasks.length > this._config.maxCompletedTasks) {
+            this._completedTasks.shift();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Snapshot recording
+    // -----------------------------------------------------------------------
+    recordSnapshot(input) {
+        const now = this._now();
+        const snapshot = {
+            concurrentCount: input.concurrentCount,
+            totalRssBytes: input.totalRssBytes,
+            systemMemoryPercent: input.systemMemoryPercent,
+            loadAvg1m: input.loadAvg1m,
+            timestamp: new Date(now).toISOString(),
+            epochMs: now,
+        };
+        if (this._snapshots.length >= this._config.maxSnapshots) {
+            this._snapshots.shift();
+        }
+        this._snapshots.push(snapshot);
+        for (const { taskId, rssBytes } of input.perTaskRss) {
+            const tracked = this._activeTasks.get(taskId);
+            if (!tracked)
+                continue;
+            tracked.rssSumBytes += rssBytes;
+            tracked.rssSampleCount += 1;
+            tracked.currentRssBytes = rssBytes;
+            if (rssBytes > tracked.peakRssBytes) {
+                tracked.peakRssBytes = rssBytes;
+            }
+            tracked.concurrentSum += input.concurrentCount;
+            tracked.concurrentSampleCount += 1;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Queries
+    // -----------------------------------------------------------------------
+    getLatestSnapshot() {
+        const last = this._snapshots[this._snapshots.length - 1];
+        if (last)
+            return { ...last };
+        const now = this._now();
+        return {
+            concurrentCount: 0,
+            totalRssBytes: 0,
+            systemMemoryPercent: 0,
+            loadAvg1m: 0,
+            timestamp: new Date(now).toISOString(),
+            epochMs: now,
+        };
+    }
+    getSnapshots() {
+        return this._snapshots.map((s) => ({ ...s }));
+    }
+    computePatterns() {
+        const n = this._snapshots.length;
+        if (n === 0) {
+            return {
+                peakConcurrent: 0,
+                avgConcurrent: 0,
+                peakTotalRssBytes: 0,
+                avgTotalRssBytes: 0,
+                avgSystemMemoryPercent: 0,
+                peakSystemMemoryPercent: 0,
+                avgLoadAvg1m: 0,
+                peakLoadAvg1m: 0,
+                windowDurationMs: 0,
+                snapshotCount: 0,
+            };
+        }
+        let sumConcurrent = 0;
+        let peakConcurrent = 0;
+        let sumRss = 0;
+        let peakRss = 0;
+        let sumMemPercent = 0;
+        let peakMemPercent = 0;
+        let sumLoad = 0;
+        let peakLoad = 0;
+        for (const s of this._snapshots) {
+            sumConcurrent += s.concurrentCount;
+            if (s.concurrentCount > peakConcurrent)
+                peakConcurrent = s.concurrentCount;
+            sumRss += s.totalRssBytes;
+            if (s.totalRssBytes > peakRss)
+                peakRss = s.totalRssBytes;
+            sumMemPercent += s.systemMemoryPercent;
+            if (s.systemMemoryPercent > peakMemPercent)
+                peakMemPercent = s.systemMemoryPercent;
+            sumLoad += s.loadAvg1m;
+            if (s.loadAvg1m > peakLoad)
+                peakLoad = s.loadAvg1m;
+        }
+        const first = this._snapshots[0];
+        const last = this._snapshots[n - 1];
+        const windowDurationMs = last.epochMs - first.epochMs;
+        return {
+            peakConcurrent,
+            avgConcurrent: Math.round((sumConcurrent / n) * 100) / 100,
+            peakTotalRssBytes: peakRss,
+            avgTotalRssBytes: Math.round(sumRss / n),
+            avgSystemMemoryPercent: Math.round((sumMemPercent / n) * 100) / 100,
+            peakSystemMemoryPercent: peakMemPercent,
+            avgLoadAvg1m: Math.round((sumLoad / n) * 100) / 100,
+            peakLoadAvg1m: Math.round(peakLoad * 100) / 100,
+            windowDurationMs,
+            snapshotCount: n,
+        };
+    }
+    getActiveTaskMetrics() {
+        const now = this._now();
+        const result = [];
+        for (const t of this._activeTasks.values()) {
+            result.push(this._buildTaskMetrics(t, now));
+        }
+        return result;
+    }
+    getCompletedTaskMetrics() {
+        const now = this._now();
+        return this._completedTasks.map((t) => this._buildTaskMetrics(t, now));
+    }
+    getSummary() {
+        const now = this._now();
+        return {
+            current: this.getLatestSnapshot(),
+            patterns: this.computePatterns(),
+            activeTasks: this.getActiveTaskMetrics(),
+            completedTasks: this.getCompletedTaskMetrics(),
+            timestamp: new Date(now).toISOString(),
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Reset
+    // -----------------------------------------------------------------------
+    reset() {
+        this._snapshots.length = 0;
+        this._activeTasks.clear();
+        this._completedTasks.length = 0;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    _buildTaskMetrics(tracked, now) {
+        const endTime = tracked.completedEpochMs ?? now;
+        const durationMs = endTime - tracked.startedEpochMs;
+        const avgRss = tracked.rssSampleCount > 0
+            ? Math.round(tracked.rssSumBytes / tracked.rssSampleCount)
+            : 0;
+        const avgConcurrent = tracked.concurrentSampleCount > 0
+            ? Math.round((tracked.concurrentSum / tracked.concurrentSampleCount) * 100) / 100
+            : 0;
+        return {
+            taskId: tracked.taskId,
+            taskTitle: tracked.taskTitle,
+            pid: tracked.pid,
+            startedAt: tracked.startedAt,
+            completedAt: tracked.completedAt,
+            durationMs,
+            peakRssBytes: tracked.peakRssBytes,
+            avgRssBytes: avgRss,
+            currentRssBytes: tracked.currentRssBytes,
+            sampleCount: tracked.rssSampleCount,
+            avgConcurrentDuringExecution: avgConcurrent,
+        };
+    }
+}
+//# sourceMappingURL=concurrent-execution-metrics.js.map

package/packages/web/dist/server/concurrent-execution-metrics.js.map

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

package/packages/web/dist/server/domain-gateway.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Centralized gateway for sourcevision runtime imports.
+ *
+ * Web route handlers need the sourcevision MCP server factory to serve
+ * the `/mcp/sourcevision` endpoint. Rather than importing from "sourcevision"
+ * directly in route files, all web→sourcevision runtime imports pass through
+ * this single module.
+ *
+ * By concentrating all web→sourcevision runtime imports here, we ensure:
+ * - The cross-package surface is **explicit** (1 re-export, not scattered imports).
+ * - The DAG stays **acyclic** — sourcevision never imports from web.
+ * - Future changes to sourcevision's public API need only be updated here.
+ *
+ * @module web/server/domain-gateway
+ * @see packages/web/src/server/rex-gateway.ts — web's gateway for rex imports
+ * @see packages/hench/src/prd/rex-gateway.ts — hench's equivalent gateway
+ */
+export { createSourcevisionMcpServer } from "sourcevision";