@smthrs/sync 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/internal/SnapshotBoundary.js

@@ -0,0 +1,68 @@
+/** Snapshot validation shared by the hosted and browser-side boundaries.
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { SyncError } from "../SyncError.js";
+import * as Protocol from "../SyncProtocol.js";
+import { causeCode } from "./CauseText.js";
+import { requireVersion } from "./ProtocolVersion.js";
+/** Decode a detached request before callbacks can mutate its expected identity.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const request = (value) => Effect.try({
+    try: () => Schema.decodeUnknownSync(Protocol.SnapshotRequest)(value, { onExcessProperty: "error" }),
+    catch: (cause) => new SyncError({ code: "invalid_request", message: "Invalid public snapshot request", cause: causeCode(cause) })
+}).pipe(
+// The schema admits any integer version so this refusal, not a decode
+// failure, is what a version mismatch produces here as on every other RPC.
+Effect.tap((decoded) => requireVersion(decoded.protocolVersion)), Effect.map((decoded) => ({ ...decoded })));
+/** Copy JSON bytes once, bound them, then check the exact requested projection.
+ * @category validation
+ * @since 1.0.0-rc.0
+ */
+export const response = (expected, value, maxBytes) => Effect.gen(function* () {
+    const text = yield* Effect.try({
+        try: () => JSON.stringify(value),
+        catch: (cause) => new SyncError({
+            code: "decode_failed",
+            message: "Public snapshot is not JSON encodable",
+            cause: causeCode(cause)
+        })
+    });
+    if (text === undefined) {
+        return yield* Effect.fail(new SyncError({ code: "decode_failed", message: "Public snapshot is missing", cause: "undefined" }));
+    }
+    if (new TextEncoder().encode(text).length > maxBytes) {
+        return yield* Effect.fail(new SyncError({ code: "frame_too_large", message: "Public snapshot exceeds the response byte limit" }));
+    }
+    const snapshot = yield* Effect.try({
+        try: () => {
+            // JSON.stringify alone silently drops undefined/functions and turns
+            // non-finite numbers into null. Reject such provider values rather than
+            // returning a different state under the same checkpoint sequence.
+            Schema.decodeUnknownSync(Protocol.Snapshot)(value, { onExcessProperty: "error" });
+            return Schema.decodeUnknownSync(Protocol.Snapshot)(JSON.parse(text), { onExcessProperty: "error" });
+        },
+        catch: (cause) => new SyncError({ code: "decode_failed", message: "Invalid public snapshot response", cause: causeCode(cause) })
+    });
+    yield* requireVersion(snapshot.protocolVersion);
+    if (snapshot.runId !== expected.runId || snapshot.lineageId !== expected.lineageId ||
+        snapshot.projection !== expected.projection || snapshot.projectionVersion !== expected.projectionVersion) {
+        return yield* Effect.fail(new SyncError({
+            code: "protocol_violation",
+            message: "Public snapshot identity does not match the request",
+            cause: "snapshot_identity_mismatch"
+        }));
+    }
+    if (snapshot.seq < expected.atLeastSeq) {
+        return yield* Effect.fail(new SyncError({
+            code: "compacted",
+            message: "Public snapshot does not cover the required history",
+            resync: { runId: expected.runId, checkpointSeq: expected.atLeastSeq }
+        }));
+    }
+    return snapshot;
+});
+//# sourceMappingURL=SnapshotBoundary.js.map

