@sixthsummit/ship-testing 0.0.0-stage → 1.2.0

package/lib/outbox.js

@@ -0,0 +1,218 @@
+import { isOutbox, systemActor } from "@sixthsummit/ship-core";
+export function createInMemoryOutbox(outbox) {
+    if (!isOutbox(outbox)) {
+        throw new TypeError("createInMemoryOutbox requires an outbox created by defineOutbox()");
+    }
+    let rows = [];
+    let sequence = 0;
+    const outboxId = outbox.id;
+    const find = (id) => rows.findIndex((row) => row.id === id);
+    const replace = (index, patch) => {
+        const next = Object.freeze({ ...rows[index], ...patch });
+        rows[index] = next;
+        return next;
+    };
+    const record = async (_scope, intents) => Object.freeze(intents.map((intent) => {
+        if (intent.dedupeKey !== undefined &&
+            rows.some((row) => row.intentId === intent.intentId && row.dedupeKey === intent.dedupeKey)) {
+            return Object.freeze({ deduplicated: true });
+        }
+        sequence += 1;
+        const id = `${outboxId}:${sequence}`;
+        rows.push(Object.freeze({
+            id,
+            outboxId,
+            intentId: intent.intentId,
+            payload: intent.payload,
+            ...(intent.dedupeKey !== undefined ? { dedupeKey: intent.dedupeKey } : {}),
+            status: "pending",
+            attempts: 0,
+            availableAt: intent.availableAt,
+            createdAt: new Date(),
+        }));
+        return Object.freeze({ recordId: id, deduplicated: false });
+    }));
+    const claimMatching = async (now, batchSize, leaseMs, matchesIntent) => {
+        const claimed = [];
+        const due = rows
+            .map((row, index) => ({ row, index }))
+            .filter(({ row }) => matchesIntent(row.intentId) &&
+            ((row.status === "pending" && row.availableAt.getTime() <= now.getTime()) ||
+                (row.status === "claimed" && (row.leaseExpiresAt?.getTime() ?? 0) <= now.getTime())))
+            .sort((left, right) => left.row.availableAt.getTime() - right.row.availableAt.getTime())
+            .slice(0, batchSize);
+        for (const { index } of due) {
+            claimed.push(replace(index, {
+                status: "claimed",
+                leaseExpiresAt: new Date(now.getTime() + leaseMs),
+            }));
+        }
+        return Object.freeze(claimed);
+    };
+    const claimDue = (now, batchSize, leaseMs, intentIds) => claimMatching(now, batchSize, leaseMs, (intentId) => intentIds === undefined ? true : intentIds.includes(intentId));
+    const claimUnknownDue = (now, batchSize, leaseMs, knownIntentIds) => claimMatching(now, batchSize, leaseMs, (intentId) => !knownIntentIds.includes(intentId));
+    const complete = async (recordId, now) => {
+        const index = find(recordId);
+        if (index >= 0 && rows[index].status === "claimed") {
+            replace(index, { status: "completed", completedAt: now, leaseExpiresAt: undefined });
+        }
+    };
+    const fail = async (recordId, error, disposition, now) => {
+        const index = find(recordId);
+        if (index < 0 || rows[index].status !== "claimed")
+            return;
+        const attempts = rows[index].attempts + 1;
+        if ("deadLetter" in disposition) {
+            replace(index, {
+                status: "dead-lettered",
+                attempts,
+                lastError: error,
+                deadLetteredAt: now,
+                leaseExpiresAt: undefined,
+            });
+        }
+        else {
+            replace(index, {
+                status: "pending",
+                attempts,
+                lastError: error,
+                availableAt: disposition.retryAt,
+                leaseExpiresAt: undefined,
+            });
+        }
+    };
+    const listDeadLettered = async ({ limit }) => Object.freeze(rows.filter((row) => row.status === "dead-lettered").slice(0, limit));
+    const retry = async (recordId, now) => {
+        const index = find(recordId);
+        if (index < 0 || rows[index].status !== "dead-lettered")
+            return undefined;
+        return replace(index, { status: "pending", availableAt: now, deadLetteredAt: undefined });
+    };
+    const discard = async (recordId, reason, now) => {
+        const index = find(recordId);
+        if (index < 0 || rows[index].status !== "dead-lettered")
+            return undefined;
+        return replace(index, { status: "discarded", discardedAt: now, discardReason: reason });
+    };
+    const cleanup = async (retention, now) => {
+        let completedDeleted = 0;
+        let deadLetteredDeleted = 0;
+        rows = rows.filter((row) => {
+            if (row.status === "completed" &&
+                row.completedAt !== undefined &&
+                now.getTime() - row.completedAt.getTime() >= retention.completedMs) {
+                completedDeleted += 1;
+                return false;
+            }
+            const terminalAt = row.status === "dead-lettered" ? row.deadLetteredAt : row.discardedAt;
+            if ((row.status === "dead-lettered" || row.status === "discarded") &&
+                terminalAt !== undefined &&
+                now.getTime() - terminalAt.getTime() >= retention.deadLetteredMs) {
+                deadLetteredDeleted += 1;
+                return false;
+            }
+            return true;
+        });
+        return Object.freeze({ completedDeleted, deadLetteredDeleted });
+    };
+    const health = async (now) => {
+        const pending = rows.filter((row) => row.status === "pending");
+        const oldest = pending.reduce((best, row) => (best === undefined || row.availableAt < best ? row.availableAt : best), undefined);
+        return Object.freeze({
+            pending: pending.length,
+            claimed: rows.filter((row) => row.status === "claimed" && (row.leaseExpiresAt?.getTime() ?? 0) > now.getTime()).length,
+            deadLettered: rows.filter((row) => row.status === "dead-lettered").length,
+            ...(oldest ? { oldestPendingAt: oldest } : {}),
+        });
+    };
+    return Object.freeze({
+        kind: "ship.outbox-backend",
+        adapter: "memory",
+        outboxId,
+        record,
+        claimDue,
+        claimUnknownDue,
+        complete,
+        fail,
+        listDeadLettered,
+        retry,
+        discard,
+        cleanup,
+        health,
+        records: () => Object.freeze([...rows]),
+        reset: () => {
+            rows = [];
+            sequence = 0;
+        },
+    });
+}
+export function createInMemoryIdempotencyStore() {
+    const entries = new Map();
+    const claim = async (key, ttlMs, context) => {
+        const existing = entries.get(key);
+        if (existing && existing.expiresAt > context.now.getTime()) {
+            return existing.status === "completed" ? "duplicate" : "in-flight";
+        }
+        entries.set(key, { status: "in-flight", expiresAt: context.now.getTime() + ttlMs });
+        return "claimed";
+    };
+    return Object.freeze({
+        kind: "ship.idempotency-store",
+        adapter: "memory",
+        claim,
+        complete: async (key, result) => {
+            const existing = entries.get(key);
+            if (existing)
+                entries.set(key, { ...existing, status: "completed", result });
+        },
+        release: async (key) => {
+            if (entries.get(key)?.status === "in-flight")
+                entries.delete(key);
+        },
+        readResult: async (key, context) => {
+            const existing = entries.get(key);
+            return existing?.status === "completed" && existing.expiresAt > context.now.getTime()
+                ? existing.result
+                : undefined;
+        },
+        reset: () => entries.clear(),
+        purgeExpired: (before, prefix = "") => {
+            let purged = 0;
+            for (const [key, entry] of entries) {
+                if (key.startsWith(prefix) && entry.expiresAt < before.getTime()) {
+                    entries.delete(key);
+                    purged += 1;
+                }
+            }
+            return purged;
+        },
+    });
+}
+/**
+ * Runs `<outbox>.dispatch` until a pass claims nothing and returns the totals.
+ * Pair it with `createInMemoryOutbox()` in unit tests to assert on effects.
+ */
+export async function drainOutbox(executor, outbox, options = {}) {
+    const outboxId = typeof outbox === "string" ? outbox : outbox.id;
+    const operationId = `${outboxId}.dispatch`;
+    const actor = options.actor ?? systemActor({ id: "ship.testing.drain" });
+    const maxRuns = options.maxRuns ?? 100;
+    const totals = { batchSize: 0, claimed: 0, completed: 0, retried: 0, deadLettered: 0 };
+    for (let run = 0; run < maxRuns; run += 1) {
+        const result = await executor.run(operationId, {}, { actor });
+        if (!result.ok) {
+            throw new Error(`drainOutbox: ${operationId} failed with ${result.error.code}: ${result.error.message}`);
+        }
+        const pass = result.data;
+        // The dispatcher's batch size, reported once; the totals sum the passes.
+        totals.batchSize = pass.batchSize;
+        totals.claimed += pass.claimed;
+        totals.completed += pass.completed;
+        totals.retried += pass.retried;
+        totals.deadLettered += pass.deadLettered;
+        if (pass.claimed === 0)
+            return Object.freeze(totals);
+    }
+    throw new Error(`drainOutbox: ${operationId} still claimed records after ${maxRuns} runs`);
+}
+//# sourceMappingURL=outbox.js.map

