@c9up/eon 0.1.0 → 0.2.0

package/src/schema/EonMigrationRunner.ts

@@ -4,7 +4,7 @@
  * sorted-file discovery, a `ream_`-prefixed tracking table, batch-based
  * rollback, `init/status/migrate/rollback/reset/refresh/fresh/dryRun`.
  *
- * ── TWO named TDengine deviations from atlas (AC6) ──────────────────────────
+ * ── THREE named TDengine deviations from atlas (AC6) ────────────────────────
  *
  *  1. **No transactions / no engine rollback.** TDengine DDL is non-transactional
  *     — a batch CANNOT be applied atomically. The runner executes statements
@@ -19,17 +19,37 @@
  *     unique timestamp key (TDengine only allows a `DELETE` predicate on the
  *     primary timestamp column).
  *
+ *  3. **The migration lock is a table's EXISTENCE, not a row's value.** atlas
+ *     (Lucid/Knex parity) serialises concurrent runners with a conditional
+ *     `UPDATE … WHERE is_locked = 0`; TDengine has no conditional UPDATE, so
+ *     that exact shape is impossible. The equivalent guarantee comes from a
+ *     different primitive: `CREATE TABLE` **without** `IF NOT EXISTS` is an
+ *     atomic compare-and-swap — the mnode serialises metadata, so exactly ONE
+ *     concurrent creator succeeds and every other gets code 1539. Creating the
+ *     lock table IS taking the lock; dropping it is releasing it. Verified
+ *     against a live TDengine 3.3.5.0: 12 racing connections, 1 winner, 11 ×
+ *     1539, three rounds. The API stays atlas's (`disableLocks`, `forceUnlock`,
+ *     `E_..._LOCKED`) — only the primitive underneath differs.
+ *
  * Agnostic leaf: takes the connection structurally and a plain directory path —
  * no `@c9up/ream` import, no app helper (`project_package_extraction`).
  */
 
+import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { EonConnection } from "../connection/EonConnection.js";
+import {
+	type EonConnection,
+	EonConnectionError,
+} from "../connection/EonConnection.js";
 import { compileStatementNative } from "../query/native.js";
 import type { Migration } from "./Migration.js";
 
+/** TDengine's "Table already exists" code — the losing side of the lock race. */
+const TABLE_ALREADY_EXISTS = 1539;
+/** TDengine's "Table does not exist" code — nothing to force-unlock. */
+const TABLE_DOES_NOT_EXIST = 9731;
 const DEFAULT_DIR = "database/eon-migrations";
 const DEFAULT_TABLE = "ream_eon_migrations";
 const TABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -45,13 +65,26 @@ export interface EonMigrationOptions {
 	 * table (`feedback_underscore_policy`) — keep it so cleanup helpers skip it.
 	 */
 	tableName?: string;
+	/**
+	 * Skip the migration lock (atlas / Lucid `disableLocks` parity). Only for a
+	 * context where concurrent runs are impossible by construction — a single
+	 * test process, or a one-off local run.
+	 */
+	disableLocks?: boolean;
 }
 
 export type MigrationState = "applied" | "pending";
 
 export interface MigrationStatus {
 	name: string;
-	state: MigrationState;
+	/**
+	 * Whether the migration has run.
+	 *
+	 * Spelled `status`, not `state`: it is what Lucid's `MigrationListNode`
+	 * calls it and what atlas already called it, and ream's migration registry
+	 * needs one shape across every store.
+	 */
+	status: MigrationState;
 	batch?: number;
 }
 
