@anteros/core 0.0.40 → 0.0.41

package/tests/lifecycle.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { formatConfig } from "../server/config";
+import { loadLifecycles, runBeforeBoot, runAfterBoot, runOnDestroy } from "../lib/lifecycle";
+import { define } from "../lib/define";
+
+const DIRS: Record<string, string> = {
+    normal: "packages/core/tests/fixtures/lc-normal",
+    thrower: "packages/core/tests/fixtures/lc-throw",
+    hang: "packages/core/tests/fixtures/lc-hang",
+    disabled: "packages/core/tests/fixtures/lc-disabled",
+};
+
+/** Configure cfg with a single tenant pointing at the given fixture dir. */
+function useFixture(id: string) {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id, dir: DIRS[id]!, database: { uri: "mongodb://localhost:27017/_LC_TEST" } }],
+    });
+}
+
+const callsOf = (key: string): string[] => ((globalThis as any)[key] ??= []);
+
+beforeEach(() => {
+    (globalThis as any).__lcNormal = [];
+    (globalThis as any).__lcHang = [];
+    (globalThis as any).__lcDisabled = [];
+});
+
+describe("define.Lifecycle", () => {
+    it("marks the config and defaults enabled to true", () => {
+        const lc = define.Lifecycle({ beforeBoot: () => {} });
+        expect(lc._isLifecycle_).toBe(true);
+        expect(lc.enabled).toBe(true);
+    });
+
+    it("keeps an explicit enabled: false", () => {
+        const lc = define.Lifecycle({ enabled: false });
+        expect(lc.enabled).toBe(false);
+    });
+});
+
+describe("lifecycle hooks", () => {
+    it("runs beforeBoot, afterBoot and onDestroy in order", async () => {
+        useFixture("normal");
+        await loadLifecycles();
+
+        await runBeforeBoot();
+        await runAfterBoot({ port: 4000 } as any, {} as any);
+        await runOnDestroy("SIGTERM");
+
+        expect(callsOf("__lcNormal")).toEqual(["beforeBoot", "afterBoot", "onDestroy:SIGTERM"]);
+        // `replication` is tenant-bound in the hook context (like `rest`)
+        expect((globalThis as any).__lcReplicationApi).toBe(true);
+    });
+
+    it("aborts the boot when beforeBoot throws (fail-fast)", async () => {
+        useFixture("thrower");
+        await loadLifecycles();
+
+        await expect(runBeforeBoot()).rejects.toThrow(/boom/);
+    });
+
+    it("bounds onDestroy with destroyTimeout instead of hanging", async () => {
+        useFixture("hang");
+        await loadLifecycles();
+
+        const started = Date.now();
+        await runOnDestroy("SIGINT"); // must resolve despite a hook that never resolves
+        const elapsed = Date.now() - started;
+
+        expect(callsOf("__lcHang")).toEqual(["onDestroy:start"]);
+        expect(elapsed).toBeGreaterThanOrEqual(100);
+        expect(elapsed).toBeLessThan(2000);
+    });
+
+    it("skips a disabled lifecycle", async () => {
+        useFixture("disabled");
+        await loadLifecycles();
+
+        await runBeforeBoot();
+        await runAfterBoot({} as any, {} as any);
+        await runOnDestroy("SIGINT");
+
+        expect(callsOf("__lcDisabled")).toEqual([]);
+    });
+
+    it("tolerates a tenant without a lifecycle.ts file", async () => {
+        formatConfig({
+            server: { port: 4000 },
+            tenants: [{ id: "nofile", dir: "packages/core/tests/fixtures/does-not-exist", database: { uri: "mongodb://localhost:27017/_LC_TEST" } }],
+        });
+        await loadLifecycles();
+        await expect(runBeforeBoot()).resolves.toBeUndefined();
+        await expect(runOnDestroy("SIGTERM")).resolves.toBeUndefined();
+    });
+});