package/lib/outbox.js.map

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

package/lib/parity.d.ts

@@ -0,0 +1,52 @@
+/**
+ * v3↔v4 behavioral-parity harness (A2-6).
+ *
+ * Exercises a v4 app with a recorded request and asserts the response matches a
+ * set of checks — either a v4-conformance contract or a behavior captured from a
+ * live v3 app (the parity oracle). Pure + in-process (Hono `app.request`), no
+ * Docker. Shipped via `@sixthsummit/ship-testing` so a consumer's migrated
+ * app can run its own captured fixtures. See docs/v4/tooling/parity-harness.md.
+ */
+/** Anything with Hono's `.request()` — the v4 app under test. */
+export interface RequestableApp {
+    request(path: string, init?: RequestInit): Promise<Response>;
+}
+export interface ParityCheck {
+    /** Dot-path into the captured response: `status`, `headers.<lowercased>`, `body.<...>`. */
+    path: string;
+    /** Deep-equality assertion. */
+    equals?: unknown;
+    /** Presence assertion (`true` = must be present, `false` = must be absent). */
+    exists?: boolean;
+}
+export interface ParityFixture {
+    id: string;
+    metadata: {
+        area: string;
+        /** The behavioral contract under test, e.g. "401 on missing token". */
+        surface: string;
+        /**
+         * `v4-conformance` = encodes a documented v4 contract (ships green).
+         * `v3-capture` = recorded from a live v3 app; asserts the v4 build matches.
+         */
+        source: "v3-capture" | "v4-conformance";
+        [k: string]: unknown;
+    };
+    request: {
+        method: string;
+        path: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    checks: ParityCheck[];
+}
+export interface ParityResult {
+    fixture: ParityFixture;
+    passed: boolean;
+    failures: string[];
+}
+/** Parse a JSONL fixture file (skips blank lines + `#` comments). */
+export declare function parseParityFixtures(jsonl: string): ParityFixture[];
+/** Exercise `app` with the fixture's request and evaluate its checks. */
+export declare function runParityFixture(app: RequestableApp, fixture: ParityFixture): Promise<ParityResult>;
+//# sourceMappingURL=parity.d.ts.map

package/lib/parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../src/parity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,WAAW;IAC1B,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,uEAAuE;QACvE,OAAO,EAAE,MAAM,CAAC;QAChB;;;WAGG;QACH,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAAC;QACxC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;KACtB,CAAC;IACF,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAMlE;AAiBD,yEAAyE;AACzE,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAgDvB"}

package/lib/parity.js

@@ -0,0 +1,72 @@
+/**
+ * v3↔v4 behavioral-parity harness (A2-6).
+ *
+ * Exercises a v4 app with a recorded request and asserts the response matches a
+ * set of checks — either a v4-conformance contract or a behavior captured from a
+ * live v3 app (the parity oracle). Pure + in-process (Hono `app.request`), no
+ * Docker. Shipped via `@sixthsummit/ship-testing` so a consumer's migrated
+ * app can run its own captured fixtures. See docs/v4/tooling/parity-harness.md.
+ */
+/** Parse a JSONL fixture file (skips blank lines + `#` comments). */
+export function parseParityFixtures(jsonl) {
+    return jsonl
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"))
+        .map((line) => JSON.parse(line));
+}
+function resolvePath(captured, path) {
+    let cur = captured;
+    for (const key of path.split(".")) {
+        if (cur == null || typeof cur !== "object")
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/** Exercise `app` with the fixture's request and evaluate its checks. */
+export async function runParityFixture(app, fixture) {
+    const { method, path, headers, body } = fixture.request;
+    const init = { method };
+    if (body !== undefined && body !== null) {
+        init.body = typeof body === "string" ? body : JSON.stringify(body);
+        init.headers = { "content-type": "application/json", ...(headers ?? {}) };
+    }
+    else if (headers) {
+        init.headers = headers;
+    }
+    const res = await app.request(path, init);
+    const rawText = await res.text();
+    let parsedBody = rawText;
+    if (rawText.length > 0) {
+        try {
+            parsedBody = JSON.parse(rawText);
+        }
+        catch {
+            /* non-JSON body — keep the raw text */
+        }
+    }
+    else {
+        parsedBody = null;
+    }
+    const captured = {
+        status: res.status,
+        headers: Object.fromEntries([...res.headers.entries()].map(([k, v]) => [k.toLowerCase(), v])),
+        body: parsedBody,
+    };
+    const failures = [];
+    for (const check of fixture.checks) {
+        const actual = resolvePath(captured, check.path);
+        if (check.exists !== undefined) {
+            const present = actual !== undefined;
+            if (present !== check.exists) {
+                failures.push(`${check.path}: expected ${check.exists ? "present" : "absent"}, got ${present ? "present" : "absent"}`);
+            }
+        }
+        if (check.equals !== undefined && JSON.stringify(actual) !== JSON.stringify(check.equals)) {
+            failures.push(`${check.path}: expected ${JSON.stringify(check.equals)}, got ${JSON.stringify(actual)}`);
+        }
+    }
+    return { fixture, passed: failures.length === 0, failures };
+}
+//# sourceMappingURL=parity.js.map

package/lib/parity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parity.js","sourceRoot":"","sources":["../src/parity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4CH,qEAAqE;AACrE,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,KAAK;SACT,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SAC1D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC,CAAC;AACtD,CAAC;AAQD,SAAS,WAAW,CAAC,QAA0B,EAAE,IAAY;IAC3D,IAAI,GAAG,GAAY,QAAQ,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7D,GAAG,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAmB,EACnB,OAAsB;IAEtB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IACxD,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,CAAC;IACrC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,OAAO,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;IAC5E,CAAC;SAAM,IAAI,OAAO,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,UAAU,GAAY,OAAO,CAAC;IAClC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,MAAM,QAAQ,GAAqB;QACjC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7F,IAAI,EAAE,UAAU;KACjB,CAAC;IAEF,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,MAAM,KAAK,SAAS,CAAC;YACrC,IAAI,OAAO,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC7B,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,CAAC,IAAI,cAAc,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,SAAS,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CACxG,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1F,QAAQ,CAAC,IAAI,CACX,GAAG,KAAK,CAAC,IAAI,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC9D,CAAC"}

package/lib/postgres.d.ts

@@ -0,0 +1,93 @@
+import { type StartedPostgreSqlContainer } from "@testcontainers/postgresql";
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import pg from "pg";
+/**
+ * Real-Postgres test harness — spins up an ephemeral Postgres
+ * container, builds a Drizzle client against it, and pushes the
+ * supplied Drizzle schema so the tables exist before tests run.
+ *
+ * Why testcontainers: the per-module unit tests (accounts /
+ * oauth / outbox) drive `DrizzleEntityService` against
+ * a fake Drizzle-shaped DB so the test loop is fast and Docker-
+ * free. Integration tests under `*.integration.test.ts` exercise
+ * the SAME services against a real Postgres so the SQL the
+ * framework actually emits — partial indexes, FK cascades,
+ * `onConflictDoUpdate`, transactional outbox semantics — gets
+ * verified end-to-end. Different surface; both matter.
+ *
+ * This harness is the foundation for V4_STATUS G3. First
+ * integration test ships in this commit; oauth + outbox
+ * integration tests layer on in subsequent slices.
+ *
+ * Usage (suite-scoped, one container per describe block):
+ *
+ *   import { describe, beforeAll, afterAll, it, expect } from "vitest";
+ *   import { setupPostgresTestDb, type PostgresTestDb }
+ *     from "@sixthsummit/ship-testing/postgres";
+ *   import { accountsSchema } from "../../../../../../modules/accounts/index.js";
+ *
+ *   describe("accounts integration", () => {
+ *     let dbCtx: PostgresTestDb<typeof accountsSchema>;
+ *     beforeAll(async () => {
+ *       dbCtx = await setupPostgresTestDb(accountsSchema);
+ *     }, 60_000);
+ *     afterAll(async () => { await dbCtx.cleanup(); });
+ *
+ *     it("inserts and reads", async () => {
+ *       // dbCtx.db is a fully typed NodePgDatabase<typeof schema>.
+ *     });
+ *   });
+ *
+ * The container starts in ~3–10 s on a warm Docker daemon. Tests
+ * SHOULD share a container per describe block (suite-scoped
+ * lifecycle); per-test container overhead would dominate runtime.
+ * Per-test isolation comes from `truncateAll(dbCtx)` between
+ * tests, not from a fresh container.
+ *
+ * NOT included by the default `pnpm test` run — the root Vitest
+ * config excludes `*.integration.test.ts`. Run via
+ * `pnpm run test:integration`.
+ */
+export interface PostgresTestDb<TSchema extends Record<string, unknown>> {
+    /** Started Postgres container (testcontainers handle). */
+    container: StartedPostgreSqlContainer;
+    /** Underlying pg.Pool. Surface for raw queries when Drizzle's API doesn't fit. */
+    pool: pg.Pool;
+    /** Fully-typed Drizzle client over the supplied schema. */
+    db: NodePgDatabase<TSchema>;
+    /** The connection string; useful when spawning subprocesses. */
+    connectionString: string;
+    /** Tear down the container + close the pool. Idempotent. */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Bring up a Postgres container, build a Drizzle client, and push
+ * the supplied schema so the tables exist. Returns the test-db
+ * context plus a cleanup hook.
+ *
+ * The schema arg is a `Record<string, unknown>` matching the shape
+ * of `import * as schema from "..."` — drizzle-kit's `pushSchema`
+ * walks the imports and creates every `pgTable` it finds, plus
+ * any `pgEnum`s, indexes, and foreign keys.
+ */
+/**
+ * A `pg.Pool` for a test against the disposable container. Attaches the
+ * pool-level `error` listener that `pg` requires: when the container stops
+ * while an idle client is still connected, the server sends
+ * `57P01 terminating connection due to administrator command`, and without
+ * a listener that arrives as an uncaught exception after the suite has
+ * already passed. Tests that build their own pools should use this too.
+ */
+export declare function createPostgresTestPool(connectionString: string, options?: Omit<pg.PoolConfig, "connectionString">): pg.Pool;
+export declare function setupPostgresTestDb<TSchema extends Record<string, unknown>>(schema: TSchema): Promise<PostgresTestDb<TSchema>>;
+/**
+ * Truncate every table in the supplied schema, restarting identity
+ * columns. Use between tests in a suite to isolate per-test state
+ * without paying the container-startup cost.
+ *
+ * Iterates every value in the schema export that has a `_.name`
+ * property (the convention drizzle-orm uses for `pgTable` metadata).
+ * Skips relations, enums, and any other non-table exports.
+ */
+export declare function truncateAll<TSchema extends Record<string, unknown>>(ctx: PostgresTestDb<TSchema>): Promise<void>;
+//# sourceMappingURL=postgres.d.ts.map

package/lib/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAElG,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,0DAA0D;IAC1D,SAAS,EAAE,0BAA0B,CAAC;IACtC,kFAAkF;IAClF,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IACd,2DAA2D;IAC3D,EAAE,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,CAAM,GACpD,EAAE,CAAC,IAAI,CAIT;AAED,wBAAsB,mBAAmB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAkClC;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/lib/postgres.js

@@ -0,0 +1,83 @@
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+import { pushSchema } from "drizzle-kit/api";
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+/**
+ * Bring up a Postgres container, build a Drizzle client, and push
+ * the supplied schema so the tables exist. Returns the test-db
+ * context plus a cleanup hook.
+ *
+ * The schema arg is a `Record<string, unknown>` matching the shape
+ * of `import * as schema from "..."` — drizzle-kit's `pushSchema`
+ * walks the imports and creates every `pgTable` it finds, plus
+ * any `pgEnum`s, indexes, and foreign keys.
+ */
+/**
+ * A `pg.Pool` for a test against the disposable container. Attaches the
+ * pool-level `error` listener that `pg` requires: when the container stops
+ * while an idle client is still connected, the server sends
+ * `57P01 terminating connection due to administrator command`, and without
+ * a listener that arrives as an uncaught exception after the suite has
+ * already passed. Tests that build their own pools should use this too.
+ */
+export function createPostgresTestPool(connectionString, options = {}) {
+    const pool = new pg.Pool({ connectionString, ...options });
+    pool.on("error", () => undefined);
+    return pool;
+}
+export async function setupPostgresTestDb(schema) {
+    const container = await new PostgreSqlContainer("postgres:16-alpine")
+        .withDatabase("ship_api_test")
+        .withUsername("ship_api")
+        .withPassword("ship_api")
+        .start();
+    const connectionString = container.getConnectionUri();
+    const pool = createPostgresTestPool(connectionString, { max: 5 });
+    const db = drizzle(pool, { schema });
+    // Programmatic pushSchema — same machinery `drizzle-kit push`
+    // uses, no migration files needed. The framework's schema source
+    // (.ts files) is the single source of truth for both runtime and
+    // tests. Schema changes propagate without committing intermediate
+    // migration SQL the test harness would otherwise have to track.
+    //
+    // The cast is required because drizzle-kit's `pushSchema` is
+    // typed against a dialect-agnostic `PgDatabase<any, ...>` rather
+    // than the concrete `NodePgDatabase<TSchema>` the runtime uses.
+    // Both are functionally compatible.
+    const result = await pushSchema(schema, db);
+    await result.apply();
+    return {
+        container,
+        pool,
+        db,
+        connectionString,
+        cleanup: async () => {
+            await pool.end().catch(() => undefined);
+            await container.stop().catch(() => undefined);
+        },
+    };
+}
+/**
+ * Truncate every table in the supplied schema, restarting identity
+ * columns. Use between tests in a suite to isolate per-test state
+ * without paying the container-startup cost.
+ *
+ * Iterates every value in the schema export that has a `_.name`
+ * property (the convention drizzle-orm uses for `pgTable` metadata).
+ * Skips relations, enums, and any other non-table exports.
+ */
+export async function truncateAll(ctx) {
+    const tableNames = [];
+    for (const exported of Object.values(ctx.db._.schema ?? {})) {
+        const meta = exported?.dbName;
+        if (typeof meta === "string" && meta.length > 0)
+            tableNames.push(meta);
+    }
+    if (tableNames.length === 0)
+        return;
+    // Single TRUNCATE statement covers all tables; CASCADE handles FK
+    // references; RESTART IDENTITY resets serial / identity sequences.
+    const quoted = tableNames.map((n) => `"${n}"`).join(", ");
+    await ctx.pool.query(`TRUNCATE TABLE ${quoted} RESTART IDENTITY CASCADE`);
+}
+//# sourceMappingURL=postgres.js.map

package/lib/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAmC,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAuB,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,MAAM,IAAI,CAAC;AA+DpB;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,gBAAwB,EACxB,UAAmD,EAAE;IAErD,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,gBAAgB,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC3D,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAe;IAEf,MAAM,SAAS,GAAG,MAAM,IAAI,mBAAmB,CAAC,oBAAoB,CAAC;SAClE,YAAY,CAAC,eAAe,CAAC;SAC7B,YAAY,CAAC,UAAU,CAAC;SACxB,YAAY,CAAC,UAAU,CAAC;SACxB,KAAK,EAAE,CAAC;IAEX,MAAM,gBAAgB,GAAG,SAAS,CAAC,gBAAgB,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,sBAAsB,CAAC,gBAAgB,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAErC,8DAA8D;IAC9D,iEAAiE;IACjE,iEAAiE;IACjE,kEAAkE;IAClE,gEAAgE;IAChE,EAAE;IACF,6DAA6D;IAC7D,iEAAiE;IACjE,gEAAgE;IAChE,oCAAoC;IACpC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,EAAiD,CAAC,CAAC;IAC3F,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,OAAO;QACL,SAAS;QACT,IAAI;QACJ,EAAE;QACF,gBAAgB;QAChB,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACxC,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAA4B;IAE5B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAI,QAA4C,EAAE,MAAM,CAAC;QACnE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,kEAAkE;IAClE,mEAAmE;IACnE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,MAAM,2BAA2B,CAAC,CAAC;AAC5E,CAAC"}

package/lib/realtime.d.ts

@@ -0,0 +1,93 @@
+import type { AnyChannel, AnyModule, ApplicationExecutor, CompiledApplication, OutboxDispatchResult, RealtimeBackend, RuntimeSchema, TenantScopeAuthority } from "@sixthsummit/ship-core";
+import { type DrainOutboxOptions } from "./outbox.js";
+export interface RealtimePublication {
+    readonly channelId: string;
+    readonly scopeKey: string;
+    readonly payload: unknown;
+    readonly publishedAt: string;
+}
+export interface InMemoryRealtimeBackendOptions {
+    readonly channels: readonly AnyChannel[];
+    readonly tenantScopes?: TenantScopeAuthority;
+    readonly id?: string;
+}
+/**
+ * Deterministic process-local realtime backend for unit tests and the raw
+ * WebSocket smoke fixture. Delivery is synchronous, presence is held in
+ * memory, and every accepted publication is recorded for assertions.
+ */
+export interface InMemoryRealtimeBackend extends RealtimeBackend {
+    readonly adapter: "memory";
+    readonly published: readonly RealtimePublication[];
+    /** Registers additional channels after construction. */
+    register(channels: readonly AnyChannel[]): void;
+    reset(): void;
+}
+export declare function createInMemoryRealtimeBackend(options: InMemoryRealtimeBackendOptions): InMemoryRealtimeBackend;
+export interface CollectedPublishes<TApp extends CompiledApplication<string, readonly AnyModule[]>> {
+    /** The same application with every channel publication bound to the recording backend. */
+    readonly application: TApp;
+    readonly backend: InMemoryRealtimeBackend;
+    /** Publications accepted so far, oldest first. */
+    publishes(): readonly RealtimePublication[];
+}
+/**
+ * Recompiles an application so every channel publication provider records
+ * into one in-memory backend, without asking the app factory to accept a
+ * backend parameter. Other providers are kept as declared.
+ */
+export declare function collectPublishes<TApp extends CompiledApplication<string, readonly AnyModule[]>>(application: TApp, options?: {
+    readonly tenantScopes?: TenantScopeAuthority;
+}): CollectedPublishes<TApp>;
+/**
+ * Runs `ship-realtime.publication.dispatch` until nothing is claimed, so
+ * publications recorded by `transaction: "write"` operations reach the
+ * backend `collectPublishes()` records into. The application must mount
+ * `defineRealtimePublicationModule()`.
+ */
+export declare function drainRealtimePublications(executor: ApplicationExecutor<CompiledApplication<string, readonly AnyModule[]>>, options?: DrainOutboxOptions): Promise<OutboxDispatchResult>;
+export type ConformanceTest = (name: string, run: () => Promise<void>) => unknown;
+export interface RealtimeConformanceOptions {
+    /** Builds a fresh backend registered with the suite's fixture channels. */
+    readonly createBackend: (channels: readonly AnyChannel[], options: {
+        readonly tenantScopes: TenantScopeAuthority;
+    }) => RealtimeBackend | Promise<RealtimeBackend>;
+    /** The host runner's test registration function, e.g. vitest `it`. */
+    readonly test: ConformanceTest;
+    /** Upper bound for asynchronous delivery. Defaults to 2000 ms. */
+    readonly deliveryTimeoutMs?: number;
+}
+export declare const conformanceChannels: Readonly<{
+    feed: import("@sixthsummit/ship-core").Channel<"conformance.feed", "actor", RuntimeSchema<{
+        readonly n: number;
+    }, {
+        readonly n: number;
+    }>, false>;
+    room: import("@sixthsummit/ship-core").Channel<"conformance.room", "tenant", RuntimeSchema<{
+        readonly n: number;
+    }, {
+        readonly n: number;
+    }>, true>;
+    board: import("@sixthsummit/ship-core").Channel<"conformance.board", "resource", RuntimeSchema<{
+        readonly n: number;
+    }, {
+        readonly n: number;
+    }>, true>;
+    ticker: import("@sixthsummit/ship-core").Channel<"conformance.ticker", "actor", RuntimeSchema<{
+        readonly id: string;
+        readonly n: number;
+    }, {
+        readonly id: string;
+        readonly n: number;
+    }>, false>;
+}>;
+export declare const conformanceTenantScopes: TenantScopeAuthority;
+/**
+ * Registers the behavioral contract every RealtimeBackend must satisfy:
+ * authorized delivery, fail-closed subscription authorization, per-scope
+ * isolation and sequencing, presence dedupe, coalescing, disconnect
+ * cleanup, and health. Both the in-memory backend and the Socket.IO
+ * adapter run exactly this suite.
+ */
+export declare function realtimeBackendConformance(options: RealtimeConformanceOptions): void;
+//# sourceMappingURL=realtime.d.ts.map