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

package/dist/cjs/RunCatalog.js

@@ -0,0 +1,122 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var RunCatalog_exports = {};
+__export(RunCatalog_exports, {
+  RunCatalog: () => RunCatalog,
+  defaultChangesCapacity: () => defaultChangesCapacity,
+  defaultPollIntervalMs: () => defaultPollIntervalMs,
+  layerMemory: () => layerMemory,
+  layerNoop: () => layerNoop,
+  layerPolling: () => layerPolling,
+  layerStatic: () => layerStatic,
+  makeMemory: () => makeMemory,
+  makePolling: () => makePolling
+});
+module.exports = __toCommonJS(RunCatalog_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var PubSub = __toESM(require("effect/PubSub"), 1);
+var Ref = __toESM(require("effect/Ref"), 1);
+var Stream = __toESM(require("effect/Stream"), 1);
+var import_PolicyOptions = require("./internal/PolicyOptions.js");
+class RunCatalog extends Context.Service()("@smthrs/sync/RunCatalog") {
+}
+const layerStatic = (ids) => {
+  const known = Array.from(new Set(ids));
+  return Layer.succeed(
+    RunCatalog,
+    RunCatalog.of({
+      list: Effect.sync(() => [...known]),
+      changes: Stream.empty
+    })
+  );
+};
+const defaultChangesCapacity = 1024;
+const makeMemory = (options = {}) => Effect.gen(function* () {
+  const known = /* @__PURE__ */ new Set();
+  const changes = yield* PubSub.sliding(
+    yield* (0, import_PolicyOptions.positiveInt)("RunCatalog.MemoryOptions.changesCapacity", options.changesCapacity, defaultChangesCapacity)
+  );
+  return {
+    catalog: RunCatalog.of({
+      list: Effect.sync(() => Array.from(known)).pipe(Effect.withSpan("RunCatalog.list")),
+      changes: Stream.fromPubSub(changes)
+    }),
+    register: Effect.fn("RunCatalog.register")(
+      (runId) => Effect.suspend(() => {
+        if (known.has(runId)) return Effect.void;
+        known.add(runId);
+        return PubSub.publish(changes, runId).pipe(Effect.asVoid);
+      })
+    )
+  };
+});
+const defaultPollIntervalMs = 1e3;
+const makePolling = (options) => Effect.gen(function* () {
+  const intervalMs = yield* (0, import_PolicyOptions.positiveInt)(
+    "RunCatalog.PollingOptions.intervalMs",
+    options.intervalMs,
+    defaultPollIntervalMs
+  );
+  const changes = yield* PubSub.sliding(
+    yield* (0, import_PolicyOptions.positiveInt)("RunCatalog.PollingOptions.changesCapacity", options.changesCapacity, defaultChangesCapacity)
+  );
+  const snapshot = yield* Ref.make([]);
+  const refresh = Effect.gen(function* () {
+    const read = yield* options.read;
+    const next = Array.from(new Set(read));
+    const previous = new Set(yield* Ref.get(snapshot));
+    yield* Ref.set(snapshot, next);
+    for (const runId of next) {
+      if (!previous.has(runId)) yield* PubSub.publish(changes, runId);
+    }
+  });
+  yield* refresh;
+  const consecutiveFailures = yield* Ref.make(0);
+  const poll = refresh.pipe(
+    Effect.matchCauseEffect({
+      onFailure: (cause) => Effect.flatMap(Ref.updateAndGet(consecutiveFailures, (count) => count + 1), (count) => count === 1 ? Effect.logWarning("The workspace run catalog could not be read; the previous view stands", cause) : Effect.void),
+      onSuccess: () => Effect.flatMap(Ref.getAndSet(consecutiveFailures, 0), (count) => count === 0 ? Effect.void : Effect.logInfo(`The workspace run catalog is readable again after ${count} failed reads`))
+    })
+  );
+  yield* poll.pipe(
+    Effect.delay(intervalMs),
+    Effect.forever,
+    Effect.forkScoped
+  );
+  return RunCatalog.of({
+    list: Effect.map(Ref.get(snapshot), (ids) => [...ids]).pipe(Effect.withSpan("RunCatalog.list")),
+    changes: Stream.fromPubSub(changes)
+  });
+});
+const layerPolling = (options) => Layer.effect(RunCatalog, makePolling(options));
+const layerMemory = (options = {}) => Layer.effect(RunCatalog, Effect.map(makeMemory(options), ({ catalog }) => catalog));
+const layerNoop = layerStatic([]);
+//# sourceMappingURL=RunCatalog.js.map

package/dist/cjs/RunCatalog.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/RunCatalog.ts"],
+  "sourcesContent": ["/**\n * Workspace run enumeration for synchronization.\n *\n * @since 0.1.0\n */\n\nimport type { JournalEvent } from \"@smthrs/journal\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as PubSub from \"effect/PubSub\"\nimport * as Ref from \"effect/Ref\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport { positiveInt } from \"./internal/PolicyOptions.ts\"\nimport type { SyncError } from \"./SyncError.ts\"\n\n/**\n * Workspace run enumeration operations.\n *\n * `list` is the AUTHORITATIVE run set and `changes` is only a low-latency\n * wake: a subscriber that misses an announcement re-lists rather than losing\n * state, and a subscriber whose covered set must stay accurate re-lists on a\n * cadence of its own. Every implementation returns a fresh array from `list`,\n * so a caller may retain and sort what it receives without disturbing another\n * reader.\n *\n * `list` names each run AT MOST ONCE. Every implementation here deduplicates,\n * and `SyncServer` deduplicates again at the seam rather than trusting a\n * host's catalog, because both fan-out paths key a run's served position by\n * run id: a run named twice is read twice from the same position and its\n * entries are served twice.\n *\n * The catalog is supplied by the host rather than derived from the journal:\n * `@smthrs/journal` has no workspace-wide list or watch contract, and\n * `@smthrs/engine-store` owns the durable run set that {@link makePolling}\n * reads.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly list: Effect.Effect<ReadonlyArray<JournalEvent.RunId>>\n  readonly changes: Stream.Stream<JournalEvent.RunId>\n}\n\n/**\n * Host-provided workspace run catalog.\n *\n * @category services\n * @since 0.1.0\n */\nexport class RunCatalog extends Context.Service<RunCatalog, Service>()(\"@smthrs/sync/RunCatalog\") {}\n\n/**\n * Provides an immutable run catalog.\n *\n * `list` answers with a fresh array each time, matching {@link makeMemory} and\n * {@link makePolling}. Handing every caller the same instance let one reader\n * sort or splice the catalog in place for every other reader, which is a\n * defect a `ReadonlyArray` type hides from TypeScript and not from JavaScript.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerStatic = (\n  ids: ReadonlyArray<JournalEvent.RunId>\n): Layer.Layer<RunCatalog> => {\n  const known = Array.from(new Set(ids))\n  return Layer.succeed(\n    RunCatalog,\n    RunCatalog.of({\n      list: Effect.sync(() => [...known]),\n      changes: Stream.empty\n    })\n  )\n}\n\n/**\n * Announcements a stalled {@link Service.changes} subscriber may fall behind\n * by before the oldest are dropped.\n *\n * `changes` is a notification feed, not a log: a follower reads it to learn\n * that the workspace gained a run and then reads the run itself. Retaining an\n * unbounded backlog for a subscriber that has stopped pulling \u2014 a disconnected\n * tab whose socket has not timed out yet, a follower blocked behind a slow\n * consumer \u2014 is therefore pure cost, and the workspace's whole run history is\n * the upper bound on it. A subscriber that falls further behind than this\n * bound loses the oldest announcements; `list` still names every run, so a\n * follower that reconnects or re-lists converges.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultChangesCapacity = 1024\n\n/**\n * Options for the in-memory run catalog.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface MemoryOptions {\n  /**\n   * Announcements a stalled subscriber may fall behind by. Defaults to\n   * {@link defaultChangesCapacity}.\n   */\n  readonly changesCapacity?: number | undefined\n}\n\n/**\n * Constructs a mutable in-memory run catalog.\n *\n * A run is published exactly once, when it is first registered. The\n * announcement feed slides: registering never waits on a stalled subscriber,\n * and never grows the process on its behalf.\n *\n * Fails with `invalid_request` when `changesCapacity` is not a positive safe\n * integer, rather than handing it to `PubSub.sliding` as a capacity.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeMemory = (options: MemoryOptions = {}): Effect.Effect<{\n  readonly catalog: Service\n  readonly register: (runId: JournalEvent.RunId) => Effect.Effect<void>\n}, SyncError> =>\n  Effect.gen(function*() {\n    const known = new Set<JournalEvent.RunId>()\n    const changes = yield* PubSub.sliding<JournalEvent.RunId>(\n      yield* positiveInt(\"RunCatalog.MemoryOptions.changesCapacity\", options.changesCapacity, defaultChangesCapacity)\n    )\n    return {\n      catalog: RunCatalog.of({\n        list: Effect.sync(() => Array.from(known)).pipe(Effect.withSpan(\"RunCatalog.list\")),\n        changes: Stream.fromPubSub(changes)\n      }),\n      register: Effect.fn(\"RunCatalog.register\")((runId) =>\n        Effect.suspend(() => {\n          if (known.has(runId)) return Effect.void\n          known.add(runId)\n          return PubSub.publish(changes, runId).pipe(Effect.asVoid)\n        })\n      )\n    }\n  })\n\n/**\n * How often {@link makePolling} re-reads its source when the caller names no\n * interval, in milliseconds.\n *\n * A workspace follower learns of a new run within one interval of it being\n * created, and the read costs one bounded query per interval per composition,\n * not per subscriber. A second is short enough that a run appears in a UI\n * while the operator is still looking at the command that started it, and\n * long enough that an idle workspace is close to free.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultPollIntervalMs = 1000\n\n/**\n * Options for the polling run catalog.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface PollingOptions<E, R> {\n  /**\n   * Reads the workspace's current run set. `@smthrs/engine-store` supplies\n   * the durable one over `flows_runs`; anything that answers the same\n   * question works, and the catalog holds no assumption about which.\n   */\n  readonly read: Effect.Effect<ReadonlyArray<JournalEvent.RunId>, E, R>\n  /** Milliseconds between reads. Defaults to {@link defaultPollIntervalMs}. */\n  readonly intervalMs?: number | undefined\n  /**\n   * Announcements a stalled subscriber may fall behind by. Defaults to\n   * {@link defaultChangesCapacity}.\n   */\n  readonly changesCapacity?: number | undefined\n}\n\n/**\n * Constructs a run catalog that polls a durable source.\n *\n * Polling, not waking. rc.0 has no cross-process event delivery, so a\n * follower learns of a run another engine created by asking the workspace\n * again, and the interval is the whole of the policy.\n *\n * The catalog primes itself before it returns, so the first read a follower\n * makes is already current and a workspace that cannot be read at all fails\n * the composition instead of serving an empty run set. After that a failed\n * read is a warning and nothing else: the previous view stands, the interval\n * holds, and no subscription attached to the catalog is torn down for it.\n * The warning is written once per outage, with the first failure's cause, and\n * one info line marks the read that ends it; the polls in between are silent.\n *\n * A run is announced once, when it first appears. A run the read stops\n * naming, which is what retention collecting it looks like, leaves the view;\n * `list` is the workspace's run set, not a log of every run it ever had.\n *\n * `list` answers with a fresh array each time, matching {@link layerStatic} and\n * {@link makeMemory}. Handing back the stored snapshot let a caller sort or\n * splice the authoritative run set in place under the poll fiber that owns it,\n * which is a defect a `ReadonlyArray` type hides from TypeScript and not from\n * JavaScript.\n *\n * The poll fiber belongs to the caller's scope. Closing the scope stops it.\n *\n * Both numeric options are validated here, before the first read: an\n * `intervalMs` of `NaN` or zero reached `Effect.delay` as the whole of the\n * poll cadence, which is a loop with no interval rather than a refusal.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makePolling = <E, R>(\n  options: PollingOptions<E, R>\n): Effect.Effect<Service, E | SyncError, R | Scope.Scope> =>\n  Effect.gen(function*() {\n    const intervalMs = yield* positiveInt(\n      \"RunCatalog.PollingOptions.intervalMs\",\n      options.intervalMs,\n      defaultPollIntervalMs\n    )\n    const changes = yield* PubSub.sliding<JournalEvent.RunId>(\n      yield* positiveInt(\"RunCatalog.PollingOptions.changesCapacity\", options.changesCapacity, defaultChangesCapacity)\n    )\n    const snapshot = yield* Ref.make<ReadonlyArray<JournalEvent.RunId>>([])\n\n    const refresh = Effect.gen(function*() {\n      const read = yield* options.read\n      const next = Array.from(new Set(read))\n      const previous = new Set(yield* Ref.get(snapshot))\n      yield* Ref.set(snapshot, next)\n      for (const runId of next) {\n        // Publishing never waits on a stalled subscriber, and never grows the\n        // process on its behalf: the feed slides.\n        if (!previous.has(runId)) yield* PubSub.publish(changes, runId)\n      }\n    })\n\n    yield* refresh\n    // The log follows the outage's transitions, not the poll cadence. With\n    // the default interval a workspace that stays unreadable would otherwise\n    // write one identical warning per second per catalog for as long as it\n    // lasts, and the line that says it ended would never be written.\n    const consecutiveFailures = yield* Ref.make(0)\n    const poll = refresh.pipe(\n      Effect.matchCauseEffect({\n        onFailure: (cause) =>\n          Effect.flatMap(Ref.updateAndGet(consecutiveFailures, (count) => count + 1), (count) =>\n            count === 1\n              ? Effect.logWarning(\"The workspace run catalog could not be read; the previous view stands\", cause)\n              : Effect.void),\n        onSuccess: () =>\n          Effect.flatMap(Ref.getAndSet(consecutiveFailures, 0), (count) =>\n            count === 0\n              ? Effect.void\n              : Effect.logInfo(`The workspace run catalog is readable again after ${count} failed reads`))\n      })\n    )\n    yield* poll.pipe(\n      Effect.delay(intervalMs),\n      Effect.forever,\n      Effect.forkScoped\n    )\n\n    return RunCatalog.of({\n      list: Effect.map(Ref.get(snapshot), (ids) => [...ids]).pipe(Effect.withSpan(\"RunCatalog.list\")),\n      changes: Stream.fromPubSub(changes)\n    })\n  })\n\n/**\n * Provides a run catalog that polls a durable source. The poll fiber lives as\n * long as the layer's scope.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerPolling = <E, R>(\n  options: PollingOptions<E, R>\n): Layer.Layer<RunCatalog, E | SyncError, R> => Layer.effect(RunCatalog, makePolling(options))\n\n/**\n * Provides the mutable in-memory run catalog, matching how every other\n * implementation here is provided. Fails with `invalid_request` when\n * `changesCapacity` is not a positive safe integer.\n *\n * The layer provides the catalog alone. A composition that also registers runs\n * builds {@link makeMemory} itself and keeps its `register`.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerMemory = (options: MemoryOptions = {}): Layer.Layer<RunCatalog, SyncError> =>\n  Layer.effect(RunCatalog, Effect.map(makeMemory(options), ({ catalog }) => catalog))\n\n/**\n * Provides an empty run catalog.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<RunCatalog> = layerStatic([])\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/SyncAuth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The sync read path's connection authentication: implementations of the
+ * `SyncRpcs.SyncAuth` RPC middleware.
+ *
+ * A connection presents a {@link WorkspaceShare.WorkspaceCapability} in the
+ * {@link capabilityHeader} request header. {@link layer} verifies it against
+ * the workspace's {@link WorkspaceShare.WorkspaceShare} authority and runs
+ * the handler as the workspace principal. A request with no header runs as
+ * the anonymous principal — branch share capabilities carried in request
+ * payloads still authorize branch reads — and the server refuses anonymous
+ * access to every non-branch run. A request whose header is present but
+ * malformed, forged, expired, or signed by an unknown key is refused
+ * outright: presence of a credential is a claim, and a false claim is never
+ * downgraded to anonymity.
+ *
+ * There is deliberately no trusted pass-through implementation here: the only
+ * sanctioned bypass is an in-process caller providing `SyncPrincipal` itself,
+ * never a transport.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as RpcMiddleware from "effect/unstable/rpc/RpcMiddleware";
+import { SyncError } from "./SyncError.ts";
+import { SyncAuth } from "./SyncRpcs.ts";
+import * as WorkspaceShare from "./WorkspaceShare.ts";
+/**
+ * The request header a connection presents its workspace capability in.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const capabilityHeader = "flows-sync-workspace";
+/**
+ * Renders a workspace capability as its header value: unpadded base64url of
+ * the schema-encoded capability JSON.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const encodeCapability: (capability: WorkspaceShare.WorkspaceCapability) => Effect.Effect<string, SyncError>;
+/**
+ * Decodes a capability header value. Every malformation folds to the same
+ * `unauthorized` refusal so the header is not a parsing oracle.
+ *
+ * @category encoding
+ * @since 0.1.0
+ */
+export declare const decodeCapability: (value: string) => Effect.Effect<WorkspaceShare.WorkspaceCapability, SyncError>;
+/**
+ * Provides the workspace-capability authentication middleware: no header
+ * runs the handler as anonymous, a verified header runs it as the workspace
+ * principal, and anything else refuses the request. Verification faults
+ * (Web Crypto failing) propagate as their own error rather than as a
+ * refusal.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<SyncAuth, never, WorkspaceShare.WorkspaceShare>;
+/**
+ * Stamps every outgoing request from a generated RPC client with the given
+ * workspace capability.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerClient: (capability: WorkspaceShare.WorkspaceCapability) => Layer.Layer<RpcMiddleware.ForClient<SyncAuth>, SyncError>;
+//# sourceMappingURL=SyncAuth.d.ts.map

package/dist/cjs/SyncAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncAuth.d.ts","sourceRoot":"","sources":["../../src/SyncAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAIrC,OAAO,KAAK,aAAa,MAAM,mCAAmC,CAAA;AAGlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,yBAAyB,CAAA;AAItD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,YAAY,cAAc,CAAC,mBAAmB,KAC7C,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAajC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,mBAAmB,EAAE,SAAS,CAe3G,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,cAAc,CAyB7E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,YAAY,cAAc,CAAC,mBAAmB,KAC7C,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,SAAS,CAKxD,CAAA"}

package/dist/cjs/SyncAuth.js

@@ -0,0 +1,109 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var SyncAuth_exports = {};
+__export(SyncAuth_exports, {
+  capabilityHeader: () => capabilityHeader,
+  decodeCapability: () => decodeCapability,
+  encodeCapability: () => encodeCapability,
+  layer: () => layer,
+  layerClient: () => layerClient
+});
+module.exports = __toCommonJS(SyncAuth_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Encoding = __toESM(require("effect/Encoding"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Result = __toESM(require("effect/Result"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Headers = __toESM(require("effect/unstable/http/Headers"), 1);
+var RpcMiddleware = __toESM(require("effect/unstable/rpc/RpcMiddleware"), 1);
+var import_CauseText = require("./internal/CauseText.js");
+var shareSigner = __toESM(require("./internal/ShareSigner.js"), 1);
+var import_SyncError = require("./SyncError.js");
+var SyncPrincipal = __toESM(require("./SyncPrincipal.js"), 1);
+var import_SyncRpcs = require("./SyncRpcs.js");
+var WorkspaceShare = __toESM(require("./WorkspaceShare.js"), 1);
+const capabilityHeader = "flows-sync-workspace";
+const denied = shareSigner.unauthorized;
+const encodeCapability = (capability) => {
+  const encoded = Schema.encodeUnknownResult(WorkspaceShare.WorkspaceCapability)(capability);
+  return Result.isFailure(encoded) ? Effect.fail(
+    new import_SyncError.SyncError({
+      code: "invalid_request",
+      message: "The workspace capability does not encode",
+      // The rendering, never the parse failure itself: a schema issue
+      // carries the value it rejected, and the value here is a credential.
+      cause: (0, import_CauseText.causeText)(encoded.failure)
+    })
+  ) : Effect.succeed(Encoding.encodeBase64Url(JSON.stringify(encoded.success)));
+};
+const decodeCapability = (value) => {
+  const text = Encoding.decodeBase64UrlString(value);
+  if (Result.isFailure(text)) {
+    return Effect.fail(denied("The workspace capability header is not a capability"));
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text.success);
+  } catch {
+    return Effect.fail(denied("The workspace capability header is not a capability"));
+  }
+  const decoded = Schema.decodeUnknownResult(WorkspaceShare.WorkspaceCapability)(parsed);
+  return Result.isFailure(decoded) ? Effect.fail(denied("The workspace capability header is not a capability")) : Effect.succeed(decoded.success);
+};
+const layer = Layer.effect(
+  import_SyncRpcs.SyncAuth,
+  Effect.gen(function* () {
+    const share = yield* WorkspaceShare.WorkspaceShare;
+    const middleware = (effect, options) => {
+      const header = Headers.get(options.headers, capabilityHeader);
+      if (header._tag === "None") {
+        return Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.anonymous);
+      }
+      return decodeCapability(header.value).pipe(
+        Effect.flatMap((capability) => share.verify(capability, { access: "read" })),
+        Effect.flatMap(
+          (claims) => Effect.provideService(
+            effect,
+            SyncPrincipal.SyncPrincipal,
+            // The signed expiry travels WITH the identity. A handler that
+            // opens a stream authorizes once; reducing the verified claims to
+            // a capability id here left the stream with nothing to expire on.
+            SyncPrincipal.workspace(claims.capabilityId, claims.expiresAtMs)
+          )
+        )
+      );
+    };
+    return middleware;
+  })
+);
+const layerClient = (capability) => RpcMiddleware.layerClient(
+  import_SyncRpcs.SyncAuth,
+  Effect.map(encodeCapability(capability), (header) => ({ next, request }) => next({ ...request, headers: Headers.set(request.headers, capabilityHeader, header) }))
+);
+//# sourceMappingURL=SyncAuth.js.map

package/dist/cjs/SyncAuth.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/SyncAuth.ts"],
+  "sourcesContent": ["/**\n * The sync read path's connection authentication: implementations of the\n * `SyncRpcs.SyncAuth` RPC middleware.\n *\n * A connection presents a {@link WorkspaceShare.WorkspaceCapability} in the\n * {@link capabilityHeader} request header. {@link layer} verifies it against\n * the workspace's {@link WorkspaceShare.WorkspaceShare} authority and runs\n * the handler as the workspace principal. A request with no header runs as\n * the anonymous principal \u2014 branch share capabilities carried in request\n * payloads still authorize branch reads \u2014 and the server refuses anonymous\n * access to every non-branch run. A request whose header is present but\n * malformed, forged, expired, or signed by an unknown key is refused\n * outright: presence of a credential is a claim, and a false claim is never\n * downgraded to anonymity.\n *\n * There is deliberately no trusted pass-through implementation here: the only\n * sanctioned bypass is an in-process caller providing `SyncPrincipal` itself,\n * never a transport.\n *\n * @since 0.1.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Encoding from \"effect/Encoding\"\nimport * as Layer from \"effect/Layer\"\nimport * as Result from \"effect/Result\"\nimport * as Schema from \"effect/Schema\"\nimport * as Headers from \"effect/unstable/http/Headers\"\nimport * as RpcMiddleware from \"effect/unstable/rpc/RpcMiddleware\"\nimport { causeText } from \"./internal/CauseText.ts\"\nimport * as shareSigner from \"./internal/ShareSigner.ts\"\nimport { SyncError } from \"./SyncError.ts\"\nimport * as SyncPrincipal from \"./SyncPrincipal.ts\"\nimport { SyncAuth } from \"./SyncRpcs.ts\"\nimport * as WorkspaceShare from \"./WorkspaceShare.ts\"\n\n/**\n * The request header a connection presents its workspace capability in.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const capabilityHeader = \"flows-sync-workspace\"\n\nconst denied = shareSigner.unauthorized\n\n/**\n * Renders a workspace capability as its header value: unpadded base64url of\n * the schema-encoded capability JSON.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const encodeCapability = (\n  capability: WorkspaceShare.WorkspaceCapability\n): Effect.Effect<string, SyncError> => {\n  const encoded = Schema.encodeUnknownResult(WorkspaceShare.WorkspaceCapability)(capability)\n  return Result.isFailure(encoded)\n    ? Effect.fail(\n      new SyncError({\n        code: \"invalid_request\",\n        message: \"The workspace capability does not encode\",\n        // The rendering, never the parse failure itself: a schema issue\n        // carries the value it rejected, and the value here is a credential.\n        cause: causeText(encoded.failure)\n      })\n    )\n    : Effect.succeed(Encoding.encodeBase64Url(JSON.stringify(encoded.success)))\n}\n\n/**\n * Decodes a capability header value. Every malformation folds to the same\n * `unauthorized` refusal so the header is not a parsing oracle.\n *\n * @category encoding\n * @since 0.1.0\n */\nexport const decodeCapability = (value: string): Effect.Effect<WorkspaceShare.WorkspaceCapability, SyncError> => {\n  const text = Encoding.decodeBase64UrlString(value)\n  if (Result.isFailure(text)) {\n    return Effect.fail(denied(\"The workspace capability header is not a capability\"))\n  }\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(text.success)\n  } catch {\n    return Effect.fail(denied(\"The workspace capability header is not a capability\"))\n  }\n  const decoded = Schema.decodeUnknownResult(WorkspaceShare.WorkspaceCapability)(parsed)\n  return Result.isFailure(decoded)\n    ? Effect.fail(denied(\"The workspace capability header is not a capability\"))\n    : Effect.succeed(decoded.success)\n}\n\n/**\n * Provides the workspace-capability authentication middleware: no header\n * runs the handler as anonymous, a verified header runs it as the workspace\n * principal, and anything else refuses the request. Verification faults\n * (Web Crypto failing) propagate as their own error rather than as a\n * refusal.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<SyncAuth, never, WorkspaceShare.WorkspaceShare> = Layer.effect(\n  SyncAuth,\n  Effect.gen(function*() {\n    const share = yield* WorkspaceShare.WorkspaceShare\n    const middleware: RpcMiddleware.RpcMiddleware<never, SyncError, never> = (effect, options) => {\n      const header = Headers.get(options.headers, capabilityHeader)\n      if (header._tag === \"None\") {\n        return Effect.provideService(effect, SyncPrincipal.SyncPrincipal, SyncPrincipal.anonymous)\n      }\n      return decodeCapability(header.value).pipe(\n        Effect.flatMap((capability) => share.verify(capability, { access: \"read\" })),\n        Effect.flatMap((claims) =>\n          Effect.provideService(\n            effect,\n            SyncPrincipal.SyncPrincipal,\n            // The signed expiry travels WITH the identity. A handler that\n            // opens a stream authorizes once; reducing the verified claims to\n            // a capability id here left the stream with nothing to expire on.\n            SyncPrincipal.workspace(claims.capabilityId, claims.expiresAtMs)\n          )\n        )\n      )\n    }\n    return middleware\n  })\n)\n\n/**\n * Stamps every outgoing request from a generated RPC client with the given\n * workspace capability.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerClient = (\n  capability: WorkspaceShare.WorkspaceCapability\n): Layer.Layer<RpcMiddleware.ForClient<SyncAuth>, SyncError> =>\n  RpcMiddleware.layerClient(\n    SyncAuth,\n    Effect.map(encodeCapability(capability), (header) => ({ next, request }) =>\n      next({ ...request, headers: Headers.set(request.headers, capabilityHeader, header) }))\n  )\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBA,aAAwB;AACxB,eAA0B;AAC1B,YAAuB;AACvB,aAAwB;AACxB,aAAwB;AACxB,cAAyB;AACzB,oBAA+B;AAC/B,uBAA0B;AAC1B,kBAA6B;AAC7B,uBAA0B;AAC1B,oBAA+B;AAC/B,sBAAyB;AACzB,qBAAgC;AAQzB,MAAM,mBAAmB;AAEhC,MAAM,SAAS,YAAY;AASpB,MAAM,mBAAmB,CAC9B,eACqC;AACrC,QAAM,UAAU,OAAO,oBAAoB,eAAe,mBAAmB,EAAE,UAAU;AACzF,SAAO,OAAO,UAAU,OAAO,IAC3B,OAAO;AAAA,IACP,IAAI,2BAAU;AAAA,MACZ,MAAM;AAAA,MACN,SAAS;AAAA;AAAA;AAAA,MAGT,WAAO,4BAAU,QAAQ,OAAO;AAAA,IAClC,CAAC;AAAA,EACH,IACE,OAAO,QAAQ,SAAS,gBAAgB,KAAK,UAAU,QAAQ,OAAO,CAAC,CAAC;AAC9E;AASO,MAAM,mBAAmB,CAAC,UAAgF;AAC/G,QAAM,OAAO,SAAS,sBAAsB,KAAK;AACjD,MAAI,OAAO,UAAU,IAAI,GAAG;AAC1B,WAAO,OAAO,KAAK,OAAO,qDAAqD,CAAC;AAAA,EAClF;AACA,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM,KAAK,OAAO;AAAA,EAClC,QAAQ;AACN,WAAO,OAAO,KAAK,OAAO,qDAAqD,CAAC;AAAA,EAClF;AACA,QAAM,UAAU,OAAO,oBAAoB,eAAe,mBAAmB,EAAE,MAAM;AACrF,SAAO,OAAO,UAAU,OAAO,IAC3B,OAAO,KAAK,OAAO,qDAAqD,CAAC,IACzE,OAAO,QAAQ,QAAQ,OAAO;AACpC;AAYO,MAAM,QAAqE,MAAM;AAAA,EACtF;AAAA,EACA,OAAO,IAAI,aAAY;AACrB,UAAM,QAAQ,OAAO,eAAe;AACpC,UAAM,aAAmE,CAAC,QAAQ,YAAY;AAC5F,YAAM,SAAS,QAAQ,IAAI,QAAQ,SAAS,gBAAgB;AAC5D,UAAI,OAAO,SAAS,QAAQ;AAC1B,eAAO,OAAO,eAAe,QAAQ,cAAc,eAAe,cAAc,SAAS;AAAA,MAC3F;AACA,aAAO,iBAAiB,OAAO,KAAK,EAAE;AAAA,QACpC,OAAO,QAAQ,CAAC,eAAe,MAAM,OAAO,YAAY,EAAE,QAAQ,OAAO,CAAC,CAAC;AAAA,QAC3E,OAAO;AAAA,UAAQ,CAAC,WACd,OAAO;AAAA,YACL;AAAA,YACA,cAAc;AAAA;AAAA;AAAA;AAAA,YAId,cAAc,UAAU,OAAO,cAAc,OAAO,WAAW;AAAA,UACjE;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;AASO,MAAM,cAAc,CACzB,eAEA,cAAc;AAAA,EACZ;AAAA,EACA,OAAO,IAAI,iBAAiB,UAAU,GAAG,CAAC,WAAW,CAAC,EAAE,MAAM,QAAQ,MACpE,KAAK,EAAE,GAAG,SAAS,SAAS,QAAQ,IAAI,QAAQ,SAAS,kBAAkB,MAAM,EAAE,CAAC,CAAC;AACzF;",
+  "names": []
+}

package/dist/cjs/SyncClient.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Browser-safe client for replaying and following journal entries.
+ *
+ * @since 0.1.0
+ */
+import type * as JournalEvent from "@smthrs/journal/JournalEvent";
+import * as Context from "effect/Context";
+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 RpcClientError from "effect/unstable/rpc/RpcClientError";
+import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+import type { ShareCapability } from "./BranchProtocol.ts";
+import { SyncError, SyncGapError } from "./SyncError.ts";
+import { type Progress, type Resync, RunCursor, type Scope, type Snapshot, type SnapshotRequest, type WorkspaceCursor } from "./SyncProtocol.ts";
+import { SyncRpcs } from "./SyncRpcs.ts";
+/**
+ * Frames one subscription round may carry before the follow replenishes it.
+ *
+ * A subscription's `credit` is a hard frame limit the server enforces with
+ * `Stream.take`, so the number the client sends is the size of its window, not
+ * a hint. At `credit: 1` the window closed after every single entry and the
+ * follow resubscribed: following a run that emits a hundred entries cost a
+ * hundred subscribe round trips, each of them a fresh cursor snapshot and a
+ * fresh server-side fan-out. Replenishing 256 frames at a time makes the
+ * round-trip cost proportional to the window rather than to the traffic, and
+ * keeps it bounded — an unbounded window would hand the server one
+ * never-closing subscription per follower.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultCredit = 256;
+/**
+ * Entries one catch-up page asks for.
+ *
+ * Bootstrap is the replay half of replay-then-follow, so the page size is the
+ * memory one catch-up costs and the granularity at which its cursor advances.
+ * It matches {@link defaultCredit} and stays under
+ * `SyncProtocol.maxReadLimit`, which is the ceiling the server enforces.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultBootstrapLimit = 256;
+/**
+ * The policy one sync client runs every operation under.
+ *
+ * Both fields are validated by {@link makeWith} and {@link layerWith}, so a
+ * value that is not a positive safe integer fails the constructor rather than
+ * disabling the bound it configures.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    /**
+     * Largest summed encoded-entry size one frame or bootstrap page may carry,
+     * in bytes. Defaults to {@link defaultMaxFrameBytes}.
+     */
+    readonly maxFrameBytes?: number | undefined;
+    /**
+     * Entries one catch-up page asks for. Defaults to
+     * {@link defaultBootstrapLimit}, and may not exceed
+     * `SyncProtocol.maxReadLimit`.
+     */
+    readonly bootstrapLimit?: number | undefined;
+}
+/**
+ * Input accepted by a sync subscription.
+ *
+ * `capability` authorizes branch reads: following a shared branch's run
+ * requires a capability that verifies for that branch on the server.
+ *
+ * `EApply` and `EResync` are the consumer's own failure types for `apply` and
+ * `onResync`. The subscription fails with them unchanged, so an application
+ * failure is never dressed as a transport or protocol {@link SyncError}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SubscribeOptions<EApply = never, EResync = never> {
+    readonly scope: Scope;
+    /**
+     * Where this subscription starts, per run. The effective position is the
+     * LATER of this and the client's matching progress map (applied when an
+     * apply callback is present, delivered otherwise), so a caller
+     * ahead of the shared view keeps its place and a caller behind it is
+     * fast-forwarded. Rebuild from an earlier position with a fresh client.
+     */
+    readonly cursors: WorkspaceCursor;
+    readonly capability?: ShareCapability;
+    /**
+     * Frames one subscription round may carry before the follow replenishes the
+     * window. Defaults to {@link defaultCredit}, and must be a positive integer
+     * no greater than `SyncProtocol.maxSubscribeCredit`.
+     */
+    readonly credit?: number | undefined;
+    /**
+     * Applies one entry, and DEFINES what this subscription's cursor means.
+     *
+     * Without it the cursor advances as each entry is handed to the consumer,
+     * so a consumer whose own application then fails has a cursor naming an
+     * entry it never materialized. With it the cursor advances only after this
+     * effect succeeds, and records it in `Progress.applied`. A failure here
+     * fails the subscription with the entry unacknowledged, so the
+     * next applying subscription delivers it again; the effect must
+     * therefore be idempotent, because a redelivery is exactly what a retry is.
+     */
+    readonly apply?: ((entry: JournalEvent.Entry) => Effect.Effect<void, EApply>) | undefined;
+    /**
+     * Restores state when the server refuses a cursor below a compaction floor.
+     * Return the exact run and sequence actually restored, after applying it.
+     *
+     * The entries under the floor are deleted. Fetch an explicitly public
+     * projection through `snapshot` or an authorized local source; a
+     * projection has a real hole to fill. The returned sequence must cover the
+     * requested floor; a newer snapshot resumes at its own sequence, not the
+     * older floor. Missing handlers, failures, interruption, and invalid receipts
+     * leave the cursor unmoved. There is no implicit skip of deleted history.
+     *
+     * Durable consumers must commit their restored state and durable cursor in
+     * their own transaction and seed a fresh client from that cursor on restart.
+     * This client's cursor is in memory, not an atomic cross-store transaction.
+     * Recovery must be idempotent, including when a newer compaction requires
+     * another restoration before the suffix can be read.
+     */
+    readonly onResync?: ((resync: Resync) => Effect.Effect<RunCursor, EResync>) | undefined;
+}
+/**
+ * Replicated journal subscription operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /** Fetches a public snapshot without applying state or advancing a cursor. */
+    readonly snapshot: (request: SnapshotRequest) => Effect.Effect<Snapshot, SyncError>;
+    /** Replays then follows `options.scope`, also failing with the callbacks' own errors. */
+    readonly subscribe: <EApply = never, EResync = never>(options: SubscribeOptions<EApply, EResync>) => Stream.Stream<JournalEvent.Entry, SyncError | SyncGapError | EApply | EResync>;
+    /**
+     * Delivery and application positions. `delivered` is a transport bookmark
+     * only; `applied` is what the `apply` and `onResync` callbacks acknowledged.
+     */
+    readonly progress: Effect.Effect<Progress>;
+}
+declare const SyncClient_base: Context.ServiceClass<SyncClient, "@smthrs/sync/SyncClient", Service>;
+/**
+ * The browser-safe journal replication client.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare class SyncClient extends SyncClient_base {
+}
+/**
+ * The client tag's former name, kept for one release.
+ *
+ * @deprecated Use {@link SyncClient}.
+ * @category services
+ * @since 0.1.0
+ */
+export declare const Sync: typeof SyncClient;
+/**
+ * The client tag's former name, kept for one release.
+ *
+ * @deprecated Use {@link SyncClient}.
+ * @category services
+ * @since 0.1.0
+ */
+export type Sync = SyncClient;
+/**
+ * Constructs a closed sync stub, optionally overriding individual operations.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a closed sync stub.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<SyncClient>;
+type Client = RpcClient.RpcClient<RpcGroup.Rpcs<typeof SyncRpcs>, RpcClientError.RpcClientError>;
+/**
+ * Projects a Sync RPC client into the local replication service.
+ *
+ * Delivered and applied cursors are separate per-service `Ref` maps: concurrent
+ * subscriptions for one materialization share them, and each commit advances
+ * its matching map monotonically. A
+ * cursor advances in the same stream pull that admits each entry to the
+ * consumer, or — when the caller supplies `SubscribeOptions.apply` — only
+ * after that callback has applied the entry. Interrupted partial pages
+ * therefore retain the last admitted entry rather than incorrectly
+ * acknowledging the server's whole page.
+ *
+ * A frame or bootstrap page whose encoded entries exceed `maxFrameBytes` is
+ * refused with `frame_too_large`. Out-of-scope entries, repeated or reordered
+ * sequences, and missing response generations fail with `protocol_violation`
+ * before delivery. Each entry-bearing run in a Read page must have exactly one
+ * explicit generation cursor, and every entry must be above the requested
+ * cursor. Live frames instead drop already-covered entries and deliver only
+ * the suffix above the cursor. An incomplete bootstrap page with no entries
+ * or a completed subscription window with no frames fails with
+ * `protocol_violation` instead of reopening immediately.
+ *
+ * A live follow that loses its transport reconnects under
+ * {@link reconnectPolicy}, resuming from the acknowledged cursors; the failure
+ * cause is logged before the retry folds it. The follow spends a credit window
+ * of {@link defaultCredit} frames per subscription round and replenishes it by
+ * resubscribing from the cursors it has acknowledged. Already-covered entries
+ * are not delivered again; the round-trip cost scales with credit windows.
+ *
+ * A `compacted` refusal fails closed unless `SubscribeOptions.onResync`
+ * restores the missing prefix and returns its exact cursor. Snapshot fetching
+ * never applies state or advances cursors. Only a validated receipt for the requested run at or
+ * above its compaction floor advances the cursor before reading the suffix.
+ *
+ * A subscription's effective cursor per run is the LATER of the caller's and
+ * the matching progress map: a caller that restored its own progress is never
+ * regressed, and a caller asking for history this client already acknowledged
+ * is fast-forwarded. Rebuild a projection from an earlier position with a
+ * fresh client, whose acknowledged map is empty.
+ *
+ * This constructor carries the default policy, which is valid by
+ * construction and so cannot fail. {@link makeWith} takes an explicit
+ * {@link Options} and validates it.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: ({ client }: {
+    readonly client: Client;
+}) => Effect.Effect<Service>;
+/**
+ * Constructs the sync client under an explicit policy.
+ *
+ * Every option is validated here, once, so a client either exists under a
+ * policy it can serve or never exists at all. Validating on each `subscribe`
+ * and each `snapshot` instead accepted a `maxFrameBytes` of `NaN` at
+ * construction and then refused every operation under it, which reported a
+ * composition's mistake as a run-time failure of the follow. This mirrors
+ * `SyncServer.makeLiveWith` and `BranchCommands.makeLiveWith`.
+ *
+ * `SubscribeOptions.credit` is a REQUEST count rather than a client policy, so
+ * it is still checked where the request is built.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeWith: ({ bootstrapLimit, client, maxFrameBytes }: Options & {
+    readonly client: Client;
+}) => Effect.Effect<Service, SyncError>;
+/**
+ * Provides the sync client from the active RPC protocol.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<SyncClient, never, RpcClient.Protocol>;
+/**
+ * Provides the sync client under an explicit policy. Fails with
+ * `invalid_request` when an option is not a positive safe integer, so a bad
+ * policy fails the composition rather than every operation under it.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<SyncClient, SyncError, RpcClient.Protocol>;
+export {};
+//# sourceMappingURL=SyncClient.d.ts.map

package/dist/cjs/SyncClient.d.ts.map

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