@@ -66,6 +99,10 @@ export class EonMigrationRunner {
 	readonly #conn: EonConnection;
 	readonly #dir: string;
 	readonly #table: string;
+	readonly #lockTable: string;
+	readonly #disableLocks: boolean;
+	/** Set while THIS runner holds the lock, so we never drop someone else's. */
+	#lockToken: string | undefined;
 
 	constructor(conn: EonConnection, options: EonMigrationOptions = {}) {
 		this.#conn = conn;
@@ -77,6 +114,10 @@ export class EonMigrationRunner {
 			);
 		}
 		this.#table = table;
+		// Derived from the tracking table, so a custom `tableName` keeps its lock
+		// beside it; already validated by the pattern above, plus a literal suffix.
+		this.#lockTable = `${table}_lock`;
+		this.#disableLocks = options.disableLocks ?? false;
 	}
 
 	/** Create the tracking table (`IF NOT EXISTS`) via the basic-table DDL path. */
@@ -124,13 +165,17 @@ export class EonMigrationRunner {
 		return files.map((name) => {
 			const batch = byName.get(name);
 			return batch === undefined
-				? { name, state: "pending" }
-				: { name, state: "applied", batch };
+				? { name, status: "pending" }
+				: { name, status: "applied", batch };
 		});
 	}
 
 	/** Run every pending migration (filename order), recording each. */
 	async migrate(): Promise<string[]> {
+		return this.#withLock(() => this.#migrateLocked());
+	}
+
+	async #migrateLocked(): Promise<string[]> {
 		await this.init();
 		const applied = await this.#appliedRecords();
 		const appliedNames = new Set(applied.map((r) => r.name));
@@ -158,6 +203,10 @@ export class EonMigrationRunner {
 
 	/** Roll back the most-recent batch (files in reverse order), running `down()`. */
 	async rollback(): Promise<string[]> {
+		return this.#withLock(() => this.#rollbackLocked());
+	}
+
+	async #rollbackLocked(): Promise<string[]> {
 		await this.init();
 		const applied = await this.#appliedRecords();
 		if (applied.length === 0) return [];
@@ -186,11 +235,17 @@ export class EonMigrationRunner {
 
 	/** Roll back every applied batch (Lucid `migrate:reset`). */
 	async reset(): Promise<string[]> {
+		return this.#withLock(() => this.#resetLocked());
+	}
+
+	async #resetLocked(): Promise<string[]> {
 		await this.init();
 		const all: string[] = [];
+		// Loops on the LOCKED variant: `rollback()` would try to take a lock this
+		// runner already holds, and the CREATE would fail with 1539 against itself.
 		// Guard against a stuck loop: each rollback must shrink the applied set.
 		for (;;) {
-			const rolled = await this.rollback();
+			const rolled = await this.#rollbackLocked();
 			if (rolled.length === 0) break;
 			all.push(...rolled);
 		}
@@ -199,9 +254,13 @@ export class EonMigrationRunner {
 
 	/** Reset then re-run every migration (Lucid `migrate:refresh`). */
 	async refresh(): Promise<{ rolled: string[]; executed: string[] }> {
-		const rolled = await this.reset();
-		const executed = await this.migrate();
-		return { rolled, executed };
+		// ONE lock held across the WHOLE rollback + re-migrate, so no other run can
+		// slip into the free window between reset and migrate (atlas does the same).
+		return this.#withLock(async () => {
+			const rolled = await this.#resetLocked();
+			const executed = await this.#migrateLocked();
+			return { rolled, executed };
+		});
 	}
 
 	/** Alias of {@link refresh} (Lucid `migrate:fresh`). */
@@ -249,6 +308,143 @@ export class EonMigrationRunner {
 		}));
 	}
 