package/dist/esm/internal/SnapshotBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotBoundary.js","sourceRoot":"","sources":["../../../src/internal/SnapshotBoundary.ts"],"names":[],"mappings":"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","sourcesContent":["/** Snapshot validation shared by the hosted and browser-side boundaries.\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport { SyncError } from \"../SyncError.ts\"\nimport * as Protocol from \"../SyncProtocol.ts\"\nimport { causeCode } from \"./CauseText.ts\"\nimport { requireVersion } from \"./ProtocolVersion.ts\"\n\n/** Decode a detached request before callbacks can mutate its expected identity.\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const request = (value: unknown): Effect.Effect<Protocol.SnapshotRequest, SyncError> =>\n  Effect.try({\n    try: () => Schema.decodeUnknownSync(Protocol.SnapshotRequest)(value, { onExcessProperty: \"error\" }),\n    catch: (cause) =>\n      new SyncError({ code: \"invalid_request\", message: \"Invalid public snapshot request\", cause: causeCode(cause) })\n  }).pipe(\n    // The schema admits any integer version so this refusal, not a decode\n    // failure, is what a version mismatch produces here as on every other RPC.\n    Effect.tap((decoded) => requireVersion(decoded.protocolVersion)),\n    Effect.map((decoded) => ({ ...decoded }))\n  )\n\n/** Copy JSON bytes once, bound them, then check the exact requested projection.\n * @category validation\n * @since 1.0.0-rc.0\n */\nexport const response = (\n  expected: Protocol.SnapshotRequest,\n  value: unknown,\n  maxBytes: number\n): Effect.Effect<Protocol.Snapshot, SyncError> =>\n  Effect.gen(function*() {\n    const text = yield* Effect.try({\n      try: () => JSON.stringify(value),\n      catch: (cause) =>\n        new SyncError({\n          code: \"decode_failed\",\n          message: \"Public snapshot is not JSON encodable\",\n          cause: causeCode(cause)\n        })\n    })\n    if (text === undefined) {\n      return yield* Effect.fail(\n        new SyncError({ code: \"decode_failed\", message: \"Public snapshot is missing\", cause: \"undefined\" })\n      )\n    }\n    if (new TextEncoder().encode(text).length > maxBytes) {\n      return yield* Effect.fail(\n        new SyncError({ code: \"frame_too_large\", message: \"Public snapshot exceeds the response byte limit\" })\n      )\n    }\n    const snapshot = yield* Effect.try({\n      try: () => {\n        // JSON.stringify alone silently drops undefined/functions and turns\n        // non-finite numbers into null. Reject such provider values rather than\n        // returning a different state under the same checkpoint sequence.\n        Schema.decodeUnknownSync(Protocol.Snapshot)(value, { onExcessProperty: \"error\" })\n        return Schema.decodeUnknownSync(Protocol.Snapshot)(JSON.parse(text), { onExcessProperty: \"error\" })\n      },\n      catch: (cause) =>\n        new SyncError({ code: \"decode_failed\", message: \"Invalid public snapshot response\", cause: causeCode(cause) })\n    })\n    yield* requireVersion(snapshot.protocolVersion)\n    if (\n      snapshot.runId !== expected.runId || snapshot.lineageId !== expected.lineageId ||\n      snapshot.projection !== expected.projection || snapshot.projectionVersion !== expected.projectionVersion\n    ) {\n      return yield* Effect.fail(\n        new SyncError({\n          code: \"protocol_violation\",\n          message: \"Public snapshot identity does not match the request\",\n          cause: \"snapshot_identity_mismatch\"\n        })\n      )\n    }\n    if (snapshot.seq < expected.atLeastSeq) {\n      return yield* Effect.fail(\n        new SyncError({\n          code: \"compacted\",\n          message: \"Public snapshot does not cover the required history\",\n          resync: { runId: expected.runId, checkpointSeq: expected.atLeastSeq }\n        })\n      )\n    }\n    return snapshot\n  })\n"]}

package/dist/esm/test/TestSocket.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Deterministic in-memory socket transport for sync tests.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import * as Socket from "effect/unstable/socket/Socket";
+/**
+ * A predicate or byte transformation installed between the two socket ends.
+ * Returning `false` drops the frame.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type FrameFilter = (bytes: Uint8Array) => boolean | Uint8Array;
+/**
+ * Deterministic transport failures that can be injected into a test socket pair.
+ *
+ * `dropRange` recognizes the JSON representation of an `Entries` frame without
+ * importing the sync protocol. Tests using another wire representation can use
+ * `installFilter` directly.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface TestFaults {
+    readonly installFilter: (filter: FrameFilter) => void;
+    readonly dropRange: (runId: string, from: number, to: number) => void;
+    readonly stall: () => void;
+    readonly resume: () => void;
+    readonly disconnect: () => Effect.Effect<void>;
+}
+/**
+ * The two endpoints and controls of an in-memory socket connection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Pair {
+    readonly client: Socket.Socket;
+    readonly server: Socket.Socket;
+    readonly faults: TestFaults;
+}
+/**
+ * Creates a scoped, bounded, bidirectional in-memory socket connection.
+ *
+ * Socket runs wait on queue reads and are therefore interrupted with their
+ * enclosing scope; no host abort signal or timer is involved.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makePair: () => Effect.Effect<Pair, never, Scope.Scope>;
+//# sourceMappingURL=TestSocket.d.ts.map

package/dist/esm/test/TestSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestSocket.d.ts","sourceRoot":"","sources":["../../../src/test/TestSocket.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,+BAA+B,CAAA;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,GAAG,UAAU,CAAA;AAErE;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;IACrD,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AAkDD;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,QAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAkF9D,CAAA"}

package/dist/esm/test/TestSocket.js

@@ -0,0 +1,128 @@
+/**
+ * Deterministic in-memory socket transport for sync tests.
+ *
+ * @since 0.1.0
+ */
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Latch from "effect/Latch";
+import * as Queue from "effect/Queue";
+import * as Scope from "effect/Scope";
+import * as Socket from "effect/unstable/socket/Socket";
+const queueCapacity = 16;
+const transportError = () => new Socket.SocketError({
+    reason: new Socket.SocketReadError({ cause: new Error("test socket disconnected") })
+});
+const intersects = (leftFrom, leftTo, rightFrom, rightTo) => leftFrom <= rightTo && rightFrom <= leftTo;
+const entriesRange = (bytes) => {
+    try {
+        const value = JSON.parse(new TextDecoder().decode(bytes));
+        return findEntriesRange(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+const findEntriesRange = (value) => {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (record["_tag"] === "Entries" &&
+        typeof record["runId"] === "string" &&
+        typeof record["fromSeq"] === "number" &&
+        typeof record["toSeq"] === "number") {
+        return { runId: record["runId"], from: record["fromSeq"], to: record["toSeq"] };
+    }
+    for (const child of Object.values(record)) {
+        if (Array.isArray(child)) {
+            for (const element of child) {
+                const result = findEntriesRange(element);
+                if (result !== undefined)
+                    return result;
+            }
+        }
+        else {
+            const result = findEntriesRange(child);
+            if (result !== undefined)
+                return result;
+        }
+    }
+    return undefined;
+};
+/**
+ * Creates a scoped, bounded, bidirectional in-memory socket connection.
+ *
+ * Socket runs wait on queue reads and are therefore interrupted with their
+ * enclosing scope; no host abort signal or timer is involved.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makePair = () => Effect.gen(function* () {
+    const scope = yield* Effect.scope;
+    const clientIncoming = yield* Queue.bounded(queueCapacity);
+    const serverIncoming = yield* Queue.bounded(queueCapacity);
+    yield* Scope.addFinalizer(scope, Effect.all([Queue.shutdown(clientIncoming), Queue.shutdown(serverIncoming)], { discard: true }));
+    const delivery = Latch.makeUnsafe(true);
+    const filters = [];
+    const offer = (queue, bytes) => Effect.suspend(() => {
+        let current = bytes;
+        for (const filter of filters) {
+            const result = filter(current);
+            if (typeof result === "boolean") {
+                if (result === false)
+                    return Effect.void;
+            }
+            else {
+                current = result;
+            }
+        }
+        return Queue.offer(queue, current).pipe(Effect.asVoid);
+    });
+    const socket = (incoming, outgoing) => {
+        const write = (chunk) => {
+            if (Socket.isCloseEvent(chunk))
+                return Effect.void;
+            const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+            return offer(outgoing, bytes);
+        };
+        return Socket.make({
+            reader: Effect.gen(function* () {
+                const closed = yield* Deferred.make();
+                yield* Effect.addFinalizer(() => Deferred.fail(closed, transportError()));
+                return {
+                    pull: Effect.raceFirst(Effect.map(delivery.whenOpen(Queue.take(incoming)), (bytes) => [bytes]), Deferred.await(closed)),
+                    upgrade: Socket.SocketUpgradeError.unsupported
+                };
+            }),
+            writer: Effect.succeed({
+                write,
+                writeAll: (chunks) => Effect.forEach(chunks, write, { discard: true })
+            })
+        });
+    };
+    const faults = {
+        installFilter: (filter) => {
+            filters.push(filter);
+        },
+        dropRange: (runId, from, to) => {
+            filters.push((bytes) => {
+                const range = entriesRange(bytes);
+                return range === undefined || range.runId !== runId || !intersects(range.from, range.to, from, to);
+            });
+        },
+        stall: () => {
+            delivery.closeUnsafe();
+        },
+        resume: () => {
+            delivery.openUnsafe();
+        },
+        disconnect: () => Effect.andThen(Queue.fail(clientIncoming, transportError()), Queue.fail(serverIncoming, transportError())).pipe(Effect.asVoid)
+    };
+    return {
+        client: socket(clientIncoming, serverIncoming),
+        server: socket(serverIncoming, clientIncoming),
+        faults
+    };
+});
+//# sourceMappingURL=TestSocket.js.map

package/dist/esm/test/TestSocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestSocket.js","sourceRoot":"","sources":["../../../src/test/TestSocket.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic in-memory socket transport for sync tests.\n *\n * @since 0.1.0\n */\n\nimport * as Deferred from \"effect/Deferred\"\nimport * as Effect from \"effect/Effect\"\nimport * as Latch from \"effect/Latch\"\nimport * as Queue from \"effect/Queue\"\nimport * as Scope from \"effect/Scope\"\nimport * as Socket from \"effect/unstable/socket/Socket\"\n\n/**\n * A predicate or byte transformation installed between the two socket ends.\n * Returning `false` drops the frame.\n *\n * @category models\n * @since 0.1.0\n */\nexport type FrameFilter = (bytes: Uint8Array) => boolean | Uint8Array\n\n/**\n * Deterministic transport failures that can be injected into a test socket pair.\n *\n * `dropRange` recognizes the JSON representation of an `Entries` frame without\n * importing the sync protocol. Tests using another wire representation can use\n * `installFilter` directly.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface TestFaults {\n  readonly installFilter: (filter: FrameFilter) => void\n  readonly dropRange: (runId: string, from: number, to: number) => void\n  readonly stall: () => void\n  readonly resume: () => void\n  readonly disconnect: () => Effect.Effect<void>\n}\n\n/**\n * The two endpoints and controls of an in-memory socket connection.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Pair {\n  readonly client: Socket.Socket\n  readonly server: Socket.Socket\n  readonly faults: TestFaults\n}\n\nconst queueCapacity = 16\n\nconst transportError = () =>\n  new Socket.SocketError({\n    reason: new Socket.SocketReadError({ cause: new Error(\"test socket disconnected\") })\n  })\n\nconst intersects = (leftFrom: number, leftTo: number, rightFrom: number, rightTo: number) =>\n  leftFrom <= rightTo && rightFrom <= leftTo\n\nconst entriesRange = (\n  bytes: Uint8Array\n): { readonly runId: string; readonly from: number; readonly to: number } | undefined => {\n  try {\n    const value: unknown = JSON.parse(new TextDecoder().decode(bytes))\n    return findEntriesRange(value)\n  } catch {\n    return undefined\n  }\n}\n\nconst findEntriesRange = (\n  value: unknown\n): { readonly runId: string; readonly from: number; readonly to: number } | undefined => {\n  if (typeof value !== \"object\" || value === null) return undefined\n  const record = value as Readonly<Record<string, unknown>>\n  if (\n    record[\"_tag\"] === \"Entries\" &&\n    typeof record[\"runId\"] === \"string\" &&\n    typeof record[\"fromSeq\"] === \"number\" &&\n    typeof record[\"toSeq\"] === \"number\"\n  ) {\n    return { runId: record[\"runId\"], from: record[\"fromSeq\"], to: record[\"toSeq\"] }\n  }\n  for (const child of Object.values(record)) {\n    if (Array.isArray(child)) {\n      for (const element of child) {\n        const result = findEntriesRange(element)\n        if (result !== undefined) return result\n      }\n    } else {\n      const result = findEntriesRange(child)\n      if (result !== undefined) return result\n    }\n  }\n  return undefined\n}\n\n/**\n * Creates a scoped, bounded, bidirectional in-memory socket connection.\n *\n * Socket runs wait on queue reads and are therefore interrupted with their\n * enclosing scope; no host abort signal or timer is involved.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makePair = (): Effect.Effect<Pair, never, Scope.Scope> =>\n  Effect.gen(function*() {\n    const scope = yield* Effect.scope\n    const clientIncoming = yield* Queue.bounded<Uint8Array, Socket.SocketError>(queueCapacity)\n    const serverIncoming = yield* Queue.bounded<Uint8Array, Socket.SocketError>(queueCapacity)\n    yield* Scope.addFinalizer(\n      scope,\n      Effect.all([Queue.shutdown(clientIncoming), Queue.shutdown(serverIncoming)], { discard: true })\n    )\n    const delivery = Latch.makeUnsafe(true)\n    const filters: Array<FrameFilter> = []\n\n    const offer = (queue: Queue.Queue<Uint8Array, Socket.SocketError>, bytes: Uint8Array) =>\n      Effect.suspend(() => {\n        let current = bytes\n        for (const filter of filters) {\n          const result = filter(current)\n          if (typeof result === \"boolean\") {\n            if (result === false) return Effect.void\n          } else {\n            current = result\n          }\n        }\n        return Queue.offer(queue, current).pipe(Effect.asVoid)\n      })\n\n    const socket = (\n      incoming: Queue.Queue<Uint8Array, Socket.SocketError>,\n      outgoing: Queue.Queue<Uint8Array, Socket.SocketError>\n    ) => {\n      const write: Socket.Writer[\"write\"] = (chunk) => {\n        if (Socket.isCloseEvent(chunk)) return Effect.void\n        const bytes = typeof chunk === \"string\" ? new TextEncoder().encode(chunk) : chunk\n        return offer(outgoing, bytes)\n      }\n      return Socket.make({\n        reader: Effect.gen(function*() {\n          const closed = yield* Deferred.make<never, Socket.SocketError>()\n          yield* Effect.addFinalizer(() => Deferred.fail(closed, transportError()))\n          return {\n            pull: Effect.raceFirst(\n              Effect.map(delivery.whenOpen(Queue.take(incoming)), (bytes) => [bytes] as const),\n              Deferred.await(closed)\n            ),\n            upgrade: Socket.SocketUpgradeError.unsupported\n          }\n        }),\n        writer: Effect.succeed({\n          write,\n          writeAll: (chunks) => Effect.forEach(chunks, write, { discard: true })\n        })\n      })\n    }\n\n    const faults: TestFaults = {\n      installFilter: (filter) => {\n        filters.push(filter)\n      },\n      dropRange: (runId, from, to) => {\n        filters.push((bytes) => {\n          const range = entriesRange(bytes)\n          return range === undefined || range.runId !== runId || !intersects(range.from, range.to, from, to)\n        })\n      },\n      stall: () => {\n        delivery.closeUnsafe()\n      },\n      resume: () => {\n        delivery.openUnsafe()\n      },\n      disconnect: () =>\n        Effect.andThen(\n          Queue.fail(clientIncoming, transportError()),\n          Queue.fail(serverIncoming, transportError())\n        ).pipe(Effect.asVoid)\n    }\n\n    return {\n      client: socket(clientIncoming, serverIncoming),\n      server: socket(serverIncoming, clientIncoming),\n      faults\n    }\n  })\n"]}

package/dist/esm/test/TestSync.d.ts

@@ -0,0 +1,54 @@
+/**
+ * In-process sync service and RPC transport wiring for tests.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as RunCatalog from "../RunCatalog.ts";
+import * as SyncClient from "../SyncClient.ts";
+import * as SyncRpcs from "../SyncRpcs.ts";
+import * as SyncServer from "../SyncServer.ts";
+import type { Pair } from "./TestSocket.ts";
+/**
+ * An authentication middleware that trusts every connection as the workspace
+ * owner. Test-only by construction: replication-mechanics suites use it so
+ * they exercise paging and streaming without provisioning capabilities,
+ * while the authentication suites use the production `SyncAuth.layer`.
+ *
+ * Never compose it into a served transport: every network client would read
+ * every workspace run as the owner. The name says so at the call site.
+ *
+ * @category layers
+ * @since 1.0.0-rc.1
+ */
+export declare const layerTrustAllAsOwner: Layer.Layer<SyncRpcs.SyncAuth, never, never>;
+/**
+ * Provides the durable in-memory journal, a mutable empty run catalog, the
+ * owner-trusting {@link layerTrustAllAsOwner} middleware, and the production
+ * sync server.
+ *
+ * Tests that need runs in the workspace may register them through their own
+ * `RunCatalog.makeMemory` fixture before providing a more specific layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerTest: Layer.Layer<import("@smthrs/journal/Journal").Journal | SyncRpcs.SyncAuth | RunCatalog.RunCatalog | SyncServer.SyncServer, import("effect/unstable/sql/SqlError").SqlError | import("@smthrs/journal/Journal").JournalError | import("effect/unstable/sql/Migrator").MigrationError | import("../SyncError.ts").SyncError, never>;
+/**
+ * Provides no-op sync dependencies for consumers that only require the ports.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<SyncRpcs.SyncAuth | RunCatalog.RunCatalog | SyncClient.SyncClient | SyncServer.SyncServer, never, never>;
+/**
+ * Starts an RPC server over the pair's server endpoint and returns a sync
+ * client over the client endpoint. JSON serialization is deliberately used so
+ * frame faults can inspect test traffic without coupling to sync schemas.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const connect: (pair: Pair) => Effect.Effect<SyncClient.Service, never, import("effect/Scope").Scope | SyncRpcs.SyncAuth | SyncServer.SyncServer>;
+//# sourceMappingURL=TestSync.d.ts.map

package/dist/esm/test/TestSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestSync.d.ts","sourceRoot":"","sources":["../../../src/test/TestSync.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAOrC,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAI3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,8CAEhC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,mUAQrB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,sHAKrB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,IAAI,uHA8B9B,CAAA"}

package/dist/esm/test/TestSync.js

@@ -0,0 +1,76 @@
+/**
+ * In-process sync service and RPC transport wiring for tests.
+ *
+ * @since 0.1.0
+ */
+import * as TestJournal from "@smthrs/journal/test/TestJournal";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as NetAddress from "effect/unstable/net/NetAddress";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import * as RpcServer from "effect/unstable/rpc/RpcServer";
+import * as Socket from "effect/unstable/socket/Socket";
+import * as SocketServer from "effect/unstable/socket/SocketServer";
+import * as RunCatalog from "../RunCatalog.js";
+import * as SyncClient from "../SyncClient.js";
+import * as SyncPrincipal from "../SyncPrincipal.js";
+import * as SyncRpcs from "../SyncRpcs.js";
+import * as SyncServer from "../SyncServer.js";
+const layerNoopAuth = Layer.succeed(SyncRpcs.SyncAuth)((effect) => effect);
+/**
+ * An authentication middleware that trusts every connection as the workspace
+ * owner. Test-only by construction: replication-mechanics suites use it so
+ * they exercise paging and streaming without provisioning capabilities,
+ * while the authentication suites use the production `SyncAuth.layer`.
+ *
+ * Never compose it into a served transport: every network client would read
+ * every workspace run as the owner. The name says so at the call site.
+ *
+ * @category layers
+ * @since 1.0.0-rc.1
+ */
+export const layerTrustAllAsOwner = Layer.succeed(SyncRpcs.SyncAuth)((effect) => Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.workspace("test-workspace-owner")));
+/**
+ * Provides the durable in-memory journal, a mutable empty run catalog, the
+ * owner-trusting {@link layerTrustAllAsOwner} middleware, and the production
+ * sync server.
+ *
+ * Tests that need runs in the workspace may register them through their own
+ * `RunCatalog.makeMemory` fixture before providing a more specific layer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerTest = SyncServer.layer.pipe(Layer.provideMerge(Layer.mergeAll(TestJournal.layer(), RunCatalog.layerMemory(), layerTrustAllAsOwner)));
+/**
+ * Provides no-op sync dependencies for consumers that only require the ports.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.mergeAll(SyncClient.layerNoop(), SyncServer.layerNoop, RunCatalog.layerNoop, layerNoopAuth);
+/**
+ * Starts an RPC server over the pair's server endpoint and returns a sync
+ * client over the client endpoint. JSON serialization is deliberately used so
+ * frame faults can inspect test traffic without coupling to sync schemas.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const connect = (pair) => Effect.gen(function* () {
+    const sync = yield* SyncServer.SyncServer;
+    const handlers = SyncServer.layerHandlers.pipe(Layer.provide(Layer.succeed(SyncServer.SyncServer, sync)));
+    // Use the production schema-aware protocol. JSON.stringify on the raw
+    // makeNoSerialization responses happened to encode successes, but not
+    // Effect's Cause representation: typed RPC failures never reached clients.
+    const serverProtocol = yield* RpcServer.makeProtocolSocketServer.pipe(Effect.provideService(SocketServer.SocketServer, {
+        address: NetAddress.inetAddressFromIpStringUnsafe("127.0.0.1", 0),
+        run: (handler) => handler(pair.server).pipe(Effect.orDie, Effect.andThen(Effect.never))
+    }), Effect.provide(RpcSerialization.layerJson));
+    yield* RpcServer.make(SyncRpcs.SyncRpcs, { disableFatalDefects: true }).pipe(Effect.provideService(RpcServer.Protocol, serverProtocol), Effect.provide(handlers), Effect.forkScoped);
+    const protocol = yield* RpcClient.makeProtocolSocket().pipe(Effect.provideService(Socket.Socket, pair.client), Effect.provide(RpcSerialization.layerJson));
+    const client = yield* RpcClient.make(SyncRpcs.SyncRpcs).pipe(Effect.provideService(RpcClient.Protocol, protocol));
+    return yield* SyncClient.make({ client });
+});
+//# sourceMappingURL=TestSync.js.map

package/dist/esm/test/TestSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestSync.js","sourceRoot":"","sources":["../../../src/test/TestSync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * In-process sync service and RPC transport wiring for tests.\n *\n * @since 0.1.0\n */\n\nimport * as TestJournal from \"@smthrs/journal/test/TestJournal\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as NetAddress from \"effect/unstable/net/NetAddress\"\nimport * as RpcClient from \"effect/unstable/rpc/RpcClient\"\nimport * as RpcSerialization from \"effect/unstable/rpc/RpcSerialization\"\nimport * as RpcServer from \"effect/unstable/rpc/RpcServer\"\nimport * as Socket from \"effect/unstable/socket/Socket\"\nimport * as SocketServer from \"effect/unstable/socket/SocketServer\"\nimport * as RunCatalog from \"../RunCatalog.ts\"\nimport * as SyncClient from \"../SyncClient.ts\"\nimport * as SyncPrincipal from \"../SyncPrincipal.ts\"\nimport * as SyncRpcs from \"../SyncRpcs.ts\"\nimport * as SyncServer from \"../SyncServer.ts\"\nimport type { Pair } from \"./TestSocket.ts\"\n\nconst layerNoopAuth = Layer.succeed(SyncRpcs.SyncAuth)((effect) => effect)\n\n/**\n * An authentication middleware that trusts every connection as the workspace\n * owner. Test-only by construction: replication-mechanics suites use it so\n * they exercise paging and streaming without provisioning capabilities,\n * while the authentication suites use the production `SyncAuth.layer`.\n *\n * Never compose it into a served transport: every network client would read\n * every workspace run as the owner. The name says so at the call site.\n *\n * @category layers\n * @since 1.0.0-rc.1\n */\nexport const layerTrustAllAsOwner = Layer.succeed(SyncRpcs.SyncAuth)((effect) =>\n  Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.workspace(\"test-workspace-owner\"))\n)\n\n/**\n * Provides the durable in-memory journal, a mutable empty run catalog, the\n * owner-trusting {@link layerTrustAllAsOwner} middleware, and the production\n * sync server.\n *\n * Tests that need runs in the workspace may register them through their own\n * `RunCatalog.makeMemory` fixture before providing a more specific layer.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerTest = SyncServer.layer.pipe(\n  Layer.provideMerge(\n    Layer.mergeAll(\n      TestJournal.layer(),\n      RunCatalog.layerMemory(),\n      layerTrustAllAsOwner\n    )\n  )\n)\n\n/**\n * Provides no-op sync dependencies for consumers that only require the ports.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop = Layer.mergeAll(\n  SyncClient.layerNoop(),\n  SyncServer.layerNoop,\n  RunCatalog.layerNoop,\n  layerNoopAuth\n)\n\n/**\n * Starts an RPC server over the pair's server endpoint and returns a sync\n * client over the client endpoint. JSON serialization is deliberately used so\n * frame faults can inspect test traffic without coupling to sync schemas.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const connect = (pair: Pair) =>\n  Effect.gen(function*() {\n    const sync = yield* SyncServer.SyncServer\n    const handlers = SyncServer.layerHandlers.pipe(\n      Layer.provide(Layer.succeed(SyncServer.SyncServer, sync))\n    )\n    // Use the production schema-aware protocol. JSON.stringify on the raw\n    // makeNoSerialization responses happened to encode successes, but not\n    // Effect's Cause representation: typed RPC failures never reached clients.\n    const serverProtocol = yield* RpcServer.makeProtocolSocketServer.pipe(\n      Effect.provideService(SocketServer.SocketServer, {\n        address: NetAddress.inetAddressFromIpStringUnsafe(\"127.0.0.1\", 0),\n        run: (handler) => handler(pair.server).pipe(Effect.orDie, Effect.andThen(Effect.never))\n      }),\n      Effect.provide(RpcSerialization.layerJson)\n    )\n    yield* RpcServer.make(SyncRpcs.SyncRpcs, { disableFatalDefects: true }).pipe(\n      Effect.provideService(RpcServer.Protocol, serverProtocol),\n      Effect.provide(handlers),\n      Effect.forkScoped\n    )\n\n    const protocol = yield* RpcClient.makeProtocolSocket().pipe(\n      Effect.provideService(Socket.Socket, pair.client),\n      Effect.provide(RpcSerialization.layerJson)\n    )\n    const client = yield* RpcClient.make(SyncRpcs.SyncRpcs).pipe(\n      Effect.provideService(RpcClient.Protocol, protocol)\n    )\n    return yield* SyncClient.make({ client })\n  })\n"]}

package/docs/README.md

@@ -0,0 +1,156 @@
+---
+title: "@smthrs/sync"
+description: "Read-only replication of a Smithers journal: a wire protocol, a server that pages and streams entries, and a browser-safe client that replays a run's history and then follows it live."
+---
+
+`@smthrs/sync` copies the history of a run to readers that do not own it. It
+carries three things: a wire protocol, a server that serves that protocol over
+[Effect](https://effect.website) RPC, and a browser-safe client that replays a
+run's durable history and then follows it live through one stream.
+
+The history it replicates is a [`@smthrs/journal`](/api/journal) run. The read
+path, `SyncRpcs` served by `SyncServer` and followed by `SyncClient`, never
+writes to a journal, so a follower cannot corrupt what it reads.
+`BranchCommands` is the separate write surface: it appends admitted branch
+commands to a branch's journal run after verifying a write-scoped
+`BranchShare` capability.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## What it solves
+
+A long-running job records what it did in a journal, on the machine that ran
+it. Everyone else who cares about that job is somewhere else: a dashboard in a
+browser, a terminal tailing a build another process started, a second engine
+reconciling its own view. Each of them needs the same entries, in the same
+order, without reaching into the writer's database.
+
+Writing that by hand means solving the same problems every time, and getting
+any one of them wrong loses history quietly. This package solves them once:
+
+- **Catch up and then follow, through one call.** `subscribe` pages durable
+  history until the server reports it reached the tail, then switches to live
+  frames. The consumer sees one stream and never sees the switch.
+- **Resume where you stopped.** A cursor is per run and exclusive, so a
+  follower that persists its cursors hands them back after a restart and reads
+  forward from there.
+- **Acknowledge what you applied, not what you received.** By default a cursor
+  names what was delivered. Supply `apply` and the cursor advances only after
+  your own write succeeds, so a consumer that fails halfway re-receives the
+  entry instead of skipping it.
+- **Hold open a bound, not a workspace.** Every in-flight surface has a
+  configured ceiling: page size, frame bytes, subscription credit, concurrent
+  journal reads. What one follower holds open is a function of those numbers
+  rather than of how far behind it has fallen. Its per-run positions and its
+  periodic catalog-wide round still scale with the runs it covers; a local
+  append wakes a read of that run alone.
+- **Read nothing until you are authorized.** The default principal is
+  anonymous and reads nothing. A connection becomes a reader by presenting a
+  signed, expiring capability, and an open subscription ends when that
+  capability expires.
+- **Distrust the server.** The client refuses a page or frame that carries
+  another run's entry, repeats or reorders a sequence, or serves an entry at or
+  below the cursor it asked from. It refuses before any cursor moves, so a
+  faulty server or a rewriting proxy costs an error rather than a hole.
+
+## Follow a run
+
+A follower composes the client over a transport and subscribes. This program
+prints every entry of one run, starting with the history that already exists:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import * as SyncClient from "@smthrs/sync/SyncClient"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+
+const runId = "build-42" as JournalEvent.RunId
+
+export const follow = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  yield* sync.subscribe({ scope: { _tag: "Run", runId }, cursors: [] }).pipe(
+    Stream.runForEach((entry) => Effect.logInfo(`${entry.seq} ${entry.eventType}`))
+  )
+})
+
+export const clientLayer = SyncClient.layer.pipe(
+  Layer.provide(RpcClient.layerProtocolSocket()),
+  Layer.provide(RpcSerialization.layerJson)
+)
+```
+
+The socket that protocol runs over comes from your platform: a WebSocket in a
+browser, `@effect/platform-node`'s socket layer in Node. Pass
+`{ _tag: "Workspace" }` instead of a run scope to follow every run the server
+lists and your credential covers.
+
+The serving side is `SyncServer` over a journal and a run catalog.
+[`@smthrs/gateway`](/api/gateway) already mounts it on `POST /sync` and
+`/sync/ws`, so a follower against a Smithers gateway writes only the code
+above. [Serve the read path](./guides/serve-the-read-path.md) builds it into a
+host of your own.
+
+To watch both halves work with no network and no database, run the
+[quickstart](./quickstart.md): it stands the real server and the real client up
+over an in-memory socket pair and follows an entry that commits while you are
+watching.
+
+## Branch collaboration
+
+The package also carries a branch surface: several people editing one shared
+live document, whose entire durable state is one journal run. Reusing a run
+means multiplayer inherits the canonical sequence, the cursors, the gap
+detection, and the resumable follow rather than introducing a second source of
+truth.
+
+Branch collaboration ships unserved at 1.0.0-rc.0. The gateway mounts the read
+path and nothing mounts the branch procedures, so treat those modules as a
+library surface waiting for a host. [Branch collaboration](./concepts/branches.md)
+describes what they guarantee.
+
+## Where this sits
+
+`@smthrs/sync` is one package of the Smithers durable flow engine, and it owns
+exactly the read path out of that engine. [`@smthrs/flows`](/api/flows) is the
+engine's barrel: it re-exports this package as a namespace next to the journal,
+the stores, and the Node runtime that wires them over one SQLite file, so
+`import { Sync } from "@smthrs/flows"` reaches the same code as
+`import * as Sync from "@smthrs/sync"`. Depend on the barrel when you want a
+working engine in one dependency. Depend on this package when replication is
+the part you need, which is what a browser wants: the root here is browser
+safe, and the barrel's Node runtime has no place in a bundle.
+
+The two packages either side of it are worth knowing.
+[`@smthrs/journal`](/api/journal) writes the entries this one replicates and
+owns compaction, which is the one refusal a follower has to recover from.
+[`@smthrs/gateway`](/api/gateway) is the host that puts the read path on a
+port.
+
+Above the whole engine sits the
+[`smithers` command-line interface](/api/cli), which runs flows out of a
+project directory without your composing any of this by hand.
+
+## Next steps
+
+- [Installation](./installation.md): the import forms, and what a follower and
+  a server each add on top of this package.
+- [Quickstart](./quickstart.md): a real server and a real client following one
+  run end to end, with no network.
+- [Scopes and cursors](./concepts/scopes-and-cursors.md): what a request covers,
+  what a cursor claims, and why journal sequences have holes.
+- [Replay then follow](./concepts/replay-then-follow.md): the two phases of a
+  subscription and the bounds on each.
+- [Authorization](./concepts/authorization.md): the two fail-closed boundaries
+  and why a subscription carries its own expiry.
+- [Follow a run](./guides/follow-a-run.md): the follower above, with cursors
+  you persist and the failures that reach you.
+- [Test a follower](./guides/test-a-follower.md): drop, stall, and corrupt
+  frames against the production client.
+- [Wire protocol](./protocol.md): the normative message shapes, for a client in
+  another language.
+- [API reference](./api.md): every public export, its bounds, and its defaults.
+- [Troubleshooting](./troubleshooting.md): every error code, the symptom it
+  produces, and the change that fixes it.