@justscale/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JustScale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @justscale/testing
+
+Test utilities for JustScale: a `createTestKit()` harness that spawns one or more app instances with lifecycle auto-drain, plus DI mocks and spy helpers built on `node:test`.
+
+## Install
+
+```bash
+pnpm add -D @justscale/testing
+```
+
+## Usage
+
+```ts
+import { test } from 'node:test';
+import { createTestKit } from '@justscale/testing';
+
+test('user service', async (t) => {
+  const kit = createTestKit(t);
+
+  const app = await kit.spawn(builder =>
+    builder.register(UserRepository, myInMemoryRepo),
+  );
+
+  const result = await app.service(UserService).findAll();
+  assert.ok(result.length > 0);
+});
+```
+
+`createTestKit(t)` registers `afterEach` automatically and drains all lifecycle handles (timers, locks, channels) on teardown — no manual cleanup required.
+
+## API
+
+- `createTestKit(t)` — primary harness.
+  - `kit.spawn(builderFn)` — single in-process app.
+  - `kit.spawnHttp(builderFn, opts?)` — app with real HTTP listener; returns typed client for controller endpoints.
+  - `kit.spawnCluster(n, builderFn)` — `n` coordinated instances for distributed-invariant tests.
+- `TestContainer` — low-level DI container that accepts mocks in place of concrete services.
+- `createTestApp` — compiles an app without opening real sockets; use `.get` / `.post` / etc.
+- `mockService` / `spyOn` / `mockFn` / `mockResolves` — thin wrappers over `node:test` mocks with DI-aware typings.
+- `InMemoryLockProvider` — lock primitive without Postgres, useful for unit tests.
+
+## Docs
+
+https://justscale.sh/testing/overview

package/dist/app.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Test App
+ *
+ * Create a testable app instance with access to internals.
+ */
+import type { App, ServiceToken, InstanceOf, ControllerDef } from '@justscale/core';
+import { TestContainer } from './container.js';
+/**
+ * Extended App interface for testing with access to container and helpers.
+ */
+export interface TestApp extends App {
+    /** The test container - allows mocking services */
+    readonly testContainer: TestContainer;
+    /**
+     * Get typed access to a service from the container.
+     *
+     * @example
+     * ```typescript
+     * const userService = await app.service(UserService);
+     * ```
+     */
+    service<T extends ServiceToken>(token: T): Promise<InstanceOf<T>>;
+    /**
+     * Mock a service with a partial implementation.
+     *
+     * @example
+     * ```typescript
+     * app.mock(UserRepository, {
+     *   findById: mockFn().returns(Promise.resolve(null)),
+     * });
+     * ```
+     */
+    mock<T>(token: ServiceToken<T>, mockInstance: Partial<T>): TestApp;
+    /**
+     * Clear all mocks.
+     */
+    clearMocks(): TestApp;
+}
+/**
+ * Configuration for creating a test app.
+ */
+export interface TestAppConfig {
+    services?: ServiceToken[];
+    controllers: ControllerDef<any>[];
+}
+/**
+ * Create a test app with mock support.
+ *
+ * @example
+ * ```typescript
+ * const app = createTestApp({
+ *   services: [UserRepository, UserService],
+ *   controllers: [UsersController],
+ * });
+ *
+ * // Mock a dependency
+ * app.mock(UserRepository, {
+ *   findById: mockFn().returns(Promise.resolve({ id: '1' })),
+ * });
+ *
+ * // Access services
+ * const userService = app.service(UserService);
+ *
+ * // Use the app for testing
+ * const matched = app.match('GET', '/users/1');
+ * ```
+ */
+export declare function createTestApp(config: TestAppConfig): Promise<TestApp>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAgB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAElG,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,OAAQ,SAAQ,GAAG;IAClC,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAElE;;;;;;;;;OASG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAEnE;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CA0F3E"}

package/dist/app.js