package/tests/replication-control.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import {
+    startReplication,
+    stopReplication,
+    replicateTenant,
+    getReplicationState,
+    resetReplication,
+    seedReplication,
+} from "../database/replication";
+
+const TEST_TENANT = "replreset";
+const SRC_DB = "mongodb://localhost:27017/_REPL_RESET_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_RESET_DEST";
+const DEST_ID = "backup";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "src",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: DEST_ID, uri: DEST_DB }],
+            },
+        }],
+    });
+
+    sourceClient = new MongoClient(SRC_DB, { serverSelectionTimeoutMS: 3000 });
+    await sourceClient.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = sourceClient;
+    tenant.database.db = sourceClient.db();
+
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "orders",
+            fields: [{ name: "title", type: "string" }],
+            replication: { enabled: true },
+        },
+    ];
+
+    await startReplication();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+    destClient = new MongoClient(DEST_DB, { serverSelectionTimeoutMS: 3000 });
+    await destClient.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    try { await sourceClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.close(); } catch (_) {}
+    try { await sourceClient.close(); } catch (_) {}
+});
+
+describe("replication reset", () => {
+    it("clears state and re-runs from scratch", async () => {
+        await rest.insertOne("orders", { title: `reset-${crypto.randomUUID()}` });
+        await replicateTenant(TEST_TENANT);
+
+        const before = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(before.length).toBe(1);
+        expect(before[0]!.status).toBe("success");
+
+        const result = await resetReplication(TEST_TENANT);
+        expect(result.state).toBeGreaterThanOrEqual(1);
+
+        const after = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(after.length).toBe(0);
+
+        // Next run re-creates the state (fresh cursor)
+        await replicateTenant(TEST_TENANT);
+        const recreated = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(recreated.length).toBe(1);
+        expect(recreated[0]!.cursor.value).not.toBeNull();
+    });
+
+    it("supports scoping by destination", async () => {
+        await resetReplication(TEST_TENANT, { destination: DEST_ID });
+        const state = await getReplicationState(TEST_TENANT, DEST_ID);
+        expect(state.length).toBe(0);
+    });
+});
+
+describe("replication seed", () => {
+    const findDest = (title: string) => destClient.db().collection("orders").findOne({ title });
+
+    it("seeds 'latest' so pre-existing documents are skipped", async () => {
+        await resetReplication(TEST_TENANT);
+        const preMarker = `pre-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: preMarker });
+
+        const res = await seedReplication(TEST_TENANT, "latest");
+        expect(res.seeded).toBe(1);
+
+        await replicateTenant(TEST_TENANT);
+        expect(await findDest(preMarker)).toBeNull(); // nothing backfilled
+
+        await Bun.sleep(5);
+        const postMarker = `post-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: postMarker });
+        await replicateTenant(TEST_TENANT);
+
+        expect(await findDest(postMarker)).toBeDefined(); // only the new document
+    });
+
+    it("seeds from an explicit date", async () => {
+        await resetReplication(TEST_TENANT);
+        const res = await seedReplication(TEST_TENANT, "2020-01-01T00:00:00Z");
+        expect(res.seeded).toBe(1);
+
+        const state = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(state.length).toBe(1);
+        expect((state[0]!.cursor.value as any).toISOString()).toBe("2020-01-01T00:00:00.000Z");
+    });
+});