+	// ── Migration lock ─────────────────────────────────────────────────────────
+	// Deviation 3 (see the file header): the lock is the lock table's EXISTENCE.
+	// `CREATE TABLE` without `IF NOT EXISTS` is TDengine's atomic compare-and-swap.
+
+	/**
+	 * Take the migration lock so two processes cannot migrate concurrently
+	 * (atlas / Lucid parity — a lock TABLE; here its existence, not a row value).
+	 *
+	 * ATOMIC: the mnode serialises table creation, so of N concurrent creators
+	 * exactly ONE succeeds and the rest get code 1539. Winning the CREATE IS
+	 * holding the lock — there is no separate read-back to race against.
+	 *
+	 * Any OTHER failure propagates untouched: we must never read an unknown error
+	 * as "someone else holds it" (or as "we hold it"). Either way we do not migrate.
+	 */
+	async #acquireLock(): Promise<void> {
+		if (this.#disableLocks) return;
+		const { statements } = compileStatementNative(
+			{
+				kind: "createTable",
+				name: this.#lockTable,
+				ifNotExists: false,
+				columns: [
+					{
+						name: "locked_at",
+						kind: "timestamp",
+						length: null,
+						precision: null,
+						scale: null,
+					},
+					{
+						name: "token",
+						kind: "varchar",
+						length: 64,
+						precision: null,
+						scale: null,
+					},
+				],
+			},
+			"tdengine",
+		);
+		const token = randomUUID();
+		try {
+			for (const sql of statements) await this.#conn.exec(sql);
+		} catch (error) {
+			if (
+				error instanceof EonConnectionError &&
+				error.code === TABLE_ALREADY_EXISTS
+			) {
+				throw new Error(
+					`[E_EON_MIGRATION_LOCKED] could not acquire the migration lock — another migration is already running. Wait for it to finish, or clear a stuck lock with forceUnlock() (drops '${this.#lockTable}').`,
+					{ cause: error },
+				);
+			}
+			throw error;
+		}
+		this.#lockToken = token;
+		// Written for diagnosis only (who holds it, since when) — the lock is
+		// already ours the moment the CREATE returned, so a failure to record it
+		// must not look like a failure to acquire.
+		await this.#writeLockRecord(token);
+	}
+
+	/** Best-effort ownership stamp inside the lock table. Never fails acquisition. */
+	async #writeLockRecord(token: string): Promise<void> {
+		try {
+			const { statements } = compileStatementNative(
+				{
+					kind: "insert",
+					table: this.#lockTable,
+					columns: ["locked_at", "token"],
+					rows: [[Date.now(), token]],
+					literal: true,
+				},
+				"tdengine",
+			);
+			for (const sql of statements) await this.#conn.exec(sql);
+		} catch {
+			// Diagnostic only — swallowed on purpose.
+		}
+	}
+
+	/** Run `fn` holding the migration lock; always release, even on throw. */
+	async #withLock<T>(fn: () => Promise<T>): Promise<T> {
+		await this.#acquireLock();
+		try {
+			return await fn();
+		} finally {
+			await this.#releaseLock();
+		}
+	}
+
+	/** Release the lock — only if WE took it, so we never drop someone else's. */
+	async #releaseLock(): Promise<void> {
+		if (this.#disableLocks || this.#lockToken === undefined) return;
+		this.#lockToken = undefined;
+		await this.#dropLockTable();
+	}
+
+	async #dropLockTable(): Promise<void> {
+		const { statements } = compileStatementNative(
+			{ kind: "dropTable", name: this.#lockTable, ifExists: true },
+			"tdengine",
+		);
+		for (const sql of statements) await this.#conn.exec(sql);
+	}
+
+	/**
+	 * Force-clear a stuck migration lock (atlas `forceUnlock`, Lucid
+	 * `migration:unlock`). A process killed mid-migrate leaves the lock table
+	 * behind with no owner alive to drop it, and every later run would fail to
+	 * acquire. Returns `true` if a held lock was cleared.
+	 */
+	async forceUnlock(): Promise<boolean> {
+		// Symmetric to acquisition: a `DROP` that omits `IF EXISTS` reports whether
+		// anything was there, in one atomic statement. No separate existence probe,
+		// which would both race and (on a missing table) read an unrelated failure
+		// as "no lock held".
+		const { statements } = compileStatementNative(
+			{ kind: "dropTable", name: this.#lockTable, ifExists: false },
+			"tdengine",
+		);
+		try {
+			for (const sql of statements) await this.#conn.exec(sql);
+		} catch (error) {
+			if (
+				error instanceof EonConnectionError &&
+				error.code === TABLE_DOES_NOT_EXIST
+			) {
+				return false;
+			}
+			throw error;
+		}
+		this.#lockToken = undefined;
+		return true;
+	}
+
 	#maxBatch(records: readonly MigrationRecord[]): number {
 		return records.reduce((max, r) => Math.max(max, r.batch), 0);
 	}