@@ -0,0 +1,105 @@
+/**
+ * Test App
+ *
+ * Create a testable app instance with access to internals.
+ */
+import { executeSteps } from '@justscale/core';
+import { TestContainer } from './container.js';
+/**
+ * Create a test app with mock support.
+ *
+ * @example
+ * ```typescript
+ * const app = createTestApp({
+ *   services: [UserRepository, UserService],
+ *   controllers: [UsersController],
+ * });
+ *
+ * // Mock a dependency
+ * app.mock(UserRepository, {
+ *   findById: mockFn().returns(Promise.resolve({ id: '1' })),
+ * });
+ *
+ * // Access services
+ * const userService = app.service(UserService);
+ *
+ * // Use the app for testing
+ * const matched = app.match('GET', '/users/1');
+ * ```
+ */
+export async function createTestApp(config) {
+    const container = new TestContainer();
+    const controllers = [];
+    // Register all services
+    for (const service of config.services ?? []) {
+        if (typeof service === 'function') {
+            container.registerClass(service);
+        }
+        else {
+            container.register(service);
+        }
+    }
+    // Register and resolve controllers
+    for (const controllerDef of config.controllers) {
+        container.register(controllerDef);
+        const instance = await container.resolve(controllerDef);
+        controllers.push(instance);
+    }
+    function match(method, pathname) {
+        for (const controller of controllers) {
+            for (const route of controller.routes) {
+                if (route.method !== method)
+                    continue;
+                const routeMatch = pathname.match(route.pattern);
+                if (!routeMatch)
+                    continue;
+                const params = {};
+                route.paramNames.forEach((name, i) => {
+                    params[name] = routeMatch[i + 1] ?? '';
+                });
+                return { route, deps: controller.deps, params };
+            }
+        }
+        return null;
+    }
+    async function execute(matched, contextAdditions) {
+        const { route, deps, params } = matched;
+        const ctx = {
+            deps,
+            params,
+            ...contextAdditions,
+        };
+        // Run steps (middleware + guards) via the canonical path that reads route.steps.
+        // The old route.middlewares/route.guards fields are always [] after compilation.
+        const passed = await executeSteps(route, ctx);
+        if (!passed) {
+            return undefined; // Guard denied
+        }
+        return route.handler(ctx);
+    }
+    const app = {
+        container,
+        controllers,
+        adapters: [],
+        subApps: [],
+        match,
+        execute,
+        ready: Promise.resolve(), // Test app is always ready immediately
+        get testContainer() {
+            return container;
+        },
+        service(token) {
+            return container.get(token);
+        },
+        mock(token, mockInstance) {
+            container.mock(token, mockInstance);
+            return app;
+        },
+        clearMocks() {
+            container.clearMocks();
+            return app;
+        },
+    };
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Test Client
+ *
+ * Provides a base test client for testing JustScale applications.
+ * Transport-specific functionality (HTTP, CLI, etc.) is added via explicit
+ * transport configuration.
+ */
+import type { App, ServiceDef, Service, ControllerDef, ResponseEntry } from '@justscale/core';
+/**
+ * Drain an app's background work without going through BuiltApp.stop().
+ * Tests use `JustScale().add(...).build().compile()` which returns the
+ * raw App (no stop method); we replicate the kernel's teardown order so
+ * the event loop drains and the test process can exit cleanly.
+ *
+ * Use this in tests that build an app directly (no TestClient) to avoid
+ * the "Promise resolution still pending" file-level timeout.
+ */
+export declare function teardownApp(app: App): Promise<void>;
+import type { Ref } from '@justscale/core/models';
+/**
+ * Response from a test request.
+ * Transports extend this with their specific fields.
+ */
+export interface TestResponse<T = unknown, TStatus extends number = number> {
+    /** HTTP status code */
+    status: TStatus;
+    /** Parsed response data */
+    data: T;
+    /** Whether the request was successful (2xx status) */
+    ok: TStatus extends 200 | 201 | 202 | 203 | 204 | 205 | 206 ? true : false;
+}
+type ServiceInstance<T> = T extends ServiceDef<infer S, any> ? S : T extends Service<infer S, any> ? S : never;
+type AnyServiceDef = ServiceDef<any, any> | Service<any, any>;
+type BuildServiceAPI<T extends Record<string, AnyServiceDef>> = {
+    [K in keyof T]: ServiceInstance<T[K]>;
+};
+type ExtractPathParams<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? {
+    [K in Param]: string;
+} & ExtractPathParams<`/${Rest}`> : Path extends `${string}:${infer Param}` ? {
+    [K in Param]: string;
+} : {};
+/**
+ * Resolve the model class for a given path param, supporting lowercase matching.
+ * `.types({ Campaign })` matches path param `:campaign` (lowercased key).
+ */
+type ResolveParamModel<ParamName extends string, TParamTypes extends Record<string, abstract new (...args: any[]) => any>> = {
+    [K in keyof TParamTypes]: Lowercase<ParamName> extends Lowercase<K & string> ? TParamTypes[K] : never;
+}[keyof TParamTypes];
+/**
+ * The type a client may pass for a path param.
+ * If `.types({ Model })` declared the model for this param, accept a string OR
+ * any Ref<Model> (Reference / Persistent / Locked) - the transport extracts
+ * the identifier at runtime via refId().
+ */
+type ClientPathParamValue<ParamName extends string, TParamTypes extends Record<string, abstract new (...args: any[]) => any>> = [
+    ResolveParamModel<ParamName, TParamTypes>
+] extends [never] ? string : string | Ref<InstanceType<Extract<ResolveParamModel<ParamName, TParamTypes>, abstract new (...args: any[]) => any>>>;
+type ClientPathParams<Path extends string, TParamTypes extends Record<string, abstract new (...args: any[]) => any>> = {
+    [K in keyof ExtractPathParams<Path>]: ClientPathParamValue<K & string, TParamTypes>;
+};
+type JoinPath<TPrefix extends string, TPath extends string> = TPath extends '/' ? TPrefix extends '/' ? '/' : TPrefix : TPrefix extends '/' ? TPath : `${TPrefix}${TPath}`;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+type ResponseEntryToTestResponse<T> = T extends ResponseEntry<infer Status extends number, infer Body, any> ? TestResponse<Body, Status> : TestResponse<unknown>;
+type HasKnownBody<T> = unknown extends T ? false : true;
+type ExtractRouteReturns<T> = T extends {
+    _types?: {
+        returns: infer R;
+    };
+} ? R : unknown;
+type ExtractRouteBody<T> = T extends {
+    _types?: {
+        body: infer B;
+    };
+} ? B : unknown;
+type ExtractRouteParamTypes<T> = T extends {
+    _types?: {
+        paramTypes: infer P;
+    };
+} ? P extends Record<string, abstract new (...args: any[]) => any> ? P : {} : {};
+type TypedRouteMethodV2<TPath extends string, TReturns, TBody, TParamTypes extends Record<string, abstract new (...args: any[]) => any> = {}> = IsEmptyObject<ExtractPathParams<TPath>> extends true ? HasKnownBody<TBody> extends true ? (input: TBody) => Promise<ResponseEntryToTestResponse<TReturns>> : (input?: Record<string, unknown>) => Promise<ResponseEntryToTestResponse<TReturns>> : HasKnownBody<TBody> extends true ? (input: Prettify<ClientPathParams<TPath, TParamTypes> & TBody>) => Promise<ResponseEntryToTestResponse<TReturns>> : (input: Prettify<ClientPathParams<TPath, TParamTypes>> & Record<string, unknown>) => Promise<ResponseEntryToTestResponse<TReturns>>;
+type RouteToMethod<TRoute, TPrefix extends string> = TRoute extends {
+    path: infer Path extends string;
+    steps: any[];
+} ? TypedRouteMethodV2<JoinPath<TPrefix, Path>, ExtractRouteReturns<TRoute>, ExtractRouteBody<TRoute>, ExtractRouteParamTypes<TRoute>> : never;
+type ExtractPrefix<TSettings> = TSettings extends {
+    prefix: infer P extends string;
+} ? P : '/';
+type ControllerMethods<TController> = TController extends ControllerDef<any, infer Routes, infer Settings> ? {
+    [K in keyof Routes]: RouteToMethod<Routes[K], ExtractPrefix<Settings>>;
+} : never;
+/**
+ * Build typed API from a controller mapping
+ */
+export type BuildControllerAPI<T extends Record<string, ControllerDef<any, any, any>>> = {
+    [K in keyof T]: ControllerMethods<T[K]>;
+};
+/**
+ * Internal state passed to transports
+ */
+export interface TransportState {
+    app: App<any>;
+    cleanupFns: (() => Promise<void> | void)[];
+}
+/**
+ * Base interface for a test transport.
+ * Transports implement this to provide their functionality.
+ */
+export interface TestTransport<TTransportClient = unknown, TOptions = unknown> {
+    /** Called during client creation to set up the transport */
+    setup(state: TransportState, options?: TOptions): Promise<TTransportClient> | TTransportClient;
+    /** Called during cleanup */
+    cleanup?(transportClient: TTransportClient): Promise<void> | void;
+}
+/**
+ * Extract the client type from a transport
+ */
+export type TransportClient<T> = T extends TestTransport<infer C, any> ? C : never;
+/**
+ * Extract options type from a transport
+ */
+export type TransportOptions<T> = T extends TestTransport<any, infer O> ? O : never;
+/**
+ * Base test client interface.
+ */
+export interface TestClient<_TApp extends App<any> = App<any>> {
+    /**
+     * Get typed access to services from the app.
+     *
+     * @example
+     * ```typescript
+     * const { game, playerRepo } = await client.services({
+     *   game: GameService,
+     *   playerRepo: PlayerRepository,
+     * });
+     * ```
+     */
+    services<T extends Record<string, AnyServiceDef>>(mapping: T): Promise<BuildServiceAPI<T>>;
+    /** Close the test client and clean up resources */
+    close(): Promise<void>;
+}
+/**
+ * Test client with transport clients attached.
+ * Each transport is accessible by its configured name.
+ */
+export type TestClientWithTransports<TApp extends App<any>, TTransports extends Record<string, TestTransport<any, any>>> = TestClient<TApp> & {
+    [K in keyof TTransports]: TransportClient<TTransports[K]>;
+};
+/**
+ * Options for creating a test client.
+ */
+export interface TestClientOptions<TTransports extends Record<string, TestTransport<any, any>> = {}> {
+    /** Named transports to use */
+    transports?: TTransports;
+    /** Options passed to each transport (keyed by transport name) */
+    transportOptions?: {
+        [K in keyof TTransports]?: TransportOptions<TTransports[K]>;
+    };
+}
+/**
+ * Create a test client for testing JustScale applications.
+ *
+ * @example Without transports (services only)
+ * ```typescript
+ * const client = await createTestClient(app);
+ * const { game } = await client.services({ game: GameService });
+ * ```
+ *
+ * @example With HTTP transport
+ * ```typescript
+ * import { httpTransport } from '@justscale/http/testing';
+ *
+ * const client = await createTestClient(app, {
+ *   transports: { http: httpTransport },
+ *   transportOptions: { http: { port: 0 } }
+ * });
+ *
+ * // Access typed controllers via HTTP
+ * const { api } = client.http.useControllers({ player: PlayersController });
+ * await api.player.list();
+ *
+ * // Raw HTTP calls
+ * await client.http.get('/health');
+ * ```
+ */
+export declare function createTestClient<TApp extends App<any>, TTransports extends Record<string, TestTransport<any, any>> = {}>(app: TApp, options?: TestClientOptions<TTransports>): Promise<TestClientWithTransports<TApp, TTransports>>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,122 @@
+/**
+ * Test Client
+ *
+ * Provides a base test client for testing JustScale applications.
+ * Transport-specific functionality (HTTP, CLI, etc.) is added via explicit
+ * transport configuration.
+ */
+import { Lifecycle, AbstractLockProvider, AbstractChannelBackend } from '@justscale/core';
+/**
+ * Drain an app's background work without going through BuiltApp.stop().
+ * Tests use `JustScale().add(...).build().compile()` which returns the
+ * raw App (no stop method); we replicate the kernel's teardown order so
+ * the event loop drains and the test process can exit cleanly.
+ *
+ * Use this in tests that build an app directly (no TestClient) to avoid
+ * the "Promise resolution still pending" file-level timeout.
+ */
+export async function teardownApp(app) {
+    try {
+        const lifecycle = await app.container.resolve(Lifecycle);
+        if (lifecycle && typeof lifecycle.runHook === 'function') {
+            await lifecycle.runHook('stop');
+        }
+    }
+    catch {
+        // Lifecycle not registered — nothing to drain at this layer.
+    }
+    for (const token of [AbstractLockProvider, AbstractChannelBackend]) {
+        try {
+            const svc = await app.container.resolve(token);
+            if (svc && typeof svc.close === 'function')
+                await svc.close();
+        }
+        catch {
+            // Provider not registered — skip.
+        }
+    }
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Create a test client for testing JustScale applications.
+ *
+ * @example Without transports (services only)
+ * ```typescript
+ * const client = await createTestClient(app);
+ * const { game } = await client.services({ game: GameService });
+ * ```
+ *
+ * @example With HTTP transport
+ * ```typescript
+ * import { httpTransport } from '@justscale/http/testing';
+ *
+ * const client = await createTestClient(app, {
+ *   transports: { http: httpTransport },
+ *   transportOptions: { http: { port: 0 } }
+ * });
+ *
+ * // Access typed controllers via HTTP
+ * const { api } = client.http.useControllers({ player: PlayersController });
+ * await api.player.list();
+ *
+ * // Raw HTTP calls
+ * await client.http.get('/health');
+ * ```
+ */
+export async function createTestClient(app, options = {}) {
+    const state = {
+        app,
+        cleanupFns: [],
+    };
+    const transports = options.transports ?? {};
+    const transportOptions = options.transportOptions ?? {};
+    const transportClients = {};
+    // Set up each transport
+    for (const [name, transport] of Object.entries(transports)) {
+        const opts = transportOptions[name];
+        const transportClient = await transport.setup(state, opts);
+        transportClients[name] = transportClient;
+        // Register cleanup if transport has it
+        if (transport.cleanup) {
+            const cleanup = transport.cleanup.bind(transport, transportClient);
+            state.cleanupFns.push(cleanup);
+        }
+    }
+    const client = {
+        async services(mapping) {
+            const services = {};
+            for (const [name, serviceDef] of Object.entries(mapping)) {
+                services[name] = await app.container.resolve(serviceDef);
+            }
+            return services;
+        },
+        async close() {
+            // Run transport cleanups first (close listening sockets, etc.)
+            for (const cleanup of state.cleanupFns.reverse()) {
+                await cleanup();
+            }
+            // Then stop the app — runs lifecycle stop hooks, drains channels,
+            // releases lock-provider connections, stops durable processes.
+            // Without this, every test leaks an app's worth of background
+            // work; node:test's harness then waits for the event loop to
+            // drain and reports "Promise resolution still pending" at the
+            // file level.
+            // Drain the app's background work. compile() returns App (no stop)
+            // — we replicate the kernel teardown sequence inline:
+            //   1. lifecycle stop hooks (cancels durable-process timers, etc.)
+            //   2. close the lock provider (clears TTL setTimeouts)
+            //   3. close the channel backend (closes pubsub LISTEN connection)
+            // Without this, every test leaves an app's worth of timers and
+            // connections holding the event loop open; node:test waits up to
+            // its file-level timeout and reports "Promise resolution still
+            // pending" even though the assertions all passed.
+            await teardownApp(app);
+        },
+        // Spread transport clients
+        ...transportClients,
+    };
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/conformance/cluster-primitives.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Adapter conformance suite - cluster primitives.
+ *
+ * Every cluster-capable adapter (Postgres, Redis, future) must pass this
+ * suite to claim conformance. Shape follows the well-trod JDBC/ODBC
+ * pattern: one abstract spec, multiple concrete runners.
+ *
+ * ## How to use
+ *
+ * ```typescript
+ * import { describeClusterConformance } from '@justscale/testing/conformance';
+ * import { PostgresFeature, PostgresChannelFeature, PostgresLockFeature,
+ *          PostgresProcessFeature } from '@justscale/postgres';
+ *
+ * describeClusterConformance('postgres (real docker pg)', {
+ *   makeInstance: () => JustScale()
+ *     .add(env)
+ *     .add(PostgresFeature)
+ *     .add(PostgresChannelFeature)
+ *     .add(PostgresLockFeature)
+ *     .add(PostgresProcessFeature),
+ *   skipIfUnavailable: async () => !(await hasDockerPg()),
+ * });
+ * ```
+ *
+ * ## What it asserts
+ *
+ * 1. Channel pub/sub cross-instance - publish on A, subscribe on B, B receives within 500ms.
+ * 2. Channel isolation - channels keyed differently don't cross-talk.
+ * 3. Lock mutex - two instances racing for the same advisory lock, only one wins; release lets the other acquire.
+ * 4. Lock hand-off - kill lock-holder, another instance picks it up.
+ * 5. Process signal resume - process suspended at race(), signal fires, process wakes and advances pc.
+ * 6. Process cross-instance signal - process running on A, emit from B, A resumes.
+ * 7. Process advisory lock - spawn same process path on two instances, only one runs.
+ *
+ * Each scenario is scoped tight enough to pinpoint the failing primitive.
+ */
+import type JustScale from '@justscale/core';
+/** The builder shape returned by `JustScale()`. */
+type JustScaleBuilder = ReturnType<typeof JustScale>;
+export interface ClusterConformanceOptions {
+    /**
+     * Factory that produces a fresh JustScale builder wired to the adapter
+     * under test. Called per scenario (and per instance within scenarios
+     * that need multiple). Must be totally independent - no shared state
+     * between calls beyond the adapter's natural backend (e.g. the same
+     * Postgres database, the same Redis instance).
+     */
+    makeInstance: (instanceId: number) => JustScaleBuilder | Promise<JustScaleBuilder>;
+    /**
+     * Optional: skip the whole suite if the adapter isn't available in the
+     * current environment. For pg this means "docker compose up -d"; for
+     * redis similar. Return true to skip, false to run.
+     */
+    skipIfUnavailable?: () => boolean | Promise<boolean>;
+    /**
+     * Optional: called once before any scenario to prepare the backend
+     * (e.g., create the test database + run migrations). Runs outside any
+     * instance factory.
+     */
+    beforeAll?: () => Promise<void>;
+    /**
+     * Optional: called once after all scenarios finish.
+     */
+    afterAll?: () => Promise<void>;
+}
+/**
+ * Run the cluster conformance suite against an adapter.
+ *
+ * @param adapterName - Shows up in test output: "cluster-conformance/postgres"
+ * @param opts - How to spin up instances + setup/teardown hooks
+ */
+export declare function describeClusterConformance(adapterName: string, opts: ClusterConformanceOptions): void;
+export {};
+//# sourceMappingURL=cluster-primitives.d.ts.map

package/dist/conformance/cluster-primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-primitives.d.ts","sourceRoot":"","sources":["../../src/conformance/cluster-primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,SAAS,MAAM,iBAAiB,CAAC;AAE7C,mDAAmD;AACnD,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAErD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEnF;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,yBAAyB,GAC9B,IAAI,CAON"}