package/tests/replication-initial-sync.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+
+const TEST_TENANT = "replinit";
+const SRC_DB = "mongodb://localhost:27017/_REPL_INIT_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_INIT_DEST";
+const DEST_ID = "backup";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "src",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: DEST_ID, uri: DEST_DB }],
+            },
+        }],
+    });
+
+    sourceClient = new MongoClient(SRC_DB, { serverSelectionTimeoutMS: 3000 });
+    await sourceClient.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = sourceClient;
+    tenant.database.db = sourceClient.db();
+
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "orders",
+            fields: [
+                { name: "title", type: "string" },
+            ],
+            // Start at the latest document — skip everything that already exists.
+            replication: { enabled: true, initialSync: "latest" },
+        },
+    ];
+
+    await startReplication();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+    destClient = new MongoClient(DEST_DB, { serverSelectionTimeoutMS: 3000 });
+    await destClient.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    try { await sourceClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.close(); } catch (_) {}
+    try { await sourceClient.close(); } catch (_) {}
+});
+
+describe("replication initialSync", () => {
+    it("skips pre-existing documents with initialSync: 'latest'", async () => {
+        await rest.insertOne("orders", { title: `old-1-${crypto.randomUUID()}` });
+        await rest.insertOne("orders", { title: `old-2-${crypto.randomUUID()}` });
+
+        await replicateTenant(TEST_TENANT);
+
+        const count = await destClient.db().collection("orders").countDocuments();
+        expect(count).toBe(0); // existing docs are NOT backfilled
+    });
+
+    it("replicates documents added after the initial sync", async () => {
+        await Bun.sleep(5); // ensure the new doc has a strictly newer updatedAt
+
+        const marker = `new-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker });
+
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+    });
+});

package/tests/replication-only.test.ts

@@ -0,0 +1,358 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { MongoClient } from "mongodb";
+import { parseBootFlags, resolveCapabilities, capabilitiesLabel, conflictingBootFlags, FULL_CAPABILITIES } from "../server/flags";
+
+const FIXTURE = "packages/core/tests/fixtures/repl-only";
+const MARKERS = path.join(FIXTURE, "tenant", ".markers");
+const SRC = "mongodb://localhost:27017/_RO_SRC";
+const DST = "mongodb://localhost:27017/_RO_DST";
+const PORT = 5556;
+
+let proc: any;
+let src: MongoClient;
+let dst: MongoClient;
+let output = "";
+
+/** Poll `check` until it returns true (or throw after `timeout`) */
+async function waitFor(check: () => Promise<boolean>, timeout = 20_000, step = 250): Promise<boolean> {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        if (await check()) return true;
+        await Bun.sleep(step);
+    }
+    return false;
+}
+
+describe("boot capabilities", () => {
+    const flags = (over: Partial<ReturnType<typeof parseBootFlags>> = {}) => ({
+        replicationOnly: false, noReplication: false, apiOnly: false, noScripts: false, noSockets: false,
+        ...over,
+    });
+
+    it("reads every flag (and its camelCase spelling)", () => {
+        expect(parseBootFlags(["bun", "index.ts", "--replication-only"]).replicationOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--replicationOnly"]).replicationOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--no-replication"]).noReplication).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--api-only"]).apiOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--noScripts"]).noScripts).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--no-sockets"]).noSockets).toBe(true);
+
+        expect(parseBootFlags(["bun", "index.ts"])).toEqual(flags());
+    });
+
+    it("resolves the named modes", () => {
+        expect(resolveCapabilities(flags())).toEqual(FULL_CAPABILITIES);
+
+        expect(resolveCapabilities(flags(), "replication-only")).toEqual({
+            api: false, replication: true, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags(), "api-only")).toEqual({
+            api: true, replication: false, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags(), "no-replication")).toEqual({
+            api: true, replication: false, scripts: true, sockets: true,
+        });
+    });
+
+    it("lets the flags win over the configured mode", () => {
+        expect(resolveCapabilities(flags({ apiOnly: true }), "full")).toEqual({
+            api: true, replication: false, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags({ replicationOnly: true }), "no-replication")).toEqual({
+            api: false, replication: true, scripts: false, sockets: false,
+        });
+        // the most restrictive flag wins
+        expect(resolveCapabilities(flags({ replicationOnly: true, apiOnly: true })).api).toBe(false);
+    });
+
+    it("disables one capability at a time", () => {
+        expect(resolveCapabilities(flags({ noScripts: true }))).toEqual({
+            api: true, replication: true, scripts: false, sockets: true,
+        });
+        expect(resolveCapabilities(flags({ noSockets: true }))).toEqual({
+            api: true, replication: true, scripts: true, sockets: false,
+        });
+        expect(resolveCapabilities(flags({ noReplication: true }))).toEqual({
+            api: true, replication: false, scripts: true, sockets: true,
+        });
+    });
+
+    it("labels the mode for the banner", () => {
+        expect(capabilitiesLabel(FULL_CAPABILITIES)).toBe("full");
+        expect(capabilitiesLabel({ api: false, replication: true, scripts: false, sockets: false })).toBe("replication-only");
+        expect(capabilitiesLabel({ api: true, replication: false, scripts: false, sockets: false })).toBe("api-only");
+        // granular flags stay in `full` — the banner lists what is off
+        expect(capabilitiesLabel({ api: true, replication: true, scripts: false, sockets: true })).toBe("full");
+    });
+
+    it("reports contradictory flags", () => {
+        expect(conflictingBootFlags(flags({ replicationOnly: true, noReplication: true }))).toBe(true);
+        expect(conflictingBootFlags(flags({ replicationOnly: true, apiOnly: true }))).toBe(true);
+        expect(conflictingBootFlags(flags({ replicationOnly: true }))).toBe(false);
+        expect(conflictingBootFlags(flags({ apiOnly: true, noScripts: true }))).toBe(false);
+    });
+});
+
+describe("replication-only boot", () => {
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        src = new MongoClient(SRC);
+        dst = new MongoClient(DST);
+        await src.connect();
+        await dst.connect();
+        await src.db().collection("orders").drop().catch(() => {});
+        await dst.db().collection("orders").drop().catch(() => {});
+        await dst.db().collection("_replication_").drop().catch(() => {});
+
+        proc = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--replication-only"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        // Drain the pipes (a full buffer would block the child)
+        for (const stream of [proc.stdout, proc.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    output += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        // A document written to the source must reach the destination on its own
+        await src.db().collection("orders").insertOne({ ref: "RO-1", total: 42 } as any);
+    });
+
+    afterAll(async () => {
+        try { proc?.kill(); } catch {}
+        try { await src?.close(); } catch {}
+        try { await dst?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("replicates the tenant data", async () => {
+        const replicated = await waitFor(async () =>
+            (await dst.db().collection("orders").countDocuments({ ref: "RO-1" })) === 1,
+        );
+        expect(replicated, `no replication after 20s — app output:\n${output}`).toBe(true);
+
+        const onTarget: any = await dst.db().collection("orders").findOne({ ref: "RO-1" });
+        expect(onTarget.total).toBe(42);
+    }, 30_000);
+
+    it("exposes no HTTP API", async () => {
+        // `/health` is registered by the framework — if anything were listening, it would answer
+        const refused = await fetch(`http://localhost:${PORT}/health`)
+            .then(() => false)
+            .catch(() => true);
+        expect(refused, "a server is listening on the configured port").toBe(true);
+    });
+
+    it("still runs the lifecycle hooks", async () => {
+        const ran = await waitFor(async () => fs.existsSync(path.join(MARKERS, "lifecycle.txt")));
+        expect(ran, `beforeBoot did not run — app output:\n${output}`).toBe(true);
+    }, 30_000);
+
+    it("does not run the tenant scripts", async () => {
+        // give the (skipped) scripts path a chance to fire
+        await Bun.sleep(500);
+        expect(fs.existsSync(path.join(MARKERS, "script.txt"))).toBe(false);
+    });
+
+    it("keeps the process alive (replication timers are unref'd)", async () => {
+        await Bun.sleep(300);
+        expect(proc.exitCode, `the process exited — output:\n${output}`).toBeNull();
+    });
+
+    it("stops replication cleanly on SIGTERM (onDestroy runs)", async () => {
+        proc.kill("SIGTERM");
+
+        const exited = await waitFor(async () => proc.exitCode !== null, 10_000, 100);
+        expect(exited, `the process did not exit — output:\n${output}`).toBe(true);
+        expect(proc.exitCode).toBe(0);
+
+        const destroyed = await waitFor(async () => fs.existsSync(path.join(MARKERS, "onDestroy.txt")));
+        expect(destroyed, `onDestroy did not run — output:\n${output}`).toBe(true);
+    }, 30_000);
+});
+
+describe("no-replication boot", () => {
+    const PORT = 5557;
+    const SRC = "mongodb://localhost:27017/_NOREP_SRC";
+    const DST = "mongodb://localhost:27017/_NOREP_DST";
+
+    let procNo: any;
+    let srcNo: MongoClient;
+    let dstNo: MongoClient;
+    let outputNo = "";
+
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        srcNo = new MongoClient(SRC);
+        dstNo = new MongoClient(DST);
+        await srcNo.connect();
+        await dstNo.connect();
+        await srcNo.db().collection("orders").drop().catch(() => {});
+        await dstNo.db().collection("orders").drop().catch(() => {});
+
+        procNo = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--no-replication"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        for (const stream of [procNo.stdout, procNo.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    outputNo += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        // Wait for the server to listen before writing to the source
+        await waitFor(async () => {
+            try {
+                await fetch(`http://localhost:${PORT}/health`);
+                return true;
+            } catch {
+                return false;
+            }
+        }, 20_000);
+
+        await srcNo.db().collection("orders").insertOne({ ref: "NOREP-1", total: 7 } as any);
+    });
+
+    afterAll(async () => {
+        try { procNo?.kill(); } catch {}
+        try { await srcNo?.close(); } catch {}
+        try { await dstNo?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("serves the HTTP API", async () => {
+        const res = await fetch(`http://localhost:${PORT}/health`);
+        expect(res.status).toBe(200);
+        expect(await res.json()).toBeDefined();
+    });
+
+    it("never starts the replication engine", async () => {
+        // give it more than enough time to replicate, if it were going to
+        await Bun.sleep(2_000);
+
+        expect(await dstNo.db().collection("orders").countDocuments({})).toBe(0);
+        // …and no replication state was created either
+        const state = await srcNo.db().listCollections({ name: "_replication_" }).toArray();
+        expect(state.length).toBe(0);
+    }, 15_000);
+
+    it("still serves the Socket.IO endpoint", async () => {
+        const res = await fetch(`http://localhost:${PORT}/socket.io/?EIO=4&transport=polling`);
+        expect(res.status).toBe(200);
+    }, 15_000);
+
+    it("is otherwise a full server (scripts run, lifecycle hooks run)", async () => {
+        const scripted = await waitFor(async () => fs.existsSync(path.join(MARKERS, "script.txt")));
+        const lifecycle = await waitFor(async () => fs.existsSync(path.join(MARKERS, "lifecycle.txt")));
+
+        expect(lifecycle, `beforeBoot did not run — output:\n${outputNo}`).toBe(true);
+        expect(scripted, `scripts did not run — output:\n${outputNo}`).toBe(true);
+    }, 20_000);
+});
+
+describe("api-only boot", () => {
+    const PORT = 5558;
+    const SRC = "mongodb://localhost:27017/_APIONLY_SRC";
+    const DST = "mongodb://localhost:27017/_APIONLY_DST";
+
+    let procApi: any;
+    let srcApi: MongoClient;
+    let dstApi: MongoClient;
+    let outputApi = "";
+
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        srcApi = new MongoClient(SRC);
+        dstApi = new MongoClient(DST);
+        await srcApi.connect();
+        await dstApi.connect();
+        await srcApi.db().collection("orders").drop().catch(() => {});
+        await dstApi.db().collection("orders").drop().catch(() => {});
+
+        procApi = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--api-only"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        for (const stream of [procApi.stdout, procApi.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    outputApi += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        await waitFor(async () => {
+            try {
+                await fetch(`http://localhost:${PORT}/health`);
+                return true;
+            } catch {
+                return false;
+            }
+        }, 20_000);
+
+        await srcApi.db().collection("orders").insertOne({ ref: "APIONLY-1", total: 3 } as any);
+    });
+
+    afterAll(async () => {
+        try { procApi?.kill(); } catch {}
+        try { await srcApi?.close(); } catch {}
+        try { await dstApi?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("serves the HTTP API", async () => {
+        const res = await fetch(`http://localhost:${PORT}/health`);
+        expect(res.status).toBe(200);
+    });
+
+    it("does not serve the Socket.IO endpoint", async () => {
+        const res = await fetch(`http://localhost:${PORT}/socket.io/?EIO=4&transport=polling`);
+        expect(res.status, `the socket endpoint answered — output:\n${outputApi}`).not.toBe(200);
+    }, 15_000);
+
+    it("does not run the tenant scripts", async () => {
+        // the scripts path would have fired ~150ms after boot — give it more
+        await Bun.sleep(1_500);
+        expect(fs.existsSync(path.join(MARKERS, "script.txt"))).toBe(false);
+        // …while the lifecycle still runs (it is part of a normal boot)
+        expect(fs.existsSync(path.join(MARKERS, "lifecycle.txt"))).toBe(true);
+    }, 15_000);
+
+    it("never starts the replication engine", async () => {
+        await Bun.sleep(1_500);
+        expect(await dstApi.db().collection("orders").countDocuments({})).toBe(0);
+        const state = await srcApi.db().listCollections({ name: "_replication_" }).toArray();
+        expect(state.length).toBe(0);
+    }, 15_000);
+});