package/src/schema/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@c9up/eon/schema` — everything a migration file needs, and nothing else.
+ *
+ * The root barrel re-exports `connectWsEon`, so importing `Migration` from
+ * `@c9up/eon` loads `@tdengine/websocket` as a side effect: a migration that
+ * only describes a schema pays for the driver. Nothing under this path touches
+ * the driver — `EonMigrationRunner` takes its connection structurally.
+ *
+ * Mirrors `@c9up/atlas/schema`.
+ */
+export {
+	type CreateStableSpec,
+	type CreateTableSpec,
+	TYPE_KIND_MAP,
+} from "./CreateStableSpec.js";
+export {
+	type EonMigrationOptions,
+	EonMigrationRunner,
+	type MigrationState,
+	type MigrationStatus,
+} from "./EonMigrationRunner.js";
+export {
+	AlterStableBuilder,
+	BasicTableBuilder,
+	EonSchema,
+	StableBuilder,
+} from "./EonSchema.js";
+export { Migration } from "./Migration.js";

package/src/testing/FakeEonConnection.ts

@@ -18,15 +18,22 @@
  *  - `ping()`/`close()` are no-ops.
  */
 
-import type {
-	EonColumnarIngest,
-	EonConnection,
-	EonSchemalessOptions,
+import {
+	type EonColumnarIngest,
+	type EonConnection,
+	EonConnectionError,
+	type EonSchemalessOptions,
 } from "../connection/EonConnection.js";
 
 type Row = Record<string, unknown>;
 
 const WINDOWED = /\b(INTERVAL|FILL|PARTITION\s+BY|SLIDING)\b/i;
+/** TDengine's "Table already exists" error code. */
+const TABLE_ALREADY_EXISTS = 1539;
+const IF_NOT_EXISTS = /\bIF\s+NOT\s+EXISTS\b/i;
+/** TDengine's "Table does not exist" error code. */
+const TABLE_DOES_NOT_EXIST = 9731;
+const IF_EXISTS = /\bIF\s+EXISTS\b/i;
 
 export class FakeEonConnection implements EonConnection {
 	readonly transport: "fake" = "fake";
@@ -39,8 +46,19 @@ export class FakeEonConnection implements EonConnection {
 		const trimmed = sql.trim();
 		if (/^CREATE\s+(STABLE|TABLE)\b/i.test(trimmed)) {
 			const table = extractCreateTarget(trimmed);
-			if (table !== undefined && !this.#store.has(table)) {
-				this.#store.set(table, []);
+			if (table !== undefined) {
+				// A real server REJECTS a duplicate CREATE that omits IF NOT EXISTS,
+				// with code 1539 — the atomic "one winner" primitive the migration
+				// lock is built on (measured against a live 3.3.5.0 server: 12 racing
+				// connections, 1 winner, 11 × 1539). The fake has to reject it too,
+				// or a lock test would pass here and deadlock against a real server.
+				if (this.#store.has(table) && !IF_NOT_EXISTS.test(trimmed)) {
+					throw new EonConnectionError(
+						`eon: exec failed for [${trimmed}]: Table already exists`,
+						{ code: TABLE_ALREADY_EXISTS },
+					);
+				}
+				if (!this.#store.has(table)) this.#store.set(table, []);
 			}
 			return { rowsAffected: 0 };
 		}
@@ -60,7 +78,19 @@ export class FakeEonConnection implements EonConnection {
 		// DROP / USE / other DDL: recorded, no store change.
 		if (/^DROP\s+(STABLE|TABLE)\b/i.test(trimmed)) {
 			const table = extractDropTarget(trimmed);
-			if (table !== undefined) this.#store.delete(table);
+			if (table !== undefined) {
+				// Mirror of the CREATE rule above: a real server rejects a DROP that
+				// omits IF EXISTS when the table is absent (code 9731, measured on
+				// 3.3.5.0). `forceUnlock` reads exactly that code to report whether a
+				// lock was actually held.
+				if (!this.#store.has(table) && !IF_EXISTS.test(trimmed)) {
+					throw new EonConnectionError(
+						`eon: exec failed for [${trimmed}]: Table does not exist`,
+						{ code: TABLE_DOES_NOT_EXIST },
+					);
+				}
+				this.#store.delete(table);
+			}
 		}
 		return { rowsAffected: 0 };
 	}

package/src/testing/FakeEonConsumer.ts

@@ -0,0 +1,93 @@
+/**
+ * An in-memory {@link EonConsumer}, so a subscription handler can be tested
+ * without a server.
+ *
+ * The fake models the two things that actually bite: `poll` drains a queue
+ * rather than replaying it, and `commit` only acknowledges what was polled. A
+ * fake that returns the same batch forever hides the bug where a handler never
+ * advances.
+ */
+import type {
+	EonConsumer,
+	EonMessage,
+	EonTopicPartition,
+} from "../tmq/EonConsumer.js";
+import { EonConsumerError } from "../tmq/EonConsumer.js";
+
+export class FakeEonConsumer implements EonConsumer {
+	#topics: string[] = [];
+	#queue: EonMessage[] = [];
+	#polled = 0;
+	#committed = 0;
+	#closed = false;
+
+	/** Queue messages a later `poll()` will return, in order. */
+	push(...messages: EonMessage[]): this {
+		this.#queue.push(...messages);
+		return this;
+	}
+
+	/** How many messages have been acknowledged. */
+	get committedCount(): number {
+		return this.#committed;
+	}
+
+	/** Whether `close()` has run. */
+	get isClosed(): boolean {
+		return this.#closed;
+	}
+
+	#ensureOpen(): void {
+		if (this.#closed) throw new EonConsumerError("eon: consumer is closed");
+	}
+
+	async subscribe(topics: string[]): Promise<void> {
+		this.#ensureOpen();
+		if (topics.length === 0) {
+			throw new EonConsumerError("eon: subscribe() needs at least one topic");
+		}
+		this.#topics = [...topics];
+	}
+
+	async subscription(): Promise<string[]> {
+		this.#ensureOpen();
+		return [...this.#topics];
+	}
+
+	async poll<T = Record<string, unknown>>(
+		_timeoutMs: number,
+	): Promise<EonMessage<T>[]> {
+		this.#ensureOpen();
+		// Drain, don't replay: a real poll never hands back the same rows twice.
+		const batch = this.#queue.splice(0, this.#queue.length);
+		this.#polled += batch.length;
+		return batch as EonMessage<T>[];
+	}
+
+	async commit(): Promise<EonTopicPartition[]> {
+		this.#ensureOpen();
+		this.#committed = this.#polled;
+		return this.#topics.map((topic) => ({ topic, vgroupId: 0 }));
+	}
+
+	async assignment(topics?: string[]): Promise<EonTopicPartition[]> {
+		this.#ensureOpen();
+		return (topics ?? this.#topics).map((topic) => ({ topic, vgroupId: 0 }));
+	}
+
+	async seek(partition: EonTopicPartition): Promise<void> {
+		this.#ensureOpen();
+		if (partition.offset === undefined) {
+			throw new EonConsumerError("eon: seek() needs an offset");
+		}
+	}
+
+	async unsubscribe(): Promise<void> {
+		this.#ensureOpen();
+		this.#topics = [];
+	}
+
+	async close(): Promise<void> {
+		this.#closed = true;
+	}
+}

package/src/testing/cleanup.ts

@@ -0,0 +1,120 @@
+/**
+ * Test-database lifecycle for eon integration suites.
+ *
+ * Every integration file used to spell its own
+ * `await conn.exec("DROP DATABASE IF EXISTS " + TEST_DB)` in `afterAll` —
+ * seven copies of one rule, which is how a cleanup quietly stops matching its
+ * setup. Atlas ships `truncateAll` / `useTransaction` for the same reason;
+ * TDengine has no transactions, so the unit here is the database.
+ */
+import type { EonConnection } from "../connection/EonConnection.js";
+
+/** TDengine identifiers: a letter or underscore, then letters, digits, underscores. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Guard an identifier before it is interpolated into DDL.
+ *
+ * `exec` takes literal SQL — TDengine binds no `?` in DDL — so a database name
+ * reaching these helpers is concatenated. A test name is not attacker-supplied,
+ * but a typo'd one silently becomes a different statement, and `DROP DATABASE`
+ * is the statement you least want to be surprising.
+ */
+function assertIdentifier(name: string, what: string): void {
+	if (!IDENTIFIER.test(name)) {
+		throw new Error(
+			`[E_EON_TEST_IDENTIFIER] invalid ${what} '${name}'; must match ${IDENTIFIER}`,
+		);
+	}
+}
+
+/**
+ * Drop a subscription topic if it exists. Safe to call when it never existed.
+ *
+ * Order matters: TDengine REFUSES to drop a database that still carries a
+ * topic ("Topic must be dropped first"), so a suite that creates one must drop
+ * it before {@link dropTestDatabase} or {@link createTestDatabase} — including
+ * on the setup path, where a topic left by a crashed previous run is exactly
+ * what breaks the next one.
+ */
+export async function dropTestTopic(
+	conn: EonConnection,
+	topic: string,
+	options: { retries?: number; delayMs?: number } = {},
+): Promise<void> {
+	assertIdentifier(topic, "topic name");
+	const retries = options.retries ?? 10;
+	const delayMs = options.delayMs ?? 300;
+
+	// TDengine rebalances a topic's partitions for a moment after a consumer
+	// disconnects, and refuses DROP TOPIC with "Topic being rebalanced" until it
+	// settles. Any suite that subscribed hits this, so the wait belongs here
+	// rather than copy-pasted into each one — and it must be BOUNDED: retrying
+	// forever would turn a real failure into a hang.
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await conn.exec(`DROP TOPIC IF EXISTS ${topic}`);
+			return;
+		} catch (error) {
+			const rebalancing = /being rebalanced/i.test(
+				error instanceof Error ? error.message : String(error),
+			);
+			if (!rebalancing || attempt >= retries) throw error;
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+		}
+	}
+}
+
+/**
+ * Drop a test database if it exists. Safe to call when it never existed.
+ *
+ * Fails if the database still carries a topic — see {@link dropTestTopic}.
+ */
+export async function dropTestDatabase(
+	conn: EonConnection,
+	database: string,
+): Promise<void> {
+	assertIdentifier(database, "database name");
+	await conn.exec(`DROP DATABASE IF EXISTS ${database}`);
+}
+
+/**
+ * Drop, recreate and `USE` a test database — the setup half of a suite.
+ *
+ * Dropping FIRST is the point: a suite that crashed mid-run leaves rows behind,
+ * and a `CREATE DATABASE IF NOT EXISTS` would then run against them. A test
+ * that passes only because the previous run left the right data is worse than
+ * one that fails.
+ */
+export async function createTestDatabase(
+	conn: EonConnection,
+	database: string,
+	options: { keepMs?: number } = {},
+): Promise<void> {
+	assertIdentifier(database, "database name");
+	await conn.exec(`DROP DATABASE IF EXISTS ${database}`);
+	const keep = options.keepMs === undefined ? "" : ` KEEP ${options.keepMs}`;
+	await conn.exec(`CREATE DATABASE ${database}${keep}`);
+	await conn.exec(`USE ${database}`);
+}
+
+/**
+ * Run a body against a freshly created test database, dropping it afterwards
+ * whether the body threw or not.
+ *
+ * The `finally` is what the hand-written `afterAll` blocks kept getting right
+ * by accident: a failing assertion must still leave the server clean, or the
+ * next run inherits the wreckage of this one.
+ */
+export async function withTestDatabase<T>(
+	conn: EonConnection,
+	database: string,
+	body: () => Promise<T>,
+): Promise<T> {
+	await createTestDatabase(conn, database);
+	try {
+		return await body();
+	} finally {
+		await dropTestDatabase(conn, database);
+	}
+}

package/src/testing/index.ts

@@ -6,15 +6,25 @@
  * integration suites skip via `describeIfTdengine` (mirrors atlas's "no external
  * DB required for unit tests" posture). CI sets it, so the roundtrip runs for
  * real — no silent cap. The fake store + factory need NO server.
+ *
+ * This module is RUNNER-AGNOSTIC and must stay that way: it is a shipped export
+ * path, so anything it imports becomes a hard requirement for every consumer.
+ * `describeIfTdengine` lives in `./vitest.js` for that reason.
  */
 
-import { describe } from "vitest";
 import type { EonConnectionConfig } from "../connection/config.js";
 import type { EonConnection } from "../connection/EonConnection.js";
 import { connectWsEon } from "../connection/websocket.js";
 
+export {
+	createTestDatabase,
+	dropTestDatabase,
+	dropTestTopic,
+	withTestDatabase,
+} from "./cleanup.js";
 export { type FactoryBuilder, factory } from "./Factory.js";
 export { FakeEonConnection } from "./FakeEonConnection.js";
+export { FakeEonConsumer } from "./FakeEonConsumer.js";
 
 /** The live TDengine URL for integration tests (taosAdapter WS), or `undefined`. */
 function testUrl(): string | undefined {
@@ -27,19 +37,6 @@ export function hasTestServer(): boolean {
 	return testUrl() !== undefined;
 }
 
-/**
- * Register a suite that runs only when a test server is configured, else skips —
- * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
- * real; local dev without a server skips them.
- */
-export function describeIfTdengine(name: string, factory: () => void): void {
-	if (hasTestServer()) {
-		describe(name, factory);
-	} else {
-		describe.skip(name, factory);
-	}
-}
-
 /**
  * Open a connection to the test server (`EON_TEST_URL`), applying root/taosdata
  * defaults and a generous connect-retry for a cold docker server. Callers gate

package/src/testing/vitest.ts

@@ -0,0 +1,27 @@
+/**
+ * The vitest-flavoured half of eon's test helpers.
+ *
+ * Split out on purpose. `@c9up/eon/testing` is a SHIPPED export path, and a
+ * static `import { describe } from "vitest"` made merely importing it require
+ * vitest — which eon carries as a devDependency only. An app on helix (ream's
+ * own runner) reaching for `factory` or `FakeEonConnection` would have died on
+ * `Cannot find package 'vitest'`, the same shape as the @c9up/comet bug.
+ *
+ * Everything runner-agnostic stays in `./index.ts`. Only this file needs the
+ * runner, and vitest is declared an OPTIONAL peer for it.
+ */
+import { describe } from "vitest";
+import { hasTestServer } from "./index.js";
+
+/**
+ * Register a suite that runs only when a test server is configured, else skips —
+ * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
+ * real; local dev without a server skips them.
+ */
+export function describeIfTdengine(name: string, factory: () => void): void {
+	if (hasTestServer()) {
+		describe(name, factory);
+	} else {
+		describe.skip(name, factory);
+	}
+}