@syncular/testkit 0.1.2 → 0.2.0

package/dist/faults.d.ts

@@ -1,52 +1,54 @@
-import type { SyncCombinedRequest, SyncPullResponse, SyncPushBatchResponse, SyncTransport } from '@syncular/core';
-export type FaultTransportOperation = 'push' | 'pull' | 'fetch';
-export type FaultTransportAction = 'pass' | 'fail';
-export type FaultTransportPhase = 'before' | 'after';
-export interface FaultPlanStep {
-    operation: FaultTransportOperation | 'any';
-    action?: FaultTransportAction;
-    phase?: FaultTransportPhase;
-    repeat?: number;
-    failWith?: Error;
-    latencyMs?: number;
+/**
+ * Fault injection at the transport seam (test doctrine, REVISE B4).
+ *
+ * Canonical home: the PUBLIC app test kit. The private conformance harness
+ * re-exports from here so both arm the SAME fault vocabulary — one
+ * implementation, publishable dependency direction (testkit ships to npm;
+ * conformance stays private).
+ *
+ * The harness owns the loopback between a ClientInstance and a
+ * ServerInstance; scenarios arm faults on this controller and the next
+ * matching exchange misbehaves — deterministically, with no timers. The
+ * only randomness is the truncation offset, drawn from a seeded PRNG so
+ * every run of a scenario byte-truncates at the same place.
+ *
+ * Fault vocabulary (§2.3, §1.4, §5.1):
+ * - drop request     — the request never reaches the server;
+ * - drop response    — the server processed it, the ack is lost;
+ * - duplicate        — the request is delivered twice (replayed bytes);
+ * - truncate         — the response is cut short (decode-error surfacing);
+ * - segment faults   — the same, at the segment download hop.
+ */
+/** Deterministic PRNG (mulberry32) — seeded per scenario. */
+export declare function seededRandom(seed: number): () => number;
+export declare function seedFromName(name: string): number;
+/** The error a faulted transport rejects with (client-observable). */
+export declare class TransportFault extends Error {
+    readonly name = "TransportFault";
+    /** Client drivers surface transport losses under this code. */
+    readonly code = "transport.lost";
 }
-export interface FaultTransportOptions {
-    failAfter?: number;
-    failWith?: Error;
-    latencyMs?: number;
-    flaky?: number;
-    failOnPush?: boolean;
-    failOnPull?: boolean;
-    failOnFetch?: boolean;
-    plan?: FaultPlanStep[];
-    onFail?: (operation: 'push' | 'pull' | 'fetch', error: Error) => void;
-    onSuccess?: (operation: 'push' | 'pull' | 'fetch') => void;
+export declare class TransportFaults {
+    #private;
+    /** Fail the next N sync requests before they reach the server. */
+    dropNextRequests: number;
+    /** Deliver the next N sync requests, then lose their responses. */
+    dropNextResponses: number;
+    /** Deliver the next sync request twice; return the second response. */
+    duplicateNextRequest: boolean;
+    /** Truncate the next sync response at a seeded offset. */
+    truncateNextResponse: boolean;
+    /** Fail the next N segment downloads before they reach the server. */
+    dropNextSegmentRequests: number;
+    /** Truncate the next segment download at a seeded offset. */
+    truncateNextSegmentDownload: boolean;
+    /** Fail the next N signed-URL fetches (the CDN hop, §5.4). */
+    dropNextUrlFetches: number;
+    /** Corrupt the next signed-URL fetch's bytes (§5.1 tamper). */
+    corruptNextUrlFetch: boolean;
+    constructor(random: () => number);
+    /** Seeded cut point: at least 1 byte kept, at least 1 byte removed. */
+    truncate(bytes: Uint8Array): Uint8Array;
+    /** Flip one seeded byte — same length, different content address. */
+    corrupt(bytes: Uint8Array): Uint8Array;
 }
-export interface FaultTransportState {
-    pushCount: number;
-    pullCount: number;
-    fetchCount: number;
-    failureCount: number;
-}
-export interface FaultTransportResult {
-    transport: SyncTransport;
-    getState: () => FaultTransportState;
-    reset: () => void;
-    setOptions: (options: Partial<FaultTransportOptions>) => void;
-}
-export declare function withFaults(baseTransport: SyncTransport, options?: FaultTransportOptions): FaultTransportResult;
-export declare function createMockTransport(options?: {
-    pullResponse?: SyncPullResponse;
-    pushResponse?: SyncPushBatchResponse;
-    chunkData?: Uint8Array;
-}): SyncTransport;
-export interface RecordingTransportResult {
-    transport: SyncTransport;
-    syncRequests: SyncCombinedRequest[];
-    fetchRequests: {
-        chunkId: string;
-    }[];
-    clear: () => void;
-}
-export declare function withRecording(baseTransport: SyncTransport): RecordingTransportResult;
-//# sourceMappingURL=faults.d.ts.map

package/dist/faults.js

@@ -1,198 +1,80 @@
-export function withFaults(baseTransport, options = {}) {
-    let currentOptions = { ...options };
-    let currentPlan = createActivePlan(currentOptions.plan);
-    const state = {
-        pushCount: 0,
-        pullCount: 0,
-        fetchCount: 0,
-        failureCount: 0,
-    };
-    const defaultError = new Error('Simulated transport error');
-    const maybeDelay = async (extraLatencyMs = 0) => {
-        const latencyMs = (currentOptions.latencyMs ?? 0) + extraLatencyMs;
-        if (latencyMs > 0) {
-            await new Promise((resolve) => setTimeout(resolve, latencyMs));
-        }
-    };
-    const shouldTargetOperation = (operation) => {
-        const hasTargets = currentOptions.failOnPush === true ||
-            currentOptions.failOnPull === true ||
-            currentOptions.failOnFetch === true;
-        if (!hasTargets) {
-            return true;
-        }
-        if (operation === 'push') {
-            return currentOptions.failOnPush === true;
-        }
-        if (operation === 'pull') {
-            return currentOptions.failOnPull === true;
-        }
-        return currentOptions.failOnFetch === true;
-    };
-    const shouldFail = (operation, count) => {
-        if (!shouldTargetOperation(operation)) {
-            return false;
-        }
-        if (currentOptions.failAfter !== undefined &&
-            count >= currentOptions.failAfter) {
-            return true;
-        }
-        if (currentOptions.flaky !== undefined && currentOptions.flaky > 0) {
-            return Math.random() < currentOptions.flaky;
-        }
-        return false;
-    };
-    const getError = () => currentOptions.failWith ?? defaultError;
-    const fail = (operation, error) => {
-        state.failureCount++;
-        currentOptions.onFail?.(operation, error);
-        throw error;
-    };
-    const recordSuccess = (operation) => {
-        if (operation === 'push') {
-            state.pushCount++;
-            return;
-        }
-        if (operation === 'pull') {
-            state.pullCount++;
-            return;
-        }
-        state.fetchCount++;
-    };
-    const takePlannedDecision = (operation) => {
-        const step = currentPlan.find((candidate) => candidate.remaining > 0 &&
-            (candidate.operation === 'any' || candidate.operation === operation));
-        if (!step) {
-            return null;
-        }
-        step.remaining -= 1;
-        return {
-            action: step.action,
-            phase: step.phase,
-            error: step.failWith ?? getError(),
-            latencyMs: step.latencyMs ?? 0,
-        };
-    };
-    const runWithFaults = async (operation, count, run) => {
-        const plannedDecision = takePlannedDecision(operation);
-        await maybeDelay(plannedDecision?.latencyMs ?? 0);
-        if (plannedDecision?.action === 'fail' &&
-            plannedDecision.phase === 'before') {
-            return fail(operation, plannedDecision.error);
-        }
-        if (!plannedDecision && shouldFail(operation, count)) {
-            return fail(operation, getError());
-        }
-        const result = await run();
-        recordSuccess(operation);
-        if (plannedDecision?.action === 'fail' &&
-            plannedDecision.phase === 'after') {
-            return fail(operation, plannedDecision.error);
-        }
-        currentOptions.onSuccess?.(operation);
-        return result;
-    };
-    const transport = {
-        async sync(request, transportOptions) {
-            const operation = request.push ? 'push' : 'pull';
-            const count = operation === 'push' ? state.pushCount : state.pullCount;
-            return runWithFaults(operation, count, () => baseTransport.sync(request, transportOptions));
-        },
-        async fetchSnapshotChunk(request, transportOptions) {
-            return runWithFaults('fetch', state.fetchCount, () => baseTransport.fetchSnapshotChunk(request, transportOptions));
-        },
-    };
-    return {
-        transport,
-        getState: () => ({ ...state }),
-        reset: () => {
-            state.pushCount = 0;
-            state.pullCount = 0;
-            state.fetchCount = 0;
-            state.failureCount = 0;
-            currentPlan = createActivePlan(currentOptions.plan);
-        },
-        setOptions: (newOptions) => {
-            currentOptions = { ...currentOptions, ...newOptions };
-            if ('plan' in newOptions) {
-                currentPlan = createActivePlan(currentOptions.plan);
-            }
-        },
+/**
+ * Fault injection at the transport seam (test doctrine, REVISE B4).
+ *
+ * Canonical home: the PUBLIC app test kit. The private conformance harness
+ * re-exports from here so both arm the SAME fault vocabulary — one
+ * implementation, publishable dependency direction (testkit ships to npm;
+ * conformance stays private).
+ *
+ * The harness owns the loopback between a ClientInstance and a
+ * ServerInstance; scenarios arm faults on this controller and the next
+ * matching exchange misbehaves — deterministically, with no timers. The
+ * only randomness is the truncation offset, drawn from a seeded PRNG so
+ * every run of a scenario byte-truncates at the same place.
+ *
+ * Fault vocabulary (§2.3, §1.4, §5.1):
+ * - drop request     — the request never reaches the server;
+ * - drop response    — the server processed it, the ack is lost;
+ * - duplicate        — the request is delivered twice (replayed bytes);
+ * - truncate         — the response is cut short (decode-error surfacing);
+ * - segment faults   — the same, at the segment download hop.
+ */
+/** Deterministic PRNG (mulberry32) — seeded per scenario. */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
-function createActivePlan(plan) {
-    if (!plan || plan.length === 0) {
-        return [];
+export function seedFromName(name) {
+    let hash = 2166136261;
+    for (let i = 0; i < name.length; i++) {
+        hash ^= name.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
     }
-    return plan.flatMap((step) => {
-        const remaining = step.repeat ?? 1;
-        if (remaining <= 0) {
-            return [];
-        }
-        return [
-            {
-                operation: step.operation,
-                action: step.action ?? 'fail',
-                phase: step.phase ?? 'before',
-                remaining,
-                failWith: step.failWith,
-                latencyMs: step.latencyMs,
-            },
-        ];
-    });
+    return hash >>> 0;
 }
-export function createMockTransport(options) {
-    return {
-        async sync(request) {
-            const result = { ok: true };
-            if (request.push) {
-                result.push = options?.pushResponse ?? {
-                    ok: true,
-                    commits: request.push.commits.map((commit) => ({
-                        ok: true,
-                        clientCommitId: commit.clientCommitId,
-                        status: 'applied',
-                        results: commit.operations.map((_, i) => ({
-                            opIndex: i,
-                            status: 'applied',
-                        })),
-                    })),
-                };
-            }
-            if (request.pull) {
-                result.pull = options?.pullResponse ?? {
-                    ok: true,
-                    subscriptions: [],
-                };
-            }
-            return result;
-        },
-        async fetchSnapshotChunk() {
-            return options?.chunkData ?? new Uint8Array();
-        },
-    };
+/** The error a faulted transport rejects with (client-observable). */
+export class TransportFault extends Error {
+    name = 'TransportFault';
+    /** Client drivers surface transport losses under this code. */
+    code = 'transport.lost';
 }
-export function withRecording(baseTransport) {
-    const syncRequests = [];
-    const fetchRequests = [];
-    const transport = {
-        async sync(request, options) {
-            syncRequests.push(structuredClone(request));
-            return baseTransport.sync(request, options);
-        },
-        async fetchSnapshotChunk(request, options) {
-            fetchRequests.push({ ...request });
-            return baseTransport.fetchSnapshotChunk(request, options);
-        },
-    };
-    return {
-        transport,
-        syncRequests,
-        fetchRequests,
-        clear: () => {
-            syncRequests.length = 0;
-            fetchRequests.length = 0;
-        },
-    };
+export class TransportFaults {
+    /** Fail the next N sync requests before they reach the server. */
+    dropNextRequests = 0;
+    /** Deliver the next N sync requests, then lose their responses. */
+    dropNextResponses = 0;
+    /** Deliver the next sync request twice; return the second response. */
+    duplicateNextRequest = false;
+    /** Truncate the next sync response at a seeded offset. */
+    truncateNextResponse = false;
+    /** Fail the next N segment downloads before they reach the server. */
+    dropNextSegmentRequests = 0;
+    /** Truncate the next segment download at a seeded offset. */
+    truncateNextSegmentDownload = false;
+    /** Fail the next N signed-URL fetches (the CDN hop, §5.4). */
+    dropNextUrlFetches = 0;
+    /** Corrupt the next signed-URL fetch's bytes (§5.1 tamper). */
+    corruptNextUrlFetch = false;
+    #random;
+    constructor(random) {
+        this.#random = random;
+    }
+    /** Seeded cut point: at least 1 byte kept, at least 1 byte removed. */
+    truncate(bytes) {
+        const cut = 1 + Math.floor(this.#random() * (bytes.length - 1));
+        return bytes.slice(0, cut);
+    }
+    /** Flip one seeded byte — same length, different content address. */
+    corrupt(bytes) {
+        const out = bytes.slice();
+        const index = Math.floor(this.#random() * out.length);
+        out[index] = (out[index] ?? 0) ^ 0xff;
+        return out;
+    }
 }
-//# sourceMappingURL=faults.js.map

package/dist/index.d.ts

@@ -1,15 +1,17 @@
-export * from './audit';
-export * from './client-bridge';
-export * from './deterministic';
-export * from './disposable';
-export * from './faults';
-export * from './hono-node-server';
-export * from './http-fixtures';
-export * from './project-scoped-tasks';
-export * from './realtime-ws';
-export * from './runtime-process';
-export * from './sync-builders';
-export * from './sync-http';
-export * from './sync-parse';
-export * from './sync-response';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @syncular/testkit — the app-developer test kit (TODO §2).
+ *
+ * A small, documented surface over the shipped Syncular core: an in-memory
+ * server, N real clients on bun:sqlite through an in-process loopback (no
+ * HTTP), a shared virtual clock, per-client offline/online, and the
+ * conformance harness's transport-fault vocabulary. Designed for APP tests
+ * (readable, minimal) — not conformance (no driver/pairing machinery).
+ *
+ * The React helper lives behind `@syncular/testkit/react` so the core
+ * pulls in no React. See README.md for paste-ready examples.
+ */
+export type { TestClient, TestClientOptions, } from './client.js';
+export { createVirtualClock, DEFAULT_EPOCH_MS, type VirtualClock, } from './clock.js';
+export { type CreateTestSyncOptions, createTestSync, type TestClientOverrides, type TestSync, } from './create-test-sync.js';
+export { seededRandom, seedFromName, TransportFault, TransportFaults, } from './faults.js';
+export { allowAllScopes, createTestServer, DEFAULT_ACTOR, DEFAULT_PARTITION, type TestServer, type TestServerOptions, } from './server.js';

package/dist/index.js

@@ -1,15 +1,18 @@
-export * from './audit.js';
-export * from './client-bridge.js';
-export * from './deterministic.js';
-export * from './disposable.js';
-export * from './faults.js';
-export * from './hono-node-server.js';
-export * from './http-fixtures.js';
-export * from './project-scoped-tasks.js';
-export * from './realtime-ws.js';
-export * from './runtime-process.js';
-export * from './sync-builders.js';
-export * from './sync-http.js';
-export * from './sync-parse.js';
-export * from './sync-response.js';
-//# sourceMappingURL=index.js.map
+/**
+ * @syncular/testkit — the app-developer test kit (TODO §2).
+ *
+ * A small, documented surface over the shipped Syncular core: an in-memory
+ * server, N real clients on bun:sqlite through an in-process loopback (no
+ * HTTP), a shared virtual clock, per-client offline/online, and the
+ * conformance harness's transport-fault vocabulary. Designed for APP tests
+ * (readable, minimal) — not conformance (no driver/pairing machinery).
+ *
+ * The React helper lives behind `@syncular/testkit/react` so the core
+ * pulls in no React. See README.md for paste-ready examples.
+ */
+export { createVirtualClock, DEFAULT_EPOCH_MS, } from './clock.js';
+export { createTestSync, } from './create-test-sync.js';
+// The transport-fault controller, re-exported from the conformance harness
+// (never duplicated) — the SAME vocabulary the reference pairing arms.
+export { seededRandom, seedFromName, TransportFault, TransportFaults, } from './faults.js';
+export { allowAllScopes, createTestServer, DEFAULT_ACTOR, DEFAULT_PARTITION, } from './server.js';

package/dist/react.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { TestClient } from './client.js';
+/**
+ * Build the `wrapper` component `renderHook` / `render` take, providing the
+ * given test client to the Syncular hook tree. Pass a `TestClient` — its
+ * `.api` (the real `SyncClient`) is supplied to `SyncProvider`.
+ */
+export declare function syncWrapper(client: TestClient): (props: {
+    children: ReactNode;
+}) => ReactNode;

package/dist/react.js

@@ -0,0 +1,41 @@
+/**
+ * React helper for the test kit (`@syncular/testkit/react`).
+ *
+ * `@syncular/react`'s `SyncProvider` already accepts any `SyncClient`, so
+ * mounting hooks against a test client is just:
+ *
+ *     <SyncProvider client={testClient.api}>…</SyncProvider>
+ *
+ * This module is the tiny convenience over that pattern: `syncWrapper`
+ * returns the `wrapper` prop `@testing-library/react`'s `renderHook` /
+ * `render` want, so a test never hand-writes the provider element.
+ *
+ *     import { renderHook, waitFor } from '@testing-library/react';
+ *     import { useSyncQuery } from '@syncular/react';
+ *     import { createTestSync } from '@syncular/testkit';
+ *     import { syncWrapper } from '@syncular/testkit/react';
+ *
+ *     const sync = await createTestSync({ schema });
+ *     const client = await sync.client('a');
+ *     const { result } = renderHook(
+ *       () => useSyncQuery('SELECT * FROM notes'),
+ *       { wrapper: syncWrapper(client) },
+ *     );
+ *
+ * `react` is an OPTIONAL peer of the kit: import this subpath only from a
+ * test that already depends on React. The core (`@syncular/testkit`)
+ * pulls in no React.
+ *
+ * NOTE: this file uses `createElement` (no JSX) so the kit typechecks under
+ * the repo's `.ts`-only root tsconfig — same posture as `SyncProvider`.
+ */
+import { SyncProvider } from '@syncular/react';
+import { createElement } from 'react';
+/**
+ * Build the `wrapper` component `renderHook` / `render` take, providing the
+ * given test client to the Syncular hook tree. Pass a `TestClient` — its
+ * `.api` (the real `SyncClient`) is supplied to `SyncProvider`.
+ */
+export function syncWrapper(client) {
+    return ({ children }) => createElement(SyncProvider, { client: client.api }, children);
+}

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The in-memory test server: one `SqliteServerStorage` (`:memory:`), a
+ * `MemorySegmentStore`, and a `RealtimeHub`, all sharing the test's virtual
+ * clock. It is the SHIPPED `@syncular/server` core — the kit adds no
+ * server logic, it only wires the pieces an app would wire in production
+ * (minus the HTTP adapter). Clients reach it through the loopback seam in
+ * `client.ts`, calling `handleSyncRequest` / `handleSegmentDownload`
+ * directly.
+ */
+import { type ClientSchema } from '@syncular/client';
+import { MemorySegmentStore, type RealtimeHub, type ResolveScopes, SqliteServerStorage, type SyncRequestContext } from '@syncular/server';
+import type { VirtualClock } from './clock.js';
+/** Default partition every actor lives in (apps override via options). */
+export declare const DEFAULT_PARTITION = "test";
+/** Default actor a client is bound to when none is given. */
+export declare const DEFAULT_ACTOR = "test-actor";
+/**
+ * `resolveScopes` that grants every value (`'*'`) for every scope variable
+ * the schema declares — the "no authorization, just make it converge"
+ * default an app test wants. Override with your own resolver to exercise
+ * scope-scoping / revocation.
+ */
+export declare function allowAllScopes(schema: ClientSchema): ResolveScopes;
+export interface TestServerOptions {
+    readonly schema: ClientSchema;
+    readonly clock: VirtualClock;
+    readonly partition: string;
+    /** Defaults to {@link allowAllScopes}. */
+    readonly resolveScopes?: ResolveScopes;
+}
+/**
+ * The server half of a test sync. `ctxFor(actorId)` builds the per-request
+ * context the loopback transport feeds `handleSyncRequest`; `hub` is the
+ * realtime fanout every client's socket attaches to.
+ */
+export interface TestServer {
+    readonly storage: SqliteServerStorage;
+    readonly segments: MemorySegmentStore;
+    readonly hub: RealtimeHub;
+    readonly partition: string;
+    ctxFor(actorId: string): SyncRequestContext;
+    close(): void;
+}
+export declare function createTestServer(options: TestServerOptions): TestServer;

package/dist/server.js

@@ -0,0 +1,68 @@
+/**
+ * The in-memory test server: one `SqliteServerStorage` (`:memory:`), a
+ * `MemorySegmentStore`, and a `RealtimeHub`, all sharing the test's virtual
+ * clock. It is the SHIPPED `@syncular/server` core — the kit adds no
+ * server logic, it only wires the pieces an app would wire in production
+ * (minus the HTTP adapter). Clients reach it through the loopback seam in
+ * `client.ts`, calling `handleSyncRequest` / `handleSegmentDownload`
+ * directly.
+ */
+import { compileClientSchema } from '@syncular/client';
+import { createRealtimeHub, MemorySegmentStore, SqliteServerStorage, } from '@syncular/server';
+/** Default partition every actor lives in (apps override via options). */
+export const DEFAULT_PARTITION = 'test';
+/** Default actor a client is bound to when none is given. */
+export const DEFAULT_ACTOR = 'test-actor';
+/**
+ * `resolveScopes` that grants every value (`'*'`) for every scope variable
+ * the schema declares — the "no authorization, just make it converge"
+ * default an app test wants. Override with your own resolver to exercise
+ * scope-scoping / revocation.
+ */
+export function allowAllScopes(schema) {
+    const compiled = compileClientSchema(schema);
+    const variables = new Set();
+    for (const table of compiled.tables.values()) {
+        for (const variable of table.scopeColumnByVariable.keys()) {
+            variables.add(variable);
+        }
+    }
+    const allowed = {};
+    for (const variable of variables)
+        allowed[variable] = ['*'];
+    return () => allowed;
+}
+export function createTestServer(options) {
+    const { schema, clock, partition } = options;
+    const serverSchema = schema;
+    const storage = new SqliteServerStorage();
+    const segments = new MemorySegmentStore();
+    const resolveScopes = options.resolveScopes ?? allowAllScopes(schema);
+    const clockFn = () => clock.now();
+    const hub = createRealtimeHub({
+        schema: serverSchema,
+        storage,
+        resolveScopes,
+        clock: clockFn,
+        segments,
+    });
+    return {
+        storage,
+        segments,
+        hub,
+        partition,
+        ctxFor: (actorId) => ({
+            partition,
+            actorId,
+            schema: serverSchema,
+            storage,
+            segments,
+            resolveScopes,
+            clock: clockFn,
+            realtime: hub,
+        }),
+        close: () => {
+            storage.db.close();
+        },
+    };